<HIDContainer> Protocol Reference

Service container instance. More...

#import <HIDContainer.h>

Instance Methods
(BOOL)	- addKey:withProtectionPolicyId:withPassword:error:
	Adds a key to the container. More...
(BOOL)	- deleteKey:withParams:error:
	Deletes the key identified by its ID. (RFU) More...
(NSArray *)	- findKeys:error:
	Retrieves a key handle from the secure keystore based on input parameter filter. More...
(NSDate *)	- getCreationDate:
	Retrieves the container creation date. More...
(NSDate *)	- getExpiryDate:
	Retrieve the container expiration date. More...
(NSInteger)	- getId
	Get the identifier of that container. More...
(NSString *)	- getName
	Gets the Friendly Name associated with that container. More...
(NSDate *)	- getOriginalCreationDate:
	Retrieves the container original creation date. More...
(NSString *)	- getProperty:error:
	Returns container property. More...
(id< HIDProtectionPolicy >)	- getProtectionPolicy:
	Gets the protection policy associated with container. More...
(NSDate *)	- getRenewalDate:
	Retrieve the container renewal date. More...
(NSString *)	- getServerURL
	Gets the server URL associated with that 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:
	Renew all keys associated with the container. 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 that container. More...
(BOOL)	- setProperty:withValue:error:
	Overrides a container property. More...
(BOOL)	- updateDeviceInfo:withValue:withPassword:withParams:error:
	Updates container information. More...

Detailed Description

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.

- (BOOL) deleteKey:		(HIDIdentifier *)	keyId
withParams:		(NSArray *)	parameters
error:		(NSError **)	error

Deletes the key identified by its ID. (RFU)

Parameters

keyId	key identifier.
parameters	NSArray of HIDParameter objects for any additional parameters.
error	error details. It may be nil.

Possible error codes are:

• HIDNotImplemented if not implemented

Returns

YES if deleteKey was successfully called.

- (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.

The property name may be any of the following:

• 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

Retrieves the container creation date.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the creation date of container

- (NSDate*) getExpiryDate:

(NSError **)

error

Retrieve the container expiration date.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the expiration date of container

- (NSInteger) getId

Get the identifier of that container.

Returns

The identifier.

- (NSString*) getName

Gets the Friendly Name associated with that container.

Returns

The NSString name.

- (NSDate*) getOriginalCreationDate:

(NSError **)

error

Retrieves the container original creation date.

Parameters

error

error details. It may be nil.

Possible error codes are:

• HIDInternal if unexpected error occurred.

Returns

the creation date of container

- (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 ProtectionPolicy used to protect the key, nil if an error occurs.

- (NSDate*) getRenewalDate:

(NSError **)

error

Retrieve the container renewal 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 that 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

Renew all keys associated with the container.

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.

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 that container.

Parameters

name	Friendly name of container.
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.

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.