PowerAuth Integration

This page explains how the keystore authorizes a wallet request with the user’s PowerAuth activation, and why it relies on device signatures rather than PowerAuth codes. The PowerAuth activation id is also the keystore’s unitId.

Request Checks

Before any HSM operation on a user request, the keystore runs these checks in order:

1. Envelope decryption. The keystore asks PowerAuth Server for the decryption key of the temporary key named in the request, and decrypts the body. This proves that the request was encrypted for this activation and keeps it confidential. It does not prove who the user is.
2. Unit check. The unit must exist (400 unit_not_found) and must not be revoked (409 unit_revoked).
3. Signed-request validation. The keystore verifies the signed request inside the envelope: every device signature against the device public keys stored for the unit, then aud, sub, the iat window and the single-use jti. This is the user’s authorization.
4. Activation status. PowerAuth Server confirms that the activation is ACTIVE, and the request matches stored device public key(s).
5. HSM operation. Only then does the keystore call the HSM through PKCS#11. To create a key, the HSM generates a key pair, wraps the private key under the wrap key of its domain and seals the result under the bind key. To sign, the HSM opens the seal, unwraps the key, signs and destroys the key. The HSM keeps no per-user keys. See HSM Setup.

Role of the Wallet Integration Server

• Registers the activation as a unit during the activation, before the commit (POST /v1/pa/units), and revokes the unit when the activation is removed.
• Serves the PowerAuth vault unlock.
• Forwards every user request of the wallet unchanged. It cannot read the encrypted bodies and cannot sign with a user’s keys, because the keystore itself verifies the device signatures.

REST API Overview

• Device signature: the user unlocks the PowerAuth vault with PIN or biometry, and PowerAuth Server verifies it. The vault then releases the device private keys, which sign the request (both keys for a hybrid activation). The keystore verifies these signatures. No PowerAuth code reaches the keystore.
• Backend token: a call of the Wallet Integration Server authenticated as a backend caller: a bearer token now, mutual TLS later.
• Encrypted: the request and response bodies are encrypted end to end between the wallet and the keystore. Every call from the wallet is encrypted; backend calls are not.

Why Device Signatures Rather Than PowerAuth Codes

PowerAuth codes are symmetric: PowerAuth Server knows the same secrets and could compute a valid code itself. Certifying that the user has sole control of the keys, as required for a WSCA/WSCD or for eIDAS level of assurance high, needs evidence that only the user’s device can produce. The PowerAuth code therefore only unlocks the vault, and the keystore accepts only signatures made with the device private keys.

Related Documentation

• API General Principles
• EUDI Wallet Flows
• Comparison with the German Model
• Glossary
• PowerAuth Server
• PowerAuth Mobile SDK