'\" t
.\"     Title: piv-tool
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/10/2024
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "PIV\-TOOL" "1" "03/10/2024" "opensc" "OpenSC Tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
piv-tool \- smart card utility for HSPD\-12 PIV cards
.SH "SYNOPSIS"
.HP \w'\fBpiv\-tool\fR\ 'u
\fBpiv\-tool\fR [\fIOPTIONS\fR]
.SH ""
.PP
The
\fBpiv\-tool\fR
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\&.
.SH "OPTIONS"
.PP
.PP
\fB\-\-serial\fR
.RS 4
Print the card serial number derived from the CHUID object, if any\&. Output is in hex byte format\&.
.RE
.PP
\fB\-\-name\fR, \fB\-n\fR
.RS 4
Print the name of the inserted card (driver)
.RE
.PP
\fB\-\-admin\fR \fIargument\fR, \fB\-A\fR \fIargument\fR
.RS 4
Authenticate to the card using a 2DES, 3DES or AES key\&. The
\fIargument\fR
of the form
.sp
.if n \{\
.RS 4
.\}
.nf
 {A|M}:\fIref\fR:\fIalg\fR
.fi
.if n \{\
.RE
.\}
.sp
is required, were
A
uses "EXTERNAL AUTHENTICATION" and
M
uses "MUTUAL AUTHENTICATION"\&.
\fIref\fR
is normally
9B, and
\fIalg\fR
is
03
for 3DES,
01
for 2DES,
08
for AES\-128,
0A
for AES\-192 or
0C
for AES\-256\&. The key is provided by the card vendor\&. The environment variable
\fIPIV_EXT_AUTH_KEY\fR
must point to either a binary file matching the length of the key or a text file containing 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
.RE
.PP
\fB\-\-genkey\fR \fIargument\fR, \fB\-G\fR \fIargument\fR
.RS 4
Generate a key pair on the card and output the public key\&. The
\fIargument\fR
of the form
.sp
.if n \{\
.RS 4
.\}
.nf
\fIref\fR:\fIalg\fR
.fi
.if n \{\
.RE
.\}
.sp
is required, where
\fIref\fR
is
9A,
9C,
9D
or
9E
and
\fIalg\fR
is
06,
07,
11
or
14
for RSA 1024, RSA 2048, ECC 256 or ECC 384 respectively\&.
.RE
.PP
\fB\-\-object\fR \fIContainerID\fR, \fB\-O\fR \fIContainerID\fR
.RS 4
Load an object onto the card\&. The
\fIContainerID\fR
is as defined in NIST 800\-73\-n without leading
0x\&. Example: CHUID object is 3000
.RE
.PP
\fB\-\-cert\fR \fIref\fR, \fB\-C\fR \fIref\fR
.RS 4
Load a certificate onto the card\&.
\fIref\fR
is
9A,
9C,
9D
or
9E
.RE
.PP
\fB\-\-compresscert\fR \fIref\fR, \fB\-Z\fR \fIref\fR
.RS 4
Load a certificate that has been gzipped onto the card\&.
\fIref\fR
is
9A,
9C,
9D
or
9E
.RE
.PP
\fB\-\-out\fR \fIfile\fR, \fB\-o\fR \fIfile\fR
.RS 4
Output file for any operation that produces output\&.
.RE
.PP
\fB\-\-in\fR \fIfile\fR, \fB\-i\fR \fIfile\fR
.RS 4
Input file for any operation that requires an input file\&.
.RE
.PP
\fB\-\-key\-slots\-discovery\fR \fIfile\fR
.RS 4
Print properties of the key slots\&. Needs \*(Aqadmin\*(Aq authentication\&.
.RE
.PP
\fB\-\-send\-apdu\fR \fIapdu\fR, \fB\-s\fR \fIapdu\fR
.RS 4
Sends an arbitrary APDU to the card in the format
AA:BB:CC:DD:EE:FF\&.\&.\&.\&. This option may be repeated\&.
.RE
.PP
\fB\-\-reader\fR \fIarg\fR, \fB\-r\fR \fIarg\fR
.RS 4
Number of the reader to use\&. By default, the first reader with a present card is used\&. If
\fIarg\fR
is an ATR, the reader with a matching card will be chosen\&.
.RE
.PP
\fB\-\-wait\fR, \fB\-w\fR
.RS 4
Wait for a card to be inserted
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Causes
\fBpiv\-tool\fR
to be more verbose\&. Specify this flag several times to enable debug output in the opensc library\&.
.RE
.SH "SEE ALSO"
.PP
\fBopensc-tool\fR(1)
.SH "AUTHORS"
.PP
\fBpiv\-tool\fR
was written by Douglas E\&. Engert
<deengert@gmail\&.com>\&.