How can we help?

Manage PIV Smart Card Tokens

Anthony - Versasec Support
Anthony - Versasec Support
  • Updated


Follow the instructions in this section to setup the vSEC:CMS whereby it will be possible to issue and manage PIV credentials. In this article, we will issue a Windows smart card logon certificate to a PIV credential.

The PKI used in this example use case will be an MS CA.
The smart card type that will be managed in this use case will be a Yubico PIV credential.

Step 1 - Configure Smart Card Access

1. From Options - Smart Cards attach a PIV token that you will manage with the vSEC:CMS. The vSEC:CMS will filter the card type and present the entry in the table.

2. Click the Edit button and for Smart Card Access select Use native access if possible.

For any supported PIV credential in the vSEC:CMS the Smart Card Access needs to be configured to Use native access if possible. This will also need to be configured if you use the vSEC:CMS User Self-Service (USS). In this case on the client open a command prompt and from the location where the USS is installed run the command vSEC_CMS_T_USS.exe -configure. From the Settings tab select Use native access if possible in the Smart Card Access section. This can be set via GPO when deploying the USS to your clients. See the article Configure Windows GPO for further details on this.

Step 2 - Configure Data Export

If it is required to extract the PUC code for the PIV credential that is created during the smart card issuance then follow the instructions in this section, otherwise jump to step 3. The PUC code is required to perform offline PIN unblock.

It will be necessary to configure a data export template of type file in order to export the PUC code to a file.

1. From Options - Connections click the Configure button. Select Data Export and add this to the Selected pane and click Ok.

2. Click the Data Export to open the configuration dialog. Click the Add button and enter a template name and for Target select File (export to file). Under File select Write automatically to file and for Filename enter location where the file is to be written to.

3. Click the Format button to configure the details that you want written to the file. In this example, it is important to select the variable ${Puc} as this will be the actual PUC code generated by the vSEC:CMS during the issuance. In this example, we will also write the users ID to the extract file.

4. Click Ok and Save to close and save the template.

Step 3 – Configure Challenge-Response Support

PIV credentials only support the resetting of the user PIN using the PUC code. Therefore, challenge-response is not normally supported for performing PIN resets. However, this is possible with vSEC:CMS.

From Options – Security in the Application Security section enable the Enable challenge/response for offline PUC based unblock. Additionally, it will be necessary to enable support for this feature on the client side. The Enable challenge/response for offline PUC based unblock setting would need to be enabled on the USS through the -configure option when configuring the setting on the USS.

The setting Enable challenge/response for offline PUC based unblock should normally be set using GPO. See the article Configure Windows GPO for details on this.

Step 4 - Configure Smart Card Template

1. From Templates - Card Templates click the Add button. Click the Edit link beside General.

2. Enter a template name and attach a PIV credential that is to be managed by this template and click the Detect button and wait for the vSEC:CMS to detect that it is a PIV token.

3. Click Ok and accept all default settings in the General dialog and click Ok to save the settings and close this dialog.

4. Click the Edit link for Issue Card.

5. Click the Expiration button to configure the card expiration flag that will be set on the token. This flag is specific to PIV specification and it is up to the external system that the PIV token is used with to act on the setting configured in this flag. This flag would typically be used by a physical access system where the physical access system would read this flag and act accordingly.

Under Smart Card Validity Configuration 3 options are available on how to configure the expiration flag.

Select Validity period from smart card issuance and set the period as required. This will mean that the expiration flag will be set from the day that the token was actually issued, for example, if the validity period is 1 year then if the token is issued on 1st of January 2019 the expiration will be 1st January 2020.

Select Static expiration and select the date when this should be. This will mean that regardless of when the token is issued the expiration will always be the static date as configured here.

Select Expiration specified in CMS variable if it is required to retrieve the expiration date from an AD attribute for the user that the token is being issued to. Click the Select variable to select the variable that is mapping to an AD attribute. The Offset can be used to add a number of additional days to the value retrieved from AD. Select Must contain valid data if it is required that the user AD object contains this attribute value otherwise the issuance will not be allowed to take place. Select the Get test user if it is required to test this with an actual end user to ensure that this setting and check will function as expected.

Under Validity Verification select the Stop card issuance before expiry date and enter the number of days before the expiration that you want the issuance to be stopped. Select Warn before stop and enter the number of days that you wish to be warned before the rule for Stop card issuance before expiry date becomes applicable. These settings are applicable only if Static expiration or Expiration specified in CMS variable are used. If this is configured and the criteria is met the operator or user will get an error dialog during issuance.

The Example Using Configuration section will give you examples of when a token could expire depending on what you have configured.

Enable No certificate issuances when card is expired if it is required to not issue or re-issue certificates if the token has expired.

6. Under User ID Options section enable Assign User ID and select the already configured AD connection.

7. Under Enroll Certificate Options section enable Enroll certificate(s) and click the Add button. Select the already configured CA connection from the Certificate Authority drop-down list and select the smart card logon certificate template as configured on your CA from the Certificate template list. From the Card key container drop-down list select PIV Authentication. Click Ok to save and close the dialog.

8. Accept all other defaults for the Issue Card dialog and click Ok to save and close.

It is important that the Windows smart card logon certificate template on the CA is configured to require an authorized signature. From the Issuance Requirements tab for the certificate template properties on the CA make sure to enable This number of authorized signatures and set a value of 1 and for Application policy drop down list select the Certificate Request Agent option.

9. In the General Card Properties section, it is possible to configure the objects that can be set on the card during the issuance.

10. Click the PIV Objects button to configure. Enable the Fingerprint(s), Facial Image and Iris Image if it is required to have these objects present on the card. This will result in dummy data being set in these objects. Dummy data may be required to be set as external systems may require these objects to be populated even though the information is not of a useful purpose.

11. In the Name encoding section it is possible to configure the data that can be set for Employee nameEmployee affiliation and Organization affiliation. By default, the dialog will be populated with preconfigured variables. If these fields need to be encoded on the PIV token then these variables need to be assigned to directory attributes in order to populate the fields. As these variables have not been assigned to a directory attribute they will need to be assigned. For example, to assign a variable of type Directory to an attribute from AD in the User ID Options section, where the Assign user ID is set to an AD, click the Manage button. From the available templates select the template type that points to the required AD and click Edit. Click the Edit button beside Variable(s) and configure the attributes as required.

The data objects that are set here are taken from the NIST Special Publication 800-73-4.

12. Click Ok to save and close the template.

13. For Initiate Card click the Edit link.

14. Enable the System set PUC checkbox and click the Configure button. From the drop-down list select the data export file configured above and click Add. Click Ok to save and close the dialog.

15. Click Ok to save and close the settings and click Ok to save and close the template.

Step 5 - Configure PIV Signing Certificate

1. From Options - PIV it will be necessary to configure the signing certificate that the vSEC:CMSwill use to sign PIV objects on the smart card during the issuance process.

Signing of PIV card objects will not be required in all circumstances therefore this feature should only be used if it is required to use the PIV card with components that required these PIV card objects to be signed.

2. Enable the Disable PIV card object signing if this feature is not required. This will disable the vSEC:CMSfrom signing PIV card objects.

3. The vSEC:CMS will search the logged-on user's Windows certificate store and all certificates found will be shown in the drop-down list available for selection. Select a signing certificate from your available list. It is important that the signing certificate you choose here is valid as the signed objects may be required to be verified by other components that the smart card will interact with once issued.

4. Enable Signing by service check box if it is required that the service that the vSEC:CMS service is running under will sign the smart card object. This option should be selected if the PIV smart card tokens are issued through the Operator Console or using the User Self-Service (USS) application.

5. Enable the Check certificate validity before signing check box if it is required to check the validity on the signing certificate before signing the card object. Enable the Stop card issuance before expiry date check box and enter the number of days before the signing certificate is to expire if it is required to not issue the smart card if the signing certificate meets the criteria configured. Enable the Warn before stop check box and enter the number of days before the stop criteria become valid such that the operator will get a warning message during card issuance.

Configure Signing by Service Certificate

Before you can use signing by service (see previous section) it will be necessary to configure a signing certificate that will be used for this operation. The vSEC:CMS will search for signing certificates in the personal store for the vSEC:CMS service. It is possible to configure a signing certificate through Windows MMC.

1. Open up MMC on the server where the vSEC:CMSis running. From File - Add/Remove Snap-in select Certificates and click Add.

2. Select Service account radio button and click Next and Next again. From the service account list select vSEC:CMS Service and click Finish.

3. Expand vSEC:CMS Service\Personal and right click Certificates and select All Tasks - Import to import a signing certificate that can be used or use the Advanced Operations to generate a certificate request that can be used. It is out of scope of this document to describe how to issue such certificates. Please consult your PKI team for assistance with this.

Step 6 - Issue Smart Card Token

1. From the Lifecycle page attach a blank Yubico PIV token. You should notice that the smart card status will be in an Unregistered state from the process diagram.

2. Click the Issued oval.

3. Select the template created earlier above and click the Execute button. The issuance work flow will now begin.

4. Enter the operator PIN (Passcode) code when prompted.

5. Select a user from AD that the smart card and certificate will be issued to.

6. When complete a short summary dialog will appear.

7. The smart card is now in an Active state as can be seen from the process diagram. Typically, the smart card holder will set the PIN code on the smart card which can be done from Actions - Smart Card Unblock for example.

This completes the use case.