freeswan/doc/manpage.d/ipsec_rsasigkey.8.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_RSASIGKEY</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_RSASIGKEY</H1>
   6 Section: Maintenance Commands (8)<BR>Updated: 14 May 2001<BR><A HREF="#index">Index</A>
   7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
   8
   9
  10 <A NAME="lbAB">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec rsasigkey - generate RSA signature key
  14 <A NAME="lbAC">&nbsp;</A>
  15 <H2>SYNOPSIS</H2>
  16
  17 <B>ipsec</B>
  18
  19 <B>rsasigkey</B>
  20
  21 [
  22 <B>--verbose</B>
  23
  24 ] [
  25 <B>--random</B>
  26
  27 filename
  28 ]
  29 <B>\</B>
  30
  31 <BR>
  32
  33 &nbsp;&nbsp;&nbsp;[
  34 <B>--rounds</B>
  35
  36 nr
  37 ] [
  38 <B>--hostname</B>
  39
  40 host ] [
  41 <B>--noopt</B>
  42
  43 ] nbits
  44 <BR>
  45
  46 <B>ipsec</B>
  47
  48 <B>rsasigkey</B>
  49
  50 [
  51 <B>--verbose</B>
  52
  53 ] [
  54 <B>--hostname</B>
  55
  56 host ]
  57 <B>\</B>
  58
  59 <BR>
  60
  61 &nbsp;&nbsp;&nbsp;
  62 [
  63 <B>--noopt</B>
  64
  65 ]
  66 <B>--oldkey</B>
  67
  68 file
  69 <A NAME="lbAD">&nbsp;</A>
  70 <H2>DESCRIPTION</H2>
  71
  72 <I>Rsasigkey</I>
  73
  74 generates an RSA public/private key pair,
  75 suitable for digital signatures,
  76 of (exactly)
  77 <I>nbits</I>
  78
  79 bits (that is, two primes each of exactly
  80 <I>nbits</I>/2
  81
  82 bits,
  83 and related numbers)
  84 and emits it on standard output as ASCII (mostly hex) data.
  85 <I>nbits</I>
  86
  87 must be a multiple of 16.
  88 <P>
  89
  90 The public exponent is forced to the value
  91 <B>3</B>,
  92
  93 which has important speed advantages for signature checking.
  94 Beware that the resulting keys have known weaknesses as encryption keys
  95 <I>and should not be used for that purpose</I>.
  96 <P>
  97
  98 The
  99 <B>--verbose</B>
 100
 101 option makes
 102 <I>rsasigkey</I>
 103
 104 give a running commentary on standard error.
 105 By default, it works in silence until it is ready to generate output.
 106 <P>
 107
 108 The
 109 <B>--random</B>
 110
 111 option specifies a source for random bits.
 112 The default is
 113 <I>/dev/random</I>
 114
 115 (see
 116 <I><A HREF="random.4.html">random</A></I>(4)).
 117
 118 Normally,
 119 <I>rsasigkey</I>
 120
 121 reads exactly
 122 <I>nbits</I>
 123
 124 random bits from the source;
 125 in extremely-rare circumstances it may need more.
 126 <P>
 127
 128 The
 129 <B>--rounds</B>
 130
 131 option specifies the number of rounds to be done by the
 132 <I>mpz_probab_prime_p</I>
 133
 134 probabilistic primality checker.
 135 The default, 30, is fairly rigorous and should not normally
 136 have to be overridden.
 137 <P>
 138
 139 The
 140 <B>--hostname</B>
 141
 142 option specifies what host name to use in
 143 the first line of the output (see below);
 144 the default is what
 145 <I><A HREF="gethostname.2.html">gethostname</A></I>(2)
 146
 147 returns.
 148 <P>
 149
 150 The
 151 <B>--noopt</B>
 152
 153 option suppresses an optimization of the private key
 154 (to be precise, setting of the decryption exponent to
 155 <B>lcm(p-1,q-1)</B>
 156
 157 rather than
 158 <B>(p-1)*(q-1)</B>)
 159
 160 which speeds up operations on it slightly
 161 but can cause it to flunk a validity check in old RSA implementations
 162 (notably, obsolete versions of
 163 <I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8)).
 164
 165 <P>
 166
 167 The
 168 <B>--oldkey</B>
 169
 170 option specifies that rather than generate a new key,
 171 <I>rsasigkey</I>
 172
 173 should read an old key from the
 174 <I>file</I>
 175
 176 (the name
 177 <B>-</B>
 178
 179 means ``standard input'')
 180 and use that to generate its output.
 181 Input lines which do not look like
 182 <I>rsasigkey</I>
 183
 184 output are silently ignored.
 185 This permits updating old keys to the current format.
 186 <P>
 187
 188 The output format looks like this (with long numbers trimmed down
 189 for clarity):
 190 <P>
 191
 192
 193 <PRE>
 194         # RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
 195         # for signatures only, UNSAFE FOR ENCRYPTION
 196         #pubkey=0sAQOF8tZ2NZt...Y1P+buFuFn/
 197         #IN KEY 0x4200 4 1 AQOF8tZ2NZt...Y1P+buFuFn/
 198         # (0x4200 = auth-only host-level, 4 = IPSec, 1 = RSA)
 199         Modulus: 0xcc2a86fcf440...cf1011abb82d1
 200         PublicExponent: 0x03
 201         # everything after this point is secret
 202         PrivateExponent: 0x881c59fdf8...ab05c8c77d23
 203         Prime1: 0xf49fd1f779...46504c7bf3
 204         Prime2: 0xd5a9108453...321d43cb2b
 205         Exponent1: 0xa31536a4fb...536d98adda7f7
 206         Exponent2: 0x8e70b5ad8d...9142168d7dcc7
 207         Coefficient: 0xafb761d001...0c13e98d98
 208 </PRE>
 209
 210 <P>
 211
 212 The first (comment) line,
 213 indicating the nature and date of the key,
 214 and giving a host name,
 215 is used by
 216 <I><A HREF="ipsec_showhostkey.8.html">ipsec_showhostkey</A></I>(8)
 217
 218 when generating some forms of key output.
 219 <P>
 220
 221 The commented-out
 222 <B>pubkey=</B>
 223
 224 line contains the public key---the public exponent and the modulus---combined
 225 in approximately RFC 2537 format
 226 (the one deviation is that the combined value is given with a
 227 <B>0s</B>
 228
 229 prefix, rather than in unadorned base-64),
 230 suitable for use in the
 231 <I>ipsec.conf</I>
 232
 233 file.
 234 <P>
 235
 236 The commented-out
 237 <B>IN KEY</B>
 238
 239 line contains the public key in
 240 <I>exactly</I>
 241
 242 RFC 2537 format (except for the lack of a name on the front),
 243 suitable for use in DNS zone files.
 244 The flags, algorithm, and protocol fields are given numerically,
 245 with an accompanying explanation,
 246 because some incomplete early implementations of the KEY
 247 record (e.g., BIND 8.2.2-P5) don't support more mnemonic syntax.
 248 <P>
 249
 250 The
 251 <B>Modulus</B>,
 252
 253 <B>PublicExponent</B>,
 254
 255 and
 256 <B>PrivateExponent</B>
 257
 258 lines give the basic signing and verification data.
 259 <P>
 260
 261 The
 262 <B>Prime1</B>
 263
 264 and
 265 <B>Prime2</B>
 266
 267 lines give the primes themselves (aka
 268 <I>p</I>
 269
 270 and
 271 <I>q</I>),
 272
 273 largest first.
 274 The
 275 <B>Exponent1</B>
 276
 277 and
 278 <B>Exponent2</B>
 279
 280 lines give
 281 the private exponent mod
 282 <I>p-1</I>
 283
 284 and
 285 <I>q-1</I>
 286
 287 respectively.
 288 The
 289 <B>Coefficient</B>
 290
 291 line gives the Chinese Remainder Theorem coefficient,
 292 which is the inverse of
 293 <I>q</I>,
 294
 295 mod
 296 <I>p</I>.
 297
 298 These additional numbers (which must all be kept as secret as the
 299 private exponent) are precomputed aids to rapid signature generation.
 300 <P>
 301
 302 No attempt is made to break long lines.
 303 <P>
 304
 305 The US patent on the RSA algorithm expired 20 Sept 2000.
 306 <A NAME="lbAE">&nbsp;</A>
 307 <H2>EXAMPLES</H2>
 308
 309 <DL COMPACT>
 310 <DT><B>ipsec rsasigkey --verbose 2048 &gt;mykey</B>
 311
 312 <DD>
 313 generates a 2048-bit signature key and puts it in the file
 314 <I>mykey</I>,
 315
 316 with running commentary on standard error.
 317 The file contents can be inserted verbatim into a suitable entry in the
 318 <I>ipsec.secrets</I>
 319
 320 file (see
 321 <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5)),
 322
 323 and the public key can then be extracted and edited into the
 324 <I>ipsec.conf</I>
 325
 326 file (see
 327 <I><A HREF="ipsec.conf.5.html">ipsec.conf</A></I>(5)).
 328
 329 <DT><B>ipsec rsasigkey --verbose --oldkey oldie &gt;latest</B>
 330
 331 <DD>
 332 takes the old signature key from file
 333 <I>oldie</I>
 334
 335 and puts a version in the current format into the file
 336 <I>latest</I>,
 337
 338 with running commentary on standard error.
 339 </DL>
 340 <A NAME="lbAF">&nbsp;</A>
 341 <H2>FILES</H2>
 342
 343 /dev/random
 344 <A NAME="lbAG">&nbsp;</A>
 345 <H2>SEE ALSO</H2>
 346
 347 <A HREF="random.4.html">random</A>(4), <A HREF="ipsec_showhostkey.8.html">ipsec_showhostkey</A>(8)
 348 <BR>
 349
 350 <I>Applied Cryptography</I>, 2nd. ed., by Bruce Schneier, Wiley 1996.
 351 <BR>
 352
 353 RFCs 2537, 2313.
 354 <BR>
 355
 356 <I>GNU MP, the GNU multiple precision arithmetic library, edition 2.0.2</I>,
 357 by Torbj Granlund.
 358 <A NAME="lbAH">&nbsp;</A>
 359 <H2>HISTORY</H2>
 360
 361 Written for the Linux FreeS/WAN project
 362 &lt;<A HREF="http://www.freeswan.org">http://www.freeswan.org</A>&gt;
 363 by Henry Spencer.
 364 <A NAME="lbAI">&nbsp;</A>
 365 <H2>BUGS</H2>
 366
 367 There is an internal limit on
 368 <I>nbits</I>,
 369
 370 currently 20000.
 371 <P>
 372
 373 <I>Rsasigkey</I>'s
 374
 375 run time is difficult to predict,
 376 since
 377 <I>/dev/random</I>
 378
 379 output can be arbitrarily delayed if
 380 the system's entropy pool is low on randomness,
 381 and the time taken by the search for primes is also somewhat unpredictable.
 382 A reasonably typical time for a 1024-bit key on a quiet 200MHz Pentium MMX
 383 with plenty of randomness available is 20 seconds,
 384 almost all of it in the prime searches;
 385 generating a 2048-bit key on the same system usually takes several minutes.
 386 <P>
 387
 388 The
 389 <B>--oldkey</B>
 390
 391 option does not check its input format as rigorously as it might.
 392 Corrupted
 393 <I>rsasigkey</I>
 394
 395 output may confuse it.
 396 <P>
 397
 398 <HR>
 399 <A NAME="index">&nbsp;</A><H2>Index</H2>
 400 <DL>
 401 <DT><A HREF="#lbAB">NAME</A><DD>
 402 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 403 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 404 <DT><A HREF="#lbAE">EXAMPLES</A><DD>
 405 <DT><A HREF="#lbAF">FILES</A><DD>
 406 <DT><A HREF="#lbAG">SEE ALSO</A><DD>
 407 <DT><A HREF="#lbAH">HISTORY</A><DD>
 408 <DT><A HREF="#lbAI">BUGS</A><DD>
 409 </DL>
 410 <HR>
 411 This document was created by
 412 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 413 using the manual pages.<BR>
 414 Time: 05:09:32 GMT, June 19, 2001
 415 </BODY>
 416 </HTML>