Wallet Manager

The WalletManagerFactory constructs the desired WalletManager.

The factory configuration parameters are:

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:

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

An action in ActivID CMS and the CCM API corresponds to a set of logical operations (device issuance, recycling, post-issuance, or unlock) that are used to personalize the security module during synchronization. The Action object represents an operation to be performed on a wallet and allows high-level operations to be performed against a wallet and indirectly against the security modules bound to it. The subject of the performProcess method is a wallet.

The applicationSet attribute of an Action indicates the set of applications (device policy) that is issued (or post-issued) to the wallet, and therefore, the corresponding security modules. The setApplicationSet method can be used to select the ActivID CMS device policy ID (which denotes a set of applications) for the corresponding action.

A device policy (applicationSet) is named at ActivID CMS configuration time; these are not predetermined values. The applicationSet attribute can be set using the Action.setApplicationSet(String) method.

The reason attribute can take the following values:

• ACTION_REASON_NONE—For initial issuance.

• ACTION_REASON_FORGOTTEN—For temporary replacement.

• ACTION_REASON_LOST—For permanent replacement when lost.

• ACTION_REASON_STOLEN—For permanent replacement when stolen.

• ACTION_REASON_DAMAGED—For permanent replacement due to damage.

• ACTION_REASON_RENEW—For reissuance

The action status may be one of the following types:

• ACTION_STATUS_REQUESTED

• ACTION_STATUS_PENDING

• ACTION_STATUS_DENIED

• ACTION_STATUS_FAILED

The following action types are supported:

• ACTION_TYPE_ISSUANCE

• ACTION_TYPE_PRODUCE

• ACTION_TYPE_RECYCLE

• ACTION_TYPE_POSTISSUANCE

• ACTION_TYPE_PINUNLOCK

• ACTION_TYPE_CARDLOCK

• ACTION_TYPE_CARDUNLOCK

The following definitions describe these supported action types:

• ACTION_TYPE_ISSUANCE

Issues a security module to the logical state of issued. A security module in this state is considered fully personalized, unlocked, and in the hands of the user.

• ACTION_TYPE_PRODUCE

Effectively issues a device content-wise, but it leaves the device in a produced lifecycle state indicating that the user has not yet taken possession of the security module. As the security module has not been issued to the user, you must activate the device to bring it to the logical state of being issued.

For additional information about unlocking a GlobalPlatform locked security module, see ACTION_TYPE_CARDUNLOCK below in this list. Also see getLifecycleStatus in Credential Manager Methods for additional information about activation. The security module production may be modified with the runtime parameter (LOCK=true) to GlobalPlatform lock the security module.

• ACTION_TYPE_RECYCLE

Performs recycling of the security module so that it is suitable for issuance again. Note that a recycle is a security module content-level operation, and this does not influence whether the security module is bound.

• ACTION_TYPE_POSTISSUANCE

Performs a post-issuance update of the device based upon the application differences between the currently employed device policy (applicationSet) and the new device policy (applicationSet) supplied with the post-issuance action.

• ACTION_TYPE_PINUNLOCK

Unlocks a device that was PIN-locked for security reasons. For example, this can occur from a multiple number of wrong PIN attempts. This also allows a change to be made in the user’s PIN.

• ACTION_TYPE_CARDLOCK

Performs a GlobalPlatform lock of the card manager, which prevents access to all of the security module’s applications. This action type has the same effect as passing the runtime parameter of LOCK=true to a ACTION_TYPE_PRODUCE action.

• ACTION_TYPE_CARDUNLOCK

Performs a GlobalPlatform unlock of the card manager, which allows access to all of the security module’s applications. This action type reverses the ACTION_TYPE_CARDLOCK effect or the locking effect of the runtime parameter LOCK=true on a security module production.

Binds the specified security module to the specified wallet.

For Java:

void bindSecurityModule(WalletId walletId, SecurityModuleId smId)
throws NoSuchSecurityModuleException, NoSuchWalletException, SecurityModuleNotBoundException, ManagementException, SessionException, LocalizedRemoteException;

For C++:

void bindSecurityModule(WalletId *walletId, SecurityModuleId *smId);

Parameters:

• walletId—wallet identifier.

• smId—unique identifier of the security module to be bound.

Exceptions:

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

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

• SecurityModuleBoundException— if the security module ID specified is already associated with another 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.

See closeSession in Common Methods.

Returns the actions matching the supplied criteria.

For example, the search criteria might result in the retrieval of all actions that are identified as:

Either ACTION_STATUS_PENDING, or ACTION_TYPE_ISSUANCE, and with the ActivID CMS policy set to PIV (Personal Identity Verification).

ACTION_TYPE_CARDLOCK and ACTION_TYPE_CARDUNLOCK return the same set of actions because ActivID CMS considers both to be Device Lock Requests.

For Java:

Action[] findActions(Criteria[] criteria, int maxItems) 
throws SessionException, ManagementException, LocalizedRemoteException;

For C++:

ActionVector *findActions(CriteriaVector *criteria, int maxItems);

Parameters:

• criteria—List of search criteria (see the following table).

• maxItems—Maximum number of items to fetch if the search exceeds this number. If there is no limit, set this parameter to 0 (zero) or to a negative number.

This represents the actions of all matching wallet actions. See the following tables.

findActions Search Criteria (Part 1)

findActions Search Criteria (Part 2)

Exceptions:

• 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 IDs of all wallet actions matching the supplied criteria (for example, retrieving all pending actions for a specified wallet).

For Java:

String[] findActionIds(
Criteria[] criteria, int maxItems)
throws SessionException, ManagementException, LocalizedRemoteException;

For C++:

TStringVector *findActionIds(CriteriaVector *criteria, int maxItems);

Parameters:

• criteria—List of search criteria (see the following table for descriptions).

• maxItems—Maximum number of items to fetch if the search exceeds this number. If there is no limit, set this parameter to 0 (zero) or to a negative number.

Returns:

The IDs of all wallet actions that meet the criteria.

Exceptions:

• 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 application sets (device policies) that meet the supplied criteria. For example, this method might be used to retrieve all the application sets allowed for an action type of ACTION_TYPE_PRODUCE. Observe the following issues regarding application sets:

• When a CRITERIA_ID_WALLETID search criteria is given, only assigned policies that are applicable to the wallet’s devices are returned.

• Multiple reason criteria are OR'ed.

This single method replaces the following LCM API methods:

• GetPoliciesForDevice

• GetPoliciesForPostIssuance

• GetPoliciesForReIssuance

For Java:

String[] findApplicationSets(Criteria[] criteria, int maxItems)
throws SessionException, ManagementException, LocalizedRemoteException;

For C++:

TStringVector *findApplicationSets(CriteriaVector
*criteria, int maxItems);

Parameters:

• criteria—List of search criteria (see the following table). Remember that all criteria are AND’ed together. None of the criteria listed in the following table are required to call this method.

• maxItems—Maximum number of items to fetch if the search exceeds this number. If there is no limit, set this parameter to 0 (zero) or to a negative number.

findApplicationSets Search Criteria

Returns:

The application sets matching the criteria.

Exceptions:

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

The findWalletIds method was added to support the retrieval of a large number of wallets at once. The paged FindWalletIds makes it possible to retrieve even larger numbers of wallets, but in separate groups (or pages).

The paging functionality facilitates integration with IDentity Management Systems, and reconciliation and the number of entries per page is configurable.

This method returns the wallet identifiers that match the supplied criteria. If no criteria are supplied, then all wallet identifiers are returned where the following conditions are met:

• Security module(s) is/are bound

• Issuance action(s) is/are pending

For Java:

WalletId[] findWalletIds(Criteria[] criteria, int maxItems)
throws SessionException, ManagementException, LocalizedRemoteException;

For C++:

WalletIdVector *findWalletIds(CriteriaVector *criteria, int maxItems);

Parameters:

• criteria—List of search criteria (see the previous table). Remember that all criteria are AND'ed together. None of the criteria listed in the previous table are required to call this method.

• maxItems—Maximum number of items to fetch if the search exceeds this number. If there is no limit, set this parameter to 0 (zero) or to a negative number.

Exceptions:

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

Terminates a previously initialized paged wallet search.

For Java:

void findWalletIdsDestroy(SearchSessionId searchHandle) 
throws NoSuchSearchException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

void findWalletIdsDestroy(TString searchHandle);

Parameters:

• searchHandle—Handle to a data set produced by a wallet search.

Exceptions:

• NoSuchSearchException— if the specified search handle is invalid.

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

The findWalletIds method was added to support the retrieval of a large number of wallets at once. The paged FindWalletIds makes it possible to retrieve even larger numbers of wallets, but in separate groups known as pages.

The paging function facilitates integration with an IDMS A collection of systems, processes, procedures, applications, database management systems, and interfaces that work together to manage and protect the identity information of PIV card applicants. The IDMS generally falls within the IDPRS domain. and reconciliation. The number of entries per page is configurable, and this method performs fetches/seeks through a previously initialized data set produced by a paged wallet search.

For Java:

WalletId[] findWalletIdsFetch(SearchSessionId searchHandle, boolean is FetchForward)
throws SearchEndException, NoSuchSearchException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

WalletIdVector *findWalletIdsFetch(TString searchHandle, bool isFetchForward, int fetchSize);

Parameters:

• searchHandle—Handle to a data set produced by a wallet search.

• isFetchForward—Indicates fetch direction. Forward is true.

Returns:

• The IDs of matching wallet IDs in the fetched page of the data set.

Exceptions:

SearchEndException thrown when a limit of a search dataset is reached by either paging forward to the end or paging back to the beginning of the dataset.

• NoSuchSearchException— if the specified search handle is invalid.

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

The findWalletIds method was added to support the retrieval of a large number of wallets at once. The paged FindWalletIds makes it possible to retrieve even larger numbers of wallets, but in separate groups known as pages.

The paging function facilitates integration with anIDMS A collection of systems, processes, procedures, applications, database management systems, and interfaces that work together to manage and protect the identity information of PIV card applicants. The IDMS generally falls within the IDPRS domain. and reconciliation. The number of entries per page is configurable, and this method initializes a paged search of all wallets matching the specified criteria.

For Java:

SearchSessionId findWalletIdsInit(Criteria[] criteria, int fetchSize)
throws SessionException, ManagementException, LocalizedRemoteException;

For C++:

TString findWalletIdsInit(CriteriaVector *criteria);

Parameters:

• criteria—List of search criteria. Uses the same values as the criteria parameter in findWalletIds does.

Returns:

• A handle to the data set to page through.

Exceptions:

• 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 identifier of the wallet that the specified user is bound to. There is a one-to-one mapping between users and wallets (each user only has one wallet).

For Java:

WalletId getBoundWalletFromUser(UserId userId) 
throws NoSuchUserException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

WalletId *getBoundWalletFromUser(UserId *userId);

Parameters:

• userId—ID of the user whose wallet is to be retrieved.

Returns:

The identifier of the wallet bound to the specified user.

Exceptions:

• NoSuchUserException— if the specified user does not exist.

• 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 identifier of the wallet to which the specified security module is bound. There can be one or more security modules bound to a wallet.

For Java:

WalletId getBoundWalletFromSM(SecurityModuleId securityModuleId)
throws NoSuchSecurityModuleException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

WalletId *getBoundWalletFromSM(SecurityModuleId *securityModuleId);

Parameters:

• securityModuleId—Identifier of the security module ID.

Returns:

The identifier of the wallet that contains the security module.

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.

Returns configuration information that is stored on the ActivID CMS server.

Parameters:

• configurationIds—An array of configuration information that is to be retrieved from the server.

Returns:

An array of parameters that includes one parameter for each of the requested configuration elements.

Exceptions:

• NoSuchConfigException— if the specified configuration or profile is not found.

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

See isSessionOpen in Common Methods.

See openSession in Common Methods.

Triggers the indicated workflow processing for the specified wallet action. The lifecycle state of the action may be changed as a side effect of the process execution.

For Java:

void performActionProcess(String actionId, String process, Parameter[] parameters)
throws NoSuchActionException, InvalidStateException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

void performActionProcess(TString actionId, TString process, ParameterVector *parameters);

Parameters:

• actionId—Identifier of the wallet action.

• process—Workflow process to be performed, with following processes supported:

• ACTION_PROCESS_CANCEL—which cancels pending action and results in action being removed from the system.

• ACTION_PROCESS_APPROVE—which approves pending action and results in action being in an approved lifecycle state.

• ACTION_PROCESS_DENY—which denies pending action and results in the action being in a denied lifecycle state.

• ACTION_PROCESS_RESET—which resets a failed request back to a pending lifecycle state.

• optional parameter name—securitymodule

• optional parameter values include initial—allows action to be synchronized only for same security module for which it was originally submitted

• any—which allows action to be synchronized for any security module (default setting).

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

Exceptions:

• NoSuchActionException— if one or more of the specified actions was not found

• InvalidStateException— if the status is not valid for the specified wallet action.

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

Triggers the indicated workflow processing for the specified wallet.

Parameters:

• walletId—Pointer to the wallet to process.

• process—Workflow process to be performed.

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

Exceptions:

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

• InvalidStateException— if the status is not valid for the specified wallet action.

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

Submits the specified list of actions for later synchronization and the order of the actions in the array is significant. If an action is rejected during validation no operations are executed. If a failure occurs executing a valid action, processing stops at that point.

For Java:

String[] submitActions(WalletId walletId, Action[] actions, String owner)
throws NoSuchWalletException, NoSuchSecurityModuleException, SecurityModuleNotBoundException, InvalidActionException, SessionException, ManagementException, LocalizedRemoteException;

For C++:

TStringVector *submitActions(WalletId *walletId, ActionVector *actions, TString owner);

Parameters:

• walletId—Unique identifier of the wallet on which the actions are to be performed.

• actions—List of actions to be performed. See type in Wallet Manager Classes for a list of the action types.

List of runtime parameters:

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

• ACTION_RUNTIME_PARAM_REASON—remplacement reason used for ISSUANCE or PRODUCE action type

• owner—(unused).

Runtime Parameters

The device produce action type can perform GlobalPlatform device locking at the end of a security module production. This optional capability is controlled using an optional runtime parameter. The parameter name/value pair should be one of the following:

• ACTION_RUNTIME_PARAM_LOCK = ACTION_RUNTIME_PARAM_VALUE_TRUE

or

• ACTION_RUNTIME_PARAM_LOCK = ACTION_RUNTIME_PARAM_VALUE_FALSE

If no ACTION_RUNTIME_PARAM_LOCK parameter is supplied at action submission time, then the default behavior is to not lock the security module.

Returns:

• List of wallet action IDs for the actions created.

If an action concerns the issuance or post-issuance of a MOBILE device, its corresponding string is supplemented by the URL to call to issue the mobile device. That URL is separated from the action identifier by a semicolon.

Exceptions:

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

• NoSuchSecurityModuleException— if one or more of the action(s)’ specified security module(s) that were not found.

• SecurityModuleNotBoundException— if one or more of the action(s)’ specified security module(s) were not bound to the specified wallet.

• InvalidActionException— if either the enrollment data or parameters of an action were invalid.

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

Unbinds the specified security module from the specified wallet.

For Java:

void unbindSecurityModule(WalletId walletId, SecurityModuleId smId)
throws NoSuchSecurityModuleException, NoSuchWalletException, SecurityModuleNotBoundException, ManagementException, SessionException, LocalizedRemoteException;

For C++:

void unbindSecurityModule(WalletId *walletId, SecurityModuleId *smId);

Parameters:

• walletId—Wallet identifier.

• smId—Unique identifier of the SecurityModule to be unbound.

Exceptions:

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

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

• SecurityModuleNotBoundException— if the SecurityModule specified is not bound to the specified 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.