Installing and Using CCM Components
Connecting CCM to ActivID CMS
The CCM client connects to ActivID CMS using web services over Secure Hypertext Transfer Protocol (HTTPS) with mutual authentication. In this connection type, an ActivID CMS-based application needs an SSL Client Certificate and key pair registered as a valid ActivID CMS Operator (client authentication), and the trusted Root CA certificate (server authentication).
The ActivID CMS-based application is only allowed to perform operations that the ActivID CMS Operator’s certificate authorizes it to perform. For more information on Roles, refer to Managing Roles.
Credential Manager, Security Module Manager, User Manager, and Wallet Manager all use SSL/TLS with mutual authentication. The Synchronization Manager is a server-side-only component and does not use the mutually-authenticated client/server SSL/TLS.
Java Authentication
For a Java-based CCM application, the client certificate, key pair, and root CA certificate must be in a keystore and a truststore that are accessible to the Java application. If a dedicated truststore is not passed in parameter, the default Java truststore is used to verify the chain of trust. Smart card-based authentication can also be implemented using the Java PKCS#11 interface and ActivID ActivClient.
Sample Authentication Code
The following sample of authentication code illustrates a Java-based CCM application:
/******************************************************
Client certificate and key pair are read out of a P12.
The Root CA Certificate is read out of a JKS keystore.
*******************************************************/
KeyStore keyStore = KeyStore.getInstance("PKCS12", "SunJSSE");
KeyStore trustStore = KeyStore.getInstance("jks", "SUN");
InputStream inputStream = new FileInputStream(client);
keyStore.load(inputStream, pwd.toCharArray());
inputStream.close(); trustStore.load(null, null); inputStream = new FileInputStream(CA);
Certificate caCert = CertificateFactory.getInstance( "X.509").generateCertificate(inputStream);
trustStore.setCertificateEntry("cert-0", caCert);
inputStream.close();
Map config = new HashMap();
config.put(CCMConstants.CONFIG_KEYSTORE, keyStore); config.put(CCMConstants.CONFIG_KEYSTORE_PWD, pwd); config.put(CCMConstants.CONFIG_TRUSTSTORE, trustStore); config.put(CCMConstants.CONFIG_HOST_NAME, host); config.put(CCMConstants.CONFIG_HOST_PORT, port);
userMgr = UserManagerFactory.newInstance(config);
userMgr.openSession(null);
userMgr.getVersion();Windows Authentication
Using native DLLs, the client certificate and key pair and root CA certificate must be registered in the CAPI certificate store accessible by the operator running the CCM API-based application. To authenticate using the CCM API for C++, the client application must provide the certificate serial number and the certificate issuer with the following two parameters:
-
CONFIG_CERTSERIAL—Serial number of a certificate for SSL/TLS
-
CONFIG_CERTISSUER—Subject DN string of CA that issued the certificate for SSL/TLS
For example, the certificate issuer is: CN=AI Commander01 CA, DC=commander01, DC=com, and the certificate serial number is: 15a041fe000000000013.
Creating CCM Application in Java
The <DISK>/SDK/API/CCM/Java folder contains the Java code distribution of the CCM API. The <DISK>/SDK/API/CCM/Java/lib folder contains the .jar files (listed below) to be added to the CCM-based Java application.
The following .jar files are found in the SDK/API/CCM/Java/lib folder:
ac-ccm-api-jaxws.jar
ac-ccm-api.jar
ac-ccm-session.jar
ac-cms-ccm-cred.jar
ac-cms-ccm-securitymodule.jar
ac-cms-ccm-sync.jar
ac-cms-ccm-user.jar
ac-cms-ccm-wallet.jar
ac-interfaces.jar
acjnicoe.jar
ac_localization.jar
ai-coe-bsi.jar
FastInfoset.jar
gmbal-api-only.jar
ha-api.jar
jakarta.activation.jar
jakarta.annotation-api.jar
jakarta.jws-api.jar
jakarta.mail.jar
jakarta.xml.bind-api.jar
jakarta.xml.soap-api.jar
jakarta.xml.ws-api.jar
jaxb-impl.jar
jaxb-jxc.jar
jaxb-xjc.jar
jaxws-rt.jar
jaxws-tools.jar
management-api.jar
mimepull.jar
policy.jar
saaj-impl.jar
slf4j-api-1.7.36.jar
stax-ex.jar
stax2-api.jar
streambuffer.jar
woodstox-core.jar
Sample CCM Java-Based Application
The CMS_home_directory/SDK/API/CCM/Java/sample folder contains sample Java code. The TestCCM.java application in the sample directory implements several functions just like a typical CCM API based-application would including the following:
- 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.
-
produce (issuance)
-
recycle
-
post-issuance
-
PIN unlock
-
-
IDPRS / Help Desk Application:
-
user attribute management (CPR for PIV issuance)
-
For more information, see the CCM API Cookbook.
Creating CCM Application in C++
The C++ related CCM directories contain specific sets of files:
-
The <DISK>/SDK/API/CCM/cpp/bin directory contains standard .dll files that must be linked into the C++ application for either x86win32 or x64win32 platforms with Unicode Character Set.
-
The <DISK>/SDK/API/CCM/cpp/include directory contains the CCM header files.
-
The <DISK>/SDK/API/CCM/cpp/lib directory contains the CCM static libraries.
|
Directory |
Contents |
|---|---|
|
SDK\API\CCM\cpp\bin\x64win32\ |
|
|
SDK\API\CCM\cpp\bin\x86win32\ |
|
|
SDK\API\CCM\cpp\include |
|
|
SDK\API\CCM\cpp\lib\x64win32 |
|
|
SDK\API\CCM\cpp\lib\x86win32 |
|
Required Libraries and Files
In the Microsoft runtime environment, the MS-Visual Studio 2022 runtime library is also required:
The <DISK>/SDK/API/CCM/cpp/sample directory contains sample code and an initial project for testing the sample code.
The testCCM.cpp sample application in the sample directory implements several functions like a typical CCM API based-application would, which includes the following:
-
Device issuance (binding, action submission, synchronization, and activation)
-
Device recycle (returning a device to a blank state by unbinding, action submission, and synchronization)
-
Card unlock and PIN unlock
-
Clearance of pending/failed device production requests
-
User creation
Compile Settings
The compile settings include the following requirements:
-
CCM applications that are created using C++ must be built using either the multi-threaded DLL or multi-threaded Debug DLL option.
-
To comply with the default configuration of Visual Studio 2022, the Yes (native wchar) configuration is used.
-
The Character Set must be set to Use Unicode Character Set
Memory Management Guidelines for C++ CCM API Applications
It is important to establish and adhere to a set of well-defined rules for memory management in the CCM API. Particularly with C/C++, memory management is an extremely important consideration. If there are resources being unwisely consumed or if you encounter memory leaks, this may cause errors to occur and performance may be impacted. You can prevent these potential conditions by observing the following rules:
-
Any memory object that is created by the calling application (client) and passed to the CCM API must also be released by the client.
-
Any memory object that is returned by the CCM API must also be released by the client.
-
Avoid the C-style memory functions malloc and free and all of their variants.
-
Always use factories to instantiate managers; never call the constructors directly.
