gpg: More fix of get_best_pubkey_byname.
[gnupg.git] / doc / gpgv.texi
1 @c Copyright (C) 2004 Free Software Foundation, Inc.
2 @c This is part of the GnuPG manual.
3 @c For copying conditions, see the file GnuPG.texi.
4
5 @c
6 @c This is included by tools.texi.
7 @c
8
9 @include defs.inc
10
11 @c Begin standard stuff
12 @ifclear gpgtwohack
13 @manpage gpgv.1
14 @node gpgv
15 @section Verify OpenPGP signatures
16 @ifset manverb
17 .B gpgv
18 \- Verify OpenPGP signatures
19 @end ifset
20
21 @mansect synopsis
22 @ifset manverb
23 .B  gpgv
24 .RI [ options ]
25 .I signed_files
26 @end ifset
27 @end ifclear
28 @c End standard stuff
29
30 @c Begin gpg2 hack stuff
31 @ifset gpgtwohack
32 @manpage gpgv2.1
33 @node gpgv
34 @section Verify OpenPGP signatures
35 @ifset manverb
36 .B gpgv2
37 \- Verify OpenPGP signatures
38 @end ifset
39
40 @mansect synopsis
41 @ifset manverb
42 .B  gpgv2
43 .RI [ options ]
44 .I signed_files
45 @end ifset
46 @end ifset
47 @c End gpg2 hack stuff
48
49 @mansect description
50 @code{@gpgvname} is an OpenPGP signature verification tool.
51
52 This program is actually a stripped-down version of @code{gpg} which is
53 only able to check signatures. It is somewhat smaller than the fully-blown
54 @code{gpg} and uses a different (and simpler) way to check that
55 the public keys used to make the signature are valid. There are
56 no configuration files and only a few options are implemented.
57
58 @code{@gpgvname} assumes that all keys in the keyring are trustworthy.
59 That does also mean that it does not check for expired or revoked
60 keys.
61
62 If no @code{--keyring} option is given, @code{gpgv} looks for a
63 ``default'' keyring named @file{trustedkeys.kbx} (preferred) or
64 @file{trustedkeys.gpg} in the home directory of GnuPG, either the
65 default home directory or the one set by the @code{--homedir} option
66 or the @code{GNUPGHOME} environment variable.  If any @code{--keyring}
67 option is used, @code{gpgv} will not look for the default keyring. The
68 @code{--keyring} option may be used multiple times and all specified
69 keyrings will be used together.
70
71 @noindent
72 @mansect options
73 @code{@gpgvname} recognizes these options:
74
75 @table @gnupgtabopt
76
77 @item --verbose
78 @itemx -v
79 @opindex verbose
80 Gives more information during processing. If used
81 twice, the input data is listed in detail.
82
83 @item --quiet
84 @itemx -q
85 @opindex quiet
86 Try to be as quiet as possible.
87
88 @item --keyring @var{file}
89 @opindex keyring
90 Add @var{file} to the list of keyrings.
91 If @var{file} begins with a tilde and a slash, these
92 are replaced by the HOME directory. If the filename
93 does not contain a slash, it is assumed to be in the
94 home-directory ("~/.gnupg" if --homedir is not used).
95
96 @item --output @var{file}
97 @itemx -o @var{file}
98 @opindex output
99 Write output to @var{file}; to write to stdout use @code{-}.  This
100 option can be used to get the signed text from a cleartext or binary
101 signature; it also works for detached signatures, but in that case
102 this option is in general not useful.  Note that an existing file will
103 be overwritten.
104
105
106 @item --status-fd @var{n}
107 @opindex status-fd
108 Write special status strings to the file descriptor @var{n}.  See the
109 file DETAILS in the documentation for a listing of them.
110
111 @item --logger-fd @code{n}
112 @opindex logger-fd
113 Write log output to file descriptor @code{n} and not to stderr.
114
115 @item --log-file @code{file}
116 @opindex log-file
117 Same as @option{--logger-fd}, except the logger data is written to
118 file @code{file}.  Use @file{socket://} to log to socket.
119
120 @item --ignore-time-conflict
121 @opindex ignore-time-conflict
122 GnuPG normally checks that the timestamps associated with keys and
123 signatures have plausible values. However, sometimes a signature seems to
124 be older than the key due to clock problems. This option turns these
125 checks into warnings.
126
127 @include opt-homedir.texi
128
129 @item --weak-digest @code{name}
130 @opindex weak-digest
131 Treat the specified digest algorithm as weak.  Signatures made over
132 weak digests algorithms are normally rejected. This option can be
133 supplied multiple times if multiple algorithms should be considered
134 weak.  MD5 is always considered weak, and does not need to be listed
135 explicitly.
136
137 @item --enable-special-filenames
138 @opindex enable-special-filenames
139 This option enables a mode in which filenames of the form
140 @file{-&n}, where n is a non-negative decimal number,
141 refer to the file descriptor n and not to a file with that name.
142
143 @end table
144
145 @mansect return value
146
147 The program returns 0 if everything is fine, 1 if at least
148 one signature was bad, and other error codes for fatal errors.
149
150 @mansect examples
151 @subsection Examples
152
153 @table @asis
154
155 @item @gpgvname @code{pgpfile}
156 @itemx @gpgvname @code{sigfile} [@code{datafile}]
157 Verify the signature of the file. The second form is used for detached
158 signatures, where @code{sigfile} is the detached signature (either
159 ASCII-armored or binary) and @code{datafile} contains the signed data;
160 if @code{datafile} is "-" the signed data is expected on
161 @code{stdin}; if @code{datafile} is not given the name of the file
162 holding the signed data is constructed by cutting off the extension
163 (".asc", ".sig" or ".sign") from @code{sigfile}.
164
165 @end table
166
167 @mansect environment
168 @subsection Environment
169
170 @table @asis
171
172 @item HOME
173 Used to locate the default home directory.
174
175 @item GNUPGHOME
176 If set directory used instead of "~/.gnupg".
177
178 @end table
179
180 @mansect files
181 @subsection FILES
182
183 @table @asis
184
185 @item ~/.gnupg/trustedkeys.gpg
186 The default keyring with the allowed keys.
187
188 @end table
189
190 @mansect see also
191 @command{gpg}(1)
192 @include see-also-note.texi
193