'\" t
.\" Title: pkcs15-tool
.\" Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 03/10/2024
.\" Manual: OpenSC Tools
.\" Source: opensc
.\" Language: English
.\"
.TH "PKCS15\-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"
pkcs15-tool \- utility for manipulating PKCS #15 data structures on smart cards and similar security tokens
.SH "SYNOPSIS"
.HP \w'\fBpkcs15\-tool\fR\ 'u
\fBpkcs15\-tool\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.PP
The
\fBpkcs15\-tool\fR
utility is used to manipulate the PKCS #15 data structures on smart cards and similar security tokens\&. Users can list and read PINs, keys and certificates stored on the token\&. User PIN authentication is performed for those operations that require it\&.
.SH "OPTIONS"
.PP
.PP
\fB\-\-version\fR
.RS 4
Print the OpenSC package release version\&.
.RE
.PP
\fB\-\-aid\fR \fIaid\fR
.RS 4
Specify in a hexadecimal form the AID of the on\-card PKCS#15 application to bind to\&.
.RE
.PP
\fB\-\-auth\-id\fR \fIid\fR, \fB\-a\fR \fIid\fR
.RS 4
Specifies the auth id of the PIN to use for the operation\&. This is useful with the \-\-change\-pin operation\&.
.RE
.PP
\fB\-\-change\-pin\fR
.RS 4
Changes a PIN or PUK stored on the token\&. User authentication is required for this operation\&.
.RE
.PP
\fB\-\-dump\fR, \fB\-D\fR
.RS 4
List all card objects\&.
.RE
.PP
\fB\-\-list\-info\fR
.RS 4
List card objects\&.
.RE
.PP
\fB\-\-list\-applications\fR
.RS 4
List the on\-card PKCS#15 applications\&.
.RE
.PP
\fB\-\-list\-certificates\fR, \fB\-c\fR
.RS 4
List all certificates stored on the token\&.
.RE
.PP
\fB\-\-list\-data\-objects\fR, \fB\-C\fR
.RS 4
List all data objects stored on the token\&. For some cards the PKCS#15 attributes of the private data objects are protected for reading and need the authentication with the User PIN\&. In such a case the
\fB\-\-verify\-pin\fR
option has to be used\&.
.RE
.PP
\fB\-\-list\-keys\fR, \fB\-k\fR
.RS 4
List all private keys stored on the token\&. General information about each private key is listed (eg\&. key name, id and algorithm)\&. Actual private key values are not displayed\&. For some cards the PKCS#15 attributes of the private keys are protected for reading and need the authentication with the User PIN\&. In such a case the
\fB\-\-verify\-pin\fR
option has to be used\&.
.RE
.PP
\fB\-\-list\-secret\-keys\fR
.RS 4
List all secret (symmetric) keys stored on the token\&. General information about each secret key is listed (eg\&. key name, id and algorithm)\&. Actual secret key values are not displayed\&. For some cards the PKCS#15 attributes of the private keys are protected for reading and need the authentication with the User PIN\&. In such a case the
\fB\-\-verify\-pin\fR
option has to be used\&.
.RE
.PP
\fB\-\-list\-pins\fR
.RS 4
List all PINs stored on the token\&. General information about each PIN is listed (eg\&. PIN name)\&. Actual PIN values are not shown\&.
.RE
.PP
\fB\-\-list\-public\-keys\fR
.RS 4
List all public keys stored on the token, including key name, id, algorithm and length information\&.
.RE
.PP
\fB\-\-short\fR, \fB\-s\fR
.RS 4
Output lists in compact format\&.
.RE
.PP
\fB\-\-no\-cache\fR
.RS 4
Disables token data caching\&.
.RE
.PP
\fB\-\-clear\-cache\fR
.RS 4
Removes the user\*(Aqs cache directory\&. On Windows, this option additionally removes the system\*(Aqs caching directory (requires administrator privileges)\&.
.RE
.PP
\fB\-\-output\fR \fIfilename\fR, \fB\-o\fR \fIfilename\fR
.RS 4
Specifies where key output should be written\&. If
\fIfilename\fR
already exists, it will be overwritten\&. If this option is not given, keys will be printed to standard output\&.
.RE
.PP
\fB\-\-raw\fR
.RS 4
Changes how
\fB\-\-read\-data\-object\fR
prints the content to standard output\&. By default, when
\fB\-\-raw\fR
is not given, it will print the content in hex notation\&. If
\fB\-\-raw\fR
is set, it will print the binary data directly\&. This does not affect the output that is written to the file specified by the
\fB\-\-output\fR
option\&. Data written to a file will always be in raw binary\&.
.RE
.PP
\fB\-\-read\-certificate\fR \fIcert\fR
.RS 4
Reads the certificate with the given id\&.
.RE
.PP
\fB\-\-read\-data\-object\fR \fIdata\fR, \fB\-R\fR \fIdata\fR
.RS 4
Reads data object with OID, applicationName or label\&. The content is printed to standard output in hex notation, unless the
\fB\-\-raw\fR
option is given\&. If an output file is given with the
\fB\-\-output\fR
option, the content is additionally written to the file\&. Output to the file is always written in raw binary mode, the
\fB\-\-raw\fR
only affects standard output behavior\&.
.RE
.PP
\fB\-\-read\-public\-key\fR \fIid\fR
.RS 4
Reads the public key with id
\fIid\fR, allowing the user to extract and store or use the public key\&.
.RE
.PP
\fB\-\-read\-ssh\-key\fR \fIid\fR
.RS 4
Reads the public key with id
\fIid\fR, writing the output in format suitable for
$HOME/\&.ssh/authorized_keys\&.
.sp
The key label, if any will be shown in the \*(AqComment\*(Aq field\&.
.PP
\fB\-\-rfc4716\fR
.RS 4
When used in conjunction with option
\fB\-\-read\-ssh\-key\fR
the output format of the public key follows rfc4716\&.
.RE
.sp
The default output format is a single line (openssh)\&.
.RE
.PP
\fB\-\-test\-update\fR, \fB\-T\fR
.RS 4
Test if the card needs a security update
.RE
.PP
\fB\-\-update\fR, \fB\-U\fR
.RS 4
Update the card with a security update
.RE
.PP
\fB\-\-reader\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\-\-unblock\-pin\fR, \fB\-u\fR
.RS 4
Unblocks a PIN stored on the token\&. Knowledge of the Pin Unblock Key (PUK) is required for this operation\&.
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Causes
\fBpkcs15\-tool\fR
to be more verbose\&. Specify this flag several times to enable debug output in the OpenSC library\&.
.RE
.PP
\fB\-\-pin\fR \fIpin\fR, \fB\-\-new\-pin\fR \fInewpin\fR, \fB\-\-puk\fR \fIpuk\fR
.RS 4
These options can be used to specify the PIN/PUK values on the command line\&. If the value is set to
env:\fIVARIABLE\fR, the value of the specified environment variable is used\&. By default, the code is prompted on the command line if needed\&.
.sp
Note that on most operation systems, any user can display the command line of any process on the system using utilities such as
\fBps(1)\fR\&. Therefore, you should prefer passing the codes via an environment variable on an unsecured system\&.
.RE
.PP
\fB\-\-new\-pin\fR \fIpin\fR
.RS 4
Specify New PIN (when changing or unblocking)
.RE
.PP
\fB\-\-verify\-pin\fR
.RS 4
Verify PIN after card binding and before issuing any command (without \*(Aqauth\-id\*(Aq the first non\-SO, non\-Unblock PIN will be verified)
.RE
.PP
\fB\-\-test\-session\-pin\fR
.RS 4
Equivalent to
\fB\-\-verify\-pin\fR
with additional session PIN generation
.RE
.PP
\fB\-\-wait\fR, \fB\-w\fR
.RS 4
Causes
\fBpkcs15\-tool\fR
to wait for a card insertion\&.
.RE
.PP
\fB\-\-use\-pinpad\fR
.RS 4
Do not prompt the user; if no PINs supplied, pinpad will be used\&.
.RE
.SH "SEE ALSO"
.PP
\fBpkcs15-init\fR(1),
\fBpkcs15-crypt\fR(1)
.SH "AUTHORS"
.PP
\fBpkcs15\-tool\fR
was written by Juha Yrjölä
\&.