freeswan/utils/showhostkey.8

   1 .TH IPSEC_SHOWHOSTKEY 8 "5 March 2002"
   2 .\" RCSID $Id: showhostkey.8,v 1.11 2002/03/05 20:18:04 henry Exp $
   3 .SH NAME
   4 ipsec showhostkey \- show host's authentication key
   5 .SH SYNOPSIS
   6 .B ipsec
   7 .B showhostkey
   8 [
   9 .B \-\-left
  10 ] [
  11 .B \-\-right
  12 ] [
  13 .B \-\-txt
  14 gateway
  15 ] [
  16 .B \-\-file
  17 secretfile
  18 ] [
  19 .B \-\-id
  20 identity
  21 ]
  22 .SH DESCRIPTION
  23 .I Showhostkey
  24 outputs (on standard output) a public key suitable for this host,
  25 using the host key information stored in
  26 .IR /etc/ipsec.secrets .
  27 In general only the super-user can run this command,
  28 since only he can read
  29 .IR ipsec.secrets .
  30 .PP
  31 By default, the output format is the text form of a DNS KEY record;
  32 the host name is the one included in the key information
  33 (or, if that is not available,
  34 the output of
  35 .BR "hostname\ \-\-fqdn" ),
  36 with a
  37 .B \&.
  38 appended.
  39 If information about how the key was generated is available,
  40 that is provided as a DNS-file comment.
  41 For example (with the key data trimmed down for clarity):
  42 .PP
  43 .nf
  44   ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
  45   xy.example.com.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/
  46 .fi
  47 .PP
  48 The
  49 .B \-\-txt
  50 option causes the output to be in opportunistic-encryption DNS TXT record
  51 format,
  52 with the specified
  53 .I gateway
  54 value.
  55 Again, generation information is included if available.
  56 For example,
  57 .B "\-\-txt 10.11.12.13"
  58 might give (with the key data trimmed for clarity):
  59 .PP
  60 .nf
  61   ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
  62       IN TXT  "X-IPsec-Server(10)=10.11.12.13 AQOF8tZ2...+buFuFn/"
  63 .fi
  64 .PP
  65 No name is supplied in the TXT record
  66 because there are too many possibilities,
  67 depending on how it will be used.
  68 If the text string is longer than 255 bytes,
  69 it is split up into multiple strings (matching the restrictions of
  70 the DNS TXT binary format) in a way that is compatible with
  71 BIND 8's automatic splitter.
  72 .PP
  73 The
  74 .B \-\-left
  75 and
  76 .B \-\-right
  77 options cause the output to be in
  78 .IR ipsec.conf (5)
  79 format, as a
  80 .B leftrsasigkey
  81 or
  82 .B rightrsasigkey
  83 parameter respectively.
  84 Again, generation information is included if available.
  85 For example,
  86 .B \-\-left
  87 might give (with the key data trimmed down for clarity):
  88 .PP
  89 .nf
  90   # RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
  91   leftrsasigkey=0sAQOF8tZ2...+buFuFn/
  92 .fi
  93 .PP
  94 Normally, the default key for this host
  95 (the one with no host identities specified for it) is the one extracted.
  96 The
  97 .B \-\-id
  98 option overrides this,
  99 causing extraction of the key labeled with the specified
 100 .IR identity ,
 101 if any.
 102 The specified
 103 .I identity
 104 must
 105 .I exactly
 106 match the identity in the file;
 107 in particular, the comparison is case-sensitive.
 108 .PP
 109 The
 110 .B \-\-file
 111 option overrides the default for where the key information should be
 112 found, and takes it from the specified
 113 .IR secretfile .
 114 .SH DIAGNOSTICS
 115 A complaint about ``no IN KEY line found'' indicates that the
 116 host has a key but it was generated with an old version of FreeS/WAN
 117 and does not contain the information that
 118 .I showhostkey
 119 needs.
 120 .SH FILES
 121 /etc/ipsec.secrets
 122 .SH SEE ALSO
 123 ipsec.secrets(5), ipsec.conf(5), ipsec_rsasigkey(8)
 124 .SH HISTORY
 125 Written for the Linux FreeS/WAN project
 126 <http://www.freeswan.org>
 127 by Henry Spencer.
 128 .SH BUGS
 129 Arguably,
 130 rather than just reporting the no-IN-KEY-line-found problem,
 131 .I showhostkey
 132 should be smart enough to run the existing key through
 133 .I rsasigkey
 134 with the
 135 .B \-\-oldkey
 136 option, to generate a suitable output line.
 137 .PP
 138 The need to specify the gateway address (etc.) for
 139 .B \-\-txt
 140 is annoying, but there is no good way to determine it automatically.
 141 .PP
 142 There should be a way to specify the priority value for TXT records;
 143 currently it is hardwired to
 144 .BR 10 .
 145 .PP
 146 The
 147 .B \-\-id
 148 option assumes that the
 149 .I identity
 150 appears on the same line as the
 151 .B ":\ RSA\ {"
 152 that begins the key proper.