Container Key Renewal

View this page for | |

The operation (HIDContainer.renew) can be used to renew the container keys without having to perform activation again or interrupting an existing service in the case of expiration. All keys are renewed during this operation.

Key Renewal Trigger

The decision to trigger the keys renewal can be taken by the application based on the following information:

HIDContainer.isRenewable() will return a boolean that states if the container can be renewed. A container can be renewed if the:

  • HID authentication platform supports this operation
  • “Transport Key for Mobile Service communications” key (CT_SMK4 credential type) is still valid
  • HIDContainer.getRenewalDate() will return the date by which the keys must be renewed for container to be fully functional (support might be limited or not working after this date)

    This date corresponds to the shortest key from this container

  • The limit date for key renewal is the expiration date of the “Transport Key for Mobile Service communications” key (CT_SMK4 credential type)

    After this date, key renewal is no longer possible

It is recommended that the Key Renewal operation happens before the RenewalDate.

For further details, see:

ActivID AS Credential Type Parameters

ActivID Appliance Credential Type Parameters

HID Authentication Service Credential Parameters

Key Renewal Processing and Result

  • As with container provisioning, key renewal is a time-consuming operation.
  • After key renewal, the container remains the same, but all previous keys have been deleted, and new keys have been created for this container just as if this was a brand-new container (created using the current HID authentication platform configuration).

  • A container key renewal operation can be used to apply an update to the protection policy configuration used for the initial container creation (for example, enabling biometrics or updating password complexity requirements). However, these changes will not be enforced for a user's current password and will only be applied after an explicit call to change password. An integrator can choose to wait until password expiration or to trigger the change password immediately after the key renewal operation depending on the desired workflow.

  • The original creation date of the container can be retrieved using HIDContainer.getOriginalCreationDate()

  • For security (non-repudiation), a password-protected container is required to provide the password to trigger the renewal operation:

    • This can be done by populating the HIDContainerRenewal structure or provided via the HIDProgressListener callback

    • For biometric-enabled containers, the end user will be prompted by the system for a standard biometric authentication

    • For device-protected policies, the password is not required

Copy 
do{
        // check if container is renewable
        // we assume session key is not password protected (password nil)
        try myContainer?.isRenewable(nil)
        NSLog("container is renewable")
        
        // Container Renewal configuration
        let config = HIDContainerRenewal()
        config.pushId = sPushID
        
        // To renew the container, we need the password which protects it.
        // You can either bypass the password prompt by filling the password through the containerRenewal, or by using the PasswordPromptEvent
        // Biometric-enabled containers will automatically prompt
        config.password = self.passwordPrompt()
        
        // The listener works the same way as the createContainer.
        let myListener = MyEventListener()
        
        // We can proceed to the renew
        // we assume session key is not password protected (password nil)
        try myContainer?.renew(config, withSessionPassword: nil, with: myListener)
        
        NSLog("container has been renewed")
    }
    catch let error as NSError{
        // HIDInternal - will be thrown if the container is not renewable
        NSLog("Failed to renew container: %@",error.localizedDescription);
    }
Copy 
// check if container is renewable
    // we assume session key is not password protected (password nil)
    NSError* error;
    Boolean isRenewable = [myContainer isRenewable:nil error:&error];
    if (error != nil) {
        NSLog(@"container renewable check failed: %@ (%ld)", [error userInfo], (long)[error code]);
    }
    else {
        
        if (isRenewable) {
            NSLog(@"container is renewable");
            
            // Container Renewal configuration
            HIDContainerRenewal* config = [[HIDContainerRenewal alloc] init];
            config.pushId = myPushId;
            
            // To renew the container, we need the password which protects it.
            // you can either bypass the password prompt by filling the password through the containerRenewal, or by using the PasswordPromptEvent
            // Biometric-enabled containers will automatically prompt
            [config setPassword:myPassword];
            
            // The listener works the same way as the createContainer.
            MyEventListener* listener = [[MyEventListener alloc] init];
            
            // We can proceed to the renew
            // we assume session key is not password protected (password nil)
            [myContainer renew:config withSessionPassword:nil withListener:myListener error:&error];
            if (error != nil) {
                NSLog(@"container renew failed: %@ (%ld)", [error userInfo], (long)[error code]);
            } else {
                NSLog(@"container has been renewed")
            }
        }
        else {
            NSLog(@"container cannot be renewed");
        }
    }