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

Merge pull request #5 from marschap/doc-for-staging 

Doc updates for staging
This commit is contained in:
Ludovic Rousseau 2012-01-09 01:25:36 -08:00
parent e2b5603ff7 3b6c985cca
commit 3f7db42878
25 changed files with 2069 additions and 1528 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
configure.ac
View File

@ -581,6 +581,7 @@ fi
AC_CONFIG_FILES([
Makefile
doc/Makefile
doc/tools/Makefile
etc/Makefile
src/Makefile
src/common/Makefile

47
doc/Makefile.am
View File

@ -1,47 +1,6 @@
MAINTAINERCLEANFILES = $(srcdir)/Makefile.in
SUBDIRS = tools
dist_noinst_SCRIPTS = html.xsl man.xsl
dist_noinst_DATA = $(srcdir)/tools/*.xml api.css
if ENABLE_DOC
html_DATA = html.out/*
endif
if ENABLE_MAN
man1_MANS = man.out/*.1
man5_MANS = man.out/*.5
endif
html.out/*: html.out
html.out: api.work
-rm -fr html.tmp html.out
$(MKDIR_P) html.tmp
$(XSLTPROC) --nonet --path "$(srcdir)/api" --xinclude -o "html.tmp/tools.html" "api.work/html.xsl" "$(srcdir)/tools/tools.xml"
mv html.tmp html.out
man.out/*.1: man.out
man.out: api.work
-rm -fr man.tmp man.out
$(MKDIR_P) man.tmp
$(XSLTPROC) --nonet --path "$(srcdir)/api" --xinclude -o "man.tmp/" "api.work/man.xsl" "$(srcdir)/tools/tools.xml"
mv man.tmp man.out
man.out/*.5: man.out/*.1
#
# This part is needed as found no
# way to make xsltproc find xsl-stylesheets
# in builddir while xsl on srcdir
#
api.work: \
$(abs_srcdir)/html.xsl \
$(abs_srcdir)/man.xsl \
$(abs_srcdir)/api.css
-rm -fr api.work
$(MKDIR_P) api.work
$(LN_S) "$(abs_srcdir)/html.xsl" api.work/html.xsl
$(LN_S) "$(abs_srcdir)/man.xsl" api.work/man.xsl
$(LN_S) "$(abs_srcdir)/api.css" api.work/api.css
$(LN_S) "$(xslstylesheetsdir)" api.work/xsl-stylesheets
clean-local:
-rm -fr html.tmp man.tmp api.work html.out man.out
dist_noinst_DATA = api.css

13
doc/html.xsl
View File

@ -3,14 +3,13 @@
<!ENTITY css SYSTEM "api.css">
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="xsl-stylesheets/html/docbook.xsl"/>
<xsl:import href="docbook.xsl"/>
<xsl:param name="toc.section.depth" select="0"/>
<xsl:template name="user.head.content">
<style type="text/css">
<xsl:comment>
&css;
</xsl:comment>
</style>
<style type="text/css">
<xsl:comment>
&css;
</xsl:comment>
</style>
</xsl:template>
</xsl:stylesheet>

2
doc/man.xsl
View File

@ -1,4 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="xsl-stylesheets/manpages/docbook.xsl"/>
<xsl:import href="docbook.xsl"/>
</xsl:stylesheet>

25
doc/tools/Makefile.am Normal file
View File

@ -0,0 +1,25 @@
MAINTAINERCLEANFILES = $(srcdir)/Makefile.in
dist_noinst_DATA = $(wildcard $(srcdir)/*.xml)
if ENABLE_DOC
html_DATA = tools.html
endif
if ENABLE_MAN
man1_MANS = $(patsubst $(srcdir)/%.xml, %, $(wildcard $(srcdir)/*.1.xml))
man5_MANS = $(patsubst $(srcdir)/%.xml, %, $(wildcard $(srcdir)/*.5.xml))
endif
tools.html: $(srcdir)/tools.xml $(wildcard $(srcdir)/*.1.xml) $(wildcard $(srcdir)/*.5.xml)
$(XSLTPROC) --nonet --path "$(srcdir)/..:$(xslstylesheetsdir)/html" --xinclude -o $@ html.xsl $<
%.1: $(srcdir)/%.1.xml
sed -e 's|@pkgdatadir[@]|$(pkgdatadir)|g' < $< \
| $(XSLTPROC) --nonet --path "$(srcdir)/..:$(xslstylesheetsdir)/manpages" --xinclude -o $@ man.xsl $<
%.5: $(srcdir)/%.5.xml
sed -e 's|@pkgdatadir[@]|$(pkgdatadir)|g' < $< \
| $(XSLTPROC) --nonet --path "$(srcdir)/..:$(xslstylesheetsdir)/manpages" --xinclude -o $@ man.xsl $<
clean-local:
-rm -rf $(html_DATA) $(man1_MANS) $(man5_MANS)

85
doc/tools/cardos-tool.1.xml Normal file
View File

@ -0,0 +1,85 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="cardos-tool">
<refmeta>
<refentrytitle>cardos-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>cardos-tool</refname>
<refpurpose>displays information about Card OS-based security tokens or format them
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>cardos-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <command>cardos-tool</command> utility is used to display information about
smart cards and similar security tokens based on Siemens Card/OS M4.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<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>--format</option>,
<option>-f</option>
</term>
<listitem><para>Format the card or token.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--info</option>,
<option>-i</option>
</term>
<listitem><para>Display information about the card or token.</para></listitem>
</varlistentry>
<varlistentry>
<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 <literal>0</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<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>
<varlistentry>
<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>
</variablelist>
</para>
</refsect1>
</refentry>

66
doc/tools/cardos-tool.xml
View File

@ -1,66 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="cardos-tool">
<refmeta>
<refentrytitle>cardos-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>cardos-tool</refname>
<refpurpose>displays information about Card OS-based security tokens or format them
</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>cardos-tool</command> [OPTIONS]
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The <command>cardos-tool</command> utility is used to display information about
smart cards and similar security tokens based on Siemens Card/OS M4.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<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>
<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.
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>
</varlistentry>
<varlistentry>
<term><option>--wait, -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>
</varlistentry>
</variablelist>
</para>
</refsect1>
</refentry>

173
doc/tools/cryptoflex-tool.1.xml Normal file
View File

@ -0,0 +1,173 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="cryptoflex-tool">
<refmeta>
<refentrytitle>cryptoflex-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>cryptoflex-tool</refname>
<refpurpose>utility for manipulating Schlumberger Cryptoflex data structures</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>cryptoflex-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>cryptoflex-tool</command> is used to manipulate PKCS
data structures on Schlumberger Cryptoflex smart cards. Users
can create, list and read PINs and keys stored on the smart card.
User PIN authentication is performed for those operations that require it.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<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>--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> <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>--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>--generate-key</option>,
<option>-g</option>
</term>
<listitem><para>Generate a new RSA key pair</para></listitem>
</varlistentry>
<varlistentry>
<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>--list-keys</option>,
<option>-l</option>
</term>
<listitem><para>Lists all keys stored in a public key file</para></listitem>
</varlistentry>
<varlistentry>
<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>--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> <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>--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>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>Forces <command>cryptoflex-tool</command> to use
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</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>
</varlistentry>
<varlistentry>
<term>
<option>--verify-pin</option>,
<option>-V</option>
</term>
<listitem><para>Verifies CHV1 before issuing commands</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry>
<refentrytitle>pkcs15-tool</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

134
doc/tools/cryptoflex-tool.xml
View File

@ -1,134 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="cryptoflex-tool">
<refmeta>
<refentrytitle>cryptoflex-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>cryptoflex-tool</refname>
<refpurpose>utility for manipulating Schlumberger Cryptoflex data structures</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>cryptoflex-tool</command> [OPTIONS]
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
<command>cryptoflex-tool</command> is used to manipulate PKCS
data structures on Schlumberger Cryptoflex smart cards. Users
can create, list and read PINs and keys stored on the smart card.
User PIN authentication is performed for those operations that require it.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term><option>--verify-pin, -V</option></term>
<listitem><para>Verifies CHV1 before issuing commands</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-keys, -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>
</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>
</varlistentry>
<varlistentry>
<term><option>--generate-key, -g</option></term>
<listitem><para>Generate a new RSA key pair</para></listitem>
</varlistentry>
<varlistentry>
<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>
<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>
<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>,
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>,
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>,
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
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>
<listitem><para>Forces <command>cryptoflex-tool</command> to use
reader number <varname>num</varname> 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>
<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>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>pkcs15-tool(1)</para>
</refsect1>
</refentry>

79
doc/tools/eidenv.xml → doc/tools/eidenv.1.xml
View File

@ -3,7 +3,9 @@
<refmeta>
<refentrytitle>eidenv</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -12,12 +14,12 @@
electronic identity cards</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>eidenv</command> [OPTIONS]
</para>
</refsect1>
<refsynopsisdiv>
<cmdsynopsis>
<command>eidenv</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
@ -36,45 +38,66 @@
<para>
<variablelist>
<varlistentry>
<term><option>--reader, r</option> num</term>
<listitem><para>
Use the given reader. The default is the first reader with a card.
</para></listitem>
<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>
<varlistentry>
<term><option>--wait, -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>
<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>--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>--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>
<listitem><para>Executes the given program with
data in environment variables.</para></listitem>
<term>
<option>--version</option>,
<option>-v</option>
</term>
<listitem><para>Prints the version
of the utility and exits.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
</variablelist>

125
doc/tools/netkey-tool.xml → doc/tools/netkey-tool.1.xml
View File

@ -3,7 +3,9 @@
<refmeta>
<refentrytitle>netkey-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -11,10 +13,13 @@
<refpurpose>administrative utility for Netkey E4 cards</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para><command>netkey-tool</command> [OPTIONS] [COMMAND]</para>
</refsect1>
<refsynopsisdiv>
<cmdsynopsis>
<command>netkey-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
<arg choice="opt"><replaceable class="parameter">COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
@ -30,34 +35,54 @@
<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>
<listitem><para>Use smart card in specified reader. Default is reader 0.</para></listitem>
</varlistentry>
<varlistentry>
<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>
<varlistentry>
<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>
<listitem><para>Causes <command>netkey-tool</command> to be more verbose. This
options may be specified multiple times to increase verbosity.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
@ -93,22 +118,40 @@
<para>
<variablelist>
<varlistentry>
<term><option>unblock</option> { <option>pin</option> | <option>pin0</option> |
<option>pin1</option> }</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>
<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
<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>change</option> { <option>pin</option> | <option>puk</option> |
<option>pin0</option> | <option>pin1</option> } new-pin</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
<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>
</varlistentry>
<varlistentry>
<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
@ -116,21 +159,12 @@
PUK-value.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>cert</option> number filename</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>
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>
<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
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>
<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>
</variablelist>
</para>
@ -138,7 +172,12 @@
<refsect1>
<title>See also</title>
<para>opensc-explorer(1)</para>
<para>
<citerefentry>
<refentrytitle>opensc-explorer</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
<refsect1>

348
doc/tools/opensc-explorer.1.xml Normal file
View File

@ -0,0 +1,348 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="opensc-explorer">
<refmeta>
<refentrytitle>opensc-explorer</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>opensc-explorer</refname>
<refpurpose>
generic interactive utility for accessing smart card
and similar security token functions
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>opensc-explorer</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <command>opensc-explorer</command> utility can be
used interactively to perform miscellaneous operations
such as exploring the contents of or sending arbitrary
APDU commands to a smart card or similar security token.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
The following are the command-line options for
<command>opensc-explorer</command>. There are additional
interactive commands available once it is running.
<variablelist>
<varlistentry>
<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>--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 <replaceable>path</replaceable> is empty (e.g. <command>opensc-explorer
--mf ""</command>), then no file is explicitly selected.
</para></listitem>
</varlistentry>
<varlistentry>
<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>--verbose</option>, <option>-v</option>
</term>
<listitem><para>
Causes <command>opensc-explorer</command> to be more
verbose. Specify this flag several times to enable
debug output in the opensc library.
</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--wait</option>, <option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<para>
The following commands are supported at the <command>opensc-explorer</command>
interactive prompt.
<variablelist>
<varlistentry>
<term>
<command>apdu</command> <replaceable>hex-data</replaceable>
</term>
<listitem>
<para>Send a custom APDU command <replaceable>hex-data</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>asn1</command> <replaceable>file-id</replaceable>
</term>
<listitem><para>Parse and print the ASN.1 encoded content of the file specified by
<replaceable>file-id</replaceable>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>cat</command> [<replaceable>file-id</replaceable>]
</term>
<term>
<command>cat sfi:</command><replaceable>short-id</replaceable>
</term>
<listitem><para>Print the contents of the currently selected EF or the contents
of a file specified by <replaceable>file-id</replaceable> or the short file id
<replaceable>short-id</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<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>
<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>
<para>
Change PIN: change CHV2 00:00:00:00:00:00 "foobar"
</para>
<para>
Set PIN: change CHV2 "foobar"
</para>
<para>
Change PIN with pinpad: change CHV2
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<command>debug</command> [<replaceable>level</replaceable>]
</term>
<listitem>
<para>Set OpenSC debug level to <replaceable>level</replaceable>.</para>
<para>If <replaceable>level</replaceable> is omitted the current debug level will be shown.</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<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 <replaceable>output</replaceable> while the tag of
the card's data is specified by <replaceable>hex-tag</replaceable>.
</para>
<para>
If <replaceable>output</replaceable> is omitted, the name of the output file will be
derived from <replaceable>hex-tag</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>do_put</command> <replaceable>hex-tag</replaceable> <replaceable>input</replaceable>
</term>
<listitem>
<para>Update internal card's 'tagged' data. </para>
<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 <literal>"</literal> enclosed string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>erase</command>
</term>
<listitem><para>Erase the card, if the card supports it.</para></listitem>
</varlistentry>
<varlistentry>
<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 <replaceable>output</replaceable> while the card file is specified by <replaceable>file-id</replaceable>.
</para>
<para>
If <replaceable>output</replaceable> is omitted, the name of the output file will be
derived from the full card path to <replaceable>file-id</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<command>ls</command>
</term>
<listitem><para>List all files in the current DF</para></listitem>
</varlistentry>
<varlistentry>
<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>
<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 <replaceable>input</replaceable> while the card file is specified by <replaceable>file-id</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>quit</command>
</term>
<listitem><para>Exit the program.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<command>random</command> <replaceable>count</replaceable>
</term>
<listitem>
<para>Generate random sequence of <replaceable>count</replaceable> bytes.</para>
</listitem>
</varlistentry>
<varlistentry>
<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>
<command>update_binary</command> <replaceable>file-id</replaceable> <replaceable>offs</replaceable> <replaceable>data</replaceable>
</term>
<listitem>
<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 <literal>"</literal> enclosed string. </para>
</listitem>
</varlistentry>
<varlistentry>
<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 <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 <literal>"</literal> enclosed string. </para>
</listitem>
</varlistentry>
<varlistentry>
<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 <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
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry>
<refentrytitle>opensc-tool</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

297
doc/tools/opensc-explorer.xml
View File

@ -1,297 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="opensc-explorer">
<refmeta>
<refentrytitle>opensc-explorer</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>opensc-explorer</refname>
<refpurpose>
generic interactive utility for accessing smart card
and similar security token functions
</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>opensc-explorer</command> [OPTIONS]
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The <command>opensc-explorer</command> utility can be
used interactively to perform miscellaneous operations
such as exploring the contents of or sending arbitrary
APDU commands to a smart card or similar security token.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
The following are the command-line options for
<command>opensc-explorer</command>. There are additional
interactive commands available once it is running.
<variablelist>
<varlistentry>
<term>
<option>--reader</option> num,
<option>-r</option> num
</term>
<listitem><para>
Use the given reader number. The default
is 0, the first reader in the system.
</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--card-driver</option> driver,
<option>-c</option> driver
</term>
<listitem><para>
Use the given card driver. The default is
auto-detected.
</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--mf</option> path,
<option>-m</option> path
</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
--mf ""</command>), then no file is explicitly selected.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<listitem><para>
Causes <command>opensc-explorer</command> to be more
verbose. Specify this flag several times to enable
debug output in the opensc library.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<para>
The following commands are supported at the <command>opensc-explorer</command>
interactive prompt.
<variablelist>
<varlistentry>
<term><option>ls</option></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>
</varlistentry>
<varlistentry>
<term><option>cat</option> [<varname>file-id</varname>]</term>
<term><option>cat</option> sfi:<varname>sfi-id</varname></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>.
</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,
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.
</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>
</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>
</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.
</para>
<para>
If <varname>key</varname> is omitted, PIN will be verified with PIN-Pad.
</para>
<para>
Example: verify CHV0 31:32:33:34:00:00:00:00
</para>
</listitem>
</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>
<para>
Examples:
</para>
<para>
Change PIN: change CHV2 00:00:00:00:00:00 "foobar"
</para>
<para>
Set PIN: change CHV2 "foobar"
</para>
<para>
Change PIN with pinpad: change CHV2
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>put</option> <varname>file-id</varname> <varname>input</varname></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>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>get</option> <varname>file-id</varname> [<varname>output</varname>]</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>.
</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>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>do_put</option> <varname>hex-tag</varname> <varname>input</varname></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
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>
<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>
<para>
If <varname>output</varname> is ommited, the name of the output file will be
derivated from <varname>hex-tag</varname>.
</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>
</varlistentry>
<varlistentry>
<term><option>erase</option></term>
<listitem><para>erase the card, if the card supports it.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>random</option> <varname>count</varname></term>
<listitem>
<para>generate random sequence of <varname>count</varname> 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>
<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
as a '"' encolsed string. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>update_binary</option> <varname>file-id</varname> <varname>offs</varname>
<varname>data</varname></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
as a '"' encolsed string. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>debug</option> [<varname>level</varname>]</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>
</listitem>
</varlistentry>
<varlistentry>
<term><option>apdu</option> <varname>hex_data</varname></term>
<listitem>
<para>send a custom APDU command <varname>hex_data</varname>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>asn1</option> <varname>file-id</varname></term>
<listitem>
<para>parse and print the ASN1 encoded content of the file specified by
<varname>file-id</varname>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>quit</option></term>
<listitem><para>exit the program.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>opensc-tool(1)</para>
</refsect1>
</refentry>

139
doc/tools/opensc-tool.1.xml Normal file
View File

@ -0,0 +1,139 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="opensc-tool">
<refmeta>
<refentrytitle>opensc-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>opensc-tool</refname>
<refpurpose>generic smart card utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>opensc-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <command>opensc-tool</command> utility can be used from the command line to perform
miscellaneous smart card operations such as getting the card ATR or
sending arbitrary APDU commands to a card.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<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>--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>--info</option>,
<option>-i</option>
</term>
<listitem><para>Print information about OpenSC, such as version and enabled components.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--list-drivers</option>,
<option>-D</option>
</term>
<listitem><para>List all installed card drivers.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--list-files</option>,
<option>-f</option>
</term>
<listitem><para>Recursively list all files stored on card.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--list-readers</option>,
<option>-l</option>
</term>
<listitem><para>List all configured readers.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--name</option>,
<option>-n</option>
</term>
<listitem><para>Print the name of the inserted card (driver).</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>Use the given reader number.
The default is <literal>0</literal>, the first reader in the system.</para></listitem>
</varlistentry>
<varlistentry>
<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
<code>AA:BB:CC:DD:EE:FF...</code>.</para></listitem>
</varlistentry>
<varlistentry>
<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>--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>
<varlistentry>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry>
<refentrytitle>opensc-explorer</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

96
doc/tools/opensc-tool.xml
View File

@ -1,96 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="opensc-tool">
<refmeta>
<refentrytitle>opensc-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>opensc-tool</refname>
<refpurpose>generic smart card utility</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>opensc-tool</command> [OPTIONS]
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The <command>opensc-tool</command> utility can be used from the command line to perform
miscellaneous smart card operations such as getting the card ATR or
sending arbitrary APDU commands to a card.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term><option>--info, -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>
<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>
<listitem><para>Print the name of the inserted card (driver)</para></listitem>
</varlistentry>
<varlistentry>
<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>
<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>
<listitem><para>Recursively lists all files stored on card</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-readers, -l</option></term>
<listitem><para>Lists all configured readers</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-drivers, -D</option></term>
<listitem><para>Lists all installed card drivers</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader</option> num, <option>-r</option> num</term>
<listitem><para>Use the given reader number. The default is 0, the first reader
in the system.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--card-driver</option> driver, <option>-c</option> driver</term>
<listitem><para>Use the given card driver. The default is auto-detected.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<listitem><para>Causes <command>opensc-tool</command> to be more verbose. Specify this flag several times
to enable debug output in the opensc library.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>opensc-explorer(1)</para>
</refsect1>
</refentry>

198
doc/tools/piv-tool.1.xml Normal file
View File

@ -0,0 +1,198 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="piv-tool">
<refmeta>
<refentrytitle>piv-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>piv-tool</refname>
<refpurpose>smart card utility for HSPD-12 PIV cards</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>piv-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<para>
The <command>piv-tool</command> utility can be used from the command line to perform
miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3.
It is intened for use with test cards only. It can be used to load objects, and generate
key pairs, as well as send arbitrary APDU commands to a card after having authenticated
to the card using the card key provided by the card vendor.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term>
<option>--serial</option>
</term>
<listitem><para>Print the card serial number derived from the CHUID object,
if any. Output is in hex byte format.</para></listitem>
</varlistentry>
<varlistentry>
<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> <replaceable>argument</replaceable>,
<option>-A</option> <replaceable>argument</replaceable>
</term>
<listitem><para>Authenticate to the card using a 2DES or 3DES key.
The <replaceable>argument</replaceable> of the form
<synopsis> {<literal>A</literal>|<literal>M</literal>}<literal>:</literal><replaceable>ref</replaceable><literal>:</literal><replaceable>alg</replaceable></synopsis>
is required, were <literal>A</literal> uses "EXTERNAL AUTHENTICATION"
and <literal>M</literal> uses "MUTUAL AUTHENTICATION".
<replaceable>ref</replaceable> is normally <literal>9B</literal>,
and <replaceable>alg</replaceable> is <literal>03</literal> for 3DES.
The key is provided by the card vendor, and the environment variable
<varname>PIV_EXT_AUTH_KEY</varname> must point to a text file containing
the key in the format:
<code>XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX</code>
</para></listitem>
</varlistentry>
<varlistentry>
<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.
The <replaceable>argument</replaceable> of th form
<synopsis><replaceable>ref</replaceable>:<replaceable>alg</replaceable></synopsis>
is required, where <replaceable>ref</replaceable> is <literal>9A</literal>,
<literal>9C</literal>, <literal>9D</literal> or <literal>9E</literal> and
<replaceable>alg</replaceable> is <literal>06</literal>,
<literal>07</literal>, <literal>11</literal> or <literal>14</literal>
for RSA 1024, RSA 2048, ECC 256 or ECC 384 respectively. </para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--object</option> <replaceable>ContainerID</replaceable>,
<option>-O</option> <replaceable>ContainerID</replaceable>
</term>
<listitem><para>Load an object on to the card.
The <replaceable>ContainerID</replaceable> is as defined in NIST 800-73-n
without leading <literal>0x</literal>. Example: CHUID object is 3000
</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--cert</option> <replaceable>ref</replaceable>,
<option>-s</option> <replaceable>ref</replaceable>
</term>
<listitem><para>Load a certificate on to the card.
<replaceable>ref</replaceable> is <literal>9A</literal>,
<literal>9C</literal>, <literal>9D</literal> or
<literal>9E</literal></para></listitem>
</varlistentry>
<varlistentry>
<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.
<replaceable>ref</replaceable> is <literal>9A</literal>,
<literal>9C</literal>, <literal>9D</literal> or
<literal>9E</literal></para></listitem>
</varlistentry>
<varlistentry>
<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> <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> <replaceable>file</replaceable>
</term>
<listitem><para>Print properties of the key slots. Needs 'admin' authentication.
</para></listitem>
</varlistentry>
<varlistentry>
<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
<code>AA:BB:CC:DD:EE:FF...</code>.
This option may be repeated.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--reader</option> <replaceable>num</replaceable>,
<option>-r</option> <replaceable>num</replaceable>
</term>
<listitem><para>Use the given reader number. The default is
<literal>0</literal>, the first reader in the system.</para></listitem>
</varlistentry>
<varlistentry>
<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</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<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>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<citerefentry>
<refentrytitle>opensc-tool</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

130
doc/tools/piv-tool.xml
View File

@ -1,130 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="piv-tool">
<refmeta>
<refentrytitle>piv-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>piv-tool</refname>
<refpurpose>smart card utility for HSPD-12 PIV cards</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>piv-tool</command> [OPTIONS]
</para>
</refsect1>
<refsect1>
<para>
The <command>piv-tool</command> utility can be used from the command line to perform
miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3.
It is intened for use with test cards only. It can be used to load objects, and generate
key pairs, as well as send arbitrary APDU commands to a card after having authenticated
to the card using the card key provided by the card vendor.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term><option>--serial</option></term>
<listitem><para>Print the derived card serial number from the CHUID object if any.
output is in hex byte format.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--name, -n</option></term>
<listitem><para>Print the name of the inserted card (driver)</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--admin</option> argument, <option>-A</option> arguement</term>
<listitem><para>Authenticate to the card using a 2DES or 3DES key.
An arguement {A|M}:{ref}:{alg} is required, were A uses "EXTERNAL AUTHENTICATION"
and M uses "MUTUAL AUTHENTICATION". ref is normally 9B, and alg is 03 for
3DES. The key is provided by card vendor, and the environment variable
PIV_EXT_AUTH_KEY must point to a text file with the key in the format:
XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--genkey</option>argument, <option>-G</option> argument</term>
<listitem><para>Generate a key pair on the card and output the public key.
An argument {ref}:{alg} is required, where ref is 9A, 9C, 9D or 9E and alg is
06, 07, 11 or 14 for RSA 1024, RSA 2048, ECC 256 or ECC 384.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--object</option> ContainerID, <option>-O</option> ContainerID</term>
<listitem><para>Load an object on to the card. The ContainerID is defined
in NIST 800-73-n without leading 0x. Example: CHUID object is 3000
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--cert</option> ref, <option>-s</option> ref</term>
<listitem><para>Load a certificate on to the card. ref is 9A, 9C, 9D or 9E</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--compresscert</option> ref, <option>-Z</option> ref</term>
<listitem><para>Load a certificate that has been gziped on to the card.
ref is 9A, 9C, 9D or 9E</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--out</option> file, <option>-o</option> file</term>
<listitem><para>Output file for any operation that produces output.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--in</option> file, <option>-i</option> file</term>
<listitem><para>Input file for any operation that requires an input file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--key-slots-discovery</option> file</term>
<listitem><para>Print properties of the key slots. Needs 'admin' authentication.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--send-apdu</option> apdu, <option>-s</option> apdu</term>
<listitem><para>Sends an arbitrary APDU to the card in the format AA:BB:CC:DD:EE:FF...
This option may be repeated.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--reader, -r</option> num</term>
<listitem><para>Use the given reader number. The default is 0,
the first reader in the system.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--card-driver</option> driver,<option> -c</option> driver</term>
<listitem><para>Use the given card driver. The default is auto-detected.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--wait, -w</option></term>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<listitem><para>Causes <command>piv-tool</command> to be more verbose.
Specify this flag several times to enable debug output in the opensc library.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>opensc-tool(1)</para>
</refsect1>
</refentry>

411
doc/tools/pkcs11-tool.xml → doc/tools/pkcs11-tool.1.xml
View File

@ -3,7 +3,9 @@
<refmeta>
<refentrytitle>pkcs11-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -11,12 +13,12 @@
<refpurpose>utility for managing and using PKCS #11 security tokens</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>pkcs11-tool</command> [OPTIONS]
</para>
</refsect1>
<refsynopsisdiv>
<cmdsynopsis>
<command>pkcs11-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
@ -34,16 +36,161 @@
<para>
<variablelist>
<varlistentry>
<term><option>--login, -l</option></term>
<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
attribute.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--change-pin</option>,
<option>-c</option>
</term>
<listitem><para>Change the user PIN on the token</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--hash</option>,
<option>-h</option>
</term>
<listitem><para>Hash some data.</para></listitem>
</varlistentry>
<varlistentry>
<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>--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
using <option>--change-pin</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--init-token</option>
</term>
<listitem><para>Initialize 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>--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>--keypairgen</option>,
<option>-k</option>
</term>
<listitem><para>Generate a new key pair (public and private pair.)</para></listitem>
</varlistentry>
<varlistentry>
<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>--list-mechanisms</option>,
<option>-M</option>
</term>
<listitem><para>Display a list of mechanisms supported by the token.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--list-objects</option>,
<option>-O</option>
</term>
<listitem><para>Display a list of objects.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--list-slots</option>,
<option>-L</option>
</term>
<listitem><para>Display a list of available slots on the token.</para></listitem>
</varlistentry>
<varlistentry>
<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>--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>--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> <replaceable>path</replaceable>,
<option>-z</option> <replaceable>path</replaceable>
</term>
<listitem><para>Test a Mozilla-like keypair generation
and certificate request. Specify the <replaceable>path</replaceable>
to the certificate file.</para></listitem>
</varlistentry>
<varlistentry>
<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>--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>
@ -52,184 +199,110 @@
</varlistentry>
<varlistentry>
<term><option>--so-pin</option> <varname>pin</varname></term>
<listitem><para>Use the given <varname>pin</varname> as the
<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>--show-info</option>,
<option>-I</option>
</term>
<listitem><para>Display general token information.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--sign</option>,
<option>-s</option>
</term>
<listitem><para>Sign some data.</para></listitem>
</varlistentry>
<varlistentry>
<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> <replaceable>description</replaceable>
</term>
<listitem><para>Specify the description of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<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> <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>--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>
<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>
<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
using <option>--change-pin</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--change-pin, -c</option></term>
<listitem><para>Change the user PIN on the token</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--test, -t</option></term>
<listitem><para>Performs some tests on the token. This
<term>
<option>--test</option>,
<option>-t</option>
</term>
<listitem><para>Perform 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>
<listitem><para>Displays general token information.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-slots, -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>
<listitem><para>Displays a list of mechanisms supported by the token.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list-objects, -O</option></term>
<listitem><para>Displays a list of objects.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sign, s</option></term>
<listitem><para>Sign some data.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--hash, -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>
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>
<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>
<listitem><para>Write a key or certificate object to the token.
<varname>path</varname> 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>
Examples are <literal>cert</literal>, <literal>privkey</literal>
and <literal>pubkey</literal>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--id</option> <varname>id</varname>,
<option>-d</option> <varname>id</varname></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>
<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>
<listitem><para>Specify the id of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--slot-description</option> <varname>description</varname></term>
<listitem><para>Specify the description of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--slot-index</option> <varname>index</varname></term>
<listitem><para>Specify the index of the slot to use.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--token-label</option> <varname>label</varname></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>
<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>
(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
attribute.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--input-file</option> <varname>path</varname>,
<option>-i</option> <varname>path</varname></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>
<listitem><para>Specify the path to a file for output.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--module</option> <varname>mod</varname></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>
<listitem><para>Tests a Mozilla-like keypair generation
and certificate request. Specify the <varname>path</varname>
to the certificate file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<listitem><para>Causes <command>pkcs11-tool</command> to be
<term>
<option>--verbose</option>, <option>-v</option>
</term>
<listitem><para>Cause <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
mode, set the OPENSC_DEBUG environment variable to a
mode, set the <varname>OPENSC_DEBUG</varname> environment variable to a
non-zero number.</para></listitem>
</varlistentry>
<varlistentry>
<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.
<replaceable>path</replaceable> points to the DER-encoded certificate or key file.
</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

184
doc/tools/pkcs15-crypt.xml → doc/tools/pkcs15-crypt.1.xml
View File

@ -3,7 +3,9 @@
<refmeta>
<refentrytitle>pkcs15-crypt</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -11,12 +13,12 @@
<refpurpose>perform crypto operations using pkcs15 smart card</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>pkcs15-crypt</command> [OPTIONS]
</para>
</refsect1>
<refsynopsisdiv>
<cmdsynopsis>
<command>pkcs15-crypt</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
@ -33,41 +35,19 @@
<para>
<variablelist>
<varlistentry>
<term><option>--sign, -s</option></term>
<listitem><para>Perform digital signature operation on
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
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>
<term>
<option>--aid</option> <replaceable>aid</replaceable>
</term>
<listitem><para>Specify the AID of the on-card PKCS#15 applicationi
to bind to. The <replaceable>aid</replaceable> must be in hexadecimal
form.</para></listitem>
</varlistentry>
<varlistentry>
<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,
the input must be padded to 128 bytes to match the modulus
length). When giving the <option>--pkcs1</option> option,
however, <command>pkcs15-crypt</command> will perform the
required padding using the algorithm outlined in the
PKCS #1 standard version 1.5.</para></listitem>
</varlistentry>
<varlistentry>
<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
representation.</para></listitem>
</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
@ -78,40 +58,34 @@
</varlistentry>
<varlistentry>
<term><option>--key</option> <varname>id</varname>,
<option>-k</option> <varname>id</varname></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
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>--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>--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>
<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
@ -124,13 +98,72 @@
</varlistentry>
<varlistentry>
<term><option>--aid</option> <varname>aid</varname></term>
<listitem><para>Specify in a hexadecimal form the AID of the on-card PKCS#15
application to be binded to.</para></listitem>
<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,
the input must be padded to 128 bytes to match the modulus
length). When giving the <option>--pkcs1</option> option,
however, <command>pkcs15-crypt</command> will perform the
required padding using the algorithm outlined in the
PKCS #1 standard version 1.5.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--raw</option>,
<option>-R</option>
</term>
<listitem><para>Outputs raw 8 bit data.</para></listitem>
</varlistentry>
<varlistentry>
<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>--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
representation.</para></listitem>
</varlistentry>
<varlistentry>
<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>
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
this option is not given, the signature is printed on standard
output, displaying non-printable characters using their hex notation
<literal>x</literal><replaceable>NN</replaceable>
(see also <option>--raw</option>).</para></listitem>
</varlistentry>
<varlistentry>
<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>
@ -139,10 +172,19 @@
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>pkcs15-init(1), pkcs15-tool(1)</para>
<para>
<citerefentry>
<refentrytitle>pkcs15-init</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkcs15-tool</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

374
doc/tools/pkcs15-init.xml → doc/tools/pkcs15-init.1.xml
View File

@ -1,9 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="">
<refentry id="pkcs15-init">
<refmeta>
<refentrytitle>pkcs15-init</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>pkcs15-init</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -11,6 +21,13 @@
<refpurpose>smart card personalization utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pkcs15-init</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
@ -29,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.
@ -54,18 +71,18 @@
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>
<para>
For some cards that use the PKCS#15 emulation, the attributes of private objects
For some cards that use the PKCS#15 emulation, the attributes of private objects
are protected and cannot be parsed without authentication (usually with User PIN).
This authentication need to be done immediately after the card binding.
In such cases <option>--verify-pin</option> has to be used.
</para>
</refsect1>
<refsect1>
<title>Modes of operation</title>
<refsect2>
@ -82,7 +99,7 @@
</para>
<para>
If the card supports it, you should erase the contents of the card with
<command>pkcs15-init --erase-card</command> before creating the PKCS#15 structure.
<command>pkcs15-init --erase-card</command> before creating the PKCS#15 structure.
</para>
</refsect2>
@ -96,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>
@ -119,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,
@ -136,11 +154,11 @@
</refsect2>
<refsect2>
<title>Private Key Download</title>
<title>Private Key Upload</title>
<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
You can use a private key generated by other means and upload it to the card.
For instance, to upload a private key contained in a file named
<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>
@ -153,13 +171,13 @@
<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.
</para>
<para>
In addition to the PEM key file format, <command>pkcs15-init</command> also
In addition to the PEM key file format, <command>pkcs15-init</command> also
supports DER encoded keys, and PKCS #12 files. The latter is the file format
used by Netscape Navigator (among others) when exporting certificates to
a file. A PKCS #12 file usually contains the X.509 certificate corresponding
@ -169,9 +187,9 @@
</refsect2>
<refsect2>
<title>Public Key Download</title>
<title>Public Key Upload</title>
<para>
You can also download individual public keys to the card using the
You can also upload individual public keys to the card using the
<option>--store-public-key</option> option, which takes a filename as an
argument. This file is supposed to contain the public key. If you don't
specify a key file format using the <option>--format</option> option,
@ -179,16 +197,16 @@
supported public key file format is DER.
</para>
<para>
Since the corresponding public keys are always downloaded automatically
when generating a new key, or when downloading a private key, you will
Since the corresponding public keys are always uploaded automatically
when generating a new key, or when uploading a private key, you will
probably use this option only very rarely.
</para>
</refsect2>
<refsect2>
<title>Certificate Download</title>
<title>Certificate Upload</title>
<para>
You can download certificates to the card using the
You can upload certificates to the card using the
<option>--store-certificate</option> option, which takes a filename as
an argument. This file is supposed to contain the PEM encoded X.509
certificate.
@ -196,7 +214,7 @@
</refsect2>
<refsect2>
<title>Downloading PKCS #12 bags</title>
<title>Uploading PKCS #12 bags</title>
<para>
Most browsers nowadays use PKCS #12 format files when you ask them to
export your key and certificate to a file. <command>pkcs15-init</command>
@ -209,46 +227,23 @@
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>
</refsect2>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term><option>--profile</option> <emphasis>name</emphasis>,
<option>-p</option> <emphasis>name</emphasis></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
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.
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>.
</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
@ -258,7 +253,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
@ -268,7 +266,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,
@ -279,126 +280,35 @@
</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,
using the <option>id</option> option, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the <option>aid</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--store-private-key</option> <emphasis>filename</emphasis>,
<option>-S</option> <emphasis>filename</emphasis></term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to download the specified
private key to the card. This command will also create a public
key object containing the public key portion. By default, the
file is assumed to contain the key in PEM format. Alternative
formats can be specified using <option>--format</option>.
It is a good idea to specify the key ID along with this command,
using the <option>--id</option> option, otherwise an intrinsic ID
using the <option>id</option> option, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
For the multi-application cards the target PKCS#15 application can be
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the <option>aid</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--store-public-key</option> <emphasis>filename</emphasis></term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to download the specified
public key to the card and create a public key object with the
key ID specified via the <option>--id</option>. By default,
the file is assumed to contain the key in PEM format. Alternative
formats can be specified using <option>--format</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--store-certificate</option> <emphasis>filename</emphasis>,
<option>-X</option> <emphasis>filename</emphasis></term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to store the certificate given
in <option>filename</option> on the card, creating a certificate
object with the ID specified via the <option>--id</option> option.
Without supplied ID an intrisic ID will be calculated from the
certificate's public key. Look the description of the 'pkcs15-id-style'
attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
The file is assumed to contain the PEM encoded certificate.
For the multi-application cards the target application can be specified
by the hexadecimal AID value of the <option>aid</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--update-certificate</option> <emphasis>filename</emphasis>,
<option>-U</option> <emphasis>filename</emphasis></term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to update the certificate
object with the ID specified via the <option>--id</option> option
with the certificate in <option>filename</option>.
The file is assumed to contain a PEM encoded certificate.
</para>
<para>Pay extra attention when updating mail decryption certificates, as
missing certificates can render e-mail messages unreadable!
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-default-transport-keys</option>,
<option>-T</option></term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to not ask for the transport
keys and use default keys, as known by the card driver.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--so-pin, --so-puk, --pin, --puk</option></term>
<listitem>
<para>
These options can be used to specify PIN/PUK values on the command
line. 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 use these options
only on a secured system, or in an options file specified with
<option>--options-file</option>.
</para>
</listitem>
</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>
@ -413,7 +323,146 @@
</varlistentry>
<varlistentry>
<term><option>--verbose, -v</option></term>
<term>
<option>--pin</option>,
<option>--puk</option>
<option>--so-pin</option>,
<option>--so-puk</option>,
</term>
<listitem>
<para>
These options can be used to specify PIN/PUK values on the command
line. 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 use these options
only on a secured system, or in an options file specified with
<option>--options-file</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<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 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 <literal>+</literal>
character, as in <literal>pkcs15+onepin</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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
in <option>filename</option> on the card, creating a certificate
object with the ID specified via the <option>--id</option> option.
Without supplied ID an intrisic ID will be calculated from the
certificate's public key. Look the description of the 'pkcs15-id-style'
attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
The file is assumed to contain the PEM encoded certificate.
For the multi-application cards the target application can be specified
by the hexadecimal AID value of the <option>aid</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--store-public-key</option> <replaceable>filename</replaceable>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to download the specified
public key to the card and create a public key object with the
key ID specified via the <option>--id</option>. By default,
the file is assumed to contain the key in PEM format. Alternative
formats can be specified using <option>--format</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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
private key to the card. This command will also create a public
key object containing the public key portion. By default, the
file is assumed to contain the key in PEM format. Alternative
formats can be specified using <option>--format</option>.
It is a good idea to specify the key ID along with this command,
using the <option>--id</option> option, otherwise an intrinsic ID
will be calculated from the key material. Look the description of
the 'pkcs15-id-style' attribut in the 'pkcs15.profile' for the details
about the algorithm used to calculate intrinsic ID.
For the multi-application cards the target PKCS#15 application can be
specified by the hexadecimal AID value of the <option>aid</option> option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<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
object with the ID specified via the <option>--id</option> option
with the certificate in <option>filename</option>.
The file is assumed to contain a PEM encoded certificate.
</para>
<para>Pay extra attention when updating mail decryption certificates, as
missing certificates can render e-mail messages unreadable!
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--use-default-transport-keys</option>,
<option>-T</option>
</term>
<listitem>
<para>
Tells <command>pkcs15-init</command> to not ask for the transport
keys and use default keys, as known by the card driver.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<option>--verbose</option>,
<option>-v</option>
</term>
<listitem>
<para>
Causes <command>pkcs15-init</command> to be more verbose. Specify this
@ -428,7 +477,12 @@
<refsect1>
<title>See also</title>
<para>pkcs15-profile(5)</para>
<para>
<citerefentry>
<refentrytitle>pkcs15-profile</refentrytitle>
<manvolnum>5</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

26
doc/tools/pkcs15-profile.xml → doc/tools/pkcs15-profile.5.xml
View File

@ -1,9 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="">
<refentry id="pkcs15-profile">
<refmeta>
<refentrytitle>pkcs15-profile</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC File Formats</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -11,13 +13,6 @@
<refpurpose>format of profile for <command>pkcs15-init</command></refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command></command>
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
@ -48,10 +43,19 @@
this soonishly.
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>pkcs15-init(1), pkcs15-crypt(1)</para>
<para>
<citerefentry>
<refentrytitle>pkcs15-init</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkcs15-crypt</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

245
doc/tools/pkcs15-tool.xml → doc/tools/pkcs15-tool.1.xml
View File

@ -3,7 +3,9 @@
<refmeta>
<refentrytitle>pkcs15-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
@ -12,12 +14,12 @@
on smart cards and similar security tokens</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>pkcs15-tool</command> [OPTIONS]
</para>
</refsect1>
<refsynopsisdiv>
<cmdsynopsis>
<command>pkcs15-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
@ -34,8 +36,44 @@
<title>Options</title>
<para>
<variablelist>
<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 be binded to.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--learn-card, -L</option></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>--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>Dump card objects.</para></listitem>
</varlistentry>
<varlistentry>
<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
@ -44,141 +82,164 @@
</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>
<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>
<listitem><para>Reads data object with OID, applicationName or label.
</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>--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
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-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>
<listitem><para>Dump card objects.</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>--unblock-pin, -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.
For some cards the PKCS#15 attributes of the private keys are protected for reading
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-public-keys</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>--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>,
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>
</varlistentry>
<varlistentry>
<term><option>--output</option> <varname>filename</varname>,
<option>-o</option> <varname>filename</varname></term>
<listitem><para>Specifies where key output should be written.
If <varname>filename</varname> 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>
<listitem><para>Specifies the auth id of the PIN to use for the
operation. This is useful with the --change-pin operation.</para></listitem>
<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>--aid</option> <varname>aid</varname></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>--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>--reader</option> <varname>num</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>--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></listitem>
</varlistentry>
<varlistentry>
<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>--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>--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>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>See also</title>
<para>pkcs15-init(1), pkcs15-crypt(1)</para>
<para>
<citerefentry>
<refentrytitle>pkcs15-init</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pkcs15-crypt</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

35
doc/tools/tools.xml
View File

@ -3,24 +3,29 @@
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<title>OpenSC tools</title>
<title>OpenSC</title>
<reference>
<referenceinfo>
<title>OpenSC</title>
<title>OpenSC tools</title>
</referenceinfo>
<xi:include href="eidenv.xml"/>
<xi:include href="cardos-tool.xml"/>
<xi:include href="cryptoflex-tool.xml"/>
<xi:include href="netkey-tool.xml"/>
<xi:include href="opensc-tool.xml"/>
<xi:include href="opensc-explorer.xml"/>
<xi:include href="piv-tool.xml"/>
<xi:include href="pkcs11-tool.xml"/>
<xi:include href="pkcs15-crypt.xml"/>
<xi:include href="pkcs15-tool.xml"/>
<xi:include href="pkcs15-init.xml"/>
<xi:include href="westcos-tool.xml"/>
<xi:include href="eidenv.1.xml"/>
<xi:include href="cardos-tool.1.xml"/>
<xi:include href="cryptoflex-tool.1.xml"/>
<xi:include href="netkey-tool.1.xml"/>
<xi:include href="opensc-tool.1.xml"/>
<xi:include href="opensc-explorer.1.xml"/>
<xi:include href="piv-tool.1.xml"/>
<xi:include href="pkcs11-tool.1.xml"/>
<xi:include href="pkcs15-crypt.1.xml"/>
<xi:include href="pkcs15-tool.1.xml"/>
<xi:include href="pkcs15-init.1.xml"/>
<xi:include href="westcos-tool.1.xml"/>
</reference>
<xi:include href="pkcs15-profile.xml"/>
<reference>
<referenceinfo>
<title>OpenSC file formats</title>
</referenceinfo>
<xi:include href="pkcs15-profile.5.xml"/>
</reference>
</book>

200
doc/tools/westcos-tool.1.xml Normal file
View File

@ -0,0 +1,200 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="westcos-tool">
<refmeta>
<refentrytitle>westcos-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="productname">OpenSC</refmiscinfo>
<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
<refmiscinfo class="source">opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>westcos-tool</refname>
<refpurpose>utility for manipulating data structures
on westcos smart cards</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>westcos-tool</command>
<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The <command>westcos-tool</command> utility is used to manipulate
the westcos data structures on 2 Ko smart cards / tokens. Users can create PINs,
keys and certificates stored on the card / token. User PIN authentication is
performed for those operations that require it.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<variablelist>
<varlistentry>
<term>
<option>--change-pin</option>,
<option>-n</option>
</term>
<listitem><para>Changes a PIN stored on the card.
User authentication is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--certificate</option> <replaceable>file</replaceable>,
<option>-t</option> <replaceable>file</replaceable>
</term>
<listitem><para>Write certificate file <replaceable>file</replaceable>
in PEM format to the card.
User authentication is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--finalize</option>,
<option>-f</option>
</term>
<listitem><para>Finalize the card. Once finalized the default key is
invalidated, so PIN and PUK cannot be changed anymore without user
authentication.</para>
<para>Warning, un-finalized are insecure because PIN can be changed
without user authentication (knowledge of default key
is enough).</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--generate-key</option>,
<option>-g</option>
</term>
<listitem><para>Generate a private key on the card. The card must not have
been finalized and a PIN must be installed (ie. the file for ithe PIN must
havei been created, see option <option>-i</option>).
By default the key length is 1536 bits. User authentication is required for
this operation. </para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--help</option>,
<option>-h</option>
</term>
<listitem><para>Print help message on screen.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--install-pin</option>,
<option>-i</option>
</term>
<listitem><para>Install PIN file in on the card.
You must provide a PIN value with <option>-x</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<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>--overwrite-key</option>,
<option>-o</option>
</term>
<listitem><para>Overwrite the key if there is already a key on the card.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<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> <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>--read-file</option> <replaceable>path</replaceable>,
<option>-j</option> <replaceable>path</replaceable>
</term>
<listitem><para>Read the file <replaceable>path</replaceable> from the card.
The file is written on disk with name <replaceable>path</replaceable>.
User authentication is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<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>--unblock-pin</option>,
<option>-u</option>
</term>
<listitem><para>Unblocks a PIN stored on the card. Knowledge of the
PIN Unblock Key (PUK) is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<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>
</varlistentry>
<varlistentry>
<term>
<option>--wait</option>,
<option>-w</option>
</term>
<listitem><para>Wait for a card to be inserted.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--write-file</option> <replaceable>path</replaceable>,
<option>-k</option> <replaceable>path</replaceable>
</term>
<listitem><para>Put the file with name <replaceable>path</replaceable>
from disk to card.
On the card the file is written in <replaceable>path</replaceable>.
User authentication is required for this operation.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Authors</title>
<para><command>westcos-tool</command> was written by
Francois Leblanc <email>francois.leblanc@cev-sa.com</email>.</para>
</refsect1>
</refentry>

164
doc/tools/westcos-tool.xml
View File

@ -1,164 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<refentry id="westcos-tool">
<refmeta>
<refentrytitle>westcos-tool</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>opensc</refmiscinfo>
</refmeta>
<refnamediv>
<refname>westcos-tool</refname>
<refpurpose>utility for manipulating data structures
on westcos smart cards</refpurpose>
</refnamediv>
<refsect1>
<title>Synopsis</title>
<para>
<command>westcos-tool</command> [OPTIONS]
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
The <command>westcos-tool</command> utility is used to manipulate
the westcos data structures on 2 Ko smart cards. Users can create 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>--reader, r</option> num</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>
<listitem><para>Wait for a card to be inserted</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-key, -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
this operation. </para></listitem>
</varlistentry>
<varlistentry>
<term><option>--overwrite-key, -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
</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>
<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
</term>
<listitem><para>set value of PIN.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--puk-value</option> value,
<option>-y</option> value
</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>
<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>
<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
</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>
<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
is enough).</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--read-file</option> path,
<option>-j</option> path
</term>
<listitem><para>Get the file path the file is written
on disk with path name. User authentication
is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<term>
<option>--write-file</option> path,
<option>-k</option> path
</term>
<listitem><para>Put the file with name path from disk
to card the file is written in path. User authentication
is required for this operation.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--help, -h</option></term>
<listitem><para>Print help message on screen.</para></listitem>
</varlistentry>
<varlistentry>
<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>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Authors</title>
<para><command>westcos-tool</command> was written by
Francois Leblanc <email>francois.leblanc@cev-sa.com</email>.</para>
</refsect1>
</refentry>