diff --git a/doc/src/tools/cardos-info.xml b/doc/src/tools/cardos-info.xml
new file mode 100644
index 00000000..9ddd492e
--- /dev/null
+++ b/doc/src/tools/cardos-info.xml
@@ -0,0 +1,64 @@
+
+
+
+ cardos-info
+ 1
+ opensc
+
+
+
+ cardos-info
+ displays information about Card OS-based security tokens
+
+
+
+
+ Synopsis
+
+ cardos-info [OPTIONS]
+
+
+
+
+ Description
+
+ The cardos-info utility is used to display information about
+smart cards and similar security tokens based on Siemens Card/OS M4.
+
+
+
+
+ Options
+
+
+
+ number, number
+ Display information about the token in reader number number.
+ 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-info to wait for the token
+ to be inserted into reader.
+
+
+
+
+ Causes cardos-info to be more verbose. Specify this flag several times
+to enable debug output in the opensc library.
+
+
+
+
+
+
+ See also
+ opensc(7)
+
+
+
diff --git a/doc/src/tools/cryptoflex-tool.xml b/doc/src/tools/cryptoflex-tool.xml
new file mode 100644
index 00000000..dbbba4ae
--- /dev/null
+++ b/doc/src/tools/cryptoflex-tool.xml
@@ -0,0 +1,134 @@
+
+
+
+ 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
+ opensc(7), pkcs15-tool(1)
+
+
+
diff --git a/doc/src/tools/opensc-config.xml b/doc/src/tools/opensc-config.xml
new file mode 100644
index 00000000..b08001a3
--- /dev/null
+++ b/doc/src/tools/opensc-config.xml
@@ -0,0 +1,77 @@
+
+
+
+ opensc-config
+ 1
+ opensc
+
+
+
+ opensc-config
+ a tool to get information about the installed version of OpenSC
+
+
+
+ Synopsis
+
+ opensc-config [OPTIONS]
+
+
+
+
+ Description
+
+ opensc-config is a tool that is used to get various information
+ about the installed version of OpenSC. It is particularly useful in determining
+ compiler and linker flags necessary to build programs with the OpenSC libraries.
+
+
+
+
+ Options
+
+ opensc-config accepts the following options:
+
+
+
+ Print the installed version of OpenSC to standard output.
+
+
+
+
+ Print the linker flags that are needed to compile a program
+ to use the OpenSC libraries.
+
+
+
+
+ Print the compiler flags that are needed to compile a program
+ to use the OpenSC libraries.
+
+
+
+
+ If specified, use PREFIX instead of the installation
+ prefix that OpenSC was built with when computing the output for the
+ --cflags and --libs options. This option is also used for the exec
+ prefix if --exec-prefix was not specified. This option must be specified
+ before any --libs or --cflags options.
+
+
+
+
+ If specified, use PREFIX instead of the installation
+ exec prefix that OpenSC was built with when computing the output for
+ the --cflags and --libs options. This option must be specified before any
+ --libs or --cflags options.
+
+
+
+
+
+
+ See also
+ opensc(7)
+
+
+
diff --git a/doc/src/tools/opensc-explorer.xml b/doc/src/tools/opensc-explorer.xml
new file mode 100644
index 00000000..896cd1ff
--- /dev/null
+++ b/doc/src/tools/opensc-explorer.xml
@@ -0,0 +1,191 @@
+
+
+
+ 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.
+
+
+
+
+
+ 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
+
+
+
+
+ print the contents of the currently selected EF
+
+
+
+ [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-idsize
+ 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
+
+
+
+ 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 number. key is the key or PIN to be verified in hex.
+
+
+ Example: verify CHV0 31:32:33:34:00:00:00:00
+
+
+
+
+
+ id [old-pin] new-pin
+ change a PIN
+
+ Example: change CHV0 31:32:33:34:00:00:00:00 'secret'
+
+
+
+
+
+ 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.
+
+
+
+
+ file-idsize
+ create a DF. file-id specifies the id number
+ and size is the size of the new file.
+
+
+
+
+ create a public key signature. NOTE: This command is currently not implemented.
+
+
+
+
+
+ perform a public key decryption. NOTE: This command is currently not implemented.
+
+
+
+
+
+ erase the card, if the card supports it.
+
+
+
+ [level]
+ get or set the debug level
+
+
+
+
+ exit the program
+
+
+
+
+
+
+
+ See also
+ opensc(7), opensc-tool(1)
+
+
+
diff --git a/doc/src/tools/opensc-tool.xml b/doc/src/tools/opensc-tool.xml
new file mode 100644
index 00000000..315a4554
--- /dev/null
+++ b/doc/src/tools/opensc-tool.xml
@@ -0,0 +1,87 @@
+
+
+
+ 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 the Answer To Reset (ATR) of the card,
+ output is in hex byte format
+
+
+
+ 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
+
+
+
+ Lists all installed reader 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.
+
+
+
+ Causes opensc-tool to be more verbose. Specify this flag several times
+to enable debug output in the opensc library.
+
+
+
+
+
+
+ See also
+ opensc(7), opensc-explorer(1)
+
+
+
diff --git a/doc/src/tools/pkcs11-tool.xml b/doc/src/tools/pkcs11-tool.xml
new file mode 100644
index 00000000..b47e3f61
--- /dev/null
+++ b/doc/src/tools/pkcs11-tool.xml
@@ -0,0 +1,223 @@
+
+
+
+ pkcs11-tool
+ 1
+ opensc
+
+
+
+ pkcs11-tool
+ utility for managing and using PKCS #11 security tokens
+
+
+
+ Synopsis
+
+ pkcs11-tool [OPTIONS]
+
+
+
+
+ Description
+
+ The pkcs11-tool utility is used to manage the
+ data objects on smart cards and similar PKCS #11 security tokens.
+ Users can list and read PINs, keys and certificates stored on the
+ token. User PIN authentication is performed for those operations
+ that require it.
+
+
+
+
+ Options
+
+
+
+
+ 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
+ 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.
+
+
+
+ pin
+ Use the given pin as the
+ Security Officer PIN for some token operations (token
+ initialization, user PIN initialization, etc). The same
+ warning as --pin also applies here.
+
+
+
+
+ Initializes a token: set the token label as
+ well as a Security Officer PIN (the label must be specified
+ using --label).
+
+
+
+
+ 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-pin.
+
+
+
+
+ Change the user PIN on the token
+
+
+
+
+ Performs some tests on the token. This
+ option is most useful when used with either --login or
+ --pin.
+
+
+
+
+ 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 -M for a list of mechanisms supported
+ by your token.
+
+
+
+
+ Generate a new key pair (public and private pair.)
+
+
+
+ id,
+ id
+ Write a key or certificate object to the token.
+
+
+
+ type,
+ type
+ Specify the type of object to operate on.
+ 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 --init-token is used).
+
+
+
+ id
+ Specify the id of the slot to use.
+
+
+
+ name
+ Specify the name of the slot to use.
+
+
+
+ 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 module 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
+ more verbose. Specify this flag several times to enable debug
+ output in the OpenSC library.
+
+
+
+
+
+
+
+ See also
+ opensc(7)
+
+
+
diff --git a/doc/src/tools/pkcs15-crypt.xml b/doc/src/tools/pkcs15-crypt.xml
new file mode 100644
index 00000000..6025871d
--- /dev/null
+++ b/doc/src/tools/pkcs15-crypt.xml
@@ -0,0 +1,141 @@
+
+
+
+ pkcs15-crypt
+ 1
+ opensc
+
+
+
+ pkcs15-crypt
+ perform crypto operations using pkcs15 smart card
+
+
+
+ Synopsis
+
+ pkcs15-crypt [OPTIONS]
+
+
+
+
+ Description
+
+ The pkcs15-crypt utility can be used from the
+ command line to perform cryptographic operations such as computing
+ digital signatures or decrypting data, using keys stored on a PKCS
+ #15 compliant smart card.
+
+
+
+
+ Options
+
+
+
+
+ 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 ).
+
+
+
+
+ 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
+ option. If this option is not given,
+ the decrypted data is printed to standard output, displaying
+ non-printable characters using their hex notation xNN (see also
+ ).
+
+
+
+ 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
+ Specifies the input file to use.
+
+
+
+ file,
+ file
+ Any output will be sent to the specified file.
+
+
+
+
+ Outputs raw 8 bit data.
+
+
+
+ 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
+ allows you to specify the PIN on the command line.
+ Note that on most operating systems, the command line of
+ a process can be displayed by any user using the ps(1)
+ command. It is therefore a security risk to specify
+ secret information such as PINs on the command line.
+
+
+
+
+ Causes pkcs15-crypt to be more
+ verbose. Specify this flag several times to enable debug output
+ in the OpenSC library.
+
+
+
+
+
+
+
+ See also
+ pkcs15-init(1), pkcs15-tool(1)
+
+
+
diff --git a/doc/src/tools/pkcs15-init.xml b/doc/src/tools/pkcs15-init.xml
new file mode 100644
index 00000000..9be31a7f
--- /dev/null
+++ b/doc/src/tools/pkcs15-init.xml
@@ -0,0 +1,407 @@
+
+
+
+ pkcs15-init
+ 1
+ opensc
+
+
+
+ pkcs15-init
+ smart card personalization utility
+
+
+
+ Description
+
+ The pkcs15-init utility can be used to create a PKCS #15
+ structure on a smart card, and add key or certificate objects. Details of the
+ structure that will be created are controlled via profiles.
+
+
+ The profile used by default is pkcs15. Alternative
+ profiles can be specified via the switch.
+
+
+
+
+ PIN Usage
+
+ 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.
+
+
+ An OpenSC card can have one security officer PIN, and zero or more user PINs.
+ PIN stands for Personal Identification Number, and is a secret code you need
+ to present to the card before being allowed to perform certain operations,
+ such as using one of the stored RSA keys to sign a document, or modifying
+ the card itself.
+
+
+ Usually, PINs are a sequence of decimal digits, but some cards will accept
+ arbitrary ASCII characters. Be aware however that using characters other
+ than digits will make the card unusable with PIN pad readers, because those
+ usually have keys for entering digits only.
+
+
+ The security officer (SO) PIN is special; it is used to protect meta data
+ information on the card, such as the PKCS #15 structure itself. Setting
+ the SO PIN is optional, because the worst that can usually happen is that
+ someone finding your card can mess it up. To extract any of your secret
+ keys stored on the card, an attacker will still need your user PIN, at
+ least for the default OpenSC profiles. However, it is possible to create
+ card profiles that will allow the security officer to override user PINs.
+
+
+ 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.
+
+
+
+
+ Modes of operation
+
+ Initialization
+ This is the first step during card personalization, and will create the
+ basic files on the card. To create the initial PKCS #15 structure, invoke the
+ utility as
+
+
+ pkcs15-init --create-pkcs15
+
+ You will then be asked for several the security officer PIN and PUK. Simply
+ pressing return at the SO PIN prompt will skip installation of an SO PIN.
+
+
+ If the card supports it, you can also request that the card is erased prior
+ to creating the PKCS #15 structure, by specifying the
+ option.
+
+
+
+
+ User PIN Installation
+
+ Before installing any user objects such as private keys, you need at least one
+ PIN to protect these objects. you can do this using
+
+
+ pkcs15-init --store-pin --id " nn
+
+
+ where nn is a PKCS #15 ID in hexadecimal notation. Common
+ values are 01, 02, etc.
+
+
+ Entering the command above will ask you for the user's PIN and PUK. If you do
+ not wish to install an unblock PIN, simply press return at the PUK prompt.
+
+
+ To set a label for this PIN object (which can be used by applications to display
+ a meaningful prompt to the user), use the command line option.
+
+
+
+
+ Key generation
+
+ pkcs15-init lets you generate a new key and store it on the card.
+ You can do this using:
+
+
+ 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
+ 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.
+
+
+ In addition to storing the private portion of the key on the card,
+ pkcs15-init will also store the the public portion of the
+ key as a PKCS #15 public key object.
+
+
+ By default, pkcs15-init will try to use the card's
+ on-board key generation facilities, if available. If the card does not
+ support on-board key generation, pkcs15-init will fall
+ back to software key generation.
+
+
+
+
+ Private Key Download
+
+ 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
+
+
+ pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01
+
+
+ If the key is protected by a pass phrase, pkcs15-init
+ will prompt you for a pass phrase to unlock the key.
+
+
+ In addition to storing the private portion of the key on the card,
+ pkcs15-init will also store the the public portion of the
+ key as a PKCS #15 public key object.
+
+
+ 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).
+ 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
+ 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
+ to the private key. If that is the case, pkcs15-init will
+ store the certificate instead of the public key portion.
+
+
+
+
+ Public Key Download
+
+ You can also download 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,
+ pkcs15-init will assume PEM format. The only other
+ 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
+ probably use this option only very rarely.
+
+
+
+
+ Certificate Download
+
+ You can download certificates to the card using the
+ option, which takes a filename as
+ an argument. This file is supposed to contain the DER encoded X.509
+ certificate.
+
+
+
+
+ Downloading 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
+ is capable of parsing these files, and storing their contents on the
+ card in a single operation. This works just like storing a private key,
+ except that you need to specify the file format:
+
+
+ pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-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
+
+
+ Tells pkcs15-init to load the specified card
+ profile option. You will rarely need this option.
+
+
+
+
+
+
+
+
+ This tells pkcs15-init to create a PKCS #15
+ structure on the card, and initialize any PINs.
+
+
+
+
+
+
+
+
+ This will erase the card prior to creating the PKCS #15 structure,
+ if the card supports it. If the card does not support erasing,
+ pkcs15-init will fail.
+
+
+
+
+
+ keyspec,
+ keyspec
+
+
+ Tells the card to generate new key and store it on the card.
+ 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.
+
+
+
+
+
+ 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.
+
+
+
+
+
+ filename,
+ 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.
+ The file is assumed to contain the DER encoded certificate.
+
+
+
+
+
+
+
+
+ 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
+ .
+
+
+
+
+
+
+
+
+ When downloading a private key, this option can be used to specify
+ the pass phrase to unlock the private key. The same caveat applies
+ here as in the case of the options.
+
+
+
+
+
+ filename
+
+
+ Tells pkcs15-init to read additional options
+ from filename. The file is supposed to
+ contain one long option per line, without the leading dashes,
+ for instance:
+
+ pin frank
+ puk zappa
+
+
+
+ You can specify several times.
+
+
+
+
+
+
+
+
+ Causes pkcs15-init to be more verbose. Specify this
+ flag several times to enable debug output in the OpenSC library.
+
+
+
+
+
+
+
+
+
+ See also
+ pkcs15-profile(5)
+
+
+
diff --git a/doc/src/tools/pkcs15-profile.xml.in b/doc/src/tools/pkcs15-profile.xml.in
new file mode 100644
index 00000000..ccfd5ea6
--- /dev/null
+++ b/doc/src/tools/pkcs15-profile.xml.in
@@ -0,0 +1,60 @@
+
+
+
+ pkcs15-profile
+ 5
+ opensc
+
+
+
+ pkcs15-profile
+ format of profile for pkcs15-init
+
+
+
+ Synopsis
+
+
+
+
+
+
+ Description
+
+ The pkcs15-init utility for PKCS #15 smart card
+ personalization is controlled via profiles. When starting, it will read two
+ such profiles at the moment, a generic application profile, and a card
+ specific profile. The generic profile must be specified on the command line,
+ while the card-specific file is selected based on the type of card detected.
+
+
+ The generic application profile defines general information about the card
+ layout, such as the path of the application DF, various PKCS #15 files within
+ that directory, and the access conditions on these files. It also defines
+ general information about PIN, key and certificate objects. Currently, there
+ is only one such generic profile, pkcs15.profile.
+
+
+ The card specific profile contains additional information required during
+ card intialization, such as location of PIN files, key references etc.
+ Profiles currently reside in @pkgdata@
+
+
+
+
+ Syntax
+
+ This section should contain information about the profile syntax. Will add
+ this soonishly.
+
+
+
+
+ See also
+
+ pkcs15(7), pkcs15-init(1),
+ pkcs15-crypt(1), opensc(7),
+
+
+
+
diff --git a/doc/src/tools/pkcs15-tool.xml b/doc/src/tools/pkcs15-tool.xml
new file mode 100644
index 00000000..7d154950
--- /dev/null
+++ b/doc/src/tools/pkcs15-tool.xml
@@ -0,0 +1,131 @@
+
+
+
+ pkcs15-tool
+ 1
+ opensc
+
+
+
+ pkcs15-tool
+ utility for manipulating PKCS #15 data structures
+ on smart cards and similar security tokens
+
+
+
+ Synopsis
+
+ pkcs15-tool [OPTIONS]
+
+
+
+
+ Description
+
+ The pkcs15-tool utility is used to manipulate
+ the PKCS #15 data structures on smart cards and similar security
+ tokens. Users can list and read PINs, keys and certificates stored
+ on the token. User PIN authentication is performed for those
+ operations that require it.
+
+
+
+
+ Options
+
+
+
+
+ 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
+ generated and stored on the token), the cache should be updated or
+ operations may show stale results.
+
+
+
+ cert,
+ cert
+ Reads the certificate with the given id.
+
+
+
+
+ Lists all certificates stored on the token.
+
+
+
+
+ Lists all PINs stored on the token. General information
+ about each PIN is listed (eg. PIN name). Actual PIN values are not shown.
+
+
+
+
+ Changes a PIN stored on the token. User authentication
+ 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.
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ num
+ Forces pkcs15-tool to use reader
+ number num for operations. The default is to use
+ reader number 0, the first reader in the system.
+
+
+
+
+ Causes pkcs15-tool to be more
+ verbose. Specify this flag several times to enable debug output
+ in the OpenSC library.
+
+
+
+
+
+
+
+ See also
+ opensc(7), pkcs15-init(1), pkcs15-crypt(1)
+
+
+
diff --git a/doc/src/tools/tools.xml b/doc/src/tools/tools.xml
new file mode 100644
index 00000000..1e8c7bc8
--- /dev/null
+++ b/doc/src/tools/tools.xml
@@ -0,0 +1,26 @@
+
+
+
+
+ OpenSC tools
+
+
+ OpenSC
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+