Security Practices ◈︎

Overview

AIOSchema uses an Ed25519 keypair to sign manifests. The public key fingerprint - your Creator ID - is your permanent attributed identity across every manifest you create. The private key is what proves you own that identity.

Two modes of identity exist:

Mode	Format	Description
Anonymous	UUID v7 or UUID v4	No identity disclosed. Manifests are tamper-evident but not attributed.
Attributed	ed25519-fp-<32hex>	Creator ID derived from your Ed25519 public key fingerprint. Manifests are cryptographically signed and attributed.

This document covers attributed mode. Anonymous mode requires no keypair and has no associated security practices beyond protecting the manifest itself.

---

Generating a Keypair

Any standard Ed25519 key generation tool produces a conforming keypair. The Creator ID is derived deterministically from the public key: it is not chosen, registered, or assigned by any authority.

Using OpenSSL (any platform):

# Generate Ed25519 private key
openssl genpkey -algorithm ED25519 -out aioschema-private-key.pem

# Export public key
openssl pkey -in aioschema-private-key.pem -pubout -out aioschema-public-key.pem

# Derive Creator ID (SHA-256 of public key bytes, first 16 bytes = 32 hex chars)
openssl pkey -in aioschema-private-key.pem -pubout -outform DER | \
  openssl dgst -sha256 | awk '{print "ed25519-fp-" substr($2, 1, 32)}'

# Export private key as Base64 (one line, for use in environment variables)
openssl pkey -in aioschema-private-key.pem -outform DER | base64 | tr -d '\n'

Using the AIOSchemaHub Creator ID Generator:

A browser-based generator is also available at aioschemahub.com.

Files to keep:

File	Secret?	Notes
aioschema-public-key.pem	No	Can be shared freely. Verifiers use it.
aioschema-private-key.pem	Yes	Never transmit, commit, or share.
Your Creator ID string	No	Public identity. Embed in manifests and config.

---

Protecting Your Private Key

The private key is the single point of compromise. If it is obtained by another party, they can sign manifests as you. There is no revocation mechanism for signatures already made with a compromised key.

Do

• Back up the private key to an encrypted, offline location: encrypted USB drive, password manager with file attachment support, or hardware security module (HSM)
• Store it as an environment variable in your build environment, not as a committed file
• Use a passphrase on the PEM if your toolchain supports it
• Replace it immediately if you suspect exposure - see Key Compromise below

Don’t

• Never commit the private key to any version control repository, public or private
• Never paste it into chat, email, support tickets, or log output
• Never hardcode it in build scripts - use secrets storage (GitHub Secrets, environment variables, Vault, etc.)
• Never store it in a location accessible to other users or services on the same system

---

Key Compromise

Loss vs compromise

Loss means you can no longer sign new work as your current Creator ID. Old manifests remain fully verifiable - verification uses the public key, not the private key file. Your Creator ID goes dormant: its existing manifests are intact, but no new ones will appear under it.

Compromise means another party can sign as you. Old signatures remain cryptographically valid - a stolen key does not retroactively break them - but a verifier who knows the key was compromised may discount signatures made after the compromise date. The steps below are the same for both cases; compromise has one additional first action.

If your key is compromised: act immediately

Step 1 - Revoke the old key. Publish "revoked": true in your key document at:

https://aioschema.org/keys/<your-creator-id>.json

This is the §9.5 Creator Key Discovery record. Once revoked is true, conforming verifiers will not use the key for new signature verification and will emit a warning. Do this before generating the new keypair.

The key document format:

{
  "creator_id":  "ed25519-fp-<your-32hex>",
  "public_key":  "<base64-encoded-public-key>",
  "published":   "2026-05-10T12:00:00Z",
  "revoked":     true
}

Step 2 - Generate a new keypair. A new keypair produces a new Creator ID. There is no mechanism to attach a new key to an existing Creator ID - this is a deliberate security property. See Why You Can’t Reuse a Creator ID below.

Step 3 - Establish asserted identity continuity. On your first new manifest, set previous_version_anchor to the anchor URI of your last manifest under the old Creator ID. Add a description note:

{
  "core": {
    "creator_id": "ed25519-fp-<new-id>",
    "previous_version_anchor": "aios-anchor:rfc3161-sectigo:<original-anchor-id>",
    ...
  },
  "extensions": {
    "description": "Re-issued: key compromise. Previous creator_id: ed25519-fp-<old-id>. Original anchor: aios-anchor:rfc3161-sectigo:<id>"
  }
}

Step 4 - Anchor the re-issued manifests. Anchoring establishes the timestamp of the transition. The original anchor proves prior existence under the old Creator ID; the new anchor proves the transition point.

Step 5 - Update your signing configuration. Replace the private key in your build environment with the new one and update your Creator ID wherever it is configured.

If your key is lost (not compromised)

Skip Step 1. The key cannot be used by anyone, so no revocation is needed. Proceed from Step 2.

What “asserted identity continuity” means

The previous_version_anchor + description chain is asserted, not cryptographically proven. You are declaring the connection between the old and new Creator ID. Verifiers who trust you can follow the chain. Verifiers who require cryptographic proof of identity continuity across a key change will see two separate signing identities connected by an anchor chain and a declared relationship - not a single unbroken identity.

This is the correct v0.5.x behaviour. Full cryptographic key rotation within a stable identity - where the DID document cryptographically authorises the new key under the same identity - is planned for v0.6 via DID-based Creator IDs.

---

Key & Identity FAQ

Q: What is my Creator ID? The SHA-256 fingerprint of your Ed25519 public key, formatted as ed25519-fp-<32hex>. It is derived deterministically - not chosen or assigned. It is public by design, like a PGP fingerprint, and is embedded in every attributed manifest you create.

Q: What happens if I lose my private key? Your existing manifests are fully verifiable without the key file - verification uses the public key embedded in the manifest or discoverable via §9.5. What you lose is the ability to sign new work as that Creator ID. Generate a new keypair, set previous_version_anchor on your first new manifest to chain it to your old provenance record, and add a description note. Your old manifests remain intact.

Q: What happens if my private key is compromised? Immediately publish "revoked": true at https://aioschema.org/keys/<your-creator-id>.json. Conforming verifiers will stop using the compromised key. Then follow the same steps as key loss: new keypair, new Creator ID, previous_version_anchor chain. Old signatures remain cryptographically valid but verifiers who know the key was compromised may discount post-compromise signatures.

Q: Can I get a new key for the same Creator ID? No. The Creator ID is the key fingerprint. A different key produces a different fingerprint, which is a different Creator ID. This is the security guarantee: if a new key could be attached to an existing Creator ID without the old key’s participation, identity hijacking would be possible. v0.6 DID mode will separate stable identity from rotatable signing keys - until then, a new key means a new Creator ID.

Q: How do I link my old and new Creator IDs? Set previous_version_anchor on your first new manifest to point to the anchor URI of your last manifest under the old Creator ID. Add a description note identifying the relationship. This creates an auditable chain: the original anchor proves prior existence, the new anchor marks the transition point, and the description records the declared connection. See the Provenance Chaining Patterns section of the Field Reference for format guidance.

Q: What’s the difference between losing a key and a key being compromised? Loss: you can’t sign new work, but neither can anyone else. The Creator ID goes dormant. Compromise: someone else can sign as you. The recovery steps are the same but compromise requires the additional revocation step first. The threat model differs: with loss, existing signatures are trustworthy; with compromise, signatures made after the theft date are suspect.

Q: Why can’t I reuse a Creator ID with a new key? {#why-you-cant-reuse-a-creator-id} The Creator ID is a cryptographic commitment to a specific key. If the standard allowed any new key to claim an existing Creator ID without the old key’s participation, an attacker who obtained the Creator ID string (which is public) could generate a new key and impersonate the original creator. The one-to-one binding between Creator ID and keypair is what makes the attribution trustworthy.

Q: Will v0.6 fix the key rotation limitation? Yes. v0.6 plans DID-based Creator IDs, which decouple stable identity from signing keys. Under DID mode, a compromised or lost key is rotated in the DID document: the Creator ID stays the same, the authorised key changes. The previous_version_anchor mechanism remains valid for backward compatibility and cross-version provenance chains.