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