freeswan/utils/newhostkey.8

   1 .TH IPSEC_NEWHOSTKEY 8 "4 March 2002"
   2 .\" RCSID $Id: newhostkey.8,v 1.4 2002/04/01 20:05:27 mcr Exp $
   3 .SH NAME
   4 ipsec newhostkey \- generate a new host authentication key
   5 .SH SYNOPSIS
   6 .B ipsec
   7 .B newhostkey
   8 .B \-\-output
   9 filename
  10 [
  11 .B \-\-quiet
  12 ]
  13 .B \e
  14 .br
  15 .in +10
  16 [
  17 .B \-\-bits
  18 n
  19 ]
  20 [
  21 .B \-\-hostname
  22 host
  23 ]
  24 .SH DESCRIPTION
  25 .I Newhostkey
  26 outputs (into
  27 .IR filename ,
  28 which can be `\fB-\fR' for standard output)
  29 an RSA private key suitable for this host,
  30 in
  31 .IR /etc/ipsec.secrets
  32 format
  33 (see
  34 .IR ipsec.secrets (5)).
  35 Normally,
  36 .I newhostkey
  37 invokes
  38 .IR rsasigkey
  39 (see
  40 .IR ipsec_rsasigkey (8))
  41 with the
  42 .B \-\-verbose
  43 option, so a narrative of what is being done appears on standard error.
  44 .PP
  45 The
  46 .B \-\-output
  47 specifier, although it is syntactically an option and can appear at
  48 any point among the options (it doesn't have to be first),
  49 is not optional.
  50 The specified
  51 .I filename
  52 is created under umask
  53 .B 077
  54 if nonexistent;
  55 if it already exists and is non-empty,
  56 a warning message about that is sent to standard error,
  57 and the output is appended to the file.
  58 .PP
  59 The
  60 .B \-\-quiet
  61 option suppresses both the
  62 .IR rsasigkey
  63 narrative and the existing-file warning message.
  64 .PP
  65 The
  66 .B \-\-bits
  67 option specifies the number of bits in the key;
  68 the current default is 2192 and we do not recommend use of anything
  69 shorter unless unusual constraints demand it.
  70 .PP
  71 The
  72 .B \-\-hostname
  73 option is passed through to
  74 .IR rsasigkey
  75 to tell it what host name to label the output with
  76 (via its
  77 .B \-\-hostname
  78 option).
  79 .PP
  80 The output format is that of
  81 .IR rsasigkey ,
  82 with bracketing added to complete the
  83 .I ipsec.secrets
  84 format.
  85 In the usual case, where
  86 .I ipsec.secrets
  87 contains only the host's own private key,
  88 the output of
  89 .I newhostkey
  90 is sufficient as a complete
  91 .I ipsec.secrets
  92 file.
  93 .SH SEE ALSO
  94 ipsec.secrets(5), ipsec_rsasigkey(8)
  95 .SH HISTORY
  96 Written for the Linux FreeS/WAN project
  97 <http://www.freeswan.org>
  98 by Henry Spencer.
  99 .SH BUGS
 100 As with
 101 .IR rsasigkey ,
 102 the run time is difficult to predict,
 103 since depletion of the system's randomness pool can cause
 104 arbitrarily long waits for random bits,
 105 and the prime-number searches can also take unpredictable
 106 (and potentially large) amounts of CPU time.
 107 See
 108 .IR ipsec_rsasigkey (8)
 109 for some typical performance numbers.
 110 .PP
 111 A higher-level tool which could handle the clerical details
 112 of changing to a new key would be helpful.
 113 .PP
 114 The requirement for
 115 .B \-\-output
 116 is a blemish,
 117 but private keys are extremely sensitive information
 118 and unusual precautions seem justified.