Synchronization Manager

A synchronization event that is sent from the server. The event ID can be used to determine the expected event data, with the event containing the following attributes:

• ID—A unique ID that identifies the event: All events during synchronization are in a range greater than 90000

• Parameters—A list of name/value pairs that communicate event details. These name/value pairs can include the following:

  • Description of low-level device operation,

  • Percentage of completion of synchronization,

  • High-level application name associated with the credential,

  • Description of the application,

  • Type of credential, and

  • Status of the application action being performed (such as create, recover, commit, or failed).

Interface that provides an entry point that receives events sent from the server during synchronization. Any class implementing a SyncListener interface should also implement the SyncEvent event method.

See the onEventReceived section.

Synchronization Events

The synchronization events are objects that the SyncListener implementation receives during the synchronization process (see the SyncEvent section). Each event consists of the parameters that are passed from the server.

Only events that have been subscribed are sent to the SyncListener implementation.

The information that the SyncListener implementation can subscribe to and its parameters are the following events:

• Event ID ACTION_RUNTIME_PARAM_VALUE_EVENT_STATUS,

• Event ID ACTION_RUNTIME_PARAM_VALUE_EVENT_APPLICATION, and

• Event ID ACTION_RUNTIME_PARAM_VALUE_EVENT_COUNTERS.

Event ID ACTION_RUNTIME_PARAM_VALUE_EVENT_STATUS

Value: 90001

A localized security module operation-level event.

Parameters:

• ID: CCMConstants.SYNC_EVENT_PARAM_MESSAGE

  • Type: Parameter.TYPE_STRING

  • Encoding: Parameter.ENCODING_NONE

  • Value: Description of the low-level device operation. The messages are based on the device profile leveraged in the synchronization.

• ID: CCMConstants.SYNC_EVENT_PARAM_PERCENT

  • Type: Parameter.TYPE_INTEGER

  • Encoding: Parameter.ENCODING_NONE

  • Value: The percentage completion of the synchronization.

• ID: CCMConstants.SYNC_EVENT_PARAM_LEVEL

  • Type: Parameter.TYPE_STRING

  • Encoding: Parameter.ENCODING_NONE

  • Value: The message level. Possible values are:

  • info—normal operation message

  • warn—a warning or ignorable error

  • error—an error fatal to the synchronization

Event ID ACTION_RUNTIME_PARAM_VALUE_EVENT_APPLICATION

Value: 90002

An application-level event that describes credential transactions that are executed on behalf of the application. The create/recover statuses are generated prior to the call to the credential provider.

The commit/failed statuses occur after a successful commit or after there is an abort of a credential transaction respectively.

Parameters:

• CCMConstants.SYNC_EVENT_PARAM_APP_NAME

  • Type: Parameter.TYPE_STRING

  • Encoding: Parameter.ENCODING_NONE

  • Value: The name of the high-level application with which the credential is associated (for example, PKI1, PKI2, or SKI1)

• CCMConstants.SYNC_EVENT_PARAM_CRED_TYPE

  • Type: Parameter.TYPE_STRING

  • Encoding: Parameter.ENCODING_NONE

  • Value: The type of credential (this should be the credential type as indicated by the credential provider)

• CCMConstants.SYNC_EVENT_PARAM_STATUS

  • Type: Parameter.TYPE_STRING

  • Encoding: Parameter.ENCODING_NONE

  • Value: Description of the status of the application action performed. Possible values are:

    • create

    • recover

    • commit

    • failed

Event ID ACTION_RUNTIME_PARAM_VALUE_EVENT_COUNTERS

Value: 90003

A one-time event that describes all the device operations expected to be performed. The event is emitted at the very start of the synchronization process. It is useful to detect specific conditions, such as the presence of a webauthn enrollment.

Parameter:

• ID: CCMConstants.ACTION_RUNTIME_PARAM_VALUE_EVENT_COUNTERS

  • Type: Parameter.TYPE_STRING

  • Encoding: Parameter.ENCODING_NONE

  • Value: A JSON string containing a map of counters. The key of each counter is the name of an operation; its value is the number of occurrences of the operation. For instance, “client.webauthn.HidGlobal:makeCredential” denotes the fact that one or more webauthn enrollments will be part of the issuance process (the number of times is the value of the counter).

Internationalization

The CCM API uses a resource bundling mechanism to support internationalization and localization. This mechanism can be used to customize the SyncListener. Internationalized strings stored in files are used in the event and these are displayed by the user interface in the ActivID CMS Operator Portal.

For Java

A single file (statusMessages.properties) located in the package (com.activcard.cms.service.tcd.client.event), is used for localizing status events returned to the SyncListener. There are other message files used purely for localizing errors on the server (and possibly in the client).

To support a new language, create a file that contains the corresponding messages in the new language and name that file with the following title:

statusMessages_XX.properties

Where the XX in the file name defines the language code. For example, to add French language messages, you can name the file:

statusMessages_fr.properties

Locate a list of language codes in the last column of the table on the following website:

http://www.loc.gov/standards/iso639-2/php/English_list.php

Unicode characters within the messages listed in this file must be encoded using the \uXXYY escape sequence, where XX and YY are the hexadecimal representation of the two bytes that specify the character.

For C++:

To localize the status events returned to the SyncListener, edit the aiCCMStatusMessages.ini file.

In this file, the set of messages in each language is stored in an .ini section that is defined by a language ID.

For example, if there are any French language messages, they would be in a section labeled [40c]. The list of language IDs can be found at the following website, which provides a table of locale identifier constants and strings: http://msdn.microsoft.com/en-us/library/dd318693.aspx

This API provides security module-centric content that describes how the SyncManager manages submitted actions such as issue, post-issue, recycle, or unlock on a particular SecurityModule in a User's Wallet (the API focuses on operations scheduled against a User's Wallet).

The security module management request comes in the form of a security module personalization operation that is submitted through synchronization management functionality. The security module itself is synchronized with all requests pending for that security module.

The SyncManagerFactory constructs the desired SyncManager using the following factory configuration parameters, using either:

• CONFIG_URL—URL of the CredentialManager service in ActivID CMS

Or both of the following:

• CONFIG_HOST_NAME—Hostname of the CredentialManager service in ActivID CMS.

• CONFIG_HOST_PORT—Port number of the CredentialManager service in ActivID CMS.

And:

• CONNECT_TIMEOUT—Represents the client timeout used when connecting to the ActivID CMS HTTP server hosting the corresponding ActivID CMS service. A value of zero (0) means that there is no client timeout; the client timeout is determined by the server settings. The timeout value is for each connection attempt; the default value is zero (0).

• CONNECT_RETRY—Represents the number of retry attempts permitted for connecting to the ActivID CMS service host. The default value is 1.

For Java implementations, the following are configuration parameters:

• CONFIG_TRUSTSTORE (optional)—Truststore containing the root or intermediate certificate that issued the server certificate. If not present, the default Java truststore is used.

• CONFIG_TRUSTSTORE_PWD (optional)—Password to the truststore.

• CONFIG_KEYSTORE (optional)—Keystore which contains client certificate. If not present, only unprivileged operations are allowed.

• CONFIG_KEYSTORE_PWD (optional)—Password to the keystore.

• CONFIG_ TRUSTMANAGERS (optional)—TrustManagers containing the root certificate.

• CONFIG_ KEYMANAGERS (optional)—KeyManagers containing client certificate.

See closeSession in Common Methods.

Retrieves and returns information from client plug-ins.

Returns:

Returns an array of client plug-in information for all registered plug-ins (including type and method name that are retrieved):

• Name (getName)

• Type (getType)

• Version (getVersion)

• Supported actions (getActionTypeList)

• Description (getDescription)

• Current status

• Ready (plug-in is valid and can execute actions; ClientPlugInfo.READY)

• Invalid (plug-in is not valid and cannot execute actions; ClientPlugInfo.VALID)

Exceptions:

• SyncException—if an internal implementation level failure. This method implements SyncManager.

Retrieves and returns the platform identifiers from the security module of the specified platform class accessible using the supplied access parameters for that class of security module.

This method is strictly client-side with no server dependencies. All client plug-ins that support the getPlatformIdentifier script are queried in sequence until one recognizes the inserted device. At that point, the plug-in returns a set of platform identifiers (IDs) that are used for security module identifications.

The SecurityModuleManager.identitySecurityModule call uses returned platform IDs as input, and ActivID CMS supports the following platform IDs:

• ActivID CMS 5.0 and later releases support:

• securitymodule.smartcard.SMOTYPE

• securitymodule.smartcard.SMOID

This method is one of a pair of methods that support the identification of a security module:

• platformIds

• SyncManager.getPlatformIds(platformClass, accessParams)

• smold

• SecurityModuleManager.identifySecurityModule(platformClass, platformIds)

The platform ID value this method returns will be one of the following:

• PLATFORM_ID_SMARTCARD_SMOID (encoded using UTF-8/hex; 8-bit Unicode Transformation Format/hexadecimal)

• PLATFORM_ID_SMARTCARD_SMOTYPE (encoded using UTF-8/hex)

• PLATFORM_ID_SMARTCARD_LABEL (encoded using UTF-8/hex)

For Java:

Parameter[] getPlatformIdentifiers(String platformClass, Parameter[] accessParameters)
throws ManagementException, LocalizedRemoteException;

For C++:

ParameterVector *getPlatformIdentifiers( TString platformClass, ParameterVector
*accessParams)

Parameters:

• platformClass—Class of the security module platform (smart card, TPM, or USB). The supported option is:

• securitymodule.smartcard

• accessParameters—Parameters required to retrieve platform identifiers of this type or access the security module. The supported option is:

• securitymodule.smartcard platform class

• readerName—Indicates the name of the reader in which the security module is inserted (one of the readers returned by the getReaderList method).

Returns:

List of platform-specific security module identification name/value pairs.

Exceptions:

• ManagementException— if an internal failure occurs.

• LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

Usage:

Typically, the usage is:

• platformIds = SyncManager.getPlatformIdentifiers(platformClass, accessParams)

• smoId = SecurityModuleManager.identifySecurityModule(platformClass, platformIds)

where:

• platformClass represents the major class of security module platform

• platformIds represents an array of platform-specific platform identifiers; for example:

• PLATFORM_ID_SMARTCARD_SMOID

• PLATFORM_ID_SMARTCARD_SMOTYPE

• PLATFORM_ID_SMARTCARD_LABEL (the latter identifier is optional, and all three identifiers are encoded in UTF-8)

• smoId is the resulting completed SecurityModuleId that can now be used with the various Managers.

Enables the retrieving of all reader lists supported by the registered client plug-ins. This method is strictly client-side with no server dependencies. This method retrieves and returns the list of the readers of the specified reader class that is accessible using the registered client plug-ins.

All client plug-ins that support the getReaderList script are queried, which returns the list of readers that they support (and readername values are encoded using UTF-8).

Parameters:

• readerClass—Class of the reader (smart card, TPM, or USB). This parameter supports the following class:

• READER_CLASS_SMARTCARD

Returns:

• List of readers—The resulting concatenated list of readers is returned as an array parameter with one reader per parameter, identified by an incrementing ID.

• ParameterId—This is formed as Reader:pluginId, where the pluginId is the identifier of the plug-in referenced in the client plug-in configuration file.

Exceptions:

• ManagementException— if an internal failure occurs.

See getSessionInfo in Common Methods.

See getVersion in Common Methods.

See isSessionOpen in Common Methods.

Returns true if there is pending activity for the discovered security module. Otherwise, the value returned is false. If the security module is not in a valid state for synchronization, an exception is thrown.

For Java:

public boolean isSyncRequired(String platformClass, Parameter[] accessParameters) 
throws NoSuchSecurityModuleException, NotSyncableStateException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

virtual bool isSyncRequired(TString platformClass, ParameterVector *accessParameters);

Parameters:

• platformClass—Class of the security module platform (smart card, TPM, or USB).

• platformIds—List of platform-specific module indentifcation name/value pairs.

Returns:

• true—If there are pending tasks for the discovered security module to perform (if not, then false).

Exceptions:

• NoSuchSecurityModuleException— if the specified security module does not exist.

• NotSyncableStateException— if the discovered security module is not in a valid state for synchronization.

• SessionException— if there is no valid session (such as session not opened or timed out).

• ManagementException— if an internal failure occurs.

• LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

See also: getPlatformIdentifiers (String, Parameter[])

This method is invoked if a listener implementation is passed to a synchronization and the events are subscribed to. It is invoked when events are dispatched from the server or client plug-ins.

For Java:

void onEventReceived(SyncEvent event);

For C++:

void onEventReceived(SyncEvent event);

Parameters:

• event—A synchronization event that was received.

Returns:

void

See openSession in Common Methods.

Executes all pending requests for the security module (device in the reader). If no actions are pending, no security module content action results. This method supports the optional runtime parameter (LOCK) with values of true or false.

When set to true, this triggers GlobalPlatform locking at the end of synchronization. If a “synchronize” is performed with no pending actions and LOCK=true is supplied to the synchronization, this locks the security module with no other effect on the device or its lifecycle state. If no actions are pending and LOCK=false, no security module content action results.

For Java:

boolean synchronize(String platformClass, Parameter[] accessParameters, Parameter[] runtimeParameters) 
throws NoSuchSecurityModuleException, SyncCancelledException, SyncException, SessionException, 
LocalizedRemoteException;

For C++:

bool synchronize(TString platformClass, ParameterVector accessParameters, ParameterVector*runtimeParameters);

Parameters:

• platformClass—Class of the security module platform (smart card, TPM, or USB). The supported option is:

• PLATFORM_CLASS_SMARTCARD

• accessParameters—Parameters required to access the security module.

Supported options for the PLATFORM_CLASS_SMARTCARD platform class include one of the following:

• ACCESS_PARAM_SMARTCARD_READER—the name of the reader in which the security module is inserted

• ACCESS_PARAM_SMARTCARD_PIN—the PIN associated with the device

• runtimeParameters—Runtime parameters for the synchronization.

List of runtime parameters:

• ACTION_RUNTIME_PARAM_PIN— device PIN used for ISSUANCE, PRODUCE and PINUNLOCK action type

• ACTION_RUNTIME_PARAM_LOCK— device is locked at the end of synchronization if set to TRUE

• ACTION_RUNTIME_ACTIONID—action identifier used to target a specific action (may be needed for wallets with multiple devices)

Returns:

A value of true if synchronization was performed; a value of false if nothing was found to synchronize.

Exceptions:

• NoSuchSecurityModuleException— if the specified security module does not exist.

• SyncCancelledException— if the synchronization is cancelled by another thread.

• SyncException— if an internal implementation level failure.

• SessionException— if there is no valid session (such as session not opened or timed out).

• LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.

• NotSyncableStateException— if the discovered security module is not in a valid state for synchronization.

Executes all pending requests for the specified security module (device in the reader) and provides an event listener that returns status data. If no actions are pending, no security module content action results. This method supports the optional runtime parameter (LOCK) with values of true or false.

When set to true, this triggers GlobalPlatform locking at the end of synchronization. If a “synchronize” is performed with no pending actions and LOCK=true is supplied to the synchronization, this locks the security module with no other effect on the device or its lifecycle state. If no actions are pending and LOCK=false, no security module content action results.

The SyncManager.synchronize(...) method supports the ability to pass a listener to harvest specified events generated during the synchronization.

The SyncListener implementation is passed only events to which it is explicitly subscribed. Subscription to these events is carried out by passing a comma-delimited list of event IDs using the ACTION_RUNTIME_PARAM_EVENTS runtime parameter.

For more information, see the Synchronization Events section.

For Java:

boolean synchronize(String platformClass, Parameter[] accessParameters, Parameter[] runtimeParameters, SyncListener listener)
throws NoSuchSecurityModuleException, SyncCancelledException, SyncException, SessionException, LocalizedRemoteException;

For C++:

bool synchronize(TString platformClass, ParameterVector accessParameters, ParameterVector *runtimeParameters, SyncListener *listener);

Parameters:

• platformClass—Class of the security module platform (smart card, TPM, or USB). The following supported option is:

• PLATFORM_CLASS_SMARTCARD

• accessParameters—Parameters required to access the security module.

For example, the reader name of the device might be an access parameter.

In the following code example, once you have assigned a value to the accessParams variable, you can pass the accessParams variable to any method to get information about the security module from the reader when issuing a device.

Parameter readerParam = new Parameter();
// Set reader Params id, value, encoding and type… Parameter[]    accessParams = new Parameter [] {readerParam};

The supported option for the PLATFORM_CLASS_SMARTCARD platform class is:

ACCESS_PARAM_SMARTCARD_READERNAME

(the name of the reader in which the security module is inserted).

• runtimeParameters—Runtime parameters for the synchronization.

List of runtime parameters:

• ACTION_RUNTIME_PARAM_PIN— device PIN used for ISSUANCE, PRODUCE and PINUNLOCK action type

• ACTION_RUNTIME_PARAM_LOCK— device is locked at the end of synchronization if set to TRUE

• ACTION_RUNTIME_ACTIONID—action identifer used only if ActivID CMS supports Multi device

• ACTION_RUNTIME_PARAM_EVENTS—SyncListener events subscription

• SyncListener—Event listener that receives status information from ActivID CMS during synchronization.

Returns:

A value of true if synchronization was performed, and false if nothing was found to synchronize.

Exceptions:

• NoSuchSecurityModuleException— if the specified security module does not exist.

• SyncCancelledException— if the synchronization is cancelled by another thread.

• SyncException— if an internal implementation level failure.

• SessionException— if there is no valid session (such as session not opened or timed out).

• LocalizedRemoteException— (thrown by the Web service layer) only when the most severe, unexpected, SOAP-level failures occur.