Migration from 1.10.x to 2.0.x
This guide contains instructions for migration from PowerAuth Cloud version 1.10.x to version 2.0.0.
Update Database Encryption Configuration
PowerAuth Server 2.0.0 introduces a new default database encryption algorithm used for encrypting sensitive values stored in the database, such as master private keys, activation private keys, temporary keys, callback authentication, and other sensitive data. This encryption is done by the PowerAuth server application and it should be used on top of database encryption at rest to avoid leakage of sensitive data.
New Default Encryption Algorithm: AEAD_KMAC
The algorithm AEAD_KMAC is now the default database encryption algorithm. It uses:
- a 256-bit master DB encryption key
- KMAC-256 for per-record key derivation
- Authenticated encryption using an AEAD scheme based on AES-256
This offers improved security with post-quantum grade encryption.
Required Action: Configure a 256-bit Base64-Encoded Encryption Key
To use the default algorithm, configure the following property:
POWERAUTH_SERVER_DB_MASTER_ENCRYPTION_AEAD_KMAC_KEY=<base64-encoded-256-bit-key>
The server will not start if AEAD_KMAC is the default algorithm but the key is missing or invalid.
How to Generate a Valid 256-bit Encryption Key
Use any cryptographically secure random generator to produce a 32-byte key and encode it in Base64.
Linux / macOS
head -c 32 /dev/urandom | base64
OpenSSL
openssl rand -base64 32
Paste the generated value into the configuration property.
Securing the Encryption Key
The master database encryption key is a highly sensitive secret and must be protected. Do not store this key directly in configuration files, source control, or container images. Use a secure secret management solution (such as a vault or encrypted configuration provider) to supply the key to the application at runtime and restrict access only to the PowerAuth Server process.
Switching to NO_ENCRYPTION
If you are upgrading a non-production environment, you may override the default encryption algorithm:
POWERAUTH_SERVER_DB_MASTER_ENCRYPTION_ALGORITHM=NO_ENCRYPTION
When using NO_ENCRYPTION, no database encryption keys are required, and sensitive values will be stored in plaintext.
Legacy Encryption Algorithm Configuration
The AES_HMAC encryption algorithm is legacy and should not be used in PowerAuth server 2.0.0 or higher.
In case you used this encryption algorithm previously, keep the configured key in property POWERAUTH_SERVER_DB_MASTER_ENCRYPTION_KEY to allow decryption of existing data.
Removed Configuration Property
Configuration property POWERAUTH_SERVER_RECOVERY_MAX_FAILED_ATTEMPTS is no longer used due to removed recovery code functionality. You can remove the configuration of this property in case it is used.
REST API Migration
The REST API has been updated to reflect changes required for integration with PowerAuth server 2.0.x, which introduces post-quantum cryptography.
REST API Updates
GET /admin/application/{id}
The application detail endpoint no longer contains parameter masterServerPublicKey. The configuration of mobile SDK is available in parameter mobileSdkConfig.
GET /v2/registrations/{registrationId}
The registration detail endpoint parameter activationCodeSignature is deprecated and will be removed in a future release. Use parameters activationCodeSignatureEcdsa instead for ECDSA signature and activationCodeSignatureMldsa for ML-DSA signature.
POST /v2/signature/verify
The signature verification endpoint is deprecated and will be removed in a future release. Use endpoint POST /v2/authentication/verify instead.
POST /v2/token/verify
The token verify endpoint parameter signatureType is deprecated and will be removed in a future release. Use parameters authenticationCodeType instead.
POST /v2/operations/{operationId}/offline/otp
The operation offline OTP validation endpoint parameter signatureType is deprecated and will be removed in a future release. Use parameters authenticationCodeType instead.
GET /admin/templates
The template list endpoint has been modified to return authenticationCodeTypes instead of signatureTypes in the template detail. This change was done to unify terminology due to updated REST API parameter naming.
Registration Attributes
The API endpoints GET /v2/registrations, and GET /v2/registrations/{registrationId} newly return the following attributes:
parentRegistrationId- Parent registration ID if the registration is created using a transfer.transferType- Transfer type of the registration, eitherSPAWNorMOVE.
Structured logging
All endpoints contain structured logging. At the INFO level, the action, its state, and important parameters are logged.
For example: action: createApplication, state: initiated, applicationId: app-example
To log the full request and response, set the logging level to DEBUG.