diff --git a/doc/ChangeLog b/doc/ChangeLog index 4c2eaf216..c8e955ef2 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,13 @@ +2004-09-30 Werner Koch + + * gpg.texi: New. + * gnupg.texi: Include gpg.texi + + * tools.texi: Add a few @command markups. + * gpgsm.texi: Ditto + * gpg-agent.texi: Ditto. + * scdaemon.texi: Ditto. + 2004-09-30 Marcus Brinkmann * tools.texi (Changing options): Add documentation for gpgconf. diff --git a/doc/Makefile.am b/doc/Makefile.am index 3ac312049..d44765a2e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,8 +21,8 @@ info_TEXINFOS = gnupg.texi gnupg_TEXINFOS = \ - gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi tools.texi \ - debugging.texi glossary.texi contrib.texi gpl.texi + gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi \ + tools.texi debugging.texi glossary.texi contrib.texi gpl.texi DISTCLEANFILES = gnupg.tmp gnupg.ops diff --git a/doc/gnupg.texi b/doc/gnupg.texi index ec82fe425..478bb4395 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -102,8 +102,8 @@ Boston, MA 02111-1307 USA This manual documents how to use the GNU Privay Guard system as well as the administration and the architecture. -@c * Gpg:: Using the OpenPGP protocol. @menu +* Invoking GPG:: Using the OpenPGP protocol. * Invoking GPGSM:: Using the S/MIME protocol. * Invoking GPG-AGENT:: How to launch the secret key daemon. * Invoking SCDAEMON:: How to handle Smartcards. @@ -127,6 +127,7 @@ Indices * Index:: Index of concepts and symbol names. @end menu +@include gpg.texi @include gpgsm.texi @include gpg-agent.texi @include scdaemon.texi diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi index 2b45a41c1..26b5634cc 100644 --- a/doc/gpg-agent.texi +++ b/doc/gpg-agent.texi @@ -10,9 +10,10 @@ @c man begin DESCRIPTION -@sc{gpg-agent} is a daemon to manage secret (private) keys independelty -from any protocol. It is used as a backend for @sc{gpg} and @sc{gpgsm} -as well as for a couple of other utilities. +@command{gpg-agent} is a daemon to manage secret (private) keys +independelty from any protocol. It is used as a backend for +@command{gpg} and @command{gpgsm} as well as for a couple of other +utilities. @noindent The usual way to run the agent is from the @code{~/.xsession} file: @@ -24,8 +25,8 @@ eval `gpg-agent --daemon` @noindent If you don't use an X server, you can also put this into your regular startup file @code{~/.profile} or @code{.bash_profile}. It is best not -to run multiple instance of the gpg-agent, so you should make sure that -only is running: @sc{gpg-agent} uses an environment variable to inform +to run multiple instance of the @command{gpg-agent}, so you should make sure that +only is running: @command{gpg-agent} uses an environment variable to inform clients about the communication parameters. You can write the content of this environment variable to a file so that you can test for a running agent. This short script may do the job: @@ -66,7 +67,7 @@ one (e.g. @file{/usr/bin/pinentry}). @c man end @noindent -@xref{Option Index}, for an index to GPG-AGENTS's commands and options. +@xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options. @menu * Agent Commands:: List of all commands. @@ -254,7 +255,7 @@ harder for users to inadvertly accept Root-CA keys. @item --ignore-cache-for-signing @opindex ignore-cache-for-signing -This option will let gpg-agent bypass the passphrase cache for all +This option will let @command{gpg-agent} bypass the passphrase cache for all signing operation. Note that there is also a per-session option to control this behaviour but this command line option takes precedence. @@ -372,13 +373,13 @@ $ eval `gpg-agent --daemon` @node Agent Protocol @section Agent's Assuan Protocol -The gpg-agent should be started by the login shell and set an +The @command{gpg-agent} should be started by the login shell and set an environment variable to tell clients about the socket to be used. Clients should deny to access an agent with a socket name which does not match its own configuration. An application may choose to start an instance of the gpgagent if it does not figure that any has been started; it should not do this if a gpgagent is running but not -usable. Because gpg-agent can only be used in background mode, no +usable. Because @command{gpg-agent} can only be used in background mode, no special command line option is required to activate the use of the protocol. @@ -416,7 +417,7 @@ appropriate secret key or to delegate it to a smartcard. @end example Tell the server about the key to be used for decryption. If this is -not used, gpg-agent may try to figure out the key by trying to +not used, @command{gpg-agent} may try to figure out the key by trying to decrypt the message with each key available. @example @@ -528,8 +529,8 @@ The operation is affected by the option @end example The default of @code{1} uses the cache. Setting this option to @code{0} -will lead gpg-agent to ignore the passphrase cache. Note, that there is -also a global command line option for gpg-agent to globally disable the +will lead @command{gpg-agent} to ignore the passphrase cache. Note, that there is +also a global command line option for @command{gpg-agent} to globally disable the caching. diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi index 05c351cd8..94e6936ad 100644 --- a/doc/gpgsm.texi +++ b/doc/gpgsm.texi @@ -10,15 +10,15 @@ @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. +@command{gpgsm} is a tool similar to @command{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. +@command{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. +@xref{Option Index}, for an index to @command{GPGSM}'s commands and options. @menu * GPGSM Commands:: List of all commands. @@ -26,7 +26,7 @@ rules defined for the German Sphinx project. * GPGSM Examples:: Some usage examples. Developer information: -* Unattended Usage:: Using @sc{gpgsm} from other programs. +* Unattended Usage:: Using @command{gpgsm} from other programs. * GPGSM Protocol:: The protocol the server mode uses. @end menu @@ -106,7 +106,7 @@ 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 +where a dirmngr must be able to call back to @command{gpgsm}. See the Dirmngr manual for details. @item --call-protect-tool @var{arguments} @@ -169,7 +169,7 @@ 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 +because @command{gpgsm} always make sure that the validity of a certificate is checked right before it is used. @item --delete-keys @var{pattern} @@ -208,7 +208,7 @@ smartcard is not yet supported. @node GPGSM Options @section Option Summary -GPGSM comes features a bunch ofoptions to control the exact behaviour +@command{GPGSM} comes features a bunch ofoptions to control the exact behaviour and to change the default configuration. @menu @@ -242,7 +242,7 @@ below the home directory of the user. @opindex verbose Outputs additional information while running. You can increase the verbosity by giving several -verbose commands to @sc{gpgsm}, such as @samp{-vv}. +verbose commands to @command{gpgsm}, such as @samp{-vv}. @item --policy-file @var{filename} @opindex policy-file @@ -463,7 +463,7 @@ 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 +Usually @command{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 @@ -472,12 +472,12 @@ 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. +lets @command{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 +lets @command{gpgsm} ignore all notAfter dates, this is used by the regresssion tests. @item --fixed-passphrase @var{string} @@ -515,7 +515,7 @@ $ gpgsm -er goo@@bar.net ciphertext @node Unattended Usage @section Unattended Usage -@sc{gpgsm} is often used as a backend engine by other software. To help +@command{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 @@ -541,7 +541,7 @@ 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 +should be displayed. Depending on the subcase @command{gpgsm} will issue these status codes: @table @asis @item signature valid and nothing did expire @@ -556,7 +556,7 @@ these status codes: @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: +@command{gpgsm} issues one of these status codes sequences: @table @code @item @code{BADSIG} @item @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER} @@ -576,12 +576,13 @@ this is a missing certificate. @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). +Description of the protocol used to access @command{GPGSM}. +@command{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 +@command{gpgsm} as a server the command line the option +@code{--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. @@ -658,7 +659,7 @@ 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 +otherwise mark it as invalid. @command{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 @@ -671,7 +672,7 @@ closed. 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 +is no need to set recipients. @command{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. @@ -697,7 +698,7 @@ Signing is usually done with these commands: INPUT FD=@var{n} [--armor|--base64|--binary] @end example -This tells GPGSM to read the data to sign from file descriptor @var{n}. +This tells @command{GPGSM} to read the data to sign from file descriptor @var{n}. @example OUTPUT FD=@var{m} [--armor|--base64] @@ -755,14 +756,14 @@ client must provide it. 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 +token is used to store the key. Configuration options to @command{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 +@command{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: diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi index 3e11a8930..42dedb6b4 100644 --- a/doc/scdaemon.texi +++ b/doc/scdaemon.texi @@ -10,7 +10,7 @@ @c man begin DESCRIPTION -The @sc{scdaemon} is a daemon to manage smartcards. It is usually +The @command{scdaemon} is a daemon to manage smartcards. It is usually invoked by gpg-agent and in general not used directly. @c man end @@ -87,7 +87,7 @@ below the home directory of the user. @opindex verbose Outputs additional information while running. You can increase the verbosity by giving several -verbose commands to @sc{gpgsm}, such as @samp{-vv}. +verbose commands to @command{gpgsm}, such as @samp{-vv}. @item --debug-level @var{level} @opindex debug-level @@ -200,7 +200,7 @@ stripping off the two leading dashes. @node Card applications @section Description of card applications -@sc{scdaemon} supports the card applications as described below. +@command{scdaemon} supports the card applications as described below. @menu * OpenPGP Card:: The OpenPGP card application @@ -212,8 +212,8 @@ stripping off the two leading dashes. @node OpenPGP Card @subsection The OpenPGP card application ``openpgp'' -This application is currently only used by @sc{gpg} but may in -future also be useful with @sc{gpgsm}. +This application is currently only used by @command{gpg} but may in +future also be useful with @command{gpgsm}. The specification for such a card is available at @uref{http://g10code.com/docs/openpgp-card-1.0.pdf}. @@ -223,7 +223,7 @@ The specification for such a card is available at This is the main application of the Telesec cards as available in Germany. It is a superset of the German DINSIG card. The card is -used by @sc{gpgsm}. +used by @command{gpgsm}. @node DINSIG Card @subsection The DINSIG card application ``dinsig'' @@ -237,7 +237,7 @@ the German signature law and its bylaws (SigG and SigV). This is common fraqmework for smart card applications; support is only available if compiled with support for the OpenSC library. It is used -by @sc{gpgsm}. +by @command{gpgsm}. @@ -375,7 +375,7 @@ To sign some data the caller should use the command SETDATA @var{hexstring} @end example -to tell scdaemon about the data to be signed. The data must be given in +to tell @command{scdaemon} about the data to be signed. The data must be given in hex notation. The actual signing is done using the command @example @@ -395,8 +395,9 @@ To decrypt some data the caller should use the command SETDATA @var{hexstring} @end example -to tell scdaemon about the data to be decrypted. The data must be given in -hex notation. The actual decryption is then done using the command +to tell @command{scdaemon} about the data to be decrypted. The data +must be given in hex notation. The actual decryption is then done +using the command @example PKDECRYPT @var{keyid} diff --git a/doc/tools.texi b/doc/tools.texi index 72707639c..79ae85d90 100644 --- a/doc/tools.texi +++ b/doc/tools.texi @@ -13,18 +13,20 @@ GnuPG comes with a couple of smaller tools: * gpgconf:: Modify .gnupg home directories. @end menu - +@c +@c WATHCGNUPG +@c @node watchgnupg @section Read logs from a socket Most of the main utilities are able to write there log files to a -Unix Domain socket if configured that way. watchgnupg is a simple +Unix Domain socket if configured that way. @command{watchgnupg} is a simple listener for such a socket. It ameliorates the output with a time stamp and makes sure that long lines are not interspersed with log output from other utilities. @noindent -watchgnupg is commonly invoked as +@command{watchgnupg} is commonly invoked as @samp{watchgnupg --force ~/.gnupg/S.log} @@ -33,7 +35,7 @@ This starts it on the current terminal for listening on the socket @file{~/.gnupg/S.log}. @noindent -watchgnupg understands these options: +@command{watchgnupg} understands these options: @table @gnupgtabopt @@ -56,7 +58,9 @@ Display a brief help page and exit @end table - +@c +@c ADDGNUPGHOME +@c @node addgnupghome @section Create .gnupg home directories. @@ -69,11 +73,14 @@ directories of the accounts given on the command line. It takes care not to overwrite existing GnuPG home directories. @noindent -addgnupghome is invoked by root as: +@command{addgnupghome} is invoked by root as: @samp{addgnupghome account1 account2 ... accountn} +@c +@c GPGCONF +@c @node gpgconf @section Modify .gnupg home directories.