Concepts and Architecture
This page explains what the Secure Keystore is for, the five security concepts it rests on, and the parties it works with. Unfamiliar terms are explained in the Glossary.
Why a secure keystore
An EUDI wallet needs two kinds of hardware-protected keys:
- a credential key for each credential: the issuer binds the credential to it, and the verifier checks it at every presentation;
- a WIA key, which proves the wallet to issuers through the wallet instance attestation (WIA).
The keystore also gives each user a user-signing key for signatures outside the EUDI protocols, to be used for HSM-backed signing by the mobile application.
The Secure Keystore provides these keys remotely. The private keys live in an HSM run by the wallet provider. In the terms of the EUDI Architecture and Reference Framework (ARF), the keystore is a remote wallet secure cryptographic application (WSCA) backed by a wallet secure cryptographic device (WSCD), here the HSM.
The keystore also signs the two attestations the EUDI ecosystem requires: the key attestation (KA), which vouches for the credential keys, and the wallet instance attestation (WIA).
The keystore keeps one unit per user device: the keystore’s record of one PowerAuth activation. The unit id is the activation id.
Main security concepts
- Wrapped keys. The HSM generates each user key and returns it encrypted, as a wrapped key. The phone stores the wrapped key. The HSM stores no per-user keys.
- Signing on demand. To sign, the wallet sends the wrapped key and the data to sign. The HSM restores the private key, signs and destroys it.
- Device signatures. Every user request that uses the HSM is a signed request (a JWS) made with the activation’s device private keys: ECDSA P-384, plus ML-DSA for a hybrid activation. The PowerAuth SDK releases these keys only after the user unlocks the PowerAuth vault with PIN or biometry. The wallet signs the request and then encrypts it. The keystore decrypts it, verifies every device signature against the device public keys stored for the unit, and only then uses the HSM.
- Keys bound to the device. Every wrapped key is sealed to its unit, its purpose and the thumbprints of the activation’s device public keys. A wrapped key presented for another unit or another purpose is refused. When a user-signing key signs, the keystore also checks that the sealed thumbprints match the device keys stored for the unit.
- End-to-end encryption. The bodies of user requests and responses are encrypted between the PowerAuth SDK on the phone and the keystore. The Wallet Integration Server forwards them unchanged and cannot read them.
Calls from backends do not carry a signed request. Unit registration and revocation by the Wallet Integration Server, and all backend-key calls, authenticate the caller with a bearer token (or mTLS when required).
Besides user keys, the HSM also holds backend keys: the long-term signing keys of PowerAuth Server and of diw-gateway, Wultra’s EUDI issuance and verification backend (services diw-issuer, diw-connector as the OAuth authorization server, and diw-verifier). Short-lived cryptographic material stays in software. See Backend Key Storage.
Architecture
The OpenID4VCI and OpenID4VP steps between the wallet, issuers and verifiers are standard and unchanged. PowerAuth Server and diw-gateway also call the keystore for their own backend keys; the diagram does not show this.
Participants
| Participant | Role |
|---|---|
| Wallet app (PowerAuth SDK) | Stores the wrapped keys, signs each request with the device private keys after a vault unlock, and encrypts it. Never calls the keystore directly. |
| Wallet Integration Server | The wallet provider’s backend. Serves the vault unlock, forwards the wallet’s requests unchanged, and registers and revokes units. |
| Secure Keystore | Decrypts each user request, checks the device signatures and the activation status, then uses the HSM. See Request Checks. |
| PowerAuth Server | Verifies the vault unlock and counts failed attempts. Holds the activations and their device public keys, and provides the decryption keys. |
| HSM | Used only by the keystore, through PKCS#11. Generates, wraps, unwraps and signs. |