'\" t .\" Title: IPSEC_RSASIGKEY .\" Author: Paul Wouters .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 05/13/2020 .\" Manual: Executable programs .\" Source: libreswan .\" Language: English .\" .TH "IPSEC_RSASIGKEY" "8" "05/13/2020" "libreswan" "Executable programs" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" ipsec_rsasigkey \- generate RSA signature key .SH "SYNOPSIS" .HP \w'\fBipsec\fR\ 'u \fBipsec\fR \fIrsasigkey\fR [\-\-verbose] [\-\-seeddev\ \fIdevice\fR] [\-\-seed\ \fInumbits\fR] [\-\-nssdir\ \fInssdir\fR] [\-\-password\ \fInsspassword\fR] [\-\-hostname\ \fIhostname\fR] [nbits] .SH "DESCRIPTION" .PP \fIrsasigkey\fR generates an RSA public/private key pair, suitable for digital signatures, of (exactly) \fInbits\fR bits (that is, two primes each of exactly \fInbits\fR/2 bits, and related numbers) and emits it on standard output as ASCII (mostly hex) data\&. \fInbits\fR must be a multiple of 16\&. .PP The public exponent is forced to the value \fB3\fR, which has important speed advantages for signature checking\&. Beware that the resulting keys have known weaknesses as encryption keys \fBand should not be used for that purpose\fR\&. .PP The \fB\-\-verbose\fR option makes \fIrsasigkey\fR give a running commentary on standard error\&. By default, it works in silence until it is ready to generate output\&. .PP The \fB\-\-seeddev\fR option specifies a source for random bits used to seed the crypto library\*(Aqs RNG\&. The default is /dev/random (see \fBrandom\fR(4))\&. FreeS/WAN and Openswan without NSS support used this option to specify the random source used to directly create keys\&. Libreswan only uses it to seed the NSS crypto libraries RNG\&. Under Linux with hardware random support, special devices might show up as /dev/*rng* devices\&. However, these should never be accessed directly using this option, as hardware failures could lead to extremely non\-random values (streams of zeroes have been observed in the wild) .PP The \fB\-\-seedbits\fR option specifies how many seed bits are pulled from the random device to seed the NSS PRNG\&. The default of 480bit comes from FIPS requirements\&. Seed bits are rounded up to a multiple of 8\&. .PP The use of a different random device or a reduction of seedbits from the default value is prevented when the system is running in FIPS mode\&. .PP The \fB\-\-nssdir\fR option specifies the directory to use for the nss database\&. This is the directory where the NSS certificate, key and security modules databases reside\&. The default value is /var/lib/ipsec/nss\&. .PP The \fB\-\-password\fR option specifies the nss cryptographic module authentication password if the NSS module has been configured to require it\&. A password is required by hardware tokens and also by the internal software token module when configured to run in FIPS mode\&. If the argument is \fI/etc/ipsec\&.d\fR/nsspassword, the password comes from that file; otherwise argument is the password\&. .PP The \fB\-\-hostname\fR option specifies what host name to use in the first line of the output (see below); the default is what \fBgethostname\fR(2) returns\&. .PP The output format looks like this (with long numbers trimmed down for clarity): .sp .if n \{\ .RS 4 .\} .nf # RSA 3744 bits road\&.toad\&.com Mon Apr 17 22:20:35 2017 # for signatures only, UNSAFE FOR ENCRYPTION #ckaid=a953473e6014dd4e08eb051e4679dc39be160fea #pubkey=0sBAEAA\&.\&.\&.sKbTzwE= Modulus: 0xb84ae7d\&.\&.\&.b0a6d3cf01 PublicExponent: 0x010001 .fi .if n \{\ .RE .\} .sp The first (comment) line, indicating the nature and date of the key, and giving a host name, is used by \fBipsec_showhostkey\fR(8) when generating some forms of key output\&. .PP The commented\-out \fBpubkey=\fR line contains the public key, the public exponent and the modulus combined in approximately RFC 2537 format (the one deviation is that the combined value is given with a \fI0s\fR prefix, rather than in unadorned base\-64), suitable for use in the ipsec\&.conf file\&. .PP The \fBModulus\fR, \fBPublicExponent\fR and \fBPrivateExponent\fR lines give the basic signing and verification data\&. .PP The \fBPrime1\fR and \fBPrime2\fR lines give the primes themselves (aka \fIp\fR and \fIq\fR), largest first\&. The \fBExponent1\fR and \fBExponent2\fR lines give the private exponent mod \fIp\-1\fR and \fIq\-1\fR respectively\&. The \fBCoefficient\fR line gives the Chinese Remainder Theorem coefficient, which is the inverse of \fIq\fR, mod \fIp\fR\&. These additional numbers (which must all be kept as secret as the private exponent) are precomputed aids to rapid signature generation\&. When NSS is used, these values are not available outside the NSS security database (software token or hardware token) and are instead filled in with the CKA_ID\&. .PP No attempt is made to break long lines\&. .PP The US patent on the RSA algorithm expired 20 Sept 2000\&. .SH "EXAMPLES" .PP \fBipsec rsasigkey \-\-verbose 4096 >mykey\&.txt\fR .RS 4 generates a 4096\-bit signature key and puts it in the file mykey\&.txt, with running commentary on standard error\&. The file contents can be inserted verbatim into a suitable entry in the ipsec\&.secrets file (see \fBipsec_secrets\fR(5)), and the public key can then be extracted and edited into the ipsec\&.conf (see \fBipsec_showhostkey\fR(8))\&. .RE .SH "FILES" .PP /dev/random, /dev/urandom .SH "SEE ALSO" .PP \fBrandom\fR(4), \fBrngd\fR(8), \fBipsec_showhostkey\fR(8), \fIApplied Cryptography, 2nd\&. ed\&., by Bruce Schneier, Wiley 1996\fR, \fIRFCs 2537, 2313\fR, \fIGNU MP, the GNU multiple precision arithmetic library, edition 2\&.0\&.2, by Torbj Granlund\fR .SH "HISTORY" .PP Originally written for the Linux FreeS/WAN project <\m[blue]\fBhttp://www\&.freeswan\&.org\fR\m[]> by Henry Spencer\&. Updated for the Libreswan Project by Paul Wouters\&. .PP The \fI\-\-round\fR and \fI\-\-noopt\fR options were obsoleted as these were only used with the old non\-library crypto code .PP The \fI\-\-random\fR device is only used for seeding the crypto library, not for direct random to generate keys .SH "BUGS" .PP There is an internal limit on \fInbits\fR, currently 20000\&. .PP \fIrsasigkey\fR\*(Aqs run time is difficult to predict, since /dev/random output can be arbitrarily delayed if the system\*(Aqs entropy pool is low on randomness, and the time taken by the search for primes is also somewhat unpredictable\&. Specifically, embedded systems and most virtual machines are low on entropy\&. In such a situation, consider generating the RSA key on another machine, and copying ipsec\&.secrets and the /var/lib/ipsec/nss directory tree to the embedded platform\&. Note that NSS embeds the full path in the DB files, so the path on proxy machine must be identical to the path on the destination machine\&. .SH "AUTHOR" .PP \fBPaul Wouters\fR .RS 4 placeholder to suppress warning .RE