Overview: CCM API Concepts

An action in ActivID CMS and the CCM API (called a request in the ActivID CMS Operator Portal) corresponds to a set of logical operations (such as device issuance, recycling, post-issuance, or unlock) that are used to personalize the Security Module during synchronization. The CCM API makes it possible to programmatically perform ActivID CMS tasks (actions) that are otherwise performed using the Operator Portal. See the type section for descriptions of the types of actions that can be performed.

Actions are not synchronous; they are not executed immediately when they are submitted, but are queued to be executed when the device synchronization operation occurs after the action is queued.

This is the reason behind the issuance and produces actions that are performed on a wallet using performProcess. An action reason can be one of the following:

• ACTION_REASON_NONE - Initial issuance of a device or a device update.

• ACTION_REASON_DAMAGED - Device issued is permanent replacement for a damaged device.

• ACTION_REASON_EXPIRED - Device issued is permanent replacement for expired device needing to be replaced.

• ACTION_REASON_FORGOTTEN - Device issued is temporary replacement for a forgotten device.

• ACTION_REASON_LOST - Device issued is permanent replacement for a lost device.

• ACTION_REASON_RENEW - Device issued is permanent replacement for an expiring device needing to be renewed.

• ACTION_REASON_STOLEN - Device issued is permanent replacement for a stolen device.

The ActivID CMS User Portal is a web-based interface that users can use to access the self-service ActivID CMS functions.

A string containing the name of the ActivID CMS device policy.

An application set (called a device policy in the ActivID CMS Operator Portal) is a list of applications to be personalized during device issuance. The application set specifies what credentials and data are to be loaded on the device during device issuance.

For instance, the application set based on the Windows Smart Card Logon Certificate Template might specify that only one PIN application and two PKI applications are to be loaded onto the smart card or device. ActivID CMS device policies support the following applications:

• PIN

• PKI (This policy will use X.509 certificates)

• SKI

• Entrust profile (Entrust profile certificates)

• Generic data storage (static data)

• VCI

A device policy is composed of the following parameters:

• Device profile

• Device type

• Set of credentials to be generated and loaded on the device

The ActivID CMS Operator Portal uses a policy assignment to map device policies for use by specific organizational groups (users) in the directory and types of issuance (for example, initial issuance, or devices that have been lost/stolen, forgotten, or damaged/expired).

The action-to-reason mapping is:

• NONE = Initial Issuance

• FORGOTTEN = Forgotten

• LOST = Lost/Stolen

• STOLEN = Lost/Stolen

• DAMAGED = Damaged/Expired

• EXPIRED = Damaged/Expired

• RENEW = Re-Issuance (one-step device recycle and re-issuance of new applets and/or credentials)

The device model identifier. The ATR can be read from a device. All devices of the same model will have the same ATR. ActivID CMS uses the ATR to reference device models and to tie device profiles to specific models of devices.

Credential used by a user for authentication with ActivID CMS. The authenticator could be one of the following:

• An initial password used to bind a device to a user so that the user can then self-issue the device, or

• An answer to a security question.

Before ActivID CMS can bind a device to a user, the device must first exist in the backend. Devices can either be imported using ActivID Exchange Manager or ActivID Batch Management System (BMS), or imported automatically at the time of issuance. If a device is not found in the backend and ActivID CMS discovery mode is enabled, the device is created automatically. For more information on ActivID BMS, refer to the ActivID BMS documentation.

When automatic device creation is enabled, either the ActivID CMS Operator Portal or the CCM API SecurityModuleManager.identifySecurityModule() must be used to create the device in the backend. Otherwise, the logistic database must be populated by the Exchange Manager.

In ActivID CMS, the automatic device creation mode allows for automatic registration (in the database) of devices that are unknown to ActivID CMS. To enable the automatic device creation mode of ActivID CMS on the ActiviD CMS Operator Portal, perform the following:

1. Select the Configuration tab.

2. Click the Customization link.

3. In Select a topic, click Miscellaneous.

4. Select Device import (enable automatic import of unknown devices), select the option Yes.

A badge is a device issued to users, which they can use for physical access. One form of badge is a smart card, which can be used for both logical and physical access (dual interface or hybrid card).

A management console where a badge is personalized (such as being printed, programmed, or assigned to a specific user). Badging stations often also have enrollment capabilities (for example, for capturing a user's photo or fingerprints).

A generic term for a piece of information that identifies someone and is certified by an authority. Credentials are trusted pieces of data that attest to the identification, authentication, or authorization of users (or other trusted identities). Credentials are classified according to the mechanisms by which they are consumed, by applications, and by the types of services they enable.

In ActivID CMS, a Credential instance is a collection of one or more credential elements that collectively provide some form of identity that can be digitally proven. As its name suggests, a credential element is any component of a fully formed Credential or a component used as input in the credential management process.

A profile that exposes the credential-specific information required to create and manage the credential created with it.

A credential provider component is one that:

• Conforms to the Credential Provider Interface (for more information, refer to About the Credential Provider Service Provider Interface (SPI)), and

• Integrates with a specific type of credential source to provide ActivID CMS with access to credential management functionality in a generalized manner.

A primary credential transaction that ActivID CMS supports is device unlock. In addition, the Credential Manager provides other management operations (such as Action, Operation, and Process).

This is the unique serial number for each device.

For details, see the Security Module section.

This is the process of changing the state of a device from “produced” to the logical state of “issued”.

This is the process of assigning or unassigning a security module (device) to a user’s wallet. A new device or blank card can be bound to a user and later self-issued using the ActivID CMS User Portal. When a device is unbound from a user, the credentials in the device are revoked.

The process of loading applets, credentials such as PKI certificates, keys, or One-Time Password (OTP) seeds, and data such as user static information, a photograph, or biometrics, onto the smart card or device.

For information on device policies, see the Application Set section.

A device profile specifies the applications to be downloaded to a device during device issuance. Unlike a device policy, a device profile does not provide any information about how to personalize the device applications.

In ActivID CMS, the device profile is an XML file that specifies which applets are to be loaded on a given device. A device policy specifies which applet instances are to be personalized by ActivID CMS during issuance (for details, see the Application Set section). You can have multiple device policies for a single device profile.

The device and all its credentials can be terminated (also known as being revoked). This process is usually triggered when the user is leaving the organization. A device might also be terminated in cases where there is no permanent replacement mechanism in place and a device is lost, stolen, or damaged. Device termination results in revocation of the security module associated with the user and all associated credentials. No physical contact with the device is required to terminate it.

An EntryTemplate extends Entry and consists of several local attributes and several inherited attributes.

Any operation that ActivID CMS delegates to an external entity such as smart card middleware. For example, a help desk operator that performs an offline device unlock using a help desk application to leverage the CCM APIs. The challenge would be requested using an external operation that prompts the help desk operator to ask for the user to produce an unlock challenge.

The resulting challenge is entered manually by the operator and the portal sends it to ActivID CMS using the CCM API. ActivID CMS generates an unlock code and again generates an external operation that displays the unlock code to the help desk operator, who passes the code to the user via the telephone.

This is the operating system level locking of devices that complies with the GlobalPlatform standard. This standard is broader than the locking of any single PIN or application as it affects the entire device. For more information, visit the GlobalPlatform website at http://www.globalplatform.org/

This is the identity management software that allows you to manually and/or automatically manage the identity lifecycle of users during which the following occurs:

• A user's identity is established: When a user joins a company, his or her details are entered in the IT systems and accounts, and credentials are generated in all systems that he or she is going to need in order to work.

• A user's identity is modified/updated: When one or several accounts of a user need to be modified; for example, when a user's role changes.

• A user's identity is destroyed: When a user leaves the company, all credentials and accounts associated with that user need to be revoked.

A component responsible for enrolling and registering user information (such as a photograph, biometrics, or some form of user identification), once the information has been verified. The IDPRS is usually based on 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 thus, also provides identity provisioning features.

The initial password that a user uses to log on to the ActivID CMS User Portal for the first time.

The PIN of a device immediately after device issuance.

These are the specifications of the inputs required during the import or update of a credential. Specifications are derived from the credential profile describing how to manage a specific type of credential.

For example, an input requirement for importing a set of security questions and answers would typically be the security questions to answer, any formatting constraints (such as minimum or maximum length), and the minimum number of security questions to answer to satisfy the credential requirement.

A software/hardware system that controls and restricts access to the designated parts of a physical facility (such as access to a specific building, office, secure door, or plant). A PACS usually includes a badging and enrollment station, video surveillance systems, and alarm systems.

Major PACS vendors use the CCM API to integrate device personalization and management within the physical access solution to provide converged physical and logical access solutions.

An available action for the credential. For example, for an active credential, the process types are “suspend” and “revoke”. For a suspended credential, the process types are “resume” and “revoke”. A revoked credential has no process type.

The role of IDMS is to provision resources such as user accounts, credentials, and identities. IDMS centralizes and automates the management of user identities and automatically creates, populates, deletes, and updates account information for all the applications it manages. For details, see the IDMS section.

A hardware or software device capable of serving as a storage and execution platform for embedded applications, credentials, and their services (for example, smart cards, One-Time Password (OTP) tokens, and Trusted Platform Modules (TPM)).

Security Module is an object within the CCM API that represents a smart card, token, or other cryptography-enabled device. A security module is associated with a wallet (for details, see the Walletsection) that belongs to a user (for details, see the User section). The only kind of security modules that ActivID CMS currently supports is smart cards.

A smart card is typically a plastic card that is embedded with an integrated circuit that can function in a variety of ways: as a photo ID, as a proximity badge for facility/building access, and as an IT security device for digital identification and authentication when accessing a secure network.

The smart card can provide solutions that allow organizations to converge user identification and improve facility and IT security by integrating these processes with the backend network systems. A smart card is also a type of security module. For details, see the Security Modulesection.

Synchronization is the operation in which a physical device is updated and this is the final step of the device issuance performed by ActivID CMS. The client initiates synchronization by opening an SSL connection to the ActivID CMS server.

ActivID CMS is a queued-request system. A list of actions is queued without the device being present. When the device is physically present, the device synchronization process executes the queued changes.

When synchronization is performed, the device is updated according to the actions previously submitted to ActivID CMS. For example, certificates may be loaded, key pairs may be generated and loaded, or data may be removed.

The Syntax attribute of a ConfigurationTemplate or ProfileTemplate contains an XML schema that ActivID CMS uses to validate operator responses. In the schema, an attribute definition is provided for each entry in the ConfigurationTemplate. An entry’s key attribute is used to look up the schema attribute definition.

This is typically a hardware-based chip.

In ActivID CMS, a User instance represents a user. Each user is identified by a unique identifier. This identifier is an LDAP attribute which has been defined in ActivID CMS as the unique user identifier attribute (for example, the identifier might be the sAMAccountName, or UID.)

A Virtual Smart Card (VSC) is a Microsoft technology that provides the same security and cryptographic capabilities as physical smart cards on supported devices with a compatible built-in Trusted Platform Module (TPM) chip.

In ActivID CMS, a Wallet instance is a set of security modules and credentials assigned to a User. Usually, there is only one security module per user. You can issue more than one bound card to a user ONLY when the user has been issued a temporary replacement card. For details, see the Security Module section.

The device request is also called device provisioning. This mechanism provisions a request for a device into ActivID CMS with a specific device policy, and, optionally, a PIN. The device policy specifies what credentials and data are to be loaded onto the card (such as PKI certificates, OTP, or static data).

ActivID CMS requires a device production request to synchronize a request queued in ActivID CMS with a physical smart card or device. A device production request must always specify an application set (device policy). The list of possible device policies can be programmatically retrieved using the CCM API findApplicationSets method. A device issuance request may be issued by:

• ActivID CMS itself in the Operator Portal

• An external 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./IDPRS

• An external badging station Synonymous with the term Issuance Station, the badging station is the server where a cardholder can be issued a PIV card by an officer authorized to execute the PIV card request.

There are two possible action types allowed while issuing a device: “issuance” and “produce”. They are equivalent, except that when “produce” is used, the card requires activation after it has been synchronized. To perform a device production request, the following steps are required:

• Bind a device to the user. The binding may be performed by another system at a later time before the device is synchronized (for details, see Device Binding).

• Submit an issuance action request with appropriate parameters (PIN, policy, or reason). Set the PIN (optional), Policy (mandatory) and Reason (mandatory) parameters.

To send an issuance request, you do NOT need to provision a PIN. However, at the time of synchronization, the PIN parameter is required. You can either use the ActivID CMS Operator Portal or the synchronize method of the SyncManager to set the PIN parameter. The following is a list of possible values for the reason parameter:

• FORGOTTEN

• LOST

• STOLEN

• DAMAGED

• RENEW

• EXPIRED

• NONE

NONE is used for an initial issuance or post issuance operation/request. For additional information, see Device Activation. Also, you can refer to the sample code in the testCCM.java file that illustrates how to implement device production/issuance request use cases.

The device must be bound (assigned) to the user. This step is mandatory before the device can be synchronized. A binding is performed between the user's wallet and a security module.

If the device is physically available to the system that is binding the device, both the ATR and CUID can be read from the device using the CCM API. A security module object is always created. Device binding can be performed by:

• An ActivID CMS Operator Portal

• An internal or external card or device management kiosk

• An external badging/printing station

• An external IDMS

• An external help desk application

Device synchronization is the process of personalizing the smart card or device. Personalization is the process of loading applets, credentials (such as PKI certificates, keys, and OTP seeds) and data (such as user static information, a user’s photograph, or a user’s biometric information) on to the device.

During device synchronization, the device is physically updated according to the pending actions that have been submitted to ActivID CMS. The resulting device can be:

• Personalized (ready to be used by a user)

• Updated if the action was a post-issuance action

• Unlocked if the pending action was an unlock action, or recycled if the pending action was a recycle action

Device synchronization can be performed at the following locations:

• Badging station

• ActivID CMS Operator Portal by the device issuance officer

• ActivID CMS User Portal by the user

• External Card or Device Management Kiosk

Device synchronization takes place only after a device production request is submitted to ActivID CMS. For a code sample that illustrates device synchronization, see Synchronizing a Device.

Device activation is the process of changing the device state from produced to the logical state of issued. Device activation can be performed at the following locations:

• Badging station

• ActivID CMS Operator Portal

• ActivID CMS User Portal

Activation is required only if the initial issuance request was “produce”. If the request was “issuance”, then activation is not required. During the activation phase, the contents of the device are not modified. For a code sample that illustrates device activation, see Activating a Device.

The device is protected by a PIN. If the PIN is entered incorrectly too many times, then the device is locked and the user is unable to use the credentials on the device. The CCM API is used to unlock the device and it can be unlocked using any of the following:

• ActivID CMS Operator Portal,

• An external badging system,

• An external badging management kiosk, or

• ActivID CMS User Portal.

To unlock a device using CCM, perform the following tasks:

• Create a PIN unlock request using CCM API (a new PIN must be specified in the unlock request).

• Perform device synchronization.

The smart card must be present during the PIN unlock process. For a code sample that illustrates a device unlock using the CCM API, see Requesting that the PIN be Unlocked.

For information about unlocking the PIN using assisted online unlock on the ActivID CMS User Portal, or unlocking the PIN using self-service unlock on the ActivID CMS User Portal, refer to the ActivID CMS User online documentation.

For information about unlocking the PIN using assisted offline unlock and ActivClient, or unlocking the PIN using face-to-face unlock on the ActivID CMS Operator Portal, refer to Unlocking a Device.

ActivID CMS supports device replacement in the following situations:

• Temporary replacement (such as when a user forgets the device). In this case, a temporary replacement device is issued when:

• The help desk operator creates a device replacement request.

• The issuance operator performs device personalization.

• The new device is given to the user.

• Permanent replacement (such as when a card is stolen, lost, expired, or damaged). Technically, damaged is actually the fourth type of replacement (damage replacement). When performing a permanent replacement of the device, you must complete the following tasks:

• The help desk operator creates a device replacement request.

• The issuance operator performs device binding.

• The new device is given to the user.

• The user enrolls the device using the ActivID CMS User Portal.

The device replacement request can be performed using any of the following:

• ActivID CMS Operator Portal,

• ActivID CMS User Portal,

• A badging station,

• An external help desk, or

• IDMS/IDPRS.

Device replacement issuance can be performed via one of the following:

• ActivID CMS Operator Portal,

• ActivID CMS User Portal, or

• A badging station.

Usually, this capability is implemented by an external help desk system. For a code sample that illustrates device replacement using the CCM API, see Requesting a Replacement Device.

The device and all its credentials can be terminated (or revoked). This process is usually triggered when the user is leaving the organization or company. A device might also be terminated when no permanent device replacement mechanism is in place and a device is lost, stolen, or damaged.

Device termination results in the revocation of the security module associated with the user and all the device’s associated credentials. No physical contact with the device is required in order to terminate it. Device recycle can be used to clear a device of its data. However, device recycle is not usually performed in production, especially when user information is printed on the badge. Device termination can be triggered from or performed by any of the following:

• An IDMS/IDPRS,

• A badging station,

• An external help desk, and

• ActivID CMS Operator Portal (by a Help Desk officer).