doc/man/pgpverify.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "PGPVERIFY 1"
 132 .TH PGPVERIFY 1 "2008-04-06" "INN 2.4.4" "InterNetNews Documentation"
 133 .SH "NAME"
 134 pgpverify \- Cryptographically verify Usenet control messages
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBpgpverify\fR [\fB\-test\fR] < \fImessage\fR
 138 .SH "DESCRIPTION"
 139 .IX Header "DESCRIPTION"
 140 The \fBpgpverify\fR program reads (on standard input) a Usenet control
 141 message that has been cryptographically signed using the \fBsigncontrol\fR
 142 program (or some other program that produces a compatible format).
 143 \&\fBpgpverify\fR then uses a \s-1PGP\s0 implementation to determine who signed the
 144 control message.  If the control message has a valid signature,
 145 \&\fBpgpverify\fR prints (to stdout) the user \s-1ID\s0 of the key that signed the
 146 message.  Otherwise, it exits with a non-zero exit status.
 147 .PP
 148 If \fBpgpverify\fR is installed as part of \s-1INN\s0, it uses \s-1INN\s0's configuration
 149 to determine what signature verification program to use, how to log
 150 errors, what temporary directory to use, and what keyring to use.
 151 Otherwise, all of those parameters can be set by editing the beginning of
 152 this script.
 153 .PP
 154 By default, when running as part of \s-1INN\s0, \fBpgpverify\fR expects the \s-1PGP\s0 key
 155 ring to be found in \fIpathetc\fR/pgp (as either \fIpubring.pgp\fR or
 156 \&\fIpubring.gpg\fR depending on whether \s-1PGP\s0 or GnuPG is used to verify
 157 signatures).  If that directory doesn't exist, it will fall back on using
 158 the default key ring, which is in a \fI.pgp\fR or \fI.gnupg\fR subdirectory of
 159 the running user's home directory.
 160 .PP
 161 \&\s-1INN\s0, when using GnuPG, configures \fBpgpverify\fR to use \fBgpgv\fR, which by
 162 default expects keys to be in a keyring named \fItrustedkeys.gpg\fR, since it
 163 doesn't implement trust checking directly.  \fBpgpverify\fR uses that file if
 164 present but falls back to \fIpubring.gpg\fR if it's not found.  This bypasses
 165 the trust model for checking keys, but is compatible with the way that
 166 \&\fBpgpverify\fR used to behave.  Of course, if a keyring is found in
 167 \&\fIpathetc\fR/pgp or configured at the top of the script, that overrides all of
 168 this behavior.
 169 .SH "OPTIONS"
 170 .IX Header "OPTIONS"
 171 The \fB\-test\fR flag causes \fBpgpverify\fR to print out the input that it is
 172 passing to \s-1PGP\s0 (which is a reconstructed version of the input that
 173 supposedly created the control message) as well as the output from \s-1PGP\s0's
 174 analysis of the message.
 175 .SH "EXIT STATUS"
 176 .IX Header "EXIT STATUS"
 177 \&\fBpgpverify\fR may exit with the following statuses:
 178 .IP "0\&" 4
 179 .IX Item "0"
 180 The control message had a good \s-1PGP\s0 signature.
 181 .IP "1" 4
 182 .IX Item "1"
 183 The control message had no \s-1PGP\s0 signature.
 184 .IP "2" 4
 185 .IX Item "2"
 186 The control message had an unknown \s-1PGP\s0 signature.
 187 .IP "3" 4
 188 .IX Item "3"
 189 The control message had a bad \s-1PGP\s0 signature.
 190 .IP "255" 4
 191 .IX Item "255"
 192 A problem occurred not directly related to \s-1PGP\s0 analysis of signature.
 193 .SH "ENVIRONMENT"
 194 .IX Header "ENVIRONMENT"
 195 \&\fBpgpverify\fR does not modify or otherwise alter the environment before
 196 invoking the \fBpgp\fR or \fBgpgv\fR program.  It is the responsibility of the
 197 person who installs \fBpgpverify\fR to ensure that when \fBpgp\fR or \fBgpgv\fR
 198 runs, it has the ability to locate and read a \s-1PGP\s0 key file that contains
 199 the \s-1PGP\s0 public keys for the appropriate Usenet hierarchy administrators.
 200 \&\fBpgpverify\fR can be pointed to an appropriate key ring by editing
 201 variables at the beginning of this script.
 202 .SH "NOTES"
 203 .IX Header "NOTES"
 204 Historically, Usenet news server administrators have configured their news
 205 servers to automatically honor Usenet control messages based on the
 206 originator of the control messages and the hierarchies for which the
 207 control messages applied.  For example, in the past, David Lawrence always
 208 issued control messages for the \*(L"Big\ 8\*(R" hierarchies (comp, humanities,
 209 misc, news, rec, sci, soc, talk).  Usenet news administrators would
 210 configure their news server software to automatically honor newgroup and
 211 rmgroup control messages that originated from David Lawrence and applied
 212 to any of the Big\ 8 hierarchies.
 213 .PP
 214 Unfortunately, Usenet news articles (including control messages) are
 215 notoriously easy to forge.  Soon, malicious users realized they could
 216 create or remove (at least temporarily) any Big\ 8 newsgroup they wanted by
 217 simply forging an appropriate control message in David Lawrence's name.
 218 As Usenet became more widely used, forgeries became more common.
 219 .PP
 220 The \fBpgpverify\fR program was designed to allow Usenet news administrators
 221 to configure their servers to cryptographically verify control messages
 222 before automatically acting on them.  Under the \fBpgpverify\fR system, a Usenet
 223 hierarchy maintainer creates a \s-1PGP\s0 public/private key pair and
 224 disseminates the public key.  Whenever the hierarchy maintainer issues a
 225 control message, he uses the \fBsigncontrol\fR program to sign the control
 226 message with the \s-1PGP\s0 private key.  Usenet news administrators configure
 227 their news servers to run the \fBpgpverify\fR program on the appropriate
 228 control messages, and take action based on the \s-1PGP\s0 key User \s-1ID\s0 that signed
 229 the control message, not the name and address that appear in the control
 230 message's From: or Sender: headers.
 231 .PP
 232 Thus, appropriate use of the \fBsigncontrol\fR and \fBpgpverify\fR programs
 233 essentially eliminates the possibility of malicious users forging Usenet
 234 control messages that sites will act upon, as such users would have to
 235 obtain the \s-1PGP\s0 private key in order to forge a control message that would
 236 pass the cryptographic verification step.  If the hierarchy administrators
 237 properly protect their \s-1PGP\s0 private keys, the only way a malicious user
 238 could forge a validly-signed control message would be by breaking the
 239 public key encryption algorithm, which (at least at this time) is believed
 240 to be prohibitively difficult for \s-1PGP\s0 keys of a sufficient bit length.
 241 .SH "HISTORY"
 242 .IX Header "HISTORY"
 243 \&\fBpgpverify\fR was written by David C Lawrence <tale@isc.org>.  Manual page
 244 provided by James Ralston.  It is currently maintained by Russ Allbery
 245 <rra@stanford.edu>.
 246 .SH "COPYRIGHT AND LICENSE"
 247 .IX Header "COPYRIGHT AND LICENSE"
 248 David Lawrence wrote:  \*(L"Our lawyer told me to include the following.  The
 249 upshot of it is that you can use the software for free as much as you
 250 like.\*(R"
 251 .PP
 252 Copyright (c) 1996 \s-1UUNET\s0 Technologies, Inc.
 253 All rights reserved.
 254 .PP
 255 Redistribution and use in source and binary forms, with or without
 256 modification, are permitted provided that the following conditions are
 257 met:
 258 .IP "1." 4
 259 Redistributions of source code must retain the above copyright notice,
 260 this list of conditions and the following disclaimer.
 261 .IP "2." 4
 262 Redistributions in binary form must reproduce the above copyright notice,
 263 this list of conditions and the following disclaimer in the documentation
 264 and/or other materials provided with the distribution.
 265 .IP "3." 4
 266 All advertising materials mentioning features or use of this software must
 267 display the following acknowledgement:
 268 .Sp
 269 .Vb 1
 270 \&  This product includes software developed by UUNET Technologies, Inc.
 271 .Ve
 272 .IP "4." 4
 273 The name of \s-1UUNET\s0 Technologies (\*(L"\s-1UUNET\s0\*(R") may not be used to endorse or
 274 promote products derived from this software without specific prior written
 275 permission.
 276 .PP
 277 \&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \s-1BY\s0 \s-1UUNET\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0
 278 \&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0
 279 \&\s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0 \s-1ARE\s0 \s-1DISCLAIMED\s0.  \s-1IN\s0
 280 \&\s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0 \s-1UUNET\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1DIRECT\s0, \s-1INDIRECT\s0, \s-1INCIDENTAL\s0,
 281 \&\s-1SPECIAL\s0, \s-1EXEMPLARY\s0, \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 (\s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0
 282 \&\s-1TO\s0, \s-1PROCUREMENT\s0 \s-1OF\s0 \s-1SUBSTITUTE\s0 \s-1GOODS\s0 \s-1OR\s0 \s-1SERVICES\s0; \s-1LOSS\s0 \s-1OF\s0 \s-1USE\s0, \s-1DATA\s0, \s-1OR\s0
 283 \&\s-1PROFITS\s0; \s-1OR\s0 \s-1BUSINESS\s0 \s-1INTERRUPTION\s0) \s-1HOWEVER\s0 \s-1CAUSED\s0 \s-1AND\s0 \s-1ON\s0 \s-1ANY\s0 \s-1THEORY\s0 \s-1OF\s0
 284 \&\s-1LIABILITY\s0, \s-1WHETHER\s0 \s-1IN\s0 \s-1CONTRACT\s0, \s-1STRICT\s0 \s-1LIABILITY\s0, \s-1OR\s0 \s-1TORT\s0 (\s-1INCLUDING\s0
 285 \&\s-1NEGLIGENCE\s0 \s-1OR\s0 \s-1OTHERWISE\s0) \s-1ARISING\s0 \s-1IN\s0 \s-1ANY\s0 \s-1WAY\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OF\s0 \s-1THIS\s0
 286 \&\s-1SOFTWARE\s0, \s-1EVEN\s0 \s-1IF\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \s-1SUCH\s0 \s-1DAMAGE\s0.
 287 .SH "SEE ALSO"
 288 .IX Header "SEE ALSO"
 289 \&\fIgpgv\fR\|(1), \fIpgp\fR\|(1).
 290 .PP
 291 <ftp://ftp.isc.org/pub/pgpcontrol/> is where the most recent versions of
 292 \&\fBsigncontrol\fR and \fBpgpverify\fR live, along with \s-1PGP\s0 public keys used for
 293 hierarchy administration.