diff options
Diffstat (limited to 'doc/gpgsm.texi')
| -rw-r--r-- | doc/gpgsm.texi | 738 |
1 files changed, 738 insertions, 0 deletions
diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi new file mode 100644 index 000000000..4d91bda5b --- /dev/null +++ b/doc/gpgsm.texi @@ -0,0 +1,738 @@ +@c Copyright (C) 2002 Free Software Foundation, Inc. +@c This is part of the GnuPG manual. +@c For copying conditions, see the file gnupg.texi. + +@node Invoking GPGSM +@chapter Invoking GPGSM +@cindex GPGSM command options +@cindex command options +@cindex options, GPGSM command + +@c man begin DESCRIPTION + +@sc{gpgsm} is a tool similar to @sc{gpg} to provide digital encryption +and signing servicesd on X.509 certificates and the CMS protocoll. It +is mainly used as a backend for S/MIME mail processing. @sc{gpgsm} +includes a full features certificate management and complies with all +rules defined for the German Sphinx project. + +@c man end + +@xref{Option Index}, for an index to GPGSM's commands and options. + +@menu +* GPGSM Commands:: List of all commands. +* GPGSM Options:: List of all options. +* GPGSM Examples:: Some usage examples. + +Developer information: +* Unattended Usage:: Using @sc{gpgsm} from other programs. +* GPGSM Protocol:: The protocol the server mode uses. +@end menu + +@c man begin COMMANDS + +@node GPGSM Commands +@section Commands + +Commands are not distinguished from options execpt for the fact that +only one one command is allowed. + +@menu +* General Commands:: Commands not specific to the functionality. +* Operational Commands:: Commands to select the type of operation. +* Certificate Management:: How to manage certificates. +@end menu + +@node General Commands +@subsection Commands not specific to the function + +@table @gnupgtabopt +@item --version +@opindex version +Print the program version and licensing information. Not that you can +abbreviate this command. + +@item --help, -h +@opindex help +Print a usage message summarizing the most usefule command-line options. +Not that you can abbreviate this command. + +@item --dump-options +@opindex dump-options +Print a list of all available options and commands. Not that you can +abbreviate this command. +@end table + + + +@node Operational Commands +@subsection Commands to select the type of operation + +@table @gnupgtabopt +@item --encrypt +@opindex encrypt +Perform an encryption. + +@item --decrypt +@opindex decrypt +Perform a decryption; the type of input is automatically detmerined. It +may either be in binary form or PEM encoded; automatic determination of +base-64 encoding is not done. + +@item --sign +@opindex sign +Create a digital signature. The key used is either the fist one found +in the keybox or thise set with the -u option + +@item --verify +@opindex verify +Check a signature file for validity. Depending on the arguments a +detached signatrue may also be checked. + +@item --server +@opindex server +Run in server mode and wait for commands on the @code{stdin}. + +@item --call-dirmngr @var{command} [@var{args}] +@opindex call-dirmngr +Behave as a Dirmngr client issuing the request @var{command} with the +optional list of @var{args}. The output of the Dirmngr is printed +stdout. Please note that filenames given as arguments should have an +absulte path because they are passed verbatim to the Dirmngr and the +working directory of the Dirmngr might not be the same as the one of +this client. Currently it is not possible to pass data via stdin to the +Dirmngr. @var{command} should not contain spaces. + +This is command is required for certain maintaining tasks of the dirmngr +where a dirmngr must be able to call back to gpgsm. See the Dirmngr +manual for details. + +@item --call-protect-tool @var{arguments} +@opindex call-protect-tool +Certain maintenance operations are done by an external program call +@command{gpg-protect-tool}; this is usually not installed in a directory +listed in the PATH variable. This command provides a simple wrapper to +access this tool. @var{arguments} are passed verbatim to this command; +use @samp{--help} to get a list of supported operations. + + +@end table + + +@node Certificate Management +@subsection How to manage the certificate and keys + +@table @gnupgtabopt +@item --gen-key +@opindex gen-key +Generate a new key and a certificate request. + +@item --list-keys +@opindex list-keys +List all available certificates stored in the local key database. + +@item --list-secret-keys +@opindex list-secret-keys +List all available keys whenre a secret key is available. + +@item --list-external-keys @var{pattern} +@opindex list-keys +List certificates matching @var{pattern} using an external server. This +utilies the @code{dirmngr} service. + +@item --delete-keys @var{pattern} +@opindex delete-keys +Delete the keys matching @var{pattern}. + +@item --export [@var{pattern}] +@opindex export +Export all certificates stored in the Keybox or those specified by the +optional @var{pattern}. When using along with the @code{--armor} option +a few informational lines are prepended before each block. + +@item --learn-card +@opindex learn-card +Read information about the private keys from the smartcard and import +the certificates from there. This command utilizes the @sc{gpg-agent} +and in turn the @sc{scdaemon}. + +@item --passwd @var{user_id} +@opindex passwd +Change the passphrase of the private key belonging to the certificate +specified as @var{user_id}. Note, that changing the passphrase/PIN of a +smartcard is not yet supported. + +@end table + + +@node GPGSM Options +@section Option Summary + +GPGSM comes features a bunch ofoptions to control the exact behaviour +and to change the default configuration. + +@menu +* Configuration Options:: How to change the configuration. +* Certificate Options:: Certificate related options. +* Input and Output:: Input and Output. +* CMS Options:: How to change how the CMS is created. +* Esoteric Options:: Doing things one usually don't want to do. +@end menu + +@c man begin OPTIONS + +@node Configuration Options +@subsection How to change the configuration + +These options are used to change the configuraton and are usually found +in the option file. + +@table @gnupgtabopt + +@item --options @var{file} +@opindex options +Reads configuration from @var{file} instead of from the default +per-user configuration file. + +@item -v +@item --verbose +@opindex v +@opindex verbose +Outputs additional information while running. +You can increase the verbosity by giving several +verbose commands to @sc{gpgsm}, such as @samp{-vv}. + +@item --policy-file @var{filename} +@opindex policy-file +Change the default name of the policy file to @var{filename}. + +@item --agent-program @var{file} +@opindex agent-program +Specify an agent program to be used for secret key operations. The +default value is the @file{/usr/local/bin/gpg-agent}. This is only used +as a fallback when the envrionment variable @code{GPG_AGENT_INFO} is not +set or a running agent can't be connected. + +@item --dirmngr-program @var{file} +@opindex dirmnr-program +Specify a dirmngr program to be used for @acronym{CRL} checks. The +default value is @file{/usr/sbin/dirmngr}. This is only used as a +fallback when the environment variable @code{DIRMNGR_INFO} is not set or +a running dirmngr can't be connected. + +@item --no-secmem-warning +@opindex no-secmem-warning +Don't print a warning when the so called "secure memory" can't be used. + + + +@end table + + +@node Certificate Options +@subsection Certificate related options + +@table @gnupgtabopt + +@item --enable-policy-checks +@itemx --disable-policy-checks +@opindex enable-policy-checks +@opindex disable-policy-checks +By default policy checks are enabled. These options may be used to +change it. + +@item --enable-crl-checks +@itemx --disable-crl-checks +@opindex enable-crl-checks +@opindex disable-crl-checks +By default the @acronym{CRL} checks are enabled and the DirMngr is used +to check for revoked certificates. The disable option is most useful +with an off-line network connection to suppress this check. + +@end table + +@node Input and Output +@subsection Input and Output + +@table @gnupgtabopt +@item --armor +@itemx -a +@opindex armor +@opindex -a +Create PEM encoded output. Default is binary output. + +@item --base64 +@opindex base64 +Create Base-64 encoded output; i.e. PEM without the header lines. + +@item --assume-armor +@opindex assume-armor +Assume the input data is PEM encoded. Default is to autodetect the +encoding but this is may fail. + +@item --assume-base64 +@opindex assume-base64 +Assume the input data is plain base-64 encoded. + +@item --assume-binary +@opindex assume-binary +Assume the input data is binary encoded. + +@item --local-user @var{user_id} +@item -u @var{user_id} +@opindex local-user +@opindex -u +Set the user(s) to be used for signing. The default is the first +secret key found in the database. + +@item --with-key-data +@opindex with-key-data +Displays extra information with the @code{--list-keys} commands. Especially +a line tagged @code{grp} is printed which tells you the keygrip of a +key. This string is for example used as the filename of the +secret key. + +@end table + +@node CMS Options +@subsection How to change how the CMS is created. + +@table @gnupgtabopt +@item --include-certs @var{n} +Using @var{n} of -2 includes all certificate except for the root cert, +-1 includes all certs, 0 does not include any certs, 1 includes only +the signers cert (this is the default) and all other positive +values include up to @var{n} certificates starting with the signer cert. + +@end table + + + +@node Esoteric Options +@subsection Doing things one usually don't want todo. + + +@table @gnupgtabopt + +@item --faked-system-time @var{epoch} +@opindex faked-system-time +This option is only useful for testing; it sets the system time back or +forth to @var{epoch} which is the number of seconds elapsed since the year +1970. + +@item --debug @var{flags} +@opindex debug +This option is only useful for debugging and the behaviour may change at +any time without notice. FLAGS are bit encoded and may be given in +usual C-Syntax. The currently defined bits are: + @table @code + @item 0 (1) + X.509 or OpenPGP protocol related data + @item 1 (2) + values of big number integers + @item 2 (4) + low level crypto operations + @item 5 (32) + memory allocation + @item 6 (64) + caching + @item 7 (128) + show memory statistics. + @item 9 (512) + write hashed data to files named @code{dbgmd-000*} + @item 10 (1024) + trace Assuan protocol + @item 12 (4096) + bypass all certificate validation + @end table + +@item --debug-all +@opindex debug-all +Same as @code{--debug=0xffffffff} + +@item --debug-no-path-validation +@opindex debug-no-path-validation +This is actually not a debugging option but only useful as such. It +lets gpgsm bypass all certificate path validation checks. + +@end table + +All the long options may also be given in the configuration file after +stripping off the two leading dashes. + + + +@c +@c Examples +@c +@node GPGSM Examples +@section Examples + +@c man begin EXAMPLES + +@example +$ gpgsm -er goo@@bar.net <plaintext >ciphertext +@end example + +@c man end + + + +@c --------------------------------- +@c The machine interface +@c -------------------------------- +@node Unattended Usage +@section Unattended Usage + +@sc{gpgsm} is often used as a backend engine by other software. To help +with this a machine interface has been defined to have an unambiguous +way to do this. This is most likely used with the @code{--server} command +but may also be used in the standard operation mode by using the +@code{--status-fd} option. + +@menu +* Automated signature checking:: Automated signature checking. +@end menu + +@node Automated signature checking,,,Unattended Usage +@section Automated signature checking + +It is very important to understand the semantics used with signature +verification. Checking a signature is not as simple as it may sound and +so the ooperation si a bit complicated. In mosted cases it is required +to look at several status lines. Here is a table of all cases a signed +message may have: + +@table @asis +@item The signature is valid +This does mean that the signature has been successfully verified, the +certificates are all sane. However there are two subcases with +important information: One of the certificates may have expired or a +signature of a message itself as expired. It is a sound practise to +consider such a signature still as valid but additional information +should be displayed. Depending on the subcase @sc{gpgsm} will issue +these status codes: + @table @asis + @item signature valid and nothing did expire + @code{GOODSIG}, @code{VALIDSIG}, @code{TRUST_FULLY} + @item signature valid but at least one certificate has expired + @code{EXPKEYSIG}, @code{VALIDSIG}, @code{TRUST_FULLY} + @item signature valid but expired + @code{EXPSIG}, @code{VALIDSIG}, @code{TRUST_FULLY} + Note, that this case is currently not implemented. + @end table + +@item The signature is invalid +This means that the signature verification failed (this is an indication +of af a transfer error, a programm error or tampering with the message). +@sc{gpgsm} issues one of these status codes sequences: + @table @code + @item @code{BADSIG} + @item @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER} + @end table + +@item Error verifying a signature +For some reason the signature could not be verified, i.e. it can't be +decided whether the signature is valid or invalid. A common reason for +this is a missing certificate. + +@end table + + +@c +@c Assuan Protocol +@c +@node GPGSM Protocol +@section The Protocol the Server Mode Uses. + +Description of the protocol used to access GPGSM. GPGSM does implement +the Assuan protocol and in addition provides a regular command line +interface which exhibits a full client to this protocol (but uses +internal linking). To start gpgsm as a server the commandline "gpgsm +--server" must be used. Additional options are provided to select the +communication method (i.e. the name of the socket). + +We assume that the connection has already been established; see the +Assuan manual for details. + +@menu +* GPGSM ENCRYPT:: Encrypting a message. +* GPGSM DECRYPT:: Decrypting a message. +* GPGSM SIGN:: Signing a message. +* GPGSM VERIFY:: Verifying a message. +* GPGSM GENKEY:: Generating a key. +* GPGSM LISTKEYS:: List available keys. +* GPGSM EXPORT:: Export certificates. +* GPGSM IMPORT:: Import certificates. +* GPGSM DELETE:: Delete certificates. +@end menu + + +@node GPGSM ENCRYPT +@subsection Encrypting a Message + +Before encrytion can be done the recipient must be set using the +command: + +@example + RECIPIENT @var{userID} +@end example + +Set the recipient for the encryption. @var{userID} should be the +internal representation of the key; the server may accept any other way +of specification. If this is a valid and trusted recipient the server +does respond with OK, otherwise the return is an ERR with the reason why +the recipient can't be used, the encryption will then not be done for +this recipient. If the policy is not to encrypt at all if not all +recipients are valid, the client has to take care of this. All +@code{RECIPIENT} commands are cumulative until a @code{RESET} or an +successful @code{ENCRYPT} command. + +@example + INPUT FD=@var{n} [--armor|--base64|--binary] +@end example + +Set the file descriptor for the message to be encrypted to @var{n}. +Obviously the pipe must be open at that point, the server establishes +its own end. If the server returns an error the client should consider +this session failed. + +The @code{--armor} option may be used to advice the server that the +input data is in @acronym{PEM} format, @code{--base64} advices that a +raw base-64 encoding is used, @code{--binary} advices of raw binary +input (@acronym{BER}). If none of these options is used, the server +tries to figure out the used encoding, but this may not always be +correct. + +@example + OUTPUT FD=@var{n} [--armor|--base64] +@end example + +Set the file descriptor to be used for the output (i.e. the encrypted +message). Obviously the pipe must be open at that point, the server +establishes its own end. If the server returns an error he client +should consider this session failed. + +The option armor encodes the output in @acronym{PEM} format, the +@code{--base64} option applies just a base 64 encoding. No option +creates binary output (@acronym{BER}). + +The actual encryption is done using the command + +@example + ENCRYPT +@end example + +It takes the plaintext from the @code{INPUT} command, writes to the +ciphertext to the file descriptor set with the @code{OUTPUT} command, +take the recipients from all the recipients set so far. If this command +fails the clients should try to delete all output currently done or +otherwise mark it as invalid. GPGSM does ensure that there won't be any +security problem with leftover data on the output in this case. + +This command should in general not fail, as all necessary checks have +been done while setting the recipients. The input and output pipes are +closed. + + +@node GPGSM DECRYPT +@subsection Decrypting a message + +Input and output FDs are set the same way as in encryption, but +@code{INPUT} refers to the ciphertext and output to the plaintext. There +is no need to set recipients. GPGSM automatically strips any +@acronym{S/MIME} headers from the input, so it is valid to pass an +entire MIME part to the INPUT pipe. + +The encryption is done by using the command + +@example + DECRYPT +@end example + +It performs the decrypt operation after doing some check on the internal +state. (e.g. that all needed data has been set). Because it utilizes +the GPG-Agent for the session key decryption, there is no need to ask +the client for a protecting passphrase - GpgAgent takes care of this by +requesting this from the user. + + +@node GPGSM SIGN +@subsection Signing a Message + +Signing is usually done with these commands: + +@example + INPUT FD=@var{n} [--armor|--base64|--binary] +@end example + +This tells GPGSM to read the data to sign from file descriptor @var{n}. + +@example + OUTPUT FD=@var{m} [--armor|--base64] +@end example + +Write the output to file descriptor @var{m}. If a detached signature is +requested, only the signature is written. + +@example + SIGN [--detached] +@end example + +Sign the data set with the INPUT command and write it to the sink set by +OUTPUT. With @code{--detached}, a detached signature is created +(surprise). + +The key used for signining is the default one or the one specified in +the configuration file. To get finer control over the keys, it is +possible to use the command + +@example + SIGNER @var{userID} +@end example + +to the signer's key. @var{userID} should be the +internal representation of the key; the server may accept any other way +of specification. If this is a valid and trusted recipient the server +does respond with OK, otherwise the return is an ERR with the reason why +the key can't be used, the signature will then not be created using +this key. If the policy is not to sign at all if not all +keys are valid, the client has to take care of this. All +@code{SIGNER} commands are cumulative until a @code{RESET} is done. +Note that a @code{SIGN} does not reset this list of signers which is in +contrats to the @code{RECIPIENT} command. + + +@node GPGSM VERIFY +@subsection Verifying a Message + +To verify a mesage the command: + +@example + VERIFY +@end example + +is used. It does a verify operation on the message send to the input FD. +The result is written out using status lines. If an output FD was +given, the signed text will be written to that. If the signature is a +detached one, the server will inquire about the signed material and the +client must provide it. + +@node GPGSM GENKEY +@subsection Generating a Key + +This is used to generate a new keypair, store the secret part in the +@acronym{PSE} and the public key in the key database. We will probably +add optional commands to allow the client to select whether a hardware +token is used to store the key. Configuration options to GPGSM can be +used to restrict the use of this command. + +@example + GENKEY +@end example + +GPGSM checks whether this command is allowed and then does an +INQUIRY to get the key parameters, the client should then send the +key parameters in the native format: + +@example + S: INQUIRE KEY_PARAM native + C: D foo:fgfgfg + C: D bar + C: END +@end example + +Please note that the server may send Status info lines while reading the +data lines from the client. After this the key generation takes place +and the server eventually does send an ERR or OK response. Status lines +may be issued as a progress indicator. + + +@node GPGSM LISTKEYS +@subsection List available keys + +To list the keys in the internal database or using an external key +provider, the command: + +@example + LISTKEYS @var{pattern} +@end example + +is used. To allow multiple patterns (which are ORed during the search) +quoting is required: Spaces are to be translated into "+" or into "%20"; +in turn this requires that the usual escape quoting rules are done. + +@example + LISTSECRETKEYS @var{pattern} +@end example + +Lists only the keys where a secret key is available. + +The list commands commands are affected by the option + +@example + OPTION list-mode=@var{mode} +@end example + +where mode may be: +@table @code +@item 0 +Use default (which is usually the same as 1). +@item 1 +List only the internal keys. +@item 2 +List only the external keys. +@item 3 +List internal and external keys. +@end table + +Note that options are valid for the entire session. + + +@node GPGSM EXPORT +@subsection Export certificates + +To export certificate from the internal key database the command: + +@example + EXPORT @var{pattern} +@end example + +is used. To allow multiple patterns (which are ORed) quoting is +required: Spaces are to be translated into "+" or into "%20"; in turn +this requires that the usual escape quoting rules are done. + +The format of the output depends on what was set with the OUTPUT +command. When using @acronym{PEM} encoding a few informational lines +are prepended. + + +@node GPGSM IMPORT +@subsection Import certificates + +To import certificates into the internal key database, the command + +@example + IMPORT +@end example + +is used. The data is expected on the file descriptor set with the +@code{INPUT} command. Certain checks are performend on the certificate. + +@node GPGSM DELETE +@subsection Delete certificates + +To delete certificate the command + +@example + DELKEYS @var{pattern} +@end example + +is used. To allow multiple patterns (which are ORed) quoting is +required: Spaces are to be translated into "+" or into "%20"; in turn +this requires that the usual escape quoting rules are done. + +The certificates must be specified unambiguously otherwise an error is +returned. + |