Container Creation

View this page for | |

Before being able to sign a transaction or generate an OTP with the HID Approve SDK, the mobile application has to provision its keys.

Typically, provisioning is triggered by the web application by invoking the HID authentication platform. The provisioning data returned by the server is received by the mobile application by scanning a QR code, or entered manually by the end user.

During provisioning, cryptographic keys designed to address the use cases above, are generated and stored securely. These keys are protected against anti-cloning (that is, they cannot be extracted and used outside the mobile device) and can be further protected with a password or fingerprint.

For further details, see:

The HID Approve Security White Paper (available upon request).

Typical Use Case

The mobile application provisions keys as follows:

Create an instance of the Device (DeviceFactory.getDevice).

During this operation, the application provides the SDK with the required server connection configuration (class ConnectionConfiguration):

Connection timeout
Number of connection retries
Connection delegates for hostname verification and certificate trust verification (an instance of javax.net.ssl.X509TrustManager and javax.net.ssl.HostnameVerifier).

Note:

The connection configuration can be changed later using Device.setConnectionConfiguration or Container.setConnectionConfiguration.
The ConnectionConfiguration values are optional.

Important: If the TLS delegates are not provided, the standard platform default handlers will be used for hostname and validation. These object instances should only be given when implementing a custom behavior in the application such as certificate pinning.

The default values are:

Property	Value
timeout	30 sec
retry	0
trustManager	System
hostnameVerifier	System

Create a key container (Device.createContainer).

The application passes an instance of ContainerInitialization to the method with the required data.

In the simplest use case, the following information is required:

Activation code (activationCode) – generated by the HID authentication platform upon customer request (for example, if the end user is using the bank web application to activate a device, the web application requests the server to generate a code).

The application can obtain the code by scanning a QR code, or any other means chosen by the integrator.

If the specified policy used to protect the generated keys requires a password, the passed EventListener.onEventReceived callback will be invoked with a PasswordPromptEvent to request a mandatory password from the application during the activation process.
Push ID (pushId) – device identifier provided by the notification service. This identifier is communicated to the server to allow it to send notifications.

The application can customize:

The device friendly name as displayed in the HID authentication platform (deviceFriendlyName).
The container friendly name that could be displayed by the application (containerFriendlyName).

At the end of provisioning, the device is provisioned with the keys.

Important: The HID Approve SDK implementation requires that all key labels are unique. Otherwise, provisioning will fail.

After the container is created, it is possible to Change Password.

Sample Container Creation on Android

Copy

// The app gets a Device instance with default connection configuration.
// context is specific to the platform. On Android, it is an instance of android.content.Context.
Device device = DeviceFactory.getDevice(context, new ConnectionConfiguration());

ContainerInitialization containerInitialization =  new ContainerInitialization();
// QR code or payload of push notification
containerInitialization.activationCode = scanContent;
// Identifier given by the push notification system
containerInitialization.pushId = pushId;

// The EventListener callback will be invoked for the app to provide a password to protect keys,
// in case the server enforces protection by a password. The password generation is app responsibility.
class MyEventListener implements EventListener {
public EventResult onEventReceived(Event event) {
if (event instanceof PasswordPromptEvent) {
// Continue: operation can continue
// Cancel: operation is cancelled by the user.
// Abort: operation is aborted by the app
PasswordPromptResult result = new PasswordPromptResult(EventResult.Code.Continue);
result.setPassword(myPassword)
return result;
}
else {// progress message
Parameter[] params = event.getParameters();
char[] message = null;
char[] percent = null;
for (int i = 0; i < params.length; i++) {
if (SDKConstants.PARAM_SYNCEVENT_MESSAGE.equalsIgnoreCase(params[i].getId()))
message = params[i].getValue();
if (SDKConstants.PARAM_SYNCEVENT_PERCENT.equalsIgnoreCase(params[i].getId()))
percent = params[i].getValue();
}
String text = new String(message) + " (" + new String(percent) + ")";
Log.d(LOG_TAG, "Event Received: " + text);
}
return null;
}
};

// Container creation 
Container container = device.createContainer(containerInitialization, sessionPassword, new MyEventListener());

Degraded Use Case

If the application is unable to get an activation code (for example, the device does not have a camera to scan the QR code), then it can prompt the end user to enter the required information (for example, provided by the HID authentication platform, and displayed in the customer web application):

User identifier (userId) – the user code in the HID authentication platform.
Invite code (inviteCode) – this is a short code provided by the server to ensure the Container creation is genuine.
Server URL (serverUrl) – the HID authentication platform short URL in the format <host>[:<port>]/<domain>.

Container Replacement

A container is uniquely identified by the user identifier, the server URL and the server domain used to create it.

If a container exists, and you provision a new one with the same user identifier, server URL and server domain, the previous one will be deleted.

Otherwise a new container will be provisioned for the user.