piv-tool.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 intened 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 derived card serial number from the CHUID object if any.   
					output is in hex byte format.</para></listitem>
				</varlistentry>			
				<varlistentry>
					<term><option>--name, -n</option></term>
					<listitem><para>Print the name of the inserted card (driver)</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--admin</option> argument, <option>-A</option> argument</term>
					<listitem><para>Authenticate to the card using a 2DES or 3DES key.
					An argument {A|M}:{ref}:{alg} is required, were A uses "EXTERNAL AUTHENTICATION"
					and M uses "MUTUAL AUTHENTICATION". ref is normally 9B, and alg is 03 for
					3DES. The key is provided by card vendor, and the environment variable 
					PIV_EXT_AUTH_KEY must point to a text file with the key in the format:
					XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
					</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--genkey</option>argument, <option>-G</option> argument</term>
					<listitem><para>Generate a key pair on the card and output the public key.
					An argument {ref}:{alg} is required, where ref is 9A, 9C, 9D or 9E and alg is 
					06, 07, 11 or 14 for RSA 1024, RSA 2048, ECC 256 or ECC 384. 
					</para></listitem>
				</varlistentry>	
				<varlistentry>
					<term><option>--object</option> ContainerID, <option>-O</option> ContainerID</term>
					<listitem><para>Load an object on to the card. The ContainerID is defined
					in NIST 800-73-n without leading 0x. Example: CHUID object is 3000
					</para></listitem>
				</varlistentry>
				
				<varlistentry>
					<term><option>--cert</option> ref, <option>-s</option> ref</term>
					<listitem><para>Load a certificate on to the card. ref is 9A, 9C, 9D or 9E</para></listitem>
				</varlistentry>
				
				<varlistentry>
					<term><option>--compresscert</option> ref, <option>-Z</option> ref</term>
					<listitem><para>Load a certificate that has been gziped on to the card.
					ref is 9A, 9C, 9D or 9E</para></listitem>
				</varlistentry>
				
				<varlistentry>
					<term><option>--out</option> file, <option>-o</option> file</term>
					<listitem><para>Output file for any operation that produces output.
					</para></listitem>
				</varlistentry>	
				
				<varlistentry>
					<term><option>--in</option> file, <option>-i</option> file</term>
					<listitem><para>Input file for any operation that requires an input file.
					</para></listitem>
				</varlistentry>				
				
				<varlistentry>
					<term><option>--key-slots-discovery</option> file</term>
					<listitem><para>Print properties of the key slots. Needs 'admin' authentication.
					</para></listitem>
				</varlistentry>	

				<varlistentry>
					<term><option>--send-apdu</option> apdu, <option>-s</option> apdu</term>
					<listitem><para>Sends an arbitrary APDU to the card in the format AA:BB:CC:DD:EE:FF...
					This option may be repeated.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term><option>--reader, -r</option> num</term>
					<listitem><para>Use the given reader number.  The default is 0, 
					the first reader in the system.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--card-driver</option> driver,<option> -c</option> driver</term>
					<listitem><para>Use the given card driver. The default is auto-detected.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--wait, -w</option></term>
					<listitem><para>Wait for a card to be inserted</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--verbose, -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>

</refentry>