More changes on the way to remove secring.gpg.
[gnupg.git] / doc / tools.texi
index d240aca..e974cc4 100644 (file)
@@ -1,4 +1,4 @@
-@c Copyright (C) 2004 Free Software Foundation, Inc.
+@c Copyright (C) 2004, 2008 Free Software Foundation, Inc.
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file GnuPG.texi.
 
@@ -18,6 +18,7 @@ GnuPG comes with a couple of smaller tools:
 * gpg-connect-agent::     Communicate with a running agent.
 * gpgparsemail::          Parse a mail message into an annotated format
 * symcryptrun::           Call a simple symmetric encryption tool.
+* gpg-zip::               Encrypt or sign files into an archive.
 @end menu
 
 @c
@@ -40,7 +41,7 @@ GnuPG comes with a couple of smaller tools:
 @end ifset
 
 @mansect description
-Most of the main utilities are able to write there log files to a
+Most of the main utilities are able to write their log files to a
 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
@@ -74,11 +75,11 @@ Enable extra informational output.
 
 @item --version
 @opindex version
-print version of the program and exit
+Print version of the program and exit.
 
 @item --help
 @opindex help
-Display a brief help page and exit
+Display a brief help page and exit.
 
 @end table
 
@@ -197,13 +198,14 @@ program that uses @command{gpgconf} in this way will be called GUI
 throughout this section.
 
 @menu
-* Invoking gpgconf::      List of all commands and options.
-* Format conventions::    Formatting conventions relevant for all commands.
-* Listing components::    List all gpgconf components.
-* Checking programs::     Check all programs know to gpgconf.
-* Listing options::       List all options of a component.
-* Changing options::      Changing options of a component.
-* Files used by gpgconf:: What files are used by gpgconf.
+* Invoking gpgconf::       List of all commands and options.
+* Format conventions::     Formatting conventions relevant for all commands.
+* Listing components::     List all gpgconf components.
+* Checking programs::      Check all programs know to gpgconf.
+* Listing options::        List all options of a component.
+* Changing options::       Changing options of a component.
+* Listing global options:: List all global options.
+* Files used by gpgconf::  What files are used by gpgconf.
 @end menu
 
 @manpause
@@ -228,10 +230,27 @@ List all options of the component @var{component}.
 @item --change-options @var{component}
 Change the options of the component @var{component}.
 
+@item --check-options @var{component}
+Check the options for the component @var{component}.
+
 @item --apply-defaults
 Update all configuration files with values taken from the global
 configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
 
+@item --list-dirs
+Lists the directories used by @command{gpgconf}.  One directory is
+listed per line, and each line consists of a colon-separated list where
+the first field names the directory type (for example @code{sysconfdir})
+and the second field contains the percent-escaped directory.  Although
+they are not directories, the socket file names used by
+@command{gpg-agent} and @command{dirmngr} are printed as well.  Note
+that the socket file names and the @code{homedir} lines are the default
+names and they may be overridden by command line switches.
+
+@item --list-config [@var{filename}]
+List the global configuration file in a colon separated format.  If
+@var{filename} is given, check that file instead.
+
 @item --check-config [@var{filename}]
 Run a syntax check on the global configuration file.  If @var{filename}
 is given, check that file instead.
@@ -254,11 +273,10 @@ The following options may be used:
 Outputs additional information while running.  Specifically, this
 extends numerical field values by human-readable descriptions.
 
-@c FIXME: Not yet supported.
-@c @item -n
-@c @itemx --dry-run
-@c Do not actually change anything.  Useful together with
-@c @code{--change-options} for testing purposes.
+@item -n
+@itemx --dry-run
+Do not actually change anything.  This is currently only implemented
+for @code{--change-options} and can be used for testing purposes.
 
 @item -r
 @itemx --runtime
@@ -316,7 +334,7 @@ never contain any special characters.
 Some fields contain strings that are described to be
 @emph{percent-escaped}.  Such strings need to be de-escaped before
 their content can be presented to the user.  A percent-escaped string
-is de-escaped by replacing all occurences of @code{%XY} by the byte
+is de-escaped by replacing all occurrences of @code{%XY} by the byte
 that has the hexadecimal value @code{XY}.  @code{X} and @code{Y} are
 from the set @code{0-9a-f}.
 
@@ -459,7 +477,7 @@ dirmngr:Directory Manager:/usr/local/bin/dirmngr:
 
 The command @code{--check-programs} is similar to
 @code{--list-components} but works on backend programs and not on
-components.  It runs each program to test wether it is installed and
+components.  It runs each program to test whether it is installed and
 runnable.  This also includes a syntax check of all config file options
 of the program.
 
@@ -496,17 +514,17 @@ The @emph{boolean value} in this field indicates whether the program's
 config file is syntactically okay.
 
 @item cfgfile
-If an error occured in the configuraion file (as indicated by a false
+If an error occurred in the configuration file (as indicated by a false
 value in the field @code{okay}), this field has the name of the failing
 configuration file.  It is @emph{percent-escaped}.
 
 @item line
-If an error occured in the configuration file, this field has the line
+If an error occurred in the configuration file, this field has the line
 number of the failing statement in the configuration file.  
 It is an @emph{unsigned number}.
 
 @item error
-If an error occured in the configuration file, this field has the error
+If an error occurred in the configuration file, this field has the error
 text of the failing statement in the configuration file.  It is
 @emph{percent-escaped} and @emph{localized}.
 
@@ -525,6 +543,11 @@ gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
 dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
 @end example
 
+@noindent
+The command @w{@code{--check-options @var{component}}} will verify the
+configuration file in the same manner as @code{--check-programs}, but
+only for the component @var{component}.
+
 
 @node Listing options
 @subsection Listing options
@@ -662,6 +685,22 @@ not necessarily need to exist.
 A @emph{string} that describes an LDAP server in the format:
 
 @code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
+
+@item key fingerprint (34)
+A @emph{string} with a 40 digit fingerprint specifying a certificate.
+
+@item pub key (35)
+A @emph{string} that describes a certificate by user ID, key ID or
+fingerprint.
+
+@item sec key (36)
+A @emph{string} that describes a certificate with a key by user ID,
+key ID or fingerprint.
+
+@item alias list (37)
+A @emph{string} that describes an alias list, like the one used with
+gpg's group option.  The list consists of a key, an equal sign and space
+separated values.
 @end table
 
 More types will be added in the future.  Please see the @var{alt-type}
@@ -686,31 +725,33 @@ name for the argument.  The field may also be empty, though, in which
 case a short name is not known.
 
 @item default
-This field is defined only for options.  Its format is that of an
-@emph{option argument} (@xref{Format conventions}, for details).  If
-the default value is empty, then no default is known.  Otherwise, the
-value specifies the default value for this option.  Note that this
-field is also meaningful if the option itself does not take a real
-argument.
+This field is defined only for options for which the @code{default} or
+@code{default desc} flag is set.  If the @code{default} flag is set,
+its format is that of an @emph{option argument} (@xref{Format
+conventions}, for details).  If the default value is empty, then no
+default is known.  Otherwise, the value specifies the default value
+for this option.  If the @code{default desc} flag is set, the field is
+either empty or contains a description of the effect if the option is
+not given.
 
 @item argdef
 This field is defined only for options for which the @code{optional
 arg} flag is set.  If the @code{no arg desc} flag is not set, its
 format is that of an @emph{option argument} (@xref{Format
 conventions}, for details).  If the default value is empty, then no
-default is known.  Otherwise, the value specifies the default value
+default is known.  Otherwise, the value specifies the default argument
 for this option.  If the @code{no arg desc} flag is set, the field is
 either empty or contains a description of the effect of this option if
-no argument is given.  Note that this field is also meaningful if the
-option itself does not take a real argument.
+no argument is given.
 
 @item value
 This field is defined only for options.  Its format is that of an
 @emph{option argument}.  If it is empty, then the option is not
-explicitely set in the current configuration, and the default applies
+explicitly set in the current configuration, and the default applies
 (if any).  Otherwise, it contains the current value of the option.
 Note that this field is also meaningful if the option itself does not
-take a real argument.
+take a real argument (in this case, it contains the number of times
+the option appears).
 @end table
 
 
@@ -750,6 +791,10 @@ argument is used (only allowed if the argument is optional for this
 option).  Otherwise, the option will be set to the specified value.
 @end table
 
+@noindent
+The output of the command is the same as that of
+@code{--check-options} for the modified configuration file.
+
 Examples:
 
 To set the force option, which is of basic type @code{none (0)}:
@@ -767,6 +812,64 @@ $ echo 'force:16:' | gpgconf --change-options dirmngr
 The @code{--runtime} option can influence when the changes take
 effect.
 
+
+@node Listing global options
+@subsection Listing global options
+
+Sometimes it is useful for applications to look at the global options
+file @file{gpgconf.conf}. 
+The colon separated listing format is record oriented and uses the first
+field to identify the record type:
+
+@table @code
+@item k
+This describes a key record to start the definition of a new ruleset for
+a user/group.  The format of a key record is:
+
+  @code{k:@var{user}:@var{group}:}
+
+@table @var
+@item user
+This is the user field of the key.  It is percent escaped.  See the
+definition of the gpgconf.conf format for details.
+
+@item group
+This is the group field of the key.  It is percent escaped.
+@end table
+
+@item r
+This describes a rule record. All rule records up to the next key record
+make up a rule set for that key.  The format of a rule record is:
+
+  @code{r:::@var{component}:@var{option}:@var{flags}:@var{value}:}
+
+@table @var
+@item component
+This is the component part of a rule.  It is a plain string.
+
+@item option
+This is the option part of a rule.  It is a plain string.
+
+@item flag
+This is the flags part of a rule.  There may be only one flag per rule
+but by using the same component and option, several flags may be
+assigned to an option.  It is a plain string.
+
+@item value
+This is the optional value for the option.  It is a percent escaped
+string with a single quotation mark to indicate a string.  The quotation
+mark is only required to distinguish between no value specified and an
+empty string.
+@end table
+
+@end table
+
+@noindent
+Unknown record types should be ignored.  Note that there is intentionally
+no feature to change the global option file through @command{gpgconf}.
+
+
+
 @mansect files
 @node Files used by gpgconf
 @subsection Files used by gpgconf
@@ -844,7 +947,7 @@ applygnupgdefaults
 @end ifset
 
 @mansect description
-This is a simple tool to interactivly generate a certificate request
+This is a simple tool to interactively generate a certificate request
 which will be printed to stdout.
 
 @manpause
@@ -879,7 +982,7 @@ which will be printed to stdout.
 .B  gpg-preset-passphrase
 .RI [ options ]
 .RI [ command ]
-.I keygrip
+.I cache-id
 @end ifset
 
 @mansect description
@@ -909,14 +1012,19 @@ starting @command{gpg-agent} with the
 @command{gpg-preset-passphrase} is invoked this way:
 
 @example
-gpg-preset-passphrase [options] [command] @var{keygrip}
+gpg-preset-passphrase [options] [command] @var{cacheid}
 @end example
 
-@var{keygrip} is a 40 character string of hexadecimal characters
-identifying the key for which the passphrase should be set or cleared.
-This keygrip is listed along with the key when running the command:
-@code{gpgsm --dump-secret-keys}. One of the following command options
-must be given:
+@var{cacheid} is either a 40 character keygrip of hexadecimal
+characters identifying the key for which the passphrase should be set
+or cleared.  The keygrip is listed along with the key when running the
+command: @code{gpgsm --dump-secret-keys}.  Alternatively an arbitrary
+string may be used to identify a passphrase; it is suggested that such
+a string is prefixed with the name of the application (e.g
+@code{foo:12346}).
+
+@noindent
+One of the following command options must be given:
 
 @table @gnupgtabopt
 @item --preset
@@ -927,7 +1035,7 @@ use. @command{gpg-preset-passphrase} will then read the passphrase from
 
 @item --forget
 @opindex forget
-Flush the passphrase for the given keygrip from the cache.
+Flush the passphrase for the given cache ID from the cache.
 
 @end table
 
@@ -974,14 +1082,14 @@ for other users.
 @mansect synopsis
 @ifset manverb
 .B  gpg-connect-agent
-.RI [ options ]
+.RI [ options ] [commands]
 @end ifset
 
 @mansect description
 The @command{gpg-connect-agent} is a utility to communicate with a
 running @command{gpg-agent}.  It is useful to check out the commands
 gpg-agent provides using the Assuan interface.  It might also be useful
-for scripting simple applications.  Inputis expected at stdin and out
+for scripting simple applications.  Input is expected at stdin and out
 put gets printed to stdout.
 
 It is very similar to running @command{gpg-agent} in server mode; but
@@ -1000,7 +1108,7 @@ here we connect to a running instance.
 @command{gpg-connect-agent} is invoked this way:
 
 @example
-gpg-connect-agent [options]
+gpg-connect-agent [options] [commands]
 @end example
 @mancont
 
@@ -1037,7 +1145,7 @@ execute it as an assuan server. Here is how you would run @command{gpgsm}:
 @smallexample
  gpg-connect-agent --exec gpgsm --server
 @end smallexample
-
+Note that you may not use options on the command line in this case.
 
 @item --no-ext-connect
 @opindex no-ext-connect
@@ -1048,7 +1156,8 @@ passing.  This option makes it use the old mode.
 @item --run @var{file}
 @opindex run 
 Run the commands from @var{file} at startup and then continue with the
-regular input method.
+regular input method.  Note, that commands given on the command line are
+executed after this file.
 
 @item -s
 @itemx --subst
@@ -1083,9 +1192,9 @@ Just print @var{args}.
 @item /let @var{name} @var{value}
 Set the variable @var{name} to @var{value}.  Variables are only
 substituted on the input if the @command{/subst} has been used.
-Variables are referenced by prefixing the name with a dollr sign and
+Variables are referenced by prefixing the name with a dollar sign and
 optionally include the name in curly braces.  The rules for a valid name
-are idnetically to those of the standard bourne shell.  This is not yet
+are identically to those of the standard bourne shell.  This is not yet
 enforced but may be in the future.  When used with curly braces no
 leading or trailing white space is allowed. 
 
@@ -1122,23 +1231,47 @@ have been given to return a useful value.
 
 @item unescape @var{args}
 Remove C-style escapes from @var{args}.  Note that @code{\0} and
-@code{\x00} terminate the returned string implictly.  The string to be
+@code{\x00} terminate the returned string implicitly.  The string to be
 converted are the entire arguments right behind the delimiting space of
 the function name.
 
 @item unpercent @var{args}
 @itemx unpercent+ @var{args}
-Remove percent style ecaping from @var{args}.  Note that @code{%00}
+Remove percent style escaping from @var{args}.  Note that @code{%00}
 terminates the string implicitly.  The string to be converted are the
 entire arguments right behind the delimiting space of the function
 name. @code{unpercent+} also maps plus signs to a spaces.
 
 @item percent @var{args}
-@item percent+ @var{args}
-Escape the @var{args} using percent style ecaping.  Tabs, formfeeds,
+@itemx percent+ @var{args}
+Escape the @var{args} using percent style escaping.  Tabs, formfeeds,
 linefeeds, carriage returns and colons are escaped. @code{percent+} also
 maps spaces to plus signs.
 
+@item errcode @var{arg}
+@itemx errsource @var{arg}
+@itemx errstring @var{arg}
+Assume @var{arg} is an integer and evaluate it using @code{strtol}.  Return
+the gpg-error error code, error source or a formatted string with the
+error code and error source.
+
+
+@item +
+@itemx -
+@itemx *
+@itemx /
+@itemx %
+Evaluate all arguments as long integers using @code{strtol} and apply
+this operator.  A division by zero yields an empty string.
+
+@item !
+@itemx |
+@itemx &
+Evaluate all arguments as long integers using @code{strtol} and apply
+the logical oeprators NOT, OR or AND.  The NOT operator works on the
+last argument only.
+
+
 @end table
 
 
@@ -1155,6 +1288,14 @@ Use content of @var{file} for inquiries with @var{name}.
 Run @var{prog} for inquiries matching @var{name} and pass the
 entire line to it as command line arguments.
 
+@item /datafile @var{name}
+Write all data lines from the server to the file @var{name}.  The file
+is opened for writing and created if it does not exists.  An existing
+file is first truncated to 0.  The data written to the file fully
+decoded.  Using a single dash for @var{name} writes to stdout.  The
+file is kept open until a new file is set using this command or this
+command is used without an argument.
+
 @item /showdef
 Print all definitions
 
@@ -1179,12 +1320,15 @@ Close the file descriptor @var{fd}.  Warning: This command is
 experimental and might change in future versions.
 
 @item /showopen
-Show a listy of open files.
+Show a list of open files.
 
 @item /serverpid
 Send the Assuan command @command{GETINFO pid} to the server and store
 the returned PID for internal purposes.
 
+@item /sleep
+Sleep for a second.
+
 @item /hex
 @itemx /nohex
 Same as the command line option @option{--hex}.
@@ -1197,6 +1341,26 @@ Same as the command line option @option{--decode}.
 @itemx /nosubst
 Enable and disable variable substitution.  It defaults to disabled
 unless the command line option @option{--subst} has been used.
+If /subst as been enabled once, leading whitespace is removed from
+input lines which makes scripts easier to read.
+
+@item /while @var{condition}
+@itemx /end
+These commands provide a way for executing loops.  All lines between the
+@code{while} and the corresponding @code{end} are executed as long as
+the evaluation of @var{condition} yields a non-zero value.  The
+evaluation is done by passing @var{condition} to the @code{strtol}
+function.  Example:
+
+@smallexample
+  /subst
+  /let i 3
+  /while $i
+    /echo loop couter is $i
+    /let i $@{- $i 1@}
+  /end
+@end smallexample
+
 
 @item /run @var{file}
 Run commands from @var{file}.
@@ -1302,7 +1466,7 @@ argument @var{inputfile}, and the ciphertext will be output to STDOUT.
 For decryption vice versa.
 
 @var{CLASS} describes the calling conventions of the external tool.
-Currently it must be given as @samp{confucius}.  @var{PROGRAM} is the
+Currently it must be given as @samp{confucius}.  @var{PROGRAM} is
 the full filename of that external tool.
  
 For the class @samp{confucius} the option @option{--keyfile} is
@@ -1335,7 +1499,7 @@ Try to be as quiet as possible.
 @item --log-file @var{file}
 @opindex log-file
 Append all logging output to @var{file}.  Default is to write logging
-informaton to STDERR.
+information to STDERR.
 
 @end table
 
@@ -1362,3 +1526,145 @@ The possible exit status codes of @command{symcryptrun} are:
 @end ifset
 @include see-also-note.texi
 
+
+@c
+@c  GPG-ZIP
+@c
+@c The original manpage on which this section is based was written 
+@c by Colin Tuckley  <colin@tuckley.org> and Daniel Leidert 
+@c <daniel.leidert@wgdd.de> for the Debian distribution (but may be used by
+@c others).
+@manpage gpg-zip.1
+@node gpg-zip
+@section Encrypt or sign files into an archive
+@ifset manverb
+.B gpg-zip \- Encrypt or sign files into an archive
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  gpg-zip
+.RI [ options ]
+.I filename1
+.I [ filename2, ... ]
+.I directory1
+.I [ directory2, ... ]
+@end ifset
+
+@mansect description
+@command{gpg-zip} encrypts or signs files into an archive.  It is an
+gpg-ized tar using the same format as used by PGP's PGP Zip.
+
+@manpause
+@noindent
+@command{gpg-zip} is invoked this way:
+
+@example
+gpg-zip [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
+@end example
+
+@mansect options
+@noindent
+@command{gpg-zip} understands these options:
+
+@table @gnupgtabopt
+
+@item --encrypt
+@itemx -e
+@opindex encrypt
+Encrypt data.  This option may be combined with @option{--symmetric} (for  output that may be decrypted via a secret key or a passphrase).
+
+@item --decrypt
+@itemx -d
+@opindex decrypt
+Decrypt data.
+
+@item --symmetric
+@itemx -c
+Encrypt with a symmetric cipher using a passphrase.  The default
+symmetric cipher used is CAST5, but may be chosen with the
+@option{--cipher-algo} option to @command{gpg}.
+
+@item --sign
+@itemx -s
+Make a signature.  See @command{gpg}.
+
+@item --recipient @var{user}
+@itemx -r @var{user}
+@opindex recipient
+Encrypt for user id @var{user}. See @command{gpg}.
+
+@item --local-user @var{user}
+@itemx -u @var{user}
+@opindex local-user
+Use @var{user} as the key to sign with.  See @command{gpg}.
+
+@item --list-archive
+@opindex list-archive
+List the contents of the specified archive.
+
+@item --output @var{file}
+@itemx -o @var{file}
+@opindex output
+Write output to specified file @var{file}.
+
+@item --gpg @var{gpgcmd}
+@opindex gpg
+Use the specified command @var{gpgcmd} instead of @command{gpg}.
+
+@item --gpg-args @var{args}
+@opindex gpg-args
+Pass the specified options to @command{gpg}.
+
+@item --tar @var{tarcmd}
+@opindex tar
+Use the specified command @var{tarcmd} instead of @command{tar}.
+
+@item --tar-args @var{args}
+@opindex tar-args
+Pass the specified options to @command{tar}.
+
+@item --version
+@opindex version
+Print version of the program and exit.
+
+@item --help
+@opindex help
+Display a brief help page and exit.
+
+@end table
+
+@mansect diagnostics
+@noindent
+The program returns 0 if everything was fine, 1 otherwise.
+
+
+@mansect examples
+@ifclear isman
+@noindent
+Some examples:
+
+@end ifclear
+@noindent
+Encrypt the contents of directory @file{mydocs} for user Bob to file
+@file{test1}:
+
+@example
+gpg-zip --encrypt --output test1 --gpg-args  -r Bob mydocs
+@end example
+
+@noindent
+List the contents of archive @file{test1}:
+
+@example
+gpg-zip --list-archive test1
+@end example
+
+
+@mansect see also
+@ifset isman
+@command{gpg}(1), 
+@command{tar}(1), 
+@end ifset
+@include see-also-note.texi
+