diff options
Diffstat (limited to 'programs/rsasigkey/rsasigkey.8')
| -rw-r--r-- | programs/rsasigkey/rsasigkey.8 | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/programs/rsasigkey/rsasigkey.8 b/programs/rsasigkey/rsasigkey.8 new file mode 100644 index 000000000..c64dd46bd --- /dev/null +++ b/programs/rsasigkey/rsasigkey.8 @@ -0,0 +1,259 @@ +.TH IPSEC_RSASIGKEY 8 "22 July 2001" +.\" RCSID $Id: rsasigkey.8,v 1.1 2004/03/15 20:35:30 as Exp $ +.SH NAME +ipsec rsasigkey \- generate RSA signature key +.SH SYNOPSIS +.B ipsec +.B rsasigkey +[ +.B \-\-verbose +] [ +.B \-\-random +filename +] +.B \e +.br +\ \ \ [ +.B \-\-rounds +nr +] [ +.B \-\-hostname +host ] [ +.B \-\-noopt +] nbits +.br +.B ipsec +.B rsasigkey +[ +.B \-\-verbose +] [ +.B \-\-hostname +host ] +.B \e +.br +\ \ \ +[ +.B \-\-noopt +] +.B \-\-oldkey +file +.SH DESCRIPTION +.I Rsasigkey +generates an RSA public/private key pair, +suitable for digital signatures, +of (exactly) +.I nbits +bits (that is, two primes each of exactly +.IR nbits /2 +bits, +and related numbers) +and emits it on standard output as ASCII (mostly hex) data. +.I nbits +must be a multiple of 16. +.PP +The public exponent is forced to the value +.BR 3 , +which has important speed advantages for signature checking. +Beware that the resulting keys have known weaknesses as encryption keys +\fIand should not be used for that purpose\fR. +.PP +The +.B \-\-verbose +option makes +.I rsasigkey +give a running commentary on standard error. +By default, it works in silence until it is ready to generate output. +.PP +The +.B \-\-random +option specifies a source for random bits. +The default is +.I /dev/random +(see +.IR random (4)). +Normally, +.I rsasigkey +reads exactly +.I nbits +random bits from the source; +in extremely-rare circumstances it may need more. +.PP +The +.B \-\-rounds +option specifies the number of rounds to be done by the +.I mpz_probab_prime_p +probabilistic primality checker. +The default, 30, is fairly rigorous and should not normally +have to be overridden. +.PP +The +.B \-\-hostname +option specifies what host name to use in +the first line of the output (see below); +the default is what +.IR gethostname (2) +returns. +.PP +The +.B \-\-noopt +option suppresses an optimization of the private key +(to be precise, setting of the decryption exponent to +.B lcm(p\-1,q\-1) +rather than +.BR (p\-1)*(q\-1) ) +which speeds up operations on it slightly +but can cause it to flunk a validity check in old RSA implementations +(notably, obsolete versions of +.IR ipsec_pluto (8)). +.PP +The +.B \-\-oldkey +option specifies that rather than generate a new key, +.I rsasigkey +should read an old key from the +.I file +(the name +.B \- +means ``standard input'') +and use that to generate its output. +Input lines which do not look like +.I rsasigkey +output are silently ignored. +This permits updating old keys to the current format. +.PP +The output format looks like this (with long numbers trimmed down +for clarity): +.PP +.ne 15 +.nf + # RSA 2048 bits xy.example.com Sat Apr 15 13:53:22 2000 + # for signatures only, UNSAFE FOR ENCRYPTION + #pubkey=0sAQOF8tZ2NZt...Y1P+buFuFn/ + Modulus: 0xcc2a86fcf440...cf1011abb82d1 + PublicExponent: 0x03 + # everything after this point is secret + PrivateExponent: 0x881c59fdf8...ab05c8c77d23 + Prime1: 0xf49fd1f779...46504c7bf3 + Prime2: 0xd5a9108453...321d43cb2b + Exponent1: 0xa31536a4fb...536d98adda7f7 + Exponent2: 0x8e70b5ad8d...9142168d7dcc7 + Coefficient: 0xafb761d001...0c13e98d98 +.fi +.PP +The first (comment) line, +indicating the nature and date of the key, +and giving a host name, +is used by +.IR ipsec_showhostkey (8) +when generating some forms of key output. +.PP +The commented-out +.B pubkey= +line contains the public key\(emthe public exponent and the modulus\(emcombined +in approximately RFC 2537 format +(the one deviation is that the combined value is given with a +.B 0s +prefix, rather than in unadorned base-64), +suitable for use in the +.I ipsec.conf +file. +.PP +The +.BR Modulus , +.BR PublicExponent , +and +.B PrivateExponent +lines give the basic signing and verification data. +.PP +The +.B Prime1 +and +.B Prime2 +lines give the primes themselves (aka +.I p +and +.IR q ), +largest first. +The +.B Exponent1 +and +.B Exponent2 +lines give +the private exponent mod +.IR p\-1 +and +.IR q\-1 +respectively. +The +.B Coefficient +line gives the Chinese Remainder Theorem coefficient, +which is the inverse of +.IR q , +mod +.IR p . +These additional numbers (which must all be kept as secret as the +private exponent) are precomputed aids to rapid signature generation. +.PP +No attempt is made to break long lines. +.PP +The US patent on the RSA algorithm expired 20 Sept 2000. +.SH EXAMPLES +.TP +.B "ipsec rsasigkey \-\-verbose 2192 >mykey" +generates a 2192-bit signature key and puts it in the file +.IR mykey , +with running commentary on standard error. +The file contents can be inserted verbatim into a suitable entry in the +.I ipsec.secrets +file (see +.IR ipsec.secrets (5)), +and the public key can then be extracted and edited into the +.I ipsec.conf +file (see +.IR ipsec.conf (5)). +.TP +.B "ipsec rsasigkey \-\-verbose \-\-oldkey oldie >latest" +takes the old signature key from file +.I oldie +and puts a version in the current format into the file +.IR latest , +with running commentary on standard error. +.SH FILES +/dev/random +.SH SEE ALSO +random(4), ipsec_showhostkey(8) +.br +\fIApplied Cryptography\fR, 2nd. ed., by Bruce Schneier, Wiley 1996. +.br +RFCs 2537, 2313. +.br +\fIGNU MP, the GNU multiple precision arithmetic library, edition 2.0.2\fR, +by Torbj Granlund. +.SH HISTORY +Written for the Linux FreeS/WAN project +<http://www.freeswan.org> +by Henry Spencer. +.SH BUGS +There is an internal limit on +.IR nbits , +currently 20000. +.PP +.IR Rsasigkey 's +run time is difficult to predict, +since +.I /dev/random +output can be arbitrarily delayed if +the system's entropy pool is low on randomness, +and the time taken by the search for primes is also somewhat unpredictable. +A reasonably typical time for a 1024-bit key on a quiet 200MHz Pentium MMX +with plenty of randomness available is 20 seconds, +almost all of it in the prime searches. +Generating a 2192-bit key on the same system usually takes several minutes. +A 4096-bit key took an hour and a half of CPU time. +.PP +The +.B \-\-oldkey +option does not check its input format as rigorously as it might. +Corrupted +.I rsasigkey +output may confuse it. |