Mapping a PIV Certificate using the PIVKey Tool

Note: You can also map certificates to the PIV slots when they are created by using an OID in the certificate template.

Why map certificates?

Windows provides a built-in minidriver that supports PIV-compliant smart cards.  When the PIVKey software is installed, the PIVKey Minidriver is used instead of the Windows built-in minidriver.  The PIVKey Minidriver can read certificates from and load certificates to the PIVKey, while the Windows Minidriver can only read certificates from the PIVKey.  In order for the certificates to be available to the Windows Minidriver, they must be mapped to the PIV slots. Placing the certificates in the PIV slots thus allows the Windows Minidriver to "find" them for use.

This means that if the PIVKey card or token is to be used on a machine that does not have the PIVKey software installed (so the Windows Minidriver will be used), the certificates must be mapped to the PIV slots.

The PIVKeyTool enables the mapping of minidriver certificates to the PIV certificate slots.

X.509 Certificate for PIV Authentication (9A Key)
X.509 Certificate for Digital Signature (9C Key)
X.509 Certificate for Key Management (9D Key)
X.509 Certificate for Card Authentication (9E Key)

By default the PIVKey is loaded with a PIVKey Certificate, mapped to the Certificate for Card Authentication (9E Key).

Do not change mapping after deploying the card

Microsoft Windows will cache the PIV certificates and the link to the PIV slot where you mapped the certificate. If you change the certificate mapping (such as moving the certificate to another slot, or replacing it with a different certificate), the Windows PIV cache may fail. Windows may or may not provide a useful error code when this happens. One error you may see is the  "Key Container Not Found" error.

Default Certificate Mapping

In most cases you can use the PIVKeyTool with the --mapdefault option:

pivkeytool.exe --mapdefault --userpin "000000"

The --mapdefault option maps the first certificate to the 9E slot, and the next 3 certificates to the 9A, 9C and 9D slots.

Custom Certificate Mapping

If you are using more certificates, or if you regularly delete and re-enroll certicates, the --mapdefault option may not be sufficient. PIVKey allows you to specify the PIV container you want to map to. 

To map explicitly, run the PIVKeyTool as in the following examples, where the kxc numbers are certificate IDs:

pivkeytool.exe --mappiv9a kxc01  --userpin "000000"
pivkeytool.exe --mappiv9c kxc02  --userpin "000000"
pivkeytool.exe --mappiv9d kxc03  --userpin "000000"

The standard retail PIVKey smart card is already loaded with a Certificate for Card Authentication (9E Key). If you have deleted and overwritten that certificate and its associated keys, then you can map the new certificate as followed:

pivkeytool.exe --mappiv9e kxc00  --userpin "000000"

Certificate Discovery

To list the minidriver certificates and their IDs to map, run the PIVKeyTool with the --listmd option. 

pivkeytool.exe --listmd

This will list the certificates as followed:

List C2 Certificates:
  kxc00 PIVKey DDBAFC744B84DC4F804951B1765D6002

To confirm the certificates have been correctly mapped, run the PIVKeyTool with the --listpiv option:

pivkeytool.exe --listpiv

This will list the PIV slots and any certificate IDs mapped to them:

List Piv Certificate Mappings:
PivCert9A not mapped
PivCert9C not mapped
PivCert9D not mapped
PivCert9E mapped to kxc00

Certificate Deletion

When a Minidriver certificate is deleted, Windows deletes the associated keys from the Minidriver directory on the card. Usually (though not always) the certificate ID is then reused when the next key pair is generated.

Clear/Wipe Mappings

To clear the PIVKey mappings use the following command:

pivkeytool.exe --clearmappings  --userpin "000000"


Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk