Developing and Configuring a Static Data Plug-In

To develop a static data Cardholder-related information including things such as health benefits, biometrics, unique organizational identifiers, or unique personal identifiers that rarely change. plug-in, complete the following steps:

1. Define the parameters needed by the plug-in and for each parameter specify the following:

   • If the parameter is visible (meaning that the parameter is displayed in the ActivID CMS user interface during device issuance) or modifiable (meaning it is an editable field in the ActivID CMS user interface).

   • If the parameter is mandatory for the plug-in. Some parameters may be mandatory for the plug-in to function; others may be optional. For example, if the plug-in has a default value that it uses if the parameter is not specified, the parameter may be optional.

   • The source of the parameter’s initial value. The source of the parameter can be either the LDAP or the name of one of the generic server plug-ins.

   • The type—Byte, Integer, String, …

   • The key—Tag/Numbers, cacert_path, …

2. Develop the plug-in class. Specifically, implement the following methods:

   • init()

   • computeCredentialParameters()

   In the init() method, save the parameter values and/or use these values to retrieve other data from the system or another application.

   In the computeCredentialParameters() method, compute and return the contents of the GC applet. Depending on the device profile An XML file that contains information about all the applets and applet instances that are to be loaded onto the device., the content returned for the GC applet may be one of the following:

   • Separate Tag and Value buffers. This applies to device profiles based on GSC-IS Government Smart Card-Interoperability Standard: This is the United States Government Smart Card-Interoperability Standard as defined by the National Institute of Standards and Technology (NIST). applets and for these the hash map contains the following keys that provide the contents of the tag and Value buffers, respectively:

     • persoGC/BufferValue/BufferT

     • persoGC/BufferValue/BufferV

   • A single Tag-Length-Value (TLV) buffer. This applies to PIV Personal Identity Verification (technical standard of "HSPD-12") device profiles and for these the samba contains the following key that provide the contents of the TLV buffer for the PIV object to be personalized:

     • persoGC/BufferValue/BufferV

   In Windows-based systems, when the plug-in is loaded by ActivID CMS, its working directory is located in the following location:

   %PROGRAMDATA%\HID Global\Credential Management System\custom.war\WEB-INF\lib

3. Package your plug-in class in a .jar file and put it and any related third-party packages into the following folder:

   %PROGRAMDATA%\HID Global\Credential Management System\custom.war\WEB-INF\lib

4. Add plug-in entries in the plugins.properties file on the ActivID CMS Portal. The file is located in the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\ directory.

   Example: Declaring a New Plug-In (sampleplugin)

   Copy

   // add the plug-in to ActivID CMS Server plug-in list
        plugins = intermediate_certificate, sampleplugin
   // add the entry that defines the Java implementation class of the plug-in
        sampleplugin.class=com.company.plugins.SamplePlugin

5. Add the plug-in definition into the <p:staticcredentialplugins> section of the selected device profile definition. Delimit the plug-in definition using the <p:staticcredentialplugin> and </p:staticcredentialplugin> tags as shown in Syntax of the Device Profile Section (p:staticcredentialplugin).

   In Example 2, three parameters are defined: SampleConfigFile, employee_name, and employee_mail.

   Example: Three Parameters Defined

   Copy

   <p:staticcredentialplugin name="sample plug-in example" type="sampleplugin">
     <p:params>
             <p:param name="Sample Config File" type="String" key="SampleConfigFile" visible="false">
                  <p:value>
                       C:\ProgramData\HID Global\Credential Management System\Shared Files\sampleplugin.properties
                  </p:value>
             </p:param>
             <p:param
                       name="Employee name" type="String" key="employee_name" visible="true" modifiable="false" initsource="ldap" initsourceparam="cn"/>
   <p:param
                      name="Employee mail" type="String" key="employee_mail" visible="true" modifiable="true" mandatory="true">
             </p:param>
     </p:params>
   </p:staticcredentialplugin>

   The device profile must define a data storage application (the GC applet) to be used with the plug-in. This is the device application that stores the data retrieved by the plug-in. To do this in the device profile XML file, you must set the attribute useplugin of the data storage application to true as shown in the following example.

   Example: Defining a data storage application

   Copy

   <p:application name="DataStorage1" type="GC" optional="true" useplugin="true" >
        <p:params/>
        <p:actions/>
   </p:application>

6. Restart the IIS service and CMS Server services on the ActivID CMS server.

7. Define a device policy that uses the selected device profile and associate the plug-in with a data storage application (GC applet). To create device policies, see Creating a Device Policy.

To compile the static data plug-in, the following external .jar files must be added to the project:

• aims-spi.jar

• ac-interfaces.jar

• slf4j-api-2.0.12.jar

These files are located in the cms_install_dir\aims.war\WEB-INF\lib directory, where cms_install_dir represents the installation directory of ActivID CMS.

The XML syntax of the device profile definition file is listed as follows:

<p:staticcredentialplugin name="displayable_name_of_the_plug-in" type="plug-in_entry_in_plugins.properties">    <p:params>
    <!—list of plug-in parameters -->
<p:param name="displayable_name_of_the_parameter"
 
        <!— type Values: String, Integer, or byte[]-->
        type="type_of_the_param"
        key="name_used_by_the_plug-in_to_retrieve_the_parameter_value"
        <!— visible Values: either true or false;
        if true, the parameter is visible by user at issuance time -->
        visible="flag"
        <!— modifiable Values: either true or false; if true, the parameter is modifiable by user 
        at issuance time -->
        modifiable="flag"
        <!— mandatory Values: either true or false; if true, the parameter is mandatory and a value 
        must be defined else the issuance will fail -->
        mandatory="flag"
        <!— The initsource parameter is optional; it defines an AIMS source for the parameter; 
        in the current version the only possible value is ldap
        -->
        <!— Note that even when the source of the parameter is an output of an enrollment plug-in, 
        the initsource value shall be set to ldap. This is related to the fact that ActivID CMS internally 
        manages the enrollment plug-in values as extensions of the LDAP user schema. -->
        initsource="optional parameter"
 
        <!— The initsourceparam parameter specifies the name of the parameter in the source. 
            For example, if the source is LDAP, the value might be: initsourceparam="emailAddress" -->
        <!— Note: When the source parameter is an output of an enrollment plug-in, the initsourceparam
            shall be: enrollmentplugin:sourceparameter where enrollmentplugin is the name of the 
            enrollment plug-in as specified in the enrollment plug-in configuration file and parameter is 
            the name of the parameter. For more information, read the Generic Plug-in SPI Developer
            Guide. -->
        initsourceparam="name_of_the_parameter_in_the_source"
 
        <!—list of parameter default values -->
        <p:value>the default value of the parameter</p:value>
    </p:param>
</p:params>
</p:staticcredentialplugin>

This example shows how to use a plug-in to retrieve data from a file, from an LDAP source, and from the user. This data can then be stored in the GC applet.

The sampleplugin defines three parameters, which are described in the following procedure and Example: Using a Plug-In for Retrieving Data:

• SampleConfigFile

• employee_name

• employee_mail

The SampleConfigFile parameter type is String. It is not visible to, nor is it modifiable by, the ActivID CMS operator. This parameter type specifies the name of the file that the plug-in opens and from which reads data.

The employee_name parameter is initialized with the CN LDAP attribute of the user by the ActivID CMS Portal. This parameter is visible to the user, but is not modifiable by the user of the ActivID CMS Portal.

The employee_mail parameter is both visible to and modifiable by the user of the ActivID CMS Portal. This parameter is mandatory; the user must enter a value before issuance can be completed.

Example: Using a Plug-In for Retrieving Data

package com.activcard.aims.plugin.staticdata;
 
 
import java.util.*;
import java.io.*;
 
 
public class SamplePlugin implements StaticDataCollectionPlugIn {
private String m_confFile = null;
private String[] values = null;
 
 
void CreateBSITags( ByteArrayOutputStream tagStream, ByteArrayOutputStream valStream,
byte tag,byte[] val) throws Exception {
tagStream.write(tag); tagStream.write(val.length); valStream.write(val, 0, val.length);
}
 
 
public void init(Map aParametersMap) throws Exception { Object[] paramValues = null;
paramValues = (Object[])aParametersMap.get("sampleConfigFile");
m_confFile = (String)paramValues[0];
values = new String[2];
paramValues = (Object[])aParametersMap.get("employee_name");
values[0] = (String) paramValues[0];
paramValues = (Object[])aParametersMap.get("employee_mail");
values[1] = (String) paramValues[0];
}
 
public void setParameters(Map aParametersMap) throws Exception {}
 
public Map computeCredentialParameters(String aUserDN, String aDeviceType, String aDeviceCUID) throws Exception {
Properties properties = new Properties();
try {
FileInputStream stream = new FileInputStream(m_confFile);
try {
properties.load(stream);
}
finally {
stream.close();
}
}
catch(FileNotFoundException e) {
throw new Exception("Properties file not found : "+    m_confFile);
}
catch (IOException x) {
throw new Exception( "Error loading properties file : " + m_confFile);
}
String someData = properties.getProperty("somedata"); Map theCredentialParams = new HashMap();
 
ByteArrayOutputStream tagStream = new ByteArrayOutputStream(); ByteArrayOutputStream valStream = new ByteArrayOutputStream();
 
CreateBSITags(tagStream, valStream,(byte)1,values[0].getBytes("UTF-8")); CreateBSITags(tagStream, valStream,(byte)2,values[1].getBytes("UTF-8")); CreateBSITags(tagStream, valStream,(byte)3,someData.getBytes("UTF-8"));
 
 
theCredentialParams.put("persoGC/BufferValue/BufferT", tagStream.toByteArray());
theCredentialParams.put("persoGC/BufferValue/BufferV", valStream.toByteArray());
tagStream.close();
valStream.close();
 
return theCredentialParams;
}
 
public String getPluginVersion() {
return "1.0";
}
public String getPluginProvider() {
return "HIDGlobal";
}
public void setStatus(String status) throws Exception {}