Configuring the PIVEnrollment.properties Plug-In

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

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.

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.

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.

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

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.

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
PIV-I	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:

hash.algo – Possible values are SHA-1 or SHA-256 (SHA-256 is recommended for FIPS 201 Federal Information Processing Standard 201 (NIST standard for HSPD-12/PIV). compliance).

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.