| blob | 69b2bbce613ce049e2ed2751d791cf8dbc422e3a |
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.