This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
Key management
This page is the key-management policy for iya-sts, and its inventory of keys. It follows the lifecycle in NIST SP 800-57 Part 1. It describes product mode: in development mode keys are made anew at every start and not rotated.
The live inventory is in the admin console:
/admin/crypto-metadatalists every algorithm the running service performs, read from the code that performs it, and every key it holds./admin/keysand/admin/pkilist the keys and certificates of the realm.GET /crypto/metadatais the public document: every signing generation with itskid, certificate chain, validity and revocation addresses. Review it on your own schedule and whenever a certificate is changed. The pages are built from the running service, so they cannot go out of date.
The inventory below adds what those pages do not say: where each key must not be used, and what kinds of data it may protect. The levels are those of Data classification.
Lifecycle
| Stage | What happens |
|---|---|
| Generation | Keys come from the operating system’s random source. RSA keys are 3072 bits in product by default (pki.keyAlgorithm). The service does not generate a key-encryption key: you, or your key management service, do. |
| Distribution | Public halves are published in JWKS, metadata and certificates. A private key leaves the service only in the reply that creates or exports it: to the person it was made for, or to a caller holding Admin Write. Data keys move between nodes wrapped, through the database. |
| Storage | Private keys and secrets are sealed at rest. The key-encryption key is held outside the database. In memory, keys.plaintextRetention sets how long a decrypted private key is kept after use. |
| Use | Each key is used only for the purposes in the inventory below. A signing unit is one use case and one algorithm. |
| Rotation | A new signing key is published before it signs (signing.rotate). Data keys rotate on a schedule and values are re-encrypted in the background. |
| Retirement | A retired signing key is still published for what it signed, for signing.retiredKeyGraceDays or the longest lifetime of anything it could have signed. A superseded data key opens what it sealed and seals nothing new. |
| Destruction | A retired signing key is dropped and its certificate is listed as superseded. A superseded data key is destroyed after keys.dataKeyRetireAfterDays, once nothing is sealed under it. Destruction cannot be undone. |
| Compromise | POST /admin-api/keys/emergency replaces every signing key at once with no grace, revokes the old certificates for keyCompromise, and ends every session of the realm. |
See Encryption at rest for data keys and the key-encryption key, and PKI for certificates and signing generations.
Who may hold a key
- A private key belongs to one entity. All the nodes of one deployment count as one entity, and share keys through the sealed store.
- A shared secret belongs to at most two entities. A client secret is shared by the client and this service. A TOTP secret is shared by the person’s authenticator and this service. A Kerberos service key is shared by the KDC and the service that holds its keytab.
- Do not copy a key to a third party. Export exists for migration and recovery. Exporting a key makes you responsible for every copy.
Where the service departs from the first rule, you can see it here. Each is an accepted condition of this policy (ASVS 5.0.0 11.1.1), kept because the key has to be retrievable after issue:
- The realm’s signing keys and the listener certificate key can be exported by a
caller holding Admin Write, from
/admin/keysand/admin/pki. Every export is a second holder. - An application’s RFC 7523 or RFC 7522 assertion key pair stays sealed on its entry after issue, so that an administrator can collect it. The service and the application then both hold it. Prefer an application that generates its own key and registers only the public half.
- A person’s assertion key pair and a TLS client certificate’s key are given once and not kept, so they have one holder.
Approved algorithms
These are the signature algorithms this policy approves (ASVS 5.0.0 11.6.1).
In product mode the service signs and accepts only these, and
/admin/crypto-metadata lists which the running realm uses.
| Family | Approved | Notes |
|---|---|---|
| RSA | RSASSA-PKCS1-v1_5 and RSASSA-PSS with SHA-256, SHA-384 or SHA-512 | 3072-bit keys are generated in product. Peers’ keys are accepted from 2048 bits in JOSE, and with no floor in XML signatures, for partners that still sign with older keys |
| ECDSA | P-256, P-384 and P-521; brainpool curves of 256 bits and more for XML | secp256k1 (ES256K) only where keys.signingAlgorithms or keys.acceptedSigningAlgorithms lists it |
| EdDSA | Ed25519 and Ed448 | Off by default (keys.eddsaSigning) |
| Post-quantum | ML-DSA-44, -65 and -87 (FIPS 204); SLH-DSA (FIPS 205); the ML-DSA composites | |
| HMAC | HMAC-SHA-256, -384 and -512 | For client_secret_jwt and shared-secret JWS |
| BBS | bbs-2023, on BLS12-381 (W3C Data Integrity BBS Cryptosuites v1.0) |
Approved for verifiable credentials only, for selective disclosure and unlinkable presentations, which no algorithm above provides. It is not a NIST algorithm. Each realm generates its own BBS key |
Algorithms outside this table are refused in product mode, or used only where a
specification requires them and the setting that allows them is named on
/admin/mode.
Inventory of keys
| Key | Use | Must not be used for | May protect |
|---|---|---|---|
Key-encryption key (keys.kek*) |
Wrapping data keys | Anything else. Never a value, a token or a password | Data keys only |
Cell key-encryption key (keys.cellKek*) |
Wrapping the data keys of one cell’s resident data | Other cells’ data | That cell’s data keys |
| Data encryption keys | Sealing stored values, one per realm per kind of data | Another realm, another kind of data, or anything off the store | Restricted, Bearer, Sensitive personal and Personal data at rest |
| Stored digest key | Keyed digests for lookups and cell locators | Encryption or signing | Lookup values, as digests only |
Realm jose signing keys (RS256, curves, post-quantum) |
Signing access tokens, refresh tokens, ID Tokens, signed UserInfo and other JWTs of the realm | Signing outside this realm. Not for DPoP where the algorithm has no thumbprint | Integrity of Bearer and Personal data |
Realm xml signing key |
Signing SAML, WS-Federation and WS-Trust documents and XML metadata | Non-XML signatures | Integrity of Bearer and Personal data |
Request object encryption keys (use: enc at /oauth2/jwks) |
Decrypting request objects sent to this realm | Signing | Confidentiality of request parameters |
KEM decryption keys (keys.encryptionKemAlgs) |
Decrypting data encrypted to the realm with those algorithms | Signing | Confidentiality of what is encrypted to the realm |
| OpenID4VCI request encryption key | Decrypting credential requests | Signing | Confidentiality of the request |
| Refresh token encryption keys | Encrypting refresh tokens | Anything else | Bearer data |
Credential signing key (oid4vci.credentialSigningAlgorithm) |
Signing verifiable credentials | Other tokens, when an algorithm of its own is chosen | Integrity of credentials |
| Root CA key | Signing Intermediate certificates | Leaf certificates or data | Certificate chains |
| Intermediate and Issuing CA keys | Signing certificates and CRLs for their use case | Data, or another use case’s certificates | Certificate chains |
| Listener certificate keys | The TLS handshake on the main port, LDAPS and custom listeners | Application-level signing | Data in transit |
| SPIFFE authority keys | Issuing X509-SVIDs and JWT-SVIDs for the trust domain | Anything outside that trust domain | Workload identities |
Kerberos krbtgt key (krb5.krbtgtRotationIntervalDays) |
Encrypting ticket-granting tickets | Any other purpose | Kerberos tickets |
| Kerberos service and person keys | Service tickets, and pre-authentication | Anything outside Kerberos | Kerberos exchanges |
| Client secrets, and federation client secrets | Authenticating one client to one server, and client_secret_jwt HMAC |
Another client or server | Client authentication only |
| TOTP secrets | Computing one person’s one-time codes | Anything else | One authentication factor |
| GNAP shared keys and macaroon root keys | Signing GNAP requests, and verifying macaroons for one resource server | Another client or resource server | GNAP requests and tokens |
| Application and person assertion key pairs | Signing RFC 7523 or RFC 7522 assertions | Any other signature | Assertion integrity |
| Service credentials: database password, secret store client certificate, mail transport secrets, audit export tokens, secret-destination credentials | Authenticating this service to that one system | Any other system | The connection to that system |
Note. The RSA keys of the
jose:RS256andxml:RS256units also open JWEs and XML encryption sent to this realm with RSA key transport, as well as signing. Prefer the dedicated request object and KEM keys for encryption, and plan for these two keys being used for both purposes.
Algorithms and their permitted uses are in /admin/crypto-metadata. Certificates
are in /admin/pki, and every certificate this service issues carries the key
usages of its use case. See PKI use cases.
Your own responsibilities
- Generate the key-encryption key, keep it out of the database and rotate it on your own schedule. See Rotating the key-encryption key.
- Restrict who can read the store your key is in, and who holds Admin Write.
- Review the live inventory on the schedule your policy requires.