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

- added a bunch of manpages 

git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@310 c6295689-39f2-0310-b995-f0e70906c6a9
This commit is contained in:
okir 2002-03-13 13:09:15 +00:00
parent c418eb91af
commit 47b1df15af
4 changed files with 385 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/pkcs15-crypt.1 Normal file
View File

@ -0,0 +1,88 @@
.PU
.ds nm \fBpkcs15-crypt\fR
.TH pkcs15-crypt 1 "" "" OpenSC
.SH NAME
pkcs15-crypt \- perform crypto operations using pkcs15 smart card
.SH SYNOPSIS
\*(nm
.RI [ " OPTIONS " ]
.SH DESCRIPTION
The \*(nm 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.
.SH OPTIONS
.TP
.BR \-\-sign ", " \-s
Perform digital signature operation on the data read from a
file specified using the
.B \-\-input
option. By default, the contents of the file are assumed to
be the result of an MD5 hash operation. Note that \*(nm
expects the data in binary representation, not ASCII.
.IP
The digitial signature is stored, in binary representation,
in the file specified by the
.B \-\-output
option. If this option is not given, the signature
is printed on standard output, displaying non-printable
characters using their hex notation
.BR \e\exNN .
.TP
.B \-\-pkcs1
By default, \*(nm 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
.B \-\-pkcs1
option, however, \*(nm will perform the required padding
using the algorithm outlined in the PCKS#1 v1.5 standard.
.TP
.B \-\-sha1
This option tells \(*nm 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.
.TP
.BR \-\-decipher ", "\-c
Decrypt the contents of the file specified by the
.B \-\-input
option. The result of the decryption operation is written to
the file specified by the
.B \-\-output
option. If this option is not given, the decrypted data is
printed to standard output, displaying non-printable
.TP
.BR \-\-key " id, " \-k " id"
Selects the ID of the key to use.
.TP
.BR \-\-reader " N, " \-r " N"
Selects the N-th smart card reader configured by the system.
If unspecified, \*(nm will use the first reader found.
.TP
.BR \-\-input " file, " \-i " file"
Specifies the input file to use.
.TP
.BR \-\-output " file, " \-o " file"
Any output will be sent to the specified file.
.TP
.BR \-\-pin " pincode, " \-p " pincode"
When the cryptographic operation requires a PIN to access
the key, \*(nm will prompt the user for the PIN on the terminal.
Using this option allows you to specify the PIN on the command
line.
.IP
Note that on most operating systems, the command line of
a process can be displayed by any user using the
.BR ps (1)
command. It is therefore a security risk to specify
secret information such as PINs on the command line.
.TP
.BR \-\-quiet ", " \-q
Operate quietly.
.TP
.BR \-\-debug ", " \-d
Print debugging information. By specifying this option
several times, you can increase the verbosity level.
.SH AUTHORS
\*(nm was written by Juha Yrjölä <juha.yrjola@iki.fi>.
This manpage was contributed by Olaf Kirch <okir@lst.de>.

201
docs/pkcs15-init.1 Normal file
View File

@ -0,0 +1,201 @@
.PU
.ds nm \fBpkcs15-init\fR
.TH pkcs15-init 1 "" "" OpenSC
pkcs15-init \- smart card personalization utility
.SH DESCRIPTION
The \*(nm(1) 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. When invoking \*(nm,
the user must specify the application profile using the
.B \-p
switch. Currently, there is only one supported profile,
which is
.BR pkcs15 .
.SH MODES OF OPERATION
.SS Initialization
This is the first step during card personalization, and
will create the basic files on the card, and initialize
user PINs. To create the initial PKCS #15 structure,
invoke the utility as
.PP
.B " pkcs15-init --create-pkcs15 --profile pkcs15
.PP
You will then be asked for several PINs (secret codes used to protect
e.g. keys stored on the card), and PUKs. PUKs are secret codes that can
be used to
.I unblock
a PIN if too many incorrect values have been entered in a row.
.PP
If the card supports it, you can also request that the card is erased
prior to creating the PKCS #15 structure, by specifying the
.B --erase-card
option.
.SS Key Generation
\*(nm lets you generate a new key and store it on the card.
You can do this using:
.PP
.BI " pkcs15-init --generate-key " keyspec
.PP
where
.I keyspec
describes the algorithm and length of the key to be created,
such as
.BR 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.
.PP
In addition to storing the private portion of the key on the
card, \*(nm will also store the the public portion of the key
as a PKCS #15 public key object.
.PP
On-board key generation is not supported at the moment.
.SS 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
.B okir.pem ,
which is in PEM format, you would use
.PP
.B " pkcs15-init --store-private-key okir.pem --id 45
.PP
If the key is protected by a pass phrase, \*(nm will prompt
you for a pass phrase to unlock the key.
.PP
In addition to storing the private portion of the key on the
card, \*(nm will also store the the public portion of the key
as a PKCS #15 public key object.
.PP
Note the use of the
.B --id
option. The current
.B 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 you don't
specify a key ID, \*(nm will pick just the first key template
defined by the profile.
.PP
In addition to the PEM key file format, \*(nm 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. Since PKCS #12 files usually contains the X.509 certificate
corresponding to the private key, \*(nm will store the certificate
instead of the public key portion.
.SS Public Key Download
You can also download individual public keys to the card using
the
.B \-\-store-public-key
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
.B \-\-format
option, \*(nm will assume PEM format.
The only other supported public key file format is DER.
.PP
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.
.SS Certificate Download
You can download certificates to the card using the
.B \-\-store-certificate
option, which takes a filename as an argument. This file is supposed
to contain the DER encoded X.509 certificate.
.SH OPTIONS
.TP
.BR \-\-profile " \fIname\fP, " \-p " \fIname\fP"
Tells \*(nm to load the specified profile. Currently, the
only application profile defined is
.BR pkcs15 ,
but you can write your own profiles and specify them using this
option.
.TP
.BR \-\-create-pkcs15 ", " \-C
This tells \*(nm to create a PKCS #15 structure on the card, and
initialize any PINs.
.TP
.BR \-\-erase-card ", " \-E
This will erase the card prior to creating the PKCS #15 structure,
if the card supports it. If the card does not support erasing,
\*(nm will fail.
.TP
.BR \-\-generate-key " \fIkeyspec\fP, " \-G " \fIkeyspec\fP
Tells the card to generate new key and store it on the card.
.I keyspec
consists of an algorithm name (currently, the only supported
name is
.BR RSA ),
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
.BR \-\-id " option.
.TP
.BR \-\-store-private-key " \fIfilename\fP, " -S " \fIfilename\fP"
Tells \*(nm 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
.BR \-\-format .
It is a good idea to specify the key ID along with this
command, using the
.BR \-\-id " option.
.TP
.BR \-\-store-public-key " \fIfilename\fP, " -P " \fIfilename\fP"
Tells \*(nm to download the specified public key to the card
and create a public key object with the key ID specified via the
.BR \-\-id " option.
By default, the file is assumed to contain the key in PEM format.
Alternative formats can be specified using
.BR \-\-format .
.TP
.BR \-\-store-certificate " \fIfilename\fX, " -P " \fIfilename\fP"
Tells \*(nm to store the certificate given in
.I filename
on the card, creating a certificate object with the ID specified
via the
.BR \-\-id " option. The file is assumed to contain the
DER encoded certificate.
.TP
.BR \-\-pin1 ", " \-\-pin1 ", " \-\-puk2 ", " \-\-puk2
These options can be used to specify PIN 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
.BR ps (1).
Therefore, you should use these options only on a secured
system, or in an options file specified with
.BR \-\-options-file .
.TP
.BR \-\-passphrase
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
.B \-\-pin
options.
.TP
.BI \-\-options-file " filename"
Tells \*(nm to read additional options from
.IR filename .
The file is supposed to contain one long option per line, without
the leading dashes, for instance:
.IP
.nf
pin1 frank
pin2 zappa
.fi
.PP
You can specify
.B \-\-options-file
several times.
.TP
.BR \-\-debug ", " \-d
Turns on debugging output. Specifying this option more than once
increases the verbosity of the output.
.SH SEE ALSO
.BR pkcs15-profile (5) .
.SH AUTHORS
\*(nm was written by Olaf Kirch <okir@lst.de>

36
docs/pkcs15-profile.5 Normal file
View File

@ -0,0 +1,36 @@
.PU
.ds nm \fBpkcs15-init\fP
.TH pkcs15-profile 5 "" "" OpenSC
pkcs15-profile \- format of profiles for \*(nm
.SH DESCRIPTION
The \*(nm(1) 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.
.PP
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,
.IR pkcs15.profile .
.PP
The card specific profile contains additional information
required during card intialization, such as location of
PIN files, key references etc.
.PP
Profiles currently reside in
.\" XXX FIXME this should really be set to $(pkgdatadir)
.B /usr/share/opensc .
.SH SYNTAX
This section should contain information about the profile
syntax. Will add this soonishly.
.SH SEE ALSO
.BR pkcs15-init (1) ,
.BR pkcs15-crypt (1) ,
.BR opensc (3) .
.SH AUTHORS
\*(nm was written by Olaf Kirch <okir@lst.de>.

60
docs/pkcs15.7 Normal file
View File

@ -0,0 +1,60 @@
.PU
.TH pkcs15 7 "" "" OpenSC
pkcs15 \- standard for storing information on smart cards
.SH DESCRIPTION
The PKCS #15 standard is available from
.BR http://www.rsasecurity.com/rsalabs/pkcs .
This document does not try to cover PKCS #15 in detail; it
just tries to give readers not familiar with the standard a
brief overview.
.PP
PKCS #15 defines a standard how to store keys, certificates
and possibly other data on a smart card, and how to describe
certain meta information (such as what PIN the user needs to
present before he's allowed to use a certain private key).
.PP
A PKCS #15 compliant smart card can contain one or more
applications. There is one ``meta directory'' that contains
a list of all applications. On cards that support an ISO 7816
compatible file system, each application usually resides in
a directory of its own.
.PP
Within each application directory,
PKCS #15 defines a structure of meta files (also
called Directory Files) that contain information on objects
stored on the card. For instance, there is a private key
directory file (or PrKDF for short) that contains a list of
private keys stored on the card. Likewise, there's a
public key directory file (PuKDF) and a certificate directory
file (CDF).
.PP
One fairly important PKCS #15 directory file is the AODF, or
authorization object directory file, which describes
the PINs held by the card. Note the AODF does not contain
the PINs themselves; this is something that is highly
card specific. What the AODF does contain however is
a descriptive label for each PIN, and additional information
required to authenticate against this PIN (sorry if this
is very vague, but unless you really want to know, we'll
better leave it at that, for the sake of your and my sanity :-).
.PP
Each object stored in a PKCS #15 structure has an ID
assigned to it, so that related objects can reference
one another. For instance, if a private key is protected
by a PIN, the PrKDF entry for this key will contain
an Authentication ID field that points to the AODF entry
for this PIN.
.PP
Similarly, if the card contains a certificate corresponding
to a private key stored on this card, the CDF entry for the
certificate will have the same ID as the PrKDF entry for
the private key. The same is true of public key objects.
.SH BUGS
This manual page is a little terse.
.PP
The use of the term Directory File in PKCS #15 is somewhat
unfortunate. Normally, a PKCS #15 DF is just a plain
(elementary) file, not a directory file in the sense of
ISO 7816.
.SH AUTHORS
This manual page was written by Olaf Kirch <okir@lst.de>.