Configure the Plug-in Files for PIV and PIV-1

This plug-in enables you to customize the PIV Enrollment configuration.

1. Open the PIVEnrollment.properties file in the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\ directory.

   In all cases, edit the following attributes:

   • Input Link parameters:

     • linkParameters– List of attributes defined to be linkParameter inputs (the first attribute will be the User unique identifier attribute determined by the directory, and there are more attributes either retrieved by ActivID CMS from LDAP Lightweight Directory Access Protocol or computed by ActivID CMS). This attribute depends on the Directory Type defined in ActivID CMS.

   • Metadata Database configuration:

     • metadata.table – Name of the table in the ActivID CMS database that stores metadata attributes. Default value: PIV_METADATA.

     • metadata.key – Attribute to be used for primary key index.

     • metadata.encrypt – Attribute used for data encryption. Default value is true.

     Optionally, edit the following attribute:

     • metadataStore – Optionally, you can update the value of this attribute which lists the CPR The Card Production Request (CPR) contains a list of user-specific attributes that will be stored, fully or partially, in the PIV Metadata database, and will be loaded on the PIV card during the issuance. attributes to store in the ActivID CMS in the PIV Metadata table. ActivID CMS can provide a PIV metadata database password to PIV plug-ins. This avoids having to re-enter the PIV metadata database password at the ActivID CMS server startup.

2. Go to the Data conversion section to define the conversions that will be used during the enrollment process to provide user-specific data stored in the PIV_METADATA table to the plug-in. Each field is initially stored in the PIV Metadata base in String format from the parsed CPR.

   For further details about the available attributes, see Data Operations/Conversions Attributes.

3. Optionally, go to the Digital Signatory Parameters section if you want to enable PIV object signing and configure the signatory parameters.

   PIV objects are all user-related data required by the PIV workflow and securely stored on smart cards. This can include CHUID, fingerprint, Facial image, and security object.

   When activating a PIV card, ActivID CMS uses digital signatory parameters to sign PIV objects.

   Two credential types can be used for PIV object signature – Credentials stored on HSM (recommended), and soft credentials stored locally on a hard disk.

   For further details about the available parameters, see Digital Signatory Parameters.

4. Optionally, go to the CPR Signing Parameters section if you want to enable Card Production Request (CPR) signature verification and update the following parameters:

   • sign.verify_cpr – Set the value to true to enable CPR signature verification, or false if the CPR signature is not verified.

   • sign.trust_keystore_file – Enter the path to your Trust Keystore if you want to enable the trust path validation of the CPR signing certificate.

   • sign.trust_keystore_type – Enter the type of your Trust Keystore.

   • sign.trust_keystore_type – Enter the password protecting your Trust Keystore.

   A tool is provided in the PIV Toolkit to generate the Trust Keystore used to verify a CPR signature. For more information on the Trust Keystore, refer to the <CMS distribution>/Tools/PIV/CPRSigning/readme.txt file.

Data Operations/Conversions Attributes

1. Update the FASCN.type attribute according to your CA type as indicated in the following table.

2. Optionally, the following attributes may be modified when necessary:

• FASCN.alt_store.type = hex – In this case, the FASC-N is a Hexadecimal string representation.

• FASCN.alt_store.name = printableFASCN – Alternative storage name for the attribute. A copy of the data will be stored with this name, with the alternate type.

• GUID.type = guid type – Type of GUID.

• GUID.store_enforcedFormat = regexp;GUID.store_enforcedFormat.regexp = (0{16}|[A-Za-z0-9+/]{22}==) – Specifies a proprietary type GUID whose syntax will be analyzed at parsing submission.

• NACIIndicator.type = numericBoolean

  • For Symantec/Verisign – NACIIndicator.type=numericBoolean allows support for 1/0 in CPR and NACIIndicator.type=string allows support for TRUE/FALSE in the CPR.

• alphaNACIIndicator.alt_get.name = NACIIndicator

• alphaNACIIndicator.type = alphaBoolean

  By default, the PIVEnrollment plug-in converts the CPR NACI value from 0/1 or from true/false to 0/1.

• PIVIssuanceOnly – If true, only CPR with PIV mandatory attributes are accepted (true is the default value for this attribute). If false, the check of PIV Mandatory attributes is driven by PIVIssuanceOnlyAtt parameter.

• mandatoryAttributes – List of PIV mandatory attributes.

• PIVIssuanceOnlyAtt – If this attribute is found in the CPR, other PIV mandatory must be present (FASC-N is the default value for this attribute).

• ExpirationDateShort – The expiration date in format MMMYYYY computed from the CPR Expiration Date attribute.

• certValidityPeriod – Used to retrieve a validity period given the current date and the card expiration date. This attribute can be used to configure the certificate validity period on a device policy. For further information, see the note below.

• IssuanceDate – Used to retrieve the current date (in format yyyyMMdd by default).

Note about Certificate Validity Period

PIV compliance requires that certificate validity period to be less than the card validity period. In addition, PIV-I compliance requires the certificate validity period to not exceed 3 years.

• Certificate Validity Period Cap – defined as a duration in years or in days. It is optional in PIV mode.

• certValidityPeriod.cap.PIV-I – This cap is automatically applied in PIV-I mode (using a default maximum duration of 3 years).

This cap is applied to the value of the piv:certValidityPeriod PIV plug-in attribute as follows (assuming 3 years is used as cap value in the PIV-I cases – see specific configuration parameter further).

Digital Signatory Parameters

If you are using an HSM, then edit the following attributes:

• sign.hsm – Set the Signature mode of PIV objects to true when signing with a credential stored in the HSM, or false if you use a soft credential.

• sign.alias – Enter the signature credential’s alias in the HSM.

If you are NOT using HSM, then edit the following attributes:

• sign.p12_filename – Enter the path to the soft credential used to sign PIV objects.

• sign.p12_password – Enter the password protecting the soft credential file.

To set the hash for the Digital Signature, edit the following attribute:

• hash.algo – Possible values are SHA-1 or SHA-256 (SHA-256 is recommended for FIPS 201 compliance).

For details on how to generate digital signature keys on an HSM, see Generate Digital Signatory Keys on an HSM.

In order to use multiple PIV signers, you need to make changes to the PIVEnrollment.properties file, as well as the XML Schema Definition and CPR XML files.

PIVEnrollment.properties

There are 4 indexable parameters which can be configured:

• sign.p12_password: present if sign.hsm is set to false

• sign.p12_filename: present if sign.hsm is set to false

• sign.alias: present if sign.hsm is set to true.

• hash.algo: always present

Other parameters, such as sign.hsm for instance, are not indexable, which means that the sign.hsm value will apply to all the key indexes. As a result, all the signatory keys are either all in an HSM (sign.hsm set to true), or they are all in software (sign.hsm set to false); there cannot be a mix between HSM and non-HSM keys.

To add the new parameters to the PIVEnrollment.properties file:

• Go to the ActivID CMS configuration directory (for example: %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\).

• Make a backup copy of the existing PIVEnrollment.properties file in a different folder and with a different extension.

• Edit the PIVEnrollment.properties file.

  Important: Do not overwrite your PIVEnrollment.properties file as it contains other configuration specific to your environment.

• Add the new DigitalSignatoryIndex attribute to the metadataStore parameter as shown here:

  

• Add the new sign.count parameter.

  Note: This is the number of digital signatory keys, in addition to the default signatory key.

• For each digital signatory key, add the parameters defining the key:

  • hash.xx.algo + sign.xx.alias (for HSM keys), OR

  • hash.xx.algo + sign.xx.p12_password + sign.xx.p12_filename (for non-HSM keys).

An example of the configuration is shown below:

• Make sure that the default PIV signer configuration remains present:

  

XML Schema Definition

• Go to your existing PIV Toolkit delivery folder and back up the existing CPR with extension.xsd file typically located under …\Tools\PIV\SimuIDPRS\CPR with extensions.xsd.

• Copy the following modification:

<xsd:element name="DigitalSignatoryIndex" minOccurs="0">
              <xsd:simpleType>
                             <xsd:annotation>
                                             <xsd:documentation> Digital Signatory Index Number</xsd:documentation>
                             </xsd:annotation>
                             <xsd:restriction base="xsd:int">
                                             <xsd:minInclusive value="1"/>
                                             <xsd:maxInclusive value="99"/>
                             </xsd:restriction>
              </xsd:simpleType>
</xsd:element>

… into the CPR with extensions.xsd file as shown below:

Sample CPR XML file

• Go to your existing PIV Toolkit delivery folder and back up the existing sample CPR .xml file typically located under …\Tools\PIV\CPRSigning\CPR 2.1.8.sample.xml.

• Make sure that the CPR 2.1.8.sample.xml file is pointing to the correct CPR with extension.xsd file.

• Add the new DigitalSignatoryIndex tag (with the correct value):

  Copy

  <hsp:DigitalSignatoryIndex>2</hsp:DigitalSignatoryIndex>

  …into the CPR 2.1.8.sample.xml file as shown below:

This plug-in enables you to customize PIV Notification configuration.

1. Open the PIVNotification.properties file in your %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\ directory.

2. Update the directory-related parameters for the Metadata Database configuration:

• metadata.table – Name of the table in the ActivID CMS database that stores metadata attributes. Default value: PIV_METADATA.

• metadata.key – Attribute to be used for primary key index.

1. Open the generic_plugin.properties file in your %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\ directory.

2. Update the piv.link attribute according to your directory type as indicated in the following table.

The first attribute (uid/sAMAccountName/cn/uniqueID) is dependent on the directory that is used. This attribute must be the same directory attribute name that is configured in ActivID CMS for “userID”. The remaining attributes are the same for all directories.

3. Optionally, you can enable the biometric client generic plug-in.

   By default, a biometric client generic plug-in is disabled and requires that a driver be installed on the client-side (as the biometric plug-in runs in the client browser).

   Once it is enabled, the plug-in will run for all users of the workstation so biometric verification will be a required step for the relevant ActivID CMS operations.

   To enable this plug-in, perform the following steps:

   • Uncomment the plugin.client lines containing the BioMatch plugins by removing the pound sign (#) at the start of each line.

   • Comment the blank plugin.client lines by adding a pound sign (#) at the start of each line

There are three PIV BioMatch plugins available:

• Required Biometric Verification – With Operator Assistance (FIPS 201-2):

  • PIVOP_BioMatchOnServerSampleBIOReq

  • PIVOP_BioMatchOffCardSampleBIOReq

  • PIVOP_MatchBioPlugin_ANSI378_BIOreq.htm

• Required Biometric Verification – Self Service Kiosk Without Operator Assistance (FIPS 201-2):

  • PIV_BioMatchOnServerSampleBIOReq

  • PIV_BioMatchOffCardSampleBIOReq

  • PIV_MatchBioPlugin_ANSI378_BIOreq.htm

• Optional Biometric Verification (legacy support):

  • PIV_BioMatchOnServerSample

  • PIV_BioMatchOffCardSample

  • PIV_MatchBioPlugin_ANSI378.htm

By default, the following configuration can be found in the generic_plugin.properties (commented):

For more information, refer to About the Generic Plug-In SPI.

For ActivID CMS with an HSM A Hardware Security Module (HSM) securely stores secret key material. They are similar to large-storage, multisession smart cards. However, unlike smart cards, they are used mainly on the server side of a system. enabled, the alias enroll.PIV.HSMPin is already present for HSMPin.

For example:

[HSMPin]
SecureData.HSMPin.label        = HSM Pin :
SecureData.HSMPin.alias            = enroll.PIV.HSMPin,PeopleManagerHSMPin,HSMPin
SecureData.HSMPin.MinLen        = 0
SecureData.HSMPin.MinLen.Msg        = Pin must be between 0 and 300 characters in length.
SecureData.HSMPin.MaxLen        = 300
SecureData.HSMPin.MaxLen.Msg        = Pin must be between 0 and 300 characters in length.
SecureData.HSMPin.contentType        = anychars
SecureData.HSMPin.contentType.Msg    = Invalid HSM Pin.
SecureData.HSMPin.value        =

1. Import the PIV Master Keys corresponding to your PIV card profiles into the HSM, using the Key Management System (KMS).

2. If you want to enable PIV object signing, then edit the Digital Signatory key. Also, generate the digital signature keys on the HSM. For details, see Generate Digital Signatory Keys on an HSM.

ActivID CMS is now designed to support FIPS 201-2 as the default, compared to the earlier FIPS 201-1 version.

If you want to revert to FIPS 201-1, in the %PROGRAMDATA%\HID Global\Credential Management System\Shared Files\PIVEnrollment.properties file, replace the policy PIV-201-2 by PIV.

You may use the CPR 2.1.8.sample.PIV-201-2.xml as a sample CPR file compliant with FIPS 201-2. This file is found in the Tools\PIV\CPRSigning folder in the ActivID CMS distribution.