Key Naming Conventions
This page defines how the keys in the HSM are labelled, which domain each key belongs to, and how each key is stored.
The labels below are the target design. The development setup created by the SoftHSM2 scripts uses shorter labels (wrap-<n>, bind-<n>, ka-signing, wia-signing, provider-ca).
Storage Modes
Each key is stored in one of two modes:
- Wrapped. The HSM generates the key, wraps it under the domain’s wrap key, seals it under the domain’s bind key and hands it out. The HSM keeps nothing. The holder sends the wrapped key back with each signing request; the HSM restores the private key, signs and destroys it. User keys (domains
user-*) are held by the phone and sealed to their unit, purpose and device keys. This mode scales to millions of keys. - Resident. The key is a persistent, non-extractable, sign-only object in the HSM. The provider keys (domain
eudi-ecdsa) are created at provisioning. Backend keys (domainspowerauth-master-*anddiw-*-ecdsa) are created through the Backend Keys API. The keystore stores a database row for each one, and the backend component stores its key id. Revocation destroys the HSM object and marks the rowREVOKED. This mode suits a small number of long-lived keys.
Key Labels
Every key in the HSM is labelled <operation>-<domain>[-<suffix>]. The operation says what the key does; the domain says whose keys it serves. A domain with wrapped keys has one wrap key and one bind key per generation <n>. A domain with resident keys holds sign keys.
<n> is the key-set generation. A new generation is added when keys rotate; older generations keep working until they are retired. The rotation period will be set for production. For user keys, the generation is shared by the EC and ML-DSA domains and written into every wrapped key as kid. Each backend domain has its own generation, written into its wrapped keys as gen.
| Key label | Storage mode | Algorithm | Use |
|---|---|---|---|
wrap-<domain>-<n> |
wrapped | AES-256 key wrap | Wraps the domain’s private keys. Every key it restores is non-extractable, sign-only and of the domain’s algorithm family. |
bind-<domain>-<n> |
wrapped | AES-256-GCM | Seals each wrapped key with what binds it, so a copied or edited wrapped key is refused. |
| none (session key) | wrapped | the domain’s algorithm | The private key restored for one signature, as a temporary non-extractable, sign-only object. Destroyed right after the signature. |
sign-eudi-ecdsa-ka, sign-eudi-ecdsa-wia |
resident | ECDSA P-256 | The provider keys that sign key attestations and WIAs. |
sign-<domain> |
resident | the domain’s algorithm | Backend keys. All keys of a domain share this label; each is found by the key id the API returns. |
What the bind key binds:
- User keys: the owner (
unit_id), the purpose and the device-key thumbprints, sealed in the plaintext. - Backend keys: the domain, key type and generation in the authenticated header, and the owner as the JWE AAD.
Domains
Every key belongs to one domain, which fixes its token, its algorithm family and its storage mode.
| Domain | Token | Storage mode | Keys in the HSM | Algorithm and use |
|---|---|---|---|---|
user-ecdsa |
user | wrapped | wrap-user-ecdsa-<n>, bind-user-ecdsa-<n> |
EC user keys: P-256 (WIA and credential keys), P-384 (user-signing keys) |
user-mldsa |
user | wrapped | wrap-user-mldsa-<n>, bind-user-mldsa-<n> |
ML-DSA-65 and ML-DSA-87 user-signing keys. Required on an HSM that supports ML-DSA; absent otherwise. |
eudi-ecdsa |
eudi | resident | sign-eudi-ecdsa-ka, sign-eudi-ecdsa-wia |
ECDSA P-256 (ES256): key attestations and WIAs |
powerauth-activation-ecdsa |
backend | wrapped | wrap-powerauth-activation-ecdsa-<n>, bind-powerauth-activation-ecdsa-<n> |
P-384 PowerAuth v4 activation server keys, one per activation |
powerauth-activation-mldsa |
backend | wrapped | wrap-powerauth-activation-mldsa-<n>, bind-powerauth-activation-mldsa-<n> |
ML-DSA-65 and ML-DSA-87 activation server keys, one per hybrid activation |
powerauth-master-ecdsa |
backend | resident | sign-powerauth-master-ecdsa |
P-384 PowerAuth v4 master keys, one per application |
powerauth-master-mldsa |
backend | resident | sign-powerauth-master-mldsa |
ML-DSA-65 and ML-DSA-87 master keys, one of each per application |
diw-issuer-ecdsa |
backend | resident | sign-diw-issuer-ecdsa |
ECDSA P-256 keys of diw-issuer: credential-signing and access-certificate keys |
diw-connector-ecdsa |
backend | resident | sign-diw-connector-ecdsa |
ECDSA P-256 access-token key of diw-connector |
diw-verifier-ecdsa |
backend | resident | sign-diw-verifier-ecdsa |
ECDSA P-256 keys of diw-verifier: access and registration keys per relying-party instance |
Rules:
- Every key is generated inside the HSM.
- A backend key may also have a
namefor the key inventory. The name is stored with the key’s database row; it is not part of the label. - A domain holds one algorithm family, and its name ends with it (
-ecdsaor-mldsa). A family added later gets its own sibling domain. - The user domains and
eudi-ecdsabelong to the keystore itself. Backend domains are configured per backend client (PowerAuth Server, diw-gateway services), each with its storage mode and accepted key types. Each backend component can use only its own keys. - The keystore finds a key by its label, but checks the key’s attributes before using it (planned; the runtime HSM operations are not implemented yet).