diff --git a/configure.ac b/configure.ac index 288e9e12..2751f0f0 100644 --- a/configure.ac +++ b/configure.ac @@ -581,6 +581,7 @@ fi AC_CONFIG_FILES([ Makefile doc/Makefile + doc/tools/Makefile etc/Makefile src/Makefile src/common/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index d982c5cd..d572f429 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/html.xsl b/doc/html.xsl index 93e75268..a9a95ee2 100644 --- a/doc/html.xsl +++ b/doc/html.xsl @@ -3,14 +3,13 @@ ]> - + - + - diff --git a/doc/man.xsl b/doc/man.xsl index 1496fb1a..892a6a81 100644 --- a/doc/man.xsl +++ b/doc/man.xsl @@ -1,4 +1,4 @@ - + diff --git a/doc/tools/Makefile.am b/doc/tools/Makefile.am new file mode 100644 index 00000000..fb514fb3 --- /dev/null +++ b/doc/tools/Makefile.am @@ -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) diff --git a/doc/tools/cardos-tool.1.xml b/doc/tools/cardos-tool.1.xml new file mode 100644 index 00000000..553934b1 --- /dev/null +++ b/doc/tools/cardos-tool.1.xml @@ -0,0 +1,85 @@ + + + + cardos-tool + 1 + OpenSC + OpenSC Tools + opensc + + + + cardos-tool + displays information about Card OS-based security tokens or format them + + + + + + cardos-tool + OPTIONS + + + + + Description + + The cardos-tool utility is used to display information about +smart cards and similar security tokens based on Siemens Card/OS M4. + + + + + Options + + + + + name, + name + Use the card driver specified by name. + The default is to auto-detect the correct card driver. + + + + , + + + Format the card or token. + + + + , + + + Display information about the card or token. + + + + number, + number + + Specify the reader number number to use. + The default is reader 0. + + + + , + + + Causes cardos-tool to be more verbose. + Specify this flag several times to enable debug output in the opensc library. + + + + , + + + Causes cardos-tool to wait for the token + to be inserted into reader. + + + + + + diff --git a/doc/tools/cardos-tool.xml b/doc/tools/cardos-tool.xml deleted file mode 100644 index ea82001b..00000000 --- a/doc/tools/cardos-tool.xml +++ /dev/null @@ -1,66 +0,0 @@ - - - - cardos-tool - 1 - opensc - - - - cardos-tool - displays information about Card OS-based security tokens or format them - - - - - Synopsis - - cardos-tool [OPTIONS] - - - - - Description - - The cardos-tool utility is used to display information about -smart cards and similar security tokens based on Siemens Card/OS M4. - - - - - Options - - - - , - Display information about the card or token. - - - , - Format the card or token. - - - number, number - Specify the reader number number to use. - The default is reader 0. - - - name, driver - Use the card driver specified by name. The default - is to auto-detect the correct card driver. - - - - Causes cardos-tool to wait for the token - to be inserted into reader. - - - - - Causes cardos-tool to be more verbose. Specify this flag several times -to enable debug output in the opensc library. - - - - - diff --git a/doc/tools/cryptoflex-tool.1.xml b/doc/tools/cryptoflex-tool.1.xml new file mode 100644 index 00000000..d54f1c15 --- /dev/null +++ b/doc/tools/cryptoflex-tool.1.xml @@ -0,0 +1,173 @@ + + + + cryptoflex-tool + 1 + OpenSC + OpenSC Tools + opensc + + + + cryptoflex-tool + utility for manipulating Schlumberger Cryptoflex data structures + + + + + cryptoflex-tool + OPTIONS + + + + + Description + + cryptoflex-tool 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. + + + + + Options + + + + + num, + num + + Specifies the DF to operate in + + + + + arg, + arg + + Creates new RSA key files for arg keys + + + + + id, + id + + Creates new PIN file for CHVid + + + + + exp, + exp + + Specifies the RSA exponent, exp, + to use in key generation. The default value is 3. + + + + + , + + + Generate a new RSA key pair + + + + + num, + num + + Specifies the key number to operate on. The default is + key number 1. + + + + + , + + + Lists all keys stored in a public key file + + + + + length, + length + + Specifies the modulus length to use + in key generation. The default value is 1024. + + + + + id, + id + + Specifies the private key file id, id, + to use + + + + + id, + id + + Specifies the public key file id, id, + to use + + + + + + + Reads a public key from the card, allowing the user to + extract and store or use the public key + + + + + + num, + num + + Forces cryptoflex-tool to use + reader number num for operations. The default + is to use reader number 0, the first reader in the system. + + + + + , + + + Causes cryptoflex-tool to be more + verbose. Specify this flag several times to enable debug output in + the opensc library. + + + + + , + + + Verifies CHV1 before issuing commands + + + + + + + + See also + + + pkcs15-tool + 1 + + + + + diff --git a/doc/tools/cryptoflex-tool.xml b/doc/tools/cryptoflex-tool.xml deleted file mode 100644 index ef09dece..00000000 --- a/doc/tools/cryptoflex-tool.xml +++ /dev/null @@ -1,134 +0,0 @@ - - - - cryptoflex-tool - 1 - opensc - - - - cryptoflex-tool - utility for manipulating Schlumberger Cryptoflex data structures - - - - Synopsis - - cryptoflex-tool [OPTIONS] - - - - - Description - - cryptoflex-tool 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. - - - - - Options - - - - - Verifies CHV1 before issuing commands - - - - - Lists all keys stored in a public key file - - - - arg, - arg - Creates new RSA key files for arg keys - - - - id, - id - Creates new PIN file for CHVid - - - - - Generate a new RSA key pair - - - - - Reads a public key from the card, allowing the user to - extract and store or use the public key - - - - - num, - num - Specifies the key number to operate on. The default is - key number 1. - - - - num, - num - Specifies the DF to operate in - - - - id, - id - Specifies the private key file id, id, - to use - - - - id, - id - Specifies the public key file id, id, - to use - - - - exp, - exp - Specifies the RSA exponent, exp, - to use in key generation. The default value is 3. - - - - length, - length - Specifies the modulus length to use - in key generation. The default value is 1024. - - - - num, - num - Forces cryptoflex-tool to use - reader number num for operations. The default - is to use reader number 0, the first reader in the system. - - - - - Causes cryptoflex-tool to be more - verbose. Specify this flag several times to enable debug output in - the opensc library. - - - - - - - - See also - pkcs15-tool(1) - - - diff --git a/doc/tools/eidenv.xml b/doc/tools/eidenv.1.xml similarity index 65% rename from doc/tools/eidenv.xml rename to doc/tools/eidenv.1.xml index 2d111711..b5f45ace 100644 --- a/doc/tools/eidenv.xml +++ b/doc/tools/eidenv.1.xml @@ -3,7 +3,9 @@ eidenv 1 - opensc + OpenSC + OpenSC Tools + opensc @@ -12,12 +14,12 @@ electronic identity cards - - Synopsis - - eidenv [OPTIONS] - - + + + eidenv + OPTIONS + + Description @@ -36,45 +38,66 @@ - num - - Use the given reader. The default is the first reader with a card. - + + prog, + prog + + Executes the given program with + data in environment variables. - - Wait for a card to be inserted - - - - + + , + + Print help message on screen. - - Prints the version - of the utility and exits. - - - - + + , + + Prints all data fields from the card, like validity period, document number etc. - + + num, + num + + + Use the given reader. The default is the first reader with a card. + + + + + + , + + Prints key usage statistics (only for Estonian ID card). - prog - Executes the given program with - data in environment variables. + + , + + + Prints the version + of the utility and exits. + + + + + , + + + Wait for a card to be inserted diff --git a/doc/tools/netkey-tool.xml b/doc/tools/netkey-tool.1.xml similarity index 66% rename from doc/tools/netkey-tool.xml rename to doc/tools/netkey-tool.1.xml index e8d3149d..a9f5ea29 100644 --- a/doc/tools/netkey-tool.xml +++ b/doc/tools/netkey-tool.1.xml @@ -3,7 +3,9 @@ netkey-tool 1 - opensc + OpenSC + OpenSC Tools + opensc @@ -11,10 +13,13 @@ administrative utility for Netkey E4 cards - - Synopsis - netkey-tool [OPTIONS] [COMMAND] - + + + netkey-tool + OPTIONS + COMMAND + + Description @@ -30,34 +35,54 @@ - , + + , + + Displays a short help message. - number, number - Use smart card in specified reader. Default is reader 0. - - - - Causes netkey-tool to be more verbose. This - options may be specified multiple times to increase verbosity. - - - pin-value, pin-value + + pin-value, + pin-value + Specifies the current value of the global PIN. - pin-value, pin-value + + pin-value, + pin-value + Specifies the current value of the global PUK. - pin-value, pin-value + + pin-value, + pin-value + Specifies the current value of the local PIN0 (aka local PIN). - pin-value, pin-value + + pin-value, + pin-value + Specifies the current value of the local PIN1 (aka local PUK). + + + number, + number + + Use smart card in specified reader. Default is reader 0. + + + + + + Causes netkey-tool to be more verbose. This + options may be specified multiple times to increase verbosity. + @@ -93,22 +118,40 @@ - { | | - } - 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, - netkey-tool will tell you which one is needed. + + cert number filename + + This command will read one of your cards certificates (as specified by + number) and save this certificate into file filename + in PEM-format. Certificates on a NetKey E4 card are readable without a pin, so you don't + have to specify one. - { | | - | } new-pin + + cert filename number + + This command will read the first PEM-encoded certificate from file + filename and store this into your smart cards certificate file + number. Some of your smart cards certificate files might be readonly, so + this will not work with all values of number. 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, netkey-tool will tell you which one is + needed. + + + + change { pin | puk | + pin0 | pin1 } new-pin + 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, netkey-tool will tell you which one is needed. - initial-pin + + nullpin initial-pin + 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. - number filename - This command will read one of your cards certificates (as specified by - ) and save this certificate into file - in PEM-format. Certificates on a NetKey E4 card are readable without a pin, so you don't - have to specify one. - - - filename number - This command will read the first PEM-encoded certificate from file - and store this into your smart cards certificate file - . Some of your smart cards certificate files might be readonly, so - this will not work with all values of . 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, netkey-tool will tell you which one is - needed. + + unblock { pin | pin0 | pin1 } + + 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, + netkey-tool will tell you which one is needed. @@ -138,7 +172,12 @@ See also - opensc-explorer(1) + + + opensc-explorer + 1 + + diff --git a/doc/tools/opensc-explorer.1.xml b/doc/tools/opensc-explorer.1.xml new file mode 100644 index 00000000..352e3b4d --- /dev/null +++ b/doc/tools/opensc-explorer.1.xml @@ -0,0 +1,348 @@ + + + + opensc-explorer + 1 + OpenSC + OpenSC Tools + opensc + + + + opensc-explorer + + generic interactive utility for accessing smart card + and similar security token functions + + + + + + opensc-explorer + OPTIONS + + + + + Description + + The opensc-explorer 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. + + + + + Options + + The following are the command-line options for + opensc-explorer. There are additional + interactive commands available once it is running. + + + + driver, + driver + + + Use the given card driver. The default is + auto-detected. + + + + + path, + path + + + Select the file referenced by the given path on + startup. The default is the path to the standard master file, + 3F00. If path is empty (e.g. opensc-explorer + --mf ""), then no file is explicitly selected. + + + + + num, + num + + + Use the given reader number. The default + is 0, the first reader in the system. + + + + + , + + + Causes opensc-explorer to be more + verbose. Specify this flag several times to enable + debug output in the opensc library. + + + + + , + + Wait for a card to be inserted + + + + + + + Commands + + The following commands are supported at the opensc-explorer + interactive prompt. + + + + apdu hex-data + + + Send a custom APDU command hex-data. + + + + + + asn1 file-id + + Parse and print the ASN.1 encoded content of the file specified by + file-id. + + + + + cat [file-id] + + + cat sfi:short-id + + Print the contents of the currently selected EF or the contents + of a file specified by file-id or the short file id + short-id. + + + + + + cd file-id + + Change to another DF specified by file-id + + + + + change CHVid [[old-pin] new-pin] + + Change a PIN, where id is the PIN reference + + Examples: + + + Change PIN: change CHV2 00:00:00:00:00:00 "foobar" + + + Set PIN: change CHV2 "foobar" + + + Change PIN with pinpad: change CHV2 + + + + + + + create file-id size + + Create a new EF. file-id specifies the + id number and size is the size of the new file. + + + + + + debug [level] + + + Set OpenSC debug level to level. + If level is omitted the current debug level will be shown. + + + + + + delete file-id + + Remove the EF or DF specified by file-id + + + + + do_get hex-tag [output] + + + Copy the internal card's 'tagged' data into the local file. + The local file is specified by output while the tag of + the card's data is specified by hex-tag. + + + If output is omitted, the name of the output file will be + derived from hex-tag. + + + + + + + do_put hex-tag input + + + Update internal card's 'tagged' data. + hex-tag is the tag of the card's data. + input is the filename of the source file or the literal data presented as + a sequence of hexadecimal values or " enclosed string. + + + + + + + erase + + Erase the card, if the card supports it. + + + + + get file-id [output] + + + Copy an EF to a local file. The local file is specified + by output while the card file is specified by file-id. + + + If output is omitted, the name of the output file will be + derived from the full card path to file-id. + + + + + + + info [file-id] + + Display attributes of a file specified by file-id. + If file-id is not supplied, + the attributes of the current file are printed. + + + + + ls + + List all files in the current DF + + + + + mkdir file-id size + + Create a DF. file-id specifies the id number + and size is the size of the new file. + + + + + put file-id input + + Copy a local file to the card. The local file is specified + by input while the card file is specified by file-id. + + + + + + quit + + Exit the program. + + + + + random count + + + Generate random sequence of count bytes. + + + + + + rm file-id + + Remove the EF or DF specified by file-id + + + + + update_binary file-id offs data + + + Binary update of the file specified by file-id with the literal data + data starting from offset specified by offs. + data can be supplied as a sequence of the hex values or + as a " enclosed string. + + + + + + update_record file-id rec-nr rec-offs data + + + Update record specified by rec-nr of the file + specified by file-id with the literal data + data starting from offset specified by + rec-offs. + data can be supplied as a sequence of the hex values or + as a " enclosed string. + + + + + + verify key-type key-id [key] + + Present a PIN or key to the card. Where key-type + can be one of CHV, KEY or PRO. key-id is a number representing the + key or PIN reference. key is the key or PIN to be verified in hex. + + + If key is omitted, PIN will be verified with PIN-Pad. + + + Example: verify CHV0 31:32:33:34:00:00:00:00 + + + + + + + + + + See also + + + opensc-tool + 1 + + + + + diff --git a/doc/tools/opensc-explorer.xml b/doc/tools/opensc-explorer.xml deleted file mode 100644 index c08b6cdd..00000000 --- a/doc/tools/opensc-explorer.xml +++ /dev/null @@ -1,297 +0,0 @@ - - - - opensc-explorer - 1 - opensc - - - - opensc-explorer - - generic interactive utility for accessing smart card - and similar security token functions - - - - - Synopsis - - opensc-explorer [OPTIONS] - - - - - Description - - The opensc-explorer 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. - - - - - Options - - The following are the command-line options for - opensc-explorer. There are additional - interactive commands available once it is running. - - - - num, - num - - - Use the given reader number. The default - is 0, the first reader in the system. - - - - - driver, - driver - - - Use the given card driver. The default is - auto-detected. - - - - - path, - path - - - Select the file referenced by the given path on - startup. The default is the path to the standard master file, - 3F00. If path is empty (e.g. opensc-explorer - --mf ""), then no file is explicitly selected. - - - - - Wait for a card to be inserted - - - - - Causes opensc-explorer to be more - verbose. Specify this flag several times to enable - debug output in the opensc library. - - - - - - - - Commands - - The following commands are supported at the opensc-explorer - interactive prompt. - - - - list all files in the current DF - - - - file-id - change to another DF specified by file-id - - - - [file-id] - sfi:sfi-id - print the contents of the currently selected EF or the contents of a file - specified by file-id - or sfi-id. - - - - - [file-id] - display attributes of a file specified by file-id. - If file-id is not supplied, - the attributes of the current file are printed. - - - - file-id size - create a new EF. file-id specifies the - id number and size is the size of the new file. - - - - - file-id - remove the EF or DF specified by file-id - - - - file-id - remove the EF or DF specified by file-id - - - - key-typekey-id - [key] - present a PIN or key to the card. Where key-type - can be one of CHV, KEY or PRO. key-id is a number representing the - key or PIN reference. key is the key or PIN to be verified in hex. - - - If key is omitted, PIN will be verified with PIN-Pad. - - - Example: verify CHV0 31:32:33:34:00:00:00:00 - - - - - - id - [[old-pin] new-pin] - change a PIN, where id is the PIN reference - - Examples: - - - Change PIN: change CHV2 00:00:00:00:00:00 "foobar" - - - Set PIN: change CHV2 "foobar" - - - Change PIN with pinpad: change CHV2 - - - - - - file-id input - copy a local file to the card. The local file is specified - by input while the card file is specified by file-id. - - - - - file-id [output] - - copy an EF to a local file. The local file is specified - by output while the card file is specified by file-id. - - - If output is ommited, the name of the output file will be - derivated from the full card path to file-id. - - - - - - hex-tag input - - update internal card's 'tagged' data. - hex-tag is the tag of the card's data. - input is the filename of the source file or the literal data presented as - a sequence of hexadecimal values or '"' enclosed string. - - - - - - hex-tag [output] - - copy the internal card's 'tagged' data into the local file. - The local file is specified by output while the tag of - the card's data is specified by hex-tag. - - - If output is ommited, the name of the output file will be - derivated from hex-tag. - - - - - - file-id size - create a DF. file-id specifies the id number - and size is the size of the new file. - - - - - erase the card, if the card supports it. - - - - count - - generate random sequence of count bytes. - - - - - file-id rec_nr - rec_offs data - - update record specified by rec_nr of the file - specified by file-id with the literal data - data starting from offset specified by - rec_offs. - data can be supplied as a sequence of the hex values or - as a '"' encolsed string. - - - - - file-id offs - data - - binary update of the file specified by file-id with the literal data - data starting from offset specified by offs. - data can be supplied as a sequence of the hex values or - as a '"' encolsed string. - - - - - [level] - - set OpenSC debug level to level. - If level is ommited the current debug level will be shown. - - - - - hex_data - - send a custom APDU command hex_data. - - - - - file-id - - parse and print the ASN1 encoded content of the file specified by - file-id. - - - - - - exit the program. - - - - - - - - See also - opensc-tool(1) - - - diff --git a/doc/tools/opensc-tool.1.xml b/doc/tools/opensc-tool.1.xml new file mode 100644 index 00000000..d4a95851 --- /dev/null +++ b/doc/tools/opensc-tool.1.xml @@ -0,0 +1,139 @@ + + + + opensc-tool + 1 + OpenSC + OpenSC Tools + opensc + + + + opensc-tool + generic smart card utility + + + + + opensc-tool + OPTIONS + + + + + Description + + The opensc-tool 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. + + + + + Options + + + + + , + + + Print the Answer To Reset (ATR) of the card. + Output is in hex byte format + + + + driver, + driver + + Use the given card driver. + The default is auto-detected. + + + + , + + + Print information about OpenSC, such as version and enabled components. + + + + , + + + List all installed card drivers. + + + + , + + + Recursively list all files stored on card. + + + + , + + + List all configured readers. + + + + , + + + Print the name of the inserted card (driver). + + + + num, + num + + Use the given reader number. + The default is 0, the first reader in the system. + + + + apdu, + apdu + + Sends an arbitrary APDU to the card in the format + AA:BB:CC:DD:EE:FF.... + + + + + + Print the card serial number (normally the ICCSN). + Output is in hex byte format + + + + , + + + Causes opensc-tool to be more verbose. + Specify this flag several times to enable debug output in the opensc library. + + + + , + + + Wait for a card to be inserted. + + + + + + + See also + + + opensc-explorer + 1 + + + + + diff --git a/doc/tools/opensc-tool.xml b/doc/tools/opensc-tool.xml deleted file mode 100644 index eda02720..00000000 --- a/doc/tools/opensc-tool.xml +++ /dev/null @@ -1,96 +0,0 @@ - - - - opensc-tool - 1 - opensc - - - - opensc-tool - generic smart card utility - - - - Synopsis - - opensc-tool [OPTIONS] - - - - - Description - - The opensc-tool 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. - - - - - Options - - - - - Print information about OpenSC, such as version and enabled components - - - - - Print the Answer To Reset (ATR) of the card, - output is in hex byte format - - - - Print the name of the inserted card (driver) - - - - Print the card serial number (normally the ICCSN), output is in hex byte -format - - - apdu, apdu - Sends an arbitrary APDU to the card in the format AA:BB:CC:DD:EE:FF... - - - - Recursively lists all files stored on card - - - - Lists all configured readers - - - - Lists all installed card drivers - - - num, num - Use the given reader number. The default is 0, the first reader -in the system. - - - driver, driver - Use the given card driver. The default is auto-detected. - - - - Wait for a card to be inserted - - - - Causes opensc-tool to be more verbose. Specify this flag several times -to enable debug output in the opensc library. - - - - - - - See also - opensc-explorer(1) - - - diff --git a/doc/tools/piv-tool.1.xml b/doc/tools/piv-tool.1.xml new file mode 100644 index 00000000..5cc99281 --- /dev/null +++ b/doc/tools/piv-tool.1.xml @@ -0,0 +1,198 @@ + + + + piv-tool + 1 + OpenSC + OpenSC Tools + opensc + + + + piv-tool + smart card utility for HSPD-12 PIV cards + + + + + piv-tool + OPTIONS + + + + + + The piv-tool 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. + + + + + Options + + + + + + + Print the card serial number derived from the CHUID object, + if any. Output is in hex byte format. + + + + , + + + Print the name of the inserted card (driver) + + + + argument, + argument + + Authenticate to the card using a 2DES or 3DES key. + The argument of the form + {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 the card vendor, and the environment variable + PIV_EXT_AUTH_KEY must point to a text file containing + the key in the format: + XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX + + + + + argument, + argument + + Generate a key pair on the card and output the public key. + The argument of th form + 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 respectively. + + + + ContainerID, + ContainerID + + Load an object on to the card. + The ContainerID is as defined in NIST 800-73-n + without leading 0x. Example: CHUID object is 3000 + + + + + + ref, + ref + + Load a certificate on to the card. + ref is 9A, + 9C, 9D or + 9E + + + + + ref, + ref + + Load a certificate that has been gziped on to the card. + ref is 9A, + 9C, 9D or + 9E + + + + + file, + file + + Output file for any operation that produces output. + + + + + + file, + file + + Input file for any operation that requires an input file. + + + + + + file + + Print properties of the key slots. Needs 'admin' authentication. + + + + + + apdu, + apdu + + Sends an arbitrary APDU to the card in the format + AA:BB:CC:DD:EE:FF.... + This option may be repeated. + + + + + num, + num + + Use the given reader number. The default is + 0, the first reader in the system. + + + + driver, + driver + + Use the given card driver. + The default is auto-detected. + + + + , + + + Wait for a card to be inserted + + + + , + + + Causes piv-tool to be more verbose. + Specify this flag several times to enable debug output in the opensc + library. + + + + + + + See also + + + opensc-tool + 1 + + + + + diff --git a/doc/tools/piv-tool.xml b/doc/tools/piv-tool.xml deleted file mode 100644 index f2d1a7b1..00000000 --- a/doc/tools/piv-tool.xml +++ /dev/null @@ -1,130 +0,0 @@ - - - - piv-tool - 1 - opensc - - - - piv-tool - smart card utility for HSPD-12 PIV cards - - - - Synopsis - - piv-tool [OPTIONS] - - - - - - The piv-tool 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. - - - - - Options - - - - - Print the derived card serial number from the CHUID object if any. - output is in hex byte format. - - - - Print the name of the inserted card (driver) - - - argument, arguement - 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 - - - - argument, argument - 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. - - - - ContainerID, ContainerID - Load an object on to the card. The ContainerID is defined - in NIST 800-73-n without leading 0x. Example: CHUID object is 3000 - - - - - ref, ref - Load a certificate on to the card. ref is 9A, 9C, 9D or 9E - - - - ref, ref - Load a certificate that has been gziped on to the card. - ref is 9A, 9C, 9D or 9E - - - - file, file - Output file for any operation that produces output. - - - - - file, file - Input file for any operation that requires an input file. - - - - - file - Print properties of the key slots. Needs 'admin' authentication. - - - - - apdu, apdu - Sends an arbitrary APDU to the card in the format AA:BB:CC:DD:EE:FF... - This option may be repeated. - - - - num - Use the given reader number. The default is 0, - the first reader in the system. - - - driver, driver - Use the given card driver. The default is auto-detected. - - - - Wait for a card to be inserted - - - - Causes piv-tool to be more verbose. - Specify this flag several times to enable debug output in the opensc library. - - - - - - - See also - opensc-tool(1) - - - diff --git a/doc/tools/pkcs11-tool.xml b/doc/tools/pkcs11-tool.1.xml similarity index 50% rename from doc/tools/pkcs11-tool.xml rename to doc/tools/pkcs11-tool.1.xml index 153ec3cb..56c8e61d 100644 --- a/doc/tools/pkcs11-tool.xml +++ b/doc/tools/pkcs11-tool.1.xml @@ -3,7 +3,9 @@ pkcs11-tool 1 - opensc + OpenSC + OpenSC Tools + opensc @@ -11,12 +13,12 @@ utility for managing and using PKCS #11 security tokens - - Synopsis - - pkcs11-tool [OPTIONS] - - + + + pkcs11-tool + OPTIONS + + Description @@ -34,16 +36,161 @@ - + + path + + Extract information from path + (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. + + + + + , + + + Change the user PIN on the token + + + + + , + + + Hash some data. + + + + + id, + id + + Specify the id of the object to operate on. + + + + + + + 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 . + + + + + + + Initialize a token: set the token label as + well as a Security Officer PIN (the label must be specified + using ). + + + + + path, + path + + Specify the path to a file for input. + + + + + , + + + Generate a new key pair (public and private pair.) + + + + + name, + name + + Specify the name of the object to operate on + (or the token label when + is used). + + + + + , + + + Display a list of mechanisms supported by the token. + + + + + , + + + Display a list of objects. + + + + + , + + + Display a list of available slots on the token. + + + + + , + + Authenticate to the token before performing other operations. This option is not needed if a PIN is provided on the command line. - pin, - pin - Use the given pin for + + mechanism, + mechanism + + Use the specified mechanism + for token operations. See for a list + of mechanisms supported by your token. + + + + + mod + + Specify a PKCS#11 module (or library) to + load. + + + + + path, + path + + Test a Mozilla-like keypair generation + and certificate request. Specify the path + to the certificate file. + + + + + path, + path + + Specify the path to a file for output. + + + + + pin, + pin + + Use the given pin 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. @@ -52,184 +199,110 @@ - pin - Use the given pin as the + + id, + id + + Set the CKA_ID of the object. + + + + + , + + + Display general token information. + + + + + , + + + Sign some data. + + + + + id + + Specify the id of the slot to use. + + + + + description + + Specify the description of the slot to use. + + + + + index + + Specify the index of the slot to use. + + + + + label + + Specify the label of token. + Will be used the first slot, that has the inserted token with this + label. + + + + + pin + + Use the given pin as the Security Officer PIN for some token operations (token initialization, user PIN initialization, etc). The same warning as also applies here. - - Initializes a token: set the token label as - well as a Security Officer PIN (the label must be specified - using ). - - - - - 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 . - - - - - Change the user PIN on the token - - - - - Performs some tests on the token. This + + , + + + Perform some tests on the token. This option is most useful when used with either or . - - Displays general token information. - - - - - Displays a list of available slots on the token. - - - - - Displays a list of mechanisms supported by the token. - - - - - Displays a list of objects. - - - - - Sign some data. - - - - - Hash some data. - - - - mechanism, - mechanism - Use the specified mechanism - for token operations. See for a list - of mechanisms supported by your token. - - - - - Generate a new key pair (public and private pair.) - - - - id, - path - Write a key or certificate object to the token. - path points to the DER-encoded certificate or key file. - - - - - type, - type + + type, + type + Specify the type of object to operate on. - Examples are cert, privkey - and pubkey. + Examples are cert, privkey + and pubkey. - id, - id - Specify the id of the object to operate on. - - - - name, - name - Specify the name of the object to operate on - (or the token label when - is used). - - - - id - Specify the id of the slot to use. - - - - description - Specify the description of the slot to use. - - - - index - Specify the index of the slot to use. - - - - label - Specify the label of token. Will be used the first slot, that has the - inserted token with this label. - - - - id, - id - Set the CKA_ID of the object. - - - - path - Extract information from path - (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. - - - - path, - path - Specify the path to a file for input. - - - - path, - path - Specify the path to a file for output. - - - - mod - Specify a PKCS#11 module (or library) to - load. - - - - path, - path - Tests a Mozilla-like keypair generation - and certificate request. Specify the path - to the certificate file. - - - - - Causes pkcs11-tool to be + + , + + Cause pkcs11-tool to be more verbose.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 OPENSC_DEBUG environment variable to a non-zero number. + + + id, + path + + Write a key or certificate object to the token. + path points to the DER-encoded certificate or key file. + + + diff --git a/doc/tools/pkcs15-crypt.xml b/doc/tools/pkcs15-crypt.1.xml similarity index 62% rename from doc/tools/pkcs15-crypt.xml rename to doc/tools/pkcs15-crypt.1.xml index e5f3d52a..d689742e 100644 --- a/doc/tools/pkcs15-crypt.xml +++ b/doc/tools/pkcs15-crypt.1.xml @@ -3,7 +3,9 @@ pkcs15-crypt 1 - opensc + OpenSC + OpenSC Tools + opensc @@ -11,12 +13,12 @@ perform crypto operations using pkcs15 smart card - - Synopsis - - pkcs15-crypt [OPTIONS] - - + + + pkcs15-crypt + OPTIONS + + Description @@ -33,41 +35,19 @@ - - Perform digital signature operation on - the data read from a file specified using the - option. By default, the contents of the file are assumed to - be the result of an MD5 hash operation. Note that pkcs15-crypt - expects the data in binary representation, not ASCII. - The digital signature is stored, in binary representation, - in the file specified by the 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 ). + + aid + + Specify the AID of the on-card PKCS#15 applicationi + to bind to. The aid must be in hexadecimal + form. - - By default, pkcs15-crypt - 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, - however, pkcs15-crypt will perform the - required padding using the algorithm outlined in the - PKCS #1 standard version 1.5. - - - - - This option tells pkcs15-crypt - 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. - - - - + + , + + Decrypt the contents of the file specified by the option. The result of the decryption operation is written to the file specified by the @@ -78,40 +58,34 @@ - id, - id - Selects the ID of the key to use. - - - - N, - N - Selects the N-th smart - card reader configured by the system. If unspecified, - pkcs15-crypt will use the first reader - found. - - - - file, - file + + file, + file + Specifies the input file to use. - file, - file + + id, + id + + Selects the ID of the key to use. + + + + + file, + file + Any output will be sent to the specified file. - - Outputs raw 8 bit data. - - - - pin, - pin + + pin, + pin + When the cryptographic operation requires a PIN to access the key, pkcs15-crypt will prompt the user for the PIN on the terminal. Using this option @@ -124,13 +98,72 @@ - aid - Specify in a hexadecimal form the AID of the on-card PKCS#15 - application to be binded to. + + + + By default, pkcs15-crypt + 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, + however, pkcs15-crypt will perform the + required padding using the algorithm outlined in the + PKCS #1 standard version 1.5. - + + , + + + Outputs raw 8 bit data. + + + + + N, + N + + Selects the N-th smart + card reader configured by the system. If unspecified, + pkcs15-crypt will use the first reader + found. + + + + + + + This option tells pkcs15-crypt + 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. + + + + + , + + + Perform digital signature operation on + the data read from a file specified using the + option. By default, the contents of the file are assumed to + be the result of an MD5 hash operation. + Note that pkcs15-crypt + expects the data in binary representation, not ASCII. + The digital signature is stored, in binary representation, + in the file specified by the 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 ). + + + + + , + + Causes pkcs15-crypt to be more verbose. Specify this flag several times to enable debug output in the OpenSC library. @@ -139,10 +172,19 @@ - + See also - pkcs15-init(1), pkcs15-tool(1) + + + pkcs15-init + 1 + , + + pkcs15-tool + 1 + + diff --git a/doc/tools/pkcs15-init.xml b/doc/tools/pkcs15-init.1.xml similarity index 75% rename from doc/tools/pkcs15-init.xml rename to doc/tools/pkcs15-init.1.xml index d27496a6..5771b64e 100644 --- a/doc/tools/pkcs15-init.xml +++ b/doc/tools/pkcs15-init.1.xml @@ -1,9 +1,19 @@ - + pkcs15-init 1 - opensc + OpenSC + OpenSC Tools + opensc + + + + pkcs15-init + 1 + OpenSC + OpenSC Tools + opensc @@ -11,6 +21,13 @@ smart card personalization utility + + + pkcs15-init + OPTIONS + + + Description @@ -29,7 +46,7 @@ pkcs15-init 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 personalization. + This process is also called personalization. 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. - For each PIN, you can specify a PUK (also called unblock PIN). + For each PIN, you can specify a PUK (also called unblock PIN). The PUK can be used to overwrite or unlock a PIN if too many incorrect values have been entered in a row. - 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 has to be used. - + Modes of operation @@ -82,7 +99,7 @@ If the card supports it, you should erase the contents of the card with - pkcs15-init --erase-card before creating the PKCS#15 structure. + pkcs15-init --erase-card before creating the PKCS#15 structure. @@ -96,7 +113,7 @@ pkcs15-init --store-pin --id " nn - where nn is a PKCS #15 ID in hexadecimal notation. Common + where nn is a PKCS #15 ID in hexadecimal notation. Common values are 01, 02, etc. @@ -119,14 +136,15 @@ pkcs15-init --generate-key " keyspec " --auth-id " nn - where describes the algorithm and length of the - key to be created, such as . This will create a 512 bit + where keyspec describes the algorithm and length of the + key to be created, such as rsa/512. 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. - is the ID of a user PIN installed previously, e.g. 01. + nn is the ID of a user PIN installed previously, + e.g. 01. In addition to storing the private portion of the key on the card, @@ -136,11 +154,11 @@ - Private Key Download + Private Key Upload - 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 - okir.pem, 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 + okir.pem, which is in PEM format, you would use pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01 @@ -153,13 +171,13 @@ Note the use of the option. The current pkcs15 profile defines two key templates, one for - authentication (key ID 45), and one for non-repudiation purposes (key ID 46). + authentication (key ID 45), and one for non-repudiation purposes (key ID 46). Other key templates will probably be added in the future. Note that if you don't specify a key ID, pkcs15-init will pick just the first key template defined by the profile. - In addition to the PEM key file format, pkcs15-init also + In addition to the PEM key file format, pkcs15-init 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 @@ - Public Key Download + Public Key Upload - 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, 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, @@ -179,16 +197,16 @@ supported public key file format is DER. - 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. - Certificate Download + Certificate Upload - You can download certificates to the card using the + You can upload certificates to the card using the option, which takes a filename as an argument. This file is supposed to contain the PEM encoded X.509 certificate. @@ -196,7 +214,7 @@ - Downloading PKCS #12 bags + Uploading PKCS #12 bags Most browsers nowadays use PKCS #12 format files when you ask them to export your key and certificate to a file. pkcs15-init @@ -209,46 +227,23 @@ 01 - This will install the private key contained in the file okir.p12, - and protect it with the PIN referenced by authentication ID 01. + This will install the private key contained in the file okir.p12, + and protect it with the PIN referenced by authentication ID 01. 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. - + Options - name, - name - - - Tells pkcs15-init to load the specified general - profile. Currently, the only application profile defined is - pkcs15, but you can write your own profiles and - specify them using this option. - - - 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, 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. - - - Profile name and options are separated by a - character, as in . - - - - - - name, - name + + name, + name + Tells pkcs15-init to load the specified card @@ -258,7 +253,10 @@ - + + , + + This tells pkcs15-init to create a PKCS #15 @@ -268,7 +266,10 @@ - + + , + + This will erase the card prior to creating the PKCS #15 structure, @@ -279,126 +280,35 @@ - keyspec, - keyspec + + keyspec, + keyspec + Tells the card to generate new key and store it on the card. - keyspec consists of an algorithm name + keyspec consists of an algorithm name (currently, the only supported name is ), 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, 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. - - - - - - filename, - filename - - - Tells pkcs15-init 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 . - It is a good idea to specify the key ID along with this command, - using the option, otherwise an intrinsic ID + using the 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. - filename - - - Tells pkcs15-init to download the specified - public key to the card and create a public key object with the - key ID specified via the . By default, - the file is assumed to contain the key in PEM format. Alternative - formats can be specified using . - - - - - - filename, - filename - - - Tells pkcs15-init to store the certificate given - in on the card, creating a certificate - object with the ID specified via the 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. - - - - - - filename, - filename - - - Tells pkcs15-init to update the certificate - object with the ID specified via the option - with the certificate in . - The file is assumed to contain a PEM encoded certificate. - - Pay extra attention when updating mail decryption certificates, as - missing certificates can render e-mail messages unreadable! - - - - - - - , - - - - Tells pkcs15-init to not ask for the transport - keys and use default keys, as known by the card driver. - - - - - - - - - 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 ps(1). Therefore, you should use these options - only on a secured system, or in an options file specified with - . - - - - - - filename + + filename + Tells pkcs15-init to read additional options - from filename. The file is supposed to + from filename. The file is supposed to contain one long option per line, without the leading dashes, for instance: @@ -413,7 +323,146 @@ - + + , + + , + , + + + + 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 ps(1). Therefore, you should use these options + only on a secured system, or in an options file specified with + . + + + + + + + name, + name + + + + Tells pkcs15-init to load the specified general + profile. Currently, the only application profile defined is + pkcs15, but you can write your own profiles and + specify them using this option. + + + 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, 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. + + + Profile name and options are separated by a + + character, as in pkcs15+onepin. + + + + + + + filename, + filename + + + + Tells pkcs15-init to store the certificate given + in on the card, creating a certificate + object with the ID specified via the 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. + + + + + + + filename + + + + Tells pkcs15-init to download the specified + public key to the card and create a public key object with the + key ID specified via the . By default, + the file is assumed to contain the key in PEM format. Alternative + formats can be specified using . + + + + + + + filename, + filename + + + + Tells pkcs15-init 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 . + It is a good idea to specify the key ID along with this command, + using the 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. + + + + + + + filename, + filename + + + + Tells pkcs15-init to update the certificate + object with the ID specified via the option + with the certificate in . + The file is assumed to contain a PEM encoded certificate. + + Pay extra attention when updating mail decryption certificates, as + missing certificates can render e-mail messages unreadable! + + + + + + + , + + + + + Tells pkcs15-init to not ask for the transport + keys and use default keys, as known by the card driver. + + + + + + + , + + Causes pkcs15-init to be more verbose. Specify this @@ -428,7 +477,12 @@ See also - pkcs15-profile(5) + + + pkcs15-profile + 5 + + diff --git a/doc/tools/pkcs15-profile.xml b/doc/tools/pkcs15-profile.5.xml similarity index 79% rename from doc/tools/pkcs15-profile.xml rename to doc/tools/pkcs15-profile.5.xml index cc687b3d..a2e28d7a 100644 --- a/doc/tools/pkcs15-profile.xml +++ b/doc/tools/pkcs15-profile.5.xml @@ -1,9 +1,11 @@ - + pkcs15-profile 5 - opensc + OpenSC + OpenSC File Formats + opensc @@ -11,13 +13,6 @@ format of profile for pkcs15-init - - Synopsis - - - - - Description @@ -48,10 +43,19 @@ this soonishly. - + See also - pkcs15-init(1), pkcs15-crypt(1) + + + pkcs15-init + 1 + , + + pkcs15-crypt + 1 + + diff --git a/doc/tools/pkcs15-tool.xml b/doc/tools/pkcs15-tool.1.xml similarity index 61% rename from doc/tools/pkcs15-tool.xml rename to doc/tools/pkcs15-tool.1.xml index 9a845c64..1a3fbd25 100644 --- a/doc/tools/pkcs15-tool.xml +++ b/doc/tools/pkcs15-tool.1.xml @@ -3,7 +3,9 @@ pkcs15-tool 1 - opensc + OpenSC + OpenSC Tools + opensc @@ -12,12 +14,12 @@ on smart cards and similar security tokens - - Synopsis - - pkcs15-tool [OPTIONS] - - + + + pkcs15-tool + OPTIONS + + Description @@ -34,8 +36,44 @@ Options + + + aid + + Specify in a hexadecimal form the AID of the on-card PKCS#15 + application to be binded to. + + - + + pin, + pin + + Specifies the auth id of the PIN to use for the + operation. This is useful with the --change-pin operation. + + + + + + + Changes a PIN or PUK stored on the token. User authentication + is required for this operation. + + + + + , + + + Dump card objects. + + + + + , + + 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 @@ - + + + List the on-card PKCS#15 applications - cert, - cert - Reads the certificate with the given id. - - - - + + , + + Lists all certificates stored on the token. - cert, - data - Reads data object with OID, applicationName or label. - - - - - - Verify PIN after card binding and before issuing any command - (without 'auth-id' the first non-SO, non-Unblock PIN will be verified) - - - - + + , + + 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 has to be used. - - Lists all PINs stored on the token. General information - about each PIN is listed (eg. PIN name). Actual PIN values are not shown. - - - - - Dump card objects. - - - - - Changes a PIN or PUK stored on the token. User authentication - is required for this operation. - - - - - Unblocks a PIN stored on the token. Knowledge of the - Pin Unblock Key (PUK) is required for this operation. - - - - + + , + + 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 has to be used. - + + + + Lists all PINs stored on the token. General information + about each PIN is listed (eg. PIN name). Actual PIN values are not shown. + + + + + + Lists all public keys stored on the token, including key name, id, algorithm and length information. - id - Reads the public key with id id, - allowing the user to extract and store or use the public key. - - - - id - Reads the public key with id id, - writing the output in format suitable for $HOME/.ssh/authorized_keys. - - - - filename, - filename - Specifies where key output should be written. - If filename already exists, it will be overwritten. - If this option is not given, keys will be printed to standard output. - - - - + + + Disables token data caching. - pin, - pin - Specifies the auth id of the PIN to use for the - operation. This is useful with the --change-pin operation. + + filename, + filename + + Specifies where key output should be written. + If filename already exists, it will be overwritten. + If this option is not given, keys will be printed to standard output. - - aid - Specify in a hexadecimal form the AID of the on-card PKCS#15 - application to be binded to. - + + + cert, + cert + + Reads the certificate with the given id. + - num + + cert, + data + + Reads data object with OID, applicationName or label. + + + + + + id + + Reads the public key with id id, + allowing the user to extract and store or use the public key. + + + + + id + + Reads the public key with id id, + writing the output in format suitable for + $HOME/.ssh/authorized_keys. + + + + + num + Forces pkcs15-tool to use reader - number num for operations. The default is to use + number num for operations. The default is to use reader number 0, the first reader in the system. - + + , + + + Unblocks a PIN stored on the token. Knowledge of the + Pin Unblock Key (PUK) is required for this operation. + + + + + , + + Causes pkcs15-tool to be more verbose. Specify this flag several times to enable debug output in the OpenSC library. + + + + + Verify PIN after card binding and before issuing any command + (without 'auth-id' the first non-SO, non-Unblock PIN will be verified) + + - + See also - pkcs15-init(1), pkcs15-crypt(1) + + + pkcs15-init + 1 + , + + pkcs15-crypt + 1 + + diff --git a/doc/tools/tools.xml b/doc/tools/tools.xml index b054ef00..2827a68c 100644 --- a/doc/tools/tools.xml +++ b/doc/tools/tools.xml @@ -3,24 +3,29 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - OpenSC tools + OpenSC - OpenSC + OpenSC tools - - - - - - - - - - - - + + + + + + + + + + + + + - + + + OpenSC file formats + + diff --git a/doc/tools/westcos-tool.1.xml b/doc/tools/westcos-tool.1.xml new file mode 100644 index 00000000..e330e859 --- /dev/null +++ b/doc/tools/westcos-tool.1.xml @@ -0,0 +1,200 @@ + + + + westcos-tool + 1 + OpenSC + OpenSC Tools + opensc + + + + westcos-tool + utility for manipulating data structures + on westcos smart cards + + + + + westcos-tool + OPTIONS + + + + + Description + + The westcos-tool 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. + + + + + Options + + + + + , + + + Changes a PIN stored on the card. + User authentication is required for this operation. + + + + + file, + file + + Write certificate file file + in PEM format to the card. + User authentication is required for this operation. + + + + + , + + + Finalize the card. Once finalized the default key is + invalidated, so PIN and PUK cannot 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). + + + + + , + + + 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 ). + By default the key length is 1536 bits. User authentication is required for + this operation. + + + + + , + + + Print help message on screen. + + + + + , + + + Install PIN file in on the card. + You must provide a PIN value with . + + + + + length, + length + + Change the length of private key. + Use with . + + + + + , + + + Overwrite the key if there is already a key on the card. + + + + + value, + value + + Set value of PIN. + + + + + value, + value + + set value of PUK (or value of new PIN for change PIN + command see ). + + + + + path, + path + + Read the file path from the card. + The file is written on disk with name path. + User authentication is required for this operation. + + + + + num, + num + + + Use the given reader. The default is the first reader with a card. + + + + + + , + + + Unblocks a PIN stored on the card. Knowledge of the + PIN Unblock Key (PUK) is required for this operation. + + + + + + + Causes westcos-tool to be more + verbose. Specify this flag several times to enable debug output + in the OpenSC library. + + + + + , + + + Wait for a card to be inserted. + + + + + path, + path + + Put the file with name path + from disk to card. + On the card the file is written in path. + User authentication is required for this operation. + + + + + + + + Authors + westcos-tool was written by + Francois Leblanc francois.leblanc@cev-sa.com. + + + diff --git a/doc/tools/westcos-tool.xml b/doc/tools/westcos-tool.xml deleted file mode 100644 index 762b59a5..00000000 --- a/doc/tools/westcos-tool.xml +++ /dev/null @@ -1,164 +0,0 @@ - - - - westcos-tool - 1 - opensc - - - - westcos-tool - utility for manipulating data structures - on westcos smart cards - - - - Synopsis - - westcos-tool [OPTIONS] - - - - - Description - - The westcos-tool 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. - - - - - Options - - - - num - - Use the given reader. The default is the first reader with a card. - - - - - - Wait for a card to be inserted - - - - - 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. - - - - - Overwrite the key if there is already a key on card. - - - - - length, - length - - Change the length of private key, use with . - - - - - - Install PIN file in token, you must provide PIN value - with . - - - - - value, - value - - set value of PIN. - - - - - value, - value - - set value of PUK (or value of new PIN for change PIN - command see ). - - - - - Changes a PIN stored on the token. User authentication - is required for this operation. - - - - - Unblocks a PIN stored on the token. Knowledge of the - PIN Unblock Key (PUK) is required for this operation. - - - - - file, - file - - Write certificate file in PEM format to the - card. User authentication is required for this operation. - - - - - 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). - - - - - path, - path - - Get the file path the file is written - on disk with path name. User authentication - is required for this operation. - - - - - path, - path - - Put the file with name path from disk - to card the file is written in path. User authentication - is required for this operation. - - - - - Print help message on screen. - - - - - Causes westcos-tool to be more - verbose. Specify this flag several times to enable debug output - in the OpenSC library. - - - - - - - - Authors - westcos-tool was written by - Francois Leblanc francois.leblanc@cev-sa.com. - - -