From b927fb5186625344cf0182ff58cb93bbd8ba64ef Mon Sep 17 00:00:00 2001
From: espie <espie@openbsd.org>
Date: Thu, 2 Jan 2014 15:01:37 +0000
Subject: [PATCH] Document new options related to signatures

---
 usr.sbin/pkg_add/pkg_create.1 | 68 ++++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 16 deletions(-)

diff --git a/usr.sbin/pkg_add/pkg_create.1 b/usr.sbin/pkg_add/pkg_create.1
index bd9ffe7a1d8..6a355acf914 100644
--- a/usr.sbin/pkg_add/pkg_create.1
+++ b/usr.sbin/pkg_add/pkg_create.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pkg_create.1,v 1.82 2012/06/08 15:15:58 espie Exp $
+.\"	$OpenBSD: pkg_create.1,v 1.83 2014/01/02 15:01:37 espie Exp $
 .\"
 .\" Documentation and design originally from FreeBSD. All the code has
 .\" been rewritten since. We keep the documentation's notice:
@@ -21,7 +21,7 @@
 .\" [jkh] Took John's changes back and made some additional extensions for
 .\" better integration with FreeBSD's new ports collection.
 .\"
-.Dd $Mdocdate: June 8 2012 $
+.Dd $Mdocdate: January 2 2014 $
 .Dt PKG_CREATE 1
 .Os
 .Sh NAME
@@ -49,11 +49,18 @@
 .Ek
 .Nm pkg_create
 .Op Fl s Ar signature-parameter
+.Op Fl D Ar VENDOR Ns = Ns Ar value
 .Fl f Ar packinglist
+.Nm pkg_create
+.Fl s Ar signature-parameter ...
+.Op Fl D Ar VENDOR Ns = Ns Ar value
+.Op Fl o Ar dir
+.Op Fl S Ar source
+.Op Ar pkgfile ...
 .Sh DESCRIPTION
 The
 .Nm
-command creates a binary package named
+command is normally used to a binary package named
 .Ar pkg-name ,
 for subsequent use with
 .Xr pkg_add 1 ,
@@ -74,6 +81,9 @@ infrastructure instead of manual
 .Nm
 invocation is strongly recommended.
 .Pp
+It can also be used to recreate a binary package from an existing installation
+(second synopsis) or to sign a collection of built packages (third synopsis).
+.Pp
 During package creation,
 .Nm
 replaces too long file names with smaller equivalents
@@ -151,6 +161,8 @@ If defined, appended to the description.
 .It Ar USE_GROFF
 Set to 1 to have groff format manpages behind the scenes during
 package creation.
+.It Ar VENDOR
+Specify a vendor-name, mostly used for signing packages.
 .El
 .It Fl d No [-] Ns Ar desc
 Fetch long description for package from file
@@ -187,6 +199,9 @@ Causes
 to always display the progress meter in cases it would not do so by default.
 .It Fl n
 Don't actually create a package.
+.It Fl o Ar dir
+Specify output directory for signing packages after the fact.
+Otherwise, unsigned packages will be replaced with signed packages.
 .It Fl P Ar pkg-dependency
 Specify a
 .Cm @depend
@@ -207,28 +222,48 @@ Print out the actual packing-list of the package being generated
 (query mode).
 Most often used in combination with
 .Fl n .
+.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_create -s signify -s mykey -DVENDOR=me \\
+	-o output -S scp://build-machine/packages/
+.Ed
 .It Xo
-.Fl s Ar x509
-.Fl s Ar cert
+.Fl s Ar signify|x509
+.Op Fl s Ar cert
 .Fl s Ar privkey
 .Xc
 Specify signature parameters for signed packages.
-For now, the only supported use involves three
-.Fl s
-options:
-.Ar x509
-to indicate X.509-style signatures,
-.Ar cert
-the path to the signer's certificate
-and
-.Ar privkey
+Option parameters are as follows:
+.Bl -tag -width ArsignifyDx509 -compact
+.It Ar signify|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.
-The signer's certificate and the signer's private key should be generated
-using standard openssl x509 commands.
+.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.
+.Pp
+For
+.Xr signify 1
+private usage, a
+.Ar VENDOR
+must be specified, so that
+.Xr pkg_add 1
+will be able to retrieve the correct public key from
+.Pa /etc/signify/<vendor>.pubkey .
 .It Fl U Ar undisplayfile
 Display the file (using
 .Xr more 1 )
@@ -989,6 +1024,7 @@ option is specified.
 .Xr pkg_add 1 ,
 .Xr pkg_delete 1 ,
 .Xr pkg_info 1 ,
+.Xr signify 1 ,
 .Xr tar 1 ,
 .Xr bsd.port.mk 5 ,
 .Xr package 5 ,
-- 
2.20.1