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:

• Customizing the push solution for ActivID AS

• Customizing the push solution for ActivID Appliance

• Customizing the push solution for HID Authentication Service

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

Typical Use Case

The mobile application provisions keys as follows:

1. Create an instance of the Device (HIDDeviceFactory.newInstance).

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

• Connection timeout
• Number of connection retries

• Connection delegates for hostname verification and certificate trust verification (an instance of NSURLSessionDelegate)

Note:

• The connection configuration can be changed later using HIDDevice.setConnectionConfiguration or HIDContainer.setConnectionConfiguration.

• The HIDConnectionConfiguration 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
delegate	System

2. Create a key container (HIDDevice.createContainer).

The application passes an instance of HIDContainerInitialization 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 HIDProgressListener.onEventReceived callback will be invoked with a HIDPasswordPromptEvent 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).
Note: If the deviceFriendlyName is not provided, the user-assigned device name will be requested by the SDK. For applications running on Apple iOS 16 (or later), a new user-assigned device name entitlement is required in order to request this information.

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.
3. After the container is created, it is possible to Change Password.

Sample Container Creation on iOS (Objective-C)

// 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.
@interface MyEventListener : NSObject<HIDProgressListener>
@end
@implementation MyEventListener
-( HIDEventResult*)onEventReceived:(NSObject<HIDEvent>*)event {

if ([event isKindOfClass:[HIDPasswordPromptEvent class]]) {
  NSArray* params = [event parameters];
  NSString* type;
  NSString* keyLabel;
  NSString* keyUsage;
        
  for (HIDParameter* p in params)
  {
    if ( [[p key] caseInsensitiveCompare:HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE]==NSOrderedSame)
      type = [p value];
    else if ( [[p key] caseInsensitiveCompare:HID_PARAM_PASSWORD_PROGRESS_EVENT_KEY_LABEL]==NSOrderedSame)
      keyLabel = [p value];
    else if ( [[p key] caseInsensitiveCompare:HID_PARAM_PASSWORD_PROGRESS_EVENT_KEY_USAGE]==NSOrderedSame)
      keyUsage = [p value];
  }

  NSString* text;
  if (type == HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE_CONTAINER)
     text = @"password to protect container";
  else if (type == HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE_KEY)
     text = [NSString stringWithFormat:@"password to protect key (%@, %@)", keyLabel, keyUsage];
  NSLog(@"Event Received: %@", text);

  // password request
  HIDPasswordPromptEvent* pPwdEvent = (HIDPasswordPromptEvent*)event;
  return [[HIDPasswordPromptResult alloc] initWithCode:Continue andPassword:myPassword];
}
else { // progress message
  NSArray* params = [event parameters];
  NSString* message;
  NSString* percent;
  for (HIDParameter* p in params) {
    if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_MESSAGE]==NSOrderedSame)
      message = [p value];
    if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_PERCENT]==NSOrderedSame)
     percent = [p value];
  }
  NSString* text = [NSString stringWithFormat:@"%@ (%@)", message, percent];
  NSLog(@"Event Received: %@", text);
}

return [[HIDEventResult alloc] initWithCode:(Continue)];
@end

…

// The app gets a Device instance with default connection configuration.
NSError* error;
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig withSessionPassword:sessionPwd error:&error];

HIDContainerInitialization* containerInitialization = [[HIDContainerInitialization alloc] init];
// QR code or payload of push notification
containerInitialization.activationCode =  [[NSString alloc] initWithData:scanContent encoding:NSUTF8StringEncoding];
// Identifier given by the push notification system
containerInitialization.pushId = sPushID;

// Container creation 
MyEventListener* listener = [[MyEventListener alloc] init];
id<HIDContainer> pContainer = [pDevice createContainer:config withSessionPassword:sessionPwd withListener:listener error:&error];

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.