> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifact Signing and Key Hierarchy

> Key hierarchy, signing algorithms, verification flow, rotation schedule, revocation, and air-gapped signing options for model artifacts.

Every model artifact, merge candidate, and release package in EMEP is signed at creation and verified at every downstream use. This page defines the key hierarchy, signing algorithms, verification flow, rotation policy, and air-gapped alternatives.

## Key Hierarchy

```mermaid theme={null}
flowchart TB
    ROOT["Root Key (offline, HSM)"] --> INT1["Intermediate: Research"]
    ROOT --> INT2["Intermediate: Staging"]
    ROOT --> INT3["Intermediate: Production"]
    ROOT --> INT4["Intermediate: Enterprise (offline)"]
    INT1 --> SIGN1["Signing: Model Downloads"]
    INT1 --> SIGN2["Signing: Datasets"]
    INT2 --> SIGN3["Signing: Merge Candidates"]
    INT2 --> SIGN4["Signing: Eval Results"]
    INT3 --> SIGN5["Signing: Releases"]
    INT4 --> SIGN6["Signing: Enterprise Packages"]
```

The root key is offline in an HSM and never touches a networked host. Intermediates are per-environment and stored in environment-specific HSM partitions. Signing keys are per-artifact-type and rotated automatically.

## Algorithms and Formats

* Baseline signing: ed25519
* Signature format: SSH-style base64-encoded ed25519 signature + key identifier + timestamp
* Optional: Sigstore cosign for public-facing releases
* Hash for signing payload: SHA-256 of canonical artifact manifest

## Signature Verification Flow

```mermaid theme={null}
flowchart LR
    START([Verify Artifact]) --> LOAD[Load Artifact + Manifest]
    LOAD --> FETCH[Fetch Public Key by ID]
    FETCH --> VALID{Key Valid?}
    VALID -->|NO| REVOKED[Reject: Key revoked or expired]
    VALID -->|YES| HASH[Compute SHA-256 of Manifest]
    HASH --> VERIFY[Verify Signature]
    VERIFY --> PASS{Valid?}
    PASS -->|YES| ACCEPT[Accept Artifact]
    PASS -->|NO| REJECT[Reject: Signature mismatch]
```

The key identifier in the signature points to a key record in the registry. A revoked or expired key causes immediate rejection.

## Key Rotation

| Key Type     | Rotation Period         | Overlap | Trigger                          |
| ------------ | ----------------------- | ------- | -------------------------------- |
| Root         | Annual, manual ceremony | 30 days | Calendar + incident              |
| Intermediate | Annual, automated       | 90 days | Calendar + environment promotion |
| Signing      | Quarterly, automated    | 14 days | Calendar + usage threshold       |

During overlap, both old and new keys are valid. After overlap, the old key is marked expired and archived. Revocation is immediate and overrides expiry.

## Key Revocation

Revocation reasons: compromise, personnel change, policy violation, environment decommission. A revoked key is published to the revocation list within 60 seconds. All verifiers check the revocation list before accepting a signature.

## Air-Gapped Signing

Enterprise deployments without network access use an offline HSM and a manual signing ceremony:

1. Export artifact manifest to write-once media
2. Transfer media to air-gapped signing station
3. Sign with offline HSM
4. Transfer signature back on separate media
5. Import signature and verify against manifest
6. Archive media with chain-of-custody log

## Cross-Links

* [Security Requirements](/security/security-requirements)
* [Model Supply Chain](/security/model-supply-chain)
* [Offline Security](/security/offline-security)