| 1 | <?xml version="1.0" encoding="UTF-8"?> |
|---|
| 2 | <refentry id="piv-tool"> |
|---|
| 3 | <refmeta> |
|---|
| 4 | <refentrytitle>piv-tool</refentrytitle> |
|---|
| 5 | <manvolnum>1</manvolnum> |
|---|
| 6 | <refmiscinfo class="productname">OpenSC</refmiscinfo> |
|---|
| 7 | <refmiscinfo class="manual">OpenSC Tools</refmiscinfo> |
|---|
| 8 | <refmiscinfo class="source">opensc</refmiscinfo> |
|---|
| 9 | </refmeta> |
|---|
| 10 | |
|---|
| 11 | <refnamediv> |
|---|
| 12 | <refname>piv-tool</refname> |
|---|
| 13 | <refpurpose>smart card utility for HSPD-12 PIV cards</refpurpose> |
|---|
| 14 | </refnamediv> |
|---|
| 15 | |
|---|
| 16 | <refsynopsisdiv> |
|---|
| 17 | <cmdsynopsis> |
|---|
| 18 | <command>piv-tool</command> |
|---|
| 19 | <arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg> |
|---|
| 20 | </cmdsynopsis> |
|---|
| 21 | </refsynopsisdiv> |
|---|
| 22 | |
|---|
| 23 | <refsect1> |
|---|
| 24 | <para> |
|---|
| 25 | The <command>piv-tool</command> utility can be used from the command line to perform |
|---|
| 26 | miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3. |
|---|
| 27 | It is intended for use with test cards only. It can be used to load objects, and generate |
|---|
| 28 | key pairs, as well as send arbitrary APDU commands to a card after having authenticated |
|---|
| 29 | to the card using the card key provided by the card vendor. |
|---|
| 30 | </para> |
|---|
| 31 | </refsect1> |
|---|
| 32 | |
|---|
| 33 | <refsect1> |
|---|
| 34 | <title>Options</title> |
|---|
| 35 | <para> |
|---|
| 36 | <variablelist> |
|---|
| 37 | <varlistentry> |
|---|
| 38 | <term> |
|---|
| 39 | <option>--serial</option> |
|---|
| 40 | </term> |
|---|
| 41 | <listitem><para>Print the card serial number derived from the CHUID object, |
|---|
| 42 | if any. Output is in hex byte format.</para></listitem> |
|---|
| 43 | </varlistentry> |
|---|
| 44 | <varlistentry> |
|---|
| 45 | <term> |
|---|
| 46 | <option>--name</option>, |
|---|
| 47 | <option>-n</option> |
|---|
| 48 | </term> |
|---|
| 49 | <listitem><para>Print the name of the inserted card (driver)</para></listitem> |
|---|
| 50 | </varlistentry> |
|---|
| 51 | <varlistentry> |
|---|
| 52 | <term> |
|---|
| 53 | <option>--admin</option> <replaceable>argument</replaceable>, |
|---|
| 54 | <option>-A</option> <replaceable>argument</replaceable> |
|---|
| 55 | </term> |
|---|
| 56 | <listitem><para>Authenticate to the card using a 2DES or 3DES key. |
|---|
| 57 | The <replaceable>argument</replaceable> of the form |
|---|
| 58 | <synopsis> {<literal>A</literal>|<literal>M</literal>}<literal>:</literal><replaceable>ref</replaceable><literal>:</literal><replaceable>alg</replaceable></synopsis> |
|---|
| 59 | is required, were <literal>A</literal> uses "EXTERNAL AUTHENTICATION" |
|---|
| 60 | and <literal>M</literal> uses "MUTUAL AUTHENTICATION". |
|---|
| 61 | <replaceable>ref</replaceable> is normally <literal>9B</literal>, |
|---|
| 62 | and <replaceable>alg</replaceable> is <literal>03</literal> for 3DES. |
|---|
| 63 | The key is provided by the card vendor, and the environment variable |
|---|
| 64 | <varname>PIV_EXT_AUTH_KEY</varname> must point to a text file containing |
|---|
| 65 | the key in the format: |
|---|
| 66 | <code>XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX</code> |
|---|
| 67 | </para></listitem> |
|---|
| 68 | </varlistentry> |
|---|
| 69 | <varlistentry> |
|---|
| 70 | <term> |
|---|
| 71 | <option>--genkey</option> <replaceable>argument</replaceable>, |
|---|
| 72 | <option>-G</option> <replaceable>argument</replaceable> |
|---|
| 73 | </term> |
|---|
| 74 | <listitem><para>Generate a key pair on the card and output the public key. |
|---|
| 75 | The <replaceable>argument</replaceable> of the form |
|---|
| 76 | <synopsis><replaceable>ref</replaceable>:<replaceable>alg</replaceable></synopsis> |
|---|
| 77 | is required, where <replaceable>ref</replaceable> is <literal>9A</literal>, |
|---|
| 78 | <literal>9C</literal>, <literal>9D</literal> or <literal>9E</literal> and |
|---|
| 79 | <replaceable>alg</replaceable> is <literal>06</literal>, |
|---|
| 80 | <literal>07</literal>, <literal>11</literal> or <literal>14</literal> |
|---|
| 81 | for RSA 1024, RSA 2048, ECC 256 or ECC 384 respectively. </para></listitem> |
|---|
| 82 | </varlistentry> |
|---|
| 83 | <varlistentry> |
|---|
| 84 | <term> |
|---|
| 85 | <option>--object</option> <replaceable>ContainerID</replaceable>, |
|---|
| 86 | <option>-O</option> <replaceable>ContainerID</replaceable> |
|---|
| 87 | </term> |
|---|
| 88 | <listitem><para>Load an object onto the card. |
|---|
| 89 | The <replaceable>ContainerID</replaceable> is as defined in NIST 800-73-n |
|---|
| 90 | without leading <literal>0x</literal>. Example: CHUID object is 3000 |
|---|
| 91 | </para></listitem> |
|---|
| 92 | </varlistentry> |
|---|
| 93 | |
|---|
| 94 | <varlistentry> |
|---|
| 95 | <term> |
|---|
| 96 | <option>--cert</option> <replaceable>ref</replaceable>, |
|---|
| 97 | <option>-s</option> <replaceable>ref</replaceable> |
|---|
| 98 | </term> |
|---|
| 99 | <listitem><para>Load a certificate onto the card. |
|---|
| 100 | <replaceable>ref</replaceable> is <literal>9A</literal>, |
|---|
| 101 | <literal>9C</literal>, <literal>9D</literal> or |
|---|
| 102 | <literal>9E</literal></para></listitem> |
|---|
| 103 | </varlistentry> |
|---|
| 104 | |
|---|
| 105 | <varlistentry> |
|---|
| 106 | <term> |
|---|
| 107 | <option>--compresscert</option> <replaceable>ref</replaceable>, |
|---|
| 108 | <option>-Z</option> <replaceable>ref</replaceable> |
|---|
| 109 | </term> |
|---|
| 110 | <listitem><para>Load a certificate that has been gzipped onto the card. |
|---|
| 111 | <replaceable>ref</replaceable> is <literal>9A</literal>, |
|---|
| 112 | <literal>9C</literal>, <literal>9D</literal> or |
|---|
| 113 | <literal>9E</literal></para></listitem> |
|---|
| 114 | </varlistentry> |
|---|
| 115 | |
|---|
| 116 | <varlistentry> |
|---|
| 117 | <term> |
|---|
| 118 | <option>--out</option> <replaceable>file</replaceable>, |
|---|
| 119 | <option>-o</option> <replaceable>file</replaceable> |
|---|
| 120 | </term> |
|---|
| 121 | <listitem><para>Output file for any operation that produces output. |
|---|
| 122 | </para></listitem> |
|---|
| 123 | </varlistentry> |
|---|
| 124 | |
|---|
| 125 | <varlistentry> |
|---|
| 126 | <term> |
|---|
| 127 | <option>--in</option> <replaceable>file</replaceable>, |
|---|
| 128 | <option>-i</option> <replaceable>file</replaceable> |
|---|
| 129 | </term> |
|---|
| 130 | <listitem><para>Input file for any operation that requires an input file. |
|---|
| 131 | </para></listitem> |
|---|
| 132 | </varlistentry> |
|---|
| 133 | |
|---|
| 134 | <varlistentry> |
|---|
| 135 | <term> |
|---|
| 136 | <option>--key-slots-discovery</option> <replaceable>file</replaceable> |
|---|
| 137 | </term> |
|---|
| 138 | <listitem><para>Print properties of the key slots. Needs 'admin' authentication. |
|---|
| 139 | </para></listitem> |
|---|
| 140 | </varlistentry> |
|---|
| 141 | |
|---|
| 142 | <varlistentry> |
|---|
| 143 | <term> |
|---|
| 144 | <option>--send-apdu</option> <replaceable>apdu</replaceable>, |
|---|
| 145 | <option>-s</option> <replaceable>apdu</replaceable> |
|---|
| 146 | </term> |
|---|
| 147 | <listitem><para>Sends an arbitrary APDU to the card in the format |
|---|
| 148 | <code>AA:BB:CC:DD:EE:FF...</code>. |
|---|
| 149 | This option may be repeated.</para></listitem> |
|---|
| 150 | </varlistentry> |
|---|
| 151 | |
|---|
| 152 | <varlistentry> |
|---|
| 153 | <term> |
|---|
| 154 | <option>--reader</option> <replaceable>num</replaceable>, |
|---|
| 155 | <option>-r</option> <replaceable>num</replaceable> |
|---|
| 156 | </term> |
|---|
| 157 | <listitem><para>Use the given reader number. The default is |
|---|
| 158 | <literal>0</literal>, the first reader in the system.</para></listitem> |
|---|
| 159 | </varlistentry> |
|---|
| 160 | <varlistentry> |
|---|
| 161 | <term> |
|---|
| 162 | <option>--card-driver</option> <replaceable>driver</replaceable>, |
|---|
| 163 | <option>-c</option> <replaceable>driver</replaceable> |
|---|
| 164 | </term> |
|---|
| 165 | <listitem><para>Use the given card driver. |
|---|
| 166 | The default is auto-detected.</para></listitem> |
|---|
| 167 | </varlistentry> |
|---|
| 168 | <varlistentry> |
|---|
| 169 | <term> |
|---|
| 170 | <option>--wait</option>, |
|---|
| 171 | <option>-w</option> |
|---|
| 172 | </term> |
|---|
| 173 | <listitem><para>Wait for a card to be inserted</para></listitem> |
|---|
| 174 | </varlistentry> |
|---|
| 175 | <varlistentry> |
|---|
| 176 | <term> |
|---|
| 177 | <option>--verbose</option>, |
|---|
| 178 | <option>-v</option> |
|---|
| 179 | </term> |
|---|
| 180 | <listitem><para>Causes <command>piv-tool</command> to be more verbose. |
|---|
| 181 | Specify this flag several times to enable debug output in the opensc |
|---|
| 182 | library.</para></listitem> |
|---|
| 183 | </varlistentry> |
|---|
| 184 | </variablelist> |
|---|
| 185 | </para> |
|---|
| 186 | </refsect1> |
|---|
| 187 | |
|---|
| 188 | <refsect1> |
|---|
| 189 | <title>See also</title> |
|---|
| 190 | <para> |
|---|
| 191 | <citerefentry> |
|---|
| 192 | <refentrytitle>opensc-tool</refentrytitle> |
|---|
| 193 | <manvolnum>1</manvolnum> |
|---|
| 194 | </citerefentry> |
|---|
| 195 | </para> |
|---|
| 196 | </refsect1> |
|---|
| 197 | |
|---|
| 198 | </refentry> |
|---|
