Updates to the HID Approve SDK for Apple iOS/macOS

This page details the design changes made in the new HID® Approve™ SDK for Apple® iOS® and macOS®.

Please refer to the code examples provided below that illustrate the code changes, as well as Add Functions to your App.

What's New in Version 6.0 from 5.13

HIDDevice.h

DEPRECATED deleteContainer

NEW deleteContainer method with reason

HIDDeviceFactory

UPDATED getDevice will raise HIDLostCredentials error if critical key information is absent

HIDContainer.h

NEW generateAuthenticationRequest method

UPDATED getProperty remove support for deprecated HID_PROPERTY_TXURI

UPDATED setProperty remove support for deprecated HID_PROPERTY_TXURI

UPDATED updateDeviceInfo remove support for deprecated DEVICE_INFO_NAME

UPDATED findKeys will return single HIDKeyPair object for asymmetric keys

HIDTransaction.h

NEW enumeration HIDCancelationReasonCode

NEW cancel method

NEW isCancelable method

NEW getRequestId method

NEW getIdToken method

HIDProtectionPolicy.h

NEW disableBioAuthentication method on HIDBioPasswordPolicy

HIDConstants.h

REMOVED deprecated string constant HID_PROPERTY_TXURI

HIDErrors.h

NEW enumeration value HIDTransactionCanceled (1002)

NEW enumeration value HIDTransactionSigned (1003)

HIDKeyPair.h

NEW class

Exceptions

UPDATED HIDServerVersion (301) has been replaced by HIDServerUnsupportedOperation (304)

UPDATED HIDServerProtocol (302) has been replaced by HIDServerOperationFailed (305)

What's New in Version 5.13 from 5.12

HIDDeviceFactory

NEW HIDDeviceFactory getDevice method replaces HIDDeviceFactory newInstance

UPDATED HIDDeviceFactory reset method reviewed to be more robust

DEPRECATED HIDDeviceFactory newInstance

HIDTransactionInfo

REMOVED deprecated class (use HIDServerActionInfo)

Several deprecated APIs (from SDK 5.5 and SDK 5.7.1) have been removed

What's New in Version 5.12 from 5.11

None - this is release is to provide important security updates and third-party component updates.

What's New in Version 5.11 from 5.10

SDK Additions and New Features

HIDDevice.h

UPDATED retrieveActionInfo method to add HIDInexplicitContainer exception

NEWretrieveActionInfo(char[] actionId, char[] userId) method with a different signature

What's New in Version 5.10 from 5.9

SDK Additions and New Features

HIDConstants.h

NEW HID_PARAM_TX_MOBILE_CONTEXT constant

HIDTransaction.h

UPDATED setStatus method supports the HID_PARAM_TX_MOBILE_CONTEXT parameter

What's New in Version 5.9 from 5.7.1

SDK Updates

Sequential passwords are prohibited unless explicitly authorized with password policy parameters

SDK Additions and New Features

HIDConstants.h

NEW HID_DEVICE_INFO_ISROOTED constant

NEW HID_PROPERTY_ORIGINAL_CREATION_DATE constant

HIDContainer.h

NEW getOriginalCreationDate accessor method

-(NSDate*)getOriginalCreationDate:(NSError**)error;

HIDProtectionPolicy.h

NEW isSequenceAllowed property

NEW HIDBioAuthenticationStateInvalidKey enum value for HIDBioAuthenticationState

HIDServerAction.h

NEW getPayload accessor method

- (NSString*)getPayload:(NSError**)error;

Bitcode Support

Bitcode support will be removed from SDK in a future version.

For further information regarding bitcode deprecation, refer to item "86118779" in the Apple XCode 14 Release Notes.

What's New in Version 5.7.1 from 5.5

SDK Updates

Migration to 5.7.1 from versions 3.0 and 4.0 is no longer supported.

SDK Additions and New Features

HIDDevice.h

REMOVED retrieveTransaction deprecated method

NEW retrieveActionInfo method

- (id<HIDServerActionInfo>)retrieveActionInfo:(NSString*)actionId error:(NSError**)error;

REMOVED createContainer deprecated method (use createContainer with sessionPassword)

REMOVED reset deprecated method (use HIDDeviceFactory reset)

REMOVED getDefaultInitializationPolicy deprecated method (use HIDProgressListener)

DEPRECATED updateDeviceInfo method (use HIDContainer updateDeviceInfo)

HIDContainerInitialization.h

REMOVED initialPassword deprecated property (use HIDProgressListener)

HIDErrors.h

NEW HIDUnsupportedVersion enumeration value (7)

NEWHIDInvalidContainer enumeration value (8)

HIDTransaction.h

UPDATED Class declaration inherits from HIDServerAction class

REMOVED setStatus deprecated method (use setStatus with password)

HIDContainer.h

NEW updateDeviceInfo method (moved from HIDDevice)

(BOOL)updateDeviceInfo:(NSString*)propertyId withValue:(NSString*)propertyValue withPassword:(NSString*)sessionPassword withParams:(NSArray*)parameters error:(NSError**)error

Others

DEPRECATED TransactionInfo class (use retrieveActionInfo)

NEW ServerAction class

NEW ServerActionInfo class

Modulemap

To support framework target integrations, the XCFramework package now includes a clang modulemap header.

Bitcode support

To support Apple optimization technology aimed at reducing the application binary size, the SDK framework fully supports Bitcode. For further information, refer to the Apple documentation.

What's New in Version 5.5 from 5.4

SDK Updates

iOS versions 10.0 and 11.0 are no longer supported.

SDK Additions and New Features

HIDDeviceFactory

NEW newInstance method

-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config error:(NSError**)error;

DEPRECATED newInstance method

-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config withSessionPassword:(NSString*)sessionPassword error:(NSError**)error;

HIDConstants.h

NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE; ///< password event type

NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_KEY_LABEL; ///< password event key label

NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_KEY_USAGE; ///< password event key usage

NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE_CONTAINER; ///< password event type container

NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE_KEY; ///< password event type key

Exceptions

Documentation has been updated to specify possible exceptions on some functions and methods.

What's New in Version 5.4 from 5.1

SDK Updates

NSError

NEW HIDInvalidArgument to replace thrown exception NSInvalidArgumentException in the SDK

SDK Additions and New Features

HIDErrors.h

NEW HIDInvalidArgument enumeration value for HIDErrorCode

HIDProtectionPolicy.h

NEW HIDLockTypeSilent enumeration value for HIDLockType

HIDConstants.h

NEW HID_KEY_PROPERTY_USAGE_OPPRO constant

What's New in Version 5.1 from 4.0

SDK Updates

HIDTransactionInfo.h

HIDTransactionInfo

NEW getTransaction method

-(id<HIDTransaction>)getTransaction:(NSString*)sessionPassword withParams:(NSArray*)parameters error:(NSError**)error;

HIDTransaction.h

HIDTransaction

UPDATED protocol moved from HIDDevice.h header

HIDProgressListener.h

HIDProgressListener

UPDATED protocol moved from HIDDevice.h header

UPDATED onEventReceived method

- (HIDEventResult*)onEventReceived:(id<HIDEvent>)event;

HIDProgressEvent

UPDATED protocol moved from HIDDevice.h header

NEW HIDEventResultCode enumeration

NEW HIDPasswordPromptResult interface

NEW HIDEvent protocol

HIDContainerInitialization.h

HIDContainerInitialization

UPDATED interface moved from HIDDevice.h header

DEPRECATED initialPassword field (use ProgressListener)

HIDDevice.h

HIDDevice

DEPRECATED retrieveTransaction method (use TransactionInfo.getTransaction)

-(id<HIDTransaction>)retrieveTransaction:(NSString*)transactionId withPassword:(NSString*)sessionPassword withParams:(NSArray*)parameters error:(NSError**)error;

DEPRECATED createContainer method (use new method)

-(id<HIDContainer>)createContainer:(HIDContainerInitialization*)config withListener:(NSObject<HIDProgressListener>*)listener error:(NSError**)error;

DEPRECATED reset method (use new method HIDDeviceFactory.reset)

- (BOOL)reset:(NSArray*)parameters error:(NSError**)error;

DEPRECATED getDefaultInitializationPolicy method (use ProgressListener)

- (id<HIDProtectionPolicy>)getDefaultInitializationPolicy:(NSError**)error;

NEW createContainer method

-(id<HIDContainer>)createContainer:(HIDContainerInitialization*)config withSessionPassword:(NSString*)sessionPassword withListener:(NSObject<HIDProgressListener>*)listener error:(NSError**)error;

HIDDeviceFactory

DEPRECATED newInstance method (use new method)

-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config error:(NSError**)error;

NEW newInstance method

-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config withSessionPassword:(NSString*)sessionPassword error:(NSError**)error;

NEW reset method

+(void)reset:error:(NSError**)error;

SDK Additions and New Features

HIDContainerInitialization.h

NEW HIDContainerRenewal interface

HIDContainer.h

HIDContainer

NEW getCreationDate method

-(NSDate*)getCreationDate:(NSError**)error;

NEW getExpiryDate method

-(NSDate*)getExpiryDate:(NSError**)error;

NEW getRenewalDate method

-(NSDate*)getRenewalDate:(NSError**)error;

NEW isRenewable method

-(Boolean)isRenewable:(NSString*)sessionPassword  error:(NSError**)error;

NEW renew method

-(Boolean)renew:(HIDContainerRenewal*)config withSessionPassword:(NSString*) sessionPassword withListener:(NSObject<HIDProgressListener>*)listener error:(NSError**)error;

HIDErrors.h

HIDErrorCode

NEW HIDPasswordCancelled enumeration value

NEW HIDServerUnsupportedOperation enumeration value

NEW HIDServerOperationFailed enumeration value

What's New in Version 4.0 from 3.0

SDK Addition

HIDContainer.h

HIDContainer

NEW IsFIPSModeEnabled method – Reserved for Future Use.

Code Examples

Transaction Retrieval

SDK 4.0

Copy

NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
// get transaction
id<HIDTransactionInfo> pTransactionInfo = [pDevice retrieveTransactionInfo:transactionId error:&error];
id<HIDTransaction> pTransaction = [pDevice retrieveTransaction:myTransactionId withPassword:mySessionPwd withParams:nil error:&error];

SDK 5.1

Copy

NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig withSessionPassword:mySessionPwd error:&error];
// get transaction
id<HIDTransactionInfo> pTransactionInfo = [pDevice retrieveTransactionInfo:myTransactionId error:&error];
id<HIDTransaction> pTransaction = [pTransactionInfo getTransaction:mySessionPwd withParams:nil error:&error];

SDK 5.5

Copy

NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
// get transaction
id<HIDTransactionInfo> pTransactionInfo = [pDevice retrieveTransactionInfo:myTransactionId error:&error];
id<HIDTransaction> pTransaction = [pTransactionInfo getTransaction:mySessionPwd withParams:nil error:&error];

Provisioning / Container Creation

SDK 4.0

Copy

// progress listener
-(void)onEventReceived:(id<HIDProgressEvent>)event {
    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);
}
// provisioning
-(void)doProvisioning {
    NSError* error;
    // get device
    HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
    id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
    // new container
    HIDContainerInitialization* config = [[HIDContainerInitialization alloc] init];
    config.activationCode = [[NSString alloc] initWithData:myActivationCodeData encoding:NSUTF8StringEncoding];
    config.initialPassword = myInitialPassword;
    config.pushId = myPushID;
    config.containerFriendlyName = myServiceName;
    id<HIDContainer> pContainer = [pDevice createContainer:config withListener:self error:&error];
}

SDK 5.1

Copy

// progress listener
-( HIDEventResult*)onEventReceived:(NSObject<HIDEvent>*)event {
    if ([event isKindOfClass:[HIDPasswordPromptEvent class]]) {
        // password request
        HIDPasswordPromptEvent* pPwdEvent = (HIDPasswordPromptEvent*)event;
        return [[HIDPasswordPromptResult alloc] initWithCode:Continue andPassword:myInitialPassword];
    }
    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)];
}
// provisioning
-(void)doProvisioning {
    NSError* error;
    // get device
    HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
    id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig withSessionPassword:mySessionPwd error:&error];
    // new container
    HIDContainerInitialization* config = [[HIDContainerInitialization alloc] init];
    config.activationCode = [[NSString alloc] initWithData:myActivationCodeData encoding:NSUTF8StringEncoding];
    // NOTE: “config.initialPassword” is not supported; use listener
    config.pushId = myPushID;
    config.containerFriendlyName = myServiceName;
    id<HIDContainer> pContainer = [pDevice createContainer:config withSessionPassword:mySessionPwd withListener:self error:&error];
}

SDK 5.5

Copy

// progress listener
-( HIDEventResult*)onEventReceived:(NSObject<HIDEvent>*)event {
    if ([event isKindOfClass:[HIDPasswordPromptEvent class]]) {
        // password request
        HIDPasswordPromptEvent* pPwdEvent = (HIDPasswordPromptEvent*)event;
        return [[HIDPasswordPromptResult alloc] initWithCode:Continue andPassword:myInitialPassword];
    }
    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)];
}
// provisioning
-(void)doProvisioning {
    NSError* error;
    // get device
    HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
    id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
    // new container
    HIDContainerInitialization* config = [[HIDContainerInitialization alloc] init];
    config.activationCode = [[NSString alloc] initWithData:myActivationCodeData encoding:NSUTF8StringEncoding];
    // NOTE: “config.initialPassword” is not supported; use listener
    config.pushId = myPushID;
    config.containerFriendlyName = myServiceName;
    id<HIDContainer> pContainer = [pDevice createContainer:config withSessionPassword:mySessionPwd withListener:self error:&error];
}