freeswan/utils/rsasigkey.8

   1 .TH IPSEC_RSASIGKEY 8 "22 July 2001"
   2 .\" RCSID $Id: rsasigkey.8,v 1.19 2002/04/01 20:05:27 mcr Exp $
   3 .SH NAME
   4 ipsec rsasigkey \- generate RSA signature key
   5 .SH SYNOPSIS
   6 .B ipsec
   7 .B rsasigkey
   8 [
   9 .B \-\-verbose
  10 ] [
  11 .B \-\-random
  12 filename
  13 ]
  14 .B \e
  15 .br
  16 \ \ \ [
  17 .B \-\-rounds
  18 nr
  19 ] [
  20 .B \-\-hostname
  21 host ] [
  22 .B \-\-noopt
  23 ] nbits
  24 .br
  25 .B ipsec
  26 .B rsasigkey
  27 [
  28 .B \-\-verbose
  29 ] [
  30 .B \-\-hostname
  31 host ]
  32 .B \e
  33 .br
  34 \ \ \
  35 [
  36 .B \-\-noopt
  37 ]
  38 .B \-\-oldkey
  39 file
  40 .SH DESCRIPTION
  41 .I Rsasigkey
  42 generates an RSA public/private key pair,
  43 suitable for digital signatures,
  44 of (exactly)
  45 .I nbits
  46 bits (that is, two primes each of exactly
  47 .IR nbits /2
  48 bits,
  49 and related numbers)
  50 and emits it on standard output as ASCII (mostly hex) data.
  51 .I nbits
  52 must be a multiple of 16.
  53 .PP
  54 The public exponent is forced to the value
  55 .BR 3 ,
  56 which has important speed advantages for signature checking.
  57 Beware that the resulting keys have known weaknesses as encryption keys
  58 \fIand should not be used for that purpose\fR.
  59 .PP
  60 The
  61 .B \-\-verbose
  62 option makes
  63 .I rsasigkey
  64 give a running commentary on standard error.
  65 By default, it works in silence until it is ready to generate output.
  66 .PP
  67 The
  68 .B \-\-random
  69 option specifies a source for random bits.
  70 The default is
  71 .I /dev/random
  72 (see
  73 .IR random (4)).
  74 Normally,
  75 .I rsasigkey
  76 reads exactly
  77 .I nbits
  78 random bits from the source;
  79 in extremely-rare circumstances it may need more.
  80 .PP
  81 The
  82 .B \-\-rounds
  83 option specifies the number of rounds to be done by the
  84 .I mpz_probab_prime_p
  85 probabilistic primality checker.
  86 The default, 30, is fairly rigorous and should not normally
  87 have to be overridden.
  88 .PP
  89 The
  90 .B \-\-hostname
  91 option specifies what host name to use in
  92 the first line of the output (see below);
  93 the default is what
  94 .IR gethostname (2)
  95 returns.
  96 .PP
  97 The
  98 .B \-\-noopt
  99 option suppresses an optimization of the private key
 100 (to be precise, setting of the decryption exponent to
 101 .B lcm(p\-1,q\-1)
 102 rather than
 103 .BR (p\-1)*(q\-1) )
 104 which speeds up operations on it slightly
 105 but can cause it to flunk a validity check in old RSA implementations
 106 (notably, obsolete versions of
 107 .IR ipsec_pluto (8)).
 108 .PP
 109 The
 110 .B \-\-oldkey
 111 option specifies that rather than generate a new key,
 112 .I rsasigkey
 113 should read an old key from the
 114 .I file
 115 (the name
 116 .B \-
 117 means ``standard input'')
 118 and use that to generate its output.
 119 Input lines which do not look like
 120 .I rsasigkey
 121 output are silently ignored.
 122 This permits updating old keys to the current format.
 123 .PP
 124 The output format looks like this (with long numbers trimmed down
 125 for clarity):
 126 .PP
 127 .ne 15
 128 .nf
 129         # RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
 130         # for signatures only, UNSAFE FOR ENCRYPTION
 131         #pubkey=0sAQOF8tZ2NZt...Y1P+buFuFn/
 132         #IN KEY 0x4200 4 1 AQOF8tZ2NZt...Y1P+buFuFn/
 133         # (0x4200 = auth-only host-level, 4 = IPSec, 1 = RSA)
 134         Modulus: 0xcc2a86fcf440...cf1011abb82d1
 135         PublicExponent: 0x03
 136         # everything after this point is secret
 137         PrivateExponent: 0x881c59fdf8...ab05c8c77d23
 138         Prime1: 0xf49fd1f779...46504c7bf3
 139         Prime2: 0xd5a9108453...321d43cb2b
 140         Exponent1: 0xa31536a4fb...536d98adda7f7
 141         Exponent2: 0x8e70b5ad8d...9142168d7dcc7
 142         Coefficient: 0xafb761d001...0c13e98d98
 143 .fi
 144 .PP
 145 The first (comment) line,
 146 indicating the nature and date of the key,
 147 and giving a host name,
 148 is used by
 149 .IR ipsec_showhostkey (8)
 150 when generating some forms of key output.
 151 .PP
 152 The commented-out
 153 .B pubkey=
 154 line contains the public key\(emthe public exponent and the modulus\(emcombined
 155 in approximately RFC 2537 format
 156 (the one deviation is that the combined value is given with a
 157 .B 0s
 158 prefix, rather than in unadorned base-64),
 159 suitable for use in the
 160 .I ipsec.conf
 161 file.
 162 .PP
 163 The commented-out
 164 .B "IN KEY"
 165 line contains the public key in
 166 .I exactly
 167 RFC 2537 format (except for the lack of a name on the front),
 168 suitable for use in DNS zone files.
 169 The flags, algorithm, and protocol fields are given numerically,
 170 with an accompanying explanation,
 171 because some incomplete early implementations of the KEY
 172 record (e.g., BIND 8.2.2-P5) don't support more mnemonic syntax.
 173 .PP
 174 The
 175 .BR Modulus ,
 176 .BR PublicExponent ,
 177 and
 178 .B PrivateExponent
 179 lines give the basic signing and verification data.
 180 .PP
 181 The
 182 .B Prime1
 183 and
 184 .B Prime2
 185 lines give the primes themselves (aka
 186 .I p
 187 and
 188 .IR q ),
 189 largest first.
 190 The
 191 .B Exponent1
 192 and
 193 .B Exponent2
 194 lines give
 195 the private exponent mod
 196 .IR p\-1
 197 and
 198 .IR q\-1
 199 respectively.
 200 The
 201 .B Coefficient
 202 line gives the Chinese Remainder Theorem coefficient,
 203 which is the inverse of
 204 .IR q ,
 205 mod
 206 .IR p .
 207 These additional numbers (which must all be kept as secret as the
 208 private exponent) are precomputed aids to rapid signature generation.
 209 .PP
 210 No attempt is made to break long lines.
 211 .PP
 212 The US patent on the RSA algorithm expired 20 Sept 2000.
 213 .SH EXAMPLES
 214 .TP
 215 .B "ipsec rsasigkey \-\-verbose 2192 >mykey"
 216 generates a 2192-bit signature key and puts it in the file
 217 .IR mykey ,
 218 with running commentary on standard error.
 219 The file contents can be inserted verbatim into a suitable entry in the
 220 .I ipsec.secrets
 221 file (see
 222 .IR ipsec.secrets (5)),
 223 and the public key can then be extracted and edited into the
 224 .I ipsec.conf
 225 file (see
 226 .IR ipsec.conf (5)).
 227 .TP
 228 .B "ipsec rsasigkey \-\-verbose \-\-oldkey oldie >latest"
 229 takes the old signature key from file
 230 .I oldie
 231 and puts a version in the current format into the file
 232 .IR latest ,
 233 with running commentary on standard error.
 234 .SH FILES
 235 /dev/random
 236 .SH SEE ALSO
 237 random(4), ipsec_showhostkey(8)
 238 .br
 239 \fIApplied Cryptography\fR, 2nd. ed., by Bruce Schneier, Wiley 1996.
 240 .br
 241 RFCs 2537, 2313.
 242 .br
 243 \fIGNU MP, the GNU multiple precision arithmetic library, edition 2.0.2\fR,
 244 by Torbj Granlund.
 245 .SH HISTORY
 246 Written for the Linux FreeS/WAN project
 247 <http://www.freeswan.org>
 248 by Henry Spencer.
 249 .SH BUGS
 250 There is an internal limit on
 251 .IR nbits ,
 252 currently 20000.
 253 .PP
 254 .IR Rsasigkey 's
 255 run time is difficult to predict,
 256 since
 257 .I /dev/random
 258 output can be arbitrarily delayed if
 259 the system's entropy pool is low on randomness,
 260 and the time taken by the search for primes is also somewhat unpredictable.
 261 A reasonably typical time for a 1024-bit key on a quiet 200MHz Pentium MMX
 262 with plenty of randomness available is 20 seconds,
 263 almost all of it in the prime searches.
 264 Generating a 2192-bit key on the same system usually takes several minutes.
 265 A 4096-bit key took an hour and a half of CPU time.
 266 .PP
 267 The
 268 .B \-\-oldkey
 269 option does not check its input format as rigorously as it might.
 270 Corrupted
 271 .I rsasigkey
 272 output may confuse it.