| blob | 2e092973d2d8c915a7a03773c975cb70106297ed |
1 '\" te
2 .\" Copyright (C) 2008, 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 PF_KEY 7P "May 6, 2008"
7 .SH NAME
8 pf_key \- Security association database interface
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/types.h>
13 #include <sys/socket.h>
14 #include <net/pfkeyv2.h>
18 \fBint\fR \fBsocket\fR(\fB\fR\fIPF_KEY\fR,SOCK_RAW,\fIPF_KEY_V2\fR);
19 .fi
21 .SH DESCRIPTION
22 .LP
23 Keying information for IPsec security services is maintained in security
24 association databases (\fBSADB\fRs). The security associations (\fBSA\fRs) are
25 used to protect both inbound and outbound packets.
26 .sp
27 .LP
28 A user process (or possibly multiple co-operating processes) maintains
29 \fBSADB\fRs by sending messages over a special kind of socket. This is
30 analogous to the method described in \fBroute\fR(7P). Only a superuser may
31 access an \fBSADB\fR.
32 .sp
33 .LP
34 SunOS applications that use PF_KEY include \fBipseckey\fR(1M) and
35 \fBin.iked\fR(1M).
36 .sp
37 .LP
38 The operating system may spontaneously send pf_key messages to listening
39 processes, such as a request for a new \fBSA\fR for an outbound datagram or to
40 report the expiration of an existing \fBSA\fR.
41 .sp
42 .LP
43 One opens the channel for passing \fBSADB\fR control messages by using the
44 socket call shown in the section above. More than one key socket can be open
45 per system.
46 .sp
47 .LP
48 Messages are formed by a small base header, followed by zero or more extension
49 messages, some of which require additional data following them. The base
50 message and all extensions must be eight-byte aligned. An example message is
51 the \fBGET\fR message, which requires the base header, the \fBSA \fRextension,
52 and the \fBADDRESS_DST\fR extension.
53 .SS "Messages"
54 .LP
55 Messages include:
56 .sp
57 .in +2
58 .nf
59 #define SADB_GETSPI /* Get a new SPI value from the system. */
60 #define SADB_UPDATE /* Update an SA. */
61 #define SADB_ADD /* Add a fully-formed SA. */
62 #define SADB_DELETE /* Delete an SA. */
63 #define SADB_GET /* Get an SA */
64 #define SADB_ACQUIRE /* Kernel needs a new SA. */
65 #define SADB_REGISTER /* Regis. to receive ACQUIRE msgs. */
66 #define SADB_EXPIRE /* SA has expired. */
67 #define SADB_FLUSH /* Flush all SAs. */
68 #define SADB_DUMP /* Get all SAs. (Unreliable) */
69 #define SADB_X_PROMISC /* Listen promiscuously */
70 #define SADB_X_INVERSE_ACQUIRE /* Query kernel policy,
71 get an ACQUIRE in return. */
72 #define SADB_X_UPDATEPAIR /* Update an SA and its pair SA */
73 #define SADB_X_DELPAIR /* Delete an SA pair. */
74 .fi
75 .in -2
77 .sp
78 .LP
79 The base message header consists of:
80 .sp
81 .in +2
82 .nf
83 struct sadb_msg {
84 uint8_t sadb_msg_version; /* Set to PF_KEY_V2, for compat. */
85 uint8_t sadb_msg_type; /* Msg. type */
86 uint8_t sadb_msg_errno; /* Why message failed */
87 uint8_t sadb_msg_satype; /* Which security service */
88 uint16_t sadb_msg_len; /* Length in 8-byte units */
89 uint16_t sadb_msg_reserved; /* Zero out */
90 #define sadb_x_msg_diagnostic sadb_msg_reserved
91 /* Extended diagnostics for errors */
92 uint32_t sadb_msg_seq; /* For msg. originator */
93 uint32_t sadb_msg_pid; /* ID originator */
94 };
95 .fi
96 .in -2
98 .sp
99 .LP
100 Extension types include:
101 .sp
102 .in +2
103 .nf
104 #define SADB_EXT_SA /* SA info */
105 #define SADB_EXT_LIFETIME_HARD /* Hard lifetime */
106 #define SADB_EXT_LIFETIME_SOFT /* Soft lifetime */
107 #define SADB_EXT_ADDRESS_SRC /* Source address */
108 #define SADB_EXT_ADDRESS_DST /* Destination address */
109 #define SADB_EXT_ADDRESS_PROXY /* Proxy address - DEPRECATED */
110 #define SADB_EXT_KEY_AUTH /* Authen. key */
111 #define SADB_EXT_KEY_ENCRYPT /* Encryption key */
112 #define SADB_EXT_IDENTITY_SRC /* Source certif. ID */
113 #define SADB_EXT_IDENTITY_DST /* Destination certif. ID */
114 #define SADB_EXT_SENSITIVITY /* Sensitivity info */
115 #define SADB_EXT_PROPOSAL /* Security proposal */
116 #define SADB_EXT_SUPPORTED_AUTH /* Supported authen. algo's */
117 #define SADB_EXT_SUPPORTED_ENCRYPT /* Supported encryption algo's */
118 #define SADB_EXT_SPIRANGE /* Range of possible SPIs *
119 #define SADB_X_EXT_EREG /* Reg. for extended ACQUIRE */
120 #define SADB_X_EXT_EPROP /* Extended ACQUIRE proposals */
121 #define SADB_X_EXT_KM_COOKIE /* Indicates which KM derived SA. */
122 #define SADB_X_EXT_ADDRESS_NATT_LOC /* NAT-Traversal local (my public) */
123 #define SADB_X_EXT_ADDRESS_NATT_REM /* NAT-T remote (peer's private) */
124 #define SADB_X_EXT_ADDRESS_INNER_SRC /* Tunnel-mode inner source */
125 #define SADB_X_EXT_ADDRESS_INNER_DST /* Tunnel-mode inner dest */
126 #define SADB_X_EXT_PAIR /* SA pair extension.
127 .fi
128 .in -2
130 .sp
131 .LP
132 Security Association Information Extension flags:
133 .sp
134 .in +2
135 .nf
136 #define SADB_SAFLAGS_PFS 0x1 /* Perfect forward secrecy? */
137 #define SADB_SAFLAGS_NOREPLAY 0x2 /* Replay field NOT PRESENT. */
138 #define SADB_X_SAFLAGS_USED 0x80000000 /* SA used/not used */
139 #define SADB_X_SAFLAGS_UNIQUE 0x40000000 /* SA unique/reusable */
140 #define SADB_X_SAFLAGS_AALG1 0x20000000 /* Auth-alg specif. flag 1 */
141 #define SADB_X_SAFLAGS_AALG2 0x10000000 /* Auth-alg specif. flag 2 */
142 #define SADB_X_SAFLAGS_EALG1 0x8000000 /* Encr-alg specif. flag 1 */
143 #define SADB_X_SAFLAGS_EALG2 0x4000000 /* Encr-alg specif. flag 2 */
144 #define SADB_X_SAFLAGS_KM1 0x2000000 /* Key mgmt. specif. flag 1 */
145 #define SADB_X_SAFLAGS_KM2 0x1000000 /* Key mgmt. specif. flag 2 */
146 #define SADB_X_SAFLAGS_KM3 0x800000 /* Key mgmt. specif. flag 3 */
147 #define SADB_X_SAFLAGS_KM4 0x400000 /* Key mgmt. specif. flag 4 */
148 #define SADB_X_SAFLAGS_KRES1 0x200000 /* Reserved by the kernel */
149 #define SADB_X_SAFLAGS_NATT_LOC 0x100000 /* this has a natted srcSA */
150 #define SADB_X_SAFLAGS_NATT_REM 0x80000 /* this has a natted dstSA */
151 #define SADB_X_SAFLAGS_KRES2 0x40000 /* Reserved by the kernel */
152 #define SADB_X_SAFLAGS_TUNNEL 0x20000 /* tunnel mode */
153 #define SADB_X_SAFLAGS_PAIRED 0x10000 /* inbound/outbound pair*/
154 #define SADB_X_SAFLAGS_OUTBOUND 0x8000 /* SA direction bit */
155 #define SADB_X_SAFLAGS_INBOUND 0x4000 /* SA direction bit */
156 .fi
157 .in -2
159 .sp
160 .LP
161 Extension headers include:
162 .SS "Generic Extension Header"
163 .in +2
164 .nf
165 struct sadb_ext {
166 uint16_t sadb_ext_len; /* In 64-bit words, inclusive */
167 uint16_t sadb_ext_type; /* 0 is reserved */
168 };
169 .fi
170 .in -2
172 .SS "Security Association Information Extension"
173 .in +2
174 .nf
175 struct sadb_sa {
176 uint16_t sadb_sa_len;
177 uint16_t sadb_sa_exttype; /* ASSOCIATION */
178 uint32_t sadb_sa_spi;
179 uint8_t sadb_sa_replay;
180 uint8_t sadb_sa_state;
181 uint8_t sadb_sa_auth;
182 uint8_t sadb_sa_encrypt;
183 uint32_t sadb_sa_flags;
184 };
185 .fi
186 .in -2
188 .SS "Lifetime Extension"
189 .in +2
190 .nf
191 struct sadb_lifetime {
192 uint16_t sadb_lifetime_len;
193 uint16_t sadb_lifetime_exttype; /* SOFT, HARD, CURRENT */
194 uint32_t sadb_lifetime_allocations;
195 uint64_t sadb_lifetime_bytes;
196 uint64_t sadb_lifetime_addtime;
197 uint64_t sadb_lifetime_usetime;
198 };
199 .fi
200 .in -2
202 .SS "Address Extension"
203 .in +2
204 .nf
205 struct sadb_address {
206 uint16_t sadb_address_len;
207 uint16_t sadb_address_exttype; /* SRC, DST, NATT_*, INNER_* */
208 uint8_t sadb_address_proto; /* Proto for ports... */
209 uint8_t sadb_address_prefixlen; /* Prefix length for INNER_*. */
210 uint16_t sadb_address_reserved; /* Padding */
211 /* Followed by a sockaddr
212 structure.*/
213 };
214 .fi
215 .in -2
217 .SS "Keying Material Extension"
218 .in +2
219 .nf
220 struct sadb_key {
221 uint16_t sadb_key_len;
222 uint16_t sadb_key_exttype; /* AUTH, ENCRYPT */
223 uint16_t sadb_key_bits;
224 uint16_t sadb_key_reserved;
225 /* Followed by actual key(s) in
226 canonical (outbound proc.) order. */
227 };
228 .fi
229 .in -2
231 .SS "Indentity Extension"
232 .in +2
233 .nf
234 struct sadb_ident {
235 uint16_t sadb_ident_len;
236 uint16_t sadb_ident_exttype; /* SRC, DST, PROXY */
237 uint16_t sadb_ident_type; /* FQDN, USER_FQDN, etc. */
238 uint16_t sadb_ident_reserved; /* Padding */
239 uint64_t sadb_ident_id; /* For userid, etc. */
240 /* Followed by an identity null-terminate C string if present. */
241 };
242 .fi
243 .in -2
245 .SS "Sensitivity/Integrity Extension"
246 .in +2
247 .nf
248 struct sadb_sens {
249 uint16_t sadb_sens_len;
250 uint16_t sadb_sens_exttype; /* SENSITIVITY */
251 uint32_t sadb_sens_dpd;
252 uint8_t sadb_sens_sens_level;
253 uint8_t sadb_sens_sens_len; /* 64-bit words */
254 uint8_t sadb_sens_integ_level;
255 uint8_t sadb_sens_integ_len; /* 64-bit words */
256 uint32_t sadb_sens_reserved;
257 /*
258 * followed by two uint64_t arrays
259 * uint64_t sadb_sens_bitmap[sens_bitmap_len];
260 * uint64_t integ_bitmap[integ_bitmap_len];
261 */
262 };
263 .fi
264 .in -2
266 .SS "Proposal Extension"
267 .in +2
268 .nf
269 struct sadb_prop {
270 uint16_t sadb_prop_len;
271 uint16_t sadb_prop_exttype; /* PROPOSAL, X_EPROP */
272 uint8_t sadb_prop_replay;
273 uint8_t sadb_X_prop_ereserved;
274 uint16_t sadb_x_prop_numecombs;
275 /* Followed by sadb_comb[] array or sadb_ecomb[] array. */
276 };
277 .fi
278 .in -2
280 .SS "Combination Instance for a Proposal"
281 .in +2
282 .nf
283 struct sadb_comb {
284 uint8_t sadb_comb_auth;
285 uint8_t sadb_comb_encrypt;
286 uint16_t sadb_comb_flags;
287 uint16_t sadb_comb_auth_minbits;
288 uint16_t sadb_comb_auth_maxbits;
289 uint16_t sadb_comb_encrypt_minbits;
290 uint16_t sadb_comb_encrypt_maxbits;
291 uint32_t sadb_comb_reserved;
292 uint32_t sadb_comb_soft_allocations;
293 uint32_t sadb_comb_hard_allocations;
294 uint64_t sadb_comb_soft_bytes;
295 uint64_t sadb_comb_hard_bytes;
296 uint64_t sadb_comb_soft_addtime;
297 uint64_t sadb_comb_hard_addtime;
298 uint64_t sadb_comb_soft_usetime;
299 uint64_t sadb_comb_hard_usetime;
300 };
301 .fi
302 .in -2
304 .SS "Extended Combination"
305 .in +2
306 .nf
307 struct sadb_x_ecomb {
308 uint8_t sadb_x_ecomb_numalgs;
309 uint8_t sadb_x_ecomb_reserved;
310 uint16_t sadb_x_ecomb_flags; /* E.g. PFS? */
311 uint32_t sadb_x_ecomb_reserved2;
312 uint32_t sadb_x_ecomb_soft_allocations;
313 uint32_t sadb_x_ecomb_hard_allocations;
314 uint64_t sadb_x_ecomb_soft_bytes;
315 uint64_t sadb_x_ecomb_hard_bytes;
316 uint64_t sadb_x_ecomb_soft_addtime;
317 uint64_t sadb_x_ecomb_hard_addtime;
318 uint64_t sadb_x_ecomb_soft_usetime;
319 uint64_t sadb_x_ecomb_hard_usetime;
320 };
321 .fi
322 .in -2
324 .SS "Extended Combination Algorithm Descriptors"
325 .in +2
326 .nf
327 struct sadb_x_algdesc {
328 uint8_t sadb_x_algdesc_satype; /* ESP, AH, etc. */
329 uint8_t sadb_x_algdesc_algtype; /* AUTH, CRYPT, COMPRESS */
330 uint8_t sadb_x_algdesc_alg; /* DES, 3DES, MD5, etc. */
331 uint8_t sadb_x_algdesc_reserved;
332 uint16_t sadb_x_algdesc_minbits; /* Bit strengths. */
333 uint16_t sadb_x_algdesc_maxbits;
334 };
335 .fi
336 .in -2
338 .SS "Extended Register"
339 .in +2
340 .nf
341 struct sadb_x_ereg {
342 uint16_t sadb_x_ereg_len;
343 uint16_t sadb_x_ereg_exttype; /* X_EREG */
344 uint8_t sadb_x_ereg_satypes[4]; /* Array of SA types, 0-terminated.
345 |};
346 .fi
347 .in -2
349 .SS "Key Management Cookie"
350 .in +2
351 .nf
352 struct sadb_x_kmc {
353 uint16_t sadb_x_kmc_len;
354 uint16_t sadb_x_kmc_exttype; /* X_KM_COOKIE */
355 uint32_t sadb_x_kmc_proto; /* KM protocol */
356 uint32_t sadb_x_kmc_cookie; /* KMP-specific */
357 uint32_t sadb_x_kmc_reserved; /* Reserved; must be zero */
358 };
359 .fi
360 .in -2
362 .SS "Supported Algorithms Extension"
363 .in +2
364 .nf
365 struct sadb_supported {
366 uint16_t sadb_supported_len;
367 uint16_t sadb_supported_exttype;
368 uint32_t sadb_supported_reserved;
369 };
370 .fi
371 .in -2
373 .SS "Algorithm Instance"
374 .in +2
375 .nf
376 struct sadb_alg {
377 uint8_t sadb_alg_id; /* Algorithm type. */
378 uint8_t sadb_alg_ivlen; /* IV len, in bits */
379 uint16_t sadb_alg_minbits; /* Min. key len (in bits) */
380 uint16_t sadb_alg_maxbits; /* Max. key length */
381 uint16_t sadb_alg_reserved;
382 };
383 .fi
384 .in -2
386 .SS "SPI Extension Range"
387 .in +2
388 .nf
389 struct sadb_spirange {
390 uint16_t sadb_spirange_len;
391 uint16_t sadb_spirange_exttype; /* SPI_RANGE */
392 uint32_t sadb_spirange_min
393 uint32_t sadb_spirange_max;
394 uint32_t sadb_spirange_reserved;
395 };
396 .fi
397 .in -2
399 .SS "Security Association Pair Extension"
400 .in +2
401 .nf
402 struct sadb_x_pair {
403 uint16_t sadb_x_pair_len;
404 uint16_t sadb_x_pair_exttype; /* SADB_X_EXT_PAIR */
405 uint32_t sadb_x_pair_spi; /* SPI of paired SA */
406 };
407 .fi
408 .in -2
410 .SS "Message Use and Behavior"
411 .LP
412 Each message has a behavior. A behavior is defined as where the initial message
413 travels, for example, user to kernel, and what subsequent actions are expected
414 to take place. Contents of messages are illustrated as:
415 .sp
416 .in +2
417 .nf
418 <base, REQUIRED EXTENSION, REQ., (OPTIONAL EXTENSION,) (OPT)>
419 .fi
420 .in -2
422 .sp
423 .LP
424 The \fBSA\fR extension is sometimes used only for its \fBSPI\fR field. If all
425 other fields must be ignored, this is represented by \fBSA\fR(*).
426 .sp
427 .LP
428 The lifetime extensions are represented with one to three letters after the
429 word lifetime, representing (H)ARD, (S)OFT, and (C)URRENT.
430 .sp
431 .LP
432 The address extensions are represented with one to three letters after the word
433 "address," representing (S)RC, (D)ST, (Nl)NAT-T local, (Nr)NAT-T remote,
434 (Is)Inner source, and (Id)Inner destination.
435 .sp
436 .LP
437 Source and destination address extensions reflect outer-header selectors for an
438 IPsec SA. An SA is inbound or outbound depending on which of the source or
439 destination address is local to the node. Inner-source and inner-destination
440 selectors represent inner-header selectors for Tunnel Mode SAs. A Tunnel Mode
441 SA \fBmust\fR have either IPPROTO_ENCAP or IPPROTO_IPV6 in its outer-headers as
442 protocol selector, in addition to filled-in Inner-address extensions.
443 .sp
444 .LP
445 NAT-T local and NAT-T remote addresses store local and remote ports used for
446 ESP-in-UDP encapsulation. A non-zero local NAT-T address extension represents
447 the local node's external IP address if it is not equivalent to the SA's local
448 address. A non-zero remote NAT-T address represents a peer's behind-a-NAT
449 address if it is not equivalent to the SA's remote address. An SA with NAT-T
450 extensions will protect-and-transmit outbound traffic. Processing of inbound
451 NAT-T traffic requires a UDP socket bound to the appropriate local port and it
452 \fBmust\fR have the UDP_NAT_T_ENDPOINT (see \fBudp\fR(7P)) socket option
453 enabled.
454 .sp
455 .LP
456 Note that when an error occurs, only the base header is sent. In the event of
457 an error, an extended diagnostic may be set (see DIAGNOSTICS). Typical errors
458 include:
459 .sp
460 .ne 2
461 .na
462 \fB\fBEINVAL\fR\fR
463 .ad
464 .RS 11n
465 Various message improprieties, including \fBSPI\fR ranges that are malformed,
466 weak keys, and others. If EINVAL is returned, an application should look at the
467 \fBsadb_x_msg_diagnostic\fR field of the sadb_msg structure. It contains one of
468 many possible causes for EINVAL. See \fBnet/pfkeyv2.h\fR for values, all of the
469 form SADB_X_DIAGNOSTIC_.
470 .RE
472 .sp
473 .ne 2
474 .na
475 \fB\fBENOMEM\fR\fR
476 .ad
477 .RS 11n
478 Needed memory was not available.
479 .RE
481 .sp
482 .ne 2
483 .na
484 \fB\fBENSGSIZ\fR\fR
485 .ad
486 .RS 11n
487 Message exceeds the maximum length allowed.
488 .RE
490 .sp
491 .ne 2
492 .na
493 \fB\fBEEXIST\fR\fR
494 .ad
495 .RS 11n
496 \fBSA\fR (that is being added or created with \fBGETSPI\fR) already exists.
497 .RE
499 .sp
500 .ne 2
501 .na
502 \fB\fBESRCH\fR\fR
503 .ad
504 .RS 11n
505 \fBSA\fR could not be found.
506 .RE
508 .sp
509 .LP
510 The following are examples of message use and behavior:
511 .SS "\fBSADB_GETSPI\fR"
512 .LP
513 Send a \fBSADB_GETSPI\fR message from a user process to the kernel.
514 .sp
515 .in +2
516 .nf
517 <base, address, SPI range>
518 .fi
519 .in -2
521 .sp
522 .LP
523 The kernel returns the \fBSADB_GETSPI\fR message to all listening processes.
524 .sp
525 .in +2
526 .nf
527 <base, SA(*), address (SD)>
528 .fi
529 .in -2
531 .SS "\fBSADB_UPDATE\fR"
532 .LP
533 Send a \fBSADB_UPDATE\fR message from a user process to the kernel.
534 .sp
535 .in +2
536 .nf
537 <base, SA, (lifetime(HS),) address(SD), (address(Is,Id),
538 address(Nl,Nr), key (AE), (identity(SD),) (sensitivity)>
539 .fi
540 .in -2
542 .sp
543 .LP
544 The kernel returns the \fBSADB_UPDATE\fR message to all listening processes.
545 .sp
546 .in +2
547 .nf
548 <base, SA(*), address (SD), (pair)>
549 .fi
550 .in -2
552 .sp
553 .LP
554 Adding a sadb_x_pair extension to an \fBSADB_UPDATE\fR or \fBSADB_ADD\fR
555 message will update the security association pair linkage with the SPI of the
556 security association contained in that extension. The resulting security
557 association "pair" can be updated or as a single entity using the
558 \fBSADB_X_UPDATEPAIR\fR or \fBSADB_X_DELPAIR\fR message types.
559 .SS "\fBSADB_ADD\fR"
560 .LP
561 Send a \fBSADB_ADD\fR message from a user process to the kernel.
562 .sp
563 .in +2
564 .nf
565 <base, SA, (lifetime(HS),) address(SD), (address(Is,Id),)
566 (address(Nl,Nr),) key (AE), (identity(SD),) (sensitivity) (pair)>
567 .fi
568 .in -2
570 .sp
571 .LP
572 The kernel returns the \fBSADB_ADD\fR message to all listening processes.
573 .sp
574 .in +2
575 .nf
576 <base, SA, (lifetime(HS),) address (SD), (address(Is,Id),)
577 (address(Nl,Nr),) (identity (SD),) (sensitivity)>
578 .fi
579 .in -2
581 .SS "\fBSADB_X_UPDATEPAIR\fR"
582 .LP
583 Send a \fBSADB_X_UPDATEPAIR\fR message from a user process to the kernel.
584 This message type is used to update the lifetime values of a security
585 association and the lifetime values of the security association it is paired
586 with.
587 .sp
588 .in +2
589 .nf
590 <base, SA, lifetime(HS), address(SD)>
591 .fi
592 .in -2
594 .SS "\fBSADB_DELETE | SADB_X_DELPAIR\fR"
595 .LP
596 Send a \fBSADB_DELETE\fR message from a user process to the kernel. The
597 \fBSADB_X_DELPAIR\fR message type will request deletion of the security
598 association and the security association it is paired with.
599 .sp
600 .in +2
601 .nf
602 <base, SA (*), address (SD)>
603 .fi
604 .in -2
606 .sp
607 .LP
608 The kernel returns the \fBSADB_DELETE\fR message to all listening processes.
609 .sp
610 .in +2
611 .nf
612 <base, SA (*), address (SD)>
613 .fi
614 .in -2
616 .SS "\fBSADB_GET\fR"
617 .LP
618 Send a \fBSADB_GET\fR message from a user process to the kernel.
619 .sp
620 .in +2
621 .nf
622 <base, SA (*), address (SD)>
623 .fi
624 .in -2
626 .sp
627 .LP
628 The kernel returns the \fBSADB_GET\fR message to the socket that sent the
629 \fBSADB_GET\fR message.
630 .sp
631 .in +2
632 .nf
633 <base, SA , (lifetime (HSC),) address SD), (address (P),) key (AE),
634 (identity (SD),) (sensitivity)>
635 .fi
636 .in -2
638 .SS "\fBSADB_ACQUIRE\fR"
639 .LP
640 The kernel sends a \fBSADB_ACQUIRE\fR message to registered sockets. Note that
641 any \fBGETSPI\fR, \fBADD\fR, or \fBUPDATE\fR calls in reaction to an
642 \fBACQUIRE\fR must fill in the \fBsadb_msg_seq\fR of those messages with the
643 one in the \fBACQUIRE\fR message. The address (\fBSD\fR) extensions must have
644 the port fields filled in with the port numbers of the session requiring keys
645 if appropriate.
646 .sp
647 .in +2
648 .nf
649 <base, address (SD), (address(Is,Id)), (identity(SD),)
650 (sensitivity,) proposal>
651 .fi
652 .in -2
654 .sp
655 .LP
656 Extended ACQUIRE will have a slightly different format. The
657 \fBsadb_msg_satype\fR field is 0, and the extension contains the desired
658 combination(s) of security protocols.
659 .sp
660 .in +2
661 .nf
662 <base, address (SD), (address(Is,Id)), (identity(SD),)
663 (sensitivity,) eprop>
664 .fi
665 .in -2
667 .sp
668 .LP
669 If key management fails, send an \fBSADB_ACQUIRE\fR to indicate failure.
670 .sp
671 .in +2
672 .nf
673 <base>
674 .fi
675 .in -2
677 .SS "\fBSADB_X_INVERSE_ACQUIRE\fR"
678 .LP
679 For inbound Key Management processing, a Key Management application may wish to
680 consult the kernel for its policy. The application should send to the kernel:
681 .sp
682 .in +2
683 .nf
684 <base, address (SD), (address(Is,Id))>
685 .fi
686 .in -2
688 .sp
689 .LP
690 The kernel returns a message similar to a kernel-generated extended ACQUIRE:
691 .sp
692 .in +2
693 .nf
694 <base, address (SD), (address(Is,Id)), (identity(SD),)
695 (sensitivity,) eprop>
696 .fi
697 .in -2
699 .SS "\fBSADB_REGISTER\fR"
700 .LP
701 Send a \fBSADB_REGISTER\fR message from a user process to the kernel.
702 .sp
703 .in +2
704 .nf
705 <base>
706 .fi
707 .in -2
709 .sp
710 .LP
711 The kernel returns the \fBSADB_REGISTER\fR message to registered sockets, with
712 algorithm types supported by the kernel being indicated in the supported
713 algorithms field. Note that this message may arrive asynchronously due to an
714 algorithm being loaded or unloaded into a dynamically linked kernel.
715 .sp
716 .in +2
717 .nf
718 <base, supported>
719 .fi
720 .in -2
722 .sp
723 .LP
724 There is also the extended REGISTER, which will allow this process to receive
725 extended ACQUIREs.
726 .sp
727 .in +2
728 .nf
729 <base, ereg>
730 .fi
731 .in -2
733 .sp
734 .LP
735 Which returns a series of SADB_REGISTER replies (one for each security protocol
736 registered) from the kernel.
737 .SS "\fBSADB_EXPIRE\fR"
738 .LP
739 The kernel sends a \fBSADB_EXPIRE\fR message to all listeners when the soft
740 limit of a security association has been expired.
741 .sp
742 .in +2
743 .nf
744 <base, SA, lifetime (C and one of HS), address (SD)>
745 .fi
746 .in -2
748 .SS "\fBSADB_FLUSH\fR"
749 .LP
750 Send a \fBSADB_FLUSH\fR message from a user process to the kernel.
751 .sp
752 .in +2
753 .nf
754 <base>
755 .fi
756 .in -2
758 .sp
759 .LP
760 The kernel returns the \fBSADB_FLUSH\fR message to all listening sockets.
761 .sp
762 .in +2
763 .nf
764 <base>
765 .fi
766 .in -2
768 .SS "\fBSADB_DUMP\fR"
769 .LP
770 Send a \fBSADB_DUMP\fR message from a user process to the kernel.
771 .sp
772 .in +2
773 .nf
774 <base>
775 .fi
776 .in -2
778 .sp
779 .LP
780 Several \fBSADB_DUMP\fR messages will return from the kernel to the sending
781 socket.
782 .sp
783 .in +2
784 .nf
785 <base, SA, (lifetime (HSC),) address (SD), (address (Is,Id),)
786 (address (Nl,Nr),) key (AE), (identity (SD),) sensitivity)>
787 .fi
788 .in -2
790 .sp
791 .LP
792 To mark the end of a dump a single base header arrives with its
793 \fBsadb_mdg_seq\fR set to 0.
794 .sp
795 .in +2
796 .nf
797 <base>
798 .fi
799 .in -2
801 .SS "\fBSADB_X_PROMISC\fR"
802 .LP
803 Send a \fBSADB_X_PROMISC\fR message from a user process to the kernel.
804 .sp
805 .in +2
806 .nf
807 <base>
808 .fi
809 .in -2
811 .sp
812 .LP
813 The kernel returns the \fBSADB_X_PROMISC\fR message to all listening processes.
814 .sp
815 .in +2
816 .nf
817 <base>
818 .fi
819 .in -2
821 .SH DIAGNOSTICS
822 .LP
823 The message returning from the kernel will contain a diagnostic value in the
824 base message header, the diagnostic value will indicate if action requested by
825 the original message was a success.
826 .sp
827 .LP
828 Diagnostic Values:
829 .sp
830 .in +2
831 .nf
832 #define SADB_X_DIAGNOSTIC_NONE 0
833 #define SADB_X_DIAGNOSTIC_UNKNOWN_MSG 1
834 #define SADB_X_DIAGNOSTIC_UNKNOWN_EXT 2
835 #define SADB_X_DIAGNOSTIC_BAD_EXTLEN 3
836 #define SADB_X_DIAGNOSTIC_UNKNOWN_SATYPE 4
837 #define SADB_X_DIAGNOSTIC_SATYPE_NEEDED 5
838 #define SADB_X_DIAGNOSTIC_NO_SADBS 6
839 #define SADB_X_DIAGNOSTIC_NO_EXT 7
840 /* Bad address family value */
841 #define SADB_X_DIAGNOSTIC_BAD_SRC_AF 8
842 /* in sockaddr->sa_family. */
843 #define SADB_X_DIAGNOSTIC_BAD_DST_AF 9
844 /* These two are synonyms. */
845 #define SADB_X_DIAGNOSTIC_BAD_PROXY_AF 10
846 #define SADB_X_DIAGNOSTIC_BAD_INNER_SRC_AF 10
848 #define SADB_X_DIAGNOSTIC_AF_MISMATCH 11
850 #define SADB_X_DIAGNOSTIC_BAD_SRC 12
851 #define SADB_X_DIAGNOSTIC_BAD_DST 13
853 #define SADB_X_DIAGNOSTIC_ALLOC_HSERR 14
854 #define SADB_X_DIAGNOSTIC_BYTES_HSERR 15
855 #define SADB_X_DIAGNOSTIC_ADDTIME_HSERR 16
856 #define SADB_X_DIAGNOSTIC_USETIME_HSERR 17
858 #define SADB_X_DIAGNOSTIC_MISSING_SRC 18
859 #define SADB_X_DIAGNOSTIC_MISSING_DST 19
860 #define SADB_X_DIAGNOSTIC_MISSING_SA 20
861 #define SADB_X_DIAGNOSTIC_MISSING_EKEY 21
862 #define SADB_X_DIAGNOSTIC_MISSING_AKEY 22
863 #define SADB_X_DIAGNOSTIC_MISSING_RANGE 23
865 #define SADB_X_DIAGNOSTIC_DUPLICATE_SRC 24
866 #define SADB_X_DIAGNOSTIC_DUPLICATE_DST 25
867 #define SADB_X_DIAGNOSTIC_DUPLICATE_SA 26
868 #define SADB_X_DIAGNOSTIC_DUPLICATE_EKEY 27
869 #define SADB_X_DIAGNOSTIC_DUPLICATE_AKEY 28
870 #define SADB_X_DIAGNOSTIC_DUPLICATE_RANGE 29
872 #define SADB_X_DIAGNOSTIC_MALFORMED_SRC 30
873 #define SADB_X_DIAGNOSTIC_MALFORMED_DST 31
874 #define SADB_X_DIAGNOSTIC_MALFORMED_SA 32
875 #define SADB_X_DIAGNOSTIC_MALFORMED_EKEY 33
876 #define SADB_X_DIAGNOSTIC_MALFORMED_AKEY 34
877 #define SADB_X_DIAGNOSTIC_MALFORMED_RANGE 35
879 #define SADB_X_DIAGNOSTIC_AKEY_PRESENT 36
880 #define SADB_X_DIAGNOSTIC_EKEY_PRESENT 37
881 #define SADB_X_DIAGNOSTIC_PROP_PRESENT 38
882 #define SADB_X_DIAGNOSTIC_SUPP_PRESENT 39
883 #define SADB_X_DIAGNOSTIC_BAD_AALG 40
884 #define SADB_X_DIAGNOSTIC_BAD_EALG 41
885 #define SADB_X_DIAGNOSTIC_BAD_SAFLAGS 42
886 #define SADB_X_DIAGNOSTIC_BAD_SASTATE 43
888 #define SADB_X_DIAGNOSTIC_BAD_AKEYBITS 44
889 #define SADB_X_DIAGNOSTIC_BAD_EKEYBITS 45
891 #define SADB_X_DIAGNOSTIC_ENCR_NOTSUPP 46
893 #define SADB_X_DIAGNOSTIC_WEAK_EKEY 47
894 #define SADB_X_DIAGNOSTIC_WEAK_AKEY 48
896 #define SADB_X_DIAGNOSTIC_DUPLICATE_KMP 49
897 #define SADB_X_DIAGNOSTIC_DUPLICATE_KMC 50
899 #define SADB_X_DIAGNOSTIC_MISSING_NATT_LOC 51
900 #define SADB_X_DIAGNOSTIC_MISSING_NATT_REM 52
901 #define SADB_X_DIAGNOSTIC_DUPLICATE_NATT_LOC 53
902 #define SADB_X_DIAGNOSTIC_DUPLICATE_NATT_REM 54
903 #define SADB_X_DIAGNOSTIC_MALFORMED_NATT_LOC 55
904 #define SADB_X_DIAGNOSTIC_MALFORMED_NATT_REM 56
905 #define SADB_X_DIAGNOSTIC_DUPLICATE_NATT_PORTS 57
907 #define SADB_X_DIAGNOSTIC_MISSING_INNER_SRC 58
908 #define SADB_X_DIAGNOSTIC_MISSING_INNER_DST 59
909 #define SADB_X_DIAGNOSTIC_DUPLICATE_INNER_SRC 60
910 #define SADB_X_DIAGNOSTIC_DUPLICATE_INNER_DST 61
911 #define SADB_X_DIAGNOSTIC_MALFORMED_INNER_SRC 62
912 #define SADB_X_DIAGNOSTIC_MALFORMED_INNER_DST 63
914 #define SADB_X_DIAGNOSTIC_PREFIX_INNER_SRC 64
915 #define SADB_X_DIAGNOSTIC_PREFIX_INNER_DST 65
916 #define SADB_X_DIAGNOSTIC_BAD_INNER_DST_AF 66
917 #define SADB_X_DIAGNOSTIC_INNER_AF_MISMATCH 67
919 #define SADB_X_DIAGNOSTIC_BAD_NATT_REM_AF 68
920 #define SADB_X_DIAGNOSTIC_BAD_NATT_LOC_AF 69
922 #define SADB_X_DIAGNOSTIC_PROTO_MISMATCH 70
923 #define SADB_X_DIAGNOSTIC_INNER_PROTO_MISMATCH 71
925 #define SADB_X_DIAGNOSTIC_DUAL_PORT_SETS 72
927 #define SADB_X_DIAGNOSTIC_PAIR_INAPPROPRIATE 73
928 #define SADB_X_DIAGNOSTIC_PAIR_ADD_MISMATCH 74
929 #define SADB_X_DIAGNOSTIC_PAIR_ALREADY 75
930 #define SADB_X_DIAGNOSTIC_PAIR_SA_NOTFOUND 76
931 #define SADB_X_DIAGNOSTIC_BAD_SA_DIRECTION 77
933 #define SADB_X_DIAGNOSTIC_SA_NOTFOUND 78
934 #define SADB_X_DIAGNOSTIC_SA_EXPIRED 79
935 .fi
936 .in -2
938 .SH ATTRIBUTES
939 .LP
940 See \fBattributes\fR(5) for descriptions of the following attributes:
941 .sp
943 .sp
944 .TS
945 box;
946 c | c
947 l | l .
948 ATTRIBUTE TYPE ATTRIBUTE VALUE
949 Interface Stability Evolving
950 .TE
952 .SH SEE ALSO
953 .LP
954 \fBin.iked\fR(1M), \fBipseckey\fR(1M), \fBsockaddr\fR(3SOCKET),
955 \fBipsec\fR(7P), \fBipsecah\fR(7P),
956 \fBipsecesp\fR(7P), \fBroute\fR(7P), \fBudp\fR(7P)
957 .sp
958 .LP
959 McDonald, D.L., Metz, C.W., and Phan, B.G., \fIRFC 2367, PF_KEY Key Management
960 API, Version 2\fR, The Internet Society, July 1998.
961 .SH NOTES
962 .LP
963 Time-based lifetimes may not expire with exact precision in seconds because
964 kernel load may affect the aging of \fBSA\fR's.