giomba
/
opensc
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc/tools/*.xml: more consistent formatting 

uUse specific tags:
<command> for commands
<option> for options
<replaceable> for values that need to be replaced with real values
This commit is contained in:
Peter Marschall 2011-08-15 16:58:01 +02:00
parent d3b865ee40
commit a9c320f8f8
12 changed files with 756 additions and 323 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
doc/tools/cardos-tool.1.xml
View File

@ -34,33 +34,50 @@ smart cards and similar security tokens based on Siemens Card/OS M4.
<para>
<variablelist>
<varlistentry>
<term><option>--info</option>, <option>-i</option></term>
<term>
<option>--info</option>,
<option>-i</option>
</term>
<listitem><para>Display information about the card or token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--format</option>, <option>-f</option></term>
<term>
<option>--format</option>,
<option>-f</option>
</term>
<listitem><para>Format the card or token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> number, <option>-r</option> number</term>
<listitem><para>Specify the reader number <varname>number</varname> to use.
<term>
<option>--reader</option> <replaceable>number</replaceable>,
<option>-r</option> <replaceable>number</replaceable>
</term>
<listitem><para>Specify the reader number <replaceable>number</replaceable> to use.
The default is reader 0.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--card-driver</option> name, <option>-c</option> driver</term>
<listitem><para>Use the card driver specified by <varname>name</varname>. The default
is to auto-detect the correct card driver.</para></listitem>
<term>
<option>--card-driver</option> <replaceable>name</replaceable>,
<option>-c</option> <replaceable>name</replaceable></term>
<listitem><para>Use the card driver specified by <replaceable>name</replaceable>.
The default is to auto-detect the correct card driver.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Causes <command>cardos-tool</command> to wait for the token
to be inserted into reader.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<listitem><para>Causes <command>cardos-tool</command> to be more verbose. Specify this flag several times
to enable debug output in the opensc library.</para></listitem>
<term>
<option>--verbose</option>,
<option>-v</option>
</term>
<listitem><para>Causes <command>cardos-tool</command> to be more verbose.
Specify this flag several times to enable debug output in the opensc library.</para></listitem>
</varlistentry>
</variablelist>
</para>

92
doc/tools/cryptoflex-tool.1.xml
View File

@ -35,90 +35,122 @@
<para>
<variablelist>
<varlistentry>
<term><option>--verify-pin, -V</option></term>
<term>
<option>--verify-pin</option>,
<option>-V</option>
</term>
<listitem><para>Verifies CHV1 before issuing commands</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-keys, -l</option></term>
<term>
<option>--list-keys</option>,
<option>-l</option>
</term>
<listitem><para>Lists all keys stored in a public key file</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--create-key-files</option> <varname>arg</varname>,
<option>-c</option> <varname>arg</varname></term>
<listitem><para>Creates new RSA key files for <varname>arg</varname> keys</para></listitem>
<term>
<option>--create-key-files</option> <replaceable>arg</replaceable>,
<option>-c</option> <replaceable>arg</replaceable>
</term>
<listitem><para>Creates new RSA key files for <replaceable>arg</replaceable> keys</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--create-pin-files</option> <varname>id</varname>,
<option>-P</option> <varname>id</varname></term>
<listitem><para>Creates new PIN file for CHV<varname>id</varname></para></listitem>
<term>
<option>--create-pin-files</option> <replaceable>id</replaceable>,
<option>-P</option> <replaceable>id</replaceable>
</term>
<listitem><para>Creates new PIN file for CHV<replaceable>id</replaceable></para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-key, -g</option></term>
<term>
<option>--generate-key</option>,
<option>-g</option>
</term>
<listitem><para>Generate a new RSA key pair</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-key</option></term>
<term>
<option>--read-key</option>
</term>
<listitem><para>Reads a public key from the card, allowing the user to
extract and store or use the public key
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--key-num</option> <varname>num</varname>,
<option>-k</option> <varname>num</varname></term>
<term>
<option>--key-num</option> <replaceable>num</replaceable>,
<option>-k</option> <replaceable>num</replaceable>
</term>
<listitem><para>Specifies the key number to operate on. The default is
key number 1.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--app-df</option> <varname>num</varname>,
<option>-a</option> <varname>num</varname></term>
<term>
<option>--app-df</option> <replaceable>num</replaceable>,
<option>-a</option> <replaceable>num</replaceable>
</term>
<listitem><para>Specifies the DF to operate in</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--prkey-file</option> <varname>id</varname>,
<option>-p</option> <varname>id</varname></term>
<listitem><para>Specifies the private key file id, <varname>id</varname>,
<term>
<option>--prkey-file</option> <replaceable>id</replaceable>,
<option>-p</option> <replaceable>id</replaceable>
</term>
<listitem><para>Specifies the private key file id, <replaceable>id</replaceable>,
to use</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pubkey-file</option> <varname>id</varname>,
<option>-u</option> <varname>id</varname></term>
<listitem><para>Specifies the public key file id, <varname>id</varname>,
<term>
<option>--pubkey-file</option> <replaceable>id</replaceable>,
<option>-u</option> <replaceable>id</replaceable>
</term>
<listitem><para>Specifies the public key file id, <replaceable>id</replaceable>,
to use</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--exponent</option> <varname>exp</varname>,
<option>-e</option> <varname>exp</varname></term>
<listitem><para>Specifies the RSA exponent, <varname>exp</varname>,
<term>
<option>--exponent</option> <replaceable>exp</replaceable>,
<option>-e</option> <replaceable>exp</replaceable>
</term>
<listitem><para>Specifies the RSA exponent, <replaceable>exp</replaceable>,
to use in key generation. The default value is 3.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--modulus-length</option> <varname>length</varname>,
<option>-m</option> <varname>length</varname></term>
<listitem><para>Specifies the modulus <varname>length</varname> to use
<term>
<option>--modulus-length</option> <replaceable>length</replaceable>,
<option>-m</option> <replaceable>length</replaceable>
</term>
<listitem><para>Specifies the modulus <replaceable>length</replaceable> to use
in key generation. The default value is 1024.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> <varname>num</varname>,
<option>-r</option> <varname>num</varname></term>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>Forces <command>cryptoflex-tool</command> to use
reader number <varname>num</varname> for operations. The default
reader number <replaceable>num</replaceable> for operations. The default
is to use reader number 0, the first reader in the system.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--verbose</option>,
<option>-v</option>
</term>
<listitem><para>Causes <command>cryptoflex-tool</command> to be more
verbose. Specify this flag several times to enable debug output in
the opensc library.</para></listitem>

35
doc/tools/eidenv.1.xml
View File

@ -38,43 +38,64 @@
<para>
<variablelist>
<varlistentry>
<term><option>--reader, r</option> num</term>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>
Use the given reader. The default is the first reader with a card.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--help, -h</option></term>
<term>
<option>--help</option>,
<option>-h</option>
</term>
<listitem><para>Print help message on screen.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version, -v</option></term>
<term>
<option>--version</option>,
<option>-v</option>
</term>
<listitem><para>Prints the version
of the utility and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--print, -n</option></term>
<term>
<option>--print</option>,
<option>-n</option>
</term>
<listitem><para>Prints all data
fields from the card, like validity
period, document number etc.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--stats, -t</option></term>
<term>
<option>--stats</option>,
<option>-t</option>
</term>
<listitem><para>Prints key usage statistics
(only for Estonian ID card).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--exec, -x</option> prog</term>
<term>
<option>--exec</option> <replaceable>prog</replaceable>,
<option>-x</option> <replaceable>prog</replaceable>
</term>
<listitem><para>Executes the given program with
data in environment variables.</para></listitem>
</varlistentry>

65
doc/tools/netkey-tool.1.xml
View File

@ -35,32 +35,52 @@
<para>
<variablelist>
<varlistentry>
<term><option>--help</option>, <option>-h</option></term>
<term>
<option>--help</option>,
<option>-h</option>
</term>
<listitem><para>Displays a short help message.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> number, <option>-r</option> number</term>
<term>
<option>--reader</option> <replaceable>number</replaceable>,
<option>-r</option> <replaceable>number</replaceable>
</term>
<listitem><para>Use smart card in specified reader. Default is reader 0.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<term>
<option>-v</option>
</term>
<listitem><para>Causes <command>netkey-tool</command> to be more verbose. This
options may be specified multiple times to increase verbosity.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pin</option> pin-value, <option>-p</option> pin-value</term>
<term>
<option>--pin</option> <replaceable>pin-value</replaceable>,
<option>-p</option> <replaceable>pin-value</replaceable>
</term>
<listitem><para>Specifies the current value of the global PIN.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--puk</option> pin-value, <option>-u</option> pin-value</term>
<term>
<option>--puk</option> <replaceable>pin-value</replaceable>,
<option>-u</option> <replaceable>pin-value</replaceable>
</term>
<listitem><para>Specifies the current value of the global PUK.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pin0</option> pin-value, <option>-0</option> pin-value</term>
<term>
<option>--pin0</option> <replaceable>pin-value</replaceable>,
<option>-0</option> <replaceable>pin-value</replaceable>
</term>
<listitem><para>Specifies the current value of the local PIN0 (aka local PIN).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pin1</option> pin-value, <option>-1</option> pin-value</term>
<term>
<option>--pin1</option> <replaceable>pin-value</replaceable>,
<option>-1</option> <replaceable>pin-value</replaceable>
</term>
<listitem><para>Specifies the current value of the local PIN1 (aka local PUK).</para></listitem>
</varlistentry>
</variablelist>
@ -98,22 +118,27 @@
<para>
<variablelist>
<varlistentry>
<term><option>unblock</option> { <option>pin</option> | <option>pin0</option> |
<option>pin1</option> }</term>
<term>
<command>unblock</command> { <parameter>pin</parameter> | <parameter>pin0</parameter> | <parameter>pin1</parameter> }
</term>
<listitem><para>This unblocks the specified pin. You must specify another pin
to be able to do this and if you don't specify a correct one,
<command>netkey-tool</command> will tell you which one is needed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>change</option> { <option>pin</option> | <option>puk</option> |
<option>pin0</option> | <option>pin1</option> } new-pin</term>
<term>
<command>change</command> { <parameter>pin</parameter> | <parameter>puk</parameter> |
<parameter>pin0</parameter> | <parameter>pin1</parameter> } <replaceable>new-pin</replaceable>
</term>
<listitem><para>This changes the value of the specified pin to the given new value.
You must specify either the current value of the pin or another pin to be able to do
this and if you don't specify a correct one, <command>netkey-tool</command> will tell
you which one is needed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>nullpin</option> initial-pin</term>
<term>
<command>nullpin</command> <replaceable>initial-pin</replaceable>
</term>
<listitem><para>This command can be executed only if the global PIN of your card is
in nullpin-state. There's no way to return back to nullpin-state once you have changed
your global PIN. You don't need a pin to execute the nullpin-command. After a succesfull
@ -121,18 +146,22 @@
PUK-value.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>cert</option> number filename</term>
<term>
<command>cert</command> <replaceable>number</replaceable> <replaceable>filename</replaceable>
</term>
<listitem><para>This command will read one of your cards certificates (as specified by
<option>number</option>) and save this certificate into file <option>filename</option>
<replaceable>number</replaceable>) and save this certificate into file <replaceable>filename</replaceable>
in PEM-format. Certificates on a NetKey E4 card are readable without a pin, so you don't
have to specify one.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>cert</option> filename number</term>
<term>
<command>cert</command> <replaceable>filename</replaceable> <replaceable>number</replaceable>
</term>
<listitem><para>This command will read the first PEM-encoded certificate from file
<option>filename</option> and store this into your smart cards certificate file
<option>number</option>. Some of your smart cards certificate files might be readonly, so
this will not work with all values of <option>number</option>. If a certificate file is
<replaceable>filename</replaceable> and store this into your smart cards certificate file
<replaceable>number</replaceable>. Some of your smart cards certificate files might be readonly, so
this will not work with all values of <replaceable>number</replaceable>. If a certificate file is
writable you must specify a pin in order to change it. If you try to use this command
without specifying a pin, <command>netkey-tool</command> will tell you which one is
needed.</para></listitem>

196
doc/tools/opensc-explorer.1.xml
View File

@ -42,8 +42,8 @@
<variablelist>
<varlistentry>
<term>
<option>--reader</option> num,
<option>-r</option> num
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>
Use the given reader number. The default
@ -52,8 +52,8 @@
</varlistentry>
<varlistentry>
<term>
<option>--card-driver</option> driver,
<option>-c</option> driver
<option>--card-driver</option> <replaceable>driver</replaceable>,
<option>-c</option> <replaceable>driver</replaceable>
</term>
<listitem><para>
Use the given card driver. The default is
@ -62,22 +62,26 @@
</varlistentry>
<varlistentry>
<term>
<option>--mf</option> path,
<option>-m</option> path
<option>--mf</option> <replaceable>path</replaceable>,
<option>-m</option> <replaceable>path</replaceable>
</term>
<listitem><para>
Select the file referenced by the given path on
startup. The default is the path to the standard master file,
3F00. If <varname>path</varname> is empty (e.g. <command>opensc-explorer
3F00. If <replaceable>path</replaceable> is empty (e.g. <command>opensc-explorer
--mf ""</command>), then no file is explicitly selected.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<term>
<option>--wait</option>, <option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--verbose</option>, <option>-v</option>
</term>
<listitem><para>
Causes <command>opensc-explorer</command> to be more
verbose. Specify this flag several times to enable
@ -95,57 +99,74 @@
interactive prompt.
<variablelist>
<varlistentry>
<term><option>ls</option></term>
<term>
<command>ls</command>
</term>
<listitem><para>list all files in the current DF</para></listitem>
</varlistentry>
<varlistentry>
<term><option>cd</option> <varname>file-id</varname></term>
<listitem><para>change to another DF specified by <varname>file-id</varname></para></listitem>
<term>
<command>cd</command> <replaceable>file-id</replaceable>
</term>
<listitem><para>change to another DF specified by <replaceable>file-id</replaceable></para></listitem>
</varlistentry>
<varlistentry>
<term><option>cat</option> [<varname>file-id</varname>]</term>
<term><option>cat</option> sfi:<varname>sfi-id</varname></term>
<term>
<command>cat</command> [<replaceable>file-id</replaceable>]
</term>
<term>
<command>cat</command> sfi:<replaceable>sfi-id</replaceable>
</term>
<listitem><para>print the contents of the currently selected EF or the contents of a file
specified by <varname>file-id</varname>
or <varname>sfi-id</varname>.
specified by <replaceable>file-id</replaceable>
or <replaceable>sfi-id</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>info</option> [<varname>file-id</varname>]</term>
<listitem><para>display attributes of a file specified by <varname>file-id</varname>.
If <varname>file-id</varname> is not supplied,
<term>
<command>info</command> [<replaceable>file-id</replaceable>]
</term>
<listitem><para>display attributes of a file specified by <replaceable>file-id</replaceable>.
If <replaceable>file-id</replaceable> is not supplied,
the attributes of the current file are printed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>create</option> <varname>file-id</varname> <varname>size</varname></term>
<listitem><para>create a new EF. <varname>file-id</varname> specifies the
id number and <varname>size</varname> is the size of the new file.
<term>
<command>create</command> <replaceable>file-id</replaceable> <replaceable>size</replaceable>
</term>
<listitem><para>create a new EF. <replaceable>file-id</replaceable> specifies the
id number and <replaceable>size</replaceable> is the size of the new file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>delete</option> <varname>file-id</varname></term>
<listitem><para>remove the EF or DF specified by <varname>file-id</varname></para></listitem>
<term>
<command>delete</command> <replaceable>file-id</replaceable>
</term>
<listitem><para>remove the EF or DF specified by <replaceable>file-id</replaceable></para></listitem>
</varlistentry>
<varlistentry>
<term><option>rm</option> <varname>file-id</varname></term>
<listitem><para>remove the EF or DF specified by <varname>file-id</varname></para></listitem>
<term>
<command>rm</command> <replaceable>file-id</replaceable>
</term>
<listitem><para>remove the EF or DF specified by <replaceable>file-id</replaceable></para></listitem>
</varlistentry>
<varlistentry>
<term><option>verify</option> <varname>key-type</varname><varname>key-id</varname>
[<varname>key</varname>]</term>
<listitem><para>present a PIN or key to the card. Where <varname>key-type</varname>
can be one of CHV, KEY or PRO. <varname>key-id</varname> is a number representing the
key or PIN reference. <varname>key</varname> is the key or PIN to be verified in hex.
<term>
<command>verify</command> <replaceable>key-type</replaceable><replaceable>key-id</replaceable> [<replaceable>key</replaceable>]
</term>
<listitem><para>present a PIN or key to the card. Where <replaceable>key-type</replaceable>
can be one of CHV, KEY or PRO. <replaceable>key-id</replaceable> is a number representing the
key or PIN reference. <replaceable>key</replaceable> is the key or PIN to be verified in hex.
</para>
<para>
If <varname>key</varname> is omitted, PIN will be verified with PIN-Pad.
If <replaceable>key</replaceable> is omitted, PIN will be verified with PIN-Pad.
</para>
<para>
Example: verify CHV0 31:32:33:34:00:00:00:00
@ -154,9 +175,10 @@
</varlistentry>
<varlistentry>
<term><option>change CHV</option><varname>id</varname>
[[<varname>old-pin</varname>] <varname>new-pin</varname>]</term>
<listitem><para>change a PIN, where <varname>id</varname> is the PIN reference</para>
<term>
<command>change CHV</command><replaceable>id</replaceable> [[<replaceable>old-pin</replaceable>] <replaceable>new-pin</replaceable>]
</term>
<listitem><para>change a PIN, where <replaceable>id</replaceable> is the PIN reference</para>
<para>
Examples:
</para>
@ -173,117 +195,141 @@
</varlistentry>
<varlistentry>
<term><option>put</option> <varname>file-id</varname> <varname>input</varname></term>
<term>
<command>put</command> <replaceable>file-id</replaceable> <replaceable>input</replaceable>
</term>
<listitem><para>copy a local file to the card. The local file is specified
by <varname>input</varname> while the card file is specified by <varname>file-id</varname>.
by <replaceable>input</replaceable> while the card file is specified by <replaceable>file-id</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>get</option> <varname>file-id</varname> [<varname>output</varname>]</term>
<term>
<command>get</command> <replaceable>file-id</replaceable> [<replaceable>output</replaceable>]
</term>
<listitem>
<para>copy an EF to a local file. The local file is specified
by <varname>output</varname> while the card file is specified by <varname>file-id</varname>.
by <replaceable>output</replaceable> while the card file is specified by <replaceable>file-id</replaceable>.
</para>
<para>
If <varname>output</varname> is ommited, the name of the output file will be
derivated from the full card path to <varname>file-id</varname>.
If <replaceable>output</replaceable> is ommited, the name of the output file will be
derivated from the full card path to <replaceable>file-id</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>do_put</option> <varname>hex-tag</varname> <varname>input</varname></term>
<term>
<command>do_put</command> <replaceable>hex-tag</replaceable> <replaceable>input</replaceable>
</term>
<listitem>
<para>update internal card's 'tagged' data. </para>
<para><varname>hex-tag</varname> is the tag of the card's data.
<varname>input</varname> is the filename of the source file or the literal data presented as
<para><replaceable>hex-tag</replaceable> is the tag of the card's data.
<replaceable>input</replaceable> is the filename of the source file or the literal data presented as
a sequence of hexadecimal values or '"' enclosed string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>do_get</option> <varname>hex-tag</varname> [<varname>output</varname>]</term>
<term>
<command>do_get</command> <replaceable>hex-tag</replaceable> [<replaceable>output</replaceable>]
</term>
<listitem>
<para>copy the internal card's 'tagged' data into the local file.</para>
<para>The local file is specified by <varname>output</varname> while the tag of
the card's data is specified by <varname>hex-tag</varname>.
<para>The local file is specified by <replaceable>output</replaceable> while the tag of
the card's data is specified by <replaceable>hex-tag</replaceable>.
</para>
<para>
If <varname>output</varname> is ommited, the name of the output file will be
derivated from <varname>hex-tag</varname>.
If <replaceable>output</replaceable> is ommited, the name of the output file will be
derivated from <replaceable>hex-tag</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>mkdir</option> <varname>file-id</varname> <varname>size</varname></term>
<listitem><para>create a DF. <varname>file-id</varname> specifies the id number
and <varname>size</varname> is the size of the new file.</para></listitem>
<term>
<command>mkdir</command> <replaceable>file-id</replaceable> <replaceable>size</replaceable>
</term>
<listitem><para>create a DF. <replaceable>file-id</replaceable> specifies the id number
and <replaceable>size</replaceable> is the size of the new file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>erase</option></term>
<term>
<command>erase</command>
</term>
<listitem><para>erase the card, if the card supports it.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>random</option> <varname>count</varname></term>
<term>
<command>random</command> <replaceable>count</replaceable>
</term>
<listitem>
<para>generate random sequence of <varname>count</varname> bytes.</para>
<para>generate random sequence of <replaceable>count</replaceable> bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>update_record</option> <varname>file-id</varname> <varname>rec_nr</varname>
<varname>rec_offs</varname> <varname>data</varname></term>
<term>
<command>update_record</command> <replaceable>file-id</replaceable> <replaceable>rec-nr</replaceable> <replaceable>rec-offs</replaceable> <replaceable>data</replaceable>
</term>
<listitem>
<para>update record specified by <varname>rec_nr</varname> of the file
specified by <varname>file-id</varname> with the literal data
<varname>data</varname> starting from offset specified by
<varname>rec_offs</varname>.</para>
<para><varname>data</varname> can be supplied as a sequence of the hex values or
<para>update record specified by <replaceable>rec-nr</replaceable> of the file
specified by <replaceable>file-id</replaceable> with the literal data
<replaceable>data</replaceable> starting from offset specified by
<replaceable>rec-offs</replaceable>.</para>
<para><replaceable>data</replaceable> can be supplied as a sequence of the hex values or
as a '"' encolsed string. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>update_binary</option> <varname>file-id</varname> <varname>offs</varname>
<varname>data</varname></term>
<term>
<command>update_binary</command> <replaceable>file-id</replaceable> <replaceable>offs</replaceable> <replaceable>data</replaceable>
</term>
<listitem>
<para>binary update of the file specified by <varname>file-id</varname> with the literal data
<varname>data</varname> starting from offset specified by <varname>offs</varname>.</para>
<para><varname>data</varname> can be supplied as a sequence of the hex values or
<para>binary update of the file specified by <replaceable>file-id</replaceable> with the literal data
<replaceable>data</replaceable> starting from offset specified by <replaceable>offs</replaceable>.</para>
<para><replaceable>data</replaceable> can be supplied as a sequence of the hex values or
as a '"' encolsed string. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>debug</option> [<varname>level</varname>]</term>
<term>
<command>debug</command> [<replaceable>level</replaceable>]
</term>
<listitem>
<para>set OpenSC debug level to <varname>level</varname>.</para>
<para>If <varname>level</varname> is ommited the current debug level will be shown.</para>
<para>set OpenSC debug level to <replaceable>level</replaceable>.</para>
<para>If <replaceable>level</replaceable> is ommited the current debug level will be shown.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>apdu</option> <varname>hex_data</varname></term>
<term>
<command>apdu</command> <replaceable>hex-data</replaceable>
</term>
<listitem>
<para>send a custom APDU command <varname>hex_data</varname>.</para>
<para>send a custom APDU command <replaceable>hex-data</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>asn1</option> <varname>file-id</varname></term>
<term>
<command>asn1</command> <replaceable>file-id</replaceable>
</term>
<listitem>
<para>parse and print the ASN1 encoded content of the file specified by
<varname>file-id</varname>.</para>
<replaceable>file-id</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>quit</option></term>
<term>
<command>quit</command>
</term>
<listitem><para>exit the program.</para></listitem>
</varlistentry>

59
doc/tools/opensc-tool.1.xml
View File

@ -34,55 +34,90 @@
<para>
<variablelist>
<varlistentry>
<term><option>--info, -i</option></term>
<term>
<option>--info</option>,
<option>-i</option>
</term>
<listitem><para>Print information about OpenSC, such as version and enabled components</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--atr, -a</option></term>
<term>
<option>--atr</option>,
<option>-a</option>
</term>
<listitem><para>Print the Answer To Reset (ATR) of the card,
output is in hex byte format</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--name, -n</option></term>
<term>
<option>--name</option>,
<option>-n</option>
</term>
<listitem><para>Print the name of the inserted card (driver)</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--serial</option></term>
<term>
<option>--serial</option>
</term>
<listitem><para>Print the card serial number (normally the ICCSN), output is in hex byte
format</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--send-apdu</option> apdu, <option>-s</option> apdu</term>
<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 AA:BB:CC:DD:EE:FF...</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-files, -f</option></term>
<term>
<option>--list-files</option>,
<option>-f</option>
</term>
<listitem><para>Recursively lists all files stored on card</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-readers, -l</option></term>
<term>
<option>--list-readers</option>,
<option>-l</option>
</term>
<listitem><para>Lists all configured readers</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-drivers, -D</option></term>
<term>
<option>--list-drivers</option>,
<option>-D</option>
</term>
<listitem><para>Lists all installed card drivers</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> num, <option>-r</option> num</term>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</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>
<term>
<option>--card-driver</option> <replaceable>driver</replaceable>,
<option>-c</option> <replaceable>driver</replaceable>
</term>
<listitem><para>Use the given card driver. The default is auto-detected.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--verbose</option>,
<option>-v</option>
</term>
<listitem><para>Causes <command>opensc-tool</command> to be more verbose. Specify this flag several times
to enable debug output in the opensc library.</para></listitem>
</varlistentry>

73
doc/tools/piv-tool.1.xml
View File

@ -35,16 +35,24 @@
<para>
<variablelist>
<varlistentry>
<term><option>--serial</option></term>
<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>
<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> argument, <option>-A</option> argument</term>
<term>
<option>--admin</option> <replaceable>argument</replaceable>,
<option>-A</option> <replaceable>argument</replaceable>
</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
@ -54,69 +62,104 @@
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--genkey</option>argument, <option>-G</option> argument</term>
<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.
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>
<term>
<option>--object</option> <replaceable>ContainerID</replaceable>,
<option>-O</option> <replaceable>ContainerID</replaceable>
</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>
<term>
<option>--cert</option> <replaceable>ref</replaceable>,
<option>-s</option> <replaceable>ref</replaceable>
</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>
<term>
<option>--compresscert</option> <replaceable>ref</replaceable>,
<option>-Z</option> <replaceable>ref</replaceable>
</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>
<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> file, <option>-i</option> file</term>
<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> file</term>
<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> apdu, <option>-s</option> apdu</term>
<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 AA:BB:CC:DD:EE:FF...
This option may be repeated.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader, -r</option> num</term>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</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>
<term>
<option>--card-driver</option> <replaceable>driver</replaceable>,
<option>-c</option> <replaceable>driver</replaceable>
</term>
<listitem><para>Use the given card driver. The default is auto-detected.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<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>

162
doc/tools/pkcs11-tool.1.xml
View File

@ -36,16 +36,21 @@
<para>
<variablelist>
<varlistentry>
<term><option>--login, -l</option></term>
<term>
<option>--login</option>,
<option>-l</option>
</term>
<listitem><para>Authenticate to the token before performing
other operations. This option is not needed if a PIN is
provided on the command line.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pin</option> <varname>pin</varname>,
<option>-p</option> <varname>pin</varname></term>
<listitem><para>Use the given <varname>pin</varname> for
<term>
<option>--pin</option> <replaceable>pin</replaceable>,
<option>-p</option> <replaceable>pin</replaceable>
</term>
<listitem><para>Use the given <replaceable>pin</replaceable> for
token operations. WARNING: Be careful using this option
as other users may be able to read the command line from
the system or if it is embedded in a script.</para>
@ -54,22 +59,28 @@
</varlistentry>
<varlistentry>
<term><option>--so-pin</option> <varname>pin</varname></term>
<listitem><para>Use the given <varname>pin</varname> as the
<term>
<option>--so-pin</option> <replaceable>pin</replaceable>
</term>
<listitem><para>Use the given <replaceable>pin</replaceable> as the
Security Officer PIN for some token operations (token
initialization, user PIN initialization, etc). The same
warning as <option>--pin</option> also applies here.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--init-token</option></term>
<term>
<option>--init-token</option>
</term>
<listitem><para>Initializes a token: set the token label as
well as a Security Officer PIN (the label must be specified
using <option>--label</option>).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--init-pin</option></term>
<term>
<option>--init-pin</option>
</term>
<listitem><para>Initializes the user PIN. This option
differs from --change-pin in that it sets the user PIN
for the first time. Once set, the user PIN can be changed
@ -77,120 +88,169 @@
</varlistentry>
<varlistentry>
<term><option>--change-pin, -c</option></term>
<term>
<option>--change-pin</option>,
<option>-c</option>
</term>
<listitem><para>Change the user PIN on the token</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--test, -t</option></term>
<term>
<option>--test</option>,
<option>-t</option>
</term>
<listitem><para>Performs some tests on the token. This
option is most useful when used with either <option>--login</option>
or <option>--pin</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--show-info, -I</option></term>
<term>
<option>--show-info</option>,
<option>-I</option>
</term>
<listitem><para>Displays general token information.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-slots, -L</option></term>
<term>
<option>--list-slots</option>,
<option>-L</option>
</term>
<listitem><para>Displays a list of available slots on the token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-mechanisms, -M</option></term>
<term>
<option>--list-mechanisms</option>,
<option>-M</option>
</term>
<listitem><para>Displays a list of mechanisms supported by the token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-objects, -O</option></term>
<term>
<option>--list-objects</option>,
<option>-O</option>
</term>
<listitem><para>Displays a list of objects.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sign, s</option></term>
<term>
<option>--sign</option>,
<option>-s</option>
</term>
<listitem><para>Sign some data.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--hash, -h</option></term>
<term>
<option>--hash</option>,
<option>-h</option>
</term>
<listitem><para>Hash some data.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--mechanism</option> <varname>mechanism</varname>,
<option>-m</option> <varname>mechanism</varname></term>
<listitem><para>Use the specified <varname>mechanism</varname>
<term>
<option>--mechanism</option> <replaceable>mechanism</replaceable>,
<option>-m</option> <replaceable>mechanism</replaceable>
</term>
<listitem><para>Use the specified <replaceable>mechanism</replaceable>
for token operations. See <option>-M</option> for a list
of mechanisms supported by your token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--keypairgen, -k</option></term>
<term>
<option>--keypairgen</option>,
<option>-k</option>
</term>
<listitem><para>Generate a new key pair (public and private pair.)</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--write-object</option> <varname>id</varname>,
<option>-w</option> <varname>path</varname></term>
<term>
<option>--write-object</option> <replaceable>id</replaceable>,
<option>-w</option> <replaceable>path</replaceable>
</term>
<listitem><para>Write a key or certificate object to the token.
<varname>path</varname> points to the DER-encoded certificate or key file.
<replaceable>path</replaceable> points to the DER-encoded certificate or key file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--type</option> <varname>type</varname>,
<option>-y</option> <varname>type</varname></term>
<term>
<option>--type</option> <replaceable>type</replaceable>,
<option>-y</option> <replaceable>type</replaceable>
</term>
<listitem><para>Specify the type of object to operate on.
Examples are <emphasis>cert</emphasis>, <emphasis>privkey</emphasis>
and <emphasis>pubkey</emphasis>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--id</option> <varname>id</varname>,
<option>-d</option> <varname>id</varname></term>
<term>
<option>--id</option> <replaceable>id</replaceable>,
<option>-d</option> <replaceable>id</replaceable>
</term>
<listitem><para>Specify the id of the object to operate on.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--label</option> <varname>name</varname>,
<option>-a</option> <varname>name</varname></term>
<term>
<option>--label</option> <replaceable>name</replaceable>,
<option>-a</option> <replaceable>name</replaceable>
</term>
<listitem><para>Specify the name of the object to operate on
(or the token label when <option>--init-token</option>
is used).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--slot</option> <varname>id</varname></term>
<term>
<option>--slot</option> <replaceable>id</replaceable>
</term>
<listitem><para>Specify the id of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--slot-description</option> <varname>description</varname></term>
<term>
<option>--slot-description</option> <replaceable>description</replaceable>
</term>
<listitem><para>Specify the description of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--slot-index</option> <varname>index</varname></term>
<term>
<option>--slot-index</option> <replaceable>index</replaceable>
</term>
<listitem><para>Specify the index of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--token-label</option> <varname>label</varname></term>
<term>
<option>--token-label</option> <replaceable>label</replaceable>
</term>
<listitem><para>Specify the label of token. Will be used the first slot, that has the
inserted token with this label.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--set-id</option> <varname>id</varname>,
<option>-e</option> <varname>id</varname></term>
<term>
<option>--set-id</option> <replaceable>id</replaceable>,
<option>-e</option> <replaceable>id</replaceable>
</term>
<listitem><para>Set the CKA_ID of the object.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--attr-from</option> <varname>path</varname></term>
<listitem><para>Extract information from <varname>path</varname>
<term>
<option>--attr-from</option> <replaceable>path</replaceable>
</term>
<listitem><para>Extract information from <replaceable>path</replaceable>
(DER-encoded certificate file) and create the corresponding
attributes when writing an object to the token. Example: the
certificate subject name is used to create the CKA_SUBJECT
@ -198,33 +258,43 @@
</varlistentry>
<varlistentry>
<term><option>--input-file</option> <varname>path</varname>,
<option>-i</option> <varname>path</varname></term>
<term>
<option>--input-file</option> <replaceable>path</replaceable>,
<option>-i</option> <replaceable>path</replaceable>
</term>
<listitem><para>Specify the path to a file for input.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--output-file</option> <varname>path</varname>,
<option>-o</option> <varname>path</varname></term>
<term>
<option>--output-file</option> <replaceable>path</replaceable>,
<option>-o</option> <replaceable>path</replaceable>
</term>
<listitem><para>Specify the path to a file for output.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--module</option> <varname>mod</varname></term>
<term>
<option>--module</option> <replaceable>mod</replaceable>
</term>
<listitem><para>Specify a PKCS#11 module (or library) to
load.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--moz-cert</option> <varname>path</varname>,
<option>-z</option> <varname>path</varname></term>
<term>
<option>--moz-cert</option> <replaceable>path</replaceable>,
<option>-z</option> <replaceable>path</replaceable>
</term>
<listitem><para>Tests a Mozilla-like keypair generation
and certificate request. Specify the <varname>path</varname>
and certificate request. Specify the <replaceable>path</replaceable>
to the certificate file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--verbose</option>, <option>-v</option>
</term>
<listitem><para>Causes <command>pkcs11-tool</command> to be
more verbose.</para><para>NB! This does not affect
OpenSC debugging level! To set OpenSC PKCS#11 module into debug

68
doc/tools/pkcs15-crypt.1.xml
View File

@ -35,21 +35,26 @@
<para>
<variablelist>
<varlistentry>
<term><option>--sign, -s</option></term>
<term>
<option>--sign</option>,
<option>-s</option>
</term>
<listitem><para>Perform digital signature operation on
the data read from a file specified using the <option>input</option>
the data read from a file specified using the <option>--input</option>
option. By default, the contents of the file are assumed to
be the result of an MD5 hash operation. Note that <command>pkcs15-crypt</command>
expects the data in binary representation, not ASCII.</para>
<para>The digital signature is stored, in binary representation,
in the file specified by the <option>output</option> option. If
in the file specified by the <option>--output</option> option. If
this option is not given, the signature is printed on standard
output, displaying non-printable characters using their hex notation
xNN (see also <option>--raw</option>).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pkcs1</option></term>
<term>
<option>--pkcs1</option>
</term>
<listitem><para>By default, <command>pkcs15-crypt</command>
assumes that input data has been padded to the correct length
(i.e. when computing an RSA signature using a 1024 bit key,
@ -61,7 +66,9 @@
</varlistentry>
<varlistentry>
<term><option>--sha-1</option></term>
<term>
<option>--sha-1</option>
</term>
<listitem><para>This option tells <command>pkcs15-crypt</command>
that the input file is the result of an SHA1 hash operation,
rather than an MD5 hash. Again, the data must be in binary
@ -69,7 +76,10 @@
</varlistentry>
<varlistentry>
<term><option>--decipher, -c</option></term>
<term>
<option>--decipher</option>,
<option>-c</option>
</term>
<listitem><para>Decrypt the contents of the file specified by
the <option>--input</option> option. The result of the
decryption operation is written to the file specified by the
@ -80,40 +90,53 @@
</varlistentry>
<varlistentry>
<term><option>--key</option> <varname>id</varname>,
<option>-k</option> <varname>id</varname></term>
<term>
<option>--key</option> <replaceable>id</replaceable>,
<option>-k</option> <replaceable>id</replaceable>
</term>
<listitem><para>Selects the ID of the key to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> <varname>N</varname>,
<option>-r</option> <varname>N</varname></term>
<listitem><para>Selects the <varname>N</varname>-th smart
<term>
<option>--reader</option> <replaceable>N</replaceable>,
<option>-r</option> <replaceable>N</replaceable>
</term>
<listitem><para>Selects the <replaceable>N</replaceable>-th smart
card reader configured by the system. If unspecified,
<command>pkcs15-crypt</command> will use the first reader
found.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--input</option> <varname>file</varname>,
<option>-i</option> <varname>file</varname></term>
<term>
<option>--input</option> <replaceable>file</replaceable>,
<option>-i</option> <replaceable>file</replaceable>
</term>
<listitem><para>Specifies the input file to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--output</option> <varname>file</varname>,
<option>-o</option> <varname>file</varname></term>
<term>
<option>--output</option> <replaceable>file</replaceable>,
<option>-o</option> <replaceable>file</replaceable>
</term>
<listitem><para>Any output will be sent to the specified file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--raw, -R</option></term>
<term>
<option>--raw</option>,
<option>-R</option>
</term>
<listitem><para>Outputs raw 8 bit data.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pin</option> <varname>pin</varname>,
<option>-p</option> <varname>pin</varname></term>
<term>
<option>--pin</option> <replaceable>pin</replaceable>,
<option>-p</option> <replaceable>pin</replaceable>
</term>
<listitem><para>When the cryptographic operation requires a
PIN to access the key, <command>pkcs15-crypt</command> will
prompt the user for the PIN on the terminal. Using this option
@ -126,13 +149,18 @@
</varlistentry>
<varlistentry>
<term><option>--aid</option> <varname>aid</varname></term>
<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 be binded to.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--verbose</option>,
<option>-v</option>
</term>
<listitem><para>Causes <command>pkcs15-crypt</command> to be more
verbose. Specify this flag several times to enable debug output
in the OpenSC library.</para></listitem>

107
doc/tools/pkcs15-init.1.xml
View File

@ -46,7 +46,7 @@
<para>
<command>pkcs15-init</command> can be used to create a PKCS #15 structure on
your smart card, create PINs, and install keys and certificates on the card.
This process is also called <emphasis>personalization</emphasis>.
This process is also called <replaceable>personalization</replaceable>.
</para>
<para>
An OpenSC card can have one security officer PIN, and zero or more user PINs.
@ -71,7 +71,7 @@
card profiles that will allow the security officer to override user PINs.
</para>
<para>
For each PIN, you can specify a PUK (also called <emphasis>unblock PIN</emphasis>).
For each PIN, you can specify a PUK (also called <replaceable>unblock PIN</replaceable>).
The PUK can be used to overwrite or unlock a PIN if too many incorrect values
have been entered in a row.
</para>
@ -113,7 +113,7 @@
<command>pkcs15-init --store-pin --id " nn</command>
</para>
<para>
where <emphasis>nn</emphasis> is a PKCS #15 ID in hexadecimal notation. Common
where <replaceable>nn</replaceable> is a PKCS #15 ID in hexadecimal notation. Common
values are 01, 02, etc.
</para>
<para>
@ -136,14 +136,15 @@
<command>pkcs15-init --generate-key " keyspec " --auth-id " nn</command>
</para>
<para>
where <option>keyspec</option> describes the algorithm and length of the
key to be created, such as <option>rsa/512</option>. This will create a 512 bit
where <replaceable>keyspec</replaceable> describes the algorithm and length of the
key to be created, such as <literal>rsa/512</literal>. This will create a 512 bit
RSA key. Currently, only RSA key generation is supported. Note that cards
usually support just a few different key lengths. Almost all cards will support
512 and 1024 bit keys, some will support 768 or 2048 as well.
</para>
<para>
<option>nn</option> is the ID of a user PIN installed previously, e.g. 01.
<replaceable>nn</replaceable> is the ID of a user PIN installed previously,
e.g. <literal>01</literal>.
</para>
<para>
In addition to storing the private portion of the key on the card,
@ -157,7 +158,7 @@
<para>
You can use a private key generated by other means and download it to the card.
For instance, to download a private key contained in a file named
<emphasis>okir.pem</emphasis>, which is in PEM format, you would use
<filename>okir.pem</filename>, which is in PEM format, you would use
</para>
<para>
<command>pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01</command>
@ -170,7 +171,7 @@
<para>
Note the use of the <option>--id</option> option. The current
<command>pkcs15</command> profile defines two key templates, one for
authentication (key ID 45), and one for non-repudiation purposes (key ID 46).
authentication (key ID <literal>45</literal>), and one for non-repudiation purposes (key ID <literal>46</literal>).
Other key templates will probably be added in the future. Note that if you don't
specify a key ID, <command>pkcs15-init</command> will pick just the first key
template defined by the profile.
@ -226,8 +227,8 @@
01</command>
</para>
<para>
This will install the private key contained in the file <emphasis>okir.p12</emphasis>,
and protect it with the PIN referenced by authentication ID <emphasis>01</emphasis>.
This will install the private key contained in the file <filename>okir.p12</filename>,
and protect it with the PIN referenced by authentication ID <literal>01</literal>.
It will also store any X.509 certificates contained in the file, which is
usually the user certificate that goes with the key, as well as the CA certificate.
</para>
@ -239,33 +240,37 @@
<para>
<variablelist>
<varlistentry>
<term><option>--profile</option> <emphasis>name</emphasis>,
<option>-p</option> <emphasis>name</emphasis></term>
<term>
<option>--profile</option> <replaceable>name</replaceable>,
<option>-p</option> <replaceable>name</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to load the specified general
profile. Currently, the only application profile defined is
<command>pkcs15</command>, but you can write your own profiles and
<literal>pkcs15</literal>, but you can write your own profiles and
specify them using this option.
</para>
<para>
The profile name can be combined with one or more <emphasis>profile
options</emphasis>, which slightly modify the profile's behavior.
The profile name can be combined with one or more profile
options, which slightly modify the profile's behavior.
For instance, the default OpenSC profile supports the
<option>openpin</option> option, which installs a single PIN during
card initialization. This PIN is then used both as the SO PIN as
well as the user PIN for all keys stored on the card.
</para>
<para>
Profile name and options are separated by a <option>+</option>
character, as in <option>pkcs15+onepin</option>.
Profile name and options are separated by a <literal>+</literal>
character, as in <literal>pkcs15+onepin</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--card-profile</option> <emphasis>name</emphasis>,
<option>-c</option> <emphasis>name</emphasis></term>
<term>
<option>--card-profile</option> <replaceable>name</replaceable>,
<option>-c</option> <replaceable>name</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to load the specified card
@ -275,7 +280,10 @@
</varlistentry>
<varlistentry>
<term><option>--create-pkcs15, -C</option></term>
<term>
<option>--create-pkcs15</option>,
<option>-C</option>
</term>
<listitem>
<para>
This tells <command>pkcs15-init</command> to create a PKCS #15
@ -285,7 +293,10 @@
</varlistentry>
<varlistentry>
<term><option>--erase-card, -E</option></term>
<term>
<option>--erase-card</option>,
<option>-E</option>
</term>
<listitem>
<para>
This will erase the card prior to creating the PKCS #15 structure,
@ -296,12 +307,14 @@
</varlistentry>
<varlistentry>
<term><option>--generate-key</option> <emphasis>keyspec</emphasis>,
<option>-G</option> <emphasis>keyspec</emphasis></term>
<term>
<option>--generate-key</option> <replaceable>keyspec</replaceable>,
<option>-G</option> <replaceable>keyspec</replaceable>
</term>
<listitem>
<para>
Tells the card to generate new key and store it on the card.
<emphasis>keyspec</emphasis> consists of an algorithm name
<replaceable>keyspec</replaceable> consists of an algorithm name
(currently, the only supported name is <option>RSA</option>),
optionally followed by a slash and the length of the key in bits.
It is a good idea to specify the key ID along with this command,
@ -316,8 +329,10 @@
</varlistentry>
<varlistentry>
<term><option>--store-private-key</option> <emphasis>filename</emphasis>,
<option>-S</option> <emphasis>filename</emphasis></term>
<term>
<option>--store-private-key</option> <replaceable>filename</replaceable>,
<option>-S</option> <replaceable>filename</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to download the specified
@ -337,7 +352,9 @@
</varlistentry>
<varlistentry>
<term><option>--store-public-key</option> <emphasis>filename</emphasis></term>
<term>
<option>--store-public-key</option> <replaceable>filename</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to download the specified
@ -350,8 +367,10 @@
</varlistentry>
<varlistentry>
<term><option>--store-certificate</option> <emphasis>filename</emphasis>,
<option>-X</option> <emphasis>filename</emphasis></term>
<term>
<option>--store-certificate</option> <replaceable>filename</replaceable>,
<option>-X</option> <replaceable>filename</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to store the certificate given
@ -369,8 +388,10 @@
</varlistentry>
<varlistentry>
<term><option>--update-certificate</option> <emphasis>filename</emphasis>,
<option>-U</option> <emphasis>filename</emphasis></term>
<term>
<option>--update-certificate</option> <replaceable>filename</replaceable>,
<option>-U</option> <replaceable>filename</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to update the certificate
@ -385,8 +406,10 @@
</varlistentry>
<varlistentry>
<term><option>--use-default-transport-keys</option>,
<option>-T</option></term>
<term>
<option>--use-default-transport-keys</option>,
<option>-T</option>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to not ask for the transport
@ -396,7 +419,12 @@
</varlistentry>
<varlistentry>
<term><option>--so-pin, --so-puk, --pin, --puk</option></term>
<term>
<option>--so-pin</option>,
<option>--so-puk</option>,
<option>--pin</option>,
<option>--puk</option>
</term>
<listitem>
<para>
These options can be used to specify PIN/PUK values on the command
@ -410,11 +438,13 @@
</varlistentry>
<varlistentry>
<term><option>--options-file</option> <emphasis>filename</emphasis></term>
<term>
<option>--options-file</option> <replaceable>filename</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to read additional options
from <emphasis>filename</emphasis>. The file is supposed to
from <replaceable>filename</replaceable>. The file is supposed to
contain one long option per line, without the leading dashes,
for instance:
<programlisting>
@ -429,7 +459,10 @@
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--verbose</option>,
<option>-v</option>
</term>
<listitem>
<para>
Causes <command>pkcs15-init</command> to be more verbose. Specify this

110
doc/tools/pkcs15-tool.1.xml
View File

@ -37,7 +37,10 @@
<para>
<variablelist>
<varlistentry>
<term><option>--learn-card, -L</option></term>
<term>
<option>--learn-card</option>,
<option>-L</option>
</term>
<listitem><para>Cache PKCS #15 token data to the local filesystem.
Subsequent operations are performed on the cached data where possible.
If the cache becomes out-of-sync with the token state (eg. new key is
@ -46,36 +49,50 @@
</varlistentry>
<varlistentry>
<term><option>--list-applications</option></term>
<term>
<option>--list-applications</option>
</term>
<listitem><para>List the on-card PKCS#15 applications</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-certificate</option> <varname>cert</varname>,
<option>-r</option> <varname>cert</varname></term>
<term>
<option>--read-certificate</option> <replaceable>cert</replaceable>,
<option>-r</option> <replaceable>cert</replaceable>
</term>
<listitem><para>Reads the certificate with the given id.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-certificates, -c</option></term>
<term>
<option>--list-certificates</option>,
<option>-c</option>
</term>
<listitem><para>Lists all certificates stored on the token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-data-object</option> <varname>cert</varname>,
<option>-R</option> <varname>data</varname></term>
<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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verify-pin</option></term>
<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>--list-data-objects, -C</option></term>
<term>
<option>--list-data-objects</option>,
<option>-C</option>
</term>
<listitem><para>Lists 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.
@ -84,30 +101,43 @@
</varlistentry>
<varlistentry>
<term><option>--list-pins</option></term>
<term>
<option>--list-pins</option>
</term>
<listitem><para>Lists 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>--dump, -D</option></term>
<term>
<option>--dump</option>,
<option>-D</option>
</term>
<listitem><para>Dump card objects.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--change-pin</option></term>
<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>--unblock-pin, -u</option></term>
<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>--list-keys, -k</option></term>
<term>
<option>--list-keys</option>,
<option>-k</option>
</term>
<listitem><para>Lists 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.
@ -117,58 +147,78 @@
</varlistentry>
<varlistentry>
<term><option>--list-public-keys</option></term>
<term>
<option>--list-public-keys</option>
</term>
<listitem><para>Lists all public keys stored on the token, including
key name, id, algorithm and length information.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-public-key</option> <varname>id</varname></term>
<listitem><para>Reads the public key with id <varname>id</varname>,
<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> <varname>id</varname></term>
<listitem><para>Reads the public key with id <varname>id</varname>,
writing the output in format suitable for $HOME/.ssh/authorized_keys.</para></listitem>
<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></listitem>
</varlistentry>
<varlistentry>
<term><option>--output</option> <varname>filename</varname>,
<option>-o</option> <varname>filename</varname></term>
<term>
<option>--output</option> <replaceable>filename</replaceable>,
<option>-o</option> <replaceable>filename</replaceable>
</term>
<listitem><para>Specifies where key output should be written.
If <varname>filename</varname> already exists, it will be overwritten.
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>--no-cache</option></term>
<term>
<option>--no-cache</option>
</term>
<listitem><para>Disables token data caching.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--auth-id</option> <varname>pin</varname>,
<option>-a</option> <varname>pin</varname></term>
<term>
<option>--auth-id</option> <replaceable>pin</replaceable>,
<option>-a</option> <replaceable>pin</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>--aid</option> <varname>aid</varname></term>
<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 be binded to.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> <varname>num</varname></term>
<term>
<option>--reader</option> <replaceable>num</replaceable>
</term>
<listitem><para>Forces <command>pkcs15-tool</command> to use reader
number <varname>num</varname> for operations. The default is to use
number <replaceable>num</replaceable> for operations. The default is to use
reader number 0, the first reader in the system.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<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>

73
doc/tools/westcos-tool.1.xml
View File

@ -36,19 +36,28 @@
<para>
<variablelist>
<varlistentry>
<term><option>--reader, r</option> num</term>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>
Use the given reader. The default is the first reader with a card.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-key, -g</option></term>
<term>
<option>--generate-key</option>,
<option>-g</option>
</term>
<listitem><para>Generate a private key on smart card. The smart card must be
not finalized and a PIN must be installed (ie. file for PIN must be created, see option
-i). By default key length is 1536 bits. User authentication is required for
@ -56,65 +65,80 @@
</varlistentry>
<varlistentry>
<term><option>--overwrite-key, -o</option></term>
<term>
<option>--overwrite-key</option>,
<option>-o</option>
</term>
<listitem><para>Overwrite the key if there is already a key on card.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--key-length</option> length,
<option>-l</option> length
<option>--key-length</option> <replaceable>length</replaceable>,
<option>-l</option> <replaceable>length</replaceable>
</term>
<listitem><para>Change the length of private key, use with <option>-g</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--install-pin, -i</option></term>
<term>
<option>--install-pin</option>,
<option>-i</option>
</term>
<listitem><para>Install PIN file in token, you must provide PIN value
with <option>-x</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--pin-value</option> value,
<option>-x</option> value
<option>--pin-value</option> <replaceable>value</replaceable>,
<option>-x</option> <replaceable>value</replaceable>
</term>
<listitem><para>set value of PIN.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--puk-value</option> value,
<option>-y</option> value
<option>--puk-value</option> <replaceable>value</replaceable>,
<option>-y</option> <replaceable>value</replaceable>
</term>
<listitem><para>set value of PUK (or value of new PIN for change PIN
command see <option>-n</option>).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--change-pin, -n</option></term>
<term>
<option>--change-pin</option>,
<option>-n</option>
</term>
<listitem><para>Changes a PIN stored on the token. User authentication
is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--unblock-pin, -u</option></term>
<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>--certificate</option> file,
<option>-t</option> file
<option>--certificate</option> <replaceable>file</replaceable>,
<option>-t</option> <replaceable>file</replaceable>
</term>
<listitem><para>Write certificate file in PEM format to the
card. User authentication is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--finalize, -f</option></term>
<term>
<option>--finalize</option>,
<option>-f</option>
</term>
<listitem><para>Finalize the card. Once finalized the default key is invalidated so PIN and PUK
can't be changed anymore without user authentication. Warning,
un-finalized are insecure because PIN can be changed without user authentication (knowledge of default key
@ -123,8 +147,8 @@
<varlistentry>
<term>
<option>--read-file</option> path,
<option>-j</option> path
<option>--read-file</option> <replaceable>path</replaceable>,
<option>-j</option> <replaceable>path</replaceable>
</term>
<listitem><para>Get the file path the file is written
on disk with path name. User authentication
@ -133,8 +157,8 @@
<varlistentry>
<term>
<option>--write-file</option> path,
<option>-k</option> path
<option>--write-file</option> <replaceable>path</replaceable>,
<option>-k</option> <replaceable>path</replaceable>
</term>
<listitem><para>Put the file with name path from disk
to card the file is written in path. User authentication
@ -142,12 +166,17 @@
</varlistentry>
<varlistentry>
<term><option>--help, -h</option></term>
<term>
<option>--help</option>,
<option>-h</option>
</term>
<listitem><para>Print help message on screen.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<term>
<option>-v</option>
</term>
<listitem><para>Causes <command>westcos-tool</command> to be more
verbose. Specify this flag several times to enable debug output
in the OpenSC library.</para></listitem>