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

Prerequisites: You must have administrative rights and access to the ActivID CMS SQL server or Oracle server database.
Note: You must configure certain property values of the PIV Personal Identity Verification (technical standard of "HSPD-12") plug-ins to reflect your specific deployment (for example, your database and directory type, or whether or not you are using 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.). For a detailed definition of the plug-in attributes, see the relevant section below.

This plug-in enables you to customize the PIV Personal Identity Verification (technical standard of "HSPD-12") 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.

  1. 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.

  1. 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 Card Holder Unique Identifier, 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 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. (recommended), and soft credentials stored locally on a hard disk.

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

  1. 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 The Certificate Authority (CA) issues and manages security credentials and public keys for message encryption in a networks environment. type as indicated in the following table.

‘FASCN.type’ Attributes

CA Type

Attributes

Microsoft®

FASCN.type=base64

Entrust®

FASCN.type=base64

Symantec/VeriSign®

FASCN.type=base64

UniCERT UPI

FASCN.type= base64
Note: base64 means that the FASC-N is read in the database, parsed as a base64-encoded value, and a binary value is provided to the plug-in.

  1. 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).

Validity Period Cap

Mode

Card Expiration Date

Certificate Validity Period Cap

piv:certValidity Period
PIV

Any

 Disabled Up to card expiration date
In more than n years

n years

 n years
In less than n years

n years

 Up to card expiration date
  PIV-I In more than 3 years

3 years

 3 years
In less than 3 years

3 years

 Up to card expiration day
Important: When in a PIV-I mode, it is recommended that you accept the piv:certValidityPeriod attribute as a dynamic value for the certificate validity period so as to enforce the PIV-I constraints automatically.

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:

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

Note: When not using an HSM – and for testing purposes only – you can use the piv_sign_2048.pfx certificate as your digital signatory certificate. This certificate is included in the PIV Toolkit and must be swapped for a production certificate once you deploy PIV Toolkit in a production environment.

In order to use multiple PIV Personal Identity Verification (technical standard of "HSPD-12") signers, you need to make changes to the PIVEnrollment.properties file, as well as the XML Schema Definition and 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. 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 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. (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:

Copy 
<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:

Note: If you want to use the default signatory key, you can either add the DigitalSignatoryIndex tag and set its value to 0, or you can simply not add the DigitalSignatoryIndex tag, in which case the default signatory key is automatically used.

This plug-in enables you to customize PIV Personal Identity Verification (technical standard of "HSPD-12") Notification configuration.

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

  1. 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.

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

Important: If you have configured ActivID CMS to work with more than one type of directory, you may need to specify the directory type by adding a suffix with the directory short name to the piv.link attribute (for example, piv.link.msft-ad). For details about the directory short names, see Configuring the Generic Plugin.

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.

‘piv.link’ Attribute Examples

Directory Type

Attributes

Microsoft® Active Directory

sAMAccountName:str,card#cuid:str,policy#oncardkeys:str,policy#chuid:str,policy#fingerprints:str,policy#keyhistory:str,policy#facialimage:str,policy#printedinfo:str,policy#discoveryobject:str,content#DiscoveryObjectValue:str,policy#iris:str

IBM® Tivoli Directory Server / Novell® eDirectory (UID) / Oracle® Directory Server

uid:str,card#cuid:str,policy#oncardkeys:str,policy#chuid:str,policy#fingerprints:str,policy#keyhistory:str,policy#facialimage:str,policy#printedinfo:str,policy#discoveryobject:str,content#DiscoveryObjectValue:str,policy#iris:str
Critical Path® / Siemens® DirX

cn:str,card#cuid:str,policy#oncardkeys:str,policy#chuid:str,policy#fingerprints:str,policy#keyhistory:str,policy#facialimage:str,policy#printedinfo:str,policy#discoveryobject:str,content#DiscoveryObjectValue:str,policy#iris:str
Microsoft® Lightweight Directory Services

uid:str,card#cuid:str,policy#oncardkeys:str,policy#chuid:str,policy#fingerprints:str,policy#keyhistory:str,policy#facialimage:str,policy#printedinfo:str,policy#discoveryobject:str,content#DiscoveryObjectValue:str,policy#iris:str
Novell® eDirectory (UniqueID)

uniqueID:str,card#cuid:str,policy#oncardkeys:str,policy#chuid:str,policy#fingerprints:str,policy#keyhistory:str,policy#facialimage:str,policy#printedinfo:str,policy#discoveryobject:str,content#DiscoveryObjectValue:str,policy#iris:str
OpenLDAP

uid:str,card#cuid:str,policy#oncardkeys:str,policy#chuid:str,policy#fingerprints:str,policy#keyhistory:str,policy#facialimage:str,policy#printedinfo:str,policy#discoveryobject:str,content#DiscoveryObjectValue:str,policy#iris:str

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

    By default, a biometric client generic plug-in is disabled and requires that a specific driver (Precise 200 or SecuGen driver) is 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 Personal Identity Verification (technical standard of "HSPD-12") 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):

PIVOP_BioMatchOnServerSampleBIOReq

PIVOP_BioMatchOffCardSampleBIOReq

USER_INFO

PERM_REPLACEMENT_USER_INFO

TEMP_REPLACEMENT_USER_INFO

EOL_REPLACEMENT_USER_INFO

DEVICE_POSTPOSSESS

PERM_REPLACEMENT_POSTPROCESS

EOL_REPLACEMENT_POSTPROCESS

PINUNLOCK_CUSTOM

PIV_BioMatchOnServerSampleBIOReq

PIV_BioMatchOffCardSampleBIOReq

MDIDC_ISSUE_INFO

MDIDC_PINUNLOCK_INFO

MDIDC_ISSUE_CUSTOM
Note:

  • For most workflows, the verification will be performed twice (once using PIV server data, and then again with data on the card at the end).

  • SecuGen fingerprint verifier is now the default biometric reader. If a SecuGen fingerprint verifier is not found, or if Java is not installed, then the Precise Biometrics reader will be used.

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:

Copy 
[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 Personal Identity Verification (technical standard of "HSPD-12") card profiles into the 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., using the Key Management System (KMS).

  1. 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 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. file compliant with FIPS 201-2. This file is found in the Tools\PIV\CPRSigning folder in the ActivID CMS distribution.