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 .\" $DragonFly: src/usr.sbin/keyadmin/keyadmin.8,v 1.2 2003/06/17 04:29:55 dillon Exp $
  59 .\"
  60 .Dd June 13, 1996
  61 .Dt KEY 8
  62 .Os
  63 .Sh NAME
  64 .Nm keyadmin
  65 .Nd manually manipulate the kernel key management database
  66 .Sh SYNOPSIS
  67 .Nm
  68 .Op Ar command Op Ar args
  69 .Sh DESCRIPTION
  70 The
  71 .Nm
  72 utility is used to manually enter security associations into the kernel
  73 key/security association database.  (See
  74 .Xr key 4 ) .
  75 .Pp
  76 Almost any operation offered in the
  77 .Xr key 4
  78 API is available to privileged users running
  79 .Nm .
  80 Until there is an implementation of an automated key management protocol,
  81 which will manipulate the key database in a manner similar to how
  82 .Xr routed 8
  83 or
  84 .Xr gated 8
  85 manipulates the routing tables,
  86 .Nm
  87 is the only way of establishing security associations.
  88 .Pp
  89 If
  90 .Nm
  91 is invoked without any arguments, it will enter an interactive mode, where
  92 the user can type in
  93 .Dq Ar command Op Ar args
  94 interactively, or use
  95 .Nm
  96 to enter a single
  97 .Dq Ar command Op Ar args .
  98 .Ar Command
  99 can be one of the following:
 100 .Bl -inset
 101 .It Ic del Ar type spi source destination
 102 .Pp
 103 Delete a security association between
 104 .Ar source
 105 and
 106 .Ar destination
 107 of the given
 108 .Ar type
 109 and
 110 .Ar spi .
 111 Example:
 112 .Bd -literal
 113         delete esp 90125 anderson.yes.org rabin.yes.org
 114 .Ed
 115 .It Ic get Ar type spi source destination
 116 .Pp
 117 Retrieve (and print) a security association between
 118 .Ar source
 119 and
 120 .Ar destination
 121 of the given
 122 .Ar type
 123 and
 124 .Ar spi .
 125 Example:
 126 .Bd -literal
 127         get ah 5150 eddie.vanhalen.com alex.vanhalen.com
 128 .Ed
 129 .It Ic dump
 130 .Pp
 131 Display the entire security association table.  WARNING:  This prints a lot
 132 of data.
 133 .It Ic load Ar filename
 134 .Pp
 135 Load security association information from a file formatted as documented in
 136 .Xr keys 5 .
 137 If
 138 .Dq -
 139 is specified for the
 140 .Ar filename ,
 141 load keys from the standard input.
 142 .It Ic save Ar filename
 143 .Pp
 144 Save security association information to a file formatted as documented in
 145 .Xr keys 5 .
 146 If
 147 .Dq -
 148 is specified for the
 149 .Ar filename ,
 150 place the key file out on the standard output.  (This can be used as a sort
 151 of lightweight
 152 .Ic dump
 153 command.)
 154 NOTE:  The
 155 .Ic save
 156 command must create a new file; it will not write into an
 157 existing file.  This is to prevent writing into a world-readable file, or a
 158 named pipe or UNIX socket (see
 159 .Xr socket 2
 160 and
 161 .Xr mkfifo 1 ) .
 162 .It Ic help Op command
 163 .Pp
 164 Offer brief help without an argument, or slightly more specific help on a
 165 particular command.
 166 .It Ic flush
 167 .Pp
 168 Erase all entries in the kernel security association table.
 169 .El
 170 .Pp
 171 The following values for
 172 .Ar command
 173 are only available by using
 174 .Nm
 175 in its interactive mode of operation:
 176 .Bl -inset
 177 .It Ic add Ar type spi source destination transform key
 178 .Op Ar iv
 179 .Pp
 180 Add a security association of a particular
 181 .Ar type
 182 and
 183 .Ar spi
 184 from a
 185 .Ar source
 186 to a
 187 .Ar destination ,
 188 using a particular
 189 .Ar transform
 190 and
 191 .Ar key .
 192 If a transform requires an initialization vector, the
 193 .Ar iv
 194 argument contains it.  This command is available only in interactive mode
 195 because
 196 .Nm
 197 makes no attempt to destroy its argument vector after use.  A malicious user
 198 of the
 199 .Xr ps 1
 200 command could determine security keys if
 201 .Ic add
 202 were allowed to be used straight from the command line.  Example:
 203 .Bd -literal
 204         add esp 2112 temples.syrinx.org priests.syrinx.org des-cbc \\
 205                 a652a476a652a476 87ac9876deac9876
 206 .Ed
 207 .It Ic exit
 208 .It Ic quit
 209 .Pp
 210 Exit interaction with
 211 .Nm .
 212 An EOF will also end interaction with
 213 .Nm .
 214 .El
 215 .Sh SEE ALSO
 216 .Xr ipsec 4 ,
 217 .Xr key 4 ,
 218 .Xr route 4 ,
 219 .Xr gated 8 ,
 220 .Xr routed 8
 221 .Sh HISTORY
 222 The
 223 .Nm
 224 utility first appeared in NRL's
 225 .Bx 4.4
 226 IPv6 networking distribution.
 227 The
 228 .Nm
 229 utility
 230 started its life as a pipe dream thought up by Dan McDonald, and came to
 231 life through the excruciating efforts of Ran Atkinson, Dan McDonald,
 232 Craig Metz, and Bao Phan.
 233 The NRL version of the program was originally called
 234 .Nm key ,
 235 but was renamed to
 236 .Nm
 237 because of the conflict with
 238 .Xr key 1 .
 239 .Sh BUGS
 240 The
 241 .Nm
 242 utility needs a -n flag like
 243 .Xr route 8
 244 to avoid name lookups.
 245 .Pp
 246 The
 247 .Ic dump
 248 and
 249 .Ic save
 250 commands currently display the first 30 or so entries.