easyrsa: add man page

[Frédéric Fauberteau <frederic%fauberteau.org@localhost>]

Module Name:	pkgsrc-wip
Committed By:	Frédéric Fauberteau <frederic%fauberteau.org@localhost>
Pushed By:	frederic
Date:		Tue Mar 1 00:46:05 2016 +0100
Changeset:	d9b8cbdcc90d412518c7d9bc1ba5f20264e92f31

Modified Files:
	easyrsa/Makefile
	easyrsa/PLIST
Added Files:
	easyrsa/files/easyrsa.1

Log Message:
easyrsa: add man page

To see a diff of this commit:
https://wip.pkgsrc.org/cgi-bin/gitweb.cgi?p=pkgsrc-wip.git;a=commitdiff;h=d9b8cbdcc90d412518c7d9bc1ba5f20264e92f31

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

diffstat:
 easyrsa/Makefile        |   7 +-
 easyrsa/PLIST           |   1 +
 easyrsa/files/easyrsa.1 | 273 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 279 insertions(+), 2 deletions(-)

diffs:
diff --git a/easyrsa/Makefile b/easyrsa/Makefile
index 06d6b76..49bc55e 100644
--- a/easyrsa/Makefile
+++ b/easyrsa/Makefile
@@ -14,10 +14,11 @@ EASYRSA_DOC_FILES=	COPYING ChangeLog KNOWN_ISSUES README README.quickstart.md
 EASYRSA_CNF_FILES=	openssl-1.0.cnf vars.example x509-types/COMMON x509-types/ca \
 			x509-types/client x509-types/server
 
-INSTALLATION_DIRS+=	${BINDIR} ${EGDIR} ${DOCDIR}
+INSTALLATION_DIRS+=	${BINDIR} ${DOCDIR} ${EGDIR} ${MANDIR}
 BINDIR=			${PREFIX}/bin
-EGDIR=			${PREFIX}/share/examples/easyrsa
 DOCDIR=			${PREFIX}/share/doc/easyrsa
+EGDIR=			${PREFIX}/share/examples/easyrsa
+MANDIR=			${PREFIX}/${PKGMANDIR}
 PKG_SYSCONFSUBDIR=	easyrsa
 OWN_DIRS=		${PKG_SYSCONFDIR}/x509-types
 .for f in ${EASYRSA_CNF_FILES}
@@ -28,6 +29,8 @@ NO_BUILD=		yes
 
 do-install:
 	${INSTALL_SCRIPT} ${WRKSRC}/easyrsa3/easyrsa ${DESTDIR}${BINDIR}/easyrsa
+	${INSTALL_MAN_DIR} ${DESTDIR}${MANDIR}/man1
+	${INSTALL_MAN} ${FILESDIR}/easyrsa.1 ${DESTDIR}${MANDIR}/man1
 
 	${INSTALL_DATA_DIR} ${DESTDIR}${EGDIR}/x509-types
 .for f in ${EASYRSA_CNF_FILES}
diff --git a/easyrsa/PLIST b/easyrsa/PLIST
index 84c2a8d..1ecc235 100644
--- a/easyrsa/PLIST
+++ b/easyrsa/PLIST
@@ -1,5 +1,6 @@
 @comment $NetBSD$
 bin/easyrsa
+man/man1/easyrsa.1
 share/doc/easyrsa/COPYING
 share/doc/easyrsa/ChangeLog
 share/doc/easyrsa/EasyRSA-Advanced.md
diff --git a/easyrsa/files/easyrsa.1 b/easyrsa/files/easyrsa.1
new file mode 100644
index 0000000..b63dc2f
--- /dev/null
+++ b/easyrsa/files/easyrsa.1
@@ -0,0 +1,273 @@
+.\" -*- nroff -*-
+.\"
+.Dd
+.Dt EASYRSA 1
+.Os
+.Sh NAME
+.Nm easyrsa
+.Nd manage RSA key
+.Sh SYNOPSIS
+.Nm easyrsa
+.Bk
+.Op Ar options
+.Oc Ar COMMAND
+.Op Ar command-options
+.Ek
+.Sh DESCRIPTION
+.Nm
+manages RSA key using
+.Xr openssl 1
+command line tool.
+.Pp
+The following options may be provided before the command. Options specified at
+runtime override env-vars and any 'vars' file in use. Unless noted, non-empty
+values to options are mandatory.
+.Ss GENERAL OPTIONS
+.Bl -tag
+.It Fl \&\-batch
+Set automatic (no-prompts when possible) mode.
+.Sm off
+.It Fl \&\-pki\-dir= Ar DIR
+.Sm on
+Declares the PKI directory.
+.Sm off
+.It Fl \&\-vars= Ar FILE
+.Sm on
+Define a specific 'vars' file to use for Easy-RSA config
+.El
+.Ss CERTIFICATE & REQUEST OPTIONS
+These options impact cert/req field values.
+.Bl -tag
+.Sm off
+.It Fl \&\-days= Ar #
+.Sm on
+Sets the signing validity to the specified number of days.
+.Sm off
+.It Fl \&\-digest= Ar ALG
+.Sm on
+Digest to use in the requests & certificates.
+.Sm off
+.It Fl \&\-dn\-mode= Ar MODE
+.Sm on
+DN mode to use (cn_only or org).
+.Sm off
+.It Fl \&\-keysize= Ar #
+.Sm on
+Size in bits of keypair to generate.
+.Sm off
+.It Fl \&\-req-cn= Ar NAME
+.Sm on
+Default CN to use.
+.Sm off
+.It Fl \&\-subca\-len= Ar #
+.Sm on
+Path length of signed sub-CA certs; must be >= 0 if used.
+.Sm off
+.It Fl \&\-subject\-alt\-name= Ar SAN_FORMAT_STRING
+.Sm on
+This global option adds a subjectAltName to the request or issued certificate.
+It MUST be in a valid format accepted by
+.Xr openssl 1
+or req/cert generation will fail. Note that including multiple such names
+requires them to be comma-separated; further invocations of this option will
+REPLACE the value.
+.Pp
+Examples of the
+.Ar SAN_FORMAT_STRING
+shown below:
+.Bl -tag -compact
+.It DNS:alternate.example.net
+.It DNS:primary.example.net,DNS:alternate.example.net
+.It IP:203.0.113.29
+.It email:alternate%example.net@localhost
+.El
+.Sm off
+.It Fl \&\-use\-algo= Ar ALG
+.Sm on
+Crypto alg to use: choose rsa (default) or ec.
+.Sm off
+.It Fl \&\-curve= Ar NAME
+.Sm on
+For elliptic curve, sets the named curve to use.
+.El
+.Ss ORGANIZATIONAL DN OPTIONS
+These options can only be used with the 'org' DN mode. The values may be blank.
+.Bl -tag
+.Sm off
+.It Fl \&\-req\-c= Ar CC
+.Sm on
+Country code (2-letters).
+.Sm off
+.It Fl \&\-req\-st= Ar NAME
+.Sm on
+State/Province.
+.Sm off
+.It Fl \&\-req\-city= Ar NAME
+.Sm on
+City/Locality.
+.Sm off
+.It Fl \&\-req\-org= Ar NAME
+.Sm on
+Organization.
+.Sm off
+.It Fl \&\-req\-email= Ar NAME
+.Sm on
+Email addresses.
+.Sm off
+.It Fl \&\-req\-ou= Ar NAME
+.Sm on
+Organizational Unit.
+.El
+.Ss DEPRECATED FEATURES
+.Bl -tag
+.Sm off
+.It Fl \&\-ns\-cert= Ar YESNO
+.Sm on
+Yes or no to including deprecated NS extensions.
+.Sm off
+.It Fl \&\-ns\-comment= Ar COMMENT
+.Sm on
+NS comment to include (value may be blank).
+.El
+.Ss COMMAND SUMMARY
+.Bl -tag
+.It Cm init-pki
+Removes & re-initializes the PKI dir for a clean PKI.
+.It Cm build-ca Op Ar cmd-opts
+Creates a new CA.
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm nopass
+do not encrypt the CA key (default is encrypted).
+.It Cm subca
+create a sub-CA keypair and request (default is a root CA).
+.El
+.It Cm gen-dh
+Generates DH (Diffie-Hellman) parameters.
+.It Cm gen-req Ar filename_base Op Ar cmd-opts
+Generate a standalone keypair and request (CSR).
+.Pp
+This request is suitable for sending to a remote CA for signing.
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm nopass
+do not encrypt the private key (default is encrypted).
+.El
+.It Cm sign-req Ar type Ar filename_base
+Sign a certificate request of the defined type.
+.Ar type
+must be a known type such as 'client', 'server', or 'ca' (or a user-added type).
+.Pp
+This request file must exist in the reqs/ dir and have a .req file extension. See
+.Cm import-req
+below for importing reqs from other sources.
+.It Cm build-client-full Ar filename_base Op Ar cmd-opts
+Generate a keypair and sign locally for a client.
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm nopass
+do not encrypt the private key (default is encrypted).
+.El
+.It Cm build-server-full Ar filename_base Op Ar cmd-opts
+Generate a keypair and sign locally for a server.
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm nopass
+do not encrypt the private key (default is encrypted).
+.El
+.It Cm revoke Ar filename_base
+Revoke a certificate specified by the
+.Ar filename_base .
+.It Cm gen-crl
+Generate a CRL.
+.It Cm update-db
+Update the index.txt database.
+.Pp
+This command will use the system time to update the status of issued certificates.
+.It Cm show-req Ar filename_base Op Ar cmd-opts
+ Shows details of the req referenced by
+.Ar filename_base .
+.Pp
+Human-readable output is shown, including any requested cert options when showing a request.
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm full
+show full req info, including pubkey/sig data.
+.El
+.It Cm show-cert Ar filename_base Op Ar cmd-opts
+ Shows details of the cert referenced by
+.Ar filename_base .
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm full
+show full cert info, including pubkey/sig data.
+.El
+.It Cm import-req Ar request_file_path Ar short_basename
+Import a certificate request from a file.
+.Pp
+This will copy the specified file into the reqs/ dir in preparation for signing. The.
+.Ar short_basename
+is the filename base to create.
+.Pp
+Example usage: import-req /some/where/bob_request.req bob
+.It Cm export-p7 Ar filename_base Op Ar cmd-opts
+Export a PKCS#7 file with the pubkey specified by
+.Ar filename_base .
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm noca
+do not include the ca.crt file in the PKCS7 output.
+.El
+.It Cm export-p12 Ar filename_base Op Ar cmd-opts
+Export a PKCS#12 file with the keypair specified by
+.Ar filename_base .
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm noca
+do not include the ca.crt file in the PKCS12 output.
+.It Cm nokey
+do not include the private key in the PKCS12 output
+.El
+.It Cm set-rsa-pass Ar filename_base Op Ar cmd-opts
+Set a new passphrase on an RSA key for the listed
+.Ar filename_base .
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm nopass
+use no password and leave the key unencrypted.
+.It Cm file
+(advanced) treat the file as a raw path, not a short-name.
+.El
+.It Cm set-ec-pass Ar filename_base Op Ar cmd-opts
+Set a new passphrase on an EC key for the listed
+.Ar filename_base .
+.Pp
+.Ar cmd-opts
+is an optional set of command options from this list:
+.Bl -tag -compact
+.It Cm nopass
+use no password and leave the key unencrypted.
+.It Cm file
+(advanced) treat the file as a raw path, not a short-name.
+.El
+.El
+.Sh SEE ALSO
+.Xr openssl 1