usr.sbin/pkg_install/sign/pkg_sign.1

   1 .\" $FreeBSD: src/usr.sbin/pkg_install/sign/pkg_sign.1,v 1.1.2.5 2002/06/21 16:42:20 charnier Exp $
   2 .\" $DragonFly: src/usr.sbin/pkg_install/sign/Attic/pkg_sign.1,v 1.2 2003/06/17 04:29:59 dillon Exp $
   3 .\" $OpenBSD: pkg_sign.1,v 1.6 2000/04/15 02:15:20 aaron Exp $
   4 .\"
   5 .\" Copyright (c) 1999 Marc Espie.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"    This product includes software developed by Marc Espie for the OpenBSD
  18 .\"    Project.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE OPENBSD PROJECT AND CONTRIBUTORS
  21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23 .\" A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OPENBSD
  24 .\" PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .Dd September 24, 1999
  32 .Dt PKG_SIGN 1
  33 .Os
  34 .Sh NAME
  35 .Nm pkg_sign ,
  36 .Nm pkg_check
  37 .Nd handle package signatures
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl sc
  41 .Op Fl t Ar type
  42 .Op Fl u Ar id
  43 .Op Fl k Ar key
  44 .Op Ar
  45 .Nm pkg_check
  46 .Op Fl sc
  47 .Op Fl u Ar id
  48 .Op Fl k Ar cert
  49 .Op Ar
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility embeds a cryptographic signature within a gzip file
  54 .Ar file .
  55 .Ar type
  56 can be
  57 .Cm pgp
  58 (default),
  59 .Cm sha1 ,
  60 or
  61 .Cm x509 .
  62 If
  63 .Ar type
  64 is
  65 .Cm pgp ,
  66 it will always prompt you for a passphrase to unlock your private
  67 pgp key, even if you don't use a passphrase (which is a bad idea, anyway).
  68 If
  69 .Ar type
  70 is
  71 .Cm sha1 ,
  72 you must supply an
  73 .Ar id ,
  74 which will be recorded as the name of the package, and printed as the
  75 SHA1 checksum.
  76 .Pp
  77 The
  78 .Nm pkg_check
  79 utility checks that cryptographic signature.
  80 It currently disregards
  81 .Ar type
  82 and checks only the topmost signature.
  83 For
  84 .Cm sha1 ,
  85 it checksums the file
  86 and verifies that the result matches the list of checksums recorded in
  87 .Pa /var/db/pkg/SHA1 .
  88 .Pp
  89 Options
  90 .Fl s
  91 and
  92 .Fl c
  93 can be used to force package signing or signature checking mode.
  94 .Pp
  95 For
  96 .Cm pgp ,
  97 the
  98 .Ar id
  99 to use to sign the package or verify the signature can be forced with
 100 .Fl u .
 101 .Pp
 102 For
 103 .Cm x509 ,
 104 the signing key or verification certificate may be
 105 specified with the
 106 .Fl k
 107 option.  If not specified, packages are signed or verified with the
 108 default keys and certificates documented below.
 109 .Pp
 110 If
 111 .Ar file
 112 is a single dash
 113 .Pq Sq Fl
 114 or absent,
 115 .Nm
 116 reads from the standard input.
 117 .Pp
 118 Package signing uses a feature of the gzip format, namely that one can
 119 set a flag
 120 .Dv EXTRA_FIELD
 121 in the gzip header and store extra data between the gzip header and the
 122 compressed file proper.
 123 The
 124 .Ox
 125 signing scheme uses eight bytes markers such
 126 .Sq Li SIGPGP
 127 + length or
 128 .Sq CKSHA1
 129 + length for its signatures (those markers are conveniently
 130 eight bytes long).
 131 .Sh DIAGNOSTICS
 132 The
 133 .Nm
 134 and
 135 .Nm pkg_check
 136 utilities return with an exit code >0 if anything went wrong for any
 137 .Ar file .
 138 For
 139 .Nm pkg_check ,
 140 this usually indicates that the package is not signed, or that the
 141 signature is forged.
 142 .Bl -diag
 143 .It "File %s is already signed"
 144 There is a signature embedded within the gzip file already.
 145 The
 146 .Nm
 147 utility currently does not handle multiple signatures.
 148 .It "File %s is not a signed gzip file"
 149 This is an unsigned package.
 150 .It "File %s is not a gzip file"
 151 The program couldn't find a proper gzip header.
 152 .It "File %s contains an unknown extension"
 153 The extended area of the gzip file has been used for an unknown purpose.
 154 .It "File %s uses old signatures, no longer supported"
 155 The gzip file uses a very early version of package signing that was
 156 substantially slower.
 157 .El
 158 .Sh BUGS
 159 .Xr pgp 1
 160 is an ill-designed program, which is hard to interface with.
 161 For instance, the `separate signing scheme' it pretends to offer is
 162 useless, as it can't be used with pipes, so that
 163 .Nm pgp_sign
 164 needs to kludge it by knowing the length of a pgp signature, and invoking
 165 pgp in `seamless' signature mode, without compression of the main file,
 166 and just retrieving the signature.
 167 .Pp
 168 The checking scheme is little less convoluted, namely we rebuild the file
 169 that pgp expects on the fly.
 170 .Pp
 171 Paths to
 172 .Nm pgp
 173 and
 174 the checksum file are hard-coded to avoid tampering and hinder flexibility.
 175 .Sh FILES
 176 .Bl -tag -width "/usr/local/bin/pgp" -compact
 177 .It Pa file.sign
 178 Temporary file built by
 179 .Nm
 180 from
 181 .Ar file .
 182 .It Pa /usr/local/bin/pgp
 183 Default path to
 184 .Xr pgp 1 .
 185 .It Pa /var/db/pkgs/SHA1
 186 Recorded checksums.
 187 .It Pa /etc/ssl/pkg.key
 188 Default package signing key.
 189 .It Pa /etc/ssl/pkg.crt
 190 Default package verification certificate(s).
 191 .El
 192 .Sh SEE ALSO
 193 .Xr gzip 1 ,
 194 .Xr pgp 1 ,
 195 .Xr pkg_add 1 ,
 196 .Xr sha1 1
 197 .Sh AUTHORS
 198 .An -nosplit
 199 A
 200 .Nm
 201 utility was created by
 202 .An Marc Espie
 203 for the
 204 .Ox
 205 Project.
 206 X.509 signatures and
 207 .Fx
 208 support added by
 209 .An Wes Peters Aq wes@softweyr.com .