Overview of the CCM API

This section describes the Card and Credential Management (CCM) Application Programming Interface (API) used with the ActivID Credential Management System (CMS).

It provides information about:

  • CCM API components,

  • How the CCM components are installed,

  • Implemented constants, interfaces, common classes, and methods,

  • Key modules that comprise CCM,

  • Corresponding classes and methods used in the key modules, and

  • General and specific exceptions and error codes.

This information is for software programmers or system developers who are responsible for developing applications or extending ActivID CMS functionality using the Card and Credential Management (CCM) API.

Developers should read this section in conjunction with the detailed CCM API reference specification HTML and Javadoc documentation. If there is any divergence between the HTML and this guide, then developers should consider the auto-generated HTML documentation to be the final authority.

About the ActivID CMS SDKs

The ActivID CMS Software Development Kits (SDKs) make it possible for the seamless integration of ActivID CMS with the various identity management and physical access control systems which provide a complete enterprise provisioning and physical/logical access control solution. The result is a credential management solution that can grow with your enterprise architecture now and into the future. For detailed information about SDKs, refer to About the Software Development Kit.

ActivID CMS Components

The ActivID CMS SDK consists of the following interfaces:

  • Card and Credential Management API (CCM API)

  • Static Data Collection Plug-In Service Provider Interface (SPI)

  • Event Notification Plug-In SPI

  • Generic Plug-In SPI

  • Credential Provider SPI

  • REST API (refer to About the REST API for more details on the services offered by this API)

CCM API Prerequisites

The CCM API is a C++ and Java-based API that works with this version of ActivID CMS on all platforms on which ActivID CMS runs.

Where native binaries are included in the CCM API application, they must support the target ActivID CMS operating systems.

CCM API for Java

The CCM API for Java is supported on client environments with Java 11 or 17 installed.

CCM API for C++ Development Environment

C++-based CCM API applications can be built using Microsoft Visual Studio® 2022 and above.

Runtime Environment

The ActivID CMS clients run in the Win32® or Win64® Client Environment.

The SyncManager component in the CCM API Client relies upon the following to communicate with (and synchronize with) the card:

  • Standard smart card access interface,

  • Basic Standard Interface (BSI) client API (available in ActivID ActivClient 7.1 and above for Windows),

    Important: Starting with ActivID CMS 5.8, the ActivID ActivClient middleware is no longer required.

  • Standard PKCS#11 library for communication with (and synchronization with) the cards.

  • Microsoft Virtual Smart Cards for clients with a supported Trusted Platform Module (TPM) chip.

For important information on how to install the CCM API for C++ and designing applications for it, see Creating CCM Application in C++.

Backward Compatibility

To facilitate integration for its partners and customers, HID Global strives to maintain sufficient backward compatibility in its APIs. The following subsections describe the type of client/server and source code backward compatibility provided in this release of ActivID CMS.

Client/Server Backward Compatibility

Due to design changes made in the client architecture for ActivID CMS 5.0, an application built using ActivID CMS 4.3 SDK client libraries will require recompilation for C++ SDK, or a library/.jar file change for Java SDK in order to work with this ActivID CMS server.

Source Code Backward Compatibility

With only a few exceptions, no code changes are necessary to link new updated CCM .jar/.dll files in projects written in C++ (Win32) or Java. In order to take advantage of the new functionality, you must add code.

Due to multi-device support, if ActivID CMS is configured to support more than one type of device (for instance, smart cards and virtual smart cards), the application must be modified with a function in the ActivID CMS CCM API (see Update in ActivID CMS API 5.0).

Using the Static Data Collection Plug-In SPI

The Static Data Collection plug-in service provider interface (SPI) enables third-party developers to store third-party application-specific data and/or organization-specific data on devices during issuance.

The Static Data Collection plug-in SPI allows developers to create methods (triggered at card issuance time) that fetch and format static data Cardholder-related information including things such as health benefits, biometrics, unique organizational identifiers, or unique personal identifiers that rarely change. to be stored in Generic Containers A Generic Container (GC) applet is used to store static data on devices. The applet treats all data as opaque or generic and never attempts to assign any meaning to the data with which it is dealing. on devices. The data can come from any repository (such as a database, LDAP Lightweight Directory Access Protocol, or data files).

For detailed information about developing plug-ins using the Static Data Collection plug-in SPI, refer to About the Static Data Collection Plug-In SPI.

Using the Event Notification Plug-In SPI

The Event Notification plug-in service provider interface allows code from a plug-in to be triggered when certain ActivID CMS events occur such as:

  • Device Management Events (such as Update, Bind, Recycle, Termination, or Unlock),

  • Credential Management Events (such as Issuance, Revoke, Suspend, or Resume),

  • Request Management Events (such as Submit or Approve),

  • User management (such as Create, Delete, or Terminate),

When an event occurs, the plug-in can then take some action, such as:

  • Log the event into a file or into a database

  • Send an e-mail message or an SNMP notification

  • Notify another application/service through some protocol

  • Update the data of an IDentity Management Systems (IDMS)/IDPRS

For detailed information about developing plug-ins using the Event Notification plug-in SPI, refer to About the Event Notification Plug-in SPI.

Using the Generic Plug-In SPI

Server-Side Generic Plug-Ins

On the server side, the generic plug-in SPI A Service Provider Interface (SPI) consists of a set of constant definitions and method declarations without implementations and intended to be called or used in a pre-determined generic manner with a set of outputs that meet pre-determined abstract rules and expectations. makes it possible for ActivID CMS to access user attributes on repositories other than the LDAP Lightweight Directory Access Protocol directory. The server-side generic plug-ins are also called enrollment plug-ins An enrollment plug-in is involved every time a user attribute is set or retrieved by ActivID CMS. This makes it possible to map user attributes to repositories other than ActivID CMS’ standard LDAP (for example, such as IDMS, databases, or XML files)..

Generic Client Plug-In Infrastructure

The generic client plug-in infrastructure allows customization of the ActivID CMS issuance workflow steps that occur on the client. Client-side generic plug-ins allow customers deploying ActivID CMS to enroll data such as a user picture or biometrics at issuance time.

The client-side plug-ins are defined as scriptable codes (for example, JavaScript) integrated into the HTML pages generated by ActivID CMS at the issuance workflow step for which the client plug-in has been configured. The client plug-in can in turn invoke custom controls.

The generic client plug-in can be used in conjunction with the enrollment plug- ins. The results of a client plug-in call can be forwarded to a server enrollment plug-in. Conversely, a server enrollment plug-in can be used to prepare data for a client plug-in.

The ActivID CMS plug-in configuration defines which plug-ins are to be invoked at each step and the input/output parameters for each plug-in.

About the Credential Provider SPI

The Credential Provider Service Provider Interface (SPI) allows ActivID CMS to integrate with third-party credential sources through third- party credential providers.

About the Card and Credential Management API (CCM API)

The following figure illustrates the card and credential interaction and management using the CCM API.

Card and Credential Management Using the CCMAPI

The CCM API facilitates programmatic management of devices and credentials, including allowing external applications to:

  • Remotely update the content of a device or smart card’s chip (Card synchronization),

  • Manage users’ personal data,

  • Request and manage device issuances,

  • Manage device credentials, and

  • Unlock devices.

Real-life integrations using the CCM API include:

  • Physical Access Integration (PACS)

  • Identity Management System Integration

  • External help desk applications

  • Customized device issuance/unlock kiosks

  • Batch management/issuance of devices

For detailed information about developing plug-ins using the Generic plug-in SPI, refer to About the Generic Plug-In SPI.

Practical Example 1: PACS Integration

The CCM API makes it possible for integrators to build their own badging stations 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. using ActivID CMS for the smart card contact chip encoding. Using the CCM API, developers can create applications that integrate ActivID CMS capabilities with physical access and ID management features that can be administered from a single point.

For example, you can use this API to turn a physical access system console into a card issuance station that does the following in a single step:

  • Prints user’s information on the card (for example name, photo).

  • Calls ActivID CMS to personalize the chip on the card for logical access (for example, enables secure log in to the user’s workstation).

  • Encodes the badge and provisions access for Physical Access Control.

The ActivID CMS CCM API streamlines the process of issuing multi-technology smart cards (chip and physical access), thereby reducing administration costs. Also, since the API can be integrated into badging stations that already issue cards, operators do not need special training to use the system.

This approach significantly reduces the cost, time, and effort required for an organization to successfully manage cards with contact chips. The CCM API makes it possible to develop a fully independent issuance and post-issuance station that has no link other than the one provided by the API to ActivID CMS.

Practical Example 2: IDMS-Card Request Provisioning

IDMSs 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. streamline the provisioning, update, and de-provisioning of smart cards. As with any credential, a smart card can be requested, updated, and terminated from within an IDMS by an ActivID CMS connector.

Device Request

A device issuance request can contain information such as a PIN and a Device Policy (a set of credentials that can be loaded on the card at synchronization time). Both can be determined by the IDMS based on the role or the organizational group.

Once the request has been provisioned, the card can then be synchronized on the ActivID CMS Operator or User Portal or by an external system (such as Batch issuance or PACS 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.) that leverages the CCM API.

Device Update

When a user changes roles, a device update request can automatically be provisioned with a target policy. Afterwards, the user can access the User Portal to automatically update the card and the associated credentials.

Device Termination

When users are terminated from the IDMS, their cards can be automatically terminated along with all other credentials/accounts managed by the IDMS. When a card is terminated using the CCM API, all credentials are revoked automatically.

Practical Example 3: Help Desk

Many companies use centralized custom help desk management applications. These applications have unified, branded Graphical User Interfaces and make it possible to manage most IT resources from a single help desk interface.

The ActivID CMS CCM API makes it possible for such systems to manage devices and credentials remotely and centrally along with all other credentials/accesses users may have. CCM allows an instance to:

  • Suspend/Resume/Revoke a device.

  • Suspend/Resume/Revoke one or several credentials from a device.

  • Compute response to a card PIN unlock challenge.

  • Set the initial password required for self-issuance of a blank card by a user.

  • Set security question answers for a user.

  • Get information about the content of a device.