freebsd/usr.sbin/pkg_install/sign/pkg_sign.1

.\" $FreeBSD$
.\" $OpenBSD: pkg_sign.1,v 1.6 2000/04/15 02:15:20 aaron Exp $
.\"
.\" Copyright (c) 1999 Marc Espie.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"    This product includes software developed by Marc Espie for the OpenBSD
.\"    Project.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OPENBSD PROJECT AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OPENBSD
.\" PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd September 24, 1999
.Dt PKG_SIGN 1
.Os
.Sh NAME
.Nm pkg_sign ,
.Nm pkg_check
.Nd handle package signatures
.Sh SYNOPSIS
.Nm
.Op Fl sc
.Op Fl t Ar type
.Op Fl u Ar id
.Op Fl k Ar key
.Op Ar
.Nm pkg_check
.Op Fl sc
.Op Fl u Ar id
.Op Fl k Ar cert
.Op Ar
.Sh DESCRIPTION
The
.Nm
utility embeds a cryptographic signature within a gzip file
.Ar file .
.Ar type
can be
.Cm pgp
(default),
.Cm sha1 ,
or
.Cm x509 .
If
.Ar type
is
.Cm pgp ,
it will always prompt you for a passphrase to unlock your private
pgp key, even if you do not use a passphrase (which is a bad idea, anyway).
If
.Ar type
is
.Cm sha1 ,
you must supply an
.Ar id ,
which will be recorded as the name of the package, and printed as the
SHA1 checksum.
.Pp
The
.Nm pkg_check
utility checks that cryptographic signature.
It currently disregards
.Ar type
and checks only the topmost signature.
For
.Cm sha1 ,
it checksums the file
and verifies that the result matches the list of checksums recorded in
.Pa /var/db/pkg/SHA1 .
.Pp
Options
.Fl s
and
.Fl c
can be used to force package signing or signature checking mode.
.Pp
For
.Cm pgp ,
the
.Ar id
to use to sign the package or verify the signature can be forced with
.Fl u .
.Pp
For
.Cm x509 ,
the signing key or verification certificate may be
specified with the
.Fl k
option.
If not specified, packages are signed or verified with the
default keys and certificates documented below.
.Pp
If
.Ar file
is a single dash
.Pq Sq Fl
or absent,
.Nm
reads from the standard input.
.Pp
Package signing uses a feature of the gzip format, namely that one can
set a flag
.Dv EXTRA_FIELD
in the gzip header and store extra data between the gzip header and the
compressed file proper.
The
.Ox
signing scheme uses eight bytes markers such
.Sq Li SIGPGP
+ length or
.Sq CKSHA1
+ length for its signatures (those markers are conveniently
eight bytes long).
.Sh FILES
.Bl -tag -width "/usr/local/bin/pgp" -compact
.It Pa file.sign
Temporary file built by
.Nm
from
.Ar file .
.It Pa /usr/local/bin/pgp
Default path to
.Xr pgp 1 .
.It Pa /var/db/pkgs/SHA1
Recorded checksums.
.It Pa /etc/ssl/pkg.key
Default package signing key.
.It Pa /etc/ssl/pkg.crt
Default package verification certificate(s).
.El
.Sh EXIT STATUS
The
.Nm
and
.Nm pkg_check
utilities return with an exit code >0 if anything went wrong for any
.Ar file .
For
.Nm pkg_check ,
this usually indicates that the package is not signed, or that the
signature is forged.
.Sh DIAGNOSTICS
.Bl -diag
.It "File %s is already signed"
There is a signature embedded within the gzip file already.
The
.Nm
utility currently does not handle multiple signatures.
.It "File %s is not a signed gzip file"
This is an unsigned package.
.It "File %s is not a gzip file"
The program could not find a proper gzip header.
.It "File %s contains an unknown extension"
The extended area of the gzip file has been used for an unknown purpose.
.It "File %s uses old signatures, no longer supported"
The gzip file uses a very early version of package signing that was
substantially slower.
.El
.Sh SEE ALSO
.Xr gzip 1 ,
.Xr pgp 1 ,
.Xr pkg_add 1 ,
.Xr sha1 1
.Sh AUTHORS
.An -nosplit
A
.Nm
utility was created by
.An Marc Espie
for the
.Ox
Project.
X.509 signatures and
.Fx
support added by
.An Wes Peters Aq wes@softweyr.com .
.Sh BUGS
The
.Xr pgp 1
utility is an ill-designed program, which is hard to interface with.
For instance, the `separate signing scheme' it pretends to offer is
useless, as it cannot be used with pipes, so that
.Nm pgp_sign
needs to kludge it by knowing the length of a pgp signature, and invoking
pgp in `seamless' signature mode, without compression of the main file,
and just retrieving the signature.
.Pp
The checking scheme is little less convoluted, namely we rebuild the file
that pgp expects on the fly.
.Pp
Paths to
.Nm pgp
and
the checksum file are hard-coded to avoid tampering and hinder flexibility.