IPSEC_RSASIGKEY(8)			       IPSEC_RSASIGKEY(8)


NAME
       ipsec rsasigkey - generate RSA signature key

SYNOPSIS
       ipsec rsasigkey [ --verbose ] [ --random filename ] \
	  [ --rounds nr ] [ --hostname host ] nbits
       ipsec rsasigkey [ --verbose ] [ --hostname host ] \
	   --oldkey file

DESCRIPTION
       Rsasigkey  generates an RSA public/private key pair, suit-
       able for digital signatures, of (exactly) nbits bits (that
       is,  two	 primes each of exactly nbits/2 bits, and related
       numbers) and emits it on standard output as ASCII  (mostly
       hex) data.  nbits must be a multiple of 16.

       The  public  exponent  is forced to the value 3, which has
       important speed advantages for signature checking.  Beware
       that  the  resulting keys have known weaknesses as encryp-
       tion keys and should not be used for that purpose.

       The --verbose option makes rsasigkey give a  running  com-
       mentary	on  standard  error.   By  default,  it	 works in
       silence until it is ready to generate output.

       The --random option specifies a source  for  random  bits.
       The  default  is	 /dev/random  (see random(4)).	Normally,
       rsasigkey reads exactly nbits random bits from the source;
       in extremely-rare circumstances it may need more.

       The  --rounds  option specifies the number of rounds to be
       done by	the  mpz_probab_prime_p	 probabilistic	primality
       checker.	  The  default, 30, is fairly rigorous and should
       not normally have to be overridden.

       The --hostname option specifies what host name to  use  in
       the  first  line of the output (see below); the default is
       what gethostname(2) returns.

       The --oldkey option specifies that rather than generate	a
       new  key,  rsasigkey  should read an old key from the file
       (the name - means ``standard input'') and use that to gen-
       erate  its  output.   Input  lines  which do not look like
       rsasigkey  output  are  silently	 ignored.   This  permits
       updating old keys to the current format.

       The  output  format  looks  like	 this  (with long numbers
       trimmed down for clarity):









			   12 Sept 2000				1





IPSEC_RSASIGKEY(8)			       IPSEC_RSASIGKEY(8)


	    # RSA 2048 bits   name.example   Sat Apr 15 13:53:22 2000
	    # for signatures only, UNSAFE FOR ENCRYPTION
	    #pubkey=0x0103cc2a86fcf440...cf1011abb82d1
	    #IN KEY 0x4200 4 1 AQOF8tZ2NZt...Y1P+buFuFn/
	    # (0x4200 = auth-only host-level, 4 = IPSec, 1 = RSA)
	    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

       The commented-out pubkey= line contains the  public  key--
       the  public exponent and the modulus--combined in approxi-
       mately RFC 2537 format (the one deviation is that the com-
       bined  value is given in hex with a 0x prefix, rather than
       in unadorned base-64), suitable for use in the  ipsec.conf
       file.

       The  commented-out  IN KEY line contains the public key in
       exactly RFC 2537 format (except for the lack of a name  on
       the  front),  suitable  for  use	 in  DNS zone files.  The
       flags, algorithm, and protocol fields  are  given  numeri-
       cally,  with  an	 accompanying  explanation,  because some
       incomplete early implementations of the KEY record  (e.g.,
       BIND 8.2.2-P5) don't support more mnemonic syntax.

       The  Modulus,  PublicExponent,  and  PrivateExponent lines
       give the basic signing and verification data.

       The Prime1 and Prime2 lines  give  the  primes  themselves
       (aka p and q), largest first.  The Exponent1 and Exponent2
       lines give the private exponent mod p-1	and  q-1  respec-
       tively.	 The Coefficient line gives the Chinese Remainder
       Theorem coefficient, which is the inverse  of  q,  mod  p.
       These additional numbers (which must all be kept as secret
       as the private exponent) are  precomputed  aids	to  rapid
       signature generation.

       No attempt is made to break long lines.

EXAMPLES
       ipsec rsasigkey --verbose 2048 >mykey
	      generates	 a  2048-bit signature key and puts it in
	      the file mykey, with running commentary on standard
	      error.   The file contents can be inserted verbatim
	      into a suitable entry  in	 the  ipsec.secrets  file
	      (see ipsec.secrets(5)), and the public key can then
	      be extracted and edited into  the	 ipsec.conf  file
	      (see ipsec.conf(5)).




			   12 Sept 2000				2





IPSEC_RSASIGKEY(8)			       IPSEC_RSASIGKEY(8)


       ipsec rsasigkey --verbose --oldkey oldie >latest
	      takes  the  old  signature  key from file oldie and
	      puts a version in the current format into the  file
	      latest,  with running commentary on standard error.

FILES
       /dev/random

SEE ALSO
       random(4)
       Applied Cryptography, 2nd. ed., by Bruce	 Schneier,  Wiley
       1996.
       RFCs 2537, 2313.
       GNU  MP,	 the  GNU  multiple precision arithmetic library,
       edition 2.0.2, by Torbj Granlund.

HISTORY
       Written	  for	  the	  Linux	    FreeS/WAN	  project
       <http://www.xs4all.nl/~freeswan/> by Henry Spencer.

BUGS
       There is an internal limit on nbits, currently 20000.

       Rsasigkey's  run	 time  is  difficult  to  predict,  since
       /dev/random output can be arbitrarily delayed if the  sys-
       tem's  entropy  pool  is	 low  on randomness, and the time
       taken by the search for primes  is  also	 somewhat  unpre-
       dictable.  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 2048-bit key  on	the  same  system
       usually takes several minutes.

       The  --oldkey  option  does  not check its input format as
       rigorously as it might.	Corrupted  rsasigkey  output  may
       confuse it.

       This  program  makes  no use of code furnished by RSA Data
       Security Inc. or Public Key Partners.  However, the  tech-
       niques used would appear to be covered (in the USA) by the
       US patent on the RSA  algorithm,	 which	expires	 20  Sept
       2000.















			   12 Sept 2000				3


