GNUPG-1-9-BRANCH gnupg/doc (ChangeLog tools.texi)
cvs user wk
cvs at cvs.gnupg.org
Tue Dec 21 21:42:04 CET 2004
Date: Tuesday, December 21, 2004 @ 21:47:04
Author: wk
Path: /cvs/gnupg/gnupg/doc
Tag: GNUPG-1-9-BRANCH
Modified: ChangeLog tools.texi
(gpg-preset-passphrase): New section.
------------+
ChangeLog | 2
tools.texi | 514 ++++-------------------------------------------------------
2 files changed, 43 insertions(+), 473 deletions(-)
Index: gnupg/doc/ChangeLog
diff -u gnupg/doc/ChangeLog:1.39.2.20 gnupg/doc/ChangeLog:1.39.2.21
--- gnupg/doc/ChangeLog:1.39.2.20 Tue Dec 21 20:05:15 2004
+++ gnupg/doc/ChangeLog Tue Dec 21 21:47:04 2004
@@ -1,5 +1,7 @@
2004-12-21 Werner Koch <wk at g10code.com>
+ * tools.texi (gpg-preset-passphrase): New section.
+
* gnupg-badge-openpgp.eps, gnupg-badge-openpgp.jpg: New
* gnupg.texi: Add a logo.
* sysnotes.texi: New.
Index: gnupg/doc/tools.texi
diff -u gnupg/doc/tools.texi:1.1.2.5 gnupg/doc/tools.texi:1.1.2.6
--- gnupg/doc/tools.texi:1.1.2.5 Tue Dec 21 20:05:15 2004
+++ gnupg/doc/tools.texi Tue Dec 21 21:47:04 2004
@@ -600,498 +600,66 @@
@node gpg-preset-passphrase
@section Put a passphrase into the cache.
-XXXX
-The @command{gpgconf} is a utility to automatically and reasonable
-safely query and modify configuration files in the @file{.gnupg} home
-directory. It is designed not to be invoked manually by the user, but
-automatically by graphical user interfaces (GUI). at footnote{Please note
-that currently no locking is done, so concurrent access should be
-avoided. There are some precautions to avoid corruption with
-concurrent usage, but results may be inconsistent and some changes may
-get lost. The stateless design makes it difficult to provide more
-guarantees.}
-
- at command{gpgconf} provides access to the configuration of one or more
-components of the GnuPG system. These components correspond more or
-less to the programs that exist in the GnuPG framework, like GnuPG,
-GPGSM, DirMngr, etc. But this is not a strict one-to-one
-relationship. Not all configuration options are available through
- at command{gpgconf}. @command{gpgconf} provides a generic and abstract
-method to access the most important configuration options that can
-feasibly be controlled via such a mechanism.
-
- at command{gpgconf} can be used to gather and change the options
-available in each component, and can also provide their default
-values. @command{gpgconf} will give detailed type information that
-can be used to restrict the user's input without making an attempt to
-commit the changes.
-
- at command{gpgconf} provides the backend of a configuration editor. The
-configuration editor would usually be a graphical user interface
-program, that allows to display the current options, their default
-values, and allows the user to make changes to the options. These
-changes can then be made active with @command{gpgconf} again. Such a
-program that uses @command{gpgconf} in this way will be called GUI
-throughout this section.
+The @command{gpg-preset-passphrase} is a utility to seed the internal
+cache of a running @command{gpg-agent} with passphrases. This is mainly
+useful for unatteneded machines, where a pinentry may not be used and
+the passphrases for the to be used keys should be given at machine
+startup.
+
+Passphrases set with this utility don't expire unless the
+ at option{--forget} option is used to explicitly clear them from the cache
+--- or @command{gpg-agent} is either restarted or reloaded (by sending a
+SIGHUP to it). It is necessary to allow this passphrase presetting by
+starting @command{gpg-agent} with the
+ at option{--allow-preset-passphrase}.
@menu
-* Invoking gpgconf:: List of all commands and options.
-* Format conventions:: Formatting conventions relevant for all commands.
-* Listing components:: List all gpgconf components.
-* Listing options:: List all options of a component.
-* Changing options:: Changing options of a component.
+* Invoking gpg-preset-passphrase:: List of all commands and options.
@end menu
- at node Invoking gpgconf
- at subsection Invoking gpgconf
+ at node Invoking gpg-preset-passphrase
+ at subsection List of all commands and options.
-One of the following commands must be given:
+ at noindent
+ at command{gpg-preset-passphrase} is invoked this way:
+
+ at example
+gpg-preset-passphrase [options] [command] @var{keygrip}
+ at end example
+
+ at var{keygrip} is a 40 character string of hexadecimal characters
+identifying the key for which the passphrase should be set or cleared.
+This @emph{keygrip} is listed along with the key when running the
+command: @code{gpgsm --dump-secret-keys}. One of the following commands
+must be given:
@table @gnupgtabopt
- at item --list-components
-List all components. This is the default command used if none is
-specified.
+ at item --preset
+Preset a passphrase. This is what you usually will
+use. @command{gpg-preset-passphrase} will then read the passphrase form
+ at code{stdin}.
- at item --list-options @var{component}
-List all options of the component @var{component}.
+ at item --forget
+Clear the passphrase for the given keygrip from the cache.
- at item --change-options @var{component}
-Change the options of the component @var{component}.
@end table
The following options may be used:
@table @gnupgtabopt
- at c FIXME: Not yet supported.
- at c @item -o @var{file}
- at c @itemx --output @var{file}
- at c Use @var{file} as output file.
-
@item -v
@itemx --verbose
-Outputs additional information while running. Specifically, this
-extends numerical field values by human-readable descriptions.
-
- at c FIXME: Not yet supported.
- at c @item -n
- at c @itemx --dry-run
- at c Do not actually change anything. Useful together with
- at c @code{--change-options} for testing purposes.
-
- at item -r
- at itemx --runtime
-Only used together with @code{--change-options}. If one of the
-modified options can be changed in a running daemon process, signal
-the running daemon to ask it to reparse its configuration file after
-changing.
-
-This means that the changes will take effect at run-time, as far as
-this is possible. Otherwise, they will take effect at the next start
-of the respective backend programs.
- at end table
-
-
- at node Format conventions
- at subsection Format conventions
-
-Some lines in the output of @command{gpgconf} contain a list of
-colon-separated fields. The following conventions apply:
-
- at itemize @bullet
- at item
-The GUI program is required to strip off trailing newline and/or
-carriage return characters from the output.
-
- at item
- at command{gpgconf} will never leave out fields. If a certain version
-provides a certain field, this field will always be present in all
- at command{gpgconf} versions from that time on.
-
- at item
-Future versions of @command{gpgconf} might append fields to the list.
-New fields will always be separated from the previously last field by
-a colon separator. The GUI should be prepared to parse the last field
-it knows about up until a colon or end of line.
-
- at item
-Not all fields are defined under all conditions. You are required to
-ignore the content of undefined fields.
- at end itemize
-
-There are several standard types for the content of a field:
-
- at table @asis
- at item verbatim
-Some fields contain strings that are not escaped in any way. Such
-fields are described to be used @emph{verbatim}. These fields will
-never contain a colon character (for obvious reasons). No de-escaping
-or other formatting is required to use the field content. This is for
-easy parsing of the output, when it is known that the content can
-never contain any special characters.
-
- at item percent-escaped
-Some fields contain strings that are described to be
- at 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
-that has the hexadecimal value @code{XY}. @code{X} and @code{Y} are
-from the set @code{0-9a-f}.
-
- at item localised
-Some fields contain strings that are described to be @emph{localised}.
-Such strings are translated to the active language and formatted in
-the active character set.
-
- at item @w{unsigned number}
-Some fields contain an @emph{unsigned number}. This number will
-always fit into a 32-bit unsigned integer variable. The number may be
-followed by a space, followed by a human readable description of that
-value (if the verbose option is used). You should ignore everything
-in the field that follows the number.
-
- at item @w{signed number}
-Some fields contain a @emph{signed number}. This number will always
-fit into a 32-bit signed integer variable. The number may be followed
-by a space, followed by a human readable description of that value (if
-the verbose option is used). You should ignore everything in the
-field that follows the number.
-
- at item option
-Some fields contain an @emph{option} argument. The format of an
-option argument depends on the type of the option and on some flags:
-
- at table @asis
- at item no argument
-The simplest case is that the option does not take an argument at all
-(@var{type} @code{0}). Then the option argument is an unsigned number
-that specifies how often the option occurs. If the @code{list} flag
-is not set, then the only valid number is @code{1}. Options that do
-not take an argument never have the @code{default} or @code{optional
-arg} flag set.
-
- at item number
-If the option takes a number argument (@var{alt-type} is @code{2} or
- at code{3}), and it can only occur once (@code{list} flag is not set),
-then the option argument is either empty (only allowed if the argument
-is optional), or it is a number. A number is a string that begins
-with an optional minus character, followed by one or more digits. The
-number must fit into an integer variable (unsigned or signed,
-depending on @var{alt-type}).
-
- at item number list
-If the option takes a number argument and it can occur more than once,
-then the option argument is either empty, or it is a comma-separated
-list of numbers as described above.
-
- at item string
-If the option takes a string argument (@var{alt-type} is 1), and it
-can only occur once (@code{list} flag is not set) then the option
-argument is either empty (only allowed if the argument is optional),
-or it starts with a double quote character (@code{"}) followed by a
-percent-escaped string that is the argument value. Note that there is
-only a leading double quote character, no trailing one. The double
-quote character is only needed to be able to differentiate between no
-value and the empty string as value.
-
- at item string list
-If the option takes a number argument and it can occur more than once,
-then the option argument is either empty, or it is a comma-separated
-list of string arguments as described above.
- at end table
- at end table
-
-The active language and character set are currently determined from
-the locale environment of the @command{gpgconf} program.
-
- at c FIXME: Document the active language and active character set. Allow
- at c to change it via the command line?
+ at opindex verbose
+Outputs additional information while running.
-
- at node Listing components
- at subsection Listing components
-
-The command @code{--list-components} will list all components that can
-be configured with @command{gpgconf}. Usually, one component will
-correspond to one GnuPG-related program and contain the options of
-that programs configuration file that can be modified using
- at command{gpgconf}. However, this is not necessarily the case. A
-component might also be a group of selected options from several
-programs, or contain entirely virtual options that have a special
-effect rather than changing exactly one option in one configuration
-file.
-
-A component is a set of configuration options that semantically belong
-together. Furthermore, several changes to a component can be made in
-an atomic way with a single operation. The GUI could for example
-provide a menu with one entry for each component, or a window with one
-tabulator sheet per component.
-
-The command argument @code{--list-components} lists all available
-components, one per line. The format of each line is:
-
- at code{@var{name}:@var{description}}
-
- at table @var
- at item name
-This field contains a name tag of the component. The name tag is used
-to specify the component in all communication with @command{gpgconf}.
-The name tag is to be used @emph{verbatim}. It is thus not in any
-escaped format.
-
- at item description
-The @emph{string} in this field contains a human-readable description
-of the component. It can be displayed to the user of the GUI for
-informational purposes. It is @emph{percent-escaped} and
- at emph{localized}.
- at end table
-
-Example:
- at example
-$ gpgconf --list-components
-gpg:GPG for OpenPGP
-gpg-agent:GPG Agent
-scdaemon:Smartcard Daemon
-gpgsm:GPG for S/MIME
-dirmngr:Directory Manager
- at end example
-
-
- at node Listing options
- at subsection Listing options
-
-Every component contains one or more options. Options may be gathered
-into option groups to allow the GUI to give visual hints to the user
-about which options are related.
-
-The command argument @code{@w{--list-options @var{component}}} lists
-all options (and the groups they belong to) in the component
- at var{component}, one per line. @var{component} must be the string in
-the field @var{name} in the output of the @code{--list-components}
-command.
-
-There is one line for each option and each group. First come all
-options that are not in any group. Then comes a line describing a
-group. Then come all options that belong into each group. Then comes
-the next group and so on. There does not need to be any group (and in
-this case the output will stop after the last non-grouped option).
-
-The format of each line is:
-
- at code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
-
- at table @var
- at item name
-This field contains a name tag for the group or option. The name tag
-is used to specify the group or option in all communication with
- at command{gpgconf}. The name tag is to be used @emph{verbatim}. It is
-thus not in any escaped format.
-
- at item flags
-The flags field contains an @emph{unsigned number}. Its value is the
-OR-wise combination of the following flag values:
-
- at table @code
- at item group (1)
-If this flag is set, this is a line describing a group and not an
-option.
+ at item -P @var{string}
+ at itemx --passphrase @var{string}
+ at opindex passphrase
+Instead of reading the passphrase from @code{stdin}, use the supplied
+ at var{string} as passphrase. Note that this makes the passphrase visible
+for other users.
@end table
-The following flag values are only defined for options (that is, if
-the @code{group} flag is not used).
-
- at table @code
- at item optional arg (2)
-If this flag is set, the argument is optional. This is never set for
- at var{type} @code{0} (none) options.
-
- at item list (4)
-If this flag is set, the option can be given multiple times.
-
- at item runtime (8)
-If this flag is set, the option can be changed at runtime.
-
- at item default (16)
-If this flag is set, a default value is available.
-
- at item default desc (32)
-If this flag is set, a (runtime) default is available. This and the
- at code{default} flag are mutually exclusive.
-
- at item no arg desc (64)
-If this flag is set, and the @code{optional arg} flag is set, then the
-option has a special meaning if no argument is given.
- at end table
-
- at item level
-This field is defined for options and for groups. It contains an
- at emph{unsigned number} that specifies the expert level under which
-this group or option should be displayed. The following expert levels
-are defined for options (they have analogous meaning for groups):
-
- at table @code
- at item basic (0)
-This option should always be offered to the user.
-
- at item advanced (1)
-This option may be offered to advanced users.
-
- at item expert (2)
-This option should only be offered to expert users.
-
- at item invisible (3)
-This option should normally never be displayed, not even to expert
-users.
-
- at item internal (4)
-This option is for internal use only. Ignore it.
- at end table
-
-The level of a group will always be the lowest level of all options it
-contains.
-
- at item description
-This field is defined for options and groups. The @emph{string} in
-this field contains a human-readable description of the option or
-group. It can be displayed to the user of the GUI for informational
-purposes. It is @emph{percent-escaped} and @emph{localized}.
-
- at item type
-This field is only defined for options. It contains an @emph{unsigned
-number} that specifies the type of the option's argument, if any. The
-following types are defined:
-
-Basic types:
-
- at table @code
- at item none (0)
-No argument allowed.
-
- at item string (1)
-An @emph{unformatted string}.
-
- at item int32 (2)
-A @emph{signed number}.
-
- at item uint32 (3)
-An @emph{unsigned number}.
- at end table
-
-Complex types:
-
- at table @code
- at item pathname (32)
-A @emph{string} that describes the pathname of a file. The file does
-not necessarily need to exist.
-
- at item ldap server (33)
-A @emph{string} that describes an LDAP server in the format:
-
- at code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
- at end table
-
-More types will be added in the future. Please see the @var{alt-type}
-field for information on how to cope with unknown types.
-
- at item alt-type
-This field is identical to @var{type}, except that only the types
- at code{0} to @code{31} are allowed. The GUI is expected to present the
-user the option in the format specified by @var{type}. But if the
-argument type @var{type} is not supported by the GUI, it can still
-display the option in the more generic basic type @var{alt-type}. The
-GUI must support all the defined basic types to be able to display all
-options. More basic types may be added in future versions. If the
-GUI encounters a basic type it doesn't support, it should report an
-error and abort the operation.
-
- at item argname
-This field is only defined for options with an argument type
- at var{type} that is not @code{0}. In this case it may contain a
- at emph{percent-escaped} and @emph{localised string} that gives a short
-name for the argument. The field may also be empty, though, in which
-case a short name is not known.
-
- at item default
-This field is defined only for options. Its format is that of an
- at 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.
-
- at 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
-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.
-
- at item value
-This field is defined only for options. Its format is that of an
- at emph{option argument}. If it is empty, then the option is not
-explicitely 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.
- at end table
-
-
- at node Changing options
- at subsection Changing options
-
-The command @w{@code{--change-options @var{component}}} will attempt
-to change the options of the component @var{component} to the
-specified values. @var{component} must be the string in the field
- at var{name} in the output of the @code{--list-components} command. You
-have to provide the options that shall be changed in the following
-format on standard input:
-
- at code{@var{name}:@var{flags}:@var{new-value}}
-
- at table @var
- at item name
-This is the name of the option to change. @var{name} must be the
-string in the field @var{name} in the output of the
- at code{--list-options} command.
-
- at item flags
-The flags field contains an @emph{unsigned number}. Its value is the
-OR-wise combination of the following flag values:
-
- at table @code
- at item default (16)
-If this flag is set, the option is deleted and the default value is
-used instead (if applicable).
- at end table
-
- at item new-value
-The new value for the option. This field is only defined if the
- at code{default} flag is not set. The format is that of an @emph{option
-argument}. If it is empty (or the field is omitted), the default
-argument is used (only allowed if the argument is optional for this
-option). Otherwise, the option will be set to the specified value.
- at end table
-
-Examples:
-
-To set the force option, which is of basic type @code{none (0)}:
-
- at example
-$ echo 'force:0:1' | gpgconf --change-options dirmngr
- at end example
-
-To delete the force option:
-
- at example
-$ echo 'force:16:' | gpgconf --change-options dirmngr
- at end example
-
-The @code{--runtime} option can influence when the changes take
-effect.
-
More information about the Gnupg-commits
mailing list