Workflow for the activation process with the DSAPP SDK

The activation process with the DSAPP SDK includes the generation and transmission of the user password and the generation and processing of the activation data. Overview of the activation process with the DSAPP SDK illustrates this activation workflow with the DSAPP SDK. For a detailed description of the workflow steps and a list of function parameters for the activation process, see Workflow steps.

Workflow steps

The following overview describes the single steps of the activation workflow with the DSAPP SDK and lists the input and output parameters for each function.

Activation workflow

1. The provisioning server must call the server component of the DSAPP SDK to generate a user password (GenerateSRPUserPassword).

   GenerateSRPUserPassword parameters

   Input/output parameters	Description
   Input	The parameters for the user password generation, like the password length or if a checksum is required. For more information, refer to the technical documentation delivered in the DSAPP SDK package.
   Input	The user identity; must be a unique value identifying the end user.
   Input	To set only custom characters for password generation, the allowedCharacters parameter must be used. It is a case-sensitive string and should include at least 10 characters from the 8-bit ASCII range. This parameter forces using only predefined characters for password generation; it can be used to avoid spelling errors by using similar-looking symbols.
   Output	The generated user password; must be transmitted to the end user without using the network.
   Output	The password verifier; must be kept on the server-side for later use.
   Output	A generated salt; must be kept on the server-side for later use.

   In C++, the method to set the property for using allowed characters is GenerateSRPUserPasswordWithAllowedCharacters.

   Recommended minimal length for user password:

   • Numeric (0-9): 6 characters
   • Alphanumeric (0-9, A-Z): 4 characters
   • Case-sensitive alphanumeric (0-9, a-z, A-Z): 4 characters

   The user password is highly sensitive data which must only be shared between the client and the server using a channel that is not on the same network connection used to transmit activation data (e.g. SMS, sealed letter).

   We strongly recommend having one user password per activation session and implementing an expiration mechanism for the user password storage in the database.

2. The provisioning server must store the password verifier and the salt in a database.

3. The provisioning server must transmit the user password to the end user without using the network (e.g. by sending an SMS or a letter through the mail).

   The user identity must also be transmitted to the end user, but this can be transmitted via the network or an alternative channel.

   When working with OneSpan Authentication Server, the user identity that must be transmitted to the client is the registration identifier returned by the DSAPPSRPRegister SOAP call.

4. The end user must enter the user password and the user identifier in the client application.
5. The client application can call the client component of the DSAPP SDK to validate the checksum contained in the user password, if applicable (ValidateSRPUserPasswordChecksum).

6. The client application must do a network request to the provisioning server to initialize the activation process through the network.

   The user identity can be transmitted for identification.

7. The provisioning server must retrieve the password verifier and the salt from the database.

8. The provisioning server must call the server component of the DSAPP SDK to generate the server ephemeral key (GenerateSRPServerEphemeralKey).

   GenerateSRPServerEphemeralKey parameters

   Input/output parameters	Description
   Input	The password verifier; this parameter must be provided mandatorily.
   Output	The server ephemeral public key; will be transmitted to the client application through the network.
   Output	The server ephemeral private key; must be kept on the server-side for later use.

   The server ephemeral keys must be unique for each activation process.

9. The provisioning server must store the server ephemeral public and private keys in a database.
10. The provisioning server must respond to the network request by providing the server ephemeral public key and the salt to the client application.

11. The client application must call the client component of the DSAPP SDK to generate the client ephemeral key (GenerateSRPClientEphemeralKey).

    GenerateSRPClientEphemeralKey parameters

    Input/output parameters	Description
    Output	The client ephemeral public key; will be transmitted to the server component of the DSAPP SDK through the network.
    Output	The client ephemeral private key; must be kept on client-side for later use.

12. The client application must call the client component of DSAPP SDK to generate the session key (GenerateSRPSessionKey).

    GenerateSRPSessionKey parameters

    Input/output parameters	Description
    Input	The client ephemeral public key and the client ephemeral private key previously generated on the client-side.
    Input	The server ephemeral public key and the salt previously generated by the provisioning server and transmitted through the network.
    Input	The user password and the user identity entered by the end user.
    Output	The generated session key; must be kept on the client-side. This session key will be used later to decrypt the activation data.
    Output	The client evidence message; must be sent to the provisioning server through the network. This message will be used to validate the key negotiation process.

    In the next steps, the server component of the DSAPP SDK will generate the same session key.

13. The client application must do a network request to the provisioning server for the activation data to be securely transmitted through the network:

    • The client ephemeral public key and the client evidence message must be transmitted.
    • The user identity can be transmitted for identification.

14. The provisioning server must retrieve the following data from the database:

    • Server ephemeral public key
    • Server ephemeral private key
    • Password verifier
    • Salt

15. The provisioning server must call the server component of the DSAPP SDK to validate the client evidence message and to generate the session key (GenerateSRPSessionKey).

    GenerateSRPSessionKey parameters

    Input/output parameters	Description
    Input	The server ephemeral public key, the server ephemeral private key, the password verifier, and the salt previously generated on the server-side and retrieved from the database.
    Input	The client ephemeral public key and the client evidence message previously generated by the client and transmitted through the network.
    Input	The user identity sent either by the client application or retrieved from the database, depending on the integration use case.
    Output	The generated session key; must be kept on the server-side. This session key will be used later to encrypt the activation data.
    Output	The server evidence message; must be returned to the client application through the network. This message will be used to validate the key negotiation process.

16. The provisioning server must call Authentication Server Framework to generate the activation data which will be securely transmitted to the client application through the network.

    In multi-device activation mode, the activation data will be the license activation message (i.e. Activation Message 1 for the Authentication Server Framework API).

    In standard activation mode, the activation data will be the XFAD and the XERC.

17. The provisioning server must call the server component of the DSAPP SDK to encrypt the activation data (EncryptSRPData).

    EncryptSRPData parameters

    Input/output parameters	Description
    Input	The activation data previously generated; must be encrypted for a secure transmission.
    Input	The session key previously generated; the activation data will be encrypted using this key.
    Output	The encrypted activation data; must be returned to the client application through the network.
    Output	The encryption counter which has been used during the encryption process; must be returned to the client application.
    Output	The message authentication code (MAC) which is used to check that the encrypted activation data has not been altered; must be returned to the client application.

    If a set of activation data must be encrypted (e.g. XFAD and XERC), several sets of encryption counters and MACs must be returned to the client application, i.e. one set per activation data (e.g. one encryption counter and one MAC for XFAD, and another encryption counter and MAC for the XERC).

18. The provisioning server must respond to the network request by providing the server evidence message, the encrypted activation data, the encryption counter(s), and the MAC(s).

19. The client application must call the client component of the DSAPP SDK to validate the server evidence message (VerifySRPServerEvidenceMessage).

    VerifySRPServerEvidenceMessage parameters

    Input/output parameters	Description
    Input	The client ephemeral public key, the client evidence message, and the session key previously generated by the client application.
    Input	The server evidence message previously generated by the provisioning server and transmitted through the network.

20. The client application must call the client component of DSAPP SDK to decrypt the activation message (DecryptSRPData).

    DecryptSRPData parameters

    Input/output parameters	Description
    Input	The session key previously generated by the client application.
    Input	The encrypted activation data, the encryption counter, and the MAC generated by the provisioning server and transmitted through the network.
    Output	The decrypted activation data, ready to be used for the activation process.

21. The client application must call the Digipass SDK to process the activation data and to perform the activation.
22. The client application must call the Digipass SDK to perform a post-activation step. This step serves as validation that the client application has been properly activated. This must be done by generating an OTP or the signature of an activation message.
23. The client application must do a network request to the provisioning server to transfer the generated OTP or signature to the provisioning server.
24. The provisioning server must call Authentication Server Framework to validate the generated OTP or signature.

25. The provisioning server must build a network response (e.g. JSON string) which contains the validation result, and it must call the server component of the DSAPP SDK to sign the content of the network response (GenerateSRPMAC).

    GenerateSRPMAC parameters

    Input/output parameters	Description
    Input	The session key previously generated; the content of the network response will be signed using this key.
    Input	The content of the network response; must be signed for a secure transmission (non-alteration).
    Output	The message authentication code (MAC) which is used to check that the content of the network response has not been altered; must be returned to the client application.

26. The provisioning server must respond to the network request by providing the content of the network response and the MAC.

27. The client application must call the client component of the DSAPP SDK to validate the content of the network response (VerifySRPMAC).

    VerifySRPMAC parameters

    Input/output parameters	Description
    Input	The session key previously generated by the client application.
    Input	The content of the network response.
    Input	The message authentication code (MAC) which is used to check that the content of the network response has not been altered.

    Once the activation process is finished (successfully or not) the activation data stored in the database must be removed so that the activation data will be regenerated for the next activation process.

    An expiration mechanism should be implemented to remove the activation data stored in the database if they have not been used after a specific period of time.