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 callback to handle server certificate validation (for further information, go to the .NET 8.0 System API documentation).

Note:

The connection configuration can be changed later using IDevice.ConnectionConfiguration or IContainer.ConnectionConfiguration.
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
HttpFilter	System

Create a key container (IDevice.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 IHIDProgress instance will be invoked on the RequestPassword method to get the 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 Windows (C#)

Copy

 // Get Device instance with default connection configuration
            var connectionConfiguration = new ConnectionConfiguration();

            IDevice device = await DeviceFactory.GetDevice(connectionConfiguration);

            // ContainerInitialization structure contains configuration information for the new container
            var containerInitialization = new ContainerInitialization();
            // QR code or payload of push notification
            containerInitialization.ActivationCode = activationCode;
 
            ProgresListener progressEvent = new ProgresListener();

            IContainer container;
            try
            {        
                // Container creation
                container = await device.CreateContainer(containerInitialization, null, progressEvent);
            }
            catch (Exception ex)
            {
                Debug.WriteLine("container creation failed : " + ex.Message + ex.ToString());
                throw;
            }
            finally
            {
                containerInitialization.Reset();
            }

Copy

private class ProgresListener : IHIDProgress<IProgressEvent>
        {
            public Task<PasswordPromptResult> RequestPassword(IPasswordPromptEvent value)
            {
                IPasswordPromptEvent passwordPromptEvent = (IPasswordPromptEvent)value;
                Debug.WriteLine("We are asked for password.");

                PasswordPromptResult result = new PasswordPromptResult();
                result.Pwd = "HIDSDK@12".ToCharArray();
                result.Code = EventCode.Continue;
                return Task.FromResult(result);
            }

            public void Report(IProgressEvent value)
            {
                Debug.WriteLine("Report Type : " + value.GetType());
                Debug.WriteLine("Report Id : " + value.Id);
                foreach (var item in value.Parameters)
                {
                    Debug.WriteLine("Report Name : " + item.Name);
                    Debug.WriteLine("Report Value : " + item.Value);
                }               
            }
        }

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.