From 47b1df15afa429e0f92822ee04c716aea2f7e143 Mon Sep 17 00:00:00 2001 From: okir Date: Wed, 13 Mar 2002 13:09:15 +0000 Subject: [PATCH] - added a bunch of manpages git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@310 c6295689-39f2-0310-b995-f0e70906c6a9 --- docs/pkcs15-crypt.1 | 88 ++++++++++++++++++ docs/pkcs15-init.1 | 201 ++++++++++++++++++++++++++++++++++++++++++ docs/pkcs15-profile.5 | 36 ++++++++ docs/pkcs15.7 | 60 +++++++++++++ 4 files changed, 385 insertions(+) create mode 100644 docs/pkcs15-crypt.1 create mode 100644 docs/pkcs15-init.1 create mode 100644 docs/pkcs15-profile.5 create mode 100644 docs/pkcs15.7 diff --git a/docs/pkcs15-crypt.1 b/docs/pkcs15-crypt.1 new file mode 100644 index 00000000..223a96e1 --- /dev/null +++ b/docs/pkcs15-crypt.1 @@ -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ä . +This manpage was contributed by Olaf Kirch . diff --git a/docs/pkcs15-init.1 b/docs/pkcs15-init.1 new file mode 100644 index 00000000..8f193cff --- /dev/null +++ b/docs/pkcs15-init.1 @@ -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 diff --git a/docs/pkcs15-profile.5 b/docs/pkcs15-profile.5 new file mode 100644 index 00000000..2f821405 --- /dev/null +++ b/docs/pkcs15-profile.5 @@ -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 . diff --git a/docs/pkcs15.7 b/docs/pkcs15.7 new file mode 100644 index 00000000..1a69c259 --- /dev/null +++ b/docs/pkcs15.7 @@ -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 .