← Back to branch summary

~ubuntu-branches/ubuntu/precise/gnupg2/precise-updates

« back to all changes in this revision

Viewing changes to doc/gpg.texi

  • Committer: Bazaar Package Importer
  • Author(s): Eric Dorland
  • Date: 2011-02-13 16:06:41 UTC
  • mfrom: (1.2.4 upstream)
  • mto: This revision was merged to the branch mainline in revision 17.
  • Revision ID: james.westby@ubuntu.com-20110213160641-364ll4kdkhft0wq3
Tags: 2.0.17-1
http://bugs.debian.org/584316
http://bugs.debian.org/603985
http://bugs.debian.org/603983
http://bugs.debian.org/603984
http://bugs.debian.org/579006
* New upstream release. (Closes: #584316, #603985, #603983, #603984)
* debian/patches/02-encode-s2k.diff,
  debian/patches/03-gpgsm-realloc.diff, debian/patches/series: Drop now
  unneeded security patches.
* debian/rules, debian/patches/01-gnupg2-rename.diff,
  debian/gnupg2.info, debian/gnupg2.install: No need to rename the info
  file anymore.
* debian/patches/01-gnupg2-rename.diff: Rename the autoconf package for
  better renaming of pkg directories. (Closes: #579006)
* debian/control, debian/compat: Upgrade to debhelper level 8.
* debian/control:
  - Upgrade Standards-Version to 3.9.1.
  - Update Build-Depends versions for the latest release.
* debian/gnupg2.install: Add the applygnupgdefaults command. (Closes:
  #567537)
* debian/gnupg2.docs: doc/faq.html no longer exists.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gpg.texi
1
1
@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
2
 
@c               2008, 2009 Free Software Foundation, Inc.
 
2
@c               2008, 2009, 2010 Free Software Foundation, Inc.
3
3
@c This is part of the GnuPG manual.
4
4
@c For copying conditions, see the file gnupg.texi.
5
5
 
 
6
@c Note that we use this texinfo file for all versions of GnuPG: 1.4.x,
 
7
@c 2.0 and 2.1.  The macro "gpgone" controls parts which are only valid
 
8
@c for GnuPG 1.4, the macro "gpgtwoone" controls parts which are only
 
9
@c valid for GnupG 2.1 and later.
 
10
 
6
11
@node Invoking GPG
7
12
@chapter Invoking GPG
8
13
@cindex GPG command options
68
73
 
69
74
@ifset gpgone
70
75
This is the standalone version of @command{gpg}.  For desktop use you
71
 
should consider using @command{gpg2}.
 
76
should consider using @command{gpg2} @footnote{On some platforms gpg2 is
 
77
installed under the name @command{gpg}}.
72
78
@end ifset
73
79
 
74
80
@ifclear gpgone
75
81
In contrast to the standalone version @command{gpg}, which is more
76
 
suited for server and embedded platforms, this version is installed
77
 
under the name @command{gpg2} and more targeted to the desktop as it
78
 
requires several other modules to be installed.  The standalone version
79
 
will be kept maintained and it is possible to install both versions on
80
 
the same system.  If you need to use different configuration files, you
81
 
should make use of something like @file{gpg.conf-2} instead of just
82
 
@file{gpg.conf}.
 
82
suited for server and embedded platforms, this version is commonly
 
83
installed under the name @command{gpg2} and more targeted to the desktop
 
84
as it requires several other modules to be installed.  The standalone
 
85
version will be kept maintained and it is possible to install both
 
86
versions on the same system.  If you need to use different configuration
 
87
files, you should make use of something like @file{gpg.conf-2} instead
 
88
of just @file{gpg.conf}.
83
89
@end ifclear
84
90
 
85
91
@manpause
415
421
command has the special property to render the secret part of the
416
422
primary key useless; this is a GNU extension to OpenPGP and other
417
423
implementations can not be expected to successfully import such a key.
 
424
@ifclear gpgtwoone
418
425
See the option @option{--simple-sk-checksum} if you want to import such
419
426
an exported key with an older OpenPGP implementation.
 
427
@end ifclear
420
428
 
421
429
@item --import
422
430
@itemx --fast-import
527
535
With the second form (or a deprecated "*" as algo) digests for all
528
536
available algorithms are printed.
529
537
 
530
 
@item --gen-random @code{0|1|2}
 
538
@item --gen-random @code{0|1|2} @code{count}
531
539
@opindex gen-random
532
 
Emit @var{count} random bytes of the given quality level. If count is
533
 
not given or zero, an endless sequence of random bytes will be emitted.
534
 
PLEASE, don't use this command unless you know what you are doing; it
535
 
may remove precious entropy from the system!
 
540
Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
 
541
@var{count} is not given or zero, an endless sequence of random bytes
 
542
will be emitted.  If used with @option{--armor} the output will be
 
543
base64 encoded.  PLEASE, don't use this command unless you know what
 
544
you are doing; it may remove precious entropy from the system!
536
545
 
537
546
@item --gen-prime @code{mode}  @code{bits}
538
547
@opindex gen-prime
845
854
 
846
855
@c man:.RS
847
856
The listing shows you the key with its secondary keys and all user
848
 
ids. Selected keys or user ids are indicated by an asterisk. The trust
 
857
ids.  The primary user id is indicated by a dot, and selected keys or
 
858
user ids are indicated by an asterisk.  The trust
849
859
value is displayed with the primary key: the first is the assigned owner
850
860
trust and the second is the calculated trust value. Letters are used for
851
861
the values:
888
898
non-exportable. This is a shortcut version of the subcommand "lsign"
889
899
from @option{--edit-key}.
890
900
 
 
901
@ifclear gpgone
 
902
@item --passwd @var{user_id}
 
903
@opindex passwd
 
904
Change the passphrase of the secret key belonging to the certificate
 
905
specified as @var{user_id}.  This is a shortcut for the sub-command
 
906
@code{passwd} of the edit key menu.
 
907
@end ifclear
891
908
 
892
909
@end table
893
910
 
901
918
@node GPG Options
902
919
@section Option Summary
903
920
 
904
 
@command{@gpgname} comes features a bunch of options to control the exact
 
921
@command{@gpgname} features a bunch of options to control the exact
905
922
behaviour and to change the default configuration.
906
923
 
907
924
@menu
1012
1029
@item show-photos
1013
1030
@opindex list-options:show-photos
1014
1031
Causes @option{--list-keys}, @option{--list-sigs},
1015
 
@option{--list-public-keys}, and @option{--list-secret-keys} to display
1016
 
any photo IDs attached to the key.  Defaults to no. See also
1017
 
@option{--photo-viewer}.
 
1032
@option{--list-public-keys}, and @option{--list-secret-keys} to
 
1033
display any photo IDs attached to the key.  Defaults to no. See also
 
1034
@option{--photo-viewer}.  Does not work with @option{--with-colons}:
 
1035
see @option{--attribute-fd} for the appropriate way to get photo data
 
1036
for scripts and other frontends.
1018
1037
 
1019
1038
@item show-policy-urls
1020
1039
@opindex list-options:show-policy-urls
1124
1143
Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
1125
1144
for the key fingerprint, "%t" for the extension of the image type
1126
1145
(e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
 
1146
"%v" for the single-character calculated validity of the image being
 
1147
viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
 
1148
"full"),
1127
1149
and "%%" for an actual percent sign. If neither %i or %I are present,
1128
1150
then the photo will be supplied to the viewer on standard input.
1129
1151
 
1522
1544
ldaps).  Defaults to on.
1523
1545
 
1524
1546
@item ca-cert-file
1525
 
Provide a certificate file to override the system default.  Only
 
1547
Provide a certificate store to override the system default.  Only
1526
1548
necessary if check-cert is enabled, and the keyserver is using a
1527
1549
certificate that is not present in a system default certificate list.
1528
1550
 
 
1551
Note that depending on the SSL library that the keyserver helper is
 
1552
built with, this may actually be a directory or a file.
1529
1553
@end table
1530
1554
 
1531
1555
@item --completes-needed @code{n}
1539
1563
@item --max-cert-depth @code{n}
1540
1564
Maximum depth of a certification chain (default is 5).
1541
1565
 
 
1566
@ifclear gpgtwoone
1542
1567
@item --simple-sk-checksum
1543
1568
Secret keys are integrity protected by using a SHA-1 checksum. This
1544
1569
method is part of the upcoming enhanced OpenPGP specification but
1549
1574
the secret key is encrypted - the simplest way to make this happen is
1550
1575
to change the passphrase on the key (even changing it to the same
1551
1576
value is acceptable).
 
1577
@end ifclear
1552
1578
 
1553
1579
@item --no-sig-cache
1554
1580
Do not cache the verification status of key signatures.
1758
1784
Use @var{name} as the key to sign with. Note that this option overrides
1759
1785
@option{--default-key}.
1760
1786
 
 
1787
@ifset gpgtwoone
 
1788
@item --try-secret-key @var{name}
 
1789
@opindex try-secret-key
 
1790
For hidden recipients GPG needs to know the keys to use for trial
 
1791
decryption.  The key set with @option{--default-key} is always tried
 
1792
first, but this is often not sufficient.  This option allows to set more
 
1793
keys to be used for trial decryption.  Although any valid user-id
 
1794
specification may be used for @var{name} it makes sense to use at least
 
1795
the long keyid to avoid ambiguities.  Note that gpg-agent might pop up a
 
1796
pinentry for a lot keys to do the trial decryption.  If you want to stop
 
1797
all further trial decryption you may use close-window button instead of
 
1798
the cancel button.
 
1799
@end ifset
 
1800
 
1761
1801
@item --try-all-secrets
 
1802
@opindex try-all-secrets
1762
1803
Don't look at the key ID as stored in the message but try all secret
1763
1804
keys in turn to find the right decryption key. This option forces the
1764
1805
behaviour as used by anonymous recipients (created by using
1765
 
@option{--throw-keyids}) and might come handy in case where an encrypted
1766
 
message contains a bogus key ID.
1767
 
 
1768
 
 
1769
 
 
 
1806
@option{--throw-keyids} or @option{--hidden-recipient}) and might come
 
1807
handy in case where an encrypted message contains a bogus key ID.
 
1808
 
 
1809
@item --skip-hidden-recipients
 
1810
@itemx --no-skip-hidden-recipients
 
1811
@opindex skip-hidden-recipients
 
1812
@opindex no-skip-hidden-recipients
 
1813
During decryption skip all anonymous recipients.  This option helps in
 
1814
the case that people use the hidden recipients feature to hide there
 
1815
own encrypt-to key from others.  If oneself has many secret keys this
 
1816
may lead to a major annoyance because all keys are tried in turn to
 
1817
decrypt soemthing which was not really intended for it.  The drawback
 
1818
of this option is that it is currently not possible to decrypt a
 
1819
message which includes real anonymous recipients.
1770
1820
 
1771
1821
 
1772
1822
@end table
1863
1913
Include designated revoker information that was marked as
1864
1914
"sensitive". Defaults to no.
1865
1915
 
 
1916
@c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
 
1917
@c export-reset-subkey-passwd hack is not anymore justified.  Such use
 
1918
@c cases need to be implemented using a specialized secret key export
 
1919
@c tool.
 
1920
@ifclear gpgtwoone
1866
1921
@item export-reset-subkey-passwd
1867
1922
When using the @option{--export-secret-subkeys} command, this option resets
1868
1923
the passphrases for all exported subkeys to empty. This is useful
1869
1924
when the exported subkey is to be used on an unattended machine where
1870
1925
a passphrase doesn't necessarily make sense. Defaults to no.
 
1926
@end ifclear
1871
1927
 
1872
1928
@item export-clean
1873
1929
Compact (remove all signatures from) user IDs on the key being
1908
1964
Same as the command @option{--fingerprint} but changes only the format
1909
1965
of the output and may be used together with another command.
1910
1966
 
 
1967
@ifset gpgtwoone
 
1968
@item --with-keygrip
 
1969
@opindex with-keygrip
 
1970
Include the keygrip in the key listings.
 
1971
@end ifset
1911
1972
 
1912
1973
@end table
1913
1974
 
1943
2004
OpenPGP states that an implementation should generate v4 signatures
1944
2005
but PGP versions 5 through 7 only recognize v4 signatures on key
1945
2006
material. This option forces v3 signatures for signatures on data.
1946
 
Note that this option implies @option{--ask-sig-expire},
 
2007
Note that this option implies @option{--no-ask-sig-expire}, and unsets
1947
2008
@option{--sig-policy-url}, @option{--sig-notation}, and
1948
2009
@option{--sig-keyserver-url}, as these features cannot be used with v3
1949
2010
signatures.  @option{--no-force-v3-sigs} disables this option.
 
2011
Defaults to no.
1950
2012
 
1951
2013
@item --force-v4-certs
1952
2014
@itemx --no-force-v4-certs
1982
2044
preferences, as GPG will only select an algorithm that is usable by
1983
2045
all recipients.  The most highly ranked digest algorithm in this list
1984
2046
is also used when signing without encryption
1985
 
(e.g. @option{--clearsign} or @option{--sign}). The default value is
1986
 
SHA-1.
 
2047
(e.g. @option{--clearsign} or @option{--sign}).
1987
2048
 
1988
2049
@item --personal-compress-preferences @code{string}
1989
2050
Set the list of personal compression preferences to @code{string}.
2176
2237
Note that this option is only available on some system.
2177
2238
@end ifset
2178
2239
 
 
2240
@item --faked-system-time @var{epoch}
 
2241
@opindex faked-system-time
 
2242
This option is only useful for testing; it sets the system time back or
 
2243
forth to @var{epoch} which is the number of seconds elapsed since the year
 
2244
1970.  Alternatively @var{epoch} may be given as a full ISO time string
 
2245
(e.g. "20070924T154812").
 
2246
 
2179
2247
@item --enable-progress-filter
2180
2248
Enable certain PROGRESS status outputs. This option allows frontends
2181
2249
to display a progress indicator while gpg is processing larger files.
2513
2581
When making a data signature, prompt for an expiration time. If this
2514
2582
option is not specified, the expiration time set via
2515
2583
@option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
2516
 
disables this option. Note that by default, @option{--force-v3-sigs} is
2517
 
set which also disables this option. If you want signature expiration,
2518
 
you must set @option{--no-force-v3-sigs} as well as turning
2519
 
@option{--ask-sig-expire} on.
 
2584
disables this option.
2520
2585
 
2521
2586
@item --default-sig-expire
2522
2587
The default expiration time to use for signature expiration. Valid
2880
2945
@mansect bugs
2881
2946
@chapheading BUGS
2882
2947
 
2883
 
On many systems this program should be installed as setuid(root). This
 
2948
On older systems this program should be installed as setuid(root). This
2884
2949
is necessary to lock memory pages. Locking memory pages prevents the
2885
2950
operating system from writing memory pages (which may contain
2886
2951
passphrases or other sensitive material) to disk. If you get no
2895
2960
to protect the saved memory, passphrases or other sensitive material
2896
2961
may be recoverable from it later.
2897
2962
 
 
2963
Before you report a bug you should first search the mailing list
 
2964
archives for similar problems and second check whether such a bug has
 
2965
already been reported to our bug tracker at http://bugs.gnupg.org .
 
2966
 
2898
2967
@mansect see also
2899
2968
@ifset isman
2900
2969
@command{gpgv}(1),