Skip to main content

Cryptographic Integrity

TRF safeguards authenticity, integrity, and non-repudiation with layered cryptography. Hashes detect tampering, signatures prove authorship, timestamps anchor evidence in time, and certificate checks tie everything to trusted authorities.

Hashing and Package Integrity​

Artifact hashes​

Every artifact stores a SHA-256 hash calculated from canonical JSON (hash field excluded):

{
  "id": "req:FUNC-001",
  "type": "requirement",
  "title": "System response time",
  "content": "The system shall respond to user input within 100ms",
  "created": "2024-01-15T10:30:00Z",
  "hash": "sha256:a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}
import hashlib
import json

def calculate_artifact_hash(artifact):
    content = {k: v for k, v in artifact.items() if k != 'hash'}
    canonical = json.dumps(content, sort_keys=True, separators=(',', ':'))
    return hashlib.sha256(canonical.encode('utf-8')).hexdigest()

Package metadata​

manifest.json records aggregate hashes and Merkle roots so clients can verify entire archives:

{
  "manifest": {
    "content_hash": "sha256:package_level_hash",
    "artifact_count": 1247,
    "link_count": 2834,
    "verification": {
      "algorithm": "merkle_tree",
      "root_hash": "sha256:merkle_root_hash"
    }
  }
}

Digital Signatures​

Artifact signatures​

Teams may sign critical artifacts with organizational certificates:

{
  "signatures": {
    "artifact_signatures": [
      {
        "artifact_id": "req:FUNC-001",
        "signer": "requirements-team@example.com",
        "algorithm": "RSA-SHA256",
        "signature": "base64-encoded-signature",
        "certificate": "X.509-certificate",
        "timestamp": "2024-01-15T10:30:00Z",
        "hash_verified": "sha256:a1b2c3d4e5f6..."
      }
    ]
  }
}

Package signatures​

Archive-wide signatures cover all artifacts and attachments:

{
  "package_signature": {
    "signer": "build-system@example.com",
    "algorithm": "RSA-SHA256",
    "signature": "base64-encoded-package-signature",
    "certificate": "X.509-certificate-chain",
    "timestamp": "2024-01-20T15:30:00Z",
    "scope": "complete_package",
    "signed_hash": "sha256:package_content_hash"
  }
}

Multi-party approvals​

Supply chains can attach multiple signatures to the same package:

{
  "multi_party_signatures": [
    {
      "party": "supplier-a@example.com",
      "role": "component_developer",
      "signature": "base64-signature-a",
      "certificate": "supplier-a-cert",
      "timestamp": "2024-01-18T14:00:00Z"
    },
    {
      "party": "integrator@example.com",
      "role": "system_integrator",
      "signature": "base64-signature-b",
      "certificate": "integrator-cert",
      "timestamp": "2024-01-20T16:00:00Z"
    },
    {
      "party": "auditor@certification-body.com",
      "role": "independent_auditor",
      "signature": "base64-signature-c",
      "certificate": "auditor-cert",
      "timestamp": "2024-01-22T09:30:00Z"
    }
  ]
}

Timestamping and Chronology​

Trusted timestamps​

RFC 3161 tokens bind evidence to trusted time sources:

{
  "timestamp_token": {
    "tsa_url": "http://timestamp.example.com/tsa",
    "token": "base64-encoded-timestamp-token",
    "hash_algorithm": "SHA-256",
    "timestamp": "2024-01-20T15:30:00.123Z",
    "accuracy": "±1 second",
    "tsa_certificate": "X.509-tsa-certificate"
  }
}

Chronology checks​

Clients validate creation/modified order and dependency timing:

def validate_chronology(artifacts):
    for artifact in artifacts:
        created = artifact['created']
        modified = artifact.get('modified', created)
        if modified < created:
            raise ChronologyError(f"Artifact {artifact['id']} modified before creation")
        for dep_id in artifact.get('dependencies', []):
            dep_artifact = find_artifact(dep_id)
            if dep_artifact['created'] > created:
                raise ChronologyError(f"Dependency {dep_id} created after dependent {artifact['id']}")

Certificate Management​

Chains and revocation​

TWPacks carry certificate metadata so verifiers can trace PKI trust roots:

{
  "certificate_chain": [
    {
      "level": "end_entity",
      "subject": "CN=build-system@example.com",
      "issuer": "CN=Example CA",
      "serial": "1234567890",
      "not_before": "2024-01-01T00:00:00Z",
      "not_after": "2025-01-01T00:00:00Z",
      "public_key": "RSA-2048-key",
      "certificate": "base64-encoded-cert"
    },
    {
      "level": "intermediate",
      "subject": "CN=Example CA",
      "issuer": "CN=Root CA",
      "certificate": "base64-encoded-intermediate-cert"
    },
    {
      "level": "root",
      "subject": "CN=Root CA",
      "issuer": "CN=Root CA",
      "certificate": "base64-encoded-root-cert"
    }
  ]
}
{
  "revocation_check": {
    "method": "OCSP",
    "ocsp_url": "http://ocsp.example.com",
    "response": "base64-encoded-ocsp-response",
    "status": "good",
    "checked_at": "2024-01-20T15:30:00Z"
  }
}

Verification Workflows​

CLI sequence​

tw validate package.twpack --check-structure
tw validate package.twpack --check-hashes
tw validate package.twpack --check-signatures
tw validate package.twpack --check-certificates
tw validate package.twpack --check-timestamps
tw validate package.twpack --full

CI/CD integration​

name: Verify Evidence Package
on:
  pull_request:
    paths: ['evidence/*.twpack']

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install TRF CLI
        run: curl -sSL https://get.trf.dev | sh
      - name: Verify Package Integrity
        run: |
          for package in evidence/*.twpack; do
            tw validate "$package" --full --strict
          done
      - name: Check Certificate Status
        run: tw certificate-status evidence/*.twpack --check-revocation

Trust Models​

Hierarchical PKI​

Root CA (Industry Standard)
├── Automotive CA
│   ├── OEM Certificate
│   └── Supplier Certificate
├── Medical Device CA
│   ├── Manufacturer Certificate
│   └── Testing Lab Certificate
└── Software CA
    ├── Developer Certificate
    └── CI/CD System Certificate

Web and consensus models​

{
  "trust_relationships": [
    {
      "trustor": "org-a@example.com",
      "trustee": "org-b@example.com",
      "level": "full",
      "established": "2024-01-01T00:00:00Z",
      "attestation": "base64-encoded-attestation"
    },
    {
      "trustor": "org-b@example.com",
      "trustee": "org-c@example.com",
      "level": "limited",
      "scope": ["test_results", "design_documents"],
      "established": "2024-01-15T00:00:00Z"
    }
  ]
}
{
  "consensus_verification": {
    "required_signatures": 2,
    "participants": [
      "developer@example.com",
      "reviewer@example.com",
      "quality-assurance@example.com"
    ],
    "signatures_received": 3,
    "consensus_achieved": true,
    "finalized_at": "2024-01-20T16:00:00Z"
  }
}

Operational Practices​

Key management​

tw keygen --algorithm RSA-4096 --output org-keypair.pem
tw sign package.twpack --key hsm://slot-1 --certificate org-cert.pem
tw verify package.twpack --public-key org-public.pem

Secure storage​

{
  "storage_security": {
    "encryption": "AES-256-GCM",
    "key_derivation": "PBKDF2-SHA256",
    "integrity_check": "HMAC-SHA256",
    "access_control": {
      "read": ["audit-team", "compliance-officer"],
      "write": ["build-system"],
      "admin": ["security-admin"]
    }
  }
}

Audit logging​

{
  "audit_log": [
    {
      "timestamp": "2024-01-20T15:30:00Z",
      "action": "signature_verification",
      "package": "evidence-v1.2.twpack",
      "result": "success",
      "verified_by": "audit-system",
      "signature_count": 3,
      "certificate_status": "valid"
    },
    {
      "timestamp": "2024-01-20T15:35:00Z",
      "action": "hash_verification",
      "artifact_count": 1247,
      "failed_artifacts": [],
      "result": "success"
    }
  ]
}

These controls ensure every TWPack delivers verifiable, tamper-evident evidence from creation through audit.