400 lines
13 KiB
XML
400 lines
13 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<refentry id="pkcs15-tool">
|
|
<refmeta>
|
|
<refentrytitle>pkcs15-tool</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="productname">OpenSC</refmiscinfo>
|
|
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
|
|
<refmiscinfo class="source">opensc</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pkcs15-tool</refname>
|
|
<refpurpose>utility for manipulating PKCS #15 data structures
|
|
on smart cards and similar security tokens</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pkcs15-tool</command>
|
|
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
The <command>pkcs15-tool</command> 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.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--version</option>,
|
|
</term>
|
|
<listitem><para>Print the OpenSC package release version.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--aid</option> <replaceable>aid</replaceable>
|
|
</term>
|
|
<listitem><para>Specify in a hexadecimal form the AID of the on-card PKCS#15
|
|
application to bind to.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--auth-id</option> <replaceable>id</replaceable>,
|
|
<option>-a</option> <replaceable>id</replaceable>
|
|
</term>
|
|
<listitem><para>Specifies the auth id of the PIN to use for the
|
|
operation. This is useful with the --change-pin operation.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--change-pin</option>
|
|
</term>
|
|
<listitem><para>Changes a PIN or PUK stored on the token. User authentication
|
|
is required for this operation.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--dump</option>,
|
|
<option>-D</option>
|
|
</term>
|
|
<listitem><para>List all card objects.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-info</option>
|
|
</term>
|
|
<listitem><para>List card objects.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-applications</option>
|
|
</term>
|
|
<listitem><para>List the on-card PKCS#15 applications.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-certificates</option>,
|
|
<option>-c</option>
|
|
</term>
|
|
<listitem><para>List all certificates stored on the token.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-data-objects</option>,
|
|
<option>-C</option>
|
|
</term>
|
|
<listitem><para>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 <option>--verify-pin</option> option has to be used.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-keys</option>,
|
|
<option>-k</option>
|
|
</term>
|
|
<listitem><para>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 <option>--verify-pin</option> option has to be used.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-secret-keys</option>
|
|
</term>
|
|
<listitem><para>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 <option>--verify-pin</option> option has to be used.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-pins</option>
|
|
</term>
|
|
<listitem><para>List all PINs stored on the token. General information
|
|
about each PIN is listed (eg. PIN name). Actual PIN values are not shown.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--list-public-keys</option>
|
|
</term>
|
|
<listitem><para>List all public keys stored on the token, including
|
|
key name, id, algorithm and length information.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--short</option>
|
|
<option>-s</option>
|
|
</term>
|
|
<listitem><para>Output lists in compact format.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--no-cache</option>
|
|
</term>
|
|
<listitem><para>Disables token data caching.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--clear-cache</option>
|
|
</term>
|
|
<listitem><para>Removes the user's cache directory. On
|
|
Windows, this option additionally removes the system's
|
|
caching directory (requires administrator
|
|
privileges).</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--clear-cache</option>
|
|
</term>
|
|
<listitem><para>Removes the user's cache directory. On
|
|
Windows, this option additionally removes the system's
|
|
caching directory (requires administrator
|
|
privileges).</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--output</option> <replaceable>filename</replaceable>,
|
|
<option>-o</option> <replaceable>filename</replaceable>
|
|
</term>
|
|
<listitem><para>Specifies where key output should be written.
|
|
If <replaceable>filename</replaceable> already exists, it will be overwritten.
|
|
If this option is not given, keys will be printed to standard output.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--raw</option>
|
|
</term>
|
|
<listitem><para>Changes how <option>--read-data-object</option> prints the content
|
|
to standard output. By default, when <option>--raw</option> is not given, it will
|
|
print the content in hex notation. If <option>--raw</option> is set, it will print
|
|
the binary data directly. This does not affect the output that is written to the
|
|
file specified by the <option>--output</option> option. Data written to a file will
|
|
always be in raw binary.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--read-certificate</option> <replaceable>cert</replaceable>
|
|
</term>
|
|
<listitem><para>Reads the certificate with the given id.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--read-data-object</option> <replaceable>cert</replaceable>,
|
|
<option>-R</option> <replaceable>data</replaceable>
|
|
</term>
|
|
<listitem><para>Reads data object with OID, applicationName or label.
|
|
The content is printed to standard output in hex notation, unless
|
|
the <option>--raw</option> option is given.
|
|
If an output file is given with the <option>--output</option> option,
|
|
the content is additionally written to the file.
|
|
Output to the file is always written in raw binary mode, the
|
|
<option>--raw</option> only affects standard output behavior.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--read-public-key</option> <replaceable>id</replaceable>
|
|
</term>
|
|
<listitem><para>Reads the public key with id <replaceable>id</replaceable>,
|
|
allowing the user to extract and store or use the public key.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--read-ssh-key</option> <replaceable>id</replaceable>
|
|
</term>
|
|
<listitem><para>Reads the public key with id <replaceable>id</replaceable>,
|
|
writing the output in format suitable for
|
|
<filename>$HOME/.ssh/authorized_keys</filename>.</para>
|
|
|
|
<para>The key label, if any will be shown in the 'Comment' field.</para>
|
|
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--rfc4716</option>
|
|
</term>
|
|
<listitem><para>When used in conjunction with option <option>--read-ssh-key</option> the
|
|
output format of the public key follows rfc4716.</para></listitem>
|
|
</varlistentry>
|
|
<para></para>
|
|
<para> The default output format is a single line (openssh).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--test-update</option>,
|
|
<option>-T</option>,
|
|
</term>
|
|
<listitem><para>Test if the card needs a security update</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--update</option>,
|
|
<option>-U</option>,
|
|
</term>
|
|
<listitem><para>Update the card with a security update</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--reader</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>--unblock-pin</option>,
|
|
<option>-u</option>
|
|
</term>
|
|
<listitem><para>Unblocks a PIN stored on the token. Knowledge of the
|
|
Pin Unblock Key (PUK) is required for this operation.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--verbose</option>,
|
|
<option>-v</option>
|
|
</term>
|
|
<listitem><para>Causes <command>pkcs15-tool</command> to be more
|
|
verbose. Specify this flag several times to enable debug output
|
|
in the OpenSC library.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--pin</option> <replaceable>pin</replaceable>,
|
|
<option>--new-pin</option> <replaceable>newpin</replaceable>
|
|
<option>--puk</option> <replaceable>puk</replaceable>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
These options can be used to specify the PIN/PUK values
|
|
on the command line. If the value is set to
|
|
<literal>env:</literal><replaceable>VARIABLE</replaceable>, the value
|
|
of the specified environment variable is used. By default,
|
|
the code is prompted on the command line if needed.
|
|
</para>
|
|
<para>
|
|
Note that on most operation systems, any user can
|
|
display the command line of any process on the
|
|
system using utilities such as
|
|
<command>ps(1)</command>. Therefore, you should prefer
|
|
passing the codes via an environment variable
|
|
on an unsecured system.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--new-pin</option> <replaceable>pin</replaceable>
|
|
</term>
|
|
<listitem><para>Specify New PIN (when changing or unblocking)</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--verify-pin</option>
|
|
</term>
|
|
<listitem><para>Verify PIN after card binding and before issuing any command
|
|
(without 'auth-id' the first non-SO, non-Unblock PIN will be verified)</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--test-session-pin</option>
|
|
</term>
|
|
<listitem><para>Equivalent to <option>--verify-pin</option>
|
|
with additional session PIN generation</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--wait</option>,
|
|
<option>-w</option>
|
|
</term>
|
|
<listitem><para>Causes <command>pkcs15-tool</command> to
|
|
wait for a card insertion.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
<option>--use-pinpad</option>
|
|
</term>
|
|
<listitem><para>Do not prompt the user; if no PINs supplied, pinpad will be used.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>pkcs15-init</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>,
|
|
<citerefentry>
|
|
<refentrytitle>pkcs15-crypt</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Authors</title>
|
|
<para><command>pkcs15-tool</command> was written by
|
|
Juha Yrjölä <email>juha.yrjola@iki.fi</email>.</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|