Trust Model

Trust Model¶

ocid is designed with explicit trust boundaries to ensure security in a peer-to-peer environment. This document describes what is trusted, what isn’t, and how ocid verifies data at each step.

🔐 Trust Boundaries¶

The following table summarizes the trust model for each component in ocid:

🔑 Publisher Trust¶

The publisher is the root of trust in ocid. A publisher is identified by their Ed25519 public key, which serves multiple purposes:

flowchart TD
    subgraph identity["Identity"]
        sk["secret.key<br/>(Ed25519)"] --> pk["public key"]
    end

    pk -->|Registry Paths| hex["Hex (64 chars)<br/>EndpointId"]
    pk -->|CLI Display| did["did:key:z6Mk…"]
    pk -->|Signing| sig["Signs releases"]
    pk -->|QUIC Auth| quic["Authenticates QUIC connections"]
    pk -->|Gossip| topic["Derives gossip topic"]

    %% Styling
    classDef identity fill:#d5e8d4,stroke:#333
    class sk,pk identity

What a Publisher Can Do¶

Publisher Verification¶

When a node receives a release from a publisher: 1. It verifies the signature using the publisher’s public key. 2. It checks that the publisher matches the expected key (from DNS, alias, or direct hex). 3. It ensures the timestamp is newer than any existing release for (publisher, name, tag).

🌍 DNS Publisher Names¶

ocid supports DNS publisher names, which allow a domain (e.g., images.example.com) to stand in for a publisher’s hex ID. This is useful for human-readable names but requires careful trust management.

DNS Record Format¶

A DNS publisher name is defined by a signed TXT record at _ocid.<zone>:

1_ocid.images.example.com. 300 IN TXT "v=ocid1 k=<64-hex> ts=<unix> sig=<128-hex>"

Signature Payload¶

The signature covers the canonical payload:

1ocid1 <zone> <k> <ts>

Example:

1ocid1 images.example.com z6MkqRYqQ... 1712345678

Trust Model for DNS¶

DNS is not trusted by default. ocid uses the following mechanisms to ensure security:

1. Signature Verification:
2. The signature is always verified before accepting the DNS record.

3. The zone is part of the signed bytes, so a record cannot be replayed across zones.

4. Freshness:

5. Records older than dns_max_age_secs (default: 30 days) are rejected.

6. TOFU Pinning:

7. The first verified resolution pins the key in $OCID_HOME/dns-pins.json.
8. A later record for the same zone with a different key is rejected as a possible hijack.

9. Rotation is explicit: Use ocictl dns-unpin <zone> to unpin, then the next resolve re-pins.

10. Cache:

11. Positive and negative lookups are cached briefly (TTL-capped).
12. Errors are never cached, so every pull re-checks a bad record.

DNS Resolution Flow¶

flowchart TD
    in["Resolve images.example.com/app:1.0"] --> q1{"Has verified<br/>_ocid TXT record?"}
    q1 -- yes --> verify["Verify signature"]
    verify --> q2{"Signature valid?"}
    q2 -- yes --> pin["Pin key in dns-pins.json"]
    q2 -- no --> reject["Reject: Invalid signature"]
    pin --> q3{"Fresh? (< 30 days)"}
    q3 -- yes --> use["Use publisher key"]
    q3 -- no --> reject2["Reject: Stale record"]
    q1 -- no --> fallback["Fallback to alias/self rules"]

DNS Commands¶

👥 Provider (Peer) Trust¶

Providers (any peer in the network) are not trusted by default. ocid uses the following mechanisms to ensure data integrity:

Blob Verification¶

1. BLAKE3 Incremental Verification:
2. iroh-blobs verifies every chunk as it streams using BLAKE3.

3. This ensures that the data received matches the expected hash before the entire blob is downloaded.

4. SHA256 Final Verification:

5. After download, ocid re-checks the SHA256 digest against the signed release.

6. This ensures compatibility with OCI tooling (which expects SHA256).

7. Size Verification:

8. The size of each blob is verified against the BlobRef in the release.

Release Verification¶

1. Signature Verification:
2. Every release is signed by the publisher.

3. ocid verifies the signature using the publisher’s public key before accepting the release.

4. Timestamp Verification:

5. ocid checks that the timestamp is newer than any existing release for (publisher, name, tag).

6. This prevents replay attacks.

7. Blob Completeness:

8. ocid checks that all blobs referenced by the release are present and verified.

Provider Flow¶

sequenceDiagram
    participant C as Node C (Consumer)
    participant P as Node P (Provider)

    C->>P: sync GetRelease(publisher=A, name=app, tag=1.0)
    P-->>C: Release (signed JSON)
    C->>C: Verify signature (Ed25519)
    C->>P: iroh-blobs download(BLAKE3:def456)
    P-->>C: Stream blob (BAO format)
    C->>C: Verify BLAKE3 incrementally
    C->>C: Verify SHA256 + size
    C->>C: Accept blob

🏠 Local Registry Trust¶

The local OCI registry (on 127.0.0.1:5050) has no authentication. This is intentional and matches the trust model of the local podman socket:

Security Implications¶

• Local access = Full control: Anyone who can reach the local registry can push as the local node.
• Same as podman socket: This matches the trust model of the local podman socket (/run/podman/podman.sock).
• Mitigation: Bind to 127.0.0.1 (loopback) to prevent external access.

TLS Support¶

ocid can serve the registry over HTTPS with a self-signed CA:

1# Enable TLS (auto-generates CA)
2ocid --tls

• The CA is stored in $OCID_HOME/tls/.
• The certificate is self-signed and provides transport encryption (not authentication).
• Clients must pin the CA to verify the server.

🗑️ Deletion Trust¶

Deletion in ocid is local only. There are no signed tombstones, and publishers cannot recall releases from peers:

Deletion Flow¶

flowchart TD
    del["DELETE /v2/app/manifests/1.0"] --> rr["Remove release record<br/>(local only)"]
    win["enforce_window"] --> rr
    gc["GC (periodic)"] --> ret["Retained = own ∪ pinned ∪ in-window ∪ cache"]
    ret --> rr
    rr --> sweep["Sweep: Unpin blob:<sha256>"]
    sweep --> ib["iroh-blobs GC deletes unpinned data"]

    %% Annotations
    click del "https://ocid.dev/reference/api#delete-manifest" _blank

Implications¶

1. No Propagated Deletion:
2. Deleting a release on Node A does not remove it from Node B.

3. Peers that already replicated the release keep it until their own policy drops it.

4. Stop Announcing:

5. Deleting a release stops it from being announced on the publisher’s gossip topic.

6. Peers will not receive new announcements for the deleted release.

7. Local Cleanup:

8. DELETE on a blob is refused (405 Method Not Allowed).
9. Only GC can remove blobs (when they are unpinned).

🔒 Security Summary¶

🛡️ Best Practices¶

For Publishers¶

1. Keep Your Key Safe:
2. The secret key (identity.key) is the root of trust for your namespace.

3. Back it up securely and never share it.

4. Use DNS Publisher Names Carefully:

5. DNS records are untrusted until verified.

6. Rotate DNS records explicitly (ocictl dns-unpin).

7. Pin Critical Releases:

8. Use ocictl pin <ref> to ensure critical releases are never pruned.

For Consumers¶

1. Verify DNS Records:

2. Use ocictl resolve <zone> to check the pinned key for a DNS publisher name.

3. Use Policy Wisely:

4. follow publishers you trust.
5. seed images you care about.

6. pin critical releases.

7. Monitor Peers:

8. Use ocictl peers to see connected peers.
9. Use ocitop to monitor real-time activity.

For Operators¶

1. Bind to Loopback:

2. Ensure the registry is only accessible locally (127.0.0.1:5050).

3. Enable TLS:

4. Use --tls to enable HTTPS with a self-signed CA.

5. Distribute the CA to clients for pinning.

6. Monitor Metrics:

7. Use Prometheus + Grafana to monitor /metrics.
8. Set up alerts for unusual activity.