idnits 2.17.1 draft-mcdonald-pf-key-v2-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 352 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 152 instances of too long lines in the document, the longest one being 11 characters in excess of 72. ** The abstract seems to contain references ([Atk95c], [AMPMC96], [Atk95a], [Atk95b]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 66: '... - MUST...' RFC 2119 keyword, line 71: '... - SHOULD...' RFC 2119 keyword, line 78: '... - MAY...' RFC 2119 keyword, line 189: '...r-space policy MAY be implemented b...' RFC 2119 keyword, line 205: '... using PF_KEY MUST NOT depend on t...' (48 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 10 has weird spacing: '... Drafts are ...' == Line 14 has weird spacing: '... Drafts may b...' == Line 15 has weird spacing: '...iate to use ...' == Line 16 has weird spacing: '... Drafts as r...' == Line 24 has weird spacing: '...hat can be u...' == (347 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The addr_which field contains a bitmask indicating what addresses; source, destination, inner-source, inner-destination, and proxy; follow. For each bit set in the addr_which field, a struct sockaddr follows. The sockaddr structure MUST conform to the sockaddr structure of the system implementing PF_KEY. (E.g. If the system has an sa_len field, so MUST the sockaddrs in the message. If the system has NO sa_len field, the sockaddrs MUST not have an sa_len field.) All non-address information in the sockaddrs MUST be zeroed out. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: An extension field MUST not be repeated. If there is a situation where an extension MUST be repeated, it should be brought to the attention of the authors. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: SEC_TYPE_MAX is never used with PF_KEY but is defined for completeness. It is always set to the highest valid numeric value. There MUST not be gaps in the numbering of security types; all numbers must be used sequentially. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (17 March 1997) is 9895 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '3' on line 606 -- Looks like a reference, but probably isn't: '4' on line 573 -- Looks like a reference, but probably isn't: '2' on line 657 -- Possible downref: Non-RFC (?) normative reference: ref. 'AMPMC96' ** Obsolete normative reference: RFC 1825 (ref. 'Atk95a') (Obsoleted by RFC 2401) ** Obsolete normative reference: RFC 1826 (ref. 'Atk95b') (Obsoleted by RFC 2402) ** Obsolete normative reference: RFC 1827 (ref. 'Atk95c') (Obsoleted by RFC 2406) -- Possible downref: Non-RFC (?) normative reference: ref. 'CG96' -- Possible downref: Non-RFC (?) normative reference: ref. 'DIA' -- Possible downref: Non-RFC (?) normative reference: ref. 'Hug96' -- Possible downref: Non-RFC (?) normative reference: ref. 'OG96' -- Possible downref: Non-RFC (?) normative reference: ref. 'Skl91' Summary: 17 errors (**), 0 flaws (~~), 10 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group D. L. McDonald 2 Internet Draft C. W. Metz 3 draft-mcdonald-pf-key-v2-01.txt B. G. Phan 4 17 March 1997 6 PF_KEY Key Management API, Version 2 8 STATUS OF THIS MEMO 10 This document is an Internet Draft. Internet Drafts are working 11 documents. 13 Internet Drafts are draft documents valid for a maximum of 6 14 months. Internet Drafts may be updated, replaced, or obsoleted by 15 other documents at any time. It is not appropriate to use Internet 16 Drafts as reference material or to cite them other than as "work in 17 progress". 19 A future version of this draft will be submitted to the RFC Editor 20 for publication as an Informational document. 22 ABSTRACT 24 A generic key management API that can be used not only for IP 25 Security [Atk95a] [Atk95b] [Atk95c] but also for other network 26 security services is presented in this document. Version 1 of this 27 API was implemented inside 4.4-Lite BSD as part of the U. S. Naval 28 Research Laboratory's freely distributable and usable IPv6 and IPsec 29 implementation[AMPMC96]. It is documented here for the benefit of 30 others who might also adopt and use the API, thus providing increased 31 portability of key management applications (e.g. an ISAKMP daemon, a 32 Photuris daemon or SKIP certificate discovery protocol daemon). 34 1. INTRODUCTION 36 PF_KEY is a new socket protocol family used by trusted privileged 37 key management applications to communicate with an operating system's 38 key management internals (referred to here as the "Key Engine" or the 39 SADB). The Key Engine and its structures incorporate the required 40 security attributes for a session and are instances of the "Security 41 Association" concept described in [Atk95a]. The names, PF_KEY and 42 Key Engine, thus refer to more than cryptographic keys and are 43 retained for consistency with the traditional phrase, "Key 44 Management". 46 PF_KEY is derived in part from the BSD routing socket, PF_ROUTE. 47 [Skl91] This document describes Version 2 of PF_KEY. Version 1 was 48 implemented in the first three alpha test versions of the NRL 49 IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco 50 ISAKMP/Oakley key management daemon. Version 2 extends and refines 51 this interface. 53 Security policy is deliberately omitted from this interface. 54 PF_KEY is not a mechanism for tuning systemwide security policy, nor 55 is it intended to enforce any sort of key management policy. The 56 developers of PF_KEY believed that it was important to separate 57 security mechanisms (such as PF_KEY) from security policies. This 58 permits a single mechanism to more easily support multiple policies. 60 1.1 TERMINOLOGY 62 In this document, the words that are used to define the 63 significance of each particular requirement are usually capitalized. 64 These words are: 66 - MUST 68 This word or the adjective "REQUIRED" means that the item is an 69 absolute requirement of the specification. 71 - SHOULD 73 This word or the adjective "RECOMMENDED" means that there might 74 exist valid reasons in particular circumstances to ignore this item, 75 but the full implications should be understood and the case carefully 76 weighed before taking a different course. 78 - MAY 80 This word or the adjective "OPTIONAL" means that this item is truly 81 optional. One vendor might choose to include the item because a 82 particular marketplace requires it or because it enhances the 83 product, for example; another vendor may omit the same item. 85 1.2 CONCEPTUAL MODEL 87 This section describes the conceptual model of an operating system 88 that implements the PF_KEY key management application programming 89 interface. This section is intended to provide background material 90 useful to understand the rest of this document. Presentation of this 91 conceptual model does not constrain a PF_KEY implementation to 92 strictly adhere to the conceptual components discussed in this 93 subsection. 95 Key management is most commonly implemented in whole or part at the 96 application-layer. For example, the Photuris, ISAKMP, and Oakley 97 proposals for IPsec key management are all application-layer 98 protocols. Even parts of the SKIP IP-layer keying proposal can be 99 implemented at the application layer. Figure 1 shows the 100 relationship between a Key Management daemon and PF_KEY, which it 101 uses to communicate with the Key Engine, and PF_INET (or PF_INET6 in 102 the case of IPv6), which it uses to communicate via the network with 103 a remote key management entity. 105 The "Key Engine" or "Security Association Database (SADB)" is a 106 logical entity in the kernel that stores, updates, and deletes 107 Security Association data for various security protocols. There are 108 logical interfaces within the kernel (e.g. getassocbyspi(), 109 getassocbysocket()) that security protocols inside the kernel (e.g. 110 IP Security, aka IPsec) use to request and obtain Security 111 Associations. 113 In the case of IPsec, if by policy a particular outbound packet 114 needs processing, then the IPsec implementation requests an 115 appropriate Security Association from the Key Engine via the kernel- 116 internal interface. If the Key Engine has an appropriate SA, it 117 allocates the SA to this session (marking it as used) and returns the 118 SA to the IPsec implementation for use. If the Key Engine has no 119 such SA but a key management application has previously indicated 120 (via a PF_KEY SADB_REGISTER message) that it can obtain such SAs, 121 then the Key Engine requests that such an SA be created (via a PF_KEY 122 SADB_ACQUIRE message). When the key management daemon creates a new 123 SA, it places it into the Key Engine for future use. 125 +---------------+ 126 |Key Mgmt Daemon| 127 +---------------+ 128 | | 129 | | 130 | | Applications 131 ======[PF_KEY]====[PF_INET]========================== 132 | | OS Kernel 134 +------------+ +-----------------+ 135 | Key Engine | | TCP/IP, | 136 | or SADB |---| including IPsec | 137 +------------+ | | 138 +-----------------+ 139 | 140 +-----------+ 141 | Network | 142 | Interface | 143 +-----------+ 145 Figure 1: Relationship of Key Mgmt to PF_KEY 147 For performance reasons, some security protocols (e.g. IP Security) 148 are usually implemented inside the operating system kernel. Other 149 security protocols (e.g. OSPFv2 Cryptographic Authentication) are 150 implemented in trusted privileged applications outside the kernel. 151 Figure 2 shows a trusted, privileged routing daemon using PF_INET to 152 communicate routing information with a remote routing daemon and 153 using PF_KEY to request, obtain, and delete Security Associations 154 used with a routing protocol. 156 +---------------+ 157 |Routing Daemon| 158 +---------------+ 159 | | 160 | | 161 | | Applications 162 ======[PF_KEY]====[PF_INET]========================== 163 | | OS Kernel 164 +------------+ +---------+ 165 | Key Engine | | TCP/IP | 166 | or SADB |---| | 167 +------------+ +---------+ 168 | 169 +-----------+ 170 | Network | 171 | Interface | 172 +-----------+ 174 Figure 2: Relationship of Trusted Application to PF_KEY 176 When a trusted privileged application is using the Key Engine but 177 implements the security protocol within itself, then operation varies 178 slightly. In this case, the application needing an SA sends a PF_KEY 179 SADB_ACQUIRE message down to the Key Engine, which then either 180 returns an error or sends a similar SADB_ACQUIRE message up to one or 181 more key management applications capable of creating such SAs. As 182 before, the key management daemon stores the SA into the Key Engine. 183 Then, the trusted privileged application uses a SADB_GET message to 184 obtain the SA from the Key Engine. 186 In some implementations, policy may be implemented in user-space, 187 even though the actually cryptographic processing takes place in the 188 kernel. Such policy communication between the kernel mechanisms and 189 the user-space policy MAY be implemented by PF_KEY extensions, or 190 other such mechanism. This document will not specify such 191 extensions. 193 Untrusted clients, for example a user's web browser or telnet 194 client, do not need to use PF_KEY. Mechanisms not specified here are 195 used by such untrusted client applications to request security 196 services (e.g. IPsec) from an operating system. For security 197 reasons, only trusted, privileged applications are permitted to open 198 a PF_KEY socket. 200 1.3 PF_KEY SOCKET DEFINITION 202 The PF_KEY protocol family (PF_KEY) symbol is defined in 203 in the same manner that other protocol families are 204 defined. PF_KEY does not use any socket addresses. Applications 205 using PF_KEY MUST NOT depend on the availability of a symbol named 206 AF_KEY, but kernel implementations are encouraged to define that 207 symbol for completeness. 209 The key socket is created as follows: 211 #include 213 int s; 214 s = socket(PF_KEY, SOCK_RAW, 0) 216 The PF_KEY domain currently supports only the SOCK_RAW socket type. 217 The protocol field MUST be set to 0. Only a trusted, privileged 218 process can create a PF_KEY socket. On conventional UNIX systems, a 219 privileged process is a process with an effective userid of zero. On 220 non-MLS proprietary operating systems, the notion of a "privileged 221 process" is implementation-defined. On Compartmented Mode 222 Workstations (CMWs) or other systems that claim to provide Multi- 223 Level Security (MLS), a process MUST have the "key management 224 privilege" in order to open a PF_KEY socket[DIA]. MLS systems that 225 don't currently have such a specific privilege MUST add that special 226 privilege and enforce it with PF_KEY in order to comply and conform 227 with this specification. Some systems, most notably some popular 228 personal computers, do not have the concept of a privileged user. 229 These systems SHOULD take steps to restrict the programs allowed to 230 access the PF_KEY API. 232 1.4 OVERVIEW OF PF_KEY MESSAGING BEHAVIOR 234 A process interacts with the key engine by sending and receiving 235 messages using the PF_KEY socket. Security association information 236 can be inserted into and retrieved from the kernel's security 237 association table using a set of predefined messages. In the normal 238 case, all messages sent to the kernel are returned to all open PF_KEY 239 sockets, including the sender. A process can disable this looping 240 back of messages it generates by disabling the SO_USELOOPBACK option 241 using the setsockopt(2) call. A PF_KEY socket listener, which by 242 default receives all replies may disable message reception by 243 terminating socket input with the shutdown(2) call. PF_KEY message 244 delivery is not guaranteed, especially in cases where kernel or 245 socket buffers are exhausted and messages are dropped. 247 Some messages are generated by the operating system to indicate 248 that actions need to be taken, and are not necessarily in response to 249 any message sent down by the user. Such messages are not received by 250 all PF_KEY sockets, but by sockets which have indicated that kernel- 251 originated messages are to be received. These messages are special 252 because of the expected frequency at which they will occur. Also, an 253 implementation may further wish to restrict return message from the 254 kernel, in cases where not all PF_KEY sockets are in the same trust 255 domain. 257 ******* 258 NOTE: SECTIONS LIKE THIS, INSIDE ******* ARE META-COMMENTS AND OPEN 259 ISSUES THAT NEED CONTEXT TO BE CLEAR. 261 [RJA: Clarifying text on security restrictions is needed here, IMHO.] 262 ******* 264 1.5 COMMON PF_KEY OPERATIONS 266 There are two basic ways to add a new Security Association into the 267 kernel. The simplest is to send a single SADB_ADD message, 268 containing all of the SA information, from the application into the 269 kernel's Key Engine. This approach works particularly well with 270 manual key management. 272 The second approach to add a new Security Association into the 273 kernel is for the application to first request an SPI value from the 274 kernel using the SADB_GETSPI message and then send a SADB_UPDATE 275 message with the complete Security Association data. This second 276 approach works well with key management daemons when the SPI values 277 need to be known before the entire Security Association data is known 278 (e.g. so the SPI value can be indicated to the remote end of the key 279 management session). 281 An individual Security Association can be deleted using the 282 SADB_DELETE message. Categories of SAs or the entire kernel SA table 283 can be deleted using the SADB_FLUSH message. 285 The SADB_GET message is used by a trusted application-layer process 286 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 287 SA) from the kernel's Key Engine. 289 The kernel or an application-layer can use the SADB_ACQUIRE message 290 to request that a Security Association be created by some 291 application-layer key management process that has registered with the 292 kernel via a SADB_REGISTER message. This ACQUIRE message will have a 293 sequence number associated with it. This sequence number MUST be 294 used by followup SADB_GETSPI and SADB_UPDATE messages, in order to 295 keep track of which request gets its keying material. The sequence 296 number (described below) is analogous to a transaction ID in a remote 297 procedure call. 299 The SADB_EXPIRE message is sent from the kernel to key management 300 applications when the "soft lifetime" or "hard lifetime" of a 301 Security Association has expired. Key management applications should 302 use receipt of a SADB_EXPIRE message as a hint to negotiate a 303 replacement SA so the replacement SA will be ready and in the kernel 304 before it is needed. 306 A SADB_DUMP message is also defined, but this is primarily intended 307 for PF_KEY implementer debugging and is not used in ordinary 308 operation of PF_KEY. 310 1.6 DIFFERENCES BETWEEN PF_KEY AND THE PF_ROUTE ROUTING SOCKET 312 The following bullets are points of difference between the routing 313 socket and PF_KEY. Programmers who are used to the routing socket 314 semantics will find some subtle differences in PF_KEY. 316 * The write() call doesn't return the PF_KEY error number, only the 317 return message has the PF_KEY error number in cases of malformed fields. 318 This means that if SO_USELOOPBACK is disabled, error checking is hard. 320 * The entire message isn't always reflected in the reply. An SADB_ADD is 321 a good example of this. 323 * The PID is not set by the kernel. The process that originates the message 324 MUST set the sadb_msg_pid to its own PID. If the kernel originates a 325 message, it MUST set the sadb_msg_pid to 0. 327 2. PF_KEY MESSAGE FORMAT 329 PF_KEY messages consist of a base header followed by additional 330 data fields, some of which may be optional. The format of the 331 additional data is dependent on the type of message. 333 PF_KEY messages currently do not mandate any specific ordering for 334 non-network multi-octet fields. Fields that may go across the wire 335 (e.g. SPI) MUST be in network byte order. 337 2.1 BASE MESSAGE HEADER FORMAT 339 PF_KEY messages consist of the base message header followed by 340 security association specific data whose types and lengths are 341 specified by a generic type-length encoding. 343 This base header is shown below, using POSIX types. The fields are 344 arranged primarily for alignment, and where possible, for reasons of 345 clarity. 347 struct sadb_msg_hdr { 348 /* Basic hdr stuff */ 349 uint8_t sadb_version; /* 2 */ 350 uint8_t sadb_msg_type; 351 uint8_t sadb_msg_errno; 352 uint8_t sadb_sa_type; 353 uint16_t sadb_msg_len; /* In 32-bit words, incl. */ 354 uint16_t sadb_sa_assocopts; 355 uint32_t sadb_msg_seq; 356 uint32_t sadb_msg_pid; 358 /* Basic SA stuff */ 359 uint32_t sadb_sa_spi; 360 uint8_t sadb_sa_replay_window_len; 361 uint8_t sadb_sa_state; 362 uint8_t sadb_sa_encrypt; /* Or uint16_t */ 363 uint8_t sadb_sa_auth; /* sadb_sa_transform */ 364 }; 366 sadb_version The version field of this PF_KEY message. Set to 2. 368 sadb_msg_type Identifies the type of message. The valid message types 369 are described later in this document. 371 sadb_msg_errno Should be set to zero by the sender. The replier stores 372 the error code in this field if an error has occured. 374 ******* 375 [C. Metz: In some cases, it may be useful for the user-space 376 program to send errnos. In the case of proxying key 377 management, a EHOSTUNREACH may tell the kernel that there 378 is no peer for this server. For that matter such errnos 379 could work in the cases of no peer KMd being present. 381 These are in the context of having received an ACQUIRE 382 message.] 383 ******* 385 sadb_sa_type indicates the type of security association (e.g. AH, 386 ESP, OSPF, etc). Valid Security Association types are 387 declared in the file . The current set of 388 Security Association types are enumerated later in this 389 document. 391 sadb_msg_len Contains the total length, in 32-bit words, of all data in 392 the PF_KEY message including the base header length and 393 additional data after the base header, if any. This length 394 includes any padding or extra space that might exist. Unless 395 otherwise stated, all other length fields are also 396 measured in 32-bit words. 398 sadb_sa_assocopts 399 Contains a bitmap of options defined for the security 400 assocation (e.g. replay protection, PFS, etc.). 401 ******* 402 [Dan McD: I may need to re-split these up into algorithm flags and 403 association flags. Some of these span both, some don't. ] 404 ******* 406 sadb_msg_seq Contains the sequence number of this message. This field, 407 along with sadb_msg_pid, SHOULD be used to uniquely identify 408 requests to a process. The sender is responsible for filling 409 in this field. This resposibility also includes matching 410 the sadb_msg_seq of a request (e.g. SADB_ACQUIRE). 412 This field is analogous to a transaction ID in a remote 413 procedure call implementation. 415 ******* 416 [Dan McD.: It may turn out that both sequence number and transaction 417 id are needed. In that case, I'll add another uint32_t.] 418 ******* 420 sadb_msg_pid Identifies the process which originated this message, or 421 which process a message is bound for. For example: If 422 process id 2112 sends a SADB_UPDATE message to the kernel, 423 the message to the kernel MUST set its process id to 2112, 424 and the SADB_UPDATE reply from the kernel will fill in this 425 fields with 2112. This field, along with sadb_msg_seq, 426 can be used to uniquely identify requests to a process. 428 It is currently believed that a 32-bit quantity will 429 hold an operating system's process ID space. If this 430 assumption is not true, then sadb_msg_pid will have to 431 be revisited. 433 ******* 434 [Dan McD.: The seq and pid fields semantics change explicitly from 435 the routing socket semantics. This better facilitates 436 asynchronous kernels, while not taking away anything from 437 synchronous kernels. ] 438 ******* 440 sadb_sa_spi Contains the Security Parameters Index value for the 441 Security Association. Although this is a 32-bit field, 442 some types of Security Association might have an SPI or 443 key identifier that is less than 32-bits long. In this 444 case, the smaller value shall be stored in the least 445 significant bits of this field and the unneeded bits 446 shall be zero. This field MUST be in network byte order. 448 ******* 449 [Dan McD: ISAKMP can negotiate an SPI that's >32-bits. I may save this 450 for v3, though.] 451 ******* 453 sadb_sa_replay_window_len 454 Specifies the size of the replay window, if not zero. If 455 zero, then no replay window is in use. 457 sadb_sa_state Is a bitmask field containing the state of the Security 458 Association. This field should be set to zero by the 459 sending process and is set to the state of the Security 460 Association when the message is received. The current 461 set of State flags are enumerated later in this 462 document. 464 ******* 465 [Dan McD: The following fields may get merged into one 16-bit 466 sadb_sa_transform field, depending.] 467 ******* 469 sadb_sa_encrypt Identifies the encryption algorithm used for this security 470 association. This can identify that no encryption is used 471 for this association. See section 3.4 for values that can 472 be placed in this field. 474 sadb_sa_auth Identifies the authentication algorithm used for this 475 security association. This can identify that no 476 authentication is used for this association. See section 477 3.4 for values that can be placed in this field. 479 The kernel MUST check sanity in these cases. For example AH 480 with no authentication algorithm is probably an error. 482 2.3 ADDITIONAL MESSAGE FIELDS 484 The additional data following the base header consists of various 485 type-length-values fields. The first 32-bits are of a constant form: 487 struct sadb_ext_hdr { 488 uint16_t ext_hdrtype; /* 0 is reserved */ 489 uint16_t ext_len; /* In 32-bit words, inclusive */ 490 }; 492 There are currently seven types of extensions headers: Lifetime, 493 Address, Key, Identity, Sensitivity, Proposal, and Supported. There 494 SHOULD be only one instance of a extension type in a message. (e.g. 495 Base, Key, Lifetime, Key is STRONGLY discouraged). 497 All extensions MUST be implemented by a PF_KEY implementation. 499 2.3.1 LIFETIME EXTENSION 501 The Lifetime extension specifies a lifetime for this security 502 association. If no Lifetime extension is present the association 503 has an infinite lifetime. An association SHOULD have a lifetime of 504 some sort associated with it. The Lifetime extension looks like: 506 struct sadb_lifetime { 507 uint16_t life_hdrtype; /* 1 */ 508 uint16_t life_len; 509 uint8_t life_type; /* Time, bytes, packets... */ 510 uint8_t life_size; /* 2, 4, 8, 16, etc. octets */ 511 uint16_t life_reserved; /* Or quantity */ 512 /* uint64_t or uint32_t might follow. */ 513 }; 515 The life_size field is in octets, while the life_len field is in 516 32-bit words. The lifetime extension MAY be followed by a 32-bit 517 aligned quantity if the life_size field is larger than 2 octets, 518 otherwise the the lifetime itself can be stored in the 16-bit 519 life_reserved field. 521 Values for life_type are defined in the SYMBOLIC NAMES section. 523 2.3.2 ADDRESS EXTENSION 525 The Address extension specifies one or more addresses that are 526 associated with a security association. An Address extension MUST 527 be present, and MUST specify at least the source and destination 528 addresses. (The source address can be INADDR_ANY or it's IPv6 529 counterpart.) The format of an Address extension is: 531 struct sadb_address { 532 uint16_t addr_hdrtype; /* 2 */ 533 uint16_t addr_len; 534 uint8_t addr_which; /* Bitmask */ 535 uint8_t addr_reserved[3]; /* Padding */ 536 /* Followed by one or more struct sockaddr structures. */ 537 }; 539 The addr_which field contains a bitmask indicating what addresses; 540 source, destination, inner-source, inner-destination, and proxy; 541 follow. For each bit set in the addr_which field, a struct sockaddr 542 follows. The sockaddr structure MUST conform to the sockaddr 543 structure of the system implementing PF_KEY. (E.g. If the system 544 has an sa_len field, so MUST the sockaddrs in the message. If the 545 system has NO sa_len field, the sockaddrs MUST not have an sa_len 546 field.) All non-address information in the sockaddrs MUST be zeroed 547 out. 549 2.3.3 KEY EXTENSION 551 The Key extension specifies one or more keys that are associated 552 with a security association. A Key extension will not always be 553 present with messages, because of security risks. The format of a 554 Key extension is: 556 struct sadb_keyblk { 557 uint16_t kb_hdrtype; /* 3 */ 558 uint16_t kb_len; 559 uint8_t kb_num_auth; /* # of auth. keys/ivs */ 560 uint8_t kb_num_encrypt; /* # of encrypt. keys/ivs */ 561 uint16_t kb_reserved; /* For 32-bit alignment */ 562 /* Followed by sadb_key */ 563 }; 565 The Key extension is followed by the appropriate number of 566 authentication or encryption keys. These keys are encoded as 567 follows: 569 struct sadb_key { 570 uint8_t key_type; /* 3DES, DES, HMAC-MD5, etc. */ 571 uint8_t key_flags; /* Right now, am I an IV? */ 572 uint16_t key_length; /* Length of key in bits */ 573 uint8_t key_key[4]; /* Actual key/iv. */ 574 /* key_key is bounded by roundup(key_length / 8) */ 575 }; 577 The length of individual keys is in bits. Each key is padded to a 578 32-bit boundary. The key bits are arranged most-sigificant to least 579 significant. For example, a 22-bit key would take up three octets, 580 with the least significant two bits not containing key material. An 581 additional octet would be used for padding to a 32-bit boundary. 583 The key_flags field indicates currently if this key is actually a 584 negotiated initialization vector. 586 2.3.4 IDENTITY EXTENSION 588 The Identity extension contains endpoint identities. If this 589 extension is not present, key management can assume that the 590 addresses in the Address extension are the only identities for this 591 Security Association. The Identity extension looks like: 593 struct sadb_id_hdr { 594 uint16_t idh_hdrtype; /* 4 */ 595 uint16_t idh_len; 596 uint32_t idh_which; /* bitmask */ 597 /* Followed by one or more sadb_certids */ 598 }; 600 The idh_which field is a bitmask, indicating if source or 601 destination certificate identities are present. Each identity is a 602 32-bit aligned quantity, specified as: 604 struct sadb_certid { 605 uint8_t certid_type; 606 uint8_t certid_reserved[3]; /* May be used */ 607 /* certid_reserved is unbounded */ 608 }; 610 Following each sadb_certid is 32-bit aligned data. Sometimes it is 611 in the best interest to use the certid_reserved field for some of 612 that data. The type of data can either be nothing (if the specified 613 identity is the address), a null-terminated C string (for fully- 614 qualified domain names, or mailbox identities), and address/mask 615 pair (for address ranges), or a port-pair/protocol tuple, used in 616 concert with the addresses. See the ILLUSTRATION OF MESSAGE LAYOUT 617 section for details. 619 2.3.5 SENSITIVITY EXTENSION 621 The Sensitiviy extension contains security labelling information 622 for a security association. If this extension is not present, no 623 sensitivity-related data can be obtained from this security 624 association. If this extension is present, then the need for 625 explicit security labelling on the packet is obviated. 627 struct sadb_sens_hdr { 628 uint16_t sens_hdrtype; /* 5 */ 629 uint16_t sens_len; 630 uint32_t sens_dpd; 631 uint8_t sens_sens_level; 632 uint8_t sens_sens_bitmap_len; /* bytes */ 633 uint8_t sens_integ_level; 634 uint8_t sens_integ_bitmap_len; /* bytes */ 635 /* 636 * followed by two uint8_t arrays 637 * uint8_t sens_bitmap[sens_bitmap_len]; 638 * uint8_t integ_bitmap[integ_bitmap_len]; 639 */ 640 }; 642 The lengths of the bitmaps are in bytes. Following this field are 643 the bitmaps. Only at the end of the second bitmap does padding to 644 32-bits occur. The sens_dpd describes the protection domain, which 645 allows interpretation of the levels and compartment bitmaps. 647 2.3.6 PROPOSAL EXTENSION 649 The Proposal extension contains a "proposed situation" of 650 algorithm preferences. It looks like: 652 struct sadb_prop_hdr { 653 uint16_t proph_hdrtype; /* 6 */ 654 uint16_t proph_len; 655 uint8_t proph_num_auth; /* # of ordered auth algs */ 656 uint8_t proph_num_encrypt; /* # of ordered encrypt algs */ 657 uint8_t proph_algs[2]; 658 /* proph_algs is bounded by num auth + num encrypt */ 659 }; 661 ******* 662 [Dan McD.: As with the base header, this may become a list of 663 transforms.] 665 [C. Metz: An argument for the transform side of this is if I want to 666 express: 668 My preferences are: 670 1.) 3DES with HMAC-MD5 auth & replay 671 2.) 3DES with replay 672 ... 673 ] 674 ******* 675 Following the header are a list of one-octet algorithm identifiers, first 676 authentication algorithms in preferential order, then encryption algorithms 677 in preferential order. 679 2.3.7 SUPPORTED ALGORITHMS EXTENSION 681 The Supported Algorithms extension contains a list of all 682 algorithms supported by the kernel. This is useful for key 683 management, as it knows what it can negotiate. Its format is: 685 struct alg_hdr { 686 uint16_t algh_hdrtype; /* 7 */ 687 uint16_t algh_len; 688 uint8_t algh_num_auth; /* # of auth algs supported */ 689 uint8_t algh_num_encrypt; /* # of encrypt algs */ 690 uint16_t algh_reserved; 691 /* Followed by one or more alg_desc */ 692 }; 694 It is followed by one or more algorithm descriptors. An algorithm 695 descriptor looks like: 697 struct alg_desc { 698 uint8_t algd_type; /* Algorithm type. */ 699 uint8_t algd_flags; /* Algorithm properties (IV, etc.) */ 700 uint8_t algd_ivlen; /* Algorithm IV len, if needed */ 701 uint8_t algd_numkeys; /* Number of keys needed */ 702 uint16_t algd_minlen; /* Minimum key length */ 703 uint16_t algd_maxlen; /* Maximum key length */ 704 }; 706 32-bit alignment is guaranteed by the fields automatically. The 707 flags indicate properties such as an initialization vector. The 708 minlen and maxlen are key lengths in bits. 710 2.3.8 SPI RANGE EXTENSION 712 One PF_KEY message, SADB_GETSPI, might need a range of acceptable 713 SPI values. This extension performs such a function. 715 struct sadb_spirange { 716 uint16_t spir_type; /* 8 */ 717 uint16_t spir_len; 718 uint32_t spi_low; 719 uint32_t spi_hi; 720 } 722 2.4 ILLUSTRATION OF MESSAGE LAYOUT 724 The following shows how the octets are layed out in a PF_KEY message. 725 Optional fields are indicated as such. 727 The base header is as follows: 729 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 730 +---------------+---------------+---------------+---------------+ 731 | sadb_version | sadb_msg_type | sadb_msg_errno| sadb_sa_type | 732 +---------------+---------------+---------------+---------------+ 733 | sadb_msg_len | sadb_sa_assocopts | 734 +---------------+---------------+---------------+---------------+ 735 | sadb_msg_seq | 736 +---------------+---------------+---------------+---------------+ 737 | sadb_msg_pid (NOTE: Assuming pid_t is 32 bits) | 738 +---------------+---------------+---------------+---------------+ 739 | sadb_sa_spi | 740 +---------------+---------------+---------------+---------------+ 741 | ...replay... | sadb_sa_state |sadb_sa_encrypt| sadb_sa_auth | 742 +---------------+---------------+---------------+---------------+ 744 The base header may be followed by one or more of the following 745 extension fields, depending on the values of various base header 746 fields. The following fields are ordered such that if they appear, 747 they SHOULD appear in the order presented below. 749 An extension field MUST not be repeated. If there is a situation 750 where an extension MUST be repeated, it should be brought to the 751 attention of the authors. 753 The Lifetime extension 755 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 756 +---------------+---------------+---------------+---------------+ 757 | life_hdrtype (1) | life_len | 758 +---------------+---------------+---------------+---------------+ 759 | life_type | life_size | life_reserved | 760 +---------------+---------------+---------------+---------------+ 761 > lifetime_value, if 32-bit or 64-bit quantity < 762 +---------------+---------------+---------------+---------------+ 764 The Address extension 766 +---------------+---------------+---------------+---------------+ 767 | addr_hdrtype (2) | addr_len | 768 +---------------+---------------+---------------+---------------+ 769 | addr_which | addr_reserved | 770 +---------------+---------------+---------------+---------------+ 771 > 32-bit aligned struct sockaddr(s) < 772 +---------------+---------------+---------------+---------------+ 774 The Key extension 776 +---------------+---------------+---------------+---------------+ 777 | kbh_hdrtype (3) | kbh_len | 778 +---------------+---------------+---------------+---------------+ 779 | kbh_num_auth |kbh_num_encrypt| kbh_reserved | 780 +---------------+---------------+---------------+---------------+ 781 > One or more actual keys, encoded as follows... < 782 +---------------+---------------+---------------+---------------+ 784 An actual key 786 +---------------+---------------+---------------+---------------+ 787 | kh_type | kh_flags | kh_length | 788 +---------------+---------------+---------------+---------------+ 789 > A key, padded to 32-bits, most sigificant bits to least. < 790 +---------------+---------------+---------------+---------------+ 792 The Identity extension 794 +---------------+---------------+---------------+---------------+ 795 | idh_hdrtype (4) | idh_len | 796 +---------------+---------------+---------------+---------------+ 797 | idh_which | 798 +---------------+---------------+---------------+---------------+ 799 > One or more certificate identities of the following forms < 800 +---------------+---------------+---------------+---------------+ 802 IPv6 address or IPv4 address should look in the previous Address 803 extension for actual values. 805 +---------------+---------------+---------------+---------------+ 806 | certid_type | certid_reserved | 807 +---------------+---------------+---------------+---------------+ 809 NOTE that certid_reserved gets filled with useful fields for some 810 identity types. 812 An IPv6 or IPv4 address range 814 +---------------+---------------+---------------+---------------+ 815 | certid_type |pref_len (bits)| certid_reserved | 816 +---------------+---------------+---------------+---------------+ 817 > 16-bytes of IPv6 or 4-bytes of IPv4 address prefix < 818 +---------------+---------------+---------------+---------------+ 820 A Fully-qualified domain name, or a mailbox ID. 822 +---------------+---------------+---------------+---------------+ 823 | certid_type | A null-terminated C-string | 824 +---------------+---------------+---------------+---------------+ 825 > which MUST be padded out for 32-bit alignment < 826 +---------------+---------------+---------------+---------------+ 828 A connection ID, which uses address plus port/protocol information. 830 +---------------+---------------+---------------+---------------+ 831 | certid_type | protocol_id | certid_reserved | 832 +---------------+---------------+---------------+---------------+ 833 | source_port | destination_port | 834 +---------------+---------------+---------------+---------------+ 836 The Sensitivity extension 838 +---------------+---------------+---------------+---------------+ 839 | sens_hdrtype (5) | sens_len | 840 +---------------+---------------+---------------+---------------+ 841 | sens_dpd | 842 +---------------+---------------+---------------+---------------+ 843 |sens_sens_level| ...bitmap_len |sens_integ_lev | ...bitmap_len | 844 +---------------+---------------+---------------+---------------+ 845 > The sensitivity bitmap, followed immediately by the integrity < 846 < bitmap, padded to a 32-bit quantity. > 847 +---------------+---------------+---------------+---------------+ 849 The Proposal extension 850 +---------------+---------------+---------------+---------------+ 851 | proph_hdrtype (6) | proph_len | 852 +---------------+---------------+---------------+---------------+ 853 | proph_num_auth|proph_num_encr.| 1st auth alg | 2nd auth alg | 854 +---------------+---------------+---------------+---------------+ 855 > Nth auth alg... then 1st encrypt alg, etc. Padded for 32-bits< 856 +---------------+---------------+---------------+---------------+ 858 The Supported Algorithms extension 860 +---------------+---------------+---------------+---------------+ 861 | algh_hdrtype (7) | algh_len | 862 +---------------+---------------+---------------+---------------+ 863 | algh_num_auth |algh_num_encr. | algh_reserved | 864 +---------------+---------------+---------------+---------------+ 866 Followed by one or more Algorithm Descriptors 868 +---------------+---------------+---------------+---------------+ 869 | algd_type | algd_flags | algd_ivlen | algd_numkeys | 870 +---------------+---------------+---------------+---------------+ 871 | algd_minlen | algd_maxlen | 872 +---------------+---------------+---------------+---------------+ 874 The SPI Range extension 876 +---------------+---------------+---------------+---------------+ 877 | spir_hdrtype (8) | spir_len | 878 +---------------+---------------+---------------+---------------+ 879 | spir_hi | 880 +---------------+---------------+---------------+---------------+ 881 | spir_low | 882 +---------------+---------------+---------------+---------------+ 884 3. SYMBOLIC NAMES 886 This section defines various symbols used with PF_KEY and the 887 semantics associated with each symbol. Applications SHOULD use the 888 symbolic name in order to be maximally portable. The numeric 889 definitions shown are for illustrative purposes, unless explicitly 890 stated otherwise. The numeric definition might vary on other 891 systems. The symbolic name MUST be kept the same for all conforming 892 implementations. 894 ******* 895 [Dan McD: Should I give a prefix, like SADB_X_*, so that 896 implementation-specific hacks (i.e. policy) can fit in?] 897 ******* 899 3.1 MESSAGE TYPES 901 The following message types are used with PF_KEY. These are 902 defined in the file . 904 #define SADB_GETSPI 1 905 #define SADB_UPDATE 2 906 #define SADB_ADD 3 907 #define SADB_DELETE 4 908 #define SADB_GET 5 909 #define SADB_ACQUIRE 6 910 #define SADB_REGISTER 7 911 #define SADB_EXPIRE 8 912 #define SADB_FLUSH 9 914 #define SADB_DUMP 10 /* not used by normal applications */ 916 Each message has a behavior. A behavior is defined as where the 917 initial message travels (e.g. user to kernel), and what subsequent 918 actions are expected to take place. Contents of messages are 919 illustrated as: 921 923 In the case of an error, only the base header is returned. 925 3.1.1 SADB_GETSPI Message 927 The SADB_GETSPI message allows a process to obtain a unique SPI value for 928 given security association type, source address, and destination address. 929 This message followed by a SADB_UPDATE is one way to create a security 930 association (SADB_ADD is the other method). The process specifies the type 931 in the base header, the source and destination address in address extension, 932 and, if proxy key management is in use, the internal sockaddrs or the proxy 933 sockaddr are also included in the address extension. If the SADB_GETSPI 934 message is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq 935 MUST be the same as the SADB_ACQUIRE message. The application may also 936 specifiy the SPI. This is done by either setting the sadb_sa_spi field to a 937 single SPI, or having the kernel select within a range of SPI values by using 938 the SPI range extension. This use of the lifetime extension to specify SPI 939 ranges is detailed later. Permitting range specification is important 940 because the kernel can allocate an SPI value based on what it knows about SPI 941 values already in use. The kernel returns the same message with the 942 allocated SPI value stored in the spi field. An update message can later be 943 used to add an entry with the requested SPI value. 945 The message behavior of the SADB_GETSPI message is: 947 Send a SADB_GETSPI message from a user process to the kernel. 949 951 The kernel returns the SADB_GETSPI message to all listening 952 processes. 954 956 Errors: 958 EINVAL Various message improprieties, including SPI ranges that 959 are malformed. 960 ENOBUFS No buffer space is available to process request. 961 EEXIST Requested SPI or SPI range is not available/already used. 963 3.1.2 SADB_UPDATE Message 965 The SADB_UPDATE message allows a process to update the information 966 in an existing Security Association. Since SADB_GETSPI does not 967 allow setting of certain parameters, this message is needed to fully 968 form the larval security association created with SADB_GETSPI. The 969 format of the update message is a base header, followed by the 970 relevant extensions. If the keying material, lifetimes, compartment 971 bitmaps, or certificate identities need to be updated, these 972 extensions should be included. The kernel searches for the security 973 association with the same type, spi, source address and destination 974 address specified in the message and updates the Security Association 975 information using the content of the SADB_UPDATE message. 977 The kernel SHOULD perform sanity checking on various technical 978 parameters passed in as part of the SADB_UPDATE message. One example 979 is DES key parity bit checking. Other examples include key length 980 checking, and checks for keys known to be weak for the specified 981 algorithm. 983 The kernel SHOULD NOT allow SADB_UPDATE to succeed unless the 984 message is issued from the same socket that created the security 985 association. Such enforcement significantly reduces the chance of 986 accidental changes to an in-use security associations. Malicious 987 trusted parties could still issue a SADB_FLUSH or SADB_DELETE 988 message, but deletion of associations is more easily detected and 989 less likely to occur accidentally than an erroneous SADB_UPDATE. 991 The message behavior of the SADB_UPDATE message is: 993 Send a SADB_UPDATE message from a user process to the kernel. 995 997 The kernel returns the SADB_UPDATE message to all listening 998 processes. 1000 1002 The keying material is not returned on the message from the kernel 1003 to listening sockets because listeners might not have the privileges 1004 to see such keying material. 1006 Errors: 1007 ESRCH The security association to be updated was not found. 1008 EINVAL Various message improprieties, including sanity check 1009 failures on keys. 1010 EACCES Insufficient privilege to update entry. Socket issuing 1011 the SADB_UPDATE is not creator of the entry to be updated. 1013 3.1.3 SADB_ADD Message 1015 The SADB_ADD message is nearly identical to the SADB_UPDATE 1016 message, except that it does not require a previous call to 1017 SADB_GETSPI. The SADB_ADD message is optimal for manual keying 1018 applications, and other strategies where the uniqueness of the SPI is 1019 known immediately. 1021 An SADB_ADD message is also used when negotiation is finished, and 1022 the second of a pair of associations is added. The SPI for this 1023 association was determined by the peer machine. It MAY be useful to 1024 set the sadb_msg_seq to that of a kernel-generated SADB_ACQUIRE so 1025 that both associations in a pair are bound to the same ACQUIRE 1026 request. 1028 The message behavior of the SADB_ADD message is: 1030 Send a SADB_ADD message from a user process to the kernel. 1032 1034 The kernel returns the SADB_ADD message to all listening 1035 processes. 1037 1039 The keying material is not returned on the message from the kernel to 1040 listening sockets because listeners may not have the privileges to see 1041 such keying material. 1043 Errors: 1045 EEXIST The security association that was to be added already 1046 exists. 1047 EINVAL Various message improprieties, including sanity check 1048 failures on keys. 1050 3.1.4 SADB_DELETE Message 1052 The SADB_DELETE message causes the kernel to delete a Security 1053 Association from the key table. The delete message consists of the 1054 base header followed by the source sockaddr and the destination 1055 sockaddr in the address extension. The kernel deletes the security 1056 association matching the type, spi, source address, and destination 1057 address in the message. 1059 There are two message behaviors for SADB_DELETE. The first is a 1060 user- originated deletion 1062 Send a SADB_DELETE message from a user process to the kernel. 1064 1066 The kernel returns the SADB_DELETE message to all listening 1067 processes. 1069 1071 The second behavior is in the case of a hard-limit lifetime 1072 expiration. 1074 The kernel sends a SADB_DELETE message to all listening 1075 processes when a security association times out. 1077 1079 Errors: 1080 ESRCH The security association to be deleted was not found. 1082 3.1.5 SADB_GET Message 1084 The SADB_GET message allows a process to retrieve a copy of a 1085 Security Association from the kernel's key table. The get message 1086 consists of the base header follows by the relevant extension fields. 1087 The Security Association matching the type, spi, source address, and 1088 destination address is returned. The K_USED flag is set inside the 1089 Key Engine for the returned Security Association. 1091 The message behavior of the SADB_GET message is: 1093 Send a SADB_GET message from a user process to the kernel. 1095 1097 The kernel returns the SADB_GET message to the socket that sent 1098 the SADB_GET message. 1100 1102 Errors: 1103 ESRCH The sought security association was not found. 1105 3.1.6 SADB_ACQUIRE Message 1107 The SADB_ACQUIRE message is typically sent only by the kernel to 1108 key socket listeners who have registered their key socket (see 1109 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 1110 application-level consumers of security associations (such as an 1111 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 1112 message is a base header along with an address extension, possibly a 1113 certificate identity extension, and if more than one algorithm and 1114 options is acceptable, a proposal extension. The proposed situation 1115 contains a list of desirable algorithms that can be used if the 1116 algorithms in the base header are not available. The values for the 1117 fields in the base header and in the security association data which 1118 follows the base header indicate the properties of the Security 1119 Association that the listening process should attempt to acquire. If 1120 the message originates from the kernel (i.e. the sadb_msg_pid is 0), 1121 the sadb_seq number MUST be used by a subsequent SADB_GETSPI message 1122 to bind a security association to the request. This avoids the race 1123 condition of two TCP connections between two IP hosts that each 1124 require unique associations, and having one steal another's security 1125 association. The sadb_errno and sadb_state fields should be ignored 1126 by the listening process. 1128 The SADB_ACQUIRE message is typically triggered by an outbound 1129 packet that needs security but for which there is no applicable 1130 Security Association existing in the key table. If the packet can be 1131 sufficiently protected by more than one algorithm or combination of 1132 options, the SADB_ACQUIRE message MUST order the preference of 1133 possibilities by placing the most preferred algorithm in the base 1134 header, and the subsequent ones in the proposed_situation field in 1135 order of preference. 1137 There are two messaging behaviors for SADB_ACQUIRE. The first is 1138 where the kernel needs a security association (e.g. for IPsec). 1140 The kernel sends a SADB_ACQUIRE message to registered sockets. 1142 1144 The second is where an application-layer consumer of security 1145 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 1146 association. 1148 Send a SADB_ACQUIRE message from a user process to the kernel. 1150 1152 The kernel returns a SADB_ACQUIRE message to registered sockets. 1154 1156 The user-level consumer waits for a SADB_UPDATE or SADB_ADD message 1157 for its particular type, and then can use that association by using 1158 SADB_GET messages. 1160 Errors: 1161 EINVAL Invalid acquire request. 1162 EPROTONOSUPPORT No KM application has registered with the Key 1163 Engine as being able to obtain the requested SA type, so 1164 the requested SA cannot be acquired. 1166 3.1.7 SADB_REGISTER Message 1168 The SADB_REGISTER message allows an application to register its key 1169 socket as able to acquire new security associations for the kernel. 1170 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 1171 the type of security association specified in sadb_sa_type. The 1172 application specifies the type of security association that it can 1173 acquire for the kernel in the type field of its register message. If 1174 an application can acquire multiple types of security association, it 1175 MUST register each type in a separate message. Only the base header 1176 is needed for the register message. For portability reasons, key 1177 management applications MAY register for a type not known to the 1178 kernel. 1180 The reply of the SADB_REGISTER message contains a supported 1181 algorithm extension. That field contains an array of supported 1182 algorithm, one per octet. This allows key management applications to 1183 know what algorithm are supported by the kernel. 1185 In an enviroment where algorithms can be dynamically loaded and 1186 unloaded, an asyncryonous SADB_REGISTER reply MAY be generated. The 1187 list of supported algorithms MUST be a complete list, so the 1188 application can make note of omissions or additions. 1190 The messaging behavior of the SADB_REGISTER message is: 1192 Send a SADB_REGISTER message from a user process to the kernel. 1194 1196 The kernel returns a SADB_REGISTER message, with algorithm types 1197 supported by the kernel being indicated in the supported algorithms 1198 field. 1200 NOTE: This message may arrive asynchronously due to an algorithm 1201 being loaded or unloaded into a dynamically linked kernel. 1203 1205 3.1.8 SADB_EXPIRE Message 1206 The operating system kernel is responsible for tracking SA 1207 expirations for security protocols that are implemented inside the 1208 kernel. If the soft limit of a Security Association has expired for 1209 a security protocol implemented inside the kernel, then the kernel 1210 MUST issue an SADB_EXPIRE message to all key socket listeners. A 1211 user application is responsible for tracking SA expirations for 1212 security protocols (e.g. OSPF Authentication) that are implemented 1213 inside that user application. If the soft limit of a Security 1214 Association has expired, the user application SHOULD issue a 1215 SADB_EXPIRE message. Regardless of where the security protocol is 1216 implemented, if both the soft limit and the hard limit expire at the 1217 same time, both SADB_DELETE and SADB_EXPIRE messages MUST be sent. 1219 The base header will contain the security association information 1220 followed by the source sockaddr, destination sockaddr, (and, if 1221 present, internal sockaddr,) (and, if present, one or both 1222 compartment bitmaps). 1224 The messaging behavior of the SADB_EXPIRE message is: 1226 The kernel sends a SADB_EXPIRE message when the soft limit of a 1227 security association has been expired. 1229 1231 ERRORS: 1232 EINVAL Message Invalid for some reason. 1233 EPROTONOSUPPORT ??? 1235 3.1.9 SADB_FLUSH Message 1237 The SADB_FLUSH message causes the kernel to delete all entries in 1238 its key table for a certain sadb_sa_type. Only the base header is 1239 required for a flush message. If sadb_sa_type is filled in with a 1240 specific value, only associations of that type are deleted. If it is 1241 filled in with SEC_TYPE_NONE, ALL associations are deleted. 1243 The messaging behavior for SADB_FLUSH is: 1245 Send a SADB_FLUSH message from a user process to the kernel. 1247 1249 The kernel will return a SADB_FLUSH message to all listening 1250 sockets. 1252 1254 The reply message happens only after the actual flushing 1255 of security associations has been attempted. 1257 3.1.10 SADB_DUMP Message 1259 The SADB_DUMP message causes the kernel to dump the operating 1260 system's entire Key Table to the requesting key socket. As in 1261 SADB_FLUSH, if a sadb_sa_type value is in the message, only 1262 associations of that type will be dumped. If SEC_TYPE_NONE is 1263 specified, all associations will be used. Each Security Association 1264 is returned in its own SADB_DUMP message. A SADB_DUMP message with a 1265 sadb_seq field of zero indicates the end of the dump transaction. 1266 Unlike other key messages, the dump message is returned only to the 1267 key socket originating the dump request because of the potentially 1268 large amount of data it can generate. The dump message is used for 1269 debugging purposes only and is not intended for production use. 1270 Support for the dump message MAY be discontinued in future versions 1271 of the key socket, hence key management applications MUST NOT depend 1272 on this message for basic operation. 1274 The messaging behavior for SADB_DUMP is: 1276 Send a SADB_DUMP message from a user process to the kernel. 1278 1280 Several SADB_DUMP messages will return from the kernel to the 1281 sending socket. 1283 1285 3.2 SECURITY ASSOCIATION STATE 1286 The Security Association's state is a bitmask field. The related 1287 symbolic definitions below should be used in order that applications 1288 will be maximally portable: 1290 #define SA_USED 0x01 /* SA used/not used */ 1291 #define SA_UNIQUE 0x02 /* SA unique/reusable */ 1292 #define SA_LARVAL 0x04 /* SPI assigned, but SA incomplete */ 1293 #define SA_ZOMBIE 0x08 /* SA expired but still useable */ 1294 #define SA_DEAD 0x10 /* SA marked for deletion */ 1295 #define SA_INBOUND 0x20 /* SA for packets destined here */ 1296 #define SA_OUTBOUND 0x40 /* SA for packets sourced here */ 1297 #define SA_FORWARD 0x80 /* SA for packets forwarded thru */ 1299 SA_USED is set by the operating system if the Security Association 1300 has been used. Otherwise this flag is not set. If SADB_GET is used 1301 to read an SA from the Key Engine, the Key Engine will set SA_USED on 1302 the SA that was read via SADB_GET. 1304 SA_UNIQUE is set by the operating system if the Security 1305 Association has been allocated uniquely to a single user (e.g. a 1306 particular network socket). If this is not set, then the Security 1307 Association is considered sharable. 1309 SA_LARVAL indicates that the operating system has assigned this SPI 1310 value but that there is no complete Security Association yet stored 1311 in the kernel. 1313 SA_ZOMBIE indicates a Security Association that has expired but is 1314 still useable until a replacement Security Association is added. 1315 This is primarily used with OSPFv2 and RIPv2 cryptographic 1316 authentication. 1318 SA_DEAD indicates a Security Association that exists but is marked 1319 for deletion. 1321 SA_INBOUND is set for an inbound Security Association and 1322 SA_OUTBOUND is set for an outbound Security Association. SA_FORWARD 1323 is used for a Security Association used only for packets originating 1324 elsewhere and destined elsewhere that have security processing on 1325 this node. All Security Associations used with PF_KEY are 1326 unidirectional. 1328 ******* 1329 [Dan McD.: Why SA_FORWARD? Isn't SA_OUTBOUND sufficient? I may 1330 implement forwarding such that it's hard or impossible for 1331 the key engine/SADB to tell the difference. ] 1333 ******* 1335 3.3 SECURITY ASSOCIATION TYPE 1337 This defines the type of Security Association in this message. The 1338 numeric definitions are those used in the prototype NRL 1339 implementation, but might be different on other implementations. The 1340 symbolic names are always the same, even on different 1341 implementations. Applications should use the symbolic name in order 1342 to have maximum portability across different implementations. These 1343 are defined in the file . 1345 #define SEC_TYPE_NONE 0 1347 #define SEC_TYPE_AH 1 /* RFC-1826 */ 1348 #define SEC_TYPE_ESP 2 /* RFC-1827 */ 1350 #define SEC_TYPE_RSVP 3 /* RSVP Authentication */ 1351 #define SEC_TYPE_OSPFV2 4 /* OSPFv2 Authentication */ 1352 #define SEC_TYPE_RIPV2 5 /* RIPv2 Authentication */ 1353 #define SEC_TYPE_MIPV4 6 /* Mobile IPv4 Authentication */ 1355 #define SEC_TYPE_MAX 6 1357 SEC_TYPE_NONE is defined for completeness and means no 1358 Security Association. This type is never used with PF_KEY. 1360 SEC_TYPE_AH is for the IP Authentication Header defined in 1361 [Atk95b]. SEC_TYPE_ESP is for the IP Encapsulating Security Payload 1362 defined in [Atk95c]. 1364 SEC_TYPE_RSVP is for the RSVP Integrity Object. 1366 SEC_TYPE_OSPFv2 is for OSPFv2 Cryptographic authentication, 1367 while SEC_TYPE_RIPv2 is for RIPv2 Cryptographic authentication. 1369 SEC_TYPE_MAX is never used with PF_KEY but is defined for 1370 completeness. It is always set to the highest valid numeric value. 1371 There MUST not be gaps in the numbering of security types; all 1372 numbers must be used sequentially. 1374 3.4 ALGORITHM TYPES 1376 The algorithm type is interpreted in the context of the Security 1377 Association type defined above. The numeric value might vary between 1378 implementations, but the symbolic name MUST NOT vary between 1379 implementations. Applications should use the symbolic name in order 1380 to have maximum portability to various implementations. 1382 Some of the algorithm types defined below might not be standardized 1383 or might be deprecated in the future. To obtain an assignment for a 1384 symbolic name, contact the editor. 1386 The symbols below are defined in . 1388 /* Authentication algorithms */ 1389 #define SADB_AALG_NONE 0 1391 #define SADB_AALG_MD5_HMAC 1 1392 #define SADB_AALG_SHA1_HMAC 2 1394 /* Encryption algorithms */ 1395 #define SADB_EALG_NONE 0 1397 #define SADB_EALG_DES_CBC 1 1398 #define SADB_EALG_3DES 2 1400 ******* 1401 [Dan McD.: This whole section is in anticipation of IPsec departing from 1402 a pure "transform" model. This also allows security schemes 1403 that do not have a transform model at all. ] 1404 ******* 1406 The algorithm for SADB_AALG_MD5_HMAC is defined in [OG96]. The 1407 algorithm for SADB_AALG_SHA1_HMAC is defined in [CG96]. The 1408 algorithm for SADB_EALG_DES_CBC is defined in [Hug96]. 1410 3.5 ASSOCIATION OPTIONS 1412 Security association types can have various options defined. 1413 Options are denoted by a bit setting in the "Type Options" field of 1414 the base header. The bitmasks for defined options MUST NOT vary 1415 between implementations. Bits not defined are RESERVED and MUST NOT 1416 be used. 1418 #define SA_OPTION_PFS 0x0001 /* Use Perfect Forward Secrecy */ 1419 #define SA_OPTION_REPLAY 0x0002 /* Replay Protection enabled */ 1420 The SEC_OPTION_PFS flag indicates to key management that this 1421 association should have perfect forward secrecy in its key. (In 1422 other words, the session key cannot be determined by cryptanalysis of 1423 previous keying material.) 1425 The SEC_OPTION_REPLAY specifies that replay protection should be 1426 enabled on this association. The sadb_sa_replay_window_len field 1427 will indicate the size of the replay field. 1429 3.6 EXTENSION HEADER VALUES 1431 To briefly recap the extension header values: 1433 #define SA_EXT_RESERVED 0 /* Reserved */ 1434 #define SA_EXT_LIFETIME 1 1435 #define SA_EXT_ADDRESS 2 1436 #define SA_EXT_KEY 3 1437 #define SA_EXT_IDENTITY 4 1438 #define SA_EXT_SENSITIVITY 5 1439 #define SA_EXT_PROPOSAL 6 1440 #define SA_EXT_SUPPORTED 7 1441 #define SA_EXT_SPI_RANGE 8 1443 3.7 LIFETIME EXTENSION VALUES 1445 The life_type field can contain the following values: 1447 #define SA_LIFETYPE_TIME 0 1448 #define SA_LIFETYPE_BYTES 1 1449 #define SA_LIFETYPE_PACKETS 2 1451 Each value specifies a type of association lifetime. 1453 3.8 ADDRESS EXTENSION VALUES 1455 The addr_which field is a bitmask which can indicate what sockaddrs 1456 follow, and what they represent. These bit values are: 1458 #define SADB_ADDR_SRC 0x1 1459 #define SADB_ADDR_DST 0x2 1460 #define SADB_ADDR_INNER_SRC 0x4 1461 #define SADB_ADDR_INNNER_DST 0x8 1462 #define SADB_ADDR_PROXY 0x10 1464 3.9 KEY EXTENSION VALUES 1466 These are already mentioned in the ALGORITHM TYPES section. 1468 3.10 IDENTITY EXTENSION VALUES 1470 The idh_which field is a bitmask which indicates what identities 1471 follow. 1473 #define SADB_ID_SRC 0x1 1474 #define SADB_ID_DST 0x2 1476 Each identity can have a certain type. 1478 #define SADB_IDT_IPV4_ADDR 1 1479 #define SADB_IDT_IPV6_ADDR 2 1480 #define SADB_IDT_IPV4_RANGE 3 1481 #define SADB_IDT_IPV6_RANGE 4 1482 #define SADB_IDT_FQDN 5 1483 #define SADB_IDT_USER_FQDN 6 1484 #define SADB_IDT_IPV4_CONNID 7 1485 #define SADB_IDT_IPV6_CONNID 8 1487 3.11 SENSITIVITY EXTENSION VALUES 1489 The only field currently defined in the sensitivity extension is 1490 the sens_dpd, which represents the data protection domain. The other 1491 data in the senstivity extension is based off the sens_dpd value. 1493 If the highest order bit of the DP/DOI is set to 1, then the DP/DOI 1494 is not necessarily globally unique and is from a number space set 1495 aside for private use among consenting users. 1497 If the highest order bit of the DP/DOI is set to zero, the DP/DOI 1498 is globally unique from a number space administered by the Internet 1499 Assigned Numbers Authority. In order to conserve the limited amount 1500 of globally unique DP/DOI number space, IANA will not normally permit 1501 any one organization to obtain very many DP/DOI values. The all 1502 zeros DP/DOI value is permanently reserved to mean that "no DP/DOI is 1503 in use". 1505 #define SADB_DPD_NONE 0 1506 #define SADB_DPD_DOD_GENSER 1 1507 #define SADB_DPD_DOD_SCI 2 1508 #define SADB_DPD_DOE 3 1509 #define SADB_DPD_NATO 4 1511 3.12 PROPOSAL EXTENSION VALUES 1513 These are already mentioned in the ALGORITHM TYPES section. 1515 3.12 PROPOSAL EXTENSION VALUES 1517 Values for algd_type are mentioned in the ALGORITHM TYPES section. 1518 Values for the bit vector algd_flags are as follows: 1520 #define SADB_ALGDF_NEED_IV 0x1 1522 4. FUTURE DIRECTIONS 1524 While the current specification for the Sensitivity and Integrity 1525 Labels is believed to be general enough, if a case should arise that 1526 can't work with the current specification then this might cause a 1527 change in a future version of PF_KEY. 1529 Similarly, PF_KEY might need extensions to work with other kinds of 1530 Security Associations in future. It is strongly desirable for such 1531 extensions to be made in a backwards-compatible manner should they be 1532 needed. 1534 ******* 1535 [ALL: What else belongs here ? ] 1536 ******* 1538 5. SECURITY CONSIDERATIONS 1540 This draft discusses a method for creating, reading, and deleting 1541 Security Associations from an operating system. Only trusted, 1542 privileged users and processes should be able to perform any of these 1543 operations. It is unclear whether this mechanism provides any 1544 security when used with operating systems not having the concept of a 1545 trusted, privileged user. 1547 If an unprivileged user is able to perform any of these operations, 1548 then the operating system cannot actually provide the related 1549 security services. If an adversary knows the keys and algorithms in 1550 use, then cryptography cannot provide any form of protection. 1552 This mechanism is not a panacea, but it does provide an important 1553 operating system component that can be useful in creating a secure 1554 internetwork. 1556 Users need to understand that the quality of the security provided 1557 by an implementation of this specification depends completely upon 1558 the overall security of the operating system, the correctness of the 1559 PF_KEY implementation, and upon the security and correctness of the 1560 applications that connect to PF_KEY. It is appropriate to use high 1561 assurance development techniques when implementing PF_KEY and the 1562 related security association components of the operating system. 1564 ACKNOWLEDGEMENTS 1566 The editors of this document are listed primarily in Alphabetical 1567 order. A side effect of this particular alphabetical listing is to 1568 also show the history (starting with the most recent) of text 1569 contribution to this document. Ran Atkinson also contributed much 1570 advice and wisdom toward this document. Finally, the editors would 1571 like to thank the PF_KEY reviewers list. 1573 REFERENCES 1574 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig W. Metz, 1575 and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite BSD", 1576 Proceedings of the 1996 USENIX Conference, San Diego, CA, 1577 January 1996, USENIX Association. 1579 [Atk95a] Randall J. Atkinson, IP Security Architecture, RFC-1825, 1580 August 1995. 1582 [Atk95b] Randall J. Atkinson, IP Authentication Header, RFC-1826, 1583 August 1995. 1585 [Atk95c] Randall J. Atkinson, IP Encapsulating Security Payload, RFC-1827, 1586 August 1995. 1588 [CG96] S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with Replay 1589 Prevention", Internet Draft, May 1996. 1591 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 1592 Workstation Specification", Technical Report DDS-2600-6243-87. 1594 [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay 1595 Prevention Security Transform", Internet Draft, April 1996. 1597 [OG96] Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with 1598 Replay Prevention", Internet Draft, May 1996. 1600 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for Berkeley 1601 UNIX", Proceedings of the Winter 1991 USENIX Conference, Dallas, 1602 TX, USENIX Association. 1991. pp. 93-103. 1604 DISCLAIMER 1606 The views and specification here are those of the editors and are not 1607 necessarily those of their employers. The employers have not passed 1608 judgement on the merits, if any, of this work. The editors and their 1609 employers specifically disclaim responsibility for any problems arising 1610 from correct or incorrect implementation or use of this specification. 1612 EDITOR INFORMATION 1614 Daniel L. McDonald 1615 Sun Microsystems, Inc. 1616 2550 Garcia Avenue, MS UMPK17-202 1617 Mountain View, CA 94043-1100 1618 E-mail: danmcd@eng.sun.com 1620 Craig W. Metz 1621 The Inner Net 1622 Code 1123, Box 10314 1623 Blacksburg, VA 24062-0314 1624 E-mail: cmetz@inner.net 1626 Bao G. Phan 1627 U. S. Naval Research Laboratory 1628 Code 5544 1629 4555 Overlook Ave. SW 1630 Washington, DC 20375 1631 E-mail: phan@itd.nrl.navy.mil 1633 APPENDIX A: CHANGE LOG 1635 The following changes were made between 00 and 01: 1637 * Added this change log. 1639 * Simplified TLV header syntax. 1641 * Splitting of algorithms. This may be controversial, but it allows 1642 PF_KEY to be used for more than just IPsec. It also allows policy to 1643 be placed in the KMd easier. 1645 * Added solid definitions and formats for certificate identities, multiple 1646 keys, etc. 1648 * Specified how keys are to be layed out (most-to-least bits). 1650 * Changed sequence number semantics to be like an RPC transaction ID number.