usr.sbin/keyadmin/keyadmin.8

   1 .\"#    @(#)COPYRIGHT   1.1a (NRL) 17 August 1995
   2 .\"
   3 .\"COPYRIGHT NOTICE
   4 .\"
   5 .\"All of the documentation and software included in this software
   6 .\"distribution from the US Naval Research Laboratory (NRL) are
   7 .\"copyrighted by their respective developers.
   8 .\"
   9 .\"This software and documentation were developed at NRL by various
  10 .\"people.  Those developers have each copyrighted the portions that they
  11 .\"developed at NRL and have assigned All Rights for those portions to
  12 .\"NRL.  Outside the USA, NRL also has copyright on the software
  13 .\"developed at NRL. The affected files all contain specific copyright
  14 .\"notices and those notices must be retained in any derived work.
  15 .\"
  16 .\"NRL LICENSE
  17 .\"
  18 .\"NRL grants permission for redistribution and use in source and binary
  19 .\"forms, with or without modification, of the software and documentation
  20 .\"created at NRL provided that the following conditions are met:
  21 .\"
  22 .\"1. Redistributions of source code must retain the above copyright
  23 .\"   notice, this list of conditions and the following disclaimer.
  24 .\"2. Redistributions in binary form must reproduce the above copyright
  25 .\"   notice, this list of conditions and the following disclaimer in the
  26 .\"   documentation and/or other materials provided with the distribution.
  27 .\"3. All advertising materials mentioning features or use of this software
  28 .\"   must display the following acknowledgement:
  29 .\"
  30 .\"     This product includes software developed at the Information
  31 .\"     Technology Division, US Naval Research Laboratory.
  32 .\"
  33 .\"4. Neither the name of the NRL nor the names of its contributors
  34 .\"   may be used to endorse or promote products derived from this software
  35 .\"   without specific prior written permission.
  36 .\"
  37 .\"THE SOFTWARE PROVIDED BY NRL IS PROVIDED BY NRL AND CONTRIBUTORS ``AS
  38 .\"IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  39 .\"TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  40 .\"PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL NRL OR
  41 .\"CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  42 .\"EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  43 .\"PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  44 .\"PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  45 .\"LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  46 .\"NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  47 .\"SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  48 .\"
  49 .\"The views and conclusions contained in the software and documentation
  50 .\"are those of the authors and should not be interpreted as representing
  51 .\"official policies, either expressed or implied, of the US Naval
  52 .\"Research Laboratory (NRL).
  53 .\"
  54 .\"----------------------------------------------------------------------*/
  55 .\"
  56 .\"     $ANA: keyadmin.8,v 1.3 1996/06/13 20:15:57 wollman Exp $
  57 .\" $FreeBSD: src/usr.sbin/keyadmin/keyadmin.8,v 1.5.2.6 2003/03/11 21:13:50 trhodes Exp $
  58 .\"
  59 .Dd June 13, 1996
  60 .Dt KEY 8
  61 .Os
  62 .Sh NAME
  63 .Nm keyadmin
  64 .Nd manually manipulate the kernel key management database
  65 .Sh SYNOPSIS
  66 .Nm
  67 .Op Ar command Op Ar args
  68 .Sh DESCRIPTION
  69 The
  70 .Nm
  71 utility is used to manually enter security associations into the kernel
  72 key/security association database.  (See
  73 .Xr key 4 ) .
  74 .Pp
  75 Almost any operation offered in the
  76 .Xr key 4
  77 API is available to privileged users running
  78 .Nm .
  79 Until there is an implementation of an automated key management protocol,
  80 which will manipulate the key database in a manner similar to how
  81 .Xr routed 8
  82 or
  83 .Xr gated 8
  84 manipulates the routing tables,
  85 .Nm
  86 is the only way of establishing security associations.
  87 .Pp
  88 If
  89 .Nm
  90 is invoked without any arguments, it will enter an interactive mode, where
  91 the user can type in
  92 .Dq Ar command Op Ar args
  93 interactively, or use
  94 .Nm
  95 to enter a single
  96 .Dq Ar command Op Ar args .
  97 .Ar Command
  98 can be one of the following:
  99 .Bl -inset
 100 .It Ic del Ar type spi source destination
 101 .Pp
 102 Delete a security association between
 103 .Ar source
 104 and
 105 .Ar destination
 106 of the given
 107 .Ar type
 108 and
 109 .Ar spi .
 110 Example:
 111 .Bd -literal
 112         delete esp 90125 anderson.yes.org rabin.yes.org
 113 .Ed
 114 .It Ic get Ar type spi source destination
 115 .Pp
 116 Retrieve (and print) a security association between
 117 .Ar source
 118 and
 119 .Ar destination
 120 of the given
 121 .Ar type
 122 and
 123 .Ar spi .
 124 Example:
 125 .Bd -literal
 126         get ah 5150 eddie.vanhalen.com alex.vanhalen.com
 127 .Ed
 128 .It Ic dump
 129 .Pp
 130 Display the entire security association table.  WARNING:  This prints a lot
 131 of data.
 132 .It Ic load Ar filename
 133 .Pp
 134 Load security association information from a file formatted as documented in
 135 .Xr keys 5 .
 136 If
 137 .Dq -
 138 is specified for the
 139 .Ar filename ,
 140 load keys from the standard input.
 141 .It Ic save Ar filename
 142 .Pp
 143 Save security association information to a file formatted as documented in
 144 .Xr keys 5 .
 145 If
 146 .Dq -
 147 is specified for the
 148 .Ar filename ,
 149 place the key file out on the standard output.  (This can be used as a sort
 150 of lightweight
 151 .Ic dump
 152 command.)
 153 NOTE:  The
 154 .Ic save
 155 command must create a new file; it will not write into an
 156 existing file.  This is to prevent writing into a world-readable file, or a
 157 named pipe or UNIX socket (see
 158 .Xr socket 2
 159 and
 160 .Xr mkfifo 1 ) .
 161 .It Ic help Op command
 162 .Pp
 163 Offer brief help without an argument, or slightly more specific help on a
 164 particular command.
 165 .It Ic flush
 166 .Pp
 167 Erase all entries in the kernel security association table.
 168 .El
 169 .Pp
 170 The following values for
 171 .Ar command
 172 are only available by using
 173 .Nm
 174 in its interactive mode of operation:
 175 .Bl -inset
 176 .It Ic add Ar type spi source destination transform key
 177 .Op Ar iv
 178 .Pp
 179 Add a security association of a particular
 180 .Ar type
 181 and
 182 .Ar spi
 183 from a
 184 .Ar source
 185 to a
 186 .Ar destination ,
 187 using a particular
 188 .Ar transform
 189 and
 190 .Ar key .
 191 If a transform requires an initialization vector, the
 192 .Ar iv
 193 argument contains it.  This command is available only in interactive mode
 194 because
 195 .Nm
 196 makes no attempt to destroy its argument vector after use.  A malicious user
 197 of the
 198 .Xr ps 1
 199 command could determine security keys if
 200 .Ic add
 201 were allowed to be used straight from the command line.  Example:
 202 .Bd -literal
 203         add esp 2112 temples.syrinx.org priests.syrinx.org des-cbc \\
 204                 a652a476a652a476 87ac9876deac9876
 205 .Ed
 206 .It Ic exit
 207 .It Ic quit
 208 .Pp
 209 Exit interaction with
 210 .Nm .
 211 An EOF will also end interaction with
 212 .Nm .
 213 .El
 214 .Sh SEE ALSO
 215 .Xr ipsec 4 ,
 216 .Xr key 4 ,
 217 .Xr route 4 ,
 218 .Xr gated 8 ,
 219 .Xr routed 8
 220 .Sh HISTORY
 221 The
 222 .Nm
 223 utility first appeared in NRL's
 224 .Bx 4.4
 225 IPv6 networking distribution.
 226 The
 227 .Nm
 228 utility
 229 started its life as a pipe dream thought up by Dan McDonald, and came to
 230 life through the excruciating efforts of Ran Atkinson, Dan McDonald,
 231 Craig Metz, and Bao Phan.
 232 The NRL version of the program was originally called
 233 .Nm key ,
 234 but was renamed to
 235 .Nm
 236 because of the conflict with
 237 .Xr key 1 .
 238 .Sh BUGS
 239 The
 240 .Nm
 241 utility needs a -n flag like
 242 .Xr route 8
 243 to avoid name lookups.
 244 .Pp
 245 The
 246 .Ic dump
 247 and
 248 .Ic save
 249 commands currently display the first 30 or so entries.