security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2024-06-09 23:39:51 +02:00
Code Activity

doc: Final update from master (gnupg 2.1)

Browse Source 
* doc/Makefile.am (sources_from_trunk): Remove.
(update-source): Make it a dummy.
* doc/gpg.texi: Update.
* doc/yat2m.c: Update.
--

Maintaining 3 versions in of the gpg manual in one file is getting
more complicated with 2.1.  Thus we stop this now and keep the manual
for 1.4 separate.
This commit is contained in:
Werner Koch 2014-09-29 11:11:30 +02:00
parent ad30b2a4ae
commit 3209f270d2
3 changed files with 218 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/Makefile.am
View File

@ -26,10 +26,6 @@ EXTRA_DIST = DETAILS FAQ \
myman_sources = gpg.texi gpgv.texi
myman_pages = gpg.1 gpgv.1
sources_from_trunk = $(myman_sources) \
opt-homedir.texi specify-user-id.texi see-also-note.texi
info_TEXINFOS = gnupg1.texi
man_MANS = $(myman_pages) gnupg.7 gpg-zip.1
@ -83,12 +79,6 @@ dist-hook:
@if test "`wc -c < gpg.1`" -lt 200; then \
echo 'ERROR: dummy man page'; false; fi
# Copy shared files from the master branch. We keep the texinfo files
# all in master so that we need to modify only one source. Macros are
# used to customize them for a specific version.
update-source:
@set -e; cd $(srcdir); \
for i in $(sources_from_trunk) yat2m.c ; do \
echo "updating from master:doc/$$i" >&2 ; \
git show master:doc/$$i >$$i ; \
done
@echo Not anymore used - we now keep docs for 1.x separate
@echo from GnuPG-2.

146
doc/gpg.texi
View File

@ -1,4 +1,4 @@
@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
@c 2008, 2009, 2010 Free Software Foundation, Inc.
@c This is part of the GnuPG manual.
@c For copying conditions, see the file gnupg.texi.
@ -14,6 +14,19 @@
@cindex command options
@cindex options, GPG command
@c Begin algorithm defaults
@ifclear gpgtwoone
@set DEFSYMENCALGO CAST5
@end ifclear
@ifset gpgtwoone
@set DEFSYMENCALGO AES128
@end ifset
@c End algorithm defaults
@c Begin GnuPG 1.x specific stuff
@ifset gpgone
@macro gpgname
@ -217,7 +230,7 @@ decrypted via a secret key or a passphrase).
@itemx -c
@opindex symmetric
Encrypt with a symmetric cipher using a passphrase. The default
symmetric cipher used is CAST5, but may be chosen with the
symmetric cipher used is @value{DEFSYMENCALGO}, but may be chosen with the
@option{--cipher-algo} option. This option may be combined with
@option{--sign} (for a signed and symmetrically encrypted message),
@option{--encrypt} (for a message that may be decrypted via a secret key
@ -408,8 +421,8 @@ removed first. In batch mode the key must be specified by fingerprint.
@opindex export
Either export all keys from all keyrings (default keyrings and those
registered via option @option{--keyring}), or if at least one name is given,
those of the given name. The new keyring is written to STDOUT or to the
file given with option @option{--output}. Use together with
those of the given name. The exported keys are written to STDOUT or to the
file given with option @option{--output}. Use together with
@option{--armor} to mail those keys.
@item --send-keys @code{key IDs}
@ -424,14 +437,30 @@ or changed by you. If no key IDs are given, @command{gpg} does nothing.
@itemx --export-secret-subkeys
@opindex export-secret-keys
@opindex export-secret-subkeys
Same as @option{--export}, but exports the secret keys instead. This is
normally not very useful and a security risk. The second form of the
command has the special property to render the secret part of the
primary key useless; this is a GNU extension to OpenPGP and other
implementations can not be expected to successfully import such a key.
Same as @option{--export}, but exports the secret keys instead. The
exported keys are written to STDOUT or to the file given with option
@option{--output}. This command is often used along with the option
@option{--armor} to allow easy printing of the key for paper backup;
however the external tool @command{paperkey} does a better job for
creating backups on paper. Note that exporting a secret key can be a
security risk if the exported keys are send over an insecure channel.
The second form of the command has the special property to render the
secret part of the primary key useless; this is a GNU extension to
OpenPGP and other implementations can not be expected to successfully
import such a key. Its intended use is to generated a full key with
an additional signing subkey on a dedicated machine and then using
this command to export the key without the primary key to the main
machine.
@ifset gpgtwoone
GnuPG may ask you to enter the passphrase for the key. This is
required because the internal protection method of the secret key is
different from the one specified by the OpenPGP protocol.
@end ifset
@ifclear gpgtwoone
See the option @option{--simple-sk-checksum} if you want to import such
an exported key with an older OpenPGP implementation.
See the option @option{--simple-sk-checksum} if you want to import an
exported secret key into ancient OpenPGP implementations.
@end ifclear
@item --import
@ -576,14 +605,36 @@ This section explains the main commands for key management
@table @gnupgtabopt
@ifset gpgtwoone
@item --quick-gen-key @code{user-id}
@opindex quick-gen-key
This is simple command to generate a standard key with one user id.
In contrast to @option{--gen-key} the key is generated directly
without the need to answer a bunch of prompts. Unless the option
@option{--yes} is given, the key creation will be canceled if the
given user id already exists in the key ring.
If invoked directly on the console without any special options an
answer to a ``Continue?'' style confirmation prompt is required. In
case the user id already exists in the key ring a second prompt to
force the creation of the key will show up.
@end ifset
@item --gen-key
@opindex gen-key
Generate a new key pair. This command is normally only used
interactively.
Generate a new key pair using teh current default parameters. This is
the standard command to create a new key.
There is an experimental feature which allows you to create keys in
batch mode. See the file @file{doc/DETAILS} in the source distribution
on how to use this.
@ifset gpgtwoone
@item --full-gen-key
@opindex gen-key
Generate a new key pair with dialogs for all options. This is an
extended version of @option{--gen-key}.
@end ifset
There is also a feature which allows you to create keys in batch
mode. See the the manual section ``Unattended key generation'' on how
to use this.
@item --gen-revoke @code{name}
@opindex gen-revoke
@ -916,12 +967,14 @@ interaction. The @code{fpr} must be the verified primary fingerprint
of a key in the local keyring. If no @code{names} are given, all
useful user ids are signed; with given [@code{names}] only useful user
ids matching one of theses names are signed. The command
@option{--quick-lsign-key} marks the signatures as non-exportable.
@option{--quick-lsign-key} marks the signatures as non-exportable. If
such a non-exportable signature already exists the
@option{--quick-sign-key} turns it into a exportable signature.
This command uses reasonable defaults and thus does not provide the
full flexibility of the "sign" subcommand from @option{--edit-key}.
Its intended use to help unattended signing using a list of verified
fingerprints.
Its intended use is to help unattended key signing by utilizing a list
of verified fingerprints.
@end ifset
@ifclear gpgone
@ -1063,6 +1116,13 @@ give the opposite meaning. The options are:
see @option{--attribute-fd} for the appropriate way to get photo data
for scripts and other frontends.
@item show-usage
@opindex list-options:show-usage
Show usage information for keys and subkeys in the standard key
listing. This is a list of letters indicating the allowed usage for a
key (@code{E}=encryption, @code{S}=signing, @code{C}=certification,
@code{A}=authentication). Defaults to no.
@item show-policy-urls
@opindex list-options:show-policy-urls
Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
@ -1226,7 +1286,13 @@ use the specified keyring alone, use @option{--keyring} along with
@item --secret-keyring @code{file}
@opindex secret-keyring
@ifset gpgtwoone
This is an obsolete option and ignored. All secret keys are stored in
the @file{private-keys-v1.d} directory below the GnuPG home directory.
@end ifset
@ifclear gpgtwoone
Same as @option{--keyring} but for the secret keyrings.
@end ifclear
@item --primary-keyring @code{file}
@opindex primary-keyring
@ -1436,7 +1502,7 @@ Set what trust model GnuPG should follow. The models are:
@item classic
@opindex trust-mode:classic
This is the standard Web of Trust as used in PGP 2.x and earlier.
This is the standard Web of Trust as introduced by PGP 2.
@item direct
@opindex trust-mode:direct
@ -2232,7 +2298,7 @@ to consider (e.g. @option{--symmetric}).
@item --s2k-cipher-algo @code{name}
@opindex s2k-cipher-algo
Use @code{name} as the cipher algorithm used to protect secret keys.
The default cipher is CAST5. This cipher is also used for
The default cipher is @value{DEFSYMENCALGO}. This cipher is also used for
conventional encryption if @option{--personal-cipher-preferences} and
@option{--cipher-algo} is not given.
@ -2302,9 +2368,11 @@ behavior. Note that this is currently the same thing as
Reset all packet, cipher and digest options to strict RFC-2440
behavior.
@ifclear gpgtowone
@item --rfc1991
@opindex rfc1991
Try to be more RFC-1991 (PGP 2.x) compliant.
Try to be more RFC-1991 (PGP 2.x) compliant. This option is
deprecated will be removed in GnuPG 2.1.
@item --pgp2
@opindex pgp2
@ -2314,14 +2382,24 @@ a message that PGP 2.x will not be able to handle. Note that `PGP
2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x
available, but the MIT release is a good common baseline.
This option implies @option{--rfc1991 --disable-mdc
--no-force-v4-certs --escape-from-lines --force-v3-sigs
This option implies
@ifset gpgone
@option{--rfc1991 --disable-mdc --no-force-v4-certs
--escape-from-lines --force-v3-sigs
--cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}.
@end ifset
@ifclear gpgone
--allow-weak-digest-algos
@option{--rfc1991 --disable-mdc --no-force-v4-certs
--escape-from-lines --force-v3-sigs --allow-weak-digest-algos
--cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}.
@end ifclear
It also disables @option{--textmode} when encrypting.
This option is deprecated will be removed in GnuPG 2.1. The reason
for dropping PGP-2 support is that the PGP 2 format is not anymore
considered safe (for example due to the use of the broken MD5 algorithm).
Note that the decryption of PGP-2 created messages will continue to work.
@end ifclear
--cipher-algo IDEA --digest-algo
MD5--compress-algo ZIP}. It also disables @option{--textmode} when
encrypting.
@item --pgp6
@opindex pgp6
@ -3086,6 +3164,16 @@ files; They all live in in the current home directory (@pxref{option
@item ~/.gnupg/secring.gpg.lock
The lock file for the secret keyring.
@item ~/.gnupg/openpgp-revocs.d/
This is the directory where gpg stores pre-generated revocation
certificates. The file name corresponds to the OpenPGP fingerprint of
the respective key. It is suggested to backup those certificates and
if the primary private key is not stored on the disk to move them to
an external storage device. Anyone who can access theses files is
able to revoke the corresponding key. You may want to print them out.
You should backup all files in this directory and take care to keep
this backup closed away.
@item /usr[/local]/share/gnupg/options.skel
The skeleton options file.
@ -3435,7 +3523,7 @@ sense. Although OpenPGP works with time intervals, GnuPG uses an
absolute value internally and thus the last year we can represent is
2105.
@item Ceation-Date: @var{iso-date}
@item Creation-Date: @var{iso-date}
Set the creation date of the key as stored in the key information and
which is also part of the fingerprint calculation. Either a date like
"1986-04-26" or a full timestamp like "19860426T042640" may be used.

102
doc/yat2m.c
View File

@ -87,6 +87,10 @@
detects the number of white spaces in front of an @item and remove
this number of spaces from all following lines until a new @item
is found or there are less spaces than for the last @item.
Note that @* does only work correctly if used at the end of an
input line.
*/
#include <stdio.h>
@ -136,6 +140,9 @@ typedef struct macro_s *macro_t;
/* List of all defined macros. */
static macro_t macrolist;
/* List of variables set by @set. */
static macro_t variablelist;
/* List of global macro names. The value part is not used. */
static macro_t predefinedmacrolist;
@ -375,8 +382,44 @@ set_macro (const char *macroname, char *macrovalue)
}
/* Return true if the macro NAME is set, i.e. not the empty string and
not evaluating to 0. */
/* Create or update a variable with name and value given in NAMEANDVALUE. */
static void
set_variable (char *nameandvalue)
{
macro_t m;
const char *value;
char *p;
for (p = nameandvalue; *p && *p != ' ' && *p != '\t'; p++)
;
if (!*p)
value = "";
else
{
*p++ = 0;
while (*p == ' ' || *p == '\t')
p++;
value = p;
}
for (m=variablelist; m; m = m->next)
if (!strcmp (m->name, nameandvalue))
break;
if (m)
free (m->value);
else
{
m = xcalloc (1, sizeof *m + strlen (nameandvalue));
strcpy (m->name, nameandvalue);
m->next = variablelist;
variablelist = m;
}
m->value = xstrdup (value);
}
/* Return true if the macro or variable NAME is set, i.e. not the
empty string and not evaluating to 0. */
static int
macro_set_p (const char *name)
{
@ -385,6 +428,10 @@ macro_set_p (const char *name)
for (m = macrolist; m ; m = m->next)
if (!strcmp (m->name, name))
break;
if (!m)
for (m = variablelist; m ; m = m->next)
if (!strcmp (m->name, name))
break;
if (!m || !m->value || !*m->value)
return 0;
if ((*m->value & 0x80) || !isdigit (*m->value))
@ -664,8 +711,11 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
{ "table", 3 },
{ "itemize", 3 },
{ "bullet", 0, "* " },
{ "*", 0, "\n.br"},
{ "/", 0 },
{ "end", 4 },
{ "quotation",1, ".RS\n\\fB" },
{ "value", 8 },
{ NULL }
};
size_t n;
@ -741,11 +791,46 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
case 7:
ignore_args = 1;
break;
case 8:
ignore_args = 1;
if (*rest != '{')
{
err ("opening brace for command '%s' missing", command);
return len;
}
else
{
/* Find closing brace. */
for (s=rest+1, n=1; *s && n < len; s++, n++)
if (*s == '}')
break;
if (*s != '}')
{
err ("closing brace for command '%s' not found", command);
return len;
}
else
{
size_t len = s - (rest + 1);
macro_t m;
for (m = variablelist; m; m = m->next)
if (strlen (m->name) == len
&&!strncmp (m->name, rest+1, len))
break;
if (m)
fputs (m->value, fp);
else
inf ("texinfo variable '%.*s' is not set",
(int)len, rest+1);
}
}
break;
default:
break;
}
}
else
else /* macro */
{
macro_t m;
@ -1215,6 +1300,10 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
macrovalue = xmalloc ((macrovaluesize = 1024));
macrovalueused = 0;
}
else if (n == 4 && !memcmp (line, "@set", 4))
{
set_variable (p);
}
else if (n == 8 && !memcmp (line, "@manpage", 8))
{
free (*section_name);
@ -1325,6 +1414,13 @@ top_parse_file (const char *fname, FILE *fp)
free (macrolist);
macrolist = next;
}
while (variablelist)
{
macro_t next = variablelist->next;
free (variablelist->value);
free (variablelist);
variablelist = next;
}
for (m=predefinedmacrolist; m; m = m->next)
set_macro (m->name, xstrdup ("1"));
cond_is_active = 1;