Advanced Provisioning Protocol

23 Oct 2024
6 Minutes à lire

Partager
Sombre
Lumière
PDF

Advanced Provisioning Protocol

Mis à jour le 23 Oct 2024
6 Minutes à lire

Partager
Sombre
Lumière
PDF

The content is currently unavailable in French. You are viewing the default English version.

Résumé de l’article

Avez-vous trouvé ce résumé utile ?

Merci pour vos commentaires

The Mobile Authenticator Studio app can be configured to use the advanced provisioning protocol to exchange the authenticator secret with the provisioning server during online activation. In this case, the authenticator secret will be encrypted with a session key derived from a shared Diffie-Hellman secret.

Both the Mobile Authenticator Studio app and the back-end server generate an elliptic curve Diffie-Hellman (ECDH) key pair based on the NIST P-256 curve and exchange their public keys. Each party uses the other party’s public key to create a shared Diffie-Hellman secret, and uses it to encrypt the authenticator activation data. The usage of an activation password ensures the authenticity of the exchanged public keys.

To implement this protocol on the server, the Digipass Software Advanced Provisioning Protocol (DSAPP) SDK version 4.4 needs to be integrated.

The Advanced Provisioning Protocol has been optimized between Mobile Authenticator Studio 4.4 and Mobile Authenticator Studio 4.1. Although we recommend using the new version of the protocol, it is possible to continue using the previous one. For more information about backwards-compatibility, refer to the Mobile Authenticator Studio Customization Guide.

If the provisioning server is OneSpan Authentication Server, the AdvancedActivationV1 element must have the enabled attribute set to true in the Mobile Authenticator Studio XML configuration file.

Online activation with Advanced Provisioning Protocol (overview)

If the Mobile Authenticator Studio app is configured to use the post-activation process, it will submit the following:

registration identifier
encrypted server nonce
initial vector
OTP

Online activation with DSAPP and post-activation (overview)

Registration request

The request sent by Mobile Authenticator Studio is configured in the OnlineActivationData section of the configuration file:

<ActivationDatauseActivationPassword="true"checksumOnActivationPassword="true">
<OnlineActivationDatainputType="manual"advanced="true"useRegistrationIdentifier="true"useAuthorizationCode="true"checksumOnAuthorizationCode="true">
<URLmethod="GET"value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE?registrationIdentifier=%_RegistrationIdentifier_%&authorizationCode=%_AuthorizationCode_%&publicKey=%_PublicKey_%&initialVector=%_InitialVector_%&deviceIdentifier=%_DeviceIdentifier_%"&rootingStatus=%_RootingStatus_%&version=%_Version_%" />
...
</OnlineActivationData>
</ActivationData>

The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator StudioCustomization Guide.

Parameter name	Description
Registration request parameters (Advanced Provisioning Protocol)
RegistrationIdentifier	The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. It will be used only if the useRegistrationIdentifier attribute of the OnlineActivation element is set to true. Format: Alphanumeric string, limited to 40 characters
AuthorizationCode	The second factor to authorize the server to process the provisioning request if the registration identifier is predictable. It will be used only if the useAuthorizationCode attribute of the OnlineActivation element is set to true. Format: Alphanumeric string, limited to 40 characters
PublicKey	The public key of the device key pair. This key will be used by the DSAPP library to negotiate the session key to encrypt the XFAD. It can be encrypted using the activation password. The device nonce is concatenated to the public key value. Both data sets are sent together in a 136–hexadecimal-character string.
InitialVector	A randomly generated initial vector. It is used to diversify the public key encryption. Format: String of 32 hexadecimal characters
Version	The version of the application binary as defined when configuring the application.
DeviceIdentifier	The device-unique identifier. Format: String of 64 hexadecimal characters
RootingStatus	The status indicating whether the device is rooted, either true or false according to the device state.

Registration response

The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:

<!ELEMENT DP4Mobile (Activation?,PendingTransactions?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>
<!ATTLIST DP4Mobile confirmationCode CDATA #IMPLIED>
<!ELEMENT Activation EMPTY>
<!ATTLIST Activation xfad CDATA #REQUIRED>
<!ATTLIST Activation xerc CDATA #IMPLIED>
<!ATTLIST Activation userId CDATA #IMPLIED>
<!ATTLIST Activation challenge CDATA #IMPLIED>
<!ATTLIST Activation serverPublicKey CDATA #REQUIRED>
<!ATTLIST Activation initialVector CDATA #REQUIRED>
<!ATTLIST Activation nonces CDATA #REQUIRED>

Example

<?xmlversion="1.0"encoding="UTF-8"?>
<DP4MobileretCode="0"message="Operation Successful"serverTime="1271862050" >
<Activationxfad="3806564453974A59302DD7..."xerc="55420849628260..."userId="myusername"challenge="123456"serverPublicKey="5431..."initialVector="98752..."nonces="24421..." />
</DP4Mobile>

Attribute name	Description
Registration response attributes (Advanced Provisioning Protocol)
retCode	Required. The return code associated with the registration request. 0 means success, any other value will cause the message attribute value to be displayed and the activation process to stop.
message	Required. The return message associated with the activation request. This value will be displayed by the application if the return code is not 0.
serverTime	Optional. This is the current server GMT time. This value will be used by the application to silently set the drift between device and server time to keep the application synchronized.
xfad	Required. The authenticator secret encrypted with the nonce and the activation password shared between the server and the user. Format: String of hexadecimal characters The length of the XFAD can be deduced from the following formula: XFAD_length = 2 * (FAD_length + (16 – FAD_length mod 16)) where: FAD_length = SV_length + SN_length + AC_length
xerc	Optional. The authenticator cryptographic application counters encrypted with the nonce and the activation password shared between the server and the user. Format: String of hexadecimal characters The length of the XERC can be deduced from the following formula: XERC_length = 2 * (ERC_length + (16 – ERC_length mod 16)) where XERC_length is up to 91.
userId	Optional. An extra user identifier. If it is returned by the server, it will be stored in the application storage and can be re-used in future HTTP requests by the application. Format: Alphanumeric string, limited to 40 characters
challenge	The challenge used in the post-activation process. If the cryptographic application used for the post-activation process is Challenge/Response, this attribute is mandatory. Otherwise, it is optional. Format: Numeric string, up to 16 characters
serverPublickey	The server public key generated by the DSAPP library. It can be encrypted with the activation password. Format: String of 128 hexadecimal characters
nonces	The device and the server nonces concatenated and encrypted by the activation password as returned by the DSAPP library. Format: String of 32 hexadecimal characters
initialVector	An initial vector diversifying the public key encryption. Format: String of 32 hexadecimal characters

Post-activation request

The request sent by Mobile Authenticator Studio is configured in the PostActivation section of the configuration file:

<PostActivationbinding="false"cryptoAppIndex="1">
<OnlinePostActivationdestroyOnFailure="true"displayMessageOnSuccess="true">
<URLmethod="GET"value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE?registrationIdentifier=%_RegistrationIdentifier_%&otp=%_OTP_%&nonce=%_Nonce_%&initialVector=%_InitialVector_%&deviceIdentifier=%_DeviceIdentifier_%&version=%_Version_%" />
</OnlinePostActivation>
...
</PostActivation>

The URL can use the HTTP POST or GET methods. For more information about URL customization, refer to the Mobile Authenticator Studio Customization Guide.

The cryptographic application used to generate the authenticator response can have the following authentication mode:

RO (Response-Only). To verify the authenticator response generated by an application with RO as the authentication mode, the AAL2VerifyPassword function of the Authentication Server Framework API must be used with an empty challenge.
CR (Challenge/Response). To use a Challenge/Response cryptographic application, Mobile Authenticator Studio must receive a challenge during its activation scenario. To verify the authenticator response, the AAL2VerifyPassword function of the Authentication Server Framework API must be used with the challenge provided during the activation scenario.
MM (multi-mode). The multi-mode applications are used as Response-Only application.

Parameter name	Description
Post-activation request parameters (Advanced Provisioning Protocol)
RegistrationIdentifier	The identifier provided by the user via the online activation screen of the Mobile Authenticator Studio app. Format: Alphanumeric string, limited to 40 characters
SerialNumber	The authenticator serial number. Format: Alphanumeric string of 10 characters
UserIdentifier	The extra user identifier that the user may have entered or received in the registration response. Format: Alphanumeric string, limited to 40 characters
Nonce	The server nonce returned for validation by the server. It is encrypted with the session key. Format: String of 32 hexadecimal characters
InitialVector	A randomly generated initial vector used to diversify the server nonce encryption. Format: String of 32 hexadecimal characters
OTP	A one-time password (OTP) generated by the cryptographic application defined by the cryptoAppIndex attribute of the PostActivation element. The length and the format of the OTP is defined in the static vector received in the XFAD.
DerivationCode	The OTP and device-specific information. It must be used to bind the authenticator BLOB on the server to the authenticator instance on the client. For more information about the derivation code, refer to the Mobile Authenticator Studio Product Guide and the OneSpan Authentication Server Framework Product Guide. The length of the derivation code is between OTP_length +1 and OTP_length + 10.
Version	The version of the application binary as defined when configuring the application.
DeviceIdentifier	The device-unique identifier. format: String of 64 hexadecimal characters
RootingStatus	The status indicating whether the device is rooted, either true or false according to the device state.

Post-activation response

The response expected by Mobile Authenticator Studio must be formatted as described in the DTD:

<!ELEMENT DP4Mobile (Activation?,PendingTransactions?)>
<!ATTLIST DP4Mobile retCode CDATA #REQUIRED>
<!ATTLIST DP4Mobile message CDATA #REQUIRED>
<!ATTLIST DP4Mobile serverTime CDATA #IMPLIED>

Example

<?xmlversion="1.0"encoding="UTF-8"?>
<DP4MobileretCode="0"message="Operation Successful" />

Attribute name	Description
Post-activation response attributes (Advanced Provisioning Protocol)
retCode	Required. The return code associated with the post-activation request. 0 means success, any other value will cause the message attribute value to be displayed and the activation process to stop.
message	Required. The return message associated with the post-activation request. This value will be displayed by the application if the return code is not 0 or if the displayMessageOnSuccess attribute of the OnlinePostActivation element is set to true.
serverTime	Optional. This is the current server GMT time. This value will be used by the application to silently set the drift between device and server time to keep the application synchronized.

Cet article vous a-t-il été utile ?

What's Next

Standard secret exchange encryption

Table des matières

Registration request
Registration response
Post-activation request
Post-activation response