Standard secret exchange encryption

Updated on 23 Oct 2024
5 Minutes to read

Share
Dark
Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Mobile Authenticator Studio app can be configured to use the standard provisioning protocol to exchange the authenticator secret with the provisioning server during online activation. In this case, the authenticator secret will be encrypted with the activation password and a nonce generated by the Mobile Authenticator Studio app.

Online activation with Standard Secret Exchange Encryption (overview)

If the Mobile Authenticator Studio app is configured to use the post-activation process, it will submit the registration identifier and an OTP in clear text.

Online activation with Standard Secret Exchange Encryption and post-activ- ation (overview)

This provisioning protocol version is described for backwards-compatibility with back-end systems supporting Mobile Authenticator Studio prior to 4.0. We strongly recommend using the advanced provisioning protocol with Mobile Authenticator Studio 4.0 and later.

Registration request

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

<ActivationData useActivationPassword="true" checksumOnActivationPassword="true">
<OnlineActivationData inputType="manual"advanced="false" useRegistrationIdentifier="true"useAuthorizationCode="true" checksumOnAuthorizationCode="true">
<URL method="GET" value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE?registrationIdentifier=%_RegistrationIdentifier_%&authorizationCode=%_AuthorizationCode_%&publicKey=%_PublicKey_% &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 Studio Customization Guide.

Parameter name	Description
Registration request parameters (Standard Secret Exchange Encryption)
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
Nonce	The random number generated by the Mobile Authenticator Studio app to diversify the activation data encryption on the server-side. Format: String of 64 hexadecimal 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
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>
<!ELEMENT Activation EMPTY>
<!ATTLIST Activation xfad CDATA #REQUIRED>
<!ATTLIST Activation xerc CDATA #IMPLIED>
<!ATTLIST Activation userid CDATA #IMPLIED>
<!ATTLIST Activation challenge CDATA #IMPLIED>

Example

<?xml version="1.0"encoding="UTF-8"?>
<DP4Mobile retCode="0"message="Operation Successful" serverTime="1271862050" >
<Activation xfad="3806564453974A59302DD7..." xerc="55420849628260..."userid="myusername" challenge="123456" />
</DP4Mobile>

Attribute name	Description
Registration response attributes (Standard Secret Exchange Encryption)
retCode	Required. The return code associated with the 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 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. XFAD_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.
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.

Post-activation request

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

<PostActivation binding="false"cryptoAppIndex="1">
<OnlinePostActivation destroyOnFailure="true" displayMessageOnSuccess="true">
<URL method="GET" value="http://MY_DOMAIN_NAME/MY_WEB_SERVICE?registrationIdentifier=%_RegistrationIdentifier_%&otp=%_OTP_%&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 operate the following authentication modes:

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 (Standard Secret Exchange Encryption)
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
UserIdentifier	The extra user identifier that the user may have entered or received in the registration response. Format: Alphanumeric string, limited to 40 characters
OTP	A one-time password (OTP) generated by the cryptographic application defined by the cryptoAppIndex attribute of the PostActivation element.
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. 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

<?xml version="1.0"encoding="UTF-8"?>
<DP4Mobile retCode="0"message="Operation Successful" />

Parameter name	Description
Post-activation response attributes (Standard Secret Exchange Encryption)
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.

Was this article helpful?

What's Next

Integrate activation data input from an image

Table of contents

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