.\" $OpenBSD: pkg_sign.1,v 1.3 1999/10/05 22:30:49 espie 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 check_sign
.Nd handle package signatures
.Sh SYNOPSIS
.Nm pkg_sign
.Op Fl sc
.Op Fl t Ar type
.Op Fl u Ar id
.Op Ar
.Nm pkg_check
.Op Fl sc
.Op Fl u Ar id
.Op Ar
.Sh DESCRIPTION
.Nm pkg_sign
embeds a cryptographic signature within a gzip file
.Ar file .
.Ar type
can be 
.Li pgp 
(default) or 
.Li sha1 .  
If
.Ar type 
is 
.Li pgp , 
it will always prompt you for a passphrase to unlock your private 
pgp key, even if you don't use a passphrase (which is a bad idea, anyway).
If
.Ar type
is 
.Li sha1 , 
you must supply an
.Ar id,
which will be recorded as the name of the package, and printed as the 
SHA1 checksum.
.Pp
.Nm pkg_check
checks that cryptographic signature. It currently disregards 
.Ar type
and checks only the topmost signature. For 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 pgp, the
.Ar id
to use to sign the package or verify the signature can be forced with
.Fl u .
.Pp
If 
.Ar file 
is a single dash 
.Pq Sq \&-
or absent,
.Nm check_sign
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 OpenBSD signing scheme uses eight bytes markers such `SIGPGP' \+ length
or `CKSHA1' \+ length for its signatures (those markers are conveniently
eight bytes long).
.Sh RESULTS
.Nm pkg_sign
and
.Nm pkg_check
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.
.Nm pkg_sign 
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 couldn't 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 BUGS
.Xr pgp 1
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 can't 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.
.Sh FILES
.Bl -tag -width "/usr/local/bin/pgp" -compact
.It Pa file.sign
Temporary file built by 
.Nm pkg_sign
from
.Ar file .
.It Pa /usr/local/bin/pgp
Default path to 
.Xr pgp 1 .
.It Pa /var/db/pkgs/SHA1
Recorded checksums.
.El
.Sh SEE ALSO
.Xr gzip 1 ,
.Xr pgp 1 ,
.Xr pkg_add 1 ,
.Xr sha1 1