OSAP

Appearance

OSAP Identity and Key Discovery ​

Status: See Status of This Document.

This document normatively defines issuer identity, issuer metadata, key format, key rotation, and key compromise handling in OSAP v0.1.

1. Identity Model ​

OSAP v0.1 binds issuer identity to web-domain control by using did:web identifiers and HTTPS. This binding identifies the party controlling the domain and its TLS endpoint; it does not certify any other property of the issuer. The issuer's name field carries no identity weight.

General DID resolution and other DID methods are future extension areas. No global registry of issuers exists or is planned.

2. did:web Identifiers ​

  • An issuer identifier MUST be a did:web DID, e.g. did:web:publisher.example.
  • v0.1 uses only the bare-domain form. Path-based did:web identifiers (e.g. did:web:example.com:users:alice) are a future extension area; verifiers MAY reject them.
  • The domain in the identifier is the domain from which issuer metadata is fetched.

3. Issuer Metadata ​

An issuer MUST publish an issuer metadata document at:

text
https://<domain>/.well-known/osap.json
  • The document MUST validate against osap-issuer.schema.json; fields are defined in data-model.md § 4.
  • The document MUST be served over HTTPS with a valid certificate. Verifiers MUST NOT accept issuer metadata served over plain HTTP.
  • The id in the metadata MUST match the did:web identifier implied by the serving domain. A mismatch MUST cause issuer key discovery to fail.
  • The document SHOULD be served with Content-Type: application/json and cache-control headers appropriate to the issuer's rotation practices.

Example: ../examples/well-known-osap.json.

Note (non-normative): Issuer metadata is not signed in v0.1; its integrity depends on HTTPS and domain control. Verifiers SHOULD cache fetched metadata for subsequent offline operation (see privacy.md).

4. Key Format ​

Each entry in keys is a Multikey:

  • type MUST be "Multikey".
  • publicKeyMultibase MUST be the multibase base58btc encoding (prefix character z) of the two-byte ed25519-pub multicodec prefix 0xed 0x01 followed by the 32-byte raw Ed25519 public key.
  • id MUST be a fragment of the issuer DID, e.g. did:web:publisher.example#key-2026, and is the value referenced by issuer.key_id and proof.verificationMethod in envelopes.

Only Ed25519 keys are defined in v0.1. Other key types (including post-quantum signatures) are future extension areas; verifiers MUST ignore key entries whose type is not Multikey or whose decoded multicodec prefix is not 0xed 0x01, and MUST treat a referenced-but-unusable key as "key not found" in the verification algorithm (verification.md).

5. Key Validity and Rotation ​

Keys carry OPTIONAL valid_from and valid_until timestamps.

  • A key is valid at time T if valid_from is absent or ≤ T, and valid_until is absent or ≥ T.
  • When verifying an attestation, the verifier MUST evaluate key validity at the attestation's issued_at time, not at verification time. A signature made while a key was valid remains historically verifiable after the key expires (see security-considerations.md).
  • To rotate keys, an issuer SHOULD: add the new key with an appropriate valid_from; begin signing with it; set valid_until on the old key; and keep the old key entry published indefinitely so historical attestations remain verifiable.
  • Issuers MUST NOT remove old key entries from metadata merely because they expired. Removal makes historical attestations unverifiable and SHOULD be reserved for compromise scenarios where that is the intent.

6. Key Compromise Handling ​

If a signing key is compromised, the issuer SHOULD:

  1. Add the key to revoked_keys in its revocation list (data-model.md § 6) with a revoked_at timestamp reflecting the earliest suspected compromise time and a reason.
  2. Set or shorten the key's valid_until in issuer metadata to the compromise time.
  3. Rotate to a new key per § 5.
  4. Individually revoke any attestations known to be forged, via RevocationAttestation and revocation-list entries.

Verifiers MUST treat a signature made by a revoked key as follows: if issued_at is at or after the key's revoked_at, the signature MUST be reported as made with a revoked key (error-level label); if issued_at is before revoked_at, the verifier MUST report the historical validity but SHOULD warn that the key was later revoked, since issued_at is an issuer assertion and a key holder can backdate it. See threat-model.md.

Note (non-normative): key compromise is one of the cases where temporal trust in bundles (temporal-trust.md) complements key-level revocation — a bundle maintainer can mark the compromise window high_caution independently of the issuer's own response.

7. Domain Loss and Ownership Change ​

If a domain lapses or is transferred, its new controller can publish new keys and issue attestations under the same did:web identifier. A trust bundle can end a trusted period at the ownership change while retaining the prior period. See temporal-trust.md for evaluation and threat-model.md for attack analysis.