.\"	$OpenBSD: pkg_sign.1,v 1.8 2015/09/25 16:56:26 schwarze Exp $
.\" Copyright (c) 2014 Marc Espie <espie@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 25 2015 $
.Dt PKG_SIGN 1
.Os
.Sh NAME
.Nm pkg_sign
.Nd sign binary packages for distribution
.Sh SYNOPSIS
.Nm pkg_sign
.Bk -words
.Op Fl Cvi
.Op Fl D Ar name Ns Op = Ns Ar value
.Op Fl j Ar maxjobs
.Op Fl o Ar dir
.Fl s Cm signify Ns | Ns Cm x509
.Op Fl s Ar cert
.Fl s Ar privkey
.Op Fl S Ar source
.Op Ar pkg-name ...
.Ek
.Sh DESCRIPTION
The
.Nm
command is used to sign existing collections of binary packages
created by
.Xr pkg_create 1 .
.Pp
It will sign the packages and optionally, produce a
.Pa SHA256
manifest file in the output directory.
The options are as follows:
.Bl -tag -width Ds
.It Fl C
Append
.Xr sha256 1
checksums to
.Pa SHA256
in the output directory, then sort it.
.It Fl D Ar resign
Allows signing over already signed packages.
Obviously, this checks the existing signature first,
so the
.Fl D Ar SIGNER
and
.Fl D Ar nosig
also apply with the same semantics as
.Xr pkg_add 1 .
.It Fl i
Incremental mode.
Ignore packages that are already in the output repository.
Note that, in verbose mode, they will still show up as
.Sq Signed
in the listing.
.It Fl j Ar maxjobs
Sign existing packages in parallel.
.It Fl o Ar dir
Specify output directory for signing packages.
Otherwise, unsigned packages are created in the current directory.
.It Fl S Ar source
Source repository for packages to be signed.
This can be any url admissible for a
.Ev PKG_PATH ,
so that it is possible to sign packages during a transfer, e.g.,
.Bd -literal -offset indent
pkg_sign -s signify -s mykey-pkg.sec \e
	-o output -S scp://build-machine/packages/
.Ed
.It Xo
.Fl s Cm signify Ns | Ns Cm x509
.Op Fl s Ar cert
.Fl s Ar privkey
.Xc
Specify signature parameters for signed packages.
Option parameters are as follows:
.Bl -tag -width signify|x509 -compact
.It Cm signify Ns | Ns Cm x509
choose
.Xr signify 1
or X.509-style signatures.
.It Ar cert
the path to the signer's certificate (X.509 only)
.It Ar privkey
the path to the signer's private key.
For
.Cm signify ,
the private key name is used to set the
.Cm @signer
annotation.
If a corresponding public key is found, the first signatures will be
checked for key mismatches.
.El
.Pp
For X.509, the signer's certificate and the signer's private key
should be generated using standard openssl x509 commands.
This assumes the existence of a certificate authority (or several), whose
public information is recorded as a
.Pa /etc/ssl/pkgca.pem
file.
.It Fl v
Turn on verbose output, display
.Sq Signed output/pkg.tgz
after each package is signed.
.El
.Sh SIGNATURE DETAILS
The packing-list is extracted from the source package:
it already contains a complete manifest of files within the package,
checksummed with
.Xr sha256 1
and annotated with proper
.Cm @mode ,
.Cm @user ,
.Cm @group
annotations, so that
.Xr pkg_add 1
will refuse to give special rights to any file which isn't properly annotated,
and so that it will abort on installation of a file whose checksum does not
match.
.Pp
That packing list is a text file that is signed using the provided method,
adding a
.Cm @digital-signature
annotation.
The signed package is then created, by putting the signed packing-list at
the start of the new package, and then blindly copying the rest of the source
package: there is no need to re-checksum any of the files;
if someone tampers with them later, their checksum will not match.
.Sh SEE ALSO
.Xr openssl 1 ,
.Xr pkg_add 1 ,
.Xr pkg_create 1 ,
.Xr sha256 1 ,
.Xr signify 1 ,
.Xr tar 1 ,
.Xr package 5
.Sh HISTORY
The
.Nm
command first appeared in
.Ox 5.5 .
.Sh AUTHORS
.An Marc Espie