com.hidglobal.ia.service.transaction.Container Interface Reference

Encapsulates an active service container instance. More...

Public Member Functions
Key	addKey (KeySpec keySpec, ProtectionPolicy protectionPolicy, char[] password) throws InternalException, UnsupportedDeviceException, LostCredentialsException, AuthenticationException, FingerprintAuthenticationRequiredException, FingerprintNotEnrolledException, PasswordRequiredException, PasswordExpiredException, InvalidParameterException
Key []	findKeys (Parameter[] filter) throws LostCredentialsException, InternalException, UnsupportedDeviceException, InvalidParameterException
Transaction	generateAuthenticationRequest (String message, KeyId signingKey) throws InternalException, InvalidParameterException, ServerUnsupportedOperationException
Date	getCreationDate ()
Date	getExpiryDate ()
int	getId ()
String	getName ()
Date	getOriginalCreationDate ()
char []	getProperty (String param) throws InternalException, UnsupportedDeviceException, LostCredentialsException, InvalidParameterException
ProtectionPolicy	getProtectionPolicy () throws UnsupportedDeviceException, InternalException, LostCredentialsException
Date	getRenewalDate ()
String	getServerURL ()
String	getUserId ()
boolean	isFIPSModeEnabled () throws InternalException
boolean	isRenewable (char[] sessionPassword)
void	renew (ContainerRenewal config, char[] sessionPassword, EventListener eventListener) throws PasswordExpiredException, UnsupportedDeviceException, InternalException, AuthenticationException, RemoteException, UnsafeDeviceException, ServerProtocolException, FingerprintAuthenticationRequiredException, FingerprintNotEnrolledException, LostCredentialsException, PasswordRequiredException, CredentialsExpiredException, ServerUnsupportedOperationException, GooglePlayServicesObsoleteException, PasswordCancelledException, ServerOperationFailedException, InvalidParameterException, InvalidPasswordException
char [][]	retrieveTransactionsIds (char[] sessionPassword, Parameter[] params) throws RemoteException,UnsupportedDeviceException, InternalException, FingerprintAuthenticationRequiredException, InvalidParameterException
void	setConnectionConfiguration (ConnectionConfiguration connectionConfiguration) throws InvalidParameterException
void	setName (String name) throws UnsupportedDeviceException, LostCredentialsException, InternalException, InvalidParameterException
void	setProperty (String param, char[] value) throws InternalException, UnsupportedDeviceException, LostCredentialsException, InvalidParameterException
void	updateDeviceInfo (String name, char[] value, char[] password, Parameter[] params) throws RemoteException, AuthenticationException, UnsupportedDeviceException, InternalException, LostCredentialsException, com.hidglobal.ia.service.exception.FingerprintAuthenticationRequiredException, ServerOperationFailedException, InvalidParameterException

Detailed Description

Encapsulates an active service container instance.

Since

2.0

Member Function Documentation

addKey()

Key com.hidglobal.ia.service.transaction.Container.addKey	(	KeySpec	keySpec,
		ProtectionPolicy	protectionPolicy,
		char []	password
	)		throws InternalException, UnsupportedDeviceException, LostCredentialsException, AuthenticationException, FingerprintAuthenticationRequiredException, FingerprintNotEnrolledException, PasswordRequiredException, PasswordExpiredException, InvalidParameterException

Adds a key to the container.

Parameters

keySpec	the specification containing the key data (expect JWS formatted key).
protectionPolicy	The protection policy Id for that key.
password	The password protecting that key. It can be set to null if the protection policy does not require a password to be set.

Returns

Key object

Exceptions

AuthenticationException	if password is incorrect.
FingerprintAuthenticationRequiredException	if fingerprint authentication is required by policy.
FingerprintNotEnrolledException	if fingerprint enrollment is required.
InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
PasswordExpiredException	if expired password is given (changePassword required).
PasswordRequiredException	if required password was not provided.
UnsupportedDeviceException	if device is not supported by policy.

findKeys()

Key [] com.hidglobal.ia.service.transaction.Container.findKeys

(

Parameter []

filter

)

throws LostCredentialsException, InternalException, UnsupportedDeviceException, InvalidParameterException

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

Parameters

filter

Array of Parameter objects with key property name and value.

Filter parameter can be defined with following id:

• SDKConstants.HID_KEY_PROPERTY_USAGE
• SDKConstants.HID_KEY_PROPERTY_LABEL
• SDKConstants.HID_KEY_PROPERTY_CREATE
• SDKConstants.HID_KEY_PROPERTY_EXPIRY

Returns

Key array of matching key items. Any provisioned asymmetric keys will be represented as a KeyPair object.

Exceptions

InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
UnsupportedDeviceException	if device is not supported by policy.

generateAuthenticationRequest()

Transaction com.hidglobal.ia.service.transaction.Container.generateAuthenticationRequest	(	String	message,
		KeyId	signingKey
	)		throws InternalException, InvalidParameterException, ServerUnsupportedOperationException

Generates a Direct Client Signature (DCS) transaction for approval

Parameters

message	The logon or operation validation message to be displayed with the transaction for approval (expected max 1000 characters)
signingKey	The signing key to be used for approval of the transaction

Returns

The generated transaction object for signing.

Exceptions

InternalException	if server responds with any other error.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
ServerUnsupportedOperationException	if the server does not support direct client signature.

getCreationDate()

Date com.hidglobal.ia.service.transaction.Container.getCreationDate

(

)

Gets the activation or renewal creation date for this container.

Returns

the creation date

getExpiryDate()

Date com.hidglobal.ia.service.transaction.Container.getExpiryDate

(

)

Gets the server defined expiration date this container.

Returns

the expire date

getId()

int com.hidglobal.ia.service.transaction.Container.getId

(

)

Get the identifier of this container.

Returns

The identifier.

getName()

String com.hidglobal.ia.service.transaction.Container.getName

(

)

Gets the Friendly Name associated with this container.

Returns

The String name.

getOriginalCreationDate()

Date com.hidglobal.ia.service.transaction.Container.getOriginalCreationDate

(

)

Gets the first creation date of this container.

Returns

the first creation date

getProperty()

char [] com.hidglobal.ia.service.transaction.Container.getProperty

(

String

param

)

throws InternalException, UnsupportedDeviceException, LostCredentialsException, InvalidParameterException

Returns container property.

Parameters

param

property name

Supported property names:

• SDKConstants.PROPERTY_APPCUSTOMIZATION
• SDKConstants.PROPERTY_CHANNEL
• SDKConstants.PROPERTY_CONTAINER_CREATION_DATE
• SDKConstants.PROPERTY_CONTAINER_EXPIRY_DATE
• SDKConstants.PROPERTY_CONTAINER_KEYSTORE_TYPE
• SDKConstants.PROPERTY_CONTAINER_ORIGINAL_CREATION_DATE
• SDKConstants.PROPERTY_CONTAINER_RENEWAL_DATE
• SDKConstants.PROPERTY_DOMAIN
• SDKConstants.PROPERTY_EXTERNALID
• SDKConstants.PROPERTY_PROTOCOL_VERSION
• SDKConstants.PROPERTY_SERIALNUMBER

Returns

The property value

Exceptions

InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
UnsupportedDeviceException	if device is not supported by policy.

getProtectionPolicy()

ProtectionPolicy com.hidglobal.ia.service.transaction.Container.getProtectionPolicy

(

)

throws UnsupportedDeviceException, InternalException, LostCredentialsException

Gets the protection policy associated with container.

Returns

the ProtectionPolicy used to protect the key

Exceptions

InternalException	if an unexpected error occurred.
LostCredentialsException	if provisioning key data has been corrupted or lost.
UnsupportedDeviceException	if device is not supported by policy.

getRenewalDate()

Date com.hidglobal.ia.service.transaction.Container.getRenewalDate

(

)

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

Returns

the renewal date

getServerURL()

String com.hidglobal.ia.service.transaction.Container.getServerURL

(

)

Gets the server URL associated with this container.

Returns

The String URL.

getUserId()

String com.hidglobal.ia.service.transaction.Container.getUserId

(

)

Gets the identifier of the user for this container.

Returns

the identifier

isFIPSModeEnabled()

boolean com.hidglobal.ia.service.transaction.Container.isFIPSModeEnabled

(

)

throws InternalException

Checks the container if FIPS strict mode is enforced.

Returns

Returns true if the FIPS strict mode is enabled.

Exceptions

InternalException

if an unexpected error occurred.

isRenewable()

boolean com.hidglobal.ia.service.transaction.Container.isRenewable

(

char []

sessionPassword

)

Check if the container can be renewed

Parameters

sessionPassword

transaction protection key password (can be null if not required by the policy)

Returns

true if renewable.

renew()

void com.hidglobal.ia.service.transaction.Container.renew	(	ContainerRenewal	config,
		char []	sessionPassword,
		EventListener	eventListener
	)		throws PasswordExpiredException, UnsupportedDeviceException, InternalException, AuthenticationException, RemoteException, UnsafeDeviceException, ServerProtocolException, FingerprintAuthenticationRequiredException, FingerprintNotEnrolledException, LostCredentialsException, PasswordRequiredException, CredentialsExpiredException, ServerUnsupportedOperationException, GooglePlayServicesObsoleteException, PasswordCancelledException, ServerOperationFailedException, InvalidParameterException, InvalidPasswordException

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

Parameters

config	ContainerRenewal structure containing configuration
sessionPassword	transaction protection key password (can be null if not required by the policy)
eventListener	EventListener instance for progress messages and password prompt events.

Exceptions

AuthenticationException	if password is incorrect.
CredentialsExpiredException	if the transaction protection key is expired and renewal is not possible.
FingerprintAuthenticationRequiredException	if fingerprint authentication is required by policy.
FingerprintNotEnrolledException	if fingerprint enrollment is required.
GooglePlayServicesObsoleteException	if Google Play Services is out of date.
InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
PasswordCancelledException	if the password prompt dialog has been canceled by the user.
PasswordExpiredException	if expired password is given (changePassword required).
PasswordRequiredException	if required password was not provided.
RemoteException	if server responds with any other error.
ServerOperationFailedException	if the server encounters a failure for the operation requested.
ServerUnsupportedOperationException	if the server does not support the operation requested.
UnsafeDeviceException	if the mobile is not protected by a password.
UnsupportedDeviceException	if device is not supported by policy.

retrieveTransactionsIds()

char [][] com.hidglobal.ia.service.transaction.Container.retrieveTransactionsIds	(	char []	sessionPassword,
		Parameter []	params
	)		throws RemoteException,UnsupportedDeviceException, InternalException, FingerprintAuthenticationRequiredException, InvalidParameterException

Retrieve a list of pending transaction IDs from the server for the container.

Parameters

sessionPassword	transaction protection key password (can be null if not required by the policy)
params	parameters empty (reserved for future use)

Returns

the Array of transaction id values.

Exceptions

FingerprintAuthenticationRequiredException	if fingerprint authentication is required by policy.
InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
RemoteException	if server responds with any other error.
UnsupportedDeviceException	if device is not supported by policy.

setConnectionConfiguration()

void com.hidglobal.ia.service.transaction.Container.setConnectionConfiguration

(

ConnectionConfiguration

connectionConfiguration

)

throws InvalidParameterException

Sets connection configuration.

Parameters

connectionConfiguration

connection configuration, see ConnectionConfiguration for details.

Exceptions

InvalidParameterException

if the given parameters are invalid or required parameters are missing.

setName()

void com.hidglobal.ia.service.transaction.Container.setName

(

String

name

)

throws UnsupportedDeviceException, LostCredentialsException, InternalException, InvalidParameterException

Sets the Friendly Name associated with this container.

Parameters

name	container friendly name. (expected max 128 characters)

Exceptions

InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
UnsupportedDeviceException	if device is not supported by policy.

setProperty()

void com.hidglobal.ia.service.transaction.Container.setProperty	(	String	param,
		char []	value
	)		throws InternalException, UnsupportedDeviceException, LostCredentialsException, InvalidParameterException

Overrides a container property.

Parameters

param

property name.

Supported property names:

• SDKConstants.PROPERTY_APPCUSTOMIZATION (expected base64, max 65k)

Parameters

value

new value for property.

Exceptions

InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
UnsupportedDeviceException	if device is not supported by policy.

updateDeviceInfo()

void com.hidglobal.ia.service.transaction.Container.updateDeviceInfo	(	String	name,
		char []	value,
		char []	password,
		Parameter []	params
	)		throws RemoteException, AuthenticationException, UnsupportedDeviceException, InternalException, LostCredentialsException, com.hidglobal.ia.service.exception.FingerprintAuthenticationRequiredException, ServerOperationFailedException, InvalidParameterException

Updates container information.

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

Parameters

name	deviceInfo property to update.

Supported name attributes:

• SDKConstants.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.

Parameters

value	the new value to replace.
password	transaction protection key password (can be null if not required by the policy)
params	empty (reserved for future use)

Exceptions

AuthenticationException	if password is incorrect.
FingerprintAuthenticationRequiredException	if fingerprint authentication is required by policy.
InternalException	if an unexpected error occurred.
InvalidParameterException	if the given parameters are invalid or required parameters are missing.
LostCredentialsException	if provisioning key data has been corrupted or lost.
RemoteException	if server responds with any other error.
ServerOperationFailedException	if the server encounters a failure for the operation requested.
UnsupportedDeviceException	if device is not supported by policy.