crypto/external/bsd/netpgp/dist/src/netpgpverify/netpgpverify.1

   1 .\" $NetBSD: netpgpverify.1,v 1.2 2009/06/08 08:02:32 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This manual page is derived from software contributed to
   7 .\" The NetBSD Foundation by Alistair Crooks (agc@NetBSD.org).
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd June 6, 2009
  31 .Dt NETPGPVERIFY 1
  32 .Os
  33 .Sh NAME
  34 .Nm netpgpverify
  35 .Nd standalone program for digital signature verification
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Fl Fl verify
  39 .Op Fl Fl output Ns = Ns Ar filename
  40 .Op options
  41 .Ar file ...
  42 .Pp
  43 where the options for all commands are:
  44 .Pp
  45 .Op Fl Fl coredumps
  46 .br
  47 .Op Fl Fl homedir Ns = Ns Ar home-directory
  48 .br
  49 .Op Fl Fl keyring Ns = Ns Ar keyring
  50 .br
  51 .Op Fl Fl userid Ns = Ns Ar userid
  52 .br
  53 .Op Fl Fl verbose
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 complements the
  58 .Xr netpgp 1
  59 program, and duplicates its verification functionality in
  60 a single standalone program.
  61 The reason for this duplication is simply because verification
  62 of digital signatures
  63 is such a common operation that a single, much smaller,
  64 standalone program can be used.
  65 .Pp
  66 The following commands are used to sign and verify signatures:
  67 .Bl -tag -width Ar
  68 .It Fl Fl coredumps
  69 In normal processing,
  70 if an error occurs, the contents of memory are saved to disk, and can
  71 be read using tools to analyse behaviour.
  72 Unfortunately this can disclose information to people viewing
  73 the core dump, such as secret keys, and passphrases protecting
  74 those keys.
  75 In normal operation,
  76 .Nm
  77 will turn off the ability to save core dumps on persistent storage,
  78 but selecting this option will allow core dumps to be written to disk.
  79 This option should be used wisely, and any core dumps should
  80 be deleted in a secure manner when no longer needed.
  81 .It Fl Fl homedir Ar home-directory
  82 Keyrings are normally located, for historical reasons, within
  83 the user's home directory in a subdirectory called
  84 .Dq Pa .gnupg
  85 and this option specifies an alternative location in which to
  86 find that sub-directory.
  87 .It Fl Fl keyring Ar keyring
  88 This option specifies an alternative keyring to be used.
  89 All keyring operations will be relative to this alternative keyring.
  90 .It Fl Fl output
  91 specifies a filename to which verified output from a signed file
  92 may be redirected.
  93 The default is to send the verified output to stdout,
  94 and this may also be specified using the
  95 .Dq -
  96 value.
  97 .It Fl Fl verbose
  98 This option can be used to view information during
  99 the process of the
 100 .Nm
 101 requests.
 102 .El
 103 .Sh SIGNING AND VERIFICATION
 104 Signing and verification of a file is best viewed using the following example:
 105 .Bd -literal
 106 % netpgp --sign --userid=agc@netbsd.org a
 107 pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
 108 Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
 109 uid              Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt]
 110 uid              Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt]
 111 uid              Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt]
 112 uid              Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt]
 113 netpgp passphrase:
 114 % netpgpverify a.gpg
 115 Good signature for a.gpg made Thu Jan 29 03:06:00 2009
 116 using RSA (Encrypt or Sign) key 1B68DCFCC0596823
 117 pub 2048/RSA (Encrypt or Sign) 1b68dcfcc0596823 2004-01-12
 118 Key fingerprint: d415 9deb 336d e4cc cdfa 00cd 1b68 dcfc c059 6823
 119 uid              Alistair Crooks \*[Lt]alistair@hockley-crooks.com\*[Gt]
 120 uid              Alistair Crooks \*[Lt]agc@pkgsrc.org\*[Gt]
 121 uid              Alistair Crooks \*[Lt]agc@netbsd.org\*[Gt]
 122 uid              Alistair Crooks \*[Lt]agc@alistaircrooks.com\*[Gt]
 123 %
 124 .Ed
 125 .Pp
 126 In the example above, a signature is made on a single file called
 127 .Dq Pa a
 128 using a user identity corresponding to
 129 .Dq agc@netbsd.org
 130 and using the
 131 .Xr netpgp 1
 132 program.
 133 The key located for the user identity is displayed, and
 134 the user is prompted to type in their passphrase.
 135 The resulting file, called
 136 .Dq Pa a.gpg
 137 is placed in the same directory.
 138 The second part of the example shows a verification
 139 using
 140 .Nm
 141 of the signed file
 142 taking place.
 143 The time and user identity of the signatory is displayed, followed
 144 by a fuller description of the public key of the signatory.
 145 In both cases, the exit value from the utility was a successful one.
 146 .Sh RETURN VALUES
 147 The
 148 .Nm
 149 utility will return 0 for success,
 150 1 if the file's signature does not match what was expected,
 151 or 2 if any other error occurs.
 152 .Sh SEE ALSO
 153 .Xr netpgp 1 ,
 154 .\" .Xr libbz2 3 ,
 155 .Xr libnetpgp 3 ,
 156 .Xr ssl 3 ,
 157 .Xr zlib 3
 158 .Sh STANDARDS
 159 The
 160 .Nm
 161 utility is designed to conform to IETF RFC 4880.
 162 .Sh HISTORY
 163 The
 164 .Nm
 165 command first appeared in
 166 .Nx 6.0 .
 167 .Sh AUTHORS
 168 .An -nosplit
 169 .An Ben Laurie ,
 170 .An Rachel Willmer ,
 171 and was overhauled and rewritten by
 172 .An Alistair Crooks Aq agc@NetBSD.org .
 173 This manual page was written by
 174 .An Alistair Crooks .