## Name

piv-tool perform some very primitive card administration operation on PIV cards.

## Description

piv-tool can be used to do some very primitive card administration operations on PIV cards. Card administration operations may vary from vendor to vendor. This tool is meant for testing during development and is by no means complete.

Before an administrative card operation can be preformed, authentication of the piv-tool to the card may be needed. After the card is personalized, addition command my be needed to complete the personalization. See your vendor's instructions for more details, including the difference between Mutual authentication and External authentication. piv-tool is similar to opensc-tool but takes some additional parameters for use with the PIV cards. See NIST 800-73-1 Table 12 for definitions of <ref> and <alg> and section 7.2.4 for the difference between Mutual and External Authentication.

## Synopsis

piv-tool [options]

## Options

--serial

> (as of 0.11.1 the serial number is not implemented.)

--name

> Print name of card. `PIV-II`

--admin, -A <{M|A}>:<ref>:<alg> -

> Authenticate using reference and algorithm.

> The environment variable PIV_EXT_AUTH_KEY must point to a file with the key. The file format is NN:NN:NN:...:NN where a 3des key would have 24 NN pairs. Oberthur cards use "-A A:9B:03", GemAlto cards use "-A M:9B:03" Both use 3des keys.

--usepin, -P

> authenticate with pin (only early beta cards used this option.)

--genkey, -G <ref>:<alg>

> Generate a key pair for <ref> with algorithm <alg> and write public key to --out <file>.

--cert, -C <ref>

> read cert from --in <file> and write the cert to the card.

--req, -R

> (not yet implemented. see examples below.)

--out, -o <file>

> file name to use for any output type operation.

--in, -i <file>

> file name for input operation.

--send-apdu, -s <arg>

> send an APDU after doing any -A operation. APDU is in the form AA:BB:CC:DD...

--reader, -r <arg>

> Use the given reader number. The default is 0, the first reader in the system.

--card-driver, -c <arg>

> Use the given card driver. The default is auto-detected

--wait, -w

> wait for card to be inserted

--verbose, -v

> several times for more debugging output.

## Examples

In the following examples $CARD is used by your scripts to identify the specific card.

### Generate a key pair

The card can have 4 different keys and matching certificates. These correspond to <ref> 9A, 9B, 9C and 9D. With pkcs#11 these correspond with ID: 1, 2, 3, 4. We will create the key for the "X.509 Certificate for PIV Authentication" which matchs the key reference of 9A using a RSA 1024 bit key, and pkcs#11 ID 1.

     PIV_EXT_AUTH_KEY=card/external.3des.key.$CARD
     export PIV_EXT_AUTH_KEY
     piv-tool -A A:9B:03 -G 9A:06 -o card/pubkey.1.$CARD

### Clear a certificate on the card

There is no delete object command. Therefore write an object with a tag of zero, using External Authenticate to the card using authentication:

     piv-tool -A A:9B:03 -s 00:DB:3F:FF:09:5C:03:5F:C1:05:53:00:00:00

(This needs to done if there is already a certificate on the card, otherwise a generate cert request may use the public key from the old certificate, rather the the one just generated.)

### Generate a certificate request

Using OpenSSL, with the engine make sure the environment variable PIV_9A06_KEY is set pointing at the file created by the generate key pair operation.

     PIV_9A06_KEY=card/pubkey.1.$CARD
     export PIV_9A06_KEY
     openssl << EOT
     engine dynamic -vvvv -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so \
          -pre ID:pkcs11 -pre NO_VCHECK:1 \
          -pre LIST_ADD:1 -pre LOAD  \
          -pre MODULE_PATH:/usr/lib/opensc-pkcs11.so
     version
     req $SSLEAY_CONFIG -engine pkcs11 -md5 -new  \
         -key slot_0-id_1 -keyform engine -out card/newreq.1.$CARD.pem -text
     EOT

(Note back slashes added for readability.)

When using the engine the environment variable PIV_9A06_KEY points at the public key being used in the request, even if the <ref> and <alg> are not 9A and 06. The pkcs#11 ID is defined in `-key slot_0-id_<N>` where <N> = 1,2,3,4. (TODO: change name to not include 9A06)

### Signing the request

This step is independent of OpenSC and depends on your CA. For example, the certificate request file could be pasted into your CA's web page. When signed, save the certificate as card/cert.1.$CARD.pem for the next step.

### Load a Certificate

     PIV_EXT_AUTH_KEY=card/external.3des.key.$CARD
     export PIV_EXT_AUTH_KEY

     piv-tool -A A:9B:03 -C 9A -i card/cert.1.$CARD.pem