206 lines
7.3 KiB
XML
206 lines
7.3 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<refentry id="piv-tool">
|
|
<refmeta>
|
|
<refentrytitle>piv-tool</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="productname">OpenSC</refmiscinfo>
|
|
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
|
|
<refmiscinfo class="source">opensc</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>piv-tool</refname>
|
|
<refpurpose>smart card utility for HSPD-12 PIV cards</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>piv-tool</command>
|
|
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<para>
|
|
The <command>piv-tool</command> utility can be used from the command line to perform
|
|
miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3.
|
|
It is intended for use with test cards only. It can be used to load objects, and generate
|
|
key pairs, as well as send arbitrary APDU commands to a card after having authenticated
|
|
to the card using the card key provided by the card vendor.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--serial</option>
|
|
</term>
|
|
<listitem><para>Print the card serial number derived from the CHUID object,
|
|
if any. Output is in hex byte format.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--name</option>,
|
|
<option>-n</option>
|
|
</term>
|
|
<listitem><para>Print the name of the inserted card (driver)</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--admin</option> <replaceable>argument</replaceable>,
|
|
<option>-A</option> <replaceable>argument</replaceable>
|
|
</term>
|
|
<listitem><para>Authenticate to the card using a 2DES, 3DES or AES key.
|
|
The <replaceable>argument</replaceable> of the form
|
|
<synopsis> {<literal>A</literal>|<literal>M</literal>}<literal>:</literal><replaceable>ref</replaceable><literal>:</literal><replaceable>alg</replaceable></synopsis>
|
|
is required, were <literal>A</literal> uses "EXTERNAL AUTHENTICATION"
|
|
and <literal>M</literal> uses "MUTUAL AUTHENTICATION".
|
|
<replaceable>ref</replaceable> is normally <literal>9B</literal>,
|
|
and <replaceable>alg</replaceable> is <literal>03</literal> for 3DES,
|
|
<literal>01</literal> for 2DES, <literal>08</literal> for AES-128,
|
|
<literal>0A</literal> for AES-192 or <literal>0C</literal> for AES-256.
|
|
The key is provided by the card vendor. The environment variable
|
|
<varname>PIV_EXT_AUTH_KEY</varname> must point to either a binary file
|
|
matching the length of the key or a text file containing
|
|
the key in the format:
|
|
<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>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--genkey</option> <replaceable>argument</replaceable>,
|
|
<option>-G</option> <replaceable>argument</replaceable>
|
|
</term>
|
|
<listitem><para>Generate a key pair on the card and output the public key.
|
|
The <replaceable>argument</replaceable> of the form
|
|
<synopsis><replaceable>ref</replaceable>:<replaceable>alg</replaceable></synopsis>
|
|
is required, where <replaceable>ref</replaceable> is <literal>9A</literal>,
|
|
<literal>9C</literal>, <literal>9D</literal> or <literal>9E</literal> and
|
|
<replaceable>alg</replaceable> is <literal>06</literal>,
|
|
<literal>07</literal>, <literal>11</literal> or <literal>14</literal>
|
|
for RSA 1024, RSA 2048, ECC 256 or ECC 384 respectively. </para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--object</option> <replaceable>ContainerID</replaceable>,
|
|
<option>-O</option> <replaceable>ContainerID</replaceable>
|
|
</term>
|
|
<listitem><para>Load an object onto the card.
|
|
The <replaceable>ContainerID</replaceable> is as defined in NIST 800-73-n
|
|
without leading <literal>0x</literal>. Example: CHUID object is 3000
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--cert</option> <replaceable>ref</replaceable>,
|
|
<option>-C</option> <replaceable>ref</replaceable>
|
|
</term>
|
|
<listitem><para>Load a certificate onto the card.
|
|
<replaceable>ref</replaceable> is <literal>9A</literal>,
|
|
<literal>9C</literal>, <literal>9D</literal> or
|
|
<literal>9E</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--compresscert</option> <replaceable>ref</replaceable>,
|
|
<option>-Z</option> <replaceable>ref</replaceable>
|
|
</term>
|
|
<listitem><para>Load a certificate that has been gzipped onto the card.
|
|
<replaceable>ref</replaceable> is <literal>9A</literal>,
|
|
<literal>9C</literal>, <literal>9D</literal> or
|
|
<literal>9E</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--out</option> <replaceable>file</replaceable>,
|
|
<option>-o</option> <replaceable>file</replaceable>
|
|
</term>
|
|
<listitem><para>Output file for any operation that produces output.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--in</option> <replaceable>file</replaceable>,
|
|
<option>-i</option> <replaceable>file</replaceable>
|
|
</term>
|
|
<listitem><para>Input file for any operation that requires an input file.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--key-slots-discovery</option> <replaceable>file</replaceable>
|
|
</term>
|
|
<listitem><para>Print properties of the key slots. Needs 'admin' authentication.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--send-apdu</option> <replaceable>apdu</replaceable>,
|
|
<option>-s</option> <replaceable>apdu</replaceable>
|
|
</term>
|
|
<listitem><para>Sends an arbitrary APDU to the card in the format
|
|
<code>AA:BB:CC:DD:EE:FF...</code>.
|
|
This option may be repeated.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--reader</option> <replaceable>arg</replaceable>,
|
|
<option>-r</option> <replaceable>arg</replaceable>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Number of the reader to use. By default, the first
|
|
reader with a present card is used. If
|
|
<replaceable>arg</replaceable> is an ATR, the
|
|
reader with a matching card will be chosen.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--wait</option>,
|
|
<option>-w</option>
|
|
</term>
|
|
<listitem><para>Wait for a card to be inserted</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--verbose</option>,
|
|
<option>-v</option>
|
|
</term>
|
|
<listitem><para>Causes <command>piv-tool</command> to be more verbose.
|
|
Specify this flag several times to enable debug output in the opensc
|
|
library.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>opensc-tool</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Authors</title>
|
|
<para><command>piv-tool</command> was written by
|
|
Douglas E. Engert <email>deengert@gmail.com</email>.</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|