pki: Add pki --gen man page

Can be opened with "man pki --gen".

diff --git a/configure.ac b/configure.ac
index 196137a..d4b198b 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -1494,6 +1494,7 @@ AC_CONFIG_FILES([
        man/strongswan.conf.5
        src/charon-cmd/charon-cmd.8
        src/pki/man/ipsec-pki.8
+       src/pki/man/pki---gen.8
 ])
 
 AC_OUTPUT

diff --git a/src/pki/commands/gen.c b/src/pki/commands/gen.c
index e3602f0..b74be7d 100644 (file)
--- a/src/pki/commands/gen.c
+++ b/src/pki/commands/gen.c
@@ -151,7 +151,7 @@ static void __attribute__ ((constructor))reg()
        command_register((command_t) {
                gen, 'g', "gen", "generate a new private key",
                {"  [--type rsa|ecdsa] [--size bits] [--safe-primes]",
-                "[--shares n] [--threshold l] [--outform der|pem|pgp]"},
+                "[--shares n] [--threshold l] [--outform der|pem]"},
                {
                        {"help",                'h', 0, "show usage information"},
                        {"type",                't', 1, "type of key, default: rsa"},
@@ -159,7 +159,7 @@ static void __attribute__ ((constructor))reg()
                        {"safe-primes", 'p', 0, "generate rsa safe primes"},
                        {"shares",              'n', 1, "number of private rsa key shares"},
                        {"threshold",   'l', 1, "minimum number of participating rsa key shares"},
-                       {"outform",             'f', 1, "encoding of generated private key"},
+                       {"outform",             'f', 1, "encoding of generated private key, default: der"},
                }
        });
 }

diff --git a/src/pki/man/Makefile.am b/src/pki/man/Makefile.am
index ba4aac8..4b33a30 100644 (file)
--- a/src/pki/man/Makefile.am
+++ b/src/pki/man/Makefile.am
@@ -1,4 +1,5 @@
 man8_MANS = \
-       ipsec-pki.8
+       ipsec-pki.8 \
+       pki---gen.8
 
 CLEANFILES = $(man8_MANS)

diff --git a/src/pki/man/ipsec-pki.8.in b/src/pki/man/ipsec-pki.8.in
index 1f81f68..0c1d427 100644 (file)
--- a/src/pki/man/ipsec-pki.8.in
+++ b/src/pki/man/ipsec-pki.8.in
@@ -69,4 +69,5 @@ Verify a certificate using a CA certificate.
 .
 .SH "SEE ALSO"
 .
-.BR ipsec (8)
+.BR ipsec (8),
+.BR pki\ \-\-gen (8)

diff --git a/src/pki/man/pki---gen.8.in b/src/pki/man/pki---gen.8.in
new file mode 100644 (file)
index 0000000..9590046
--- /dev/null
+++ b/src/pki/man/pki---gen.8.in
@@ -0,0 +1,112 @@
+.TH "PKI \-\-GEN" 8 "2013-07-31" "@PACKAGE_VERSION@" "strongSwan"
+.
+.SH "NAME"
+.
+pki \-\-gen \- Generate a new RSA or ECDSA private key
+.
+.SH "SYNOPSIS"
+.
+.SY pki\ \-\-gen
+.OP \-\-type type
+.OP \-\-size bits
+.OP \-\-safe\-primes
+.OP \-\-shares n
+.OP \-\-threshold l
+.OP \-\-outform encoding
+.OP \-\-debug level
+.YS
+.
+.SY pki\ \-\-gen
+.BI \-\-options\~ file
+.YS
+.
+.SY "pki \-\-gen"
+.B \-h
+|
+.B \-\-help
+.YS
+.
+.SH "DESCRIPTION"
+.
+This sub-command of
+.BR ipsec\-pki (8)
+is used to generate a new RSA or ECDSA private key.
+.
+.SH "OPTIONS"
+.
+.TP
+.B "\-h, \-\-help"
+Print usage information with a summary of the available options.
+.TP
+.BI "\-v, \-\-debug " level
+Set debug level, default: 1.
+.TP
+.BI "\-+, \-\-options " file
+Read command line options from \fIfile\fR.
+.TP
+.BI "\-t, \-\-type " type
+Type of key to generate. Either \fIrsa\fR or \fIecdsa\fR, defaults to \fIrsa\fR.
+.TP
+.BI "\-s, \-\-size " bits
+Key length in bits. Defaults to 2048 for \fIrsa\fR and 384 for \fIecdsa\fR.
+For \fIecdsa\fR only three values are currently supported: 256, 384 and 521.
+.TP
+.BI "\-p, \-\-safe\-primes"
+Generate RSA safe primes.
+.TP
+.BI "\-f, \-\-outform " encoding
+Encoding of the generated private key. Either \fIder\fR (ASN.1 DER) or \fIpem\fR
+(Base64 PEM), defaults
+to \fIder\fR.
+.PP
+.SS "RSA Threshold Cryptography"
+.TP
+.BI "\-n, \-\-shares " <n>
+Number of private RSA key shares.
+.TP
+.BI "\-l, \-\-threshold " <l>
+Minimum number of participating RSA key shares.
+.
+.SH "PROBLEMS ON HOSTS WITH LOW ENTROPY"
+.
+If the
+.I gmp
+plugin is used to generate RSA private keys the key material is read from
+.I /dev/random
+(via the
+.I random
+plugin). Therefore, the command may block if the system's entropy pool is empty.
+To avoid this, either use a hardware random number generator to feed
+.I /dev/random
+or use OpenSSL (via the
+.I openssl
+plugin or the command line) which is not as strict in regards to the quality of
+the key material (it reads from
+.I /dev/urandom
+if necessary). It is also possible to configure the devices used by the
+.I random
+plugin in
+.BR strongswan.conf (5).
+Setting
+.B libstrongswan.plugins.random.random
+to
+.I /dev/urandom
+forces the plugin to treat bytes read from
+.I /dev/urandom
+as high grade random data, thus avoiding the blocking. Of
+course, this doesn't change the fact that the key material generated this way is
+of lower quality.
+.
+.SH "EXAMPLES"
+.
+.TP
+.B ipsec pki \-\-gen \-\-size 3072 > rsa_key.der
+Generates a 3072-bit RSA private key.
+.
+.TP
+.B ipsec pki \-\-gen \-\-type ecdsa \-\-size 256 > ecdsa_key.der
+Generates a 256-bit ECDSA private key.
+.
+.SH "SEE ALSO"
+.
+.BR ipsec\-pki (8)
\ No newline at end of file