Skip to content

Commit

Permalink
Merge pull request #335 from wultra/develop
Browse files Browse the repository at this point in the history 
Prepare release 0.24.0
  • Loading branch information
@romanstrobl
romanstrobl authored Apr 24, 2020
2 parents ea9583f + af919f8 commit 9e41eab
Show file tree
Hide file tree
Showing 65 changed files with 491 additions and 686 deletions.
5 changes: 4 additions & 1 deletion docs/Activation-Code.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
# Activation Code

The PowerAuth protocol 3, defines a new version of activation code, where OTP is no longer applied. The format of the code is the same (four groups, each group is composed from five Base32 characters), but the code is no longer split into `OTP` and `SHORT_ID` parts. The new code has following features:
The PowerAuth protocol 3, defines a new version of activation code, where OTP<sup>1</sup> is no longer applied. The format of the code is the same (four groups, each group is composed from five Base32 characters), but the code is no longer split into `OTP` and `SHORT_ID` parts. The new code has following features:

- The whole code is now a short activation identifier, and we call it simply `ACTIVATION_CODE`. This principally means, that the code is no longer used in the cryptographic calculations.
- The code is using `CRC-16/ARC` to detect a typing errors. This is useful for scenarios, where the user needs to re-type the code manually.
- 96 out of possible 100 bits are used (80 random bits + 16 bits for CRC).

> Notes:
> 1. PowerAuth protocol V2 defines OTP as a part of activation code. It's completely unrelated to an [additional activation OTP](Additional-Activation-OTP.md).
## Code Construction

1. Generate 10 random bytes
Expand Down
3 changes: 2 additions & 1 deletion docs/Activation-Recovery.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,14 +46,15 @@ The Activation via Recovery Code is by default **disabled** on PowerAuth Server.
If application is activated via the Recovery Code and PUK, then it goes immediately to **ACTIVE** state (see [Activation States](Activation.md#activation-states)). There's no intermediate state when the user can confirm that activation in the additional digital channel (like internet banking). This fact limits this feature mostly to only limited application scenarios:

1. Only for the application that doesn't provide active operations
2. The application itself acts as a confirmation device (like our [Mobile Token](https://www.wultra.com/product/powerauth-mobile-token) does)
2. The application itself acts as a confirmation device as our [Mobile Token](https://www.wultra.com/mobile-token) does.

For the first case, we don't recommend to allow this feature for PowerAuth powered applications, that provide "active" operations. That's typically a mobile banking app that can withdraw money from user's account. The reason for that is that if the Recovery Code and PUK are compromised, then the attacker can easily harm the user.

In the second scenario, the mobile application acts as a replacement for a typical authorization channel, like SMS, or another hardware token. In this situation, compromising Recovery Code and PUK can be still very dangerous, but requires a more coordinated attack to harm the user. The attacker has to typically gain an access to additional credentials, like login and password to internet banking.

For all cases, we recommend you to implement the following countermeasures:

- Confirm the recovery activation with an [additional activation OTP](Additional-Activation-OTP.md).
- Your application should receive a push notification once the activation is recovered on another device.
- You should also notify the user via other digital channel, like SMS or e-mail.
- You should adequately inform the user about how sensitive Recovery Code and PUK are.
Expand Down
2 changes: 1 addition & 1 deletion docs/Activation-Status.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ where:
- Note that the last byte of this constant also represents the version of the status blob format. If we decide to change the status blob significantly, then the value will be changed to `0xD2`, `0xD3`, etc...
- `${STATUS}` - A status of the activation record, it can be one of following values:
- `0x01 - CREATED`
- `0x02 - OTP_USED`
- `0x02 - PENDING_COMMIT`
- `0x03 - ACTIVE`
- `0x04 - BLOCKED`
- `0x05 - REMOVED`
Expand Down
12 changes: 9 additions & 3 deletions docs/Activation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Following components play role in activation:
Record associated with given PowerAuth keys transits between following states during it's lifecycle:

- **CREATED** - The activation record is created but it was not activated yet.
- **OTP_USED** - The activation record is created and activation code was already used, but the activation record was not activated yet.
- **PENDING_COMMIT** - The activation record is created and activation code was already used, but the activation record was not activated yet.
- **ACTIVE** - The activation record is created and active, ready to be used for generating signatures.
- **BLOCKED** - The activation record is blocked and cannot be used for generating signatures. It can be renewed and activated again.
- **REMOVED** - The activation record is permanently blocked - cannot be used for generating signatures or renewed.
Expand Down Expand Up @@ -81,7 +81,7 @@ To describe the steps more precisely, the activation process is performed in fol
1. PowerAuth Server generates an `ACTIVATION_ID`, `ACTIVATION_CODE`, `CTR_DATA` - an initial value for hash based counter, and a key pair `(KEY_SERVER_PRIVATE, KEY_SERVER_PUBLIC)`. Server also optionally computes a signature `ACTIVATION_SIGNATURE` of `ACTIVATION_CODE` using servers master private key `KEY_SERVER_MASTER_PRIVATE`.
```java
String ACTIVATION_ID = Generator.randomUUID()
String ACTIVATION_CODE = Generator.randomActivationCode() // must be unique among records in CREATED and OTP_USED states
String ACTIVATION_CODE = Generator.randomActivationCode() // must be unique among records in CREATED and PENDING_COMMIT states
byte[] CTR_DATA = Generator.randomBytes(16)
KeyPair keyPair = KeyGenerator.randomKeyPair()
PrivateKey KEY_SERVER_PRIVATE = keyPair.getPrivate()
Expand Down Expand Up @@ -119,7 +119,7 @@ To describe the steps more precisely, the activation process is performed in fol

1. PowerAuth Server decrypts `ACTIVATION_DATA` with using an application scoped ECIES (level 2, `sh1="/pa/activation"`) and stores `KEY_DEVICE_PUBLIC` at given record.

1. PowerAuth Server changes the record status to `OTP_USED`.
1. PowerAuth Server changes the record status to `PENDING_COMMIT`.

1. PowerAuth Server encrypts response, containing `ACTIVATION_ID`, `CTR_DATA`, `KEY_SERVER_PUBLIC` with the same key as was used for ECIES level 2 decryption. This data is once more time encrypted by Intermediate Server Application, with the same key from ECIES level 1, and the response is sent to the PowerAuth Client.

Expand Down Expand Up @@ -149,3 +149,9 @@ To describe the steps more precisely, the activation process is performed in fol
1. Record associated with given `ACTIVATION_ID` is now in `ACTIVE` state.

After completing the activation, client must store derived keys and throw away unencrypted device private key and key master secret. Only the derived keys should be stored on the device according to the description in "PowerAuth Key Derivation" chapter.

## Related topics

- [Activation Code Format](Activation-Code.md)
- [Activation Recovery](Activation-Recovery.md)
- [Additional Activation OTP](Additional-Activation-OTP.md)
166 changes: 166 additions & 0 deletions docs/Additional-Activation-OTP.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
# Additional activation OTP

The purpose of additional activation OTP is to help with the user authentication, or with the activation confirmation. The additional OTP can be used either in the early stages of the activation or later when the activation is created and waits for the confirmation in the PENDING_COMMIT state.

We will describe each situation in detail in the separate chapters:

1. [Additional user authentication](#additional-user-authentication)
- [Regular activation with OTP](#regular-activation-with-otp)
- [Custom activation with OTP](#custom-activation-with-otp)
2. [Activation confirmation](#activation-confirmation)
- [Confirm regular activation with OTP](#confirm-regular-activation-with-otp)
- [Confirm custom activation with OTP](#confirm-custom-activation-with-otp)
- [Confirm activation recovery with OTP](#confirm-activation-recovery-with-otp)


> Notes:
> 1. This part of the documentation describes in detail how usage of additional activation OTP changes the activation process. So, before you start, you should be familiar with actors and processes defined for the [regular activation](Activation.md).
## Additional user authentication

In this common scenario, it's expected that the PowerAuth activation is not yet created so that the additional activation OTP can be used in the time of the activation creation as additional user authentication.

### Regular activation with OTP

1. User is authenticated in Master Front-End Application and initiates the activation creation process:

1. Master Front-End Application generates random activation OTP.
1. Master Front-End Application then asks PowerAuth server to create an activation, with using this OTP ([`initActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-initactivation) method, OTP validation set to ON_KEY_EXCHANGE).
1. Master Front-End Application then displays QR code, containing an activation code.
1. At the same time, Master Front-End Application initiates the delivery of activation OTP. It's recommended to deliver such code via a dedicated out-of-band channel, for example, via SMS.

1. In the mobile application:

1. The user scans QR code or retypes the activation code manually.
1. The user waits for OTP delivery via the out-of-band channel.
1. The user retypes OTP to the mobile application.
1. Mobile application then initializes the activation, using activation code and OTP.

1. Intermediate Server Application receives activation with activation code and OTP:

1. The activation code and OTP are verified by the PowerAuth server in the [`prepareActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-prepareactivation) method.
1. If the method call succeeds, the activation is set to the ACTIVE state. There's no need to wait for the confirmation.
1. In case that received OTP is wrong, the user has a limited number of retry attempts. The activation will be removed after too many failures.

1. The mobile application receives the response from the server and completes the activation on the mobile side.


### Custom activation with OTP

There are multiple ways how to implement custom activation with an additional authentication OTP so that we will discuss only one particular case. What they have all common and what you need to know is that OTP is, in this case, not verified by PowerAuth Server. It's more practical to validate it before the actual activation creation.

1. Let's say that the user is authenticated in Master Front-End Application (with username and password) and initiates the activation creation process:

1. Master Front-End Application generates random activation OTP and keeps it temporarily in the database.
1. At the same time, Master Front-End Application initiates the delivery of activation OTP. It's recommended to deliver such code via a dedicated out-of-band channel, for example, via SMS.
1. Master Front-End Application instructs the user to start the mobile application and type the username, password, and OTP to the mobile app.

1. In the mobile application:

1. The user enters username and password.
1. The user waits for OTP delivery via the out-of-band channel.
1. The user retypes OTP.
1. Mobile application then initializes the custom activation with provided username, password, and OTP.

1. Intermediate Server Application receives a custom activation request, with username, password, and OTP:

1. The username, password, and OTP is verified by the Intermediate Server Application.
1. If everything's right, then Intermediate Server Application creates activation by calling [`createActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-createactivation). The activation state can be set to ACTIVE.

1. The mobile application receives the response from the server and completes the activation on the mobile side.



## Activation confirmation

In this common scenario, an additional activation OTP helps with the final activation confirmation, so the OTP is required in the later stages of the activation process (during the commit). In this case, it doesn't matter how the activation process was initiated. You can confirm regular, custom and also recovery activations with the OTP.

### Confirm regular activation with OTP

1. User is authenticated in Master Front-End Application and initiates the activation creation process:

1. Master Front-End Application generates random activation OTP and keeps it temporarily in the database.
1. Master Front-End Application then asks PowerAuth server to create an activation, with using this OTP ([`initActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-initactivation) method, OTP validation set to ON_COMMIT).
1. Master Front-End Application then displays QR code, containing an activation code.

1. In the mobile application:

1. The user scans QR code or retypes the activation code manually.
1. Mobile application then initializes the activation, using activation code.

1. Intermediate Server Application receives a regular activation request, with activation code:

1. The activation code is verified by the PowerAuth server in the [`prepareActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-prepareactivation) method.
1. If the method call succeeds, the activation is set to the PENDING_COMMIT state.
1. At the same time, Intermediate Server Application initiates the delivery of activation OTP. It's recommended to deliver such code via a dedicated out-of-band channel, for example, via SMS.

1. The mobile application receives the response from the server and completes the keys-exchange on the mobile side.

Now it depends whether the user has to retype OTP back to the Master Front-End Application, or the mobile application.

1. For the first case, the implementation is straightforward. Once the user retypes OTP back to Master Front-End Application, the activation can be completed on PowerAuth Server by calling [`commitActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-commitactivation) method. In case the commit fails, the number of commit attempts is limited to the [`MAX_FAILED_ATTEMPTS`](Computing-and-Validating-Signatures.md#constants-and-variables).

2. In case the OTP is retyped in the mobile application, the additional RESTful endpoint has to be implemented on the Intermediate Server Application. We recommend to use our [ECIES encryption](End-To-End-Encryption.md) to protect such endpoint. In case the commit fails, the number of commit attempts is limited to the [`MAX_FAILED_ATTEMPTS`](Computing-and-Validating-Signatures.md#constants-and-variables).

For both cases, it's recommended to generate a new OTP in case that delivery failed (e.g. user did not receive SMS). You can use [`updateActivationOtp`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-updateactivationotp) method to set a new OTP to the PowerAuth Server.

You can also slightly alter this whole sequence, and generate the first OTP later, in the step 3. In this case, you have to use [`updateActivationOtp`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-updateactivationotp) in the same step, to set the OTP.

### Confirm custom activation with OTP

There are multiple ways how to implement custom activation and confirm it with an additional authentication OTP so that we will discuss only one particular case. In this scenario, we don't involve the Master Front-End Application in the process, but we expect that the user has already issued some valid credentials to the system.

1. In the mobile application:

1. The user enters username and password.
1. Mobile application then initializes the custom activation with provided username and password.

1. Intermediate Server Application receives a custom activation request, with username and password:

1. The username and password is verified by the Intermediate Server Application.
1. If everything's right, then Intermediate Server Application creates activation by calling [`createActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-createactivation). The activation must be set to the PENDING_COMMIT state.
1. Intermediate Server Application generates random activation OTP and update the activation record, by calling [`updateActivationOtp`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-updateactivationotp) method.
1. At the same time, Intermediate Server Application initiates the delivery of activation OTP.

1. Back in the mobile application:

1. The mobile application receives the response from the server and completes the key exchange on the mobile side.
1. The user waits for OTP delivery via the out-of-band channel.
1. The user retypes OTP.
1. Mobile application then commits the activation with OTP, by calling a custom RESTful endpoint, protected with our [ECIES encryption](End-To-End-Encryption.md) scheme.

1. Intermediate Server Application then receives the commit request:

1. Decrypts OTP from the request
1. Commits the activation by calling PowerAuth Server's [`commitActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-commitactivation) method.

After the response from the commit is received on the mobile side, the application can check whether the activation's state is ACTIVE.

### Confirm activation recovery with OTP

The confirmation of activation recovery is very similar to custom activation confirmation.

1. In the mobile application:

1. The user enters recovery code and PUK.
1. Mobile application then initializes the recovery activation with provided code and PUK.

1. Intermediate Server Application receives a recovery activation request:

1. The recovery code and PUK is verified by the PowerAuth Server, by calling [`recoveryCodeActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-recoverycodeactivation).
1. Intermediate Server Application generates random activation OTP and update the activation record, by calling [`updateActivationOtp`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-updateactivationotp) method.
1. At the same time, Intermediate Server Application initiates the delivery of activation OTP.

1. Back in the mobile application:

1. The mobile application receives the response from the server and completes the keys-exchange on the mobile side.
1. The user waits for OTP delivery via the out-of-band channel.
1. The user retypes OTP.
1. Mobile application then commits the activation with OTP, by calling a custom RESTful endpoint, protected with our [ECIES encryption](End-To-End-Encryption.md) scheme.

1. Intermediate Server Application then receives the commit request:

1. Decrypts OTP from the request.
1. Commits the activation by calling PowerAuth Server's [`commitActivation`](https://github.com/wultra/powerauth-server/blob/develop/docs/SOAP-Service-Methods.md#method-commitactivation) method.

After the response from the commit is received on the mobile side, the application can check whether the activation's state is ACTIVE.
Loading

0 comments on commit 9e41eab

Please sign in to comment.