| blob | 032702d537d4ba751ab0c0c371bb688f3bc74b94 |
7 Network Working Group D. McDonald
8 Request for Comments: 2367 C. Metz
9 Category: Informational B. Phan
10 July 1998
13 PF_KEY Key Management API, Version 2
15 Status of this Memo
17 This memo provides information for the Internet community. It does
18 not specify an Internet standard of any kind. Distribution of this
19 memo is unlimited.
21 Copyright Notice
23 Copyright (C) The Internet Society (1998). All Rights Reserved.
25 Abstract
27 A generic key management API that can be used not only for IP
28 Security [Atk95a] [Atk95b] [Atk95c] but also for other network
29 security services is presented in this document. Version 1 of this
30 API was implemented inside 4.4-Lite BSD as part of the U. S. Naval
31 Research Laboratory's freely distributable and usable IPv6 and IPsec
32 implementation[AMPMC96]. It is documented here for the benefit of
33 others who might also adopt and use the API, thus providing increased
34 portability of key management applications (e.g. a manual keying
35 application, an ISAKMP daemon, a GKMP daemon [HM97a][HM97b], a
36 Photuris daemon, or a SKIP certificate discovery protocol daemon).
38 Table of Contents
40 1 Introduction ............................................. 3
41 1.1 Terminology .............................................. 3
42 1.2 Conceptual Model ......................................... 4
43 1.3 PF_KEY Socket Definition ................................. 8
44 1.4 Overview of PF_KEY Messaging Behavior .................... 8
45 1.5 Common PF_KEY Operations ................................. 9
46 1.6 Differences Between PF_KEY and PF_ROUTE .................. 10
47 1.7 Name Space ............................................... 11
48 1.8 On Manual Keying ..........................................11
49 2 PF_KEY Message Format .................................... 11
50 2.1 Base Message Header Format ............................... 12
51 2.2 Alignment of Headers and Extension Headers ............... 14
52 2.3 Additional Message Fields ................................ 14
53 2.3.1 Association Extension .................................... 15
54 2.3.2 Lifetime Extension ....................................... 16
58 McDonald, et. al. Informational [Page 1]
59 \f
60 RFC 2367 PF_KEY Key Management API July 1998
63 2.3.3 Address Extension ........................................ 18
64 2.3.4 Key Extension ............................................ 19
65 2.3.5 Identity Extension ....................................... 21
66 2.3.6 Sensitivity Extension .................................... 21
67 2.3.7 Proposal Extension ....................................... 22
68 2.3.8 Supported Algorithms Extension ........................... 25
69 2.3.9 SPI Range Extension ...................................... 26
70 2.4 Illustration of Message Layout ........................... 27
71 3 Symbolic Names ........................................... 30
72 3.1 Message Types ............................................ 31
73 3.1.1 SADB_GETSPI .............................................. 32
74 3.1.2 SADB_UPDATE .............................................. 33
75 3.1.3 SADB_ADD ................................................. 34
76 3.1.4 SADB_DELETE .............................................. 35
77 3.1.5 SADB_GET ................................................. 36
78 3.1.6 SADB_ACQUIRE ............................................. 36
79 3.1.7 SADB_REGISTER ............................................ 38
80 3.1.8 SADB_EXPIRE .............................................. 39
81 3.1.9 SADB_FLUSH ............................................... 40
82 3.1.10 SADB_DUMP ................................................ 40
83 3.2 Security Association Flags ............................... 41
84 3.3 Security Association States .............................. 41
85 3.4 Security Association Types ............................... 41
86 3.5 Algorithm Types .......................................... 42
87 3.6 Extension Header Values .................................. 43
88 3.7 Identity Extension Values ................................ 44
89 3.8 Sensitivity Extension Values ............................. 45
90 3.9 Proposal Extension Values ................................ 45
91 4 Future Directions ........................................ 45
92 5 Examples ................................................. 45
93 5.1 Simple IP Security Example ............................... 46
94 5.2 Proxy IP Security Example ................................ 47
95 5.3 OSPF Security Example .................................... 50
96 5.4 Miscellaneous ............................................ 50
97 6 Security Considerations .................................. 51
98 Acknowledgments ............,............................. 52
99 References ............................................... 52
100 Disclaimer ............................................... 54
101 Authors' Addresses ....................................... 54
102 A Promiscuous Send/Receive Extension ....................... 55
103 B Passive Change Message Extension ......................... 57
104 C Key Management Private Data Extension .................... 58
105 D Sample Header File ....................................... 59
106 E Change Log ............................................... 64
107 F Full Copyright Statement ................................. 68
114 McDonald, et. al. Informational [Page 2]
115 \f
116 RFC 2367 PF_KEY Key Management API July 1998
119 1 Introduction
121 PF_KEY is a new socket protocol family used by trusted privileged key
122 management applications to communicate with an operating system's key
123 management internals (referred to here as the "Key Engine" or the
124 Security Association Database (SADB)). The Key Engine and its
125 structures incorporate the required security attributes for a session
126 and are instances of the "Security Association" (SA) concept
127 described in [Atk95a]. The names PF_KEY and Key Engine thus refer to
128 more than cryptographic keys and are retained for consistency with
129 the traditional phrase, "Key Management".
131 PF_KEY is derived in part from the BSD routing socket, PF_ROUTE.
132 [Skl91] This document describes Version 2 of PF_KEY. Version 1 was
133 implemented in the first five alpha test versions of the NRL
134 IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco
135 ISAKMP/Oakley key management daemon. Version 2 extends and refines
136 this interface. Theoretically, the messages defined in this document
137 could be used in a non-socket context (e.g. between two directly
138 communicating user-level processes), but this document will not
139 discuss in detail such possibilities.
141 Security policy is deliberately omitted from this interface. PF_KEY
142 is not a mechanism for tuning systemwide security policy, nor is it
143 intended to enforce any sort of key management policy. The developers
144 of PF_KEY believe that it is important to separate security
145 mechanisms (such as PF_KEY) from security policies. This permits a
146 single mechanism to more easily support multiple policies.
148 1.1 Terminology
150 Even though this document is not intended to be an actual Internet
151 standard, the words that are used to define the significance of
152 particular features of this interface are usually capitalized. Some
153 of these words, including MUST, MAY, and SHOULD, are detailed in
154 [Bra97].
156 - CONFORMANCE and COMPLIANCE
158 Conformance to this specification has the same meaning as compliance
159 to this specification. In either case, the mandatory-to-implement,
160 or MUST, items MUST be fully implemented as specified here. If any
161 mandatory item is not implemented as specified here, that
162 implementation is not conforming and not compliant with this
163 specification.
170 McDonald, et. al. Informational [Page 3]
171 \f
172 RFC 2367 PF_KEY Key Management API July 1998
175 This specification also uses many terms that are commonly used in the
176 context of network security. Other documents provide more
177 definitions and background information on these [VK83, HA94, Atk95a].
178 Two terms deserve special mention:
180 - (Encryption/Authentication) Algorithm
182 For PF_KEY purposes, an algorithm, whether encryption or
183 authentication, is the set of operations performed on a packet to
184 complete authentication or encryption as indicated by the SA type. A
185 PF_KEY algorithm MAY consist of more than one cryptographic
186 algorithm. Another possibility is that the same basic cryptographic
187 algorithm may be applied with different modes of operation or some
188 other implementation difference. These differences, henceforth called
189 _algorithm differentiators_, distinguish between different PF_KEY
190 algorithms, and options to the same algorithm. Algorithm
191 differentiators will often cause fundamentally different security
192 properties.
194 For example, both DES and 3DES use the same cryptographic algorithm,
195 but they are used differently and have different security properties.
196 The triple-application of DES is considered an algorithm
197 differentiator. There are therefore separate PF_KEY algorithms for
198 DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same hash function, but
199 construct their message authentication codes differently. The use of
200 HMAC is an algorithm differentiator. DES-ECB and DES-CBC are the
201 same cryptographic algorithm, but use a different mode. Mode (e.g.,
202 chaining vs. code-book) is an algorithm differentiator. Blowfish with
203 a 128-bit key, however, is similar to Blowfish with a 384-bit key,
204 because the algorithm's workings are otherwise the same and therefore
205 the key length is not an algorithm differentiator.
207 In terms of IP Security, a general rule of thumb is that whatever
208 might be labeled the "encryption" part of an ESP transform is
209 probably a PF_KEY encryption algorithm. Whatever might be labelled
210 the "authentication" part of an AH or ESP transform is probably a
211 PF_KEY authentication algorithm.
213 1.2 Conceptual Model
215 This section describes the conceptual model of an operating system
216 that implements the PF_KEY key management application programming
217 interface. This section is intended to provide background material
218 useful to understand the rest of this document. Presentation of this
219 conceptual model does not constrain a PF_KEY implementation to
220 strictly adhere to the conceptual components discussed in this
221 subsection.
226 McDonald, et. al. Informational [Page 4]
227 \f
228 RFC 2367 PF_KEY Key Management API July 1998
231 Key management is most commonly implemented in whole or in part at
232 the application layer. For example, the ISAKMP/Oakley, GKMP, and
233 Photuris proposals for IPsec key management are all application-layer
234 protocols. Manual keying is also done at the application layer.
235 Even parts of the SKIP IP-layer keying proposal can be implemented at
236 the application layer. Figure 1 shows the relationship between a Key
237 Management daemon and PF_KEY. Key management daemons use PF_KEY to
238 communicate with the Key Engine and use PF_INET (or PF_INET6 in the
239 case of IPv6) to communicate, via the network, with a remote key
240 management entity.
242 The "Key Engine" or "Security Association Database (SADB)" is a
243 logical entity in the kernel that stores, updates, and deletes
244 Security Association data for various security protocols. There are
245 logical interfaces within the kernel (e.g. getassocbyspi(),
246 getassocbysocket()) that security protocols inside the kernel (e.g.
247 IP Security, aka IPsec) use to request and obtain Security
248 Associations.
250 In the case of IPsec, if by policy a particular outbound packet needs
251 processing, then the IPsec implementation requests an appropriate
252 Security Association from the Key Engine via the kernel-internal
253 interface. If the Key Engine has an appropriate SA, it allocates the
254 SA to this session (marking it as used) and returns the SA to the
255 IPsec implementation for use. If the Key Engine has no such SA but a
256 key management application has previously indicated (via a PF_KEY
257 SADB_REGISTER message) that it can obtain such SAs, then the Key
258 Engine requests that such an SA be created (via a PF_KEY SADB_ACQUIRE
259 message). When the key management daemon creates a new SA, it places
260 it into the Key Engine for future use.
282 McDonald, et. al. Informational [Page 5]
283 \f
284 RFC 2367 PF_KEY Key Management API July 1998
287 +---------------+
288 |Key Mgmt Daemon|
289 +---------------+
290 | |
291 | |
292 | | Applications
293 ======[PF_KEY]====[PF_INET]==========================
294 | | OS Kernel
295 +------------+ +-----------------+
296 | Key Engine | | TCP/IP, |
297 | or SADB |---| including IPsec |
298 +------------+ | |
299 +-----------------+
300 |
301 +-----------+
302 | Network |
303 | Interface |
304 +-----------+
306 Figure 1: Relationship of Key Mgmt to PF_KEY
308 For performance reasons, some security protocols (e.g. IP Security)
309 are usually implemented inside the operating system kernel. Other
310 security protocols (e.g. OSPFv2 Cryptographic Authentication) are
311 implemented in trusted privileged applications outside the kernel.
312 Figure 2 shows a trusted, privileged routing daemon using PF_INET to
313 communicate routing information with a remote routing daemon and
314 using PF_KEY to request, obtain, and delete Security Associations
315 used with a routing protocol.
338 McDonald, et. al. Informational [Page 6]
339 \f
340 RFC 2367 PF_KEY Key Management API July 1998
343 +---------------+
344 |Routing Daemon|
345 +---------------+
346 | |
347 | |
348 | | Applications
349 ======[PF_KEY]====[PF_INET]==========================
350 | | OS Kernel
351 +------------+ +---------+
352 | Key Engine | | TCP/IP |
353 | or SADB |---| |
354 +------------+ +---------+
355 |
356 +-----------+
357 | Network |
358 | Interface |
359 +-----------+
361 Figure 2: Relationship of Trusted Application to PF_KEY
363 When a trusted privileged application is using the Key Engine but
364 implements the security protocol within itself, then operation varies
365 slightly. In this case, the application needing an SA sends a PF_KEY
366 SADB_ACQUIRE message down to the Key Engine, which then either
367 returns an error or sends a similar SADB_ACQUIRE message up to one or
368 more key management applications capable of creating such SAs. As
369 before, the key management daemon stores the SA into the Key Engine.
370 Then, the trusted privileged application uses an SADB_GET message to
371 obtain the SA from the Key Engine.
373 In some implementations, policy may be implemented in user-space,
374 even though the actual cryptographic processing takes place in the
375 kernel. Such policy communication between the kernel mechanisms and
376 the user-space policy MAY be implemented by PF_KEY extensions, or
377 other such mechanism. This document does not specify such
378 extensions. A PF_KEY implementation specified by the memo does NOT
379 have to support configuring systemwide policy using PF_KEY.
381 Untrusted clients, for example a user's web browser or telnet client,
382 do not need to use PF_KEY. Mechanisms not specified here are used by
383 such untrusted client applications to request security services (e.g.
384 IPsec) from an operating system. For security reasons, only trusted,
385 privileged applications are permitted to open a PF_KEY socket.
394 McDonald, et. al. Informational [Page 7]
395 \f
396 RFC 2367 PF_KEY Key Management API July 1998
399 1.3 PF_KEY Socket Definition
401 The PF_KEY protocol family (PF_KEY) symbol is defined in
402 <sys/socket.h> in the same manner that other protocol families are
403 defined. PF_KEY does not use any socket addresses. Applications
404 using PF_KEY MUST NOT depend on the availability of a symbol named
405 AF_KEY, but kernel implementations are encouraged to define that
406 symbol for completeness.
408 The key management socket is created as follows:
410 #include <sys/types.h>
411 #include <sys/socket.h>
412 #include <net/pfkeyv2.h>
414 int s;
415 s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2);
417 The PF_KEY domain currently supports only the SOCK_RAW socket type.
418 The protocol field MUST be set to PF_KEY_V2, or else EPROTONOSUPPORT
419 will be returned. Only a trusted, privileged process can create a
420 PF_KEY socket. On conventional UNIX systems, a privileged process is
421 a process with an effective userid of zero. On non-MLS proprietary
422 operating systems, the notion of a "privileged process" is
423 implementation-defined. On Compartmented Mode Workstations (CMWs) or
424 other systems that claim to provide Multi-Level Security (MLS), a
425 process MUST have the "key management privilege" in order to open a
426 PF_KEY socket[DIA]. MLS systems that don't currently have such a
427 specific privilege MUST add that special privilege and enforce it
428 with PF_KEY in order to comply and conform with this specification.
429 Some systems, most notably some popular personal computers, do not
430 have the concept of an unprivileged user. These systems SHOULD take
431 steps to restrict the programs allowed to access the PF_KEY API.
433 1.4 Overview of PF_KEY Messaging Behavior
435 A process interacts with the key engine by sending and receiving
436 messages using the PF_KEY socket. Security association information
437 can be inserted into and retrieved from the kernel's security
438 association table using a set of predefined messages. In the normal
439 case, all properly-formed messages sent to the kernel are returned to
440 all open PF_KEY sockets, including the sender. Improperly formed
441 messages will result in errors, and an implementation MUST check for
442 a properly formed message before returning it to the appropriate
443 listeners. Unlike the routing socket, most errors are sent in reply
444 messages, not the errno field when write() or send() fails. PF_KEY
445 message delivery is not guaranteed, especially in cases where kernel
446 or socket buffers are exhausted and messages are dropped.
450 McDonald, et. al. Informational [Page 8]
451 \f
452 RFC 2367 PF_KEY Key Management API July 1998
455 Some messages are generated by the operating system to indicate that
456 actions need to be taken, and are not necessarily in response to any
457 message sent down by the user. Such messages are not received by all
458 PF_KEY sockets, but by sockets which have indicated that kernel-
459 originated messages are to be received. These messages are special
460 because of the expected frequency at which they will occur. Also, an
461 implementation may further wish to restrict return messages from the
462 kernel, in cases where not all PF_KEY sockets are in the same trust
463 domain.
465 Many of the normal BSD socket calls have undefined behavior on PF_KEY
466 sockets. These include: bind(), connect(), socketpair(), accept(),
467 getpeername(), getsockname(), ioctl(), and listen().
469 1.5 Common PF_KEY Operations
471 There are two basic ways to add a new Security Association into the
472 kernel. The simplest is to send a single SADB_ADD message,
473 containing all of the SA information, from the application into the
474 kernel's Key Engine. This approach works particularly well with
475 manual key management, which is required for IPsec, and other
476 security protocols.
478 The second approach to add a new Security Association into the kernel
479 is for the application to first request a Security Parameters Index
480 (SPI) value from the kernel using the SADB_GETSPI message and then
481 send an SADB_UPDATE message with the complete Security Association
482 data. This second approach works well with key management daemons
483 when the SPI values need to be known before the entire Security
484 Association data is known (e.g. so the SPI value can be indicated to
485 the remote end of the key management session).
487 An individual Security Association can be deleted using the
488 SADB_DELETE message. Categories of SAs or the entire kernel SA table
489 can be deleted using the SADB_FLUSH message.
491 The SADB_GET message is used by a trusted application-layer process
492 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF
493 SA) from the kernel's Key Engine.
495 The kernel or an application-layer can use the SADB_ACQUIRE message
496 to request that a Security Association be created by some
497 application-layer key management process that has registered with the
498 kernel via an SADB_REGISTER message. This ACQUIRE message will have
499 a sequence number associated with it. This sequence number MUST be
500 used by followup SADB_GETSPI, SADB_UPDATE, and SADB_ADD messages, in
501 order to keep track of which request gets its keying material. The
502 sequence number (described below) is similar to a transaction ID in a
506 McDonald, et. al. Informational [Page 9]
507 \f
508 RFC 2367 PF_KEY Key Management API July 1998
511 remote procedure call.
513 The SADB_EXPIRE message is sent from the kernel to key management
514 applications when the "soft lifetime" or "hard lifetime" of a
515 Security Association has expired. Key management applications should
516 use receipt of a soft lifetime SADB_EXPIRE message as a hint to
517 negotiate a replacement SA so the replacement SA will be ready and in
518 the kernel before it is needed.
520 A SADB_DUMP message is also defined, but this is primarily intended
521 for PF_KEY implementor debugging and is not used in ordinary
522 operation of PF_KEY.
524 1.6 Differences Between PF_KEY and PF_ROUTE
526 The following bullets are points of difference between the routing
527 socket and PF_KEY. Programmers who are used to the routing socket
528 semantics will find some differences in PF_KEY.
530 * PF_KEY message errors are usually returned in PF_KEY messages
531 instead of causing write() operations to fail and returning the
532 error number in errno. This means that other listeners on a PF_KEY
533 socket can be aware that requests from another process failed,
534 which can be useful for auditing purposes. This also means that
535 applications that fail to read PF_KEY messages cannot do error
536 checking.
538 An implementation MAY return the errors EINVAL, ENOMEM, and ENOBUFS
539 by causing write() operations to fail and returning the error
540 number in errno. This is an optimization for common error cases in
541 which it does not make sense for any other process to receive the
542 error. An application MUST NOT depend on such errors being set by
543 the write() call, but it SHOULD check for such errors, and handle
544 them in an appropriate manner.
546 * The entire message isn't always reflected in the reply. A SADB_ADD
547 message is an example of this.
549 * The PID is not set by the kernel. The process that originates the
550 message MUST set the sadb_msg_pid to its own PID. If the kernel
551 ORIGINATES a message, it MUST set the sadb_msg_pid to 0. A reply
552 to an original message SHOULD have the pid of the original message.
553 (E.g. the kernel's response to an SADB_ADD SHOULD have its pid set
554 to the pid value of the original SADB_ADD message.)
562 McDonald, et. al. Informational [Page 10]
563 \f
564 RFC 2367 PF_KEY Key Management API July 1998
567 1.7 Name Space
569 All PF_KEYv2 preprocessor symbols and structure definitions are
570 defined as a result of including the header file <net/pfkeyv2.h>.
571 There is exactly one exception to this rule: the symbol "PF_KEY" (two
572 exceptions if "AF_KEY" is also counted), which is defined as a result
573 of including the header file <sys/socket.h>. All PF_KEYv2
574 preprocessor symbols start with the prefix "SADB_" and all structure
575 names start with "sadb_". There are exactly two exceptions to this
576 rule: the symbol "PF_KEY_V2" and the symbol "PFKEYV2_REVISION".
578 The symbol "PFKEYV2_REVISION" is a date-encoded value not unlike
579 certain values defined by POSIX and X/Open. The current value for
580 PFKEYV2_REVISION is 199806L, where 1998 is the year and 06 is the
581 month.
583 Inclusion of the file <net/pfkeyv2.h> MUST NOT define symbols or
584 structures in the PF_KEYv2 name space that are not described in this
585 document without the explicit prior permission of the authors. Any
586 symbols or structures in the PF_KEYv2 name space that are not
587 described in this document MUST start with "SADB_X_" or "sadb_x_". An
588 implementation that fails to obey these rules IS NOT COMPLIANT WITH
589 THIS SPECIFICATION and MUST NOT make any claim to be. These rules
590 also apply to any files that might be included as a result of
591 including the file <net/pfkeyv2.h>. This rule provides implementors
592 with some assurance that they will not encounter namespace-related
593 surprises.
595 1.8 On Manual Keying
597 Not unlike the 4.4-Lite BSD PF_ROUTE socket, this interface allows an
598 application full-reign over the security associations in a kernel
599 that implements PF_KEY. A PF_KEY implementation MUST have some sort
600 of manual interface to PF_KEY, which SHOULD allow all of the
601 functionality of the programmatic interface described here.
603 2. PF_KEY Message Format
605 PF_KEY messages consist of a base header followed by additional data
606 fields, some of which may be optional. The format of the additional
607 data is dependent on the type of message.
609 PF_KEY messages currently do not mandate any specific ordering for
610 non-network multi-octet fields. Unless otherwise specified (e.g. SPI
611 values), fields MUST be in host-specific byte order.
618 McDonald, et. al. Informational [Page 11]
619 \f
620 RFC 2367 PF_KEY Key Management API July 1998
623 2.1 Base Message Header Format
625 PF_KEY messages consist of the base message header followed by
626 security association specific data whose types and lengths are
627 specified by a generic type-length encoding.
629 This base header is shown below, using POSIX types. The fields are
630 arranged primarily for alignment, and where possible, for reasons of
631 clarity.
633 struct sadb_msg {
634 uint8_t sadb_msg_version;
635 uint8_t sadb_msg_type;
636 uint8_t sadb_msg_errno;
637 uint8_t sadb_msg_satype;
638 uint16_t sadb_msg_len;
639 uint16_t sadb_msg_reserved;
640 uint32_t sadb_msg_seq;
641 uint32_t sadb_msg_pid;
642 };
643 /* sizeof(struct sadb_msg) == 16 */
645 sadb_msg_version
646 The version field of this PF_KEY message. This MUST
647 be set to PF_KEY_V2. If this is not set to PF_KEY_V2,
648 the write() call MAY fail and return EINVAL.
649 Otherwise, the behavior is undetermined, given that
650 the application might not understand the formatting
651 of the messages arriving from the kernel.
653 sadb_msg_type Identifies the type of message. The valid message
654 types are described later in this document.
656 sadb_msg_errno Should be set to zero by the sender. The responder
657 stores the error code in this field if an error has
658 occurred. This includes the case where the responder
659 is in user space. (e.g. user-space negotiation
660 fails, an errno can be returned.)
662 sadb_msg_satype Indicates the type of security association(s). Valid
663 Security Association types are declared in the file
664 <net/pfkeyv2.h>. The current set of Security
665 Association types is enumerated later in this
666 document.
674 McDonald, et. al. Informational [Page 12]
675 \f
676 RFC 2367 PF_KEY Key Management API July 1998
679 sadb_msg_len Contains the total length, in 64-bit words, of all
680 data in the PF_KEY message including the base header
681 length and additional data after the base header, if
682 any. This length includes any padding or extra space
683 that might exist. Unless otherwise stated, all other
684 length fields are also measured in 64-bit words.
686 On user to kernel messages, this field MUST be
687 verified against the length of the inbound message.
688 EMSGSIZE MUST be returned if the verification fails.
689 On kernel to user messages, a size mismatch is most
690 likely the result of the user not providing a large
691 enough buffer for the message. In these cases, the
692 user application SHOULD drop the message, but it MAY
693 try and extract what information it can out of the
694 message.
696 sadb_msg_reserved
697 Reserved value. It MUST be zeroed by the sender. All
698 fields labeled reserved later in the document have
699 the same semantics as this field.
701 sadb_msg_seq Contains the sequence number of this message. This
702 field, along with sadb_msg_pid, MUST be used to
703 uniquely identify requests to a process. The sender
704 is responsible for filling in this field. This
705 responsibility also includes matching the
706 sadb_msg_seq of a request (e.g. SADB_ACQUIRE).
708 This field is similar to a transaction ID in a
709 remote procedure call implementation.
711 sadb_msg_pid Identifies the process which originated this message,
712 or which process a message is bound for. For
713 example, if process id 2112 sends an SADB_UPDATE
714 message to the kernel, the process MUST set this
715 field to 2112 and the kernel will set this field
716 to 2112 in its reply to that SADB_UPDATE
717 message. This field, along with sadb_msg_seq, can
718 be used to uniquely identify requests to a
719 process.
721 It is currently assumed that a 32-bit quantity will
722 hold an operating system's process ID space.
730 McDonald, et. al. Informational [Page 13]
731 \f
732 RFC 2367 PF_KEY Key Management API July 1998
735 2.2 Alignment of Headers and Extension Headers
737 The base message header is a multiple of 64 bits and fields after it
738 in memory will be 64 bit aligned if the base itself is 64 bit
739 aligned. Some of the subsequent extension headers have 64 bit fields
740 in them, and as a consequence need to be 64 bit aligned in an
741 environment where 64 bit quantities need to be 64 bit aligned.
743 The basic unit of alignment and length in PF_KEY Version 2 is 64
744 bits. Therefore:
746 * All extension headers, inclusive of the sadb_ext overlay fields,
747 MUST be a multiple of 64 bits long.
749 * All variable length data MUST be padded appropriately such that
750 its length in a message is a multiple of 64 bits.
752 * All length fields are, unless otherwise specified, in units of
753 64 bits.
755 * Implementations may safely access quantities of between 8 and 64
756 bits directly within a message without risk of alignment faults.
758 All PF_KEYv2 structures are packed and already have all intended
759 padding. Implementations MUST NOT insert any extra fields, including
760 hidden padding, into any structure in this document. This forbids
761 implementations from "extending" or "enhancing" existing headers
762 without changing the extension header type. As a guard against such
763 insertion of silent padding, each structure in this document is
764 labeled with its size in bytes. The size of these structures in an
765 implementation MUST match the size listed.
767 2.3 Additional Message Fields
769 The additional data following the base header consists of various
770 length-type-values fields. The first 32-bits are of a constant form:
772 struct sadb_ext {
773 uint16_t sadb_ext_len;
774 uint16_t sadb_ext_type;
775 };
776 /* sizeof(struct sadb_ext) == 4 */
778 sadb_ext_len Length of the extension header in 64 bit words,
779 inclusive.
786 McDonald, et. al. Informational [Page 14]
787 \f
788 RFC 2367 PF_KEY Key Management API July 1998
791 sadb_ext_type The type of extension header that follows. Values for
792 this field are detailed later. The value zero is
793 reserved.
795 Types of extension headers include: Association, Lifetime(s),
796 Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and
797 Supported. There MUST be only one instance of a extension type in a
798 message. (e.g. Base, Key, Lifetime, Key is forbidden). An EINVAL
799 will be returned if there are duplicate extensions within a message.
800 Implementations MAY enforce ordering of extensions in the order
801 presented in the EXTENSION HEADER VALUES section.
803 If an unknown extension type is encountered, it MUST be ignored.
804 Applications using extension headers not specified in this document
805 MUST be prepared to work around other system components not
806 processing those headers. Likewise, if an application encounters an
807 unknown extension from the kernel, it must be prepared to work around
808 it. Also, a kernel that generates extra extension header types MUST
809 NOT _depend_ on applications also understanding extra extension
810 header types.
812 All extension definitions include these two fields (len and exttype)
813 because they are instances of a generic extension (not unlike
814 sockaddr_in and sockaddr_in6 are instances of a generic sockaddr).
815 The sadb_ext header MUST NOT ever be present in a message without at
816 least four bytes of extension header data following it, and,
817 therefore, there is no problem with it being only four bytes long.
819 All extensions documented in this section MUST be implemented by a
820 PF_KEY implementation.
822 2.3.1 Association Extension
824 The Association extension specifies data specific to a single
825 security association. The only times this extension is not present is
826 when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being
827 passed and on the SADB_ACQUIRE message.
829 struct sadb_sa {
830 uint16_t sadb_sa_len;
831 uint16_t sadb_sa_exttype;
832 uint32_t sadb_sa_spi;
833 uint8_t sadb_sa_replay;
834 uint8_t sadb_sa_state;
835 uint8_t sadb_sa_auth;
836 uint8_t sadb_sa_encrypt;
837 uint32_t sadb_sa_flags;
838 };
842 McDonald, et. al. Informational [Page 15]
843 \f
844 RFC 2367 PF_KEY Key Management API July 1998
847 /* sizeof(struct sadb_sa) == 16 */
849 sadb_sa_spi The Security Parameters Index value for the security
850 association. Although this is a 32-bit field, some
851 types of security associations might have an SPI or
852 key identifier that is less than 32-bits long. In
853 this case, the smaller value shall be stored in the
854 least significant bits of this field and the unneeded
855 bits shall be zero. This field MUST be in network
856 byte order.
858 sadb_sa_replay The size of the replay window, if not zero. If zero,
859 then no replay window is in use.
861 sadb_sa_state The state of the security association. The currently
862 defined states are described later in this document.
864 sadb_sa_auth The authentication algorithm to be used with this
865 security association. The valid authentication
866 algorithms are described later in this document. A
867 value of zero means that no authentication is used
868 for this security association.
870 sadb_sa_encrypt The encryption algorithm to be used with this
871 security association. The valid encryption algorithms
872 are described later in this document. A value of zero
873 means that no encryption is used for this security
874 association.
876 sadb_sa_flags A bitmap of options defined for the security
877 association. The currently defined flags are
878 described later in this document.
880 The kernel MUST check these values where appropriate. For example,
881 IPsec AH with no authentication algorithm is probably an error.
883 When used with some messages, the values in some fields in this
884 header should be ignored.
886 2.3.2 Lifetime Extension
888 The Lifetime extension specifies one or more lifetime variants for
889 this security association. If no Lifetime extension is present the
890 association has an infinite lifetime. An association SHOULD have a
891 lifetime of some sort associated with it. Lifetime variants come in
892 three varieties, HARD - indicating the hard-limit expiration, SOFT -
893 indicating the soft-limit expiration, and CURRENT - indicating the
894 current state of a given security association. The Lifetime
898 McDonald, et. al. Informational [Page 16]
899 \f
900 RFC 2367 PF_KEY Key Management API July 1998
903 extension looks like:
905 struct sadb_lifetime {
906 uint16_t sadb_lifetime_len;
907 uint16_t sadb_lifetime_exttype;
908 uint32_t sadb_lifetime_allocations;
909 uint64_t sadb_lifetime_bytes;
910 uint64_t sadb_lifetime_addtime;
911 uint64_t sadb_lifetime_usetime;
912 };
913 /* sizeof(struct sadb_lifetime) == 32 */
915 sadb_lifetime_allocations
916 For CURRENT, the number of different connections,
917 endpoints, or flows that the association has been
918 allocated towards. For HARD and SOFT, the number of
919 these the association may be allocated towards
920 before it expires. The concept of a connection,
921 flow, or endpoint is system specific.
923 sadb_lifetime_bytes
924 For CURRENT, how many bytes have been processed
925 using this security association. For HARD and SOFT,
926 the number of bytes that may be processed using
927 this security association before it expires.
929 sadb_lifetime_addtime
930 For CURRENT, the time, in seconds, when the
931 association was created. For HARD and SOFT, the
932 number of seconds after the creation of the
933 association until it expires.
935 For such time fields, it is assumed that 64-bits is
936 sufficiently large to hold the POSIX time_t value.
937 If this assumption is wrong, this field will have to
938 be revisited.
940 sadb_lifetime_usetime
941 For CURRENT, the time, in seconds, when association
942 was first used. For HARD and SOFT, the number of
943 seconds after the first use of the association until
944 it expires.
946 The semantics of lifetimes are inclusive-OR, first-to-expire. This
947 means that if values for bytes and time, or multiple times, are
948 passed in, the first of these values to be reached will cause a
949 lifetime expiration.
954 McDonald, et. al. Informational [Page 17]
955 \f
956 RFC 2367 PF_KEY Key Management API July 1998
959 2.3.3 Address Extension
961 The Address extension specifies one or more addresses that are
962 associated with a security association. Address extensions for both
963 source and destination MUST be present when an Association extension
964 is present. The format of an Address extension is:
966 struct sadb_address {
967 uint16_t sadb_address_len;
968 uint16_t sadb_address_exttype;
969 uint8_t sadb_address_proto;
970 uint8_t sadb_address_prefixlen;
971 uint16_t sadb_address_reserved;
972 };
973 /* sizeof(struct sadb_address) == 8 */
975 /* followed by some form of struct sockaddr */
977 The sockaddr structure SHOULD conform to the sockaddr structure of
978 the system implementing PF_KEY. If the system has an sa_len field, so
979 SHOULD the sockaddrs in the message. If the system has NO sa_len
980 field, the sockaddrs SHOULD NOT have an sa_len field. All non-address
981 information in the sockaddrs, such as sin_zero for AF_INET sockaddrs,
982 and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out. The
983 zeroing of ports (e.g. sin_port and sin6_port) MUST be done for all
984 messages except for originating SADB_ACQUIRE messages, which SHOULD
985 fill them in with ports from the relevant TCP or UDP session which
986 generates the ACQUIRE message. If the ports are non-zero, then the
987 sadb_address_proto field, normally zero, MUST be filled in with the
988 transport protocol's number. If the sadb_address_prefixlen is non-
989 zero, then the address has a prefix (often used in KM access control
990 decisions), with length specified in sadb_address_prefixlen. These
991 additional fields may be useful to KM applications.
993 The SRC and DST addresses for a security association MUST be in the
994 same protocol family and MUST always be present or absent together in
995 a message. The PROXY address MAY be in a different protocol family,
996 and for most security protocols, represents an actual originator of a
997 packet. (For example, the inner-packets's source address in a
998 tunnel.)
1000 The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY)
1001 address. The DST address can be any valid destination address
1002 (unicast, multicast, or even broadcast). The PROXY address SHOULD be
1003 a unicast address (there are experimental security protocols where
1004 PROXY semantics may be different than described above).
1010 McDonald, et. al. Informational [Page 18]
1011 \f
1012 RFC 2367 PF_KEY Key Management API July 1998
1015 2.3.4 Key Extension
1017 The Key extension specifies one or more keys that are associated with
1018 a security association. A Key extension will not always be present
1019 with messages, because of security risks. The format of a Key
1020 extension is:
1022 struct sadb_key {
1023 uint16_t sadb_key_len;
1024 uint16_t sadb_key_exttype;
1025 uint16_t sadb_key_bits;
1026 uint16_t sadb_key_reserved;
1027 };
1028 /* sizeof(struct sadb_key) == 8 */
1030 /* followed by the key data */
1032 sadb_key_bits The length of the valid key data, in bits. A value of
1033 zero in sadb_key_bits MUST cause an error.
1035 The key extension comes in two varieties. The AUTH version is used
1036 with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT
1037 version is used with encryption keys (e.g. IPsec ESP). PF_KEY deals
1038 only with fully formed cryptographic keys, not with "raw key
1039 material". For example, when ISAKMP/Oakley is in use, the key
1040 management daemon is always responsible for transforming the result
1041 of the Diffie-Hellman computation into distinct fully formed keys
1042 PRIOR to sending those keys into the kernel via PF_KEY. This rule is
1043 made because PF_KEY is designed to support multiple security
1044 protocols (not just IP Security) and also multiple key management
1045 schemes including manual keying, which does not have the concept of
1046 "raw key material". A clean, protocol-independent interface is
1047 important for portability to different operating systems as well as
1048 for portability to different security protocols.
1050 If an algorithm defines its key to include parity bits (e.g. DES)
1051 then the key used with PF_KEY MUST also include those parity bits.
1052 For example, this means that a single DES key is always a 64-bit
1053 quantity.
1055 When a particular security protocol only requires one authentication
1056 and/or one encryption key, the fully formed key is transmitted using
1057 the appropriate key extension. When a particular security protocol
1058 requires more than one key for the same function (e.g. Triple-DES
1059 using 2 or 3 keys, and asymmetric algorithms), then those two fully
1060 formed keys MUST be concatenated together in the order used for
1061 outbound packet processing. In the case of multiple keys, the
1062 algorithm MUST be able to determine the lengths of the individual
1066 McDonald, et. al. Informational [Page 19]
1067 \f
1068 RFC 2367 PF_KEY Key Management API July 1998
1071 keys based on the information provided. The total key length (when
1072 combined with knowledge of the algorithm in use) usually provides
1073 sufficient information to make this determination.
1075 Keys are always passed through the PF_KEY interface in the order that
1076 they are used for outbound packet processing. For inbound processing,
1077 the correct order that keys are used might be different from this
1078 canonical concatenation order used with the PF_KEY interface. It is
1079 the responsibility of the implementation to use the keys in the
1080 correct order for both inbound and outbound processing.
1082 For example, consider a pair of nodes communicating unicast using an
1083 ESP three-key Triple-DES Security Association. Both the outbound SA
1084 on the sender node, and the inbound SA on the receiver node will
1085 contain key-A, followed by key-B, followed by key-C in their
1086 respective ENCRYPT key extensions. The outbound SA will use key-A
1087 first, followed by key-B, then key-C when encrypting. The inbound SA
1088 will use key-C, followed by key-B, then key-A when decrypting.
1089 (NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.)
1090 The canonical ordering of key-A, key-B, key-C is used for 3DES, and
1091 should be documented. The order of "encryption" is the canonical
1092 order for this example. [Sch96]
1094 The key data bits are arranged most-significant to least significant.
1095 For example, a 22-bit key would take up three octets, with the least
1096 significant two bits not containing key material. Five additional
1097 octets would then be used for padding to the next 64-bit boundary.
1099 While not directly related to PF_KEY, there is a user interface issue
1100 regarding odd-digit hexadecimal representation of keys. Consider the
1101 example of the 16-bit number:
1103 0x123
1105 That will require two octets of storage. In the absence of other
1106 information, however, unclear whether the value shown is stored as:
1108 01 23 OR 12 30
1110 It is the opinion of the authors that the former (0x123 == 0x0123) is
1111 the better way to interpret this ambiguity. Extra information (for
1112 example, specifying 0x0123 or 0x1230, or specifying that this is only
1113 a twelve-bit number) would solve this problem.
1122 McDonald, et. al. Informational [Page 20]
1123 \f
1124 RFC 2367 PF_KEY Key Management API July 1998
1127 2.3.5 Identity Extension
1129 The Identity extension contains endpoint identities. This
1130 information is used by key management to select the identity
1131 certificate that is used in negotiations. This information may also
1132 be provided by a kernel to network security aware applications to
1133 identify the remote entity, possibly for access control purposes. If
1134 this extension is not present, key management MUST assume that the
1135 addresses in the Address extension are the only identities for this
1136 Security Association. The Identity extension looks like:
1138 struct sadb_ident {
1139 uint16_t sadb_ident_len;
1140 uint16_t sadb_ident_exttype;
1141 uint16_t sadb_ident_type;
1142 uint16_t sadb_ident_reserved;
1143 uint64_t sadb_ident_id;
1144 };
1145 /* sizeof(struct sadb_ident) == 16 */
1147 /* followed by the identity string, if present */
1149 sadb_ident_type The type of identity information that follows.
1150 Currently defined identity types are described later
1151 in this document.
1153 sadb_ident_id An identifier used to aid in the construction of an
1154 identity string if none is present. A POSIX user id
1155 value is one such identifier that will be used in this
1156 field. Use of this field is described later in this
1157 document.
1159 A C string containing a textual representation of the identity
1160 information optionally follows the sadb_ident extension. The format
1161 of this string is determined by the value in sadb_ident_type, and is
1162 described later in this document.
1164 2.3.6 Sensitivity Extension
1166 The Sensitivity extension contains security labeling information for
1167 a security association. If this extension is not present, no
1168 sensitivity-related data can be obtained from this security
1169 association. If this extension is present, then the need for
1170 explicit security labeling on the packet is obviated.
1172 struct sadb_sens {
1173 uint16_t sadb_sens_len;
1174 uint16_t sadb_sens_exttype;
1178 McDonald, et. al. Informational [Page 21]
1179 \f
1180 RFC 2367 PF_KEY Key Management API July 1998
1183 uint32_t sadb_sens_dpd;
1184 uint8_t sadb_sens_sens_level;
1185 uint8_t sadb_sens_sens_len;
1186 uint8_t sadb_sens_integ_level;
1187 uint8_t sadb_sens_integ_len;
1188 uint32_t sadb_sens_reserved;
1189 };
1190 /* sizeof(struct sadb_sens) == 16 */
1192 /* followed by:
1193 uint64_t sadb_sens_bitmap[sens_len];
1194 uint64_t sadb_integ_bitmap[integ_len]; */
1196 sadb_sens_dpd Describes the protection domain, which allows
1197 interpretation of the levels and compartment
1198 bitmaps.
1199 sadb_sens_sens_level
1200 The sensitivity level.
1201 sadb_sens_sens_len
1202 The length, in 64 bit words, of the sensitivity
1203 bitmap.
1204 sadb_sens_integ_level
1205 The integrity level.
1206 sadb_sens_integ_len
1207 The length, in 64 bit words, of the integrity
1208 bitmap.
1210 This sensitivity extension is designed to support the Bell-LaPadula
1211 [BL74] security model used in compartmented-mode or multi-level
1212 secure systems, the Clark-Wilson [CW87] commercial security model,
1213 and/or the Biba integrity model [Biba77]. These formal models can be
1214 used to implement a wide variety of security policies. The definition
1215 of a particular security policy is outside the scope of this
1216 document. Each of the bitmaps MUST be padded to a 64-bit boundary if
1217 they are not implicitly 64-bit aligned.
1219 2.3.7 Proposal Extension
1221 The Proposal extension contains a "proposed situation" of algorithm
1222 preferences. It looks like:
1224 struct sadb_prop {
1225 uint16_t sadb_prop_len;
1226 uint16_t sadb_prop_exttype;
1227 uint8_t sadb_prop_replay;
1228 uint8_t sadb_prop_reserved[3];
1229 };
1230 /* sizeof(struct sadb_prop) == 8 */
1234 McDonald, et. al. Informational [Page 22]
1235 \f
1236 RFC 2367 PF_KEY Key Management API July 1998
1239 /* followed by:
1240 struct sadb_comb sadb_combs[(sadb_prop_len *
1241 sizeof(uint64_t) - sizeof(struct sadb_prop)) /
1242 sizeof(struct sadb_comb)]; */
1244 Following the header is a list of proposed parameter combinations in
1245 preferential order. The values in these fields have the same
1246 definition as the fields those values will move into if the
1247 combination is chosen.
1249 NOTE: Some algorithms in some security protocols will have
1250 variable IV lengths per algorithm. Variable length IVs
1251 are not supported by PF_KEY v2. If they were, however,
1252 proposed IV lengths would go in the Proposal Extension.
1254 These combinations look like:
1256 struct sadb_comb {
1257 uint8_t sadb_comb_auth;
1258 uint8_t sadb_comb_encrypt;
1259 uint16_t sadb_comb_flags;
1260 uint16_t sadb_comb_auth_minbits;
1261 uint16_t sadb_comb_auth_maxbits;
1262 uint16_t sadb_comb_encrypt_minbits;
1263 uint16_t sadb_comb_encrypt_maxbits;
1264 uint32_t sadb_comb_reserved;
1265 uint32_t sadb_comb_soft_allocations;
1266 uint32_t sadb_comb_hard_allocations;
1267 uint64_t sadb_comb_soft_bytes;
1268 uint64_t sadb_comb_hard_bytes;
1269 uint64_t sadb_comb_soft_addtime;
1270 uint64_t sadb_comb_hard_addtime;
1271 uint64_t sadb_comb_soft_usetime;
1272 uint64_t sadb_comb_hard_usetime;
1273 };
1275 /* sizeof(struct sadb_comb) == 72 */
1277 sadb_comb_auth If this combination is accepted, this will be the
1278 value of sadb_sa_auth.
1280 sadb_comb_encrypt
1281 If this combination is accepted, this will be the
1282 value of sadb_sa_encrypt.
1290 McDonald, et. al. Informational [Page 23]
1291 \f
1292 RFC 2367 PF_KEY Key Management API July 1998
1295 sadb_comb_auth_minbits;
1296 sadb_comb_auth_maxbits;
1297 The minimum and maximum acceptable authentication
1298 key lengths, respectably, in bits. If sadb_comb_auth
1299 is zero, both of these values MUST be zero. If
1300 sadb_comb_auth is nonzero, both of these values MUST
1301 be nonzero. If this combination is accepted, a value
1302 between these (inclusive) will be stored in the
1303 sadb_key_bits field of KEY_AUTH. The minimum MUST
1304 NOT be greater than the maximum.
1306 sadb_comb_encrypt_minbits;
1307 sadb_comb_encrypt_maxbits;
1308 The minimum and maximum acceptable encryption key
1309 lengths, respectably, in bits. If sadb_comb_encrypt
1310 is zero, both of these values MUST be zero. If
1311 sadb_comb_encrypt is nonzero, both of these values
1312 MUST be nonzero. If this combination is accepted, a
1313 value between these (inclusive) will be stored in
1314 the sadb_key_bits field of KEY_ENCRYPT. The minimum
1315 MUST NOT be greater than the maximum.
1317 sadb_comb_soft_allocations
1318 sadb_comb_hard_allocations
1319 If this combination is accepted, these are proposed
1320 values of sadb_lifetime_allocations in the SOFT and
1321 HARD lifetimes, respectively.
1323 sadb_comb_soft_bytes
1324 sadb_comb_hard_bytes
1325 If this combination is accepted, these are proposed
1326 values of sadb_lifetime_bytes in the SOFT and HARD
1327 lifetimes, respectively.
1329 sadb_comb_soft_addtime
1330 sadb_comb_hard_addtime
1331 If this combination is accepted, these are proposed
1332 values of sadb_lifetime_addtime in the SOFT and HARD
1333 lifetimes, respectively.
1335 sadb_comb_soft_usetime
1336 sadb_comb_hard_usetime
1337 If this combination is accepted, these are proposed
1338 values of sadb_lifetime_usetime in the SOFT and HARD
1339 lifetimes, respectively.
1346 McDonald, et. al. Informational [Page 24]
1347 \f
1348 RFC 2367 PF_KEY Key Management API July 1998
1351 Each combination has an authentication and encryption algorithm,
1352 which may be 0, indicating none. A combination's flags are the same
1353 as the flags in the Association extension. The minimum and maximum
1354 key lengths (which are in bits) are derived from possible a priori
1355 policy decisions, along with basic properties of the algorithm.
1356 Lifetime attributes are also included in a combination, as some
1357 algorithms may know something about their lifetimes and can suggest
1358 lifetime limits.
1360 2.3.8 Supported Algorithms Extension
1362 The Supported Algorithms extension contains a list of all algorithms
1363 supported by the system. This tells key management what algorithms it
1364 can negotiate. Available authentication algorithms are listed in the
1365 SUPPORTED_AUTH extension and available encryption algorithms are
1366 listed in the SUPPORTED_ENCRYPT extension. The format of these
1367 extensions is:
1369 struct sadb_supported {
1370 uint16_t sadb_supported_len;
1371 uint16_t sadb_supported_exttype;
1372 uint32_t sadb_supported_reserved;
1373 };
1374 /* sizeof(struct sadb_supported) == 8 */
1376 /* followed by:
1377 struct sadb_alg sadb_algs[(sadb_supported_len *
1378 sizeof(uint64_t) - sizeof(struct sadb_supported)) /
1379 sizeof(struct sadb_alg)]; */
1381 This header is followed by one or more algorithm descriptions. An
1382 algorithm description looks like:
1384 struct sadb_alg {
1385 uint8_t sadb_alg_id;
1386 uint8_t sadb_alg_ivlen;
1387 uint16_t sadb_alg_minbits;
1388 uint16_t sadb_alg_maxbits;
1389 uint16_t sadb_alg_reserved;
1390 };
1391 /* sizeof(struct sadb_alg) == 8 */
1393 sadb_alg_id The algorithm identification value for this
1394 algorithm. This is the value that is stored in
1395 sadb_sa_auth or sadb_sa_encrypt if this algorithm is
1396 selected.
1402 McDonald, et. al. Informational [Page 25]
1403 \f
1404 RFC 2367 PF_KEY Key Management API July 1998
1407 sadb_alg_ivlen The length of the initialization vector to be used
1408 for the algorithm. If an IV is not needed, this
1409 value MUST be set to zero.
1411 sadb_alg_minbits
1412 The minimum acceptable key length, in bits. A value
1413 of zero is invalid.
1415 sadb_alg_maxbits
1416 The maximum acceptable key length, in bits. A value
1417 of zero is invalid. The minimum MUST NOT be greater
1418 than the maximum.
1420 2.3.9 SPI Range Extension
1422 One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI
1423 values. This extension performs such a function.
1425 struct sadb_spirange {
1426 uint16_t sadb_spirange_len;
1427 uint16_t sadb_spirange_exttype;
1428 uint32_t sadb_spirange_min;
1429 uint32_t sadb_spirange_max;
1430 uint32_t sadb_spirange_reserved;
1431 };
1432 /* sizeof(struct sadb_spirange) == 16 */
1434 sadb_spirange_min
1435 The minimum acceptable SPI value.
1437 sadb_spirange_max
1438 The maximum acceptable SPI value. The maximum MUST
1439 be greater than or equal to the minimum.
1458 McDonald, et. al. Informational [Page 26]
1459 \f
1460 RFC 2367 PF_KEY Key Management API July 1998
1463 2.4 Illustration of Message Layout
1465 The following shows how the octets are laid out in a PF_KEY message.
1466 Optional fields are indicated as such.
1468 The base header is as follows:
1470 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
1471 +---------------+---------------+---------------+---------------+
1472 | ...version | sadb_msg_type | sadb_msg_errno| ...msg_satype |
1473 +---------------+---------------+---------------+---------------+
1474 | sadb_msg_len | sadb_msg_reserved |
1475 +---------------+---------------+---------------+---------------+
1476 | sadb_msg_seq |
1477 +---------------+---------------+---------------+---------------+
1478 | sadb_msg_pid |
1479 +---------------+---------------+---------------+---------------+
1481 The base header may be followed by one or more of the following
1482 extension fields, depending on the values of various base header
1483 fields. The following fields are ordered such that if they appear,
1484 they SHOULD appear in the order presented below.
1486 An extension field MUST not be repeated. If there is a situation
1487 where an extension MUST be repeated, it should be brought to the
1488 attention of the authors.
1490 The Association extension
1492 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
1493 +---------------+---------------+---------------+---------------+
1494 | sadb_sa_len | sadb_sa_exttype |
1495 +---------------+---------------+---------------+---------------+
1496 | sadb_sa_spi |
1497 +---------------+---------------+---------------+---------------+
1498 | ...replay | sadb_sa_state | sadb_sa_auth |sadb_sa_encrypt|
1499 +---------------+---------------+---------------+---------------+
1500 | sadb_sa_flags |
1501 +---------------+---------------+---------------+---------------+
1503 The Lifetime extension
1505 +---------------+---------------+---------------+---------------+
1506 | sadb_lifetime_len | sadb_lifetime_exttype |
1507 +---------------+---------------+---------------+---------------+
1508 | sadb_lifetime_allocations |
1509 +---------------+---------------+---------------+---------------+
1514 McDonald, et. al. Informational [Page 27]
1515 \f
1516 RFC 2367 PF_KEY Key Management API July 1998
1519 +---------------+---------------+---------------+---------------+
1520 | sadb_lifetime_bytes |
1521 | (64 bits) |
1522 +---------------+---------------+---------------+---------------+
1523 | sadb_lifetime_addtime |
1524 | (64 bits) |
1525 +---------------+---------------+---------------+---------------+
1526 | sadb_lifetime_usetime |
1527 | (64 bits) |
1528 +---------------+---------------+---------------+---------------+
1530 The Address extension
1532 +---------------+---------------+---------------+---------------+
1533 | sadb_address_len | sadb_address_exttype |
1534 +---------------+---------------+---------------+---------------+
1535 | _address_proto| ..._prefixlen | sadb_address_reserved |
1536 +---------------+---------------+---------------+---------------+
1537 > Some form of 64-bit aligned struct sockaddr goes here. <
1538 +---------------+---------------+---------------+---------------+
1540 The Key extension
1542 +---------------+---------------+---------------+---------------+
1543 | sadb_key_len | sadb_key_exttype |
1544 +---------------+---------------+---------------+---------------+
1545 | sadb_key_bits | sadb_key_reserved |
1546 +---------------+---------------+---------------+---------------+
1547 > A key, padded to 64-bits, most significant bits to least. >
1548 +---------------+---------------+---------------+---------------+
1550 The Identity extension
1552 +---------------+---------------+---------------+---------------+
1553 | sadb_ident_len | sadb_ident_exttype |
1554 +---------------+---------------+---------------+---------------+
1555 | sadb_ident_type | sadb_ident_reserved |
1556 +---------------+---------------+---------------+---------------+
1557 | sadb_ident_id |
1558 | (64 bits) |
1559 +---------------+---------------+---------------+---------------+
1560 > A null-terminated C-string which MUST be padded out for >
1561 < 64-bit alignment. <
1562 +---------------+---------------+---------------+---------------+
1570 McDonald, et. al. Informational [Page 28]
1571 \f
1572 RFC 2367 PF_KEY Key Management API July 1998
1575 The Sensitivity extension
1577 +---------------+---------------+---------------+---------------+
1578 | sadb_sens_len | sadb_sens_exttype |
1579 +---------------+---------------+---------------+---------------+
1580 | sadb_sens_dpd |
1581 +---------------+---------------+---------------+---------------+
1582 | ...sens_level | ...sens_len |..._integ_level| ..integ_len |
1583 +---------------+---------------+---------------+---------------+
1584 | sadb_sens_reserved |
1585 +---------------+---------------+---------------+---------------+
1586 > The sensitivity bitmap, followed immediately by the <
1587 < integrity bitmap, each is an array of uint64_t. >
1588 +---------------+---------------+---------------+---------------+
1590 The Proposal extension
1592 +---------------+---------------+---------------+---------------+
1593 | sadb_prop_len | sadb_prop_exttype |
1594 +---------------+---------------+---------------+---------------+
1595 |...prop_replay | sadb_prop_reserved |
1596 +---------------+---------------+---------------+---------------+
1597 > One or more combinations, specified as follows... <
1598 +---------------+---------------+---------------+---------------+
1600 Combination
1601 +---------------+---------------+---------------+---------------+
1602 |sadb_comb_auth |sadb_comb_encr | sadb_comb_flags |
1603 +---------------+---------------+---------------+---------------+
1604 | sadb_comb_auth_minbits | sadb_comb_auth_maxbits |
1605 +---------------+---------------+---------------+---------------+
1606 | sadb_comb_encrypt_minbits | sadb_comb_encrypt_maxbits |
1607 +---------------+---------------+---------------+---------------+
1608 | sadb_comb_reserved |
1609 +---------------+---------------+---------------+---------------+
1610 | sadb_comb_soft_allocations |
1611 +---------------+---------------+---------------+---------------+
1612 | sadb_comb_hard_allocations |
1613 +---------------+---------------+---------------+---------------+
1614 | sadb_comb_soft_bytes |
1615 | (64 bits) |
1616 +---------------+---------------+---------------+---------------+
1617 | sadb_comb_hard_bytes |
1618 | (64 bits) |
1619 +---------------+---------------+---------------+---------------+
1620 | sadb_comb_soft_addtime |
1621 | (64 bits) |
1622 +---------------+---------------+---------------+---------------+
1626 McDonald, et. al. Informational [Page 29]
1627 \f
1628 RFC 2367 PF_KEY Key Management API July 1998
1631 +---------------+---------------+---------------+---------------+
1632 | sadb_comb_hard_addtime |
1633 | (64 bits) |
1634 +---------------+---------------+---------------+---------------+
1635 | sadb_comb_soft_usetime |
1636 | (64 bits) |
1637 +---------------+---------------+---------------+---------------+
1638 | sadb_comb_hard_usetime |
1639 | (64 bits) |
1640 +---------------+---------------+---------------+---------------+
1642 The Supported Algorithms extension
1644 +---------------+---------------+---------------+---------------+
1645 | sadb_supported_len | sadb_supported_exttype |
1646 +---------------+---------------+---------------+---------------+
1647 | sadb_supported_reserved |
1648 +---------------+---------------+---------------+---------------+
1650 Followed by one or more Algorithm Descriptors
1652 +---------------+---------------+---------------+---------------+
1653 | sadb_alg_id | sadb_alg_ivlen| sadb_alg_minbits |
1654 +---------------+---------------+---------------+---------------+
1655 | sadb_alg_maxbits | sadb_alg_reserved |
1656 +---------------+---------------+---------------+---------------+
1658 The SPI Range extension
1660 +---------------+---------------+---------------+---------------+
1661 | sadb_spirange_len | sadb_spirange_exttype |
1662 +---------------+---------------+---------------+---------------+
1663 | sadb_spirange_min |
1664 +---------------+---------------+---------------+---------------+
1665 | sadb_spirange_max |
1666 +---------------+---------------+---------------+---------------+
1667 | sadb_spirange_reserved |
1668 +---------------+---------------+---------------+---------------+
1670 3 Symbolic Names
1672 This section defines various symbols used with PF_KEY and the
1673 semantics associated with each symbol. Applications MUST use the
1674 symbolic names in order to be portable. The numeric definitions
1675 shown are for illustrative purposes, unless explicitly stated
1676 otherwise. The numeric definition MAY vary on other systems. The
1677 symbolic name MUST be kept the same for all conforming
1678 implementations.
1682 McDonald, et. al. Informational [Page 30]
1683 \f
1684 RFC 2367 PF_KEY Key Management API July 1998
1687 3.1 Message Types
1689 The following message types are used with PF_KEY. These are defined
1690 in the file <net/pfkeyv2.h>.
1692 #define SADB_RESERVED 0
1693 #define SADB_GETSPI 1
1694 #define SADB_UPDATE 2
1695 #define SADB_ADD 3
1696 #define SADB_DELETE 4
1697 #define SADB_GET 5
1698 #define SADB_ACQUIRE 6
1699 #define SADB_REGISTER 7
1700 #define SADB_EXPIRE 8
1701 #define SADB_FLUSH 9
1703 #define SADB_DUMP 10 /* not used normally */
1705 #define SADB_MAX 10
1707 Each message has a behavior. A behavior is defined as where the
1708 initial message travels (e.g. user to kernel), and what subsequent
1709 actions are expected to take place. Contents of messages are
1710 illustrated as:
1712 <base, REQUIRED EXTENSION, REQ., (OPTIONAL EXT.,) (OPT)>
1714 The SA extension is sometimes used only for its SPI field. If all
1715 other fields MUST be ignored, this is represented by "SA(*)".
1717 The lifetime extensions are represented with one to three letters
1718 after the word "lifetime," representing (H)ARD, (S)OFT, and
1719 (C)URRENT.
1721 The address extensions are represented with one to three letters
1722 after the word "address," representing (S)RC, (D)ST, (P)ROXY.
1724 NOTE: Some security association types do not use a source
1725 address for SA identification, where others do. This may
1726 cause EEXIST errors for some SA types where others do not
1727 report collisions. It is expected that application
1728 authors know enough about the underlying security
1729 association types to understand these differences.
1731 The key extensions are represented with one or two letters after the
1732 word "key," representing (A)UTH and (E)NCRYPT.
1738 McDonald, et. al. Informational [Page 31]
1739 \f
1740 RFC 2367 PF_KEY Key Management API July 1998
1743 The identity extensions are represented with one or two letters after
1744 the word "identity," representing (S)RC and (D)ST.
1746 In the case of an error, only the base header is returned.
1748 Note that any standard error could be returned for any message.
1750 Typically, they will be either one of the errors specifically listed
1751 in the description for a message or one of the following:
1753 EINVAL Various message improprieties, including SPI ranges
1754 that are malformed.
1755 ENOMEM Needed memory was not available.
1756 ENOBUFS Needed memory was not available.
1757 EMSGSIZ The message exceeds the maximum length allowed.
1759 3.1.1 SADB_GETSPI
1761 The SADB_GETSPI message allows a process to obtain a unique SPI value
1762 for given security association type, source address, and destination
1763 address. This message followed by an SADB_UPDATE is one way to
1764 create a security association (SADB_ADD is the other method). The
1765 process specifies the type in the base header, the source and
1766 destination address in address extension. If the SADB_GETSPI message
1767 is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq
1768 MUST be the same as the SADB_ACQUIRE message. The application may
1769 also specify the SPI. This is done by having the kernel select
1770 within a range of SPI values by using the SPI range extension. To
1771 specify a single SPI value to be verified, the application sets the
1772 high and low values to be equal. Permitting range specification is
1773 important because the kernel can allocate an SPI value based on what
1774 it knows about SPI values already in use. The kernel returns the
1775 same message with the allocated SPI value stored in the spi field of
1776 an association extension. The allocate SPI (and destination address)
1777 refer to a LARVAL security association. An SADB_UPDATE message can
1778 later be used to add an entry with the requested SPI value.
1780 It is recommended that associations that are created with SADB_GETSPI
1781 SHOULD be automatically deleted within a fixed amount of time if they
1782 are not updated by an SADB_UPDATE message. This allows SA storage
1783 not to get cluttered with larval associations.
1785 The message behavior of the SADB_GETSPI message is:
1787 Send an SADB_GETSPI message from a user process to the kernel.
1789 <base, address, SPI range>
1794 McDonald, et. al. Informational [Page 32]
1795 \f
1796 RFC 2367 PF_KEY Key Management API July 1998
1799 The kernel returns the SADB_GETSPI message to all listening
1800 processes.
1802 <base, SA(*), address(SD)>
1804 Errors:
1806 EEXIST Requested SPI or SPI range is not available or already
1807 used.
1809 3.1.2 SADB_UPDATE Message
1811 The SADB_UPDATE message allows a process to update the information in
1812 an existing Security Association. Since SADB_GETSPI does not allow
1813 setting of certain parameters, this message is needed to fully form
1814 the SADB_SASTATE_LARVAL security association created with
1815 SADB_GETSPI. The format of the update message is a base header,
1816 followed by an association header and possibly by several extension
1817 headers. The kernel searches for the security association with the
1818 same type, spi, source address and destination address specified in
1819 the message and updates the Security Association information using
1820 the content of the SADB_UPDATE message.
1822 The kernel MAY disallow SADB_UPDATE to succeed unless the message is
1823 issued from the same socket that created the security association.
1824 Such enforcement significantly reduces the chance of accidental
1825 changes to an in-use security association. Malicious trusted parties
1826 could still issue an SADB_FLUSH or SADB_DELETE message, but deletion
1827 of associations is more easily detected and less likely to occur
1828 accidentally than an erroneous SADB_UPDATE. The counter argument to
1829 supporting this behavior involves the case where a user-space key
1830 management application fails and is restarted. The new instance of
1831 the application will not have the same socket as the creator of the
1832 security association.
1834 The kernel MUST sanity check all significant values submitted in an
1835 SADB_UPDATE message before changing the SA in its database and MUST
1836 return EINVAL if any of the values are invalid. Examples of checks
1837 that should be performed are DES key parity bits, key length
1838 checking, checks for keys known to be weak for the specified
1839 algorithm, and checks for flags or parameters known to be
1840 incompatible with the specified algorithm.
1842 Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_UPDATE
1843 message. If the original SA is an SADB_SASTATE_LARVAL SA, then any
1844 value in the SA may be changed except for the source address,
1845 destination address, and SPI. If the original SA is an
1846 SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA
1850 McDonald, et. al. Informational [Page 33]
1851 \f
1852 RFC 2367 PF_KEY Key Management API July 1998
1855 MUST return EINVAL. It is not valid for established keying or
1856 algorithm information to change without the SPI changing, which would
1857 require creation of a new SA rather than a change to an existing SA.
1858 Once keying and algorithm information is negotiated, address and
1859 identity information is fixed for the SA. Therefore, if the original
1860 SA is an SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state
1861 field in the SA header and lifetimes (hard, soft, and current) may be
1862 changed and any attempt to change other values MUST result in an
1863 error return of EINVAL.
1865 The message behavior of the SADB_UPDATE message is:
1867 Send an SADB_UPDATE message from a user process to the kernel.
1869 <base, SA, (lifetime(HSC),) address(SD), (address(P),)
1870 key(AE), (identity(SD),) (sensitivity)>
1872 The kernel returns the SADB_UPDATE message to all listening
1873 processes.
1875 <base, SA, (lifetime(HSC),) address(SD), (address(P),)
1876 (identity(SD),) (sensitivity)>
1879 The keying material is not returned on the message from the kernel to
1880 listening sockets because listeners might not have the privileges to
1881 see such keying material.
1883 Errors:
1884 ESRCH The security association to be updated was not found.
1885 EINVAL In addition to other possible causes, this error is
1886 returned if sanity checking on the SA values (such
1887 as the keys) fails.
1888 EACCES Insufficient privilege to update entry. The socket
1889 issuing the SADB_UPDATE is not creator of the entry
1890 to be updated.
1892 3.1.3 SADB_ADD
1894 The SADB_ADD message is nearly identical to the SADB_UPDATE message,
1895 except that it does not require a previous call to SADB_GETSPI. The
1896 SADB_ADD message is used in manual keying applications, and in other
1897 cases where the uniqueness of the SPI is known immediately.
1899 An SADB_ADD message is also used when negotiation is finished, and
1900 the second of a pair of associations is added. The SPI for this
1901 association was determined by the peer machine. The sadb_msg_seq
1906 McDonald, et. al. Informational [Page 34]
1907 \f
1908 RFC 2367 PF_KEY Key Management API July 1998
1911 MUST be set to the value set in a kernel-generated SADB_ACQUIRE so
1912 that both associations in a pair are bound to the same ACQUIRE
1913 request.
1915 The kernel MUST sanity check all used fields in the SA submitted in
1916 an SADB_ADD message before adding the SA to its database and MUST
1917 return EINVAL if any of the values are invalid.
1919 Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_ADD message.
1920 SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is not
1921 sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state.
1922 Therefore, the sadb_sa_state field of all submitted SAs MUST be
1923 SADB_SASTATE_MATURE and the kernel MUST return an error if this is
1924 not true.
1926 The message behavior of the SADB_ADD message is:
1928 Send an SADB_ADD message from a user process to the kernel.
1930 <base, SA, (lifetime(HS),) address(SD), (address(P),)
1931 key(AE), (identity(SD),) (sensitivity)>
1933 The kernel returns the SADB_ADD message to all listening
1934 processes.
1936 <base, SA, (lifetime(HS),) address(SD), (identity(SD),)
1937 (sensitivity)>
1939 The keying material is not returned on the message from the kernel to
1940 listening sockets because listeners may not have the privileges to
1941 see such keying material.
1943 Errors:
1945 EEXIST The security association that was to be added already
1946 exists.
1947 EINVAL In addition to other possible causes, this error is
1948 returned if sanity checking on the SA values (such
1949 as the keys) fails.
1951 3.1.4 SADB_DELETE
1953 The SADB_DELETE message causes the kernel to delete a Security
1954 Association from the key table. The delete message consists of the
1955 base header followed by the association, and the source and
1956 destination sockaddrs in the address extension. The kernel deletes
1957 the security association matching the type, spi, source address, and
1958 destination address in the message.
1962 McDonald, et. al. Informational [Page 35]
1963 \f
1964 RFC 2367 PF_KEY Key Management API July 1998
1967 The message behavior for SADB_DELETE is as follows:
1969 Send an SADB_DELETE message from a user process to the kernel.
1971 <base, SA(*), address(SD)>
1973 The kernel returns the SADB_DELETE message to all listening
1974 processes.
1976 <base, SA(*), address(SD)>
1978 3.1.5 SADB_GET
1980 The SADB_GET message allows a process to retrieve a copy of a
1981 Security Association from the kernel's key table. The get message
1982 consists of the base header follows by the relevant extension fields.
1983 The Security Association matching the type, spi, source address, and
1984 destination address is returned.
1986 The message behavior of the SADB_GET message is:
1988 Send an SADB_GET message from a user process to the kernel.
1990 <base, SA(*), address(SD)>
1992 The kernel returns the SADB_GET message to the socket that sent
1993 the SADB_GET message.
1995 <base, SA, (lifetime(HSC),) address(SD), (address(P),) key(AE),
1996 (identity(SD),) (sensitivity)>
1998 Errors:
1999 ESRCH The sought security association was not found.
2001 3.1.6 SADB_ACQUIRE
2003 The SADB_ACQUIRE message is typically sent only by the kernel to key
2004 socket listeners who have registered their key socket (see
2005 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by
2006 application-level consumers of security associations (such as an
2007 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE
2008 message is a base header along with an address extension, possibly an
2009 identity extension, and a proposal extension. The proposed situation
2010 contains a list of desirable algorithms that can be used if the
2011 algorithms in the base header are not available. The values for the
2012 fields in the base header and in the security association data which
2013 follows the base header indicate the properties of the Security
2014 Association that the listening process should attempt to acquire. If
2018 McDonald, et. al. Informational [Page 36]
2019 \f
2020 RFC 2367 PF_KEY Key Management API July 1998
2023 the message originates from the kernel (i.e. the sadb_msg_pid is 0),
2024 the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and
2025 SADB_UPDATE, or subsequent SADB_ADD message to bind a security
2026 association to the request. This avoids the race condition of two
2027 TCP connections between two IP hosts that each require unique
2028 associations, and having one steal another's security association.
2029 The sadb_msg_errno and sadb_msg_state fields should be ignored by the
2030 listening process.
2032 The SADB_ACQUIRE message is typically triggered by an outbound packet
2033 that needs security but for which there is no applicable Security
2034 Association existing in the key table. If the packet can be
2035 sufficiently protected by more than one algorithm or combination of
2036 options, the SADB_ACQUIRE message MUST order the preference of
2037 possibilities in the Proposal extension.
2039 There are three messaging behaviors for SADB_ACQUIRE. The first is
2040 where the kernel needs a security association (e.g. for IPsec).
2042 The kernel sends an SADB_ACQUIRE message to registered sockets.
2044 <base, address(SD), (address(P)), (identity(SD),) (sensitivity,)
2045 proposal>
2047 NOTE: The address(SD) extensions MUST have the port fields
2048 filled in with the port numbers of the session requiring
2049 keys if appropriate.
2051 The second is when, for some reason, key management fails, it can
2052 send an ACQUIRE message with the same sadb_msg_seq as the initial
2053 ACQUIRE with a non-zero errno.
2055 Send an SADB_ACQUIRE to indicate key management failure.
2057 <base>
2059 The third is where an application-layer consumer of security
2060 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security
2061 association.
2063 Send an SADB_ACQUIRE message from a user process to the kernel.
2065 <base, address(SD), (address(P),) (identity(SD),) (sensitivity,)
2066 proposal>
2068 The kernel returns an SADB_ACQUIRE message to registered
2069 sockets.
2074 McDonald, et. al. Informational [Page 37]
2075 \f
2076 RFC 2367 PF_KEY Key Management API July 1998
2079 <base, address(SD), (address(P),) (identity(SD),) (sensitivity,)
2080 proposal>
2082 The user-level consumer waits for an SADB_UPDATE or SADB_ADD
2083 message for its particular type, and then can use that
2084 association by using SADB_GET messages.
2086 Errors:
2087 EINVAL Invalid acquire request.
2088 EPROTONOSUPPORT No KM application has registered with the Key
2089 Engine as being able to obtain the requested SA type, so
2090 the requested SA cannot be acquired.
2092 3.1.7 SADB_REGISTER
2094 The SADB_REGISTER message allows an application to register its key
2095 socket as able to acquire new security associations for the kernel.
2096 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for
2097 the type of security association specified in sadb_msg_satype. The
2098 application specifies the type of security association that it can
2099 acquire for the kernel in the type field of its register message. If
2100 an application can acquire multiple types of security association, it
2101 MUST register each type in a separate message. Only the base header
2102 is needed for the register message. Key management applications MAY
2103 register for a type not known to the kernel, because the consumer may
2104 be in user-space (e.g. OSPFv2 security).
2106 The reply of the SADB_REGISTER message contains a supported algorithm
2107 extension. That field contains an array of supported algorithms, one
2108 per octet. This allows key management applications to know what
2109 algorithm are supported by the kernel.
2111 In an environment where algorithms can be dynamically loaded and
2112 unloaded, an asynchronous SADB_REGISTER reply MAY be generated. The
2113 list of supported algorithms MUST be a complete list, so the
2114 application can make note of omissions or additions.
2116 The messaging behavior of the SADB_REGISTER message is:
2118 Send an SADB_REGISTER message from a user process to the kernel.
2120 <base>
2122 The kernel returns an SADB_REGISTER message to registered
2123 sockets, with algorithm types supported by the kernel being
2124 indicated in the supported algorithms field.
2130 McDonald, et. al. Informational [Page 38]
2131 \f
2132 RFC 2367 PF_KEY Key Management API July 1998
2135 NOTE: This message may arrive asynchronously due to an
2136 algorithm being loaded or unloaded into a dynamically
2137 linked kernel.
2139 <base, supported>
2141 3.1.8 SADB_EXPIRE Message
2143 The operating system kernel is responsible for tracking SA
2144 expirations for security protocols that are implemented inside the
2145 kernel. If the soft limit or hard limit of a Security Association
2146 has expired for a security protocol implemented inside the kernel,
2147 then the kernel MUST issue an SADB_EXPIRE message to all key socket
2148 listeners. If the soft limit or hard limit of a Security Association
2149 for a user-level security protocol has expired, the user-level
2150 protocol SHOULD issue an SADB_EXPIRE message.
2152 The base header will contain the security association information
2153 followed by the source sockaddr, destination sockaddr, (and, if
2154 present, internal sockaddr,) (and, if present, one or both
2155 compartment bitmaps).
2157 The lifetime extension of an SADB_EXPIRE message is important to
2158 indicate which lifetime expired. If a HARD lifetime extension is
2159 included, it indicates that the HARD lifetime expired. This means
2160 the association MAY be deleted already from the SADB. If a SOFT
2161 lifetime extension is included, it indicates that the SOFT lifetime
2162 expired. The CURRENT lifetime extension will indicate the current
2163 status, and comparisons to the HARD or SOFT lifetime will indicate
2164 which limit was reached. HARD lifetimes MUST take precedence over
2165 SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same,
2166 the HARD lifetime will appear on the EXPIRE message. The
2167 pathological case of HARD lifetimes being shorter than SOFT lifetimes
2168 is handled such that the SOFT lifetime will never expire.
2170 The messaging behavior of the SADB_EXPIRE message is:
2172 The kernel sends an SADB_EXPIRE message to all listeners when
2173 the soft limit of a security association has been expired.
2175 <base, SA, lifetime(C and one of HS), address(SD)>
2177 Note that the SADB_EXPIRE message is ONLY sent by the kernel to the
2178 KMd. It is a one-way informational message that does not have a
2179 reply.
2186 McDonald, et. al. Informational [Page 39]
2187 \f
2188 RFC 2367 PF_KEY Key Management API July 1998
2191 3.1.9 SADB_FLUSH
2193 The SADB_FLUSH message causes the kernel to delete all entries in its
2194 key table for a certain sadb_msg_satype. Only the base header is
2195 required for a flush message. If sadb_msg_satype is filled in with a
2196 specific value, only associations of that type are deleted. If it is
2197 filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted.
2199 The messaging behavior for SADB_FLUSH is:
2201 Send an SADB_FLUSH message from a user process to the kernel.
2203 <base>
2205 The kernel will return an SADB_FLUSH message to all listening
2206 sockets.
2208 <base>
2210 The reply message happens only after the actual flushing
2211 of security associations has been attempted.
2213 3.1.10 SADB_DUMP
2215 The SADB_DUMP message causes the kernel to dump the operating
2216 system's entire Key Table to the requesting key socket. As in
2217 SADB_FLUSH, if a sadb_msg_satype value is in the message, only
2218 associations of that type will be dumped. If SADB_SATYPE_UNSPEC is
2219 specified, all associations will be dumped. Each Security Association
2220 is returned in its own SADB_DUMP message. A SADB_DUMP message with a
2221 sadb_seq field of zero indicates the end of the dump transaction. The
2222 dump message is used for debugging purposes only and is not intended
2223 for production use.
2225 Support for the dump message MAY be discontinued in future versions
2226 of PF_KEY. Key management applications MUST NOT depend on this
2227 message for basic operation.
2229 The messaging behavior for SADB_DUMP is:
2231 Send an SADB_DUMP message from a user process to the kernel.
2233 <base>
2235 Several SADB_DUMP messages will return from the kernel to the
2236 sending socket.
2242 McDonald, et. al. Informational [Page 40]
2243 \f
2244 RFC 2367 PF_KEY Key Management API July 1998
2247 <base, SA, (lifetime (HSC),) address(SD), (address(P),)
2248 key(AE), (identity(SD),) (sensitivity)>
2250 3.2 Security Association Flags
2252 The Security Association's flags are a bitmask field. These flags
2253 also appear in a combination that is part of a PROPOSAL extension.
2254 The related symbolic definitions below should be used in order that
2255 applications will be portable:
2257 #define SADB_SAFLAGS_PFS 1 /* perfect forward secrecy */
2259 The SADB_SAFLAGS_PFS flag indicates to key management that this
2260 association should have perfect forward secrecy in its key. (In
2261 other words, any given session key cannot be determined by
2262 cryptanalysis of previous session keys or some master key.)
2264 3.3 Security Association States
2266 The security association state field is an integer that describes the
2267 states of a security association. They are:
2269 #define SADB_SASTATE_LARVAL 0
2270 #define SADB_SASTATE_MATURE 1
2271 #define SADB_SASTATE_DYING 2
2272 #define SADB_SASTATE_DEAD 3
2274 #define SADB_SASTATE_MAX 3
2276 A SADB_SASTATE_LARVAL security association is one that was created by
2277 the SADB_GETSPI message. A SADB_SASTATE_MATURE association is one
2278 that was updated with the SADB_UPDATE message or added with the
2279 SADB_ADD message. A DYING association is one whose soft lifetime has
2280 expired. A SADB_SASTATE_DEAD association is one whose hard lifetime
2281 has expired, but hasn't been reaped by system garbage collection. If
2282 a consumer of security associations has to extend an association
2283 beyond its normal lifetime (e.g. OSPF Security) it MUST only set the
2284 soft lifetime for an association.
2286 3.4 Security Association Types
2288 This defines the type of Security Association in this message. The
2289 symbolic names are always the same, even on different
2290 implementations. Applications SHOULD use the symbolic name in order
2291 to have maximum portability across different implementations. These
2292 are defined in the file <net/pfkeyv2.h>.
2298 McDonald, et. al. Informational [Page 41]
2299 \f
2300 RFC 2367 PF_KEY Key Management API July 1998
2303 #define SADB_SATYPE_UNSPEC 0
2305 #define SADB_SATYPE_AH 2 /* RFC-1826 */
2306 #define SADB_SATYPE_ESP 3 /* RFC-1827 */
2308 #define SADB_SATYPE_RSVP 5 /* RSVP Authentication */
2309 #define SADB_SATYPE_OSPFV2 6 /* OSPFv2 Authentication */
2310 #define SADB_SATYPE_RIPV2 7 /* RIPv2 Authentication */
2311 #define SADB_SATYPE_MIP 8 /* Mobile IP Auth. */
2313 #define SADB_SATYPE_MAX 8
2315 SADB_SATYPE_UNSPEC is defined for completeness and means no specific
2316 type of security association. This type is never used with PF_KEY
2317 SAs.
2319 SADB_SATYPE_AH is for the IP Authentication Header [Atk95b].
2321 SADB_SATYPE_ESP is for the IP Encapsulating Security Payload
2322 [Atk95c].
2324 SADB_SATYPE_RSVP is for the RSVP Integrity Object.
2326 SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication
2327 [Moy98].
2329 SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97].
2331 SADB_SATYPE_MIP is for Mobile IP's authentication extensions [Per97].
2333 SADB_SATYPE_MAX is always set to the highest valid numeric value.
2335 3.5 Algorithm Types
2337 The algorithm type is interpreted in the context of the Security
2338 Association type defined above. The numeric value might vary between
2339 implementations, but the symbolic name MUST NOT vary between
2340 implementations. Applications should use the symbolic name in order
2341 to have maximum portability to various implementations.
2343 Some of the algorithm types defined below might not be standardized
2344 or might be deprecated in the future. To obtain an assignment for a
2345 symbolic name, contact the authors.
2347 The symbols below are defined in <net/pfkeyv2.h>.
2354 McDonald, et. al. Informational [Page 42]
2355 \f
2356 RFC 2367 PF_KEY Key Management API July 1998
2359 /* Authentication algorithms */
2360 #define SADB_AALG_NONE 0
2361 #define SADB_AALG_MD5HMAC 2
2362 #define SADB_AALG_SHA1HMAC 3
2363 #define SADB_AALG_MAX 3
2365 /* Encryption algorithms */
2366 #define SADB_EALG_NONE 0
2367 #define SADB_EALG_DESCBC 2
2368 #define SADB_EALG_3DESCBC 3
2369 #define SADB_EALG_NULL 11
2370 #define SADB_EALG_MAX 11
2372 The algorithm for SADB_AALG_MD5_HMAC is defined in [MG98a]. The
2373 algorithm for SADB_AALG_SHA1HMAC is defined in [MG98b]. The
2374 algorithm for SADB_EALG_DESCBC is defined in [MD98]. SADB_EALG_NULL
2375 is the NULL encryption algorithm, defined in [GK98]. The
2376 SADB_EALG_NONE value is not to be used in any security association
2377 except those which have no possible encryption algorithm in them
2378 (e.g. IPsec AH).
2380 3.6 Extension Header Values
2382 To briefly recap the extension header values:
2384 #define SADB_EXT_RESERVED 0
2385 #define SADB_EXT_SA 1
2386 #define SADB_EXT_LIFETIME_CURRENT 2
2387 #define SADB_EXT_LIFETIME_HARD 3
2388 #define SADB_EXT_LIFETIME_SOFT 4
2389 #define SADB_EXT_ADDRESS_SRC 5
2390 #define SADB_EXT_ADDRESS_DST 6
2391 #define SADB_EXT_ADDRESS_PROXY 7
2392 #define SADB_EXT_KEY_AUTH 8
2393 #define SADB_EXT_KEY_ENCRYPT 9
2394 #define SADB_EXT_IDENTITY_SRC 10
2395 #define SADB_EXT_IDENTITY_DST 11
2396 #define SADB_EXT_SENSITIVITY 12
2397 #define SADB_EXT_PROPOSAL 13
2398 #define SADB_EXT_SUPPORTED_AUTH 14
2399 #define SADB_EXT_SUPPORTED_ENCRYPT 15
2400 #define SADB_EXT_SPIRANGE 16
2402 #define SADB_EXT_MAX 16
2410 McDonald, et. al. Informational [Page 43]
2411 \f
2412 RFC 2367 PF_KEY Key Management API July 1998
2415 3.7 Identity Extension Values
2417 Each identity can have a certain type.
2419 #define SADB_IDENTTYPE_RESERVED 0
2420 #define SADB_IDENTTYPE_PREFIX 1
2421 #define SADB_IDENTTYPE_FQDN 2
2422 #define SADB_IDENTTYPE_USERFQDN 3
2424 #define SADB_IDENTTYPE_MAX 3
2426 The PREFIX identity string consists of a network address followed by a
2427 forward slash and a prefix length. The network address is in a
2428 printable numeric form appropriate for the protocol family. The
2429 prefix length is a decimal number greater than or equal to zero and
2430 less than the number of bits in the network address. It indicates the
2431 number of bits in the network address that are significant; all bits
2432 in the network address that are not significant MUST be set to zero.
2433 Note that implementations MUST parse the contents of the printable
2434 address into a binary form for comparison purposes because multiple
2435 printable strings are valid representations of the same address in
2436 many protocol families (for example, some allow leading zeros and some
2437 have letters that are case insensitive). Examples of PREFIX identities
2438 are "199.33.248.64/27" and "3ffe::1/128". If the source or destination
2439 identity is a PREFIX identity, the source or destination address for
2440 the SA (respectively) MUST be within that prefix. The sadb_ident_id
2441 field is zeroed for these identity types.
2443 The FQDN identity string contains a fully qualified domain name. An
2444 example FQDN identity is "ministry-of-truth.inner.net". The
2445 sadb_ident_id field is zeroed for these identity types.
2447 The UserFQDN identity consists of a text string in the format commonly
2448 used for Internet-standard electronic mail. The syntax is the text
2449 username, followed by the "@" character, followed in turn by the
2450 appropriate fully qualified domain name. This identity specifies both
2451 a username and an associated FQDN. There is no requirement that this
2452 string specify a mailbox valid for SMTP or other electronic mail
2453 use. This identity is useful with protocols supporting user-oriented
2454 keying. It is a convenient identity form because the DNS Security
2455 extensions can be used to distribute signed public key values by
2456 associating KEY and SIG records with an appropriate MB DNS record. An
2457 example UserFQDN identity is "julia@ministry-of-love.inner.net". The
2458 sadb_ident_id field is used to contain a POSIX user id in the absence
2459 of an identity string itself so that a user-level application can use
2460 the getpwuid{,_r}() routine to obtain a textual user login id. If a
2461 string is present, it SHOULD match the numeric value in the
2462 sadb_ident_id field. If it does not match, the string SHOULD override
2466 McDonald, et. al. Informational [Page 44]
2467 \f
2468 RFC 2367 PF_KEY Key Management API July 1998
2471 the numeric value.
2473 3.8 Sensitivity Extension Values
2475 The only field currently defined in the sensitivity extension is the
2476 sadb_sens_dpd, which represents the data protection domain. The other
2477 data in the sensitivity extension is based off the sadb_sens_dpd
2478 value.
2480 The DP/DOI is defined to be the same as the "Labeled Domain Identifier
2481 Value" of the IP Security DOI specification [Pip98]. As noted in that
2482 specification, values in the range 0x80000000 to 0xffffffff
2483 (inclusive) are reserved for private use and values in the range
2484 0x00000001 through 0x7fffffff are assigned by IANA. The all-zeros
2485 DP/DOI value is permanently reserved to mean that "no DP/DOI is in
2486 use".
2488 3.9 Proposal Extension Values
2490 These are already mentioned in the Algorithm Types and Security
2491 Association Flags sections.
2493 4 Future Directions
2495 While the current specification for the Sensitivity and Integrity
2496 Labels is believed to be general enough, if a case should arise that
2497 can't work with the current specification then this might cause a
2498 change in a future version of PF_KEY.
2500 Similarly, PF_KEY might need extensions to work with other kinds of
2501 Security Associations in future. It is strongly desirable for such
2502 extensions to be made in a backwards-compatible manner should they be
2503 needed.
2505 When more experience is gained with certificate management, it is
2506 possible that the IDENTITY extension will have to be revisited to
2507 allow a finer grained selection of certificate identities.
2509 5. Examples
2511 The following examples illustrate how PF_KEY is used. The first
2512 example is an IP Security example, where the consumer of the security
2513 associations is inside an operating system kernel. The second example
2514 is an OSPF Security example, which illustrates a user-level consumer
2515 of security associations. The third example covers things not
2516 mentioned by the first two examples. A real system may closely
2517 conform to one of these examples, or take parts of them. These
2518 examples are purely illustrative, and are not intended to mandate a
2522 McDonald, et. al. Informational [Page 45]
2523 \f
2524 RFC 2367 PF_KEY Key Management API July 1998
2527 particular implementation method.
2529 5.1 Simple IP Security Example
2531 +---------------+ +-------------+
2532 |Key Mgmt Daemon| | Application |
2533 +---------------+ +-------------+
2534 | | /
2535 | | /
2536 | | | Applications
2537 ======[PF_KEY]====[PF_INET]==========================
2538 | | | OS Kernel
2539 +------------+ +-----------------+
2540 | Key Engine | | TCP/IP, |
2541 | or SADB |---| including IPsec |
2542 +------------+ | |
2543 +-----------------+
2545 When the Key Management daemon (KMd) begins. It must tell PF_KEY
2546 that it is willing to accept message for the two IPsec services, AH
2547 and ESP. It does this by sending down two SADB_REGISTER messages.
2549 KMd->Kernel: SADB_REGISTER for ESP
2550 Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms
2551 KMd->Kernel: SADB_REGISTER for AH
2552 Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms
2554 Each REGISTER message will cause a reply to go to all PF_KEY sockets
2555 registered for ESP and AH respectively (including the requester).
2557 Assume that no security associations currently exist for IPsec to
2558 use. Consider when a network application begins transmitting data
2559 (e.g. a TCP SYN). Because of policy, or the application's request,
2560 the kernel IPsec module needs an AH security association for this
2561 data. Since there is not one present, the following message is
2562 generated:
2564 Kernel->Registered: SADB_ACQUIRE for AH, addrs, ID, sens,
2565 proposals
2567 The KMd reads the ACQUIRE message, especially the sadb_msg_seq
2568 number. Before it begins the negotiation, it sends down an
2569 SADB_GETSPI message with the sadb_msg_seq number equal to the one
2570 received in the ACQUIRE. The kernel returns the results of the
2571 GETSPI to all listening sockets.
2573 KMd->Kernel: SADB_GETSPI for AH, addr, SPI range
2574 Kernel->All: SADB_GETSPI for AH, assoc, addrs
2578 McDonald, et. al. Informational [Page 46]
2579 \f
2580 RFC 2367 PF_KEY Key Management API July 1998
2583 The KMd may perform a second GETSPI operation if it needs both
2584 directions of IPsec SPI values. Now that the KMd has an SPI for at
2585 least one of the security associations, it begins negotiation. After
2586 deriving keying material, and negotiating other parameters, it sends
2587 down one (or more) SADB_UPDATE messages with the same value in
2588 sadb_msg_seq.
2590 If a KMd has any error at all during its negotiation, it can send
2591 down:
2593 KMd->Kernel: SADB_ACQUIRE for AH, assoc (with an error)
2594 Kernel->All: SADB_ACQUIRE for AH, assoc (same error)
2596 but if it succeeds, it can instead:
2598 KMd->Kernel: SADB_UPDATE for AH, assoc, addrs, keys,
2599 <etc.>
2600 Kernel->All: SADB_UPDATE for AH, assoc, addrs, <etc.>
2602 The results of the UPDATE (minus the actual keys) are sent to all
2603 listening sockets. If only one SPI value was determined locally, the
2604 other SPI (since IPsec SAs are unidirectional) must be added with an
2605 SADB_ADD message.
2607 KMd->Kernel: SADB_ADD for AH, assoc, addrs, keys, <etc.>
2608 Kernel->All: SADB_ADD for AH, assoc, addrs, <etc.>
2610 If one of the extensions passed down was a Lifetime extension, it is
2611 possible at some point an SADB_EXPIRE message will arrive when one of
2612 the lifetimes has expired.
2614 Kernel->All: SADB_EXPIRE for AH, assoc, addrs,
2615 Hard or Soft, Current, <etc.>
2617 The KMd can use this as a clue to begin negotiation, or, if it has
2618 some say in policy, send an SADB_UPDATE down with a lifetime
2619 extension.
2621 5.2 Proxy IP Security Example
2623 Many people are interested in using IP Security in a "proxy" or
2624 "firewall" configuration in which an intermediate system provides
2625 security services for "inside" hosts. In these environments, the
2626 intermediate systems can use PF_KEY to communicate with key
2627 management applications almost exactly as they would if they were the
2628 actual endpoints. The messaging behavior of PF_KEY in these cases is
2629 exactly the same as the previous example, but the address information
2630 is slightly different.
2634 McDonald, et. al. Informational [Page 47]
2635 \f
2636 RFC 2367 PF_KEY Key Management API July 1998
2639 Consider this case:
2641 A ========= B --------- C
2643 Key:
2644 A "outside" host that implements IPsec
2645 B "firewall" that implements IPsec
2646 C "inside" host that does not implement IPsec
2648 === IP_{A<->B} ESP [ IP_{A<->C} ULP ]
2649 --- IP_{A<->C} ULP
2651 A is a single system that wishes to communicate with the "inside"
2652 system C. B is a "firewall" between C and the outside world that
2653 will do ESP and tunneling on C's behalf. A discovers that it needs
2654 to send traffic to C via B through methods not described here (Use of
2655 the DNS' KX record might be one method for discovering this).
2657 For packets that flow from left to right, A and B need an IPsec
2658 Security Association with:
2660 SA type of ESP tunnel-mode
2661 Source Identity that dominates A (e.g. A's address)
2662 Destination Identity that dominates B (e.g. B's address)
2663 Source Address of A
2664 Destination Address of B
2666 For packets to flow from right to left, A and B need an IPsec
2667 Security Association with:
2669 SA type of ESP tunnel-mode
2670 Source Identity that dominates C
2671 Destination Identity that dominates A
2672 Source Address of B
2673 Destination Address of A
2674 Proxy Address of C
2676 For this second SA (for packets flowing from C towards A), node A
2677 MUST verify that the inner source address is dominated by the Source
2678 Identity for the SA used with those packets. If node A does not do
2679 this, an adversary could forge packets with an arbitrary Source
2680 Identity and defeat the packet origin protections provided by IPsec.
2682 Now consider a slightly more complex case:
2684 A_1 --| |-- D_1
2685 |--- B ====== C ---|
2686 A_2 --| |-- D_2
2690 McDonald, et. al. Informational [Page 48]
2691 \f
2692 RFC 2367 PF_KEY Key Management API July 1998
2695 Key:
2696 A_n "inside" host on net 1 that does not do IPsec.
2697 B "firewall" for net 1 that supports IPsec.
2698 C "firewall" for net 2 that supports IPsec.
2699 D_n "inside" host on net 2 that does not do IPsec.
2700 === IP_{B<->C} ESP [ IP_{A<->C} ULP ]
2701 --- IP_{A<->C} ULP
2703 For A_1 to send a packet to D_1, B and C need an SA with:
2705 SA Type of ESP
2706 Source Identity that dominates A_1
2707 Destination Identity that dominates C
2708 Source Address of B
2709 Destination Address of C
2710 Proxy Address of A_1
2712 For D_1 to send a packet to A_1, C and B need an SA with:
2713 SA Type of ESP Tunnel-mode
2714 Source Identity that dominates D_1
2715 Destination Identity that dominates B
2716 Source Address of C
2717 Destination Address of B
2718 Proxy Address of D_1
2720 Note that A_2 and D_2 could be substituted for A_1 and D_1
2721 (respectively) here; the association of an SA with a particular pair
2722 of ends or group of those pairs is a policy decision on B and/or C
2723 and not necessarily a function of key management. The same check of
2724 the Source Identity against the inner source IP address MUST also be
2725 performed in this case for the same reason.
2727 For a more detailed discussion of the use of IP Security in complex
2728 cases, please see [Atk97].
2730 NOTE: The notion of identity domination might be unfamiliar. Let H
2731 represent some node. Let Hn represent H's fully qualified domain
2732 name. Let Ha represent the IP address of H. Let Hs represent the IP
2733 subnet containing Ha. Let Hd represent a fully qualified domain
2734 name that is a parent of the fully qualified domain name of H. Let
2735 M be a UserFQDN identity that whose right-hand part is Hn or Ha.
2737 Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the
2738 example above. Hs dominates any node having an IP address within
2739 the IP address range represented by Hs. Hd dominates any node
2740 having a fully qualified domain name within underneath Hd.
2746 McDonald, et. al. Informational [Page 49]
2747 \f
2748 RFC 2367 PF_KEY Key Management API July 1998
2751 5.3 OSPF Security Example
2753 +---------------+ +-------------+
2754 |Key Mgmt Daemon| | OSPF daemon |
2755 +---------------+ +-------------+
2756 | | / / |
2757 | /------|----+ / |
2758 | / | +---+ | Applications
2759 ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================
2760 | | | | OS Kernel
2761 +------------+ +-----------------+ +---------+
2762 | Key Engine | | TCP/IP, | | Routing |
2763 | or SADB |---| including IPsec |--| Table |
2764 +------------+ | | +---------+
2765 +-----------------+
2767 As in the previous examples, the KMd registers itself with the Key
2768 Engine via PF_KEY. Even though the consumer of the security
2769 associations is in user-space, the PF_KEY and Key Engine
2770 implementation knows enough to store SAs and to relay messages.
2772 When the OSPF daemon needs to communicate securely with its peers, it
2773 would perform an SADB_GET message and retrieve the appropriate
2774 association:
2776 OSPFd->Kernel: SADB_GET of OSPF, assoc, addrs
2777 Kernel->OSPFd: SADB_GET of OSPF, assoc, addrs, keys, <etc.>
2779 If this GET fails, the OSPFd may need to acquire a new security
2780 association. This interaction is as follows:
2782 OSPFd->Kernel: SADB_ACQUIRE of OSPF, addrs, <ID, sens,>
2783 proposal
2784 Kernel->Registered: SADB_ACQUIRE of OSPF, <same as sent message>
2786 The KMd sees this and performs actions similar to the previous
2787 example. One difference, however, is that when the UPDATE message
2788 comes back, the OSPFd will then perform a GET of the updated SA to
2789 retrieve all of its parameters.
2791 5.4 Miscellaneous
2793 Some messages work well only in system maintenance programs, for
2794 debugging, or for auditing. In a system panic situation, such as a
2795 detected compromise, an SADB_FLUSH message should be issued for a
2796 particular SA type, or for ALL SA types.
2802 McDonald, et. al. Informational [Page 50]
2803 \f
2804 RFC 2367 PF_KEY Key Management API July 1998
2807 Program->Kernel: SADB_FLUSH for ALL
2808 <Kernel then flushes all internal SAs>
2809 Kernel->All: SADB_FLUSH for ALL
2811 Some SAs may need to be explicitly deleted, either by a KMd, or by a
2812 system maintenance program.
2814 Program->Kernel: SADB_DELETE for AH, association, addrs
2815 Kernel->All: SADB_DELETE for AH, association, addrs
2817 Common usage of the SADB_DUMP message is discouraged. For debugging
2818 purposes, however, it can be quite useful. The output of a DUMP
2819 message should be read quickly, in order to avoid socket buffer
2820 overflows.
2822 Program->Kernel: SADB_DUMP for ESP
2823 Kernel->Program: SADB_DUMP for ESP, association, <all fields>
2824 Kernel->Program: SADB_DUMP for ESP, association, <all fields>
2825 Kernel->Program: SADB_DUMP for ESP, association, <all fields>
2826 <ad nauseam...>
2828 6 Security Considerations
2830 This memo discusses a method for creating, reading, modifying, and
2831 deleting Security Associations from an operating system. Only
2832 trusted, privileged users and processes should be able to perform any
2833 of these operations. It is unclear whether this mechanism provides
2834 any security when used with operating systems not having the concept
2835 of a trusted, privileged user.
2837 If an unprivileged user is able to perform any of these operations,
2838 then the operating system cannot actually provide the related
2839 security services. If an adversary knows the keys and algorithms in
2840 use, then cryptography cannot provide any form of protection.
2842 This mechanism is not a panacea, but it does provide an important
2843 operating system component that can be useful in creating a secure
2844 internetwork.
2846 Users need to understand that the quality of the security provided by
2847 an implementation of this specification depends completely upon the
2848 overall security of the operating system, the correctness of the
2849 PF_KEY implementation, and upon the security and correctness of the
2850 applications that connect to PF_KEY. It is appropriate to use high
2851 assurance development techniques when implementing PF_KEY and the
2852 related security association components of the operating system.
2858 McDonald, et. al. Informational [Page 51]
2859 \f
2860 RFC 2367 PF_KEY Key Management API July 1998
2863 Acknowledgments
2865 The authors of this document are listed primarily in alphabetical
2866 order. Randall Atkinson and Ron Lee provided useful feedback on
2867 earlier versions of this document.
2869 At one time or other, all of the authors worked at the Center for
2870 High Assurance Computer Systems at the U.S. Naval Research
2871 Laboratory. This work was sponsored by the Information Security
2872 Program Office (PMW-161), U.S. Space and Naval Warfare Systems
2873 Command (SPAWAR) and the Computing Systems Technology Office, Defense
2874 Advanced Research Projects Agency (DARPA/CSTO). We really appreciate
2875 their sponsorship of our efforts and their continued support of
2876 PF_KEY development. Without that support, PF_KEY would not exist.
2878 The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST98].
2880 Finally, the authors would like to thank those who sent in comments
2881 and questions on the various iterations of this document. This
2882 specification and implementations of it are discussed on the PF_KEY
2883 mailing list. If you would like to be added to this list, send a note
2884 to <pf_key-request@inner.net>.
2886 References
2888 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig
2889 W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite
2890 BSD", Proceedings of the 1996 USENIX Conference, San Diego, CA,
2891 January 1996, USENIX Association.
2893 [Atk95a] Atkinson, R., "IP Security Architecture", RFC 1825, August
2894 1995.
2896 [Atk95b] Atkinson, R., "IP Authentication Header", RFC 1826, August
2897 1995.
2899 [Atk95c] Atkinson, R., "IP Encapsulating Security Payload", RFC 1827,
2900 August 1995.
2902 [Atk97] Atkinson, R., "Key Exchange Delegation Record for the Domain
2903 Name System", RFC 2230, October 1997.
2905 [BA97] Baker, F., and R. Atkinson, "RIP-2 MD5 Authentication", RFC
2906 2082, January 1997.
2908 [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer
2909 Systems", MTR-3153, The MITRE Corporation, June 1975; ESD-TR-76-372,
2910 April 1977.
2914 McDonald, et. al. Informational [Page 52]
2915 \f
2916 RFC 2367 PF_KEY Key Management API July 1998
2919 [BL74] D. Elliot Bell and Leonard J. LaPadula, "Secure Computer
2920 Systems: Unified Exposition and Multics Interpretation", MTR 2997,
2921 The MITRE Corporation, April 1974. (AD/A 020 445)
2923 [Bra97] Bradner, S., "Key words for use in RFCs to Indicate
2924 Requirement Levels", BCP 14, RFC 2119, March 1997.
2926 [CW87] D. D. Clark and D. R. Wilson, "A Comparison of Commercial and
2927 Military Computer Security Policies", Proceedings of the 1987
2928 Symposium on Security and Privacy, pp. 184-195, IEEE Computer
2929 Society, Washington, D.C., 1987.
2931 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode
2932 Workstation Specification", Technical Report DDS-2600-6243-87.
2934 [GK98] Glenn, R., and S. Kent, "The NULL Encryption Algorithm and Its
2935 Use with IPsec", Work in Progress.
2937 [HM97a] Harney, H., and C. Muckenhirn, "Group Key Management Protocol
2938 (GKMP) Specification", RFC 2093, July 1997.
2940 [HM97b] Harney, H., and C. Muckenhirn, "Group Key Management Protocol
2941 (GKMP) Architecture", RFC 2094, July 1997.
2943 [MD98] Madsen, C., and N. Doraswamy, "The ESP DES-CBC Cipher
2944 Algorithm With Explicit IV", Work in Progress.
2946 [MG98a] Madsen, C., and R. Glenn, "The Use of HMAC-MD5-96 within ESP
2947 and AH", Work in Progress.
2949 [MG98b] Madsen, C., and R. Glenn, "The Use of HMAC-SHA-1-96 within
2950 ESP and AH", Work in Progress.
2952 [MSST98] Maughan, D., Schertler, M., Schneider, M., and J. Turner,
2953 "Internet Security Association and Key Management Protocol (ISAKMP)",
2954 Work in Progress.
2956 [Moy98] Moy, J., "OSPF Version 2", STD 54, RFC 2328, April 1998.
2958 [Per97] Perkins, C., "IP Mobility Support", RFC 2002, October 1996.
2960 [Pip98] Piper, D., "The Internet IP Security Domain of Interpretation
2961 for ISAKMP", Work in Progress.
2963 [Sch96] Bruce Schneier, Applied Cryptography, p. 360, John Wiley &
2964 Sons, Inc., 1996.
2970 McDonald, et. al. Informational [Page 53]
2971 \f
2972 RFC 2367 PF_KEY Key Management API July 1998
2975 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for
2976 Berkeley UNIX", Proceedings of the Winter 1991 USENIX Conference,
2977 Dallas, TX, USENIX Association. 1991. pp. 93-103.
2979 Disclaimer
2981 The views and specification here are those of the editors and are not
2982 necessarily those of their employers. The employers have not passed
2983 judgment on the merits, if any, of this work. The editors and their
2984 employers specifically disclaim responsibility for any problems
2985 arising from correct or incorrect implementation or use of this
2986 specification.
2988 Authors' Addresses
2990 Daniel L. McDonald
2991 Sun Microsystems, Inc.
2992 901 San Antonio Road, MS UMPK17-202
2993 Palo Alto, CA 94303
2995 Phone: +1 650 786 6815
2996 EMail: danmcd@eng.sun.com
2999 Craig Metz
3000 (for Code 5544)
3001 U.S. Naval Research Laboratory
3002 4555 Overlook Ave. SW
3003 Washington, DC 20375
3005 Phone: (DSN) 754-8590
3006 EMail: cmetz@inner.net
3009 Bao G. Phan
3010 U. S. Naval Research Laboratory
3012 EMail: phan@itd.nrl.navy.mil
3026 McDonald, et. al. Informational [Page 54]
3027 \f
3028 RFC 2367 PF_KEY Key Management API July 1998
3031 Appendix A: Promiscuous Send/Receive Message Type
3033 A kernel supporting PF_KEY MAY implement the following extension for
3034 development and debugging purposes. If it does, it MUST implement the
3035 extension as specified here. An implementation MAY require an
3036 application to have additional privileges to perform promiscuous send
3037 and/or receive operations.
3039 The SADB_X_PROMISC message allows an application to send and receive
3040 messages in a "promiscuous mode." There are two forms of this
3041 message: control and data. The control form consists of only a
3042 message header. This message is used to toggle the promiscuous-
3043 receive function. A value of one in the sadb_msg_satype field enables
3044 promiscuous message reception for this socket, while a value of zero
3045 in that field disables it.
3047 The second form of this message is the data form. This is used to
3048 send or receive messages in their raw form. Messages in the data form
3049 consist of a message header followed by an entire new message. There
3050 will be two message headers in a row: one for the SADB_X_PROMISC
3051 message, and one for the payload message.
3053 Data messages sent from the application are sent to either the PF_KEY
3054 socket of a single process identified by a nonzero sadb_msg_seq or to
3055 all PF_KEY sockets if sadb_msg_seq is zero. These messages are sent
3056 without any processing of their contents by the PF_KEY interface
3057 (including sanity checking). This promiscuous-send capability allows
3058 an application to send messages as if it were the kernel. This also
3059 allows it to send erroneous messages.
3061 If the promiscuous-receive function has been enabled, a copy of any
3062 message sent via PF_KEY by another application or by the kernel is
3063 sent to the promiscuous application. This is done before any
3064 processing of the message's contents by the PF_KEY interface (again,
3065 including sanity checking). This promiscuous-receive capability
3066 allows an application to receive all messages sent by other parties
3067 using PF_KEY.
3069 The messaging behavior of the SADB_X_PROMISC message is:
3071 Send a control-form SADB_X_PROMISC message from a user process
3072 to the kernel.
3074 <base>
3076 The kernel returns the SADB_X_PROMISC message to all listening
3077 processes.
3082 McDonald, et. al. Informational [Page 55]
3083 \f
3084 RFC 2367 PF_KEY Key Management API July 1998
3087 <base>
3089 Send a data-form SADB_X_PROMISC message from a user process to
3090 the kernel.
3092 <base, base(, others)>
3094 The kernel sends the encapsulated message to the target
3095 process(s).
3097 <base(, others)>
3099 If promiscuous-receive is enabled, the kernel will encapsulate
3100 and send copies of all messages sent via the PF_KEY interface.
3102 <base, base(, others)>
3104 Errors:
3105 EPERM Additional privileges are required to perform the
3106 requested operations.
3107 ESRCH (Data form, sending) The target process in sadb_msg_seq
3108 does not exist or does not have an open PF_KEY Version 2
3109 socket.
3138 McDonald, et. al. Informational [Page 56]
3139 \f
3140 RFC 2367 PF_KEY Key Management API July 1998
3143 Appendix B: Passive Change Message Type
3145 The SADB_X_PCHANGE message is a passive-side (aka. the "listener" or
3146 "receiver") counterpart to the SADB_ACQUIRE message. It is useful
3147 for when key management applications wish to more effectively handle
3148 incoming key management requests for passive-side sessions that
3149 deviate from systemwide default security services. If a passive
3150 session requests that only certain levels of security service be
3151 allowed, the SADB_X_PCHANGE message expresses this change to any
3152 registered PF_KEY sockets. Unlike SADB_ACQUIRE, this message is
3153 purely informational, and demands no other PF_KEY interaction.
3155 The SADB_X_PCHANGE message is typically triggered by either a change
3156 in an endpoint's requested security services, or when an endpoint
3157 that made a special request disappears. In the former case, an
3158 SADB_X_PCHANGE looks like an SADB_ACQUIRE, complete with an
3159 sadb_proposal extension indicating the preferred algorithms,
3160 lifetimes, and other attributes. When a passive session either
3161 disappears, or reverts to a default behavior, an SADB_X_PCHANGE will
3162 be issued with _no_ sadb_proposal extension, indicating that the
3163 exception to systemwide default behavior has disappeared.
3165 There are two messaging behaviors for SADB_X_PCHANGE. The first is
3166 the kernel-originated case:
3168 The kernel sends an SADB_X_PCHANGE message to registered
3169 sockets.
3171 <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>
3173 NOTE: The address(SD) extensions MUST have the port fields
3174 filled in with the port numbers of the session
3175 requiring keys if appropriate.
3177 The second is for a user-level consumer of SAs.
3179 Send an SADB_X_PCHANGE message from a user process to the
3180 kernel.
3182 <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>
3184 The kernel returns an SADB_X_PCHANGE message to registered
3185 sockets.
3187 <base, address(SD), (identity(SD),) (sensitivity,) (proposal)>
3194 McDonald, et. al. Informational [Page 57]
3195 \f
3196 RFC 2367 PF_KEY Key Management API July 1998
3199 Appendix C: Key Management Private Data Extension
3201 The Key Management Private Data extension is attached to either an
3202 SADB_ADD or an SADB_UPDATE message. It attaches a single piece of
3203 arbitrary data to a security association. It may be useful for key
3204 managment applications that could use an SADB_DUMP or SADB_GET
3205 message to obtain additional state if it needs to restart or recover
3206 after a crash. The format of this extension is:
3208 #define SADB_X_EXT_KMPRIVATE 17
3210 struct sadb_x_kmprivate {
3211 uint16_t sadb_x_kmprivate_len;
3212 uint16_t sadb_x_kmprivate_exttype;
3213 uint32_t sadb_x_kmprivate_reserved;
3214 };
3215 /* sizeof(struct sadb_x_kmprivate) == 8 */
3217 /* followed by arbitrary data */
3220 The data following the sadb_x_kmprivate extension can be anything.
3221 It will be stored with the actual security association in the kernel.
3222 Like all data, it must be padded to an eight byte boundary.
3250 McDonald, et. al. Informational [Page 58]
3251 \f
3252 RFC 2367 PF_KEY Key Management API July 1998
3255 Appendix D: Sample Header File
3257 /*
3258 This file defines structures and symbols for the PF_KEY Version 2
3259 key management interface. It was written at the U.S. Naval Research
3260 Laboratory. This file is in the public domain. The authors ask that
3261 you leave this credit intact on any copies of this file.
3262 */
3263 #ifndef __PFKEY_V2_H
3264 #define __PFKEY_V2_H 1
3266 #define PF_KEY_V2 2
3267 #define PFKEYV2_REVISION 199806L
3269 #define SADB_RESERVED 0
3270 #define SADB_GETSPI 1
3271 #define SADB_UPDATE 2
3272 #define SADB_ADD 3
3273 #define SADB_DELETE 4
3274 #define SADB_GET 5
3275 #define SADB_ACQUIRE 6
3276 #define SADB_REGISTER 7
3277 #define SADB_EXPIRE 8
3278 #define SADB_FLUSH 9
3279 #define SADB_DUMP 10
3280 #define SADB_X_PROMISC 11
3281 #define SADB_X_PCHANGE 12
3282 #define SADB_MAX 12
3284 struct sadb_msg {
3285 uint8_t sadb_msg_version;
3286 uint8_t sadb_msg_type;
3287 uint8_t sadb_msg_errno;
3288 uint8_t sadb_msg_satype;
3289 uint16_t sadb_msg_len;
3290 uint16_t sadb_msg_reserved;
3291 uint32_t sadb_msg_seq;
3292 uint32_t sadb_msg_pid;
3293 };
3295 struct sadb_ext {
3296 uint16_t sadb_ext_len;
3297 uint16_t sadb_ext_type;
3298 };
3300 struct sadb_sa {
3301 uint16_t sadb_sa_len;
3302 uint16_t sadb_sa_exttype;
3306 McDonald, et. al. Informational [Page 59]
3307 \f
3308 RFC 2367 PF_KEY Key Management API July 1998
3311 uint32_t sadb_sa_spi;
3312 uint8_t sadb_sa_replay;
3313 uint8_t sadb_sa_state;
3314 uint8_t sadb_sa_auth;
3315 uint8_t sadb_sa_encrypt;
3316 uint32_t sadb_sa_flags;
3317 };
3319 struct sadb_lifetime {
3320 uint16_t sadb_lifetime_len;
3321 uint16_t sadb_lifetime_exttype;
3322 uint32_t sadb_lifetime_allocations;
3323 uint64_t sadb_lifetime_bytes;
3324 uint64_t sadb_lifetime_addtime;
3325 uint64_t sadb_lifetime_usetime;
3326 };
3328 struct sadb_address {
3329 uint16_t sadb_address_len;
3330 uint16_t sadb_address_exttype;
3331 uint8_t sadb_address_proto;
3332 uint8_t sadb_address_prefixlen;
3333 uint16_t sadb_address_reserved;
3334 };
3336 struct sadb_key {
3337 uint16_t sadb_key_len;
3338 uint16_t sadb_key_exttype;
3339 uint16_t sadb_key_bits;
3340 uint16_t sadb_key_reserved;
3341 };
3343 struct sadb_ident {
3344 uint16_t sadb_ident_len;
3345 uint16_t sadb_ident_exttype;
3346 uint16_t sadb_ident_type;
3347 uint16_t sadb_ident_reserved;
3348 uint64_t sadb_ident_id;
3349 };
3351 struct sadb_sens {
3352 uint16_t sadb_sens_len;
3353 uint16_t sadb_sens_exttype;
3354 uint32_t sadb_sens_dpd;
3355 uint8_t sadb_sens_sens_level;
3356 uint8_t sadb_sens_sens_len;
3357 uint8_t sadb_sens_integ_level;
3358 uint8_t sadb_sens_integ_len;
3362 McDonald, et. al. Informational [Page 60]
3363 \f
3364 RFC 2367 PF_KEY Key Management API July 1998
3367 uint32_t sadb_sens_reserved;
3368 };
3370 struct sadb_prop {
3371 uint16_t sadb_prop_len;
3372 uint16_t sadb_prop_exttype;
3373 uint8_t sadb_prop_replay;
3374 uint8_t sadb_prop_reserved[3];
3375 };
3377 struct sadb_comb {
3378 uint8_t sadb_comb_auth;
3379 uint8_t sadb_comb_encrypt;
3380 uint16_t sadb_comb_flags;
3381 uint16_t sadb_comb_auth_minbits;
3382 uint16_t sadb_comb_auth_maxbits;
3383 uint16_t sadb_comb_encrypt_minbits;
3384 uint16_t sadb_comb_encrypt_maxbits;
3385 uint32_t sadb_comb_reserved;
3386 uint32_t sadb_comb_soft_allocations;
3387 uint32_t sadb_comb_hard_allocations;
3388 uint64_t sadb_comb_soft_bytes;
3389 uint64_t sadb_comb_hard_bytes;
3390 uint64_t sadb_comb_soft_addtime;
3391 uint64_t sadb_comb_hard_addtime;
3392 uint64_t sadb_comb_soft_usetime;
3393 uint64_t sadb_comb_hard_usetime;
3394 };
3396 struct sadb_supported {
3397 uint16_t sadb_supported_len;
3398 uint16_t sadb_supported_exttype;
3399 uint32_t sadb_supported_reserved;
3400 };
3402 struct sadb_alg {
3403 uint8_t sadb_alg_id;
3404 uint8_t sadb_alg_ivlen;
3405 uint16_t sadb_alg_minbits;
3406 uint16_t sadb_alg_maxbits;
3407 uint16_t sadb_alg_reserved;
3408 };
3410 struct sadb_spirange {
3411 uint16_t sadb_spirange_len;
3412 uint16_t sadb_spirange_exttype;
3413 uint32_t sadb_spirange_min;
3414 uint32_t sadb_spirange_max;
3418 McDonald, et. al. Informational [Page 61]
3419 \f
3420 RFC 2367 PF_KEY Key Management API July 1998
3423 uint32_t sadb_spirange_reserved;
3424 };
3426 struct sadb_x_kmprivate {
3427 uint16_t sadb_x_kmprivate_len;
3428 uint16_t sadb_x_kmprivate_exttype;
3429 uint32_t sadb_x_kmprivate_reserved;
3430 };
3432 #define SADB_EXT_RESERVED 0
3433 #define SADB_EXT_SA 1
3434 #define SADB_EXT_LIFETIME_CURRENT 2
3435 #define SADB_EXT_LIFETIME_HARD 3
3436 #define SADB_EXT_LIFETIME_SOFT 4
3437 #define SADB_EXT_ADDRESS_SRC 5
3438 #define SADB_EXT_ADDRESS_DST 6
3439 #define SADB_EXT_ADDRESS_PROXY 7
3440 #define SADB_EXT_KEY_AUTH 8
3441 #define SADB_EXT_KEY_ENCRYPT 9
3442 #define SADB_EXT_IDENTITY_SRC 10
3443 #define SADB_EXT_IDENTITY_DST 11
3444 #define SADB_EXT_SENSITIVITY 12
3445 #define SADB_EXT_PROPOSAL 13
3446 #define SADB_EXT_SUPPORTED_AUTH 14
3447 #define SADB_EXT_SUPPORTED_ENCRYPT 15
3448 #define SADB_EXT_SPIRANGE 16
3449 #define SADB_X_EXT_KMPRIVATE 17
3450 #define SADB_EXT_MAX 17
3451 #define SADB_SATYPE_UNSPEC 0
3452 #define SADB_SATYPE_AH 2
3453 #define SADB_SATYPE_ESP 3
3454 #define SADB_SATYPE_RSVP 5
3455 #define SADB_SATYPE_OSPFV2 6
3456 #define SADB_SATYPE_RIPV2 7
3457 #define SADB_SATYPE_MIP 8
3458 #define SADB_SATYPE_MAX 8
3460 #define SADB_SASTATE_LARVAL 0
3461 #define SADB_SASTATE_MATURE 1
3462 #define SADB_SASTATE_DYING 2
3463 #define SADB_SASTATE_DEAD 3
3464 #define SADB_SASTATE_MAX 3
3466 #define SADB_SAFLAGS_PFS 1
3468 #define SADB_AALG_NONE 0
3469 #define SADB_AALG_MD5HMAC 2
3470 #define SADB_AALG_SHA1HMAC 3
3474 McDonald, et. al. Informational [Page 62]
3475 \f
3476 RFC 2367 PF_KEY Key Management API July 1998
3479 #define SADB_AALG_MAX 3
3481 #define SADB_EALG_NONE 0
3482 #define SADB_EALG_DESCBC 2
3483 #define SADB_EALG_3DESCBC 3
3484 #define SADB_EALG_NULL 11
3485 #define SADB_EALG_MAX 11
3487 #define SADB_IDENTTYPE_RESERVED 0
3488 #define SADB_IDENTTYPE_PREFIX 1
3489 #define SADB_IDENTTYPE_FQDN 2
3490 #define SADB_IDENTTYPE_USERFQDN 3
3491 #define SADB_IDENTTYPE_MAX 3
3493 #define SADB_KEY_FLAGS_MAX 0
3494 #endif /* __PFKEY_V2_H */
3530 McDonald, et. al. Informational [Page 63]
3531 \f
3532 RFC 2367 PF_KEY Key Management API July 1998
3535 Appendix E: Change Log
3537 The following changes were made between 05 and 06:
3539 * Last change before becoming an informational RFC. Removed all
3540 Internet-Draft references. Also standardized citation strings.
3541 Now cite RFC 2119 for MUST, etc.
3543 * New appendix on optional KM private data extension.
3545 * Fixed example to indicate the ACQUIRE messages with errno mean
3546 KM failure.
3548 * Added SADB_EALG_NULL.
3550 * Clarified proxy examples to match definition of PROXY address being
3551 the inner packet's source address. (Basically a sign-flip. The
3552 example still shows how to protect against policy vulnerabilities
3553 in tunnel endpoints.)
3555 * Loosened definition of a destination address to include broadcast.
3557 * Recommended that LARVAL security associations have implicit short
3558 lifetimes.
3560 The following changes were made between 04 and 05:
3562 * New appendix on Passive Change message.
3564 * New sadb_address_prefixlen field.
3566 * Small clarifications on sadb_ident_id usage.
3568 * New PFKEYV2_REVISION value.
3570 * Small clarification on what a PROXY address is.
3572 * Corrected sadb_spirange_{min,max} language.
3574 * In ADD messages that are in response to an ACQUIRE, the
3575 sadb_msg_seq MUST be the same as that of the originating ACQUIRE.
3577 * Corrected ACQUIRE message behavior, ACQUIRE message SHOULD send up
3578 PROXY addresses when it needs them.
3580 * Clarification on SADB_EXPIRE and user-level security protocols.
3582 The following changes were made between 03 and 04:
3586 McDonald, et. al. Informational [Page 64]
3587 \f
3588 RFC 2367 PF_KEY Key Management API July 1998
3591 * Stronger language about manual keying.
3593 * PFKEYV2_REVISION, ala POSIX.
3595 * Put in language about sockaddr ports in ACQUIRE messages.
3597 * Mention of asymmetric algorithms.
3599 * New sadb_ident_id field for easier construction of USER_FQDN
3600 identity strings.
3602 * Caveat about source addresses not always used for collision
3603 detection. (e.g. IPsec)
3605 The following changes were made between 02 and 03:
3608 * Formatting changes.
3610 * Many editorial cleanups, rewordings, clarifications.
3612 * Restrictions that prevent many strange and invalid cases.
3614 * Added definitions section.
3616 * Removed connection identity type (this will reappear when it is
3617 more clear what it should look like).
3619 * Removed 5.2.1 (Why involve the kernel?).
3621 * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed
3622 from src, dst, and proxy and you had to anyway for sanity checking.
3624 * Removed REPLAY flag; sadb_sa_replay==0 means the same thing.
3626 * Renamed bit lengths to "bits" to avoid potential confusion.
3628 * Explicitly listed lengths for structures.
3630 * Reworked identities to always use a string format.
3632 * Removed requirements for support of shutdown() and SO_USELOOPBACK.
3634 * 64 bit alignment and 64 bit lengths instead of 32 bit.
3636 * time_t replaced with uint64 in lifetimes.
3642 McDonald, et. al. Informational [Page 65]
3643 \f
3644 RFC 2367 PF_KEY Key Management API July 1998
3647 * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER
3648 FILE).
3650 * Explicit error if PF_KEY_V2 not set at socket() call.
3652 * More text on SO_USELOOPBACK.
3654 * Made fields names and symbol names more consistent.
3656 * Explicit error if PF_KEY_V2 is not in sadb_msg_version field.
3658 * Bytes lifetime field now a 64-bit quantity.
3660 * Explicit len/exttype wording.
3662 * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.)
3664 * UI example (0x123 == 0x1230 or 0x0123).
3666 * Cleaned up and fixed some message behavior examples.
3668 The following changes were made between 01 and 02:
3670 * Mentioned that people COULD use these same messages between user
3671 progs. (Also mentioned why you still might want to use the actual
3672 socket.)
3674 * Various wordsmithing changes.
3676 * Took out netkey/ directory, and make net/pfkeyv2.h
3678 * Inserted PF_KEY_V2 proto argument per C. Metz.
3680 * Mentioned other socket calls and how their PF_KEY behavior is
3681 undefined.
3683 * SADB_EXPIRE now communicates both hard and soft lifetime expires.
3685 * New "association" extension, even smaller base header.
3687 * Lifetime extension improvements.
3689 * Length now first in extensions.
3691 * Errors can be sent from kernel to user, also.
3693 * Examples section inserted.
3698 McDonald, et. al. Informational [Page 66]
3699 \f
3700 RFC 2367 PF_KEY Key Management API July 1998
3703 * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup.
3705 * Key splitting now only across auth algorithm and encryption
3706 algorithm. Thanks for B. Sommerfeld for clues here.
3708 The following changes were made between 00 and 01:
3710 * Added this change log.
3712 * Simplified TLV header syntax.
3714 * Splitting of algorithms. This may be controversial, but it allows
3715 PF_KEY to be used for more than just IPsec. It also allows some
3716 kinds of policies to be placed in the KMd easier.
3718 * Added solid definitions and formats for certificate identities,
3719 multiple keys, etc.
3721 * Specified how keys are to be layed out (most-to-least bits).
3723 * Changed sequence number semantics to be like an RPC transaction ID
3724 number.
3754 McDonald, et. al. Informational [Page 67]
3755 \f
3756 RFC 2367 PF_KEY Key Management API July 1998
3759 F. Full Copyright Statement
3761 Copyright (C) The Internet Society (1998). All Rights Reserved.
3763 This document and translations of it may be copied and furnished to
3764 others, and derivative works that comment on or otherwise explain it
3765 or assist in its implementation may be prepared, copied, published
3766 and distributed, in whole or in part, without restriction of any
3767 kind, provided that the above copyright notice and this paragraph are
3768 included on all such copies and derivative works. However, this
3769 document itself may not be modified in any way, such as by removing
3770 the copyright notice or references to the Internet Society or other
3771 Internet organizations, except as needed for the purpose of
3772 developing Internet standards in which case the procedures for
3773 copyrights defined in the Internet Standards process must be
3774 followed, or as required to translate it into languages other than
3775 English.
3777 The limited permissions granted above are perpetual and will not be
3778 revoked by the Internet Society or its successors or assigns.
3780 This document and the information contained herein is provided on an
3781 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
3782 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
3783 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
3784 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
3785 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3810 McDonald, et. al. Informational [Page 68]
3811 \f