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.

Database Changes

A new database table pa_cloud_device_info_mapping has been added in version 2.0.0.

For convenience, you can use liquibase for your database migration.

For manual changes use SQL scripts:

• PostgreSQL script
• Oracle script
• MSSQL script

Update Database Encryption Configuration

PowerAuth Cloud 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.

Configuration of Applications to Support New Cryptographic Algorithms

Existing applications only have traditional elliptic curve P-256 key pairs.

To generate new application key pairs for elliptic curve P-384 and ML-DSA-65 / ML-DSA-87, call the application configuration endpoint to configure supported algorithms Create Application Configuration:

REST endpoint: POST /admin/applications/[appId]/config

You can exclude some algorithms if you don’t want to use them from the list above. Application key pairs for supported algorithms will be generated.

Sample cURL call:

curl --request POST \
--url https://[host]:[port]/powerauth-cloud/admin/applications/[appId]/config \
--header 'Content-Type: application/json' \
--data '{
  "key": "cryptography_algorithms_supported",
  "values": [ "EC_P256", "EC_P384", "EC_P384_ML_L3", "EC_P384_ML_L5"]
}'

Changed Configuration Properties

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.

Configuration property POWERAUTH_SERVER_TOKEN_TIMESTAMP_VALIDITY is no longer used. You can remove the configuration of this property in case it is used.

Configuration property POWERAUTH_SERVER_SIGNATURE_MAX_FAILED_ATTEMPTS was renamed to POWERAUTH_SERVER_AUTHENTICATION_CODE_MAX_FAILED_ATTEMPTS. Update your configuration in case this value is modified from default value (5 attempts).

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 activationCodeSignatures instead for getting ECDSA and ML-DSA signatures.

The following keys can be used to get signatures, the JWT terminology is used:

• ES256 - ECDSA signature on P-256 elliptic curve (legacy)
• ES384 - ECDSA signature on P-384 elliptic curve (current)
• ML-DSA-65 - post-quantum ML-DSA-65 signature (current)
• ML-DSA-87 - post-quantum ML-DSA-87 signature (current)

The endpoint also accepts a new optional boolean parameter translateDeviceInfo (see GET /v2/registrations).

GET /v2/registrations

The endpoint accepts a new optional boolean parameter translateDeviceInfo (default value false). If the value is true, the PowerAuth Cloud will attempt to replace the value returned in the deviceInfo attribute with a human-friendly variant.

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.

Note that the error code changed from ERROR_SIGNATURE_INVALID to ERROR_AUTH_INVALID to reflect the terminology changes. Update your code in case you check the error code.

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, either SPAWN or MOVE.

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.