| blob | a3e8fc581218ae8bc4f58b0a1690ad294c074afb |
1 '\" te
2 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH IPSECALGS 8 "Jul 5, 2007"
7 .SH NAME
8 ipsecalgs \- configure the IPsec protocols and algorithms table
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBipsecalgs\fR
13 .fi
15 .LP
16 .nf
17 \fBipsecalgs\fR \fB-l\fR
18 .fi
20 .LP
21 .nf
22 \fBipsecalgs\fR \fB-s\fR
23 .fi
25 .LP
26 .nf
27 \fBipsecalgs\fR \fB-a\fR [\fB-P\fR \fIprotocol-number\fR | \fB-p\fR \fIprotocol-name\fR] \fB-k\fR \fIkeylen-list\fR
28 [\fB-i\fR \fIinc\fR] [\fB-K\fR \fIdefault-keylen\fR] \fB-b\fR \fIblocklen-list\fR \fB-n\fR \fIalg-names\fR
29 \fB-N\fR \fIalg-number\fR \fB-m\fR \fImech-name\fR [\fB-f\fR] [\fB-s\fR]
30 .fi
32 .LP
33 .nf
34 \fBipsecalgs\fR \fB-P\fR \fIprotocol-number\fR \fB-p\fR \fIprotocol-name\fR
35 [\fB-e\fR \fIexec-mode\fR] [\fB-f\fR] [\fB-s\fR]
36 .fi
38 .LP
39 .nf
40 \fBipsecalgs\fR \fB-r\fR \fB-p\fR \fIprotocol-name\fR [] \fB-n\fR \fIalg-name\fR [\fB-s\fR]
41 .fi
43 .LP
44 .nf
45 \fBipsecalgs\fR \fB-r\fR \fB-p\fR \fIprotocol-name\fR [] \fB-N\fR \fIalg-number\fR [\fB-s\fR]
46 .fi
48 .LP
49 .nf
50 \fBipsecalgs\fR \fB-R\fR \fB-P\fR \fIprotocol-number\fR [\fB-s\fR]
51 .fi
53 .LP
54 .nf
55 \fBipsecalgs\fR \fB-R\fR \fB-p\fR \fIprotocol-name\fR [\fB-s\fR]
56 .fi
58 .LP
59 .nf
60 \fBipsecalgs\fR \fB-e\fR \fIexec-mode\fR \fB-P\fR \fIprotocol-number\fR [\fB-s\fR]
61 .fi
63 .LP
64 .nf
65 \fBipsecalgs\fR \fB-e\fR \fIexec-mode\fR \fB-p\fR \fIprotocol-name\fR [\fB-s\fR]
66 .fi
68 .SH DESCRIPTION
69 .sp
70 .LP
71 Use the \fBipsecalgs\fR command to query and modify the IPsec protocol and
72 algorithms stored in \fB/etc/inet/ipsecalgs\fR. You can use the \fBipsecalgs\fR
73 command to do the following:
74 .RS +4
75 .TP
76 .ie t \(bu
77 .el o
78 list the currently defined IPsec protocols and algorithms
79 .RE
80 .RS +4
81 .TP
82 .ie t \(bu
83 .el o
84 modify IPsec protocols definitions
85 .RE
86 .RS +4
87 .TP
88 .ie t \(bu
89 .el o
90 modify IPsec algorithms definitions
91 .RE
92 .sp
93 .LP
94 \fBNever\fR edit the \fB/etc/inet/ipsecalgs\fR file manually. The valid IPsec
95 protocols and algorithms are described by the ISAKMP DOI. See \fIRFC 2407\fR.
96 In the general sense, a Domain of Interpretation (DOI) defines data formats,
97 network traffic exchange types, and conventions for naming security-relevant
98 information such as security policies or cryptographic algorithms and modes.
99 For \fBipsecalgs\fR, the DOI defines naming and numbering conventions for
100 algorithms and the protocols they belong to. These numbers are defined by the
101 Internet Assigned Numbers Authority (IANA). Each algorithm belongs to a
102 protocol. Algorithm information includes supported key lengths, block or MAC
103 length, and the name of the cryptographic mechanism corresponding to that
104 algorithm. This information is used by the IPsec modules, \fBipsecesp\fR(7P)
105 and \fBipsecah\fR(7P), to determine the authentication and encryption
106 algorithms that can be applied to IPsec traffic.
107 .sp
108 .LP
109 The following protocols are predefined:
110 .sp
111 .ne 2
112 .na
113 \fB\fBIPSEC_PROTO_ESP\fR\fR
114 .ad
115 .RS 19n
116 Defines the encryption algorithms (transforms) that can be used by IPsec to
117 provide data confidentiality.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fBIPSEC_PROTO_AH\fR\fR
124 .ad
125 .RS 19n
126 Defines the authentication algorithms (transforms) that can be used by IPsec to
127 provide authentication.
128 .RE
130 .sp
131 .LP
132 The mechanism name specified by an algorithm entry must correspond to a valid
133 Solaris Cryptographic Framework mechanism. You can obtain the list of available
134 mechanisms by using the \fBcryptoadm\fR(8) command.
135 .sp
136 .LP
137 Applications can retrieve the supported algorithms and their associated
138 protocols by using the functions \fBgetipsecalgbyname\fR(3NSL),
139 \fBgetipsecalgbynum\fR(3NSL), \fBgetipsecprotobyname\fR(3NSL) and
140 \fBgetipsecprotobynum\fR(3NSL).
141 .sp
142 .LP
143 Modifications to the protocols and algorithm by default update only the
144 contents of the \fB/etc/inet/ipsecalgs\fR configuration file. In order for the
145 new definitions to be used for IPsec processing, the changes must be
146 communicated to the kernel using the \fB-s\fR option. See \fBNOTES\fR for a
147 description of how the \fBipsecalgs\fR configuration is synchronized with the
148 kernel at system restart.
149 .sp
150 .LP
151 When invoked without arguments, \fBipsecalgs\fR displays the list of mappings
152 that are currently defined in \fB/etc/inet/ipsecalgs\fR. You can obtain the
153 corresponding kernel table of protocols and algorithms by using the \fB-l\fR
154 option.
155 .SH OPTIONS
156 .sp
157 .LP
158 \fBipsecalgs\fR supports the following options:
159 .sp
160 .ne 2
161 .na
162 \fB\fB-a\fR\fR
163 .ad
164 .RS 6n
165 Adds an algorithm of the protocol specified by the \fB-P\fR option. The
166 algorithm name(s) are specified with the \fB-n\fR option. The supported key
167 lengths and block sizes are specified with the \fB-k\fR, \fB-i\fR, and \fB-b\fR
168 options.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fB-b\fR\fR
175 .ad
176 .RS 6n
177 Specifies the block or MAC lengths of an algorithm, in bytes. Set more than one
178 block length by separating the values with commas.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fB-e\fR\fR
185 .ad
186 .RS 6n
187 Designates the execution mode of cryptographic requests for the specified
188 protocol in the absence of cryptographic hardware provider. See
189 \fBcryptoadm\fR(8). \fIexec-mode\fR can be one of the following values:
190 .sp
191 .ne 2
192 .na
193 \fB\fBsync\fR\fR
194 .ad
195 .RS 9n
196 Cryptographic requests are processed synchronously in the absence of a
197 cryptographic hardware provider. This execution mode leads to better latency
198 when no cryptographic hardware providers are available
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBasync\fR\fR
205 .ad
206 .RS 9n
207 Cryptographic requests are always processed asynchronously in the absence of
208 cryptographic hardware provider. This execution can improve the resource
209 utilization on a multi-CPU system, but can lead to higher latency when no
210 cryptographic hardware providers are available.
211 .RE
213 This option can be specified when defining a new protocol or to modify the
214 execution mode of an existing protocol. By default, the \fBsync\fR execution
215 mode is used in the absence of a cryptographic hardware provider.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fB-f\fR\fR
222 .ad
223 .RS 6n
224 Used with the \fB-a\fR option to force the addition of an algorithm or protocol
225 if an entry with the same name or number already exists.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fB-i\fR\fR
232 .ad
233 .RS 6n
234 Specifies the valid key length increments in bits. This option must be used
235 when the valid key lengths for an algorithm are specified by a range with the
236 \fB-k\fR option.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fB-K\fR\fR
243 .ad
244 .RS 6n
245 Specifies the default key lengths for an algorithm, in bits. If the \fB-K\fR
246 option is not specified, the minimum key length will be determined as follows:
247 .RS +4
248 .TP
249 .ie t \(bu
250 .el o
251 If the supported key lengths are specified by range, the default key length
252 will be the minimum key length.
253 .RE
254 .RS +4
255 .TP
256 .ie t \(bu
257 .el o
258 If the supported key lengths are specified by enumeration, the default key
259 length will be the first listed key length.
260 .RE
261 .RE
263 .sp
264 .ne 2
265 .na
266 \fB\fB-k\fR\fR
267 .ad
268 .RS 6n
269 Specifies the supported key lengths for an algorithm, in bits. You can
270 designate the supported key lengths by enumeration or by range.
271 .sp
272 Without the \fB-i\fR option, \fB-k\fR specifies the supported key lengths by
273 enumeration. In this case, \fIkeylen-list\fR consists of a list of one or more
274 key lengths separated by commas, for example:
275 .sp
276 .in +2
277 .nf
278 128,192,256
279 .fi
280 .in -2
281 .sp
283 The listed key lengths need not be increasing, and the first listed key length
284 will be used as the default key length for that algorithm unless the \fB-K\fR
285 option is used.
286 .sp
287 With the \fB-i\fR option, \fB-k\fR specifies the range of supported key lengths
288 for the algorithm. The minimum and maximum key lengths must be separated by a
289 dash ('\fB-\fR') character, for example:
290 .sp
291 .in +2
292 .nf
293 32-448
294 .fi
295 .in -2
296 .sp
298 .RE
300 .sp
301 .ne 2
302 .na
303 \fB\fB-l\fR\fR
304 .ad
305 .RS 6n
306 Displays the kernel algorithm tables.
307 .RE
309 .sp
310 .ne 2
311 .na
312 \fB\fB-m\fR\fR
313 .ad
314 .RS 6n
315 Specifies the name of the cryptographic framework mechanism name corresponding
316 to the algorithm. Cryptographic framework mechanisms are described in the
317 \fBcryptoadm\fR(8) man page.
318 .RE
320 .sp
321 .ne 2
322 .na
323 \fB\fB-N\fR\fR
324 .ad
325 .RS 6n
326 Specifies an algorithm number. The algorithm number for a protocol must be
327 unique. IANA manages the algorithm numbers. See \fIRFC 2407\fR.
328 .RE
330 .sp
331 .ne 2
332 .na
333 \fB\fB-n\fR\fR
334 .ad
335 .RS 6n
336 Specifies one or more names for an algorithm. When adding an algorithm with the
337 \fB-a\fR option, \fIalg-names\fR contains a string or a comma-separated list of
338 strings, for example:
339 .sp
340 .in +2
341 .nf
342 des-cbs,des
343 .fi
344 .in -2
345 .sp
347 When used with the \fB-r\fR option to remove an algorithm, \fIalg-names\fR
348 contains one of the valid algorithm names.
349 .RE
351 .sp
352 .ne 2
353 .na
354 \fB\fB-P\fR\fR
355 .ad
356 .RS 6n
357 Adds a protocol of the number specified by \fIprotocol-number\fR with the name
358 specified by the \fB-p\fR option. This option is also used to specify an IPsec
359 protocol when used with the \fB-a\fR and the \fB-R\fR options. Protocol numbers
360 are managed by the IANA. See \fIRFC 2407\fR.
361 .RE
363 .sp
364 .ne 2
365 .na
366 \fB\fB-p\fR\fR
367 .ad
368 .RS 6n
369 Specifies the name of the IPsec protocol.
370 .RE
372 .sp
373 .ne 2
374 .na
375 \fB\fB-R\fR\fR
376 .ad
377 .RS 6n
378 Removes and IPsec protocol from the algorithm table. The protocol can be
379 specified by number by using the \fB-P\fR option or by name by using the
380 \fB-p\fR option. The algorithms associated with the protocol are removed as
381 well.
382 .RE
384 .sp
385 .ne 2
386 .na
387 \fB\fB-r\fR\fR
388 .ad
389 .RS 6n
390 Removes the mapping for an algorithm The algorithm can be specified by
391 algorithm number using the \fB-N\fR option or by algorithm name using the
392 \fB-A\fR option.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB\fB-s\fR\fR
399 .ad
400 .RS 6n
401 Synchronizes the kernel with the contents of \fB/etc/inet/ipsecalgs\fR. The
402 contents of \fB/etc/inet/ipsecalgs\fR are always updated, but new information
403 is not passed on to the kernel unless the \fB-s\fR is used. See \fBNOTES\fR for
404 a description of how the \fBipsecalgs\fR configuration is synchronized with the
405 kernel at system restart.
406 .RE
408 .SH EXAMPLES
409 .LP
410 \fBExample 1 \fRAdding a Protocol for IPsec Encryption
411 .sp
412 .LP
413 The following example shows how to add a protocol for IPsec encryption:
415 .sp
416 .in +2
417 .nf
418 example# \fBipsecalgs -P 3 -p "IPSEC_PROTO_ESP"\fR
419 .fi
420 .in -2
421 .sp
423 .LP
424 \fBExample 2 \fRAdding the Blowfish Algorithm
425 .sp
426 .LP
427 The following example shows how to add the Blowfish algorithm:
429 .sp
430 .in +2
431 .nf
432 example# \fBipsecalgs -a -P 3 -k 32-488 -K 128 -i 8 -n "blowfish" \e
433 -b 8 -N 7 -m CKM_BF_CBC\fR
434 .fi
435 .in -2
436 .sp
438 .LP
439 \fBExample 3 \fRUpdating the Kernel Algorithm Table
440 .sp
441 .LP
442 The following example updates the kernel algorithm table with the currently
443 defined protocol and algorithm definitions:
445 .sp
446 .in +2
447 .nf
448 example# \fBsvcadm refresh ipsecalgs\fR
449 .fi
450 .in -2
451 .sp
453 .SH FILES
454 .sp
455 .ne 2
456 .na
457 \fB\fB/etc/inet/ipsecalgs\fR\fR
458 .ad
459 .sp .6
460 .RS 4n
461 File that contains the configured IPsec protocols and algorithm definitions.
462 Never edit this file manually.
463 .RE
465 .SH ATTRIBUTES
466 .sp
467 .LP
468 See \fBattributes\fR(5) for descriptions of the following attributes:
469 .sp
471 .sp
472 .TS
473 box;
474 c | c
475 l | l .
476 ATTRIBUTE TYPE ATTRIBUTE VALUE
477 _
478 Interface Stability Evolving
479 .TE
481 .SH SEE ALSO
482 .sp
483 .LP
484 \fBcryptoadm\fR(8), \fBipsecconf\fR(8), \fBipseckey\fR(8), \fBsvcadm\fR(8),
485 \fBgetipsecalgbyname\fR(3NSL), \fBgetipsecprotobyname\fR(3NSL),
486 \fBike.config\fR(4), \fBattributes\fR(5), \fBsmf\fR(5), \fBipsecah\fR(7P),
487 \fBipsecesp\fR(7P)
488 .sp
489 .LP
490 Piper, Derrell, \fIRFC 2407, The Internet IP Security Domain of Interpretation
491 for ISAKMP\fR. Network Working Group. November 1998.
492 .SH NOTES
493 .sp
494 .LP
495 When protocols or algorithm definitions that are removed or altered, services
496 that rely upon these definitions can become unavailable. For example, if the
497 \fBIPSEC_PROTO_ESP\fR protocol is removed, then IPsec cannot encrypt and
498 decrypt packets.
499 .sp
500 .LP
501 Synchronization of the \fBipsecalgs\fR configuration with the kernel at system
502 startup is provided by the following \fBsmf\fR(5) service:
503 .sp
504 .in +2
505 .nf
506 svc:/network/ipsec/ipsecalgs:default
507 .fi
508 .in -2
509 .sp
511 .sp
512 .LP
513 The IPsec services are delivered as follows:
514 .sp
515 .in +2
516 .nf
517 svc:/network/ipsec/policy:default (enabled)
518 svc:/network/ipsec/ipsecalgs:default (enabled)
519 svc:/network/ipsec/manual-key:default (disabled)
520 svc:/network/ipsec/ike:default (disabled)
521 .fi
522 .in -2
523 .sp
525 .sp
526 .LP
527 Services that are delivered disabled are delivered that way because the system
528 administrator must create configuration files for those services before
529 enabling them. See \fBipseckey\fR(8) and \fBike.config\fR(4). The default
530 policy for the \fBpolicy\fR service is to allow all traffic to pass without
531 IPsec protection. See \fBipsecconf\fR(8).
532 .sp
533 .LP
534 The correct administrative procedure is to create the configuration file for
535 each service, then enable each service using \fBsvcadm\fR(8), as shown in the
536 following example:
537 .sp
538 .in +2
539 .nf
540 example# \fBsvcadm enable ipsecalgs\fR
541 .fi
542 .in -2
543 .sp
545 .sp
546 .LP
547 The service's status can be queried using the \fBsvcs\fR(1) command.
548 .sp
549 .LP
550 If the \fBipsecalgs\fR configuration is modified, the new configuration should
551 be resynchronized as follows:
552 .sp
553 .in +2
554 .nf
555 example# \fBsvcadm refresh ipsecalgs\fR
556 .fi
557 .in -2
558 .sp
560 .sp
561 .LP
562 Administrative actions on this service, such as enabling, disabling,
563 refreshing, and requesting restart can be performed using \fBsvcadm\fR(8). A
564 user who has been assigned the authorization shown below can perform these
565 actions:
566 .sp
567 .in +2
568 .nf
569 solaris.smf.manage.ipsec
570 .fi
571 .in -2
572 .sp
574 .sp
575 .LP
576 See \fBauths\fR(1), \fBuser_attr\fR(4), \fBrbac\fR(5).
577 .sp
578 .LP
579 The \fBipsecalgs\fR \fBsmf\fR(5) service does not have any user-configurable
580 properties.
581 .sp
582 .LP
583 The \fBsmf\fR(5) framework records any errors in the service-specific log file.
584 Use any of the following commands to examine the \fBlogfile\fR property:
585 .sp
586 .in +2
587 .nf
588 example# \fBsvcs -l ipsecalgs\fR
589 example# \fBsvcprop ipsecalgs\fR
590 example# \fBsvccfg -s ipsecalgs listprop\fR
591 .fi
592 .in -2
593 .sp
595 .sp
596 .LP
597 This command requires \fBsys_ip_config\fR privilege to operate and thus can run
598 in the global zone and in exclusive-IP zones. All shared-IP zones share the
599 same available set of algorithms; however, you can use \fBipsecconf\fR(8) to
600 set up system policy that uses differing algorithms for various shared-IP
601 zones. All exclusive-IP zones have their own set of algorithms.