CCM API Cookbook

This section acts as a CCM API cookbook by providing code snippets that demonstrate examples you can use to code specific use cases using the Java CCM API. The C++ code implementation should follow a very similar set of processes.

The use cases that comprise this CCM API cookbook are noted in the list below. Each use case also includes a procedure that provides an example of a use case (such as issuing a device, creating a user, synchronizing a device, or obtaining device status).

A typical CCM workflow is the issuance of a SecurityModule. To issue a card, complete the following steps:

  1. Open a SecurityModuleManager, a SyncManager, a UserManager, and a WalletManager session, as described in Java Example of Factory Use.

  2. Define the user on which to operate. This could be done by accessing a Human Resources database or an LDAP repository to obtain the unique UserId (such as the sAMAccountName) required by ActivID CMS.

    3. If the specified user does not exist in a database, then you can create the user using the createUser function of the UserManager. Enroll user data using the addEnrollmentData function of the UserManager.

  3. Use the getPlatformIdentifiers and identifySecurityModule methods to retrieve information from the device present in the reader. Use this information to create the SecurityModule object based on the information about the physical device.

    Copy 
    SecurityModuleId smId = smMgr.identifySecurityModule(CCMConstants. PLATFORM_CLASS_SMARTCARD, CCMConstantsplatformIds);
    WalletId walletId = walletMgr. getBoundWalletFromUser(userId);

  4. Retrieve the WalletId associated with the user using the getBoundWalletFromUser function of the WalletManager. Bind the SecurityModule (for example, the smart card) to the user using the bindSecurityModule function of the WalletManager.

    Copy 
    WalletId walletId = walletMgr. getBoundWalletFromUser(userId); try {
    walletMgr.bindSecurityModule(walletId, smId);
    }
    catch(SecurityModuleBoundException smbe) { if (log.isEnabledFor(Level.WARN)) {
    log.warn(smbe.getMessage());
    }
    }

  5. Set up the pin, reason, and event (optionally) parameters including their types, encoding values, and IDs.

    Copy 
    Parameter pinParam = new Parameter(CCMConstants.ACTION_RUNTIME_PARAM_PIN, pin); 
    Parameter reasonParam = new Parameter(CCMConstants.ACTION_RUNTIME_PARAM_REASON, reason); 
    Parameter eventParam = new Parameter(CCMConstants.ACTION_RUNTIME_PARAM_EVENTS "com.activcard.cms.service.tcd.subscribedEvents");
    Parameter[] actionParams = new Parameter[] {pinParam, reasonParam, eventParam};

  6. Set up the desired action type (for example, produce) and runtime parameters.

    Copy 
    Action action = new Action(); action.setApplicationSet(policy); action.setType(CCMConstants.ACTION_TYPE_PRODUCE); action.setRuntimeParameters(actionParams); action.setSecurityModuleIds(smIds);
    Action[] actions = new Action[] {action};

  7. Submit the requested actions (for example, produce) using the submitAction function of the WalletManager.

  8. Update the device using the synchronize function of the SyncManager.

    Copy 
    syncMgr.synchronize(CCMConstants.
    PLATFORM_CLASS_SMARTCARD, accessParams,
    new Parameter[] {pinParam, eventParam}, this);

  9. If the action type chosen is produce, perform device activation:

    Copy 
    smMgr.performProcess(smId, CCMConstants.
    PROCESS_ID_SM_ACTIVATE, null);

The initial password is used to authenticate the user during device self issuance. Before the initial password can be provisioned, the following requirements must be met:

  • The device must be bound to the user.

  • An issuance request with the specified device policy must exist.

  • The initial password must comply with the PIN policy specified in the device policy provision.

To provision the initial password, complete the following steps:

  1. Establish the wallet and credential manager clients.

    Copy 
    CredentialManager cm = …; WalletId walletId = …;

  2. Set up search criteria based on password credential type and wallet ID, and observe the following considerations:

    • The application ID is not necessary since setting the password is not associated with the device profile.

    • CRED_ID_TYPE_PASSWORD is the credential type for initial passwords.

      Copy 
      Criteria[] criteria = {new Criteria(CCMConstants.
      CRITERIA_CRED_TYPE, CCMConstants. CRITERIA_COMPARISON_EQUAL, CCMConstants. CRED_ID_TYPE_PASSWORD),
      new Criteria(CCMConstants. CRITERIA_CRED_PARENT_WALLET, CCMConstants.
      CRITERIA_COMPARISON_EQUAL, walletId.getId())
      };

  3. Find the credential IDs that meet the supplied search criteria:

    Copy 
    CredentialId[] credIds = cm.findCredentialIds(criteria, maxItem);

  4. At this point, there are two possibilities:

    • Either an initial password has already been provisioned, or

    • An initial password has not been provisioned.

    If an initial password has already been provisioned, then the update can occur based on the following conditions and tasks being met:

    • Once a credential that matches the supplied criteria has been found, get the credentials based on credential IDs:

      Copy 
      if (credIds.length == 1)
      Credential[] creds = cm.getCredentials(credIds);

    • Get the Input Requirements for an update based on the profile ID:

      Copy 
      EntryTemplate[] entries = cm.getProfileDynamicEntries(creds[0]. getProfileId());

    • getProfileDynamicEntries should return only one entry. You can set its initial password value using setValue:

      Copy 
      String initialPassword=... // Initial Password
      entries[0].setValue(initialPassword);

    • Once all inputs are collected from the user interface, perform an update:

      Copy 
      cm.updateCredential(credIds[0], CCMConstants.
      ACTION_ID_CRED_REPLACE, entries);

    If an initial password has not yet been provisioned, then you can import the initial password and perform the following:

    • Set up new search criteria:

      Copy 
      Criteria[] profCriteria = {new Criteria(CCMConstants.
      CRITERIA_CRED_TYPE, CCMConstants.CRITERIA_COMPARISON_EQUAL, CCMConstants.CRED_ID_TYPE_PASSWORD),
      new Criteria(CCMConstants. CRITERIA_CRED_PARENT_WALLET, CCMConstants.CRITERIA_COMPARISON_EQUAL,
      walletId.getId())
      };

    • Retrieve the IDs of all credential profiles that match the supplied criteria:

      Copy 
      ConfigurationId[] credProfIds = credMgr. findCredentialProfileIds(profCriteria, maxItems);

    • Throw an exception if there is no credential profile returned:

      Copy 
      if (credProfIds.length != 1) {
      throw new Exception("more than expected single credential profile returned");
      }

    • Get the list of runtime input requirements for the specified credential:

      Copy 
      EntryTemplate[] entries = credMgr. getProfileDynamicEntries(credProfIds[0]);

    • Create an array of credentials:

      Copy 
      Credential[] creds = { new Credential() }; creds[0].setProfileId(credProfIds[0]); CredentialElement credEl = new CredentialElement(); credEl.setId(entries[0].getKey()); credEl.setIsReference(false);
      String initialPassword = ..........;
      credEl.setValue(initialPassword);
      creds[0].setCredentialElements(new CredentialElement[] {
      credEl });

    • Import the set of externally formed credentials:

      Copy 
      credMgr.importCredentials(walletId, creds);

To set the security answer, complete the following steps:

  1. Establish the wallet and credential manager clients.

    Copy 
    CredentialManager cm = ...; WalletId walletId = ...;
    Note: The application ID is not necessary for setting up criteria based on security questions and answers.

  2. Set up search criteria based on security questions and credential type answers (the constant is CRED_ELEMENT_TYPE_SQ) and walletId:

    Copy 
    Criteria[] criteria = {
    new Criteria(CCMConstants.CRITERIA_CRED_TYPE, CCMConstants.CRITERIA_COMPARISON_EQUAL, CCMConstants.CRED_ID_TYPE_SQ),
    new Criteria(CCMConstants. CRITERIA_CRED_PARENT_WALLET, CCMConstants.CRITERIA_COMPARISON_EQUAL,
    walletId.getId())
    };
    Note: If more than one credential is returned, then an error has occurred.

  3. Get credential IDs based on supplied search criteria.

    Copy 
    CredentialId[] credIds = cm.findCredentialIds(criteria, maxItem);

  4. At this point, there are two possibilities:

    • Either the security question answers have been provisioned (and can therefore be updated), or

    • The required security question answers required must be imported.

    If the security question answers have already been provisioned (and can be updated), then make sure that the following conditions are met:

    • Get credentials based on credential IDs:

      Copy 
      if (credIds.length == 1){
      Credential[] creds = cm.getCredentials(credIds);

    • Using the profile ID, get the Input Requirements for the update.

      Copy 
      EntryTemplate[] entries = cm.getProfileDynamicEntries(
      creds[0].getProfileId());

    • For each entry, set the security question answer:

      Copy 
      for (int i = 0; i < entries.length; i++) {
      // Display the question
      System.out.println(entries[i].getLabel()");
      // Get the answer from the standard input or in another way
      String answer = .........;
      //Set the security question answer entries[i].setValue(answer);
      }

    • Once all necessary entries have been set, submit the change by invoking updateCredential:

      Copy 
      cm.updateCredential (credIds[0], CCMConstants.ACTION_ID_CRED_REPLACE, entries);

    If security question answers are not already provisioned, then the required answers must be imported. To do this, make sure that the following conditions are met:

    • Create a new array of CredentialElements. For each CredentialElement set the ID to the key corresponding to that Entry. For each CredentialElement, assign the security question answer as its value:

      Copy 
      for (int i = 0; i < entries.length; i++) {
      // Display the question
      System.out.println(entries[i].getLabel()");
      // Get theanswer from the standard input or other ways
      String answer = .........;
      System.out.println(entries[i].getLabel() + " : " +
      answer);
      CredentialElement credEl = new CredentialElement(); credEl.setId(entries[i].getKey()); credEl.setIsReference(false); credEl.setValue(answer);
      credElList.add(credEl);
      }

    • Once the CredentialElement array has been populated with the necessary entries, instantiate a new Credential object, assign it to the CredentialElements, and invoke the Import method:

      Copy 
      Credential[] creds = { new Credential() }; creds[0].setProfileId(credProfIds[0]); creds[0].setCredentialElements(credElList.toArray(
      new CredentialElement[credElList.size()]));
      cm.importCredentials(walletId, creds);

To get details about the content of a device, complete the following steps:

  1. Using the getBoundSMFromUser(...) method of the SecurityModuleManager class, obtain the security module IDs associated with a user:

    Copy 
    SecurityModuleId[] smIds =
    smMgr.getBoundSMFromUser(userId);

  2. Obtain the SecurityModule object using the getSecurityModule(...) method of the SecurityModuleManager and retrieve relevant information (such as device policy, creation date, card state, and serial number):

    Copy 
    for (int i = 0; i < smIds.length; i++) { SecurityModule sm = smMgr.
    log.info(“Device Policy: “ + sm.getApplicationSet()
    .toString());
    log.info(“Date Created: “ + sm.getCreated()); log.info(“State: “ + sm.getState()); log.info(“Device type and serial number: “ +
    sm.getId());
    }

To get the initial PIN, complete the following steps:

  1. Get the SecurityModule:

    Copy 
    SecurityModule smo = smMgr.getSecurityModule(smId);

  2. Get the credentials for the SecurityModule:

    Copy 
    Credential[] creds = smo.getCredentials();

  3. Find the PIN credential.

    Note: The CCM constant associated with the PIN credential element is CRED_ID_TYPE_PIN.
    Copy 
    for (int i = 0; i < creds.length; i++){
    if (creds[i].getType().equals(CCMConstants. CRED_ID_TYPE_PIN){
    // Get the set of credential elements for each credential: 
    CredentialElement[] credEls = cred[i].getCredentialElements();
    // Iterate through credential elements looking for initial PIN 
    for (int j = 0; j < credEls.length; i++){
    if(credEls[j].getType().equals(CCMConstants. CRED_ELEMENT_ID_PIN){
       return credEls[j].getValue();
    }

To retrieve all certificates from PKI credentials, complete the following steps:

  1. Retrieve all the certificates that are bound to a specified wallet:

    Copy 
    WalletId walletId = walletMgr. getBoundWalletFromUser(userId);
    Criteria[] criterias = {
    new Criteria(CCMConstants.CRITERIA_CRED_TYPE, CCMConstants.CRITERIA_COMPARISON_EQUAL, CCMConstants.CRED_ID_TYPE_PKI),
    new Criteria(CCMConstants.
    CRITERIA_CRED_PARENT_WALLET, CCMConstants.CRITERIA_COMPARISON_EQUAL,
    walletId.getId())
    };

  2. Find the actions that meet the supplied criteria:

    Copy 
    CredentialId[] credIds = credMgr. findCredentialIds(criterias, maxItems);
    Credential[] creds = credMgr.getCredentials(credIds);

  3. Print all the certificates in each PKI credential:

    Copy 
    for(int i=0; i< elements.length; i++) { CredentialElement[] elements = creds[i].
    getCredentialElements();
    System.out.println("-----BEGIN CERTIFICATE-----"); System.out.println(elements[0].getValue()); System.out.println("-----END CERTIFICATE-----");
    }

To initiate the suspension, resumption, or revocation workflow with the supplied parameters, follow the examples below:

To suspend:

Copy 
smMgr.performProcess(smId, CCMConstants.
PROCESS_ID_SM_SUSPEND, new Parameter[0]);

To resume:

Copy 
smMgr.performProcess(smId, CCMConstants.
PROCESS_ID_SM_RESUME, new Parameter[0]);

To revoke:

Copy 
smMgr.performProcess(smId, CCMConstants.
PROCESS_ID_SM_REVOKE, new Parameter[0]);

To suspend, resume, or revoke a PKI credential, complete the following steps:

  1. Instantiate and open a session to the CredentialManager and WalletManager client.

  2. Set up search criteria based on credential type (optional), parent wallet (required), and application ID (required).

    Copy 
    //In the sample code, PKI1 is the name of an application
    Criteria[] criteria = {
    new Criteria(CCMConstants.CRITERIA_CRED_TYPE, CCMConstants.CRITERIA_COMPARISON_EQUAL,
    CCMConstants.CRED_ID_TYPE_PKI), new Criteria(CCMConstants.
    CRITERIA_CRED_APPLICATION_ID, CCMConstants.CRITERIA_COMPARISON_EQUAL, "PKI1"),
    new Criteria(CCMConstants.
    CRITERIA_CRED_PARENT_WALLET, CCMConstants.CRITERIA_COMPARISON_EQUAL, walletId.getId()) };

  3. Find the credential IDs of all credentials to be suspended, resumed, or revoked (with the method used, findCredentialIds).

    Copy 
    CredentialId[] credIds = cm. findCredentialIds(criteria, maxItem);

  4. Initiate the suspension, resumption, or revocation workflow using the supplied parameters (with the method used, performProcess).

    • To suspend, use the following:

      Copy 
      cm.performProcess(credIds[0], CCMConstants.
      PROCESS_ID_CRED_SUSPEND, new Parameter[0]);

    • To resume, use the following:

      Copy 
      cm.performProcess(credIds[0], CCMConstants.
      PROCESS_ID_CRED_RESUME, new Parameter[0]);

    • To revoke, use the following:

      Copy 
      cm.performProcess(credIds[0], CCMConstants.
      PROCESS_ID_CRED_REVOKE, new Parameter[0]);

To compute an unlock response, complete the following steps:

  1. Set up search criteria based on credential type (optional), parent wallet (required), and application ID (required).

    Copy 
    Criteria[] criteria =
    {new Criteria(CCMConstants.CRITERIA_CRED_TYPE, CCMConstants.CRITERIA_COMPARISON_EQUAL, CCMConstants.CRED_ID_TYPE_PIN),
    new Criteria(CCMConstants.
    CRITERIA_CRED_APPLICATION_ID, CCMConstants.CRITERIA_COMPARISON_EQUAL, CCMConstants.CRED_ID_TYPE_PIN),
    new Criteria(CCMConstants.
    CRITERIA_CRED_PARENT_WALLET, CCMConstants.CRITERIA_COMPARISON_EQUAL, walletId.getId())
    };

  2. Find credential IDs for all credentials to be unlocked:

    Copy 
    CredentialId[] credIds = cm.findCredentialIds(criteria, maxItem);

  3. Initiate an offline unlock transaction:

    Copy 
    TransactionId txId = cm.operateCredential(credIds[0], CCMConstants.OPER_ID_CRED_UNLOCK, new Parameter[0]);

  4. Continually check for pending external operations:

    Copy 
    ExternalOperation[] exOps = new ExternalOperation[0];
    do{
    exOps = cm.getNextExternalOperations(txId, exOps);
    // do step 5 here 
    ...
    } while( exOps.length > 0);

  5. Iterate through the returned list of external operations:

    Copy 
    for (int i = 0; i < exOps.length; i++){
    String scriptType = exOps[i].getType(); String script = exOps[i].getScript();
    // do the following steps here 
    ...
    }

    • Check the script type (AI) and the script (challenge) itself:

      Copy 
      if (scriptType.equals(“AI”) &&
      script.equals(CCMConstants.CRED_EXOP_GETCHALLENGE))
      // Note: Currently the value of the script type is always “AI”
      // To obtain the challenge from a card that is offline
      // (For example: ActivClient)
      String challenge = ..........; // challenge code format
      // XXXXXXXXXXXXXXXX
      // Set the challenge as the response parameter for the external operation Parameter[] responseParams = { new Parameter (
      CCMConstants.CRED_EXOP_GETCHALLENGE_RESPONSE, challenge);
      exOps[i].setResponseParameters(responseParams);
      }

    • Check the script type (AI) and the script (unlock) itself:

      Copy 
      else if (scriptType.equals(“AI”) &&
      script.equals(CCMConstants.CRED_EXOP_UNLOCK)){
      /* Note: At this point, the script indicates the unlock code has been provisioned, and an offline unlock is requested */ System.out.println(exOps[i].getParameter()[0]);
      }

  6. Commit the credential transaction outside the do loop:

    Copy 
    cm.commitCredentialTransaction(txId);
Note: The challenge that is returned from the ActivID CMS server is set in the Response parameter of the external operation.

Before you can create a new user, you first have to obtain such LDAP attributes as:

  • parentDN

  • sAMAccountName

  • cn

  • sn

  • givenName

Once you have obtained these LDAP attributes, follow these steps to create a new user:

  1. Obtain the LDAP attributes necessary for creating a user in Active Directory (for example, parentDN, sAMAccountName, cn, sn, and givenName).

  2. Set up the enrollment data (user attributes) that must be conveyed to ActivID CMS:

    Copy 
    EnrollmentDataValue[] enrollmentValue =
    new EnrollmentDataValue[5]; enrollmentValue[0] = new EnrollmentDataValue(); enrollmentValue[0].setId(“parentDN”); enrollmentValue[0].setType(EnrollmentData.
    ENROLLMENT_DATA_TYPE_STRING);
    enrollmentValue[0].setEncoding(EnrollmentData.
    ENROLLMENT_DATA_ENCODING_NONE); enrollmentValue[0].setValue(parentDN); enrollmentValue[1] = new EnrollmentDataValue(); enrollmentValue[1].setId(“sAMAccountName”); enrollmentValue[1].setType(EnrollmentData.
    ENROLLMENT_DATA_TYPE_STRING);
    enrollmentValue[1].setEncoding(EnrollmentData.
    ENROLLMENT_DATA_ENCODING_NONE); enrollmentValue[1].setValue(sAMAccountName); enrollmentValue[2] = new EnrollmentDataValue(); enrollmentValue[2].setId(“cn”); enrollmentValue[2].setType(EnrollmentData.
    ENROLLMENT_DATA_TYPE_STRING);
    enrollmentValue[2].setEncoding(EnrollmentData.
    ENROLLMENT_DATA_ENCODING_NONE); enrollmentValue[2].setValue(cn); enrollmentValue[3] = new EnrollmentDataValue(); enrollmentValue[3].setId(“sn”); enrollmentValue[3].setType(EnrollmentData.
    ENROLLMENT_DATA_TYPE_STRING);
    enrollmentValue[3].setEncoding(EnrollmentData.
    ENROLLMENT_DATA_ENCODING_NONE);
    enrollmentValue[3].setValue(sn); enrollmentValue[4] = new EnrollmentDataValue(); enrollmentValue[4].setId(“givenName”); enrollmentValue[4].setType(EnrollmentData.
    ENROLLMENT_DATA_TYPE_STRING);
    enrollmentValue[4].setEncoding(EnrollmentData.
    ENROLLMENT_DATA_ENCODING_NONE);
    enrollmentValue[4].setValue(givenName);

  3. Instantiate a user ID object using the LDAP attribute sAMAccountName:

    Copy 
    UserId userId = new UserId(sAMAccountName);

  4. Instantiate a User object using the enrollment data and the user ID:

    Copy 
    User user = new User(userId, enrollmentValue);
    Note: The unicodePwd attribute (user password) can only be changed if the connection to the Active Directory is secured using SSL or LDAPS (LDAP over SSL).

  5. Use the createUser method of the UserManager class to create a new user:

    Copy 
    userMgr.createUser(user);

To obtain device information (such as the card ATR and serial number) when the device is present in the reader, perform the following:

Copy 
Parameter[] platformIds = syncMgr. getPlatformIdentifiers(CCMConstants. PLATFORM_CLASS_SMARTCARD, accessParams);

To generate a security module id object with ATR and serial number when the smart card is not physically available, perform the following:

Copy 
// Static CUID value
String CUID = "20505000428830000001";
/**
* PlatformIds contain the card ATR, CUID.
* ATR and CUID are the constituents of security module id.
*/
Parameter[] platformIds = new Parameter[2];
platformIds[0] = new Parameter();
platformIds[0].setId(CCMConstants.
PLATFORM_ID_SMARTCARD_ATR); platformIds[0].setType(TYPE_STRING); platformIds[0].setEncoding(ENCODING_NONE); platformIds[0].
setValue("3b7b1800000031c06477e30300829000");
platformIds[1] = new Parameter();
platformIds[1]. setId("securitymodule.smartcard.gp20.CUID");
platformIds[1].setType(TYPE_STRING); platformIds[1].setEncoding(ENCODING_NONE); platformIds[1].setValue(CUID); SecurityModuleId smId = smMgr.
identifySecurityModule(CCMConstants. PLATFORM_CLASS_SMARTCARD, platformIds);

To obtain the walletId and the SecurityModuleId of a user, perform the following:

Copy 
SecurityModuleId smId = smMgr.identifySecurityModule(CCMConstants. PLATFORM_CLASS_SMARTCARD, CCMConstantsplatformIds);
WalletId walletId = walletMgr. getBoundWalletFromUser(userId);

To bind the device to a user, perform the following:

Copy 
try {
}
walletMgr.bindSecurityModule(walletId, smId);
catch (SecurityModuleBoundException smbe) {
if (log.isEnabledFor(Level.WARN)) {
log.warn(smbe.getMessage());
}
}

To set the PIN and reason parameters, perform the following:

Copy 
pinParam.setId(CCMConstants.ACTION_RUNTIME_PARAM_PIN); pinParam.setValue(pin); pinParam.setEncoding(ENCODING_NONE); pinParam.setType(TYPE_STRING);
reasonParam.setId(CCMConstants.
ACTION_RUNTIME_PARAM_REASON); reasonParam.setValue(reason); reasonParam.setEncoding(ENCODING_NONE); reasonParam.setType(TYPE_STRING);

To define or set a policy, perform the following:

Copy 
Action action = new Action();
action.setApplicationSet(policy)

To list the device policies that could be assigned to a device, perform the following:

Copy 
try {
}
Criteria[] criterias = new Criteria[0];
policies = walletMgr. findApplicationSets(criterias, maxItem);
for (int j = 0; j <policies.length; j++) System.out.println(“Policy “+ j + “
: “+ policies[j]);
catch (Exception ex) {
if (log.isEnabledFor(Level.WARN)) {
log.warn(ex.getMessage());
}
}

To submit a request (for example, issuance request), perform the following:

Copy 
Parameter[] actionParams = new Parameter[] {reasonParam}; Action action = new Action(); action.setRuntimeParameters(actionParams); action.setApplicationPolicy(policy);
Action[] actions = new Action[](action};
walletMgr.submitActions(walletId, actions, null);

To perform device synchronization of a pending request, perform the following:

Copy 
syncMgr.synchronize( CCMConstants.
PLATFORM_CLASS_SMARTCARD, accessParams, new Parameter[] {pinParam};

To perform device activation, perform the following:

Copy 
// Note: This method call is necessary ONLY if the Action Type is PRODUCE.
// It is not needed if the Action Type is ISSUANCE. 
smMgr.performProcess(smId, CCMConstants. PROCESS_ID_SM_ACTIVATE, null);

To perform a PIN unlock request and submit it, perform the following:

Copy 
// Create a PIN UNLOCK action Parameter pinParam = new Parameter(); String pin = ......;
pinParam.setId(CCMConstants.ACTION_RUNTIME_PARAM_PIN); pinParam.setParam.setValue(pin); pinParam.setEncoding(Parameter.ENCODING_NONE); pinParam.setType(Parameter.TYPE_STRING);
Parameter[] actionParams = new Parameter[] {pinParam}; SecurityModuleId[] smIds = new SecurityModuleId[]
{ smId };
Action action = new Action(); action.setType(CCMConstants.ACTION_TYPE_PINUNLOCK); action.setRuntimeParameters(actionParams); action.setSecurityModuleIds(smIds);
Action[] actions = new Action[]{action};
// Submit the specified pin unlock action walletMgr.submitActions(walletId, actions, null);

The following sample code illustrates the authentication process using a specific provider:

Copy 
private void connect(String host, String port, String client, String pwd, String CA)
throws Throwable {
String configurationFile = "...";
SunPKCS11 provider = new sun.security.pkcs11.
SunPKCS11(configurationFile); Security.addProvider(provider); System.setProperty("javax.net.ssl.keyStoreType",
"PKCS11");
KeyStore keyStore = KeyStore.getInstance("PKCS11", provider);
keyStore.load(null, pwd.toCharArray());
KeyStore trustStore = KeyStore.getInstance("jks", "SUN");
trustStore.load(null, null);
FileInputStream in = new FileInputStream(CA);
 
Certificate caCert = CertificateFactory. getInstance("X.509").generateCertificate(in);
trustStore.setCertificateEntry("cert-0", caCert);
in.close();
Map<String, Object> config = new HashMap<String, Object>();
 
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);
 
smMgr = SecurityModuleManagerFactory. newInstance(config);
smMgr.openSession(null);
smMgr.getVersion();
 
syncMgr = SyncManagerFactory.newInstance(config);
syncMgr.openSession(null);
syncMgr.getVersion();
 
userMgr = UserManagerFactory.newInstance(config);
userMgr.openSession(null);
userMgr.getVersion();
 
walletMgr = WalletManagerFactory. newInstance(config);
walletMgr.openSession(null);
walletMgr.getVersion();
}

The following sample code illustrates the device replacement workflow:

Copy 
String[] reason ={"FORGOTTEN", "LOST", "DAMAGED", "EXPIRED", "STOLEN"};
// .. Choose the appropriate reason int i = .... // selected reason
// Replacement reason
Parameter replacementReasonParam = new Parameter(); replacementReasonParam.setType(TYPE_STRING); replacementReasonParam.setEncoding(ENCODING_NONE); replacementReasonParam.setValue(reason[i]); replacementReasonParam.setId(CCMConstants.
ACTION_RUNTIME_PARAM_REASON);
Parameter[] actionParams = new
Parameter[]{replacementReasonParam};
Action action = new Action(); action.setType(CCMConstants.ACTION_TYPE_ISSUANCE); action.setRuntimeParameters(actionParams);action. setApplicationSet(policy);
// Only if ActivID CMS is configured with Multi device features
SecurityModuleId[] smIds = new SecurityModuleId[] { oldSMId, newSMId };
action.setSecurityModuleIds(smIds);
Action[] actions = new Action[]{action};
// Submit the specified card replacement action walletMgr.submitActions(walletId, actions, null);

The following sample code illustrates a device termination. Note that unbinding a device from the user is similar to termination (in that this revokes the device credentials).

Copy 
WalletId walletId = walletMgr. getBoundWalletIdFromUser(userId);
SecurityModuleId[] smIds = smMgr. getBoundSMFromUser(userId);
try {
/*
* Unbind all devices bound to the user
*/
for (int i = 0; i < smIds.length; i++) {
walletMgr.unbindSecurityModule(walletId, smIds[i]);
}
}
catch(NoSuchWalletException nswe) {
if (log.isEnabledFor(Level.WARN))
log.warn(nswe.getMessage());
}

To recycle a device for new issuance process, perform the following:

Copy 
// Create an action type
Action action = new Action();
// Set its action type to Recycle action.setType(CCMConstants.ACTION_TYPE_RECYCLE); Action[] actions = new Action[]{action};
// Submit the request walletMgr.submitActions(walletId, actions, null);
// Update the device syncMgr.synchronize(CCMConstants.
PLATFORM_CLASS_SMARTCARD, accessParams, new Parameter[0], null);

To obtain the list of pending requests, perform the following:

Copy 
try {
// Obtain wallet ID
WalletId walletId = walletMgr. getBoundWalletFromUser(userId);
// Supply appropriate criteria Criteria[] criterias = new Criteria[1]; criterias[0] = new Criteria(); criterias[0].setId(CCMConstants.
CRITERIA_ACTION_PARENT_WALLET);
criterias[0].setComparison(CCMConstants.
CRITERIA_COMPARISON_EQUAL);
criterias[0].setValue(walletId.getId());
// Find actions matching supplied criteria
Action[] actions = walletMgr. findActions(criterias, maxItem);
System.out.println("List of pending requests: ");
for (int i = 0; i < actions.length; i ++){
System.out.println("Request Type "+ i + ": "+
actions[i].getType());
}
}
catch (Exception ex) {
if (log.isEnabledFor(Level.WARN))
log.warn(ex.getMessage());
}
}

To clear the pending requests, perform the following:

Copy 
Criteria[] criterias = new Criteria[1]; criterias[0] = new Criteria(); criterias[0].setId(CCMConstants.CRITERIA_ACTION_STATUS); criterias[0].setComparison(CCMConstants.
CRITERIA_COMPARISON_EQUAL);
criterias[0].setValue(CCMConstants.
ACTION_STATUS_PENDING);
String[] actionIds = walletMgr. findActionIds(criterias, 1);
for(int i=0; i<actionIds.length; i++) { System.out.println("Remove: " + actionIds[i]); walletMgr.performActionProcess(actionIds[i],
CCMConstants.ACTION_PROCESS_CANCEL, new
Parameter[0]);
}

To get enrollment data for user data registration, perform the following:

Copy 
String[] attributes = new String[] {"sAMAccountName", "cn"};
EnrollmentData[] data = userMgr.getEnrollmentData(userId, attributes);
for(int i=0; i<data.length; i++) {
EnrollmentDataValue edv = (EnrollmentDataValue)
data[i]; System.out.println(
"Enrollment Data: " + edv.getId() + " = " +
edv.getValue() );
}

To get the current status of the card, perform the following:

Copy 
SecurityModuleId[] smIds =
smMgr.getBoundSMFromUser(userId);
for (int j = 0; j < smIds.length; j++) {
String status = smMgr.getLifecycleStatus(smIds[j]); System.out.println("Card Status: " + status);
}

To get the VCI Pairing Code, complete the following steps:

  1. Get the SecurityModule:

    Copy 
    SecurityModule smo = smMgr.getSecurityModule(smId);

  2. Get the credentials for the SecurityModule:

    Copy 
    Credential[] creds = smo.getCredentials();

  3. Find the VCI credential.

    Note: The CCM constant associated with the VCI credential element is CRED_ID_TYPE_VCI.

  4. Find the Pairing Code element in the credential.

    Note: Note: The CCM constant associated with the pairing code credential element is CRED_ELEMENT_ID_VCI_PAIRING_CODE.
    Copy 
    for (int i = 0; i < creds.length; i++){
    if (creds[i].getType().equals(CCMConstants.CRED_ID_TYPE_VCI){
    // Get the set of credential elements for each credential:
    CredentialElement[] credEls = cred[i].getCredentialElements();
    // Iterate through credential elements looking for initial PIN
    for (int j = 0; j < credEls.length; i++){
    if(credEls[j].getType().equals(CCMConstants.CRED_ELEMENT_ID_VCI_PAIRING_CODE){
        return credEls[j].getValue();
    }