Migration from 0.22.0 to 0.23.0
This guide contains instructions for migration from PowerAuth Server version 0.22.0 to version 0.23.0.
Bouncy Castle Library Update to Version 1.64
Bouncy Castle library has been updated to version 1.64. The newest version of Bouncy Castle library can be downloaded from: https://www.bouncycastle.org/download/bcprov-jdk15on-164.jar
Installation on Java 8:
- Update Bouncy Castle library the
lib/extfolder of the Java runtime
Installation on Java 11:
- Tomcat: update Bouncy Castle library in
CATALINA_HOME/lib - JBoss / Wildfly: update Bouncy Castle library global module
- Other web containers: follow instructions for installing a global library for the web container
- Standalone mode: PowerAuth Server can no longer be started from command line because of missing Bouncy Castle library in the war file. Contact us if you want to run PowerAuth Server in standalone mode.
For more details about installation of the library see Installing Bouncy Castle.
Database Changes
Following DB changes occurred between version 0.22.0 and 0.23.0:
- Table
pa_application- added not null constraint to columnname, inserted defaultapplication_idwhere null - Table
pa_application- added unique index constraint to columnname- This index is mandatory. The script will fail when there are already duplicated names. In such case ensure unique values manually and repeat adding the unique index constraint.
Migration script for Oracle:
UPDATE "PA_APPLICATION" SET NAME = CONCAT('application_', id) WHERE NAME IS NULL;
ALTER TABLE "PA_APPLICATION" MODIFY "NAME" NOT NULL;
CREATE UNIQUE INDEX "PA_APPLICATION_NAME" ON PA_APPLICATION(NAME);
ALTER TABLE "PA_SIGNATURE_AUDIT" ADD "SIGNATURE_VERSION" VARCHAR2(255 CHAR);
Migration script for MySQL:
UPDATE `pa_application` SET `name` = CONCAT('application_', `id`) WHERE `name` IS NULL;
ALTER TABLE `pa_application` MODIFY COLUMN `name` VARCHAR(255) NOT NULL;
CREATE UNIQUE INDEX `pa_application_name` ON `pa_application`(`name`);
ALTER TABLE `pa_signature_audit` ADD `signature_version` varchar(255);
Migration script for PostgreSQL:
UPDATE "pa_application" SET name = CONCAT('application_', id) WHERE name IS NULL;
ALTER TABLE "pa_application" ALTER COLUMN "name" SET NOT NULL;
CREATE UNIQUE INDEX "pa_application_name" ON PA_APPLICATION(NAME);
ALTER TABLE "pa_signature_audit" ADD "signature_version" VARCHAR(255);
PowerAuth Protocol Version 3.1
PowerAuth protocol version 3.1 support has been introduced in PowerAuth server version 0.23.0.
The main changes in PowerAuth protocol are following:
- Improved information entropy in PowerAuth online signatures. The signature is now encoded into BASE64 instead of decimal string.
- Improved protection of encrypted status blob against possible replay attacks.
- Improved protection of payload encrypted by our ECIES scheme.
- Improved protocol reliability by allowing the mobile client to synchronize its counter with the server.
The changes of cryptography are documented in details in the powerauth-crypto project.
SOAP Interface Changes
PowerAuth server in version 0.23.0 slightly changed SOAP interface for protocol version 3 (namespace http://getlime.io/security/powerauth/v3):
VerifySignatureRequestrequest object has now required parametersignatureVersion. The client must provide the version of signature obtained fromX-PowerAuth-Authorizationheader.VaultUnlockRequestrequest object has now required parametersignatureVersion. The client must provide the version of signature obtained fromX-PowerAuth-Authorizationheader.GetActivationStatusRequestrequest object has now new optional parameterchallenge, which is now provided byV3.1mobile clients.GetActivationStatusResponseresponse object has now new optional parameterencryptedStatusBlobNonce, which is provided only ifchallengein request is present.
The following request objects were updated due to changes in our ECIES encryption scheme. The optional parameter nonce must be provided for protocol V3.1 and later:
PrepareActivationRequestrequest object now contains optional parameternonce.CreateActivationRequestrequest object now contains optional parameternonce.VaultUnlockRequestrequest object now contains optional parameternonce.CreateTokenRequestrequest object now contains optional parameternonce.StartUpgradeRequestrequest object now contains optional parameternonce.ConfirmRecoveryCodeRequestrequest object now contains optional parameternonce.RecoveryCodeActivationRequestrequest object now contains optional parameternonce.
You can access the WSDL files in following URLs:
- version
3:http://localhost:8080/powerauth-java-server/soap/serviceV3.wsdl - version
2:http://localhost:8080/powerauth-java-server/soap/serviceV2.wsdl
Client API Changes
Both Spring and Axis2 clients have been updated to support version 3.1 of PowerAuth protocol. The most important change is in the method which provides information about the activation status:
getActivationStatus(activationId)method no longer providesencryptedStatusBlobin the response, so it’s no longer usable for PowerAuth standard RESTful API implementation.getActivationStatusWithEncryptedStatusBlob(activationId, challenge)is a new method that returns an activation information, together with theencryptedStatusBlob(andencryptedStatusBlobNonce, ifV3.1mobile client is getting the status)
The reason for the change is that the original function is no longer usable for PowerAuth standard RESTful API implementation purposes, because the challenge parameter is now required for V3.1 status blob encryption.
Database record encryption
If you turned on additional database record encryption in any previous PowerAuth Server version (see Encrypting Records in Database), please contact us at [email protected]. The encryption scheme has been slightly changed, so we can help you with the migration.
SOAP Endpoint Changes
Revoking Recovery Codes on Activation Removal
We added an optional revokeRecoveryCodes attribute to activation removal service call. This flag indicates if recovery codes that are associated with removed activation should be also revoked. By default, the value of the flag is false, hence omitting the flag results in the same behavior as before this change.