diff options
Diffstat (limited to 'doc/gpgsm.texi')
| -rw-r--r-- | doc/gpgsm.texi | 848 |
1 files changed, 0 insertions, 848 deletions
diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi deleted file mode 100644 index 4bb688c44..000000000 --- a/doc/gpgsm.texi +++ /dev/null @@ -1,848 +0,0 @@ -@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 file names given as arguments should have an -absulte file name (i.e. commencing with @code{/} 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 -@itemx -k -@opindex list-keys -List all available certificates stored in the local key database. - -@item --list-secret-keys -@itemx -K -@opindex list-secret-keys -List all available certificates for which a corresponding a secret key -is available. - -@item --list-external-keys @var{pattern} -@opindex list-keys -List certificates matching @var{pattern} using an external server. This -utilizes the @code{dirmngr} service. - -@item --dump-keys -@opindex dump-keys -List all available certificates stored in the local key database using a -format useful mainly for debugging. - -@item --dump-secret-keys -@opindex dump-secret-keys -List all available certificates for which a corresponding a secret key -is available using a format useful mainly for debugging. - -@item --dump-external-keys @var{pattern} -@opindex dump-keys -List certificates matching @var{pattern} using an external server. -This utilizes the @code{dirmngr} service. It uses a format useful -mainly for debugging. - -@item --keydb-clear-some-cert-flags -@opindex keydb-clear-some-cert-flags -This is a debugging aid to reset certain flags in the key database -which are used to cache certain certificate stati. It is especially -useful if a bad CRL or a weird running OCSP reponder did accidently -revoke certificate. There is no security issue with this command -because gpgsm always make sure that the validity of a certificate is -checked right before it is used. - -@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 --export-secret-key-p12 @var{key-id} -@opindex export -Export the private key and the certificate identified by @var{key-id} -in a PKCS#12 format. When using along with the @code{--armor} option -a few informational lines are prepended to the output. Note, that the -PKCS#12 format is higly insecure and this command is only provided if -there is no other way to exchange the private key. - -@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. The default configuration file is named -@file{gpgsm.conf} and expected in the @file{.gnupg} directory directly -below the home directory of the user. - -@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. - -@item --force-crl-refresh -@opindex force-crl-refresh -Tell the dirmngr to reload the CRL for each request. For better -performance, the dirmngr will actually optimize this by suppressing -the loading for short time intervalls (e.g. 30 minutes). This option -is useful to make sure that a fresh CRL is available for certificates -hold in the keybox. The suggested way of doing this is by using it -along with the option @code{--with-validation} for a ke listing -command. This option should not be used in a configuration file. - -@item --enable-ocsp -@itemx --disable-ocsp -@opindex enable-ocsp -@opindex disable-ocsp -Be default @acronym{OCSP} checks are disabled. The enable opton may -be used to enable OCSP checks via Dirmngr. If @acronym{CRL} checks -are also enabled, CRLs willbe used as a fallback if for some reason an -OCSP request won't succeed. - -@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 file name of the -secret key. - -@item --with-validation -@opindex with-validation -When doing a key listing, do a full validation check for each key and -print the result. This is usually a slow operation because it -requires a CRL lookup and other operations. - -@item --with-md5-fingerprint -For standard key listings, also print the MD5 fingerprint of the -certificate. - -@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-level @var{level} -@opindex debug-level -Select the debug level for investigating problems. @var{level} may be -one of: - - @table @code - @item none - no debugging at all. - @item basic - some basic debug messages - @item advanced - more verbose debug messages - @item expert - even more detailed messages - @item guru - all of the debug messages you can get - @end table - -How these messages are mapped to the actual debugging flags is not -specified and may change with newer releaes of this program. They are -however carefully selected to best aid in debugging. - -@item --debug @var{flags} -@opindex debug -This option is only useful for debugging and the behaviour may change -at any time without notice; using @code{--debug-levels} is the -preferred method to select the debug verbosity. 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 - @end table - -Note, that all flags set using this option may get overriden by -@code{--debug-level}. - -@item --debug-all -@opindex debug-all -Same as @code{--debug=0xffffffff} - -@item --debug-allow-core-dump -@opindex debug-allow-core-dump -Usually gpgsm tries to avoid dumping core by well written code and by -disabling core dumps for security reasons. However, bugs are pretty -durable beasts and to squash them it is sometimes useful to have a core -dump. This option enables core dumps unless the Bad Thing happened -before the option parsing. - -@item --debug-no-chain-validation -@opindex debug-no-chain-validation -This is actually not a debugging option but only useful as such. It -lets gpgsm bypass all certificate chain validation checks. - -@item --debug-ignore-expiration -@opindex debug-ignore-expiration -This is actually not a debugging option but only useful as such. It -lets gpgsm ignore all notAfter dates, this is used by the regresssion -tests. - -@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. Note that the code will also handle PKCS\#12 files and -import private keys; a helper program is used for that. - - -@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. - |