Security Module Manager

An abstract device application. The getSecurityModule method returns a SecurityModule object that contains a list of Application objects.

An Application identifier; used by the Application object.

The SecurityModuleManagerFactory constructs the desired SecurityModuleManager. The factory configuration consists of the following parameters:

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 there is no client timeout; the client timeout is determined by the server settings. The timeout value is for each connection attempt, with the default value being 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:

• 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 (mandatory)—Keystore that contains client certificate

• CONFIG_KEYSTORE_PWD (mandatory)—Password to the keystore

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

• CONFIG_ KEYMANAGERS (optional)—KeyManagers containing client certificate

The security module, its state, and application/credential contents.

An interface that describes a particular security module. Each SecurityModuleInterface instance contains an interface type (contact or contactless) and status (active or inactive).

See closeSession in Common Methods.

Returns a list of security module IDs that are bound to the specified user. There is a one-to-one mapping between users and wallets. Each user only has one wallet. There may be a 1-to-0, a 1-to-1, or a 1-to-2 relationship between wallets and security modules because a user may have more than one device.

For Java:

SecurityModuleId[] getBoundSMFromUser(UserId userId) 
throws NoSuchUserException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

SecurityModuleIdVector
*getBoundSMFromUser(UserId *userId);

Parameters:

• userId—Unique identifier of the user.

Returns:

List of IDs identifying security modules bound to the specified user.

Exceptions:

• NoSuchUserException—if the specified user ID does not identify a valid user.

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

Returns a list of security module IDs that are bound to the specified wallet. There may be a 1-to-0, a 1-to-1, or a 1-to-many relationship between wallets and security modules.

For Java:

SecurityModuleId[]
getBoundSMFromWallet(WalletId walletId)
throws NoSuchWalletException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

SecurityModuleIdVector
*getBoundSMFromWallet(WalletId *walletId);

Parameters:

• walletId—Unique ID of the wallet.

Returns:

List of IDs identifying the SecurityModules that are bound to the specified wallet.

Exceptions:

• NoSuchWalletException—if the specified wallet ID does not identify a valid wallet.

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

Returns the lifecycle status of this security module.

For Java:

String getLifecycleStatus(SecurityModuleId smId) 
throws NoSuchSecurityModuleException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

TString getLifecycleStatus(SecurityModuleId *smId);

Parameters:

• smId—security module ID.

Returns:

The lifecycle status of this security module. The status is a concatenation of the security modules status and reason codes separated by a “,” (comma).

For example, for a status of ISSUED and a reason of ASSIGNED, the returned status would be:

SECURITY_MODULE_STATUS_ISSUED + "," + SECURITY_MODULE_STATUS_REASON_ASSIGNED.

The status returned can be:

Exceptions:

• NoSuchSecurityModuleException—if the security module ID specified does not identify a valid security module.

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

• ManagementException—if an internal implementation-level failure occurs.

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

See also: Section Security Module / Device Lifecycle.

Returns the content state of the security module representing its internal encoded state.

For Java:

SecurityModule getSecurityModule(SecurityModuleId securityModuleId)
throws NoSuchSecurityModuleException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

SecurityModule* getSecurityModule(SecurityModuleId *smId)

Parameters:

• securityModuleId—security module to process.

Returns:

The security module. The content state of the security module consists of: SecurityModuleId, ConfigurationId, ApplicationSet, the security module interfaces, the security module applications, and the security module credentials.

Exceptions:

• NoSuchSecurityModuleException—if the security module ID specified does not identify a valid security module.

• 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 getSessionInfo in Common Methods.

See getVersion in Common Methods.

Identifies a security module using platform-specific security module identification information and returns a security module identifier based on this information.

If ActivID CMS is configured to automatically register security modules (by enabling ActivID CMS, see Automatic Device Creation), this method registers any unregistered security module presented. If already registered, no action is taken.

For Java:

SecurityModuleId identifySecurityModule(String platformClass, Parameter[] platformIds) 
throws NoSuchSecurityModuleException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

SecurityModuleId *identifySecurityModule(TString platformClass, ParameterVector *platformIds);

Parameters:

• platformClass—Class of the security module platform (such as smart card, TPM, or USB). This parameter can accept the following value:

• PLATFORM_CLASS_SMARTCARD

• platformIds—List of platform-specific security module identification name/value pairs. The preferred method for preparing the Parameter[] for SecurityModuleManager.identifySecurityModule(…) is to call SyncManager.getPlatformIdentifiers(String, Parameter[]). ActivID CMS supports the following platform ID types, which are encoded using UTF-8:

• PLATFORM_ID_SMARTCARD_SMOID

• PLATFORM_ID_SMARTCARD_SMOTYPE

• PLATFORM_ID_SMARTCARD_LABEL (optional)

Returns:

Unique security module identification information.

Exceptions:

• NoSuchSecurityModuleException—if the security module is unidentifiable or not known where automatic security module registration is disabled.

• 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 isSessionOpen in Common Methods.

See openSession in Common Methods.

Triggers the indicated lifecycle workflow processing for the specified security module. The process parameter specifies the workflow to be executed. Processing invoked through this method does not impact the device’s content. To modify device content, issue the following command:

WalletManager.performProcess(WalletId, Action[], String)

For Java:

void performProcess(SecurityModuleId smId, String process, Parameter[] parameters)
throws NoSuchSecurityModuleException, InvalidStateException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

void performProcess(SecurityModuleId *smId, TString process, ParameterVector *parameters);

Parameters:

• smId—ID of the security module to process.

• process—Workflow process to perform. This parameter can take the following values:

• PROCESS_ID_SM_ACTIVATE—Completes the issuance of a device from a device lifecycle perspective. This step is primarily to support bureau-produced security modules.

• PROCESS_ID_SM_SUSPEND—Suspends a security module and suspends associated credentials.

• PROCESS_ID_SM_RESUME—Resumes a suspended security module and resumes associated suspended credentials.

• PROCESS_ID_SM_REVOKE—Revokes a security module and revokes all associated credentials.

• parameters—Input parameters required to perform the process, or an empty array.

Exceptions:

• NoSuchSecurityModuleException—if the security module ID specified does not identify a valid security module.

• InvalidStateException—if the security module is in a state not compatible with the requested process.

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