<HIDContainer> Protocol Reference

Encapsulates an active service container instance. More...

#import <HIDContainer.h>

Instance Methods
(BOOL)	- addKey:withProtectionPolicyId:withPassword:error:
	Adds a key to the container. More...
(NSArray *)	- findKeys:error:
	Retrieves a key handle from the secure keystore based on input parameter filter. More...
(NSDate *)	- getCreationDate:
	Gets the activation or renewal creation date for this container. More...
(NSDate *)	- getExpiryDate:
	Gets the server defined expiration date this container. More...
(NSInteger)	- getId
	Get the identifier of this container. More...
(NSString *)	- getName
	Gets the Friendly Name associated with this container. More...
(NSDate *)	- getOriginalCreationDate:
	Gets the first creation date of this container. More...
(NSString *)	- getProperty:error:
	Returns container property. More...
(id< HIDProtectionPolicy >)	- getProtectionPolicy:
	Gets the protection policy associated with container. More...
(NSDate *)	- getRenewalDate:
	Gets the renewal date limit for this container to remain fully functional (support is limited or not working after this date). More...
(NSString *)	- getServerURL
	Gets the server URL associated with this container. More...
(NSString *)	- getUserId
	Gets the identifier of the user for this container. More...
(BOOL)	- isFIPSModeEnabled
	Checks if FIPS 140-2 mode is required. More...
(Boolean)	- isRenewable:error:
	Verify whether the container renewal is possible. More...
(Boolean)	- renew:withSessionPassword:withListener:error:
	Triggers the container service key renewal process with the server for all container keys. More...
(NSArray *)	- retrieveTransactionIds:withParams:error:
	Retrieve a list of pending transaction IDs from the container. More...
(BOOL)	- setConnectionConfiguration:error:
	Sets connection configuration. More...
(BOOL)	- setName:error:
	Sets the Friendly Name associated with this container. More...
(BOOL)	- setProperty:withValue:error:
	Overrides a container property. More...
(BOOL)	- updateDeviceInfo:withValue:withPassword:withParams:error:
	Updates container information. More...

Detailed Description

Encapsulates an active service container instance.

Method Documentation

- (BOOL) addKey:		(HIDKeySpec *)	keySpec
withProtectionPolicyId:		(HIDIdentifier *)	protectionPolicyId
withPassword:		(NSString *)	password
error:		(NSError **)	error

Adds a key to the container.

Parameters

keySpec	the specification containing the key data (expect JWS formatted key).
protectionPolicyId	the protection policy Id for that key.
password	The password protecting that key. It can be set to nil if the protection policy does not require password to be set.
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

false if error occurs.

- (NSArray*) findKeys:		(NSArray *)	filter
error:		(NSError **)	error

Retrieves a key handle from the secure keystore based on input parameter filter.

Parameters

filter

NSArray of HIDParameter objects with key property name and value. (or nil for all keys)

Parameter can b defined with the following id:

• HID_KEY_PROPERTY_USAGE
• HID_KEY_PROPERTY_LABEL
• HID_KEY_PROPERTY_CREATE
• HID_KEY_PROPERTY_EXPIRY

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

The HIDIdentifier array of matching key items, nil if an error occurs.

- (NSDate*) getCreationDate:

(NSError **)

error

Gets the activation or renewal creation date for this container.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the creation date

- (NSDate*) getExpiryDate:

(NSError **)

error

Gets the server defined expiration date this container.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the expire date

- (NSInteger) getId

Get the identifier of this container.

Returns

The identifier.

- (NSString*) getName

Gets the Friendly Name associated with this container.

Returns

The NSString name.

- (NSDate*) getOriginalCreationDate:

(NSError **)

error

Gets the first creation date of this container.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the first creation date

- (NSString*) getProperty:		(NSString *)	propertyId
error:		(NSError **)	error

Returns container property.

Parameters

propertyId

property name.

Supported property names:

• HID_PROPERTY_APPCUSTOMIZATION
• HID_PROPERTY_CHANNEL
• HID_PROPERTY_CREATION_DATE
• HID_PROPERTY_DOMAIN
• HID_PROPERTY_EXPIRY_DATE
• HID_PROPERTY_EXTERNALID
• HID_PROPERTY_PROTOCOL_VERSION
• HID_PROPERTY_RENEWAL_DATE
• HID_PROPERTY_SERIALNUMBER
• HID_PROPERTY_TXURI

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

The property value, nil if an error occurs.

- (id<HIDProtectionPolicy>) getProtectionPolicy:

(NSError **)

error

Gets the protection policy associated with container.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

the HIDProtectionPolicy used to protect the key, nil if an error occurs.

- (NSDate*) getRenewalDate:

(NSError **)

error

Gets the renewal date limit for this container to remain fully functional (support is limited or not working after this date).

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the renewal date of container

- (NSString*) getServerURL

Gets the server URL associated with this container.

Returns

The NSString URL.

- (NSString*) getUserId

Gets the identifier of the user for this container.

Returns

Container user identifier

- (BOOL) isFIPSModeEnabled

Checks if FIPS 140-2 mode is required.

Returns

YES if the container instance has FIPS mode enabled.

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

Verify whether the container renewal is possible.

Parameters

sessionPassword	transaction protection key password (can be nil if not required by the policy)
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if container is not renewable or unexpected error occurs

Returns

YES if the container is renewable.

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

Triggers the container service key renewal process with the server for all container keys.

Parameters

config	renewal configuration see HIDContainerRenewal for details
sessionPassword	transaction protection key password (can be nil if not required by the policy)
listener	A HIDProgressListener implementation to which to report status information or receive password request events.
error	error details. It may be nil.

Possible error codes are:

• HIDAuthentication if password is incorrect.
• HIDInternal if an unexpected error occurred.
• HIDServerAuthentication if the server rejected the authentication.
• HIDInvalidPassword if password validation fails.
• HIDPasswordExpired if password is expired.
• HIDRemote if server responds with any other error.
• HIDServerProtocol if the server response provoked an unexpected error.
• HIDServerOperationFailed if the server encounters a failure for the operation requested.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.
• HIDPasswordRequired if required password was not provided.

Returns

the container or nil if an error occurs.

- (NSArray*) retrieveTransactionIds:		(NSString *)	sessionPassword
withParams:		(NSArray *)	parameters
error:		(NSError **)	error

Retrieve a list of pending transaction IDs from the container.

Parameters

sessionPassword	transaction protection key password (can be nil if not required by the policy)
parameters	empty (reserved for future use)
error	error details. It may be nil.

Possible error codes are:

• HIDAuthentication if password is incorrect.
• HIDTransactionExpired if transaction is no longer valid
• HIDCredentialsExpired if key is no longer valid
• HIDInternal if unexpected error occurred.
• HIDPasswordExpired if expired password is given (changePassword required).
• HIDServerAuthentication if server rejects authentication
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

the Array of transaction id values, nil if an error occurs.

- (BOOL) setConnectionConfiguration:		(HIDConnectionConfiguration *)	config
error:		(NSError **)	error

Sets connection configuration.

Parameters

config	configuration, see HIDConnectionConfiguration for details.
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

false if error occurs

- (BOOL) setName:		(NSString *)	name
error:		(NSError **)	error

Sets the Friendly Name associated with this container.

Parameters

name	Friendly name of container. (expected max 128 characters)
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

YES if property value was successfully updated.

- (BOOL) setProperty:		(NSString *)	propertyId
withValue:		(NSString *)	propertyValue
error:		(NSError **)	error

Overrides a container property.

Parameters

propertyId

property name.

Supported property names:

• HID_PROPERTY_TXURI

Parameters

propertyValue	property value.
error	error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

YES if property has been successfully set.

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

Updates container information.

This method is used by the application to notify of a change in one of the externally generated device attributes.

Parameters

propertyId

deviceInfo property to update.

Supported name attributes:

• HID_DEVICE_INFO_PUSHID: update of the 'pushId', set up at provisioning and used by the server to notify the correct phone. Value may be null or empty to disable push notification for device.
• HID_DEVICE_INFO_NAME: update of the device friendly name, set up at provisioning and used by the server to identify the correct phone. (expected max 128 characters)

Parameters

propertyValue	the new value to replace.
sessionPassword	transaction protection key password (can be nil if not required by the policy)
parameters	empty (reserved for future use)
error	error details. It may be nil.

Possible error codes are:

• HIDAuthentication if password is incorrect.
• HIDTransactionExpired if transaction is no longer valid
• HIDCredentialsExpired if key is no longer valid
• HIDInternal if unexpected error occurred.
• HIDPasswordExpired if expired password is given (changePassword required).
• HIDServerAuthentication if server rejects authentication
• HIDInvalidArgument if the given parameters are invalid or required parameters are missing.

Returns

YES if property value was successfully updated.