Mapping a PIV Certificate using the PIVKey Tool

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

Why map certificates?

PIVKey enables you to load certificates using the standard Microsoft Smart Card environment, including the Microsoft CA and windows enrollment client. It does this by implementing the Microsoft Smart Card Minidriver specification. The Minidriver is not aware of the PIV specific certificate and key containers. Therefore as an additional step you must assign the Minidriver certificates to the PIV certificate containers.

The PIVKey Tool enables the mapping of minidriver certificates to the PIVKey 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 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 mapdefault command:

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

Mapdefault 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 command may not be sufficient. PIVKey allows you to specify the minidriver container you want to map to. 

To map a custom profile profile run PIVKey Tool as in the following example:

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 certificate slots to map, run the ListMD command.

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 ListPIV command:

pivkeytool.exe --listpiv

This will list the PIV slots:

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 slot is then reused when the next key pair is generated.

Clear/Wipe Mappings

To clear the PIV Key mapping use the following command:

--clearmappings  --userpin "000000"


Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk