idnits 2.17.1 draft-mcdonald-pf-key-v2-05.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-16) 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. == 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 593 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 10 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The abstract seems to contain references ([Atk95c], [HM97a,HM97b], [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 131: '... - MUST...' RFC 2119 keyword, line 136: '... - SHOULD...' RFC 2119 keyword, line 143: '... - MAY...' RFC 2119 keyword, line 153: '... implement, or MUST, items MUST be ...' RFC 2119 keyword, line 167: '...PF_KEY algorithm MAY consist of more t...' (119 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 11 has weird spacing: '... Drafts are ...' == Line 15 has weird spacing: '... Drafts may b...' == Line 16 has weird spacing: '...iate to use ...' == Line 17 has weird spacing: '... Drafts as r...' == Line 20 has weird spacing: '...tor for publi...' == (588 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: 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. -- 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 (28 February 1998) is 9544 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) == Missing Reference: 'VK83' is mentioned on line 160, but not defined == Missing Reference: 'HA94' is mentioned on line 160, but not defined -- Looks like a reference, but probably isn't: '3' on line 2687 -- 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. 'Atk97' ** Obsolete normative reference: RFC 2082 (ref. 'BA97') (Obsoleted by RFC 4822) -- Possible downref: Non-RFC (?) normative reference: ref. 'Baker97' -- Possible downref: Non-RFC (?) normative reference: ref. 'Biba77' -- Possible downref: Non-RFC (?) normative reference: ref. 'BL74' -- Possible downref: Non-RFC (?) normative reference: ref. 'CG96' -- Possible downref: Non-RFC (?) normative reference: ref. 'CW87' -- Possible downref: Non-RFC (?) normative reference: ref. 'DIA' -- Possible downref: Non-RFC (?) normative reference: ref. 'DMS97' ** Downref: Normative reference to an Experimental RFC: RFC 2093 (ref. 'HM97a') ** Downref: Normative reference to an Experimental RFC: RFC 2094 (ref. 'HM97b') -- Possible downref: Non-RFC (?) normative reference: ref. 'Hug96' -- Possible downref: Non-RFC (?) normative reference: ref. 'MSST97' -- Possible downref: Non-RFC (?) normative reference: ref. 'Moy97' -- Possible downref: Non-RFC (?) normative reference: ref. 'OG96' ** Obsolete normative reference: RFC 2002 (ref. 'Perkins97') (Obsoleted by RFC 3220) -- Possible downref: Non-RFC (?) normative reference: ref. 'Piper97' -- Possible downref: Non-RFC (?) normative reference: ref. 'Skl91' Summary: 19 errors (**), 0 flaws (~~), 10 warnings (==), 19 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. L. McDonald 3 Internet Draft C. W. Metz 4 draft-mcdonald-pf-key-v2-05.txt B. G. Phan 5 28 February 1998 7 PF_KEY Key Management API, Version 2 9 Status of this Memo 11 This document is an Internet Draft. Internet Drafts are working 12 documents. 14 Internet Drafts are draft documents valid for a maximum of 6 15 months. Internet Drafts may be updated, replaced, or obsoleted by 16 other documents at any time. It is not appropriate to use Internet 17 Drafts as reference material or to cite them other than as "work in 18 progress". 20 This draft will be submitted to the RFC Editor for publication as 21 an Informational document. 23 Abstract 25 A generic key management API that can be used not only for IP 26 Security [Atk95a] [Atk95b] [Atk95c] but also for other network 27 security services is presented in this document. Version 1 of this 28 API was implemented inside 4.4-Lite BSD as part of the U. S. Naval 29 Research Laboratory's freely distributable and usable IPv6 and IPsec 30 implementation[AMPMC96]. It is documented here for the benefit of 31 others who might also adopt and use the API, thus providing increased 32 portability of key management applications (e.g. a manual keying 33 application, an ISAKMP daemon, a GKMP daemon [HM97a,HM97b], a 34 Photuris daemon, or a SKIP certificate discovery protocol daemon). 36 Table of Contents 37 1 Introduction ............................................. 4 38 1.1 Terminology .............................................. 4 39 1.2 Conceptual Model ......................................... 6 40 1.3 PF_KEY Socket Definition ................................. 8 41 1.4 Overview of PF_KEY Messaging Behavior .................... 9 42 1.5 Common PF_KEY Operations ................................. 10 43 1.6 Differences Between PF_KEY and PF_ROUTE .................. 11 44 1.7 Name Space ............................................... 11 45 1.8 On Manual Keying ..........................................12 46 2 PF_KEY Message Format .................................... 13 47 2.1 Base Message Header Format ............................... 13 48 2.2 Alignment of Headers and Extension Headers ............... 15 49 2.3 Additional Message Fields ................................ 15 50 2.3.1 Association Extension .................................... 16 51 2.3.2 Lifetime Extension ....................................... 18 52 2.3.3 Address Extension ........................................ 19 53 2.3.4 Key Extension ............................................ 20 54 2.3.5 Identity Extension ....................................... 21 55 2.3.6 Sensitivity Extension .................................... 22 56 2.3.7 Proposal Extension ....................................... 23 57 2.3.8 Supported Algorithms Extension ........................... 25 58 2.3.9 SPI Range Extension ...................................... 26 59 2.4 Illustration of Message Layout ........................... 27 60 3 Symbolic Names ........................................... 31 61 3.1 Message Types ............................................ 31 62 3.1.1 SADB_GETSPI .............................................. 33 63 3.1.2 SADB_UPDATE .............................................. 34 64 3.1.3 SADB_ADD ................................................. 35 65 3.1.4 SADB_DELETE .............................................. 36 66 3.1.5 SADB_GET ................................................. 37 67 3.1.6 SADB_ACQUIRE ............................................. 37 68 3.1.7 SADB_REGISTER ............................................ 39 69 3.1.8 SADB_EXPIRE .............................................. 39 70 3.1.9 SADB_FLUSH ............................................... 40 71 3.1.10 SADB_DUMP ................................................ 41 72 3.2 Security Association Flags ............................... 41 73 3.3 Security Association States .............................. 42 74 3.4 Security Association Types ............................... 42 75 3.5 Algorithm Types .......................................... 43 76 3.6 Extension Header Values .................................. 44 77 3.7 Identity Extension Values ................................ 44 78 3.8 Sensitivity Extension Values ............................. 45 79 3.9 Proposal Extension Values ................................ 45 80 4 Future Directions ........................................ 46 81 5 Examples ................................................. 47 82 5.1 Simple IP Security Example ............................... 47 83 5.2 Proxy IP Security Example ................................ 49 84 5.3 OSPF Security Example .................................... 51 85 5.4 Miscellaneous ............................................ 51 86 6 Security Considerations .................................. 53 87 Acknowledgments ............,............................. 54 88 References ............................................... 55 89 Disclaimer ............................................... 57 90 Authors' Addresses ....................................... 57 91 A Promiscuous Send/Receive Extension ....................... 58 92 B Passive Change Message Extension ......................... 60 93 C Sample Header File ....................................... 61 94 D Change Log ............................................... 66 96 1 Introduction 98 PF_KEY is a new socket protocol family used by trusted privileged 99 key management applications to communicate with an operating system's 100 key management internals (referred to here as the "Key Engine" or the 101 SADB). The Key Engine and its structures incorporate the required 102 security attributes for a session and are instances of the "Security 103 Association" concept described in [Atk95a]. The names PF_KEY and Key 104 Engine thus refer to more than cryptographic keys and are retained 105 for consistency with the traditional phrase, "Key Management". 107 PF_KEY is derived in part from the BSD routing socket, PF_ROUTE. 108 [Skl91] This document describes Version 2 of PF_KEY. Version 1 was 109 implemented in the first three alpha test versions of the NRL 110 IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco 111 ISAKMP/Oakley key management daemon. Version 2 extends and refines 112 this interface. Theoretically, the messages defined in this document 113 could be used in a non-socket context (e.g. between two directly 114 communicating user-level processes), but this document will not 115 discuss in detail such possibilities. 117 Security policy is deliberately omitted from this interface. PF_KEY 118 is not a mechanism for tuning systemwide security policy, nor is it 119 intended to enforce any sort of key management policy. The developers 120 of PF_KEY believed that it was important to separate security 121 mechanisms (such as PF_KEY) from security policies. This permits a 122 single mechanism to more easily support multiple policies. 124 1.1 Terminology 126 Even though this document is not intended to be an actual Internet 127 standard, the words that are used to define the significance of 128 particular features of this interface are usually capitalized. These 129 words are: 131 - MUST 133 This word or the adjective "REQUIRED" means that the item is an 134 absolute requirement of the specification. 136 - SHOULD 138 This word or the adjective "RECOMMENDED" means that there might 139 exist valid reasons in particular circumstances to ignore this item, 140 but the full implications should be understood and the case carefully 141 weighed before taking a different course. 143 - MAY 144 This word or the adjective "OPTIONAL" means that this item is truly 145 optional. One vendor might choose to include the item because a 146 particular marketplace requires it or because it enhances the 147 product, for example; another vendor may omit the same item. 149 - CONFORMANCE and COMPLIANCE 151 Conformance to this specification has the same meaning as 152 compliance to this specification. In either case, the mandatory-to- 153 implement, or MUST, items MUST be fully implemented as specified 154 here. If any mandatory item is not implemented as specified here, 155 that implementation is not conforming and not compliant with this 156 specification. 158 This specification also uses many terms that are commonly used in 159 the context of network security. Other documents provide more 160 definitions and background information on these [VK83, HA94, Atk95a]. 161 A few terms deserve special mention: 163 (Encryption/Authentication) Algorithm 164 For PF_KEY purposes, an algorithm, whether encryption or 165 authentication, is the set of operations performed on a packet to 166 complete authentication or encryption as indicated by the SA type. 167 A PF_KEY algorithm MAY consist of more than one cryptographic 168 algorithm. Another possibility is that the same basic cryptographic 169 algorithm may be applied with different modes of operation or some 170 other implementation difference. These differences, henceforth 171 called _algorithm differentiators_, distinguish between different 172 PF_KEY algorithms, and options to the same algorithm. Algorithm 173 differentiators will often cause fundamentally different security 174 properties. 176 For example, both DES and 3DES use the same cryptographic 177 algorithm, but they are used differently and have different 178 security properties. The triple-application of DES is considered an 179 algorithm differentiator. There are therefore two different PF_KEY 180 algorithms for DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same 181 hash function, but construct their message authentication codes 182 differently. The use of HMAC is an algorithm differentiator. 183 DES-ECB and DES-CBC are the same cryptographic algorithm, but use a 184 different mode. Mode (e.g., chaining vs. code-book) is an algorithm 185 differentiator. Blowfish with a 128-bit key, however, is similar to 186 Blowfish with a 384-bit key, because the algorithm's workings are 187 otherwise the same and therefore the key length is not an algorithm 188 differentiator. 190 In terms of IP Security, a general rule of thumb is that whatever 191 might be labeled the "encryption" part of an ESP transform is 192 probably a PF_KEY encryption algorithm. Whatever might be labelled 193 the "authentication" part of an AH or ESP transform is probably a 194 PF_KEY authentication algorithm. 196 1.2 Conceptual Model 198 This section describes the conceptual model of an operating system 199 that implements the PF_KEY key management application programming 200 interface. This section is intended to provide background material 201 useful to understand the rest of this document. Presentation of this 202 conceptual model does not constrain a PF_KEY implementation to 203 strictly adhere to the conceptual components discussed in this 204 subsection. 206 Key management is most commonly implemented in whole or part at the 207 application layer. For example, the ISAKMP/Oakley, GKMP, and 208 Photuris proposals for IPsec key management are all application-layer 209 protocols. Manual keying is also done at the application layer. 210 Even parts of the SKIP IP-layer keying proposal can be implemented at 211 the application layer. Figure 1 shows the relationship between a Key 212 Management daemon and PF_KEY, which it uses to communicate with the 213 Key Engine, and PF_INET (or PF_INET6 in the case of IPv6), which it 214 uses to communicate via the network with a remote key management 215 entity. 217 The "Key Engine" or "Security Association Database (SADB)" is a 218 logical entity in the kernel that stores, updates, and deletes 219 Security Association data for various security protocols. There are 220 logical interfaces within the kernel (e.g. getassocbyspi(), 221 getassocbysocket()) that security protocols inside the kernel (e.g. 222 IP Security, aka IPsec) use to request and obtain Security 223 Associations. 225 In the case of IPsec, if by policy a particular outbound packet 226 needs processing, then the IPsec implementation requests an 227 appropriate Security Association from the Key Engine via the kernel- 228 internal interface. If the Key Engine has an appropriate SA, it 229 allocates the SA to this session (marking it as used) and returns the 230 SA to the IPsec implementation for use. If the Key Engine has no 231 such SA but a key management application has previously indicated 232 (via a PF_KEY SADB_REGISTER message) that it can obtain such SAs, 233 then the Key Engine requests that such an SA be created (via a PF_KEY 234 SADB_ACQUIRE message). When the key management daemon creates a new 235 SA, it places it into the Key Engine for future use. 237 +---------------+ 238 |Key Mgmt Daemon| 239 +---------------+ 240 | | 241 | | 242 | | Applications 243 ======[PF_KEY]====[PF_INET]========================== 244 | | OS Kernel 245 +------------+ +-----------------+ 246 | Key Engine | | TCP/IP, | 247 | or SADB |---| including IPsec | 248 +------------+ | | 249 +-----------------+ 250 | 251 +-----------+ 252 | Network | 253 | Interface | 254 +-----------+ 256 Figure 1: Relationship of Key Mgmt to PF_KEY 258 For performance reasons, some security protocols (e.g. IP Security) 259 are usually implemented inside the operating system kernel. Other 260 security protocols (e.g. OSPFv2 Cryptographic Authentication) are 261 implemented in trusted privileged applications outside the kernel. 262 Figure 2 shows a trusted, privileged routing daemon using PF_INET to 263 communicate routing information with a remote routing daemon and 264 using PF_KEY to request, obtain, and delete Security Associations 265 used with a routing protocol. 267 +---------------+ 268 |Routing Daemon| 269 +---------------+ 270 | | 271 | | 272 | | Applications 273 ======[PF_KEY]====[PF_INET]========================== 274 | | OS Kernel 275 +------------+ +---------+ 276 | Key Engine | | TCP/IP | 277 | or SADB |---| | 278 +------------+ +---------+ 279 | 280 +-----------+ 281 | Network | 282 | Interface | 283 +-----------+ 285 Figure 2: Relationship of Trusted Application to PF_KEY 287 When a trusted privileged application is using the Key Engine but 288 implements the security protocol within itself, then operation varies 289 slightly. In this case, the application needing an SA sends a PF_KEY 290 SADB_ACQUIRE message down to the Key Engine, which then either 291 returns an error or sends a similar SADB_ACQUIRE message up to one or 292 more key management applications capable of creating such SAs. As 293 before, the key management daemon stores the SA into the Key Engine. 294 Then, the trusted privileged application uses a SADB_GET message to 295 obtain the SA from the Key Engine. 297 In some implementations, policy may be implemented in user-space, 298 even though the actual cryptographic processing takes place in the 299 kernel. Such policy communication between the kernel mechanisms and 300 the user-space policy MAY be implemented by PF_KEY extensions, or 301 other such mechanism. This document does not specify such 302 extensions. 304 Untrusted clients, for example a user's web browser or telnet 305 client, do not need to use PF_KEY. Mechanisms not specified here are 306 used by such untrusted client applications to request security 307 services (e.g. IPsec) from an operating system. For security 308 reasons, only trusted, privileged applications are permitted to open 309 a PF_KEY socket. 311 1.3 PF_KEY Socket Definition 313 The PF_KEY protocol family (PF_KEY) symbol is defined in 314 in the same manner that other protocol families are 315 defined. PF_KEY does not use any socket addresses. Applications 316 using PF_KEY MUST NOT depend on the availability of a symbol named 317 AF_KEY, but kernel implementations are encouraged to define that 318 symbol for completeness. 320 The key management socket is created as follows: 322 #include 324 int s; 325 s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2); 327 The PF_KEY domain currently supports only the SOCK_RAW socket type. 328 The protocol field MUST be set to PF_KEY_V2, or else EPROTONOSUPPORT 329 will be returned. Only a trusted, privileged process can create a 330 PF_KEY socket. On conventional UNIX systems, a privileged process is 331 a process with an effective userid of zero. On non-MLS proprietary 332 operating systems, the notion of a "privileged process" is 333 implementation-defined. On Compartmented Mode Workstations (CMWs) or 334 other systems that claim to provide Multi-Level Security (MLS), a 335 process MUST have the "key management privilege" in order to open a 336 PF_KEY socket[DIA]. MLS systems that don't currently have such a 337 specific privilege MUST add that special privilege and enforce it 338 with PF_KEY in order to comply and conform with this specification. 339 Some systems, most notably some popular personal computers, do not 340 have the concept of an unprivileged user. These systems SHOULD take 341 steps to restrict the programs allowed to access the PF_KEY API. 343 1.4 Overview of PF_KEY Messaging Behavior 345 A process interacts with the key engine by sending and receiving 346 messages using the PF_KEY socket. Security association information 347 can be inserted into and retrieved from the kernel's security 348 association table using a set of predefined messages. In the normal 349 case, all properly-formed messages sent to the kernel are returned to 350 all open PF_KEY sockets, including the sender. Improperly formed 351 messages will result in errors, and an implementation MUST check for 352 a properly formed message before returning it to the appropriate 353 listeners. Unlike the routing socket, most errors are sent in reply 354 messages, not the errno field when write() or send() fails. PF_KEY 355 message delivery is not guaranteed, especially in cases where kernel 356 or socket buffers are exhausted and messages are dropped. 358 Some messages are generated by the operating system to indicate 359 that actions need to be taken, and are not necessarily in response to 360 any message sent down by the user. Such messages are not received by 361 all PF_KEY sockets, but by sockets which have indicated that kernel- 362 originated messages are to be received. These messages are special 363 because of the expected frequency at which they will occur. Also, an 364 implementation may further wish to restrict return message from the 365 kernel, in cases where not all PF_KEY sockets are in the same trust 366 domain. 368 Many of the normal BSD socket calls have undefined behavior on 369 PF_KEY sockets. These include: bind(), connect(), socketpair(), 370 accept(), getpeername(), getsockname(), ioctl(), and listen(). 372 1.5 Common PF_KEY Operations 374 There are two basic ways to add a new Security Association into the 375 kernel. The simplest is to send a single SADB_ADD message, 376 containing all of the SA information, from the application into the 377 kernel's Key Engine. This approach works particularly well with 378 manual key management, which is required for IPsec, and other 379 security protocols. 381 The second approach to add a new Security Association into the 382 kernel is for the application to first request an SPI value from the 383 kernel using the SADB_GETSPI message and then send a SADB_UPDATE 384 message with the complete Security Association data. This second 385 approach works well with key management daemons when the SPI values 386 need to be known before the entire Security Association data is known 387 (e.g. so the SPI value can be indicated to the remote end of the key 388 management session). 390 An individual Security Association can be deleted using the 391 SADB_DELETE message. Categories of SAs or the entire kernel SA table 392 can be deleted using the SADB_FLUSH message. 394 The SADB_GET message is used by a trusted application-layer process 395 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 396 SA) from the kernel's Key Engine. 398 The kernel or an application-layer can use the SADB_ACQUIRE message 399 to request that a Security Association be created by some 400 application-layer key management process that has registered with the 401 kernel via a SADB_REGISTER message. This ACQUIRE message will have a 402 sequence number associated with it. This sequence number MUST be 403 used by followup SADB_GETSPI, SADB_UPDATE, and SADB_ADD messages, in 404 order to keep track of which request gets its keying material. The 405 sequence number (described below) is analogous to a transaction ID in 406 a remote procedure call. 408 The SADB_EXPIRE message is sent from the kernel to key management 409 applications when the "soft lifetime" or "hard lifetime" of a 410 Security Association has expired. Key management applications should 411 use receipt of a soft lifetime SADB_EXPIRE message as a hint to 412 negotiate a replacement SA so the replacement SA will be ready and in 413 the kernel before it is needed. 415 A SADB_DUMP message is also defined, but this is primarily intended 416 for PF_KEY implementor debugging and is not used in ordinary 417 operation of PF_KEY. 419 1.6 Differences Between PF_KEY and PF_ROUTE 421 The following bullets are points of difference between the routing 422 socket and PF_KEY. Programmers who are used to the routing socket 423 semantics will find some differences in PF_KEY. 425 * PF_KEY message errors are usually returned in PF_KEY messages 426 instead of causing write() operations to fail and returning the 427 error number in errno. This means that other listeners on a 428 PF_KEY socket can be aware that requests from another process 429 failed, which can be useful for auditing purposes. This also 430 means that applications that fail to read PF_KEY messages 431 cannot do error checking. 433 An implementation MAY return the errors EINVAL, ENOMEM, and 434 ENOBUFS by causing write() operations to fail and returning the 435 error number in errno. This is an optimization for common error 436 cases in which it does not make sense for any other process to 437 receive the error. An application MUST NOT depend on such errors 438 being set by the write() call, but can save itself time by checking 439 for such errors. 441 * The entire message isn't always reflected in the reply. A SADB_ADD 442 message is an example of this. 444 * The PID is not set by the kernel. The process that originates the 445 message MUST set the sadb_msg_pid to its own PID. If the kernel 446 ORIGINATES a message, it MUST set the sadb_msg_pid to 0. A reply 447 to an original message SHOULD have the pid of the original message. 448 (E.g. The kernel's response to an SADB_ADD SHOULD have its pid set 449 to the pid value of the original SADB_ADD message.) 451 1.7 Name Space 453 All PF_KEYv2 preprocessor symbols and structure definitions are 454 defined as a result of including the header file . 455 There is exactly one exception to this rule: the symbol "PF_KEY", 456 which is defined as a result of including the header file 457 . All PF_KEYv2 preprocessor symbols start with the 458 prefix "SADB_" and all structure names start with "sadb_". There are 459 exactly two exceptions to this rule: the symbol "PF_KEY_V2" and the 460 symbol "PFKEYV2_REVISION". 462 The symbol "PFKEYV2_REVISION" is a date-encoded value not unlike 463 certain values defined by POSIX and X/Open. The current value for 464 PFKEYV2_REVISION is 199802L, where 1998 is the year and 02 is the 465 month. 467 Inclusion of the file MUST NOT define symbols or 468 structures in the PF_KEYv2 name space that are not described in this 469 document without the explicit prior permission of the authors. Any 470 symbols or structures in the PF_KEYv2 name space that are not 471 described in this document MUST start with "SADB_X_" or "sadb_x_". An 472 implementation that fails to obey these rules IS NOT COMPLIANT WITH 473 THIS SPECIFICATION and MUST NOT make any claim to be. These rules 474 also apply to any files that might be included as a result of 475 including the file . This rule provides implementors 476 with some assurance that they will not encounter namespace-related 477 surprises. 479 1.8 On Manual Keying 481 Not unlike the 4.4-Lite BSD PF_ROUTE socket, this interface allows 482 an application full-reign over the security associations in a kernel 483 that implements PF_KEY. A PF_KEY implementation MUST have some sort 484 of manual interface to PF_KEY, which SHOULD allow all of the 485 functionality of the programmatic interface described here. 487 2 PF_KEY Message Format 489 PF_KEY messages consist of a base header followed by additional 490 data fields, some of which may be optional. The format of the 491 additional data is dependent on the type of message. 493 PF_KEY messages currently do not mandate any specific ordering for 494 non-network multi-octet fields. Fields that may go across the wire 495 (e.g. SPI) MUST be in network byte order. 497 2.1 Base Message Header Format 499 PF_KEY messages consist of the base message header followed by 500 security association specific data whose types and lengths are 501 specified by a generic type-length encoding. 503 This base header is shown below, using POSIX types. The fields are 504 arranged primarily for alignment, and where possible, for reasons of 505 clarity. 507 struct sadb_msg { 508 uint8_t sadb_msg_version; 509 uint8_t sadb_msg_type; 510 uint8_t sadb_msg_errno; 511 uint8_t sadb_msg_satype; 512 uint16_t sadb_msg_len; 513 uint16_t sadb_msg_reserved; 514 uint32_t sadb_msg_seq; 515 uint32_t sadb_msg_pid; 516 }; 517 /* sizeof(struct sadb_msg) == 16 */ 519 sadb_msg_version 520 The version field of this PF_KEY message. This MUST 521 be set to PF_KEY_V2. If this is not set to PF_KEY_V2, 522 the write() call MAY fail and return EINVAL. 523 Otherwise, the behavior is undetermined, given that 524 the application might not understand the formatting 525 of the messages arriving from the kernel. 527 sadb_msg_type Identifies the type of message. The valid message 528 types are described later in this document. 530 sadb_msg_errno Should be set to zero by the sender. The responder 531 stores the error code in this field if an error has 532 occurred. This includes the case where the responder 533 is in user space. (e.g. user-space negotiation 534 fails, an errno can be returned.) 536 sadb_msg_satype Indicates the type of security association(s). Valid 537 Security Association types are declared in the file 538 . The current set of Security 539 Association types are enumerated later in this 540 document. 542 sadb_msg_len Contains the total length, in 64-bit words, of all 543 data in the PF_KEY message including the base header 544 length and additional data after the base header, if 545 any. This length includes any padding or extra space 546 that might exist. Unless otherwise stated, all other 547 length fields are also measured in 64-bit words. 549 On user to kernel messages, this field MUST be 550 verified against the length of the inbound message. 551 EMSGSIZE MUST be returned if the verification fails. 552 On kernel to user messages, a size mismatch is most 553 likely the result of the user not providing a large 554 enough buffer for the message. In these cases, the 555 user application SHOULD drop the message, but it MAY 556 try and extract what information it can out of the 557 message. 559 sadb_msg_reserved 560 Reserved value. It MUST be zeroed by the sender. All 561 fields labeled reserved later in the document have 562 the same semantics as this field. 564 sadb_msg_seq Contains the sequence number of this message. This 565 field, along with sadb_msg_pid, MUST be used to 566 uniquely identify requests to a process. The sender 567 is responsible for filling in this field. This 568 responsibility also includes matching the 569 sadb_msg_seq of a request (e.g. SADB_ACQUIRE). 571 This field is analogous to a transaction ID in a 572 remote procedure call implementation. 574 sadb_msg_pid Identifies the process which originated this message, 575 or which process a message is bound for. For example, 576 if process id 2112 sends a SADB_UPDATE message to the 577 kernel, the process MUST set this field to 2112 and 578 the kernel will set this field to 2112 in its reply 579 to that SADB_UPDATE message. This field, along with 580 sadb_msg_seq, can be used to uniquely identify 581 requests to a process. 583 It is currently assumed that a 32-bit quantity will 584 hold an operating system's process ID space. 586 2.2 Alignment of Headers and Extension Headers 588 The base message header is a multiple of 64 bits and fields after 589 it in memory will be 64 bit aligned if the base itself is 64 bit 590 aligned. Some of the subsequent extension headers have 64 bit fields 591 in them, and as a consequence need to be 64 bit aligned in an 592 environment where 64 bit quantities need to be 64 bit aligned. 594 The basic unit of alignment and length in PF_KEY Version 2 is 64 595 bits. Therefore: 597 * All extension headers, inclusive of the sadb_ext overlay fields, 598 MUST be a multiple of 64 bits long. 599 * All variable length data MUST be padded appropriately such that 600 its length in a message is a multiple of 64 bits. 601 * All length fields are, unless otherwise specified, in units of 602 64 bits. 603 * Implementations may safely access quantities of between 8 and 64 604 bits directly within a message without risk of alignment faults. 606 All PF_KEYv2 structures are packed and already have all intended 607 padding. Implementations MUST NOT insert any extra fields, including 608 hidden padding, into any structure in this document. This forbids 609 implementations from "extending" or "enhancing" existing headers 610 without changing the extension header type. As a guard against such 611 insertion of silent padding, each structure in this document is 612 labeled with its size in bytes. The size of these structures in an 613 implementation MUST match the size listed. 615 2.3 Additional Message Fields 617 The additional data following the base header consists of various 618 length-type-values fields. The first 32-bits are of a constant form: 620 struct sadb_ext { 621 uint16_t sadb_ext_len; 622 uint16_t sadb_ext_type; 623 }; 624 /* sizeof(struct sadb_ext) == 4 */ 626 sadb_ext_len Length of the extension header in 64 bit words, 627 inclusive. 629 sadb_ext_type The type of extension header that follows. Values for 630 this field are detailed later. The value zero is 631 reserved. 633 Types of extensions headers include: Association, Lifetime(s), 634 Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and 635 Supported. There MUST be only one instance of a extension type in a 636 message. (e.g. Base, Key, Lifetime, Key is forbidden), an EINVAL will 637 be returned if there are duplicate extensions within a message. 638 Implementations MAY enforce ordering of extensions in the order 639 presented in the EXTENSION HEADER VALUES section. 641 If an unknown extension type is encountered, it MUST be ignored. 642 Applications using extension headers not specified in this document 643 MUST be prepared to work around other system components not 644 processing those headers. Likewise, if an application encounters an 645 unknown extension from the kernel, it must be prepared to work around 646 it. Also, a kernel that generates extra extension header types MUST 647 NOT _depend_ on applications also understanding extra extension 648 header types. 650 All extension definitions include these two fields (len and 651 exttype) because they are instances of a generic extension (not 652 unlike sockaddr_in and sockaddr_in6 are instances of a generic 653 sockaddr). The sadb_ext header MUST NOT ever be present in a message 654 without at least four bytes of extension header data following it, 655 and, therefore, there is no problem with it being only four bytes 656 long. 658 All extensions documented in this section MUST be implemented by a 659 PF_KEY implementation. 661 2.3.1 Association Extension 663 The Association extension specifies data specific to a single 664 security association. The only times this extension is not present is 665 when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being 666 passed and on the SADB_ACQUIRE message. 668 struct sadb_sa { 669 uint16_t sadb_sa_len; 670 uint16_t sadb_sa_exttype; 671 uint32_t sadb_sa_spi; 672 uint8_t sadb_sa_replay; 673 uint8_t sadb_sa_state; 674 uint8_t sadb_sa_auth; 675 uint8_t sadb_sa_encrypt; 676 uint32_t sadb_sa_flags; 677 }; 678 /* sizeof(struct sadb_sa) == 16 */ 680 sadb_sa_spi The Security Parameters Index value for the security 681 association. Although this is a 32-bit field, some 682 types of security associations might have a SPI or 683 key identifier that is less than 32-bits long. In 684 this case, the smaller value shall be stored in the 685 least significant bits of this field and the unneeded 686 bits shall be zero. This field MUST be in network 687 byte order. 689 sadb_sa_replay The size of the replay window, if not zero. If zero, 690 then no replay window is in use. 692 sadb_sa_state The state of the security association. The currently 693 defined states are described later in this document. 695 sadb_sa_auth The authentication algorithm to be used with this 696 security association. The valid authentication 697 algorithms are described later in this document. A 698 value of zero means that no authentication is used 699 for this security association. 701 sadb_sa_encrypt The encryption algorithm to be used with this 702 security association. The valid encryption algorithms 703 are described later in this document. A value of zero 704 means that no encryption is used for this security 705 association. 707 sadb_sa_flags A bitmap of options defined for the security 708 association. The currently defined flags are 709 described later in this document. 711 The kernel MUST check these values where appropriate. For example, 712 IPsec AH with no authentication algorithm is probably an error. 714 When used with some messages, the values in some fields in this 715 header should be ignored. 717 2.3.2 Lifetime Extension 719 The Lifetime extension specifies one or more lifetime variants for 720 this security association. If no Lifetime extension is present the 721 association has an infinite lifetime. An association SHOULD have a 722 lifetime of some sort associated with it. Lifetime variants come in 723 three varieties, HARD - indicating the hard-limit expiration, SOFT - 724 indicating the soft-limit expiration, and CURRENT - indicating the 725 current state of a given security association. The Lifetime 726 extension looks like: 728 struct sadb_lifetime { 729 uint16_t sadb_lifetime_len; 730 uint16_t sadb_lifetime_exttype; 731 uint32_t sadb_lifetime_allocations; 732 uint64_t sadb_lifetime_bytes; 733 uint64_t sadb_lifetime_addtime; 734 uint64_t sadb_lifetime_usetime; 735 }; 736 /* sizeof(struct sadb_lifetime) == 32 */ 738 sadb_lifetime_allocations 739 For CURRENT, the number of different connections, 740 endpoints, or flows that the association has been 741 allocated towards. For HARD and SOFT, the number of 742 these the association may be allocated towards 743 before it expires. The concept of a connection, 744 flow, or endpoint is system specific. 746 sadb_lifetime_bytes 747 For CURRENT, how many bytes have been processed 748 using this security association. For HARD and SOFT, 749 the number of bytes that may be processed using 750 this security association before it expires. 752 sadb_lifetime_addtime 753 For CURRENT, the time, in seconds, when the 754 association was created. For HARD and SOFT, the 755 number of seconds after the creation of the 756 association until it expires. 758 For such time fields, it is assumed that 64-bits is 759 sufficiently large to hold the POSIX time_t value. 760 If this assumption is wrong, this field will have to 761 be revisited. 763 sadb_lifetime_usetime 764 For CURRENT, the time, in seconds, when association 765 was first used. For HARD and SOFT, the number of 766 seconds after the first use of the association until 767 it expires. 769 The semantics of lifetimes are inclusive-OR, first-to-expire. This 770 means that if values for bytes and time, or multiple times, are 771 passed in, the first of these values to be reached will cause a 772 lifetime expiration. 774 2.3.3 Address Extension 776 The Address extension specifies one or more addresses that are 777 associated with a security association. Address extensions for both 778 source and destination MUST be present when an Association extension 779 is present. The format of an Address extension is: 781 struct sadb_address { 782 uint16_t sadb_address_len; 783 uint16_t sadb_address_exttype; 784 uint8_t sadb_address_proto; 785 uint8_t sadb_address_prefixlen; 786 uint16_t sadb_address_reserved; 787 }; 788 /* sizeof(struct sadb_address) == 8 */ 790 /* followed by some form of struct sockaddr */ 792 The sockaddr structure SHOULD conform to the sockaddr structure of 793 the system implementing PF_KEY. If the system has an sa_len field, so 794 SHOULD the sockaddrs in the message. If the system has NO sa_len 795 field, the sockaddrs SHOULD NOT have an sa_len field. All non-address 796 information in the sockaddrs, such as sin_zero for AF_INET sockaddrs, 797 and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out. The 798 zeroing of ports (e.g. sin_port and sin6_port) MUST be done for all 799 messages except for originating SADB_ACQUIRE messages, which SHOULD 800 fill them in with ports from the relevant TCP or UDP session which 801 generates the ACQUIRE message. If the ports are non-zero, then the 802 sadb_address_proto field, normally zero, MUST be filled in with the 803 transport protocol's number. If the sadb_address_prefixlen is non- 804 zero, then the address has a prefix (often used in KM access control 805 decisions), with length specified in sadb_address_prefixlen. These 806 additional fields may be useful to KM applications. 808 The SRC and DST addresses for a security association MUST be in the 809 same protocol family and MUST always be present or absent together in 810 a message. The PROXY address MAY be in a different protocol family, 811 and represents an actual originator of a packet. (For example, the 812 inner-packets's source address in a tunnel.) 814 The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY) 815 address. The DST address MUST be a unicast or multicast address. The 816 PROXY address MUST be a unicast address. 818 2.3.4 Key Extension 820 The Key extension specifies one or more keys that are associated 821 with a security association. A Key extension will not always be 822 present with messages, because of security risks. The format of a 823 Key extension is: 825 struct sadb_key { 826 uint16_t sadb_key_len; 827 uint16_t sadb_key_exttype; 828 uint16_t sadb_key_bits; 829 uint16_t sadb_key_reserved; 830 }; 831 /* sizeof(struct sadb_key) == 8 */ 833 /* followed by the key data */ 835 sadb_key_bits The length of the valid key data, in bits. A value of 836 zero in sadb_key_bits MUST cause an error. 838 The key extension comes in two varieties. The AUTH version is used 839 with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT 840 version is used with encryption keys (e.g. IPsec ESP). PF_KEY deals 841 only with fully formed cryptographic keys, not with "raw key 842 material". For example, when ISAKMP/Oakley is in use, the key 843 management daemon is always responsible for transforming the result 844 of the Diffie-Hellman computation into distinct fully formed keys 845 PRIOR to sending those keys into the kernel via PF_KEY. This rule is 846 made because PF_KEY is designed to support multiple security 847 protocols (not just IP Security) and also multiple key management 848 schemes including manual keying, which does not have the concept of 849 "raw key material". A clean, protocol-independent interface is 850 important for portability to different operating systems as well as 851 for portability to different security protocols. 853 If an algorithm defines its key to include parity bits (e.g. DES) 854 then the key used with PF_KEY MUST also include those parity bits. 855 For example, this means that a single DES key is always a 64-bit 856 quantity. 858 When a particular security protocol only requires one 860 authentication and/or one encryption key, the fully formed key is 861 transmitted using the appropriate key extension. When a particular 862 security protocol requires more than one key for the same function 863 (e.g. Triple-DES using 2 or 3 keys, and asymmetric algorithms), then 864 those two fully formed keys concatenated together in the order used 865 for outbound packet processing. In the case of multiple keys, the 866 algorithm MUST be able to determine the lengths of the individual 867 keys based on the information provided. The total key length (when 868 combined with knowledge of the algorithm in use) usually provides 869 sufficient information to make this determination. 871 Keys are always passed through the PF_KEY interface in the order 872 that they are used for outbound packet processing. For inbound 873 processing, the correct order that keys are used might be different 874 from this canonical concatenation order used with the PF_KEY 875 interface. It is the responsibility of the implementation to use the 876 keys in the correct order for both inbound and outbound processing. 878 For example, consider a pair of nodes communicating unicast using 879 an ESP three-key Triple-DES Security Association. Both the outbound 880 SA on the sender node, and the inbound SA on the receiver node will 881 contain key-A, followed by key-B, followed by key-C in their 882 respective ENCRYPT key extensions. The outbound SA will use key-A 883 first, followed by key-B, then key-C when encrypting. The inbound SA 884 will use key-C, followed by key-B, then key-A when decrypting. 885 (NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.) 886 The canonical ordering of key-A, key-B, key-C is used for 3DES, and 887 should be documented. The order of "encryption" is the canonical 888 order for this example. [DMS97] 890 The key data bits are arranged most-significant to least 891 significant. For example, a 22-bit key would take up three octets, 892 with the least significant two bits not containing key material. Five 893 additional octets would then be used for padding to the next 64-bit 894 boundary. 896 While not directly related to PF_KEY, there is a user interface 897 issue regarding odd-digit hexadecimal representation of keys. 898 Consider the example of the 16-bit number: 900 0x123 902 That will require two octets of storage. In the absence of other 903 information, however, unclear whether the value shown is stored as: 905 01 23 OR 12 30 907 It is the opinion of the authors that the former (0x123 == 0x0123) is 908 the better way to interpret this ambiguity. Extra information (for 909 example, specifying 0x0123 or 0x1230, or specifying that this is only 910 a twelve-bit number) would solve this problem. 912 2.3.5 Identity Extension 914 The Identity extension contains endpoint identities. This 915 information is used by key management to select the identity 916 certificate that is used in negotiations. This information may also 917 be provided by a kernel to network security aware applications to 918 identify the remote entity, possibly for access control purposes. If 919 this extension is not present, key management MUST assume that the 920 addresses in the Address extension are the only identities for this 921 Security Association. The Identity extension looks like: 923 struct sadb_ident { 924 uint16_t sadb_ident_len; 925 uint16_t sadb_ident_exttype; 926 uint16_t sadb_ident_type; 927 uint16_t sadb_ident_reserved; 928 uint64_t sadb_ident_id; 929 }; 930 /* sizeof(struct sadb_ident) == 16 */ 932 /* followed by the identity string, if present */ 934 sadb_ident_type The type of identity information that follows. 935 Currently defined identity types are described later 936 in this document. 938 sadb_ident_id An identifier used to aid in the construction of an 939 identity string if none is present. A POSIX user id 940 value is one such identifier that will be used in this 941 field. Use of this field is described later in this 942 document. 944 A C string containing a textual representation of the identity 945 information optionally follows the sadb_ident extension. The format 946 of this string is determined by the value in sadb_ident_type, and is 947 described later in this document. 949 2.3.6 Sensitivity Extension 951 The Sensitivity extension contains security labeling information 952 for a security association. If this extension is not present, no 953 sensitivity-related data can be obtained from this security 954 association. If this extension is present, then the need for 955 explicit security labeling on the packet is obviated. 957 struct sadb_sens { 958 uint16_t sadb_sens_len; 959 uint16_t sadb_sens_exttype; 960 uint32_t sadb_sens_dpd; 961 uint8_t sadb_sens_sens_level; 962 uint8_t sadb_sens_sens_len; 963 uint8_t sadb_sens_integ_level; 964 uint8_t sadb_sens_integ_len; 965 uint32_t sadb_sens_reserved; 966 }; 967 /* sizeof(struct sadb_sens) == 16 */ 969 /* followed by: 970 uint64_t sadb_sens_bitmap[sens_len]; 971 uint64_t sadb_integ_bitmap[integ_len]; */ 973 sadb_sens_dpd Describes the protection domain, which allows 974 interpretation of the levels and compartment 975 bitmaps. 976 sadb_sens_sens_level 977 The sensitivity level. 978 sadb_sens_sens_len 979 The length, in 64 bit words, of the sensitivity 980 bitmap. 981 sadb_sens_integ_level 982 The integrity level. 983 sadb_sens_integ_len 984 The length, in 64 bit words, of the integrity 985 bitmap. 987 This sensitivity extension is designed to support the Bell-LaPadula 988 [BL74] security model used in compartmented-mode or multi-level 989 secure systems, the Clark-Wilson [CW87] commercial security model, 990 and/or the Biba integrity model [Biba77]. These formal models can be 991 used to implement a wide variety of security policies. The definition 992 of a particular security policy is outside the scope of this 993 document. 995 2.3.7 Proposal Extension 997 The Proposal extension contains a "proposed situation" of algorithm 998 preferences. It looks like: 1000 struct sadb_prop { 1001 uint16_t sadb_prop_len; 1002 uint16_t sadb_prop_exttype; 1003 uint8_t sadb_prop_replay; 1004 uint8_t sadb_prop_reserved[3]; 1006 }; 1007 /* sizeof(struct sadb_prop) == 8 */ 1009 /* followed by: 1010 struct sadb_comb sadb_combs[(sadb_prop_len * 1011 sizeof(uint64_t) - sizeof(struct sadb_prop)) / 1012 sizeof(struct sadb_comb)]; */ 1014 Following the header are a list of proposed parameter combinations in 1015 preferential order. The values in these fields have the same 1016 definition as the fields those values will move into if the 1017 combination is chosen. These combinations look like: 1019 struct sadb_comb { 1020 uint8_t sadb_comb_auth; 1021 uint8_t sadb_comb_encrypt; 1022 uint16_t sadb_comb_flags; 1023 uint16_t sadb_comb_auth_minbits; 1024 uint16_t sadb_comb_auth_maxbits; 1025 uint16_t sadb_comb_encrypt_minbits; 1026 uint16_t sadb_comb_encrypt_maxbits; 1027 uint32_t sadb_comb_reserved; 1028 uint32_t sadb_comb_soft_allocations; 1029 uint32_t sadb_comb_hard_allocations; 1030 uint64_t sadb_comb_soft_bytes; 1031 uint64_t sadb_comb_hard_bytes; 1032 uint64_t sadb_comb_soft_addtime; 1033 uint64_t sadb_comb_hard_addtime; 1034 uint64_t sadb_comb_soft_usetime; 1035 uint64_t sadb_comb_hard_usetime; 1036 }; 1037 /* sizeof(struct sadb_comb) == 72 */ 1039 sadb_comb_auth If this combination is accepted, this will be the 1040 value of sadb_sa_auth. 1042 sadb_comb_encrypt 1043 If this combination is accepted, this will be the 1044 value of sadb_sa_encrypt. 1046 sadb_comb_auth_minbits; 1047 sadb_comb_auth_maxbits; 1048 The minimum and maximum acceptable authentication 1049 key lengths, respectably, in bits. If sadb_comb_auth 1050 is zero, both of these values MUST be zero. If 1051 sadb_comb_auth is nonzero, both of these values MUST 1052 be nonzero. If this combination is accepted, a value 1053 between these (inclusive) will be stored in the 1054 sadb_key_bits field of KEY_AUTH. The minimum MUST 1055 NOT be greater than the maximum. 1057 sadb_comb_encrypt_minbits; 1058 sadb_comb_encrypt_maxbits; 1059 The minimum and maximum acceptable encryption key 1060 lengths, respectably, in bits. If sadb_comb_encrypt 1061 is zero, both of these values MUST be zero. If 1062 sadb_comb_encrypt is nonzero, both of these values 1063 MUST be nonzero. If this combination is accepted, a 1064 value between these (inclusive) will be stored in 1065 the sadb_key_bits field of KEY_ENCRYPT. The minimum 1066 MUST NOT be greater than the maximum. 1068 sadb_comb_soft_allocations 1069 sadb_comb_hard_allocations 1070 If this combination is accepted, these are proposed 1071 values of sadb_lifetime_allocations in the SOFT and 1072 HARD lifetimes, respectively. 1074 sadb_comb_soft_bytes 1075 sadb_comb_hard_bytes 1076 If this combination is accepted, these are proposed 1077 values of sadb_lifetime_bytes in the SOFT and HARD 1078 lifetimes, respectively. 1080 sadb_comb_soft_addtime 1081 sadb_comb_hard_addtime 1082 If this combination is accepted, these are proposed 1083 values of sadb_lifetime_addtime in the SOFT and HARD 1084 lifetimes, respectively. 1086 sadb_comb_soft_usetime 1087 sadb_comb_hard_usetime 1088 If this combination is accepted, these are proposed 1089 values of sadb_lifetime_usetime in the SOFT and HARD 1090 lifetimes, respectively. 1092 Each combination has an authentication and encryption algorithm, 1093 which may be 0, indicating none. A combination's flags are the same 1094 as the flags in the Association extension. The minimum and maximum 1095 key lengths (which are in bits) are derived from possible a priori 1096 policy decisions, along with basic properties of the algorithm. 1097 Lifetime attributes are also included in a combination, as some 1098 algorithms may know something about their lifetimes and can suggest 1099 lifetime limits. 1101 2.3.8 Supported Algorithms Extension 1103 The Supported Algorithms extension contains a list of all 1104 algorithms supported by the system. This tells key management what 1105 algorithms it can negotiate. Available authentication algorithms are 1106 listed in the SUPPORTED_AUTH extension and available encryption 1107 algorithms are listed in the SUPPORTED_ENCRYPT extension. The format 1108 of these extensions is: 1110 struct sadb_supported { 1111 uint16_t sadb_supported_len; 1112 uint16_t sadb_supported_exttype; 1113 uint32_t sadb_supported_reserved; 1114 }; 1115 /* sizeof(struct sadb_supported) == 8 */ 1117 /* followed by: 1118 struct sadb_alg sadb_algs[(sadb_supported_len * 1119 sizeof(uint64_t) - sizeof(struct sadb_supported)) / 1120 sizeof(struct sadb_alg)]; */ 1122 This header is followed by one or more algorithm descriptions. An 1123 algorithm description looks like: 1125 struct sadb_alg { 1126 uint8_t sadb_alg_id; 1127 uint8_t sadb_alg_ivlen; 1128 uint16_t sadb_alg_minbits; 1129 uint16_t sadb_alg_maxbits; 1130 uint16_t sadb_alg_reserved; 1131 }; 1132 /* sizeof(struct sadb_alg) == 8 */ 1134 sadb_alg_id The algorithm identification value for this 1135 algorithm. This is the value that is stored in 1136 sadb_sa_auth or sadb_sa_encrypt if this algorithm is 1137 selected. 1139 sadb_alg_ivlen The length of the initialization vector to be used 1140 for the algorithm. If an IV is not needed, this 1141 value MUST be set to zero. 1143 sadb_alg_minbits 1144 The minimum acceptable key length, in bits. A value 1145 of zero is invalid. 1147 sadb_alg_maxbits 1148 The maximum acceptable key length, in bits. A value 1149 of zero is invalid. The minimum MUST NOT be greater 1150 than the maximum. 1152 2.3.9 SPI Range Extension 1154 One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI 1155 values. This extension performs such a function. 1157 struct sadb_spirange { 1158 uint16_t sadb_spirange_len; 1159 uint16_t sadb_spirange_exttype; 1160 uint32_t sadb_spirange_min; 1161 uint32_t sadb_spirange_max; 1162 uint32_t sadb_spirange_reserved; 1163 }; 1164 /* sizeof(struct sadb_spirange) == 16 */ 1166 sadb_spirange_min 1167 The minimum acceptable SPI value. 1169 sadb_spirange_max 1170 The maximum acceptable SPI value. The maximum MUST 1171 be greater than or equal to the minimum. 1173 2.4 Illustration of Message Layout 1175 The following shows how the octets are laid out in a PF_KEY message. 1176 Optional fields are indicated as such. 1178 The base header is as follows: 1180 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 1181 +---------------+---------------+---------------+---------------+ 1182 | ...version | sadb_msg_type | sadb_msg_errno| ...msg_satype | 1183 +---------------+---------------+---------------+---------------+ 1184 | sadb_msg_len | sadb_msg_reserved | 1185 +---------------+---------------+---------------+---------------+ 1186 | sadb_msg_seq | 1187 +---------------+---------------+---------------+---------------+ 1188 | sadb_msg_pid | 1189 +---------------+---------------+---------------+---------------+ 1191 The base header may be followed by one or more of the following 1192 extension fields, depending on the values of various base header 1193 fields. The following fields are ordered such that if they appear, 1194 they SHOULD appear in the order presented below. 1196 An extension field MUST not be repeated. If there is a situation 1197 where an extension MUST be repeated, it should be brought to the 1198 attention of the authors. 1200 The Association extension 1202 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 1203 +---------------+---------------+---------------+---------------+ 1204 | sadb_sa_len | sadb_sa_exttype | 1205 +---------------+---------------+---------------+---------------+ 1206 | sadb_sa_spi | 1207 +---------------+---------------+---------------+---------------+ 1208 | ...replay | sadb_sa_state | sadb_sa_auth |sadb_sa_encrypt| 1209 +---------------+---------------+---------------+---------------+ 1210 | sadb_sa_flags | 1211 +---------------+---------------+---------------+---------------+ 1213 The Lifetime extension 1215 +---------------+---------------+---------------+---------------+ 1216 | sadb_lifetime_len | sadb_lifetime_exttype | 1217 +---------------+---------------+---------------+---------------+ 1218 | sadb_lifetime_allocations | 1219 +---------------+---------------+---------------+---------------+ 1220 | sadb_lifetime_bytes | 1221 | (64 bits) | 1222 +---------------+---------------+---------------+---------------+ 1223 | sadb_lifetime_addtime | 1224 | (64 bits) | 1225 +---------------+---------------+---------------+---------------+ 1226 | sadb_lifetime_usetime | 1227 | (64 bits) | 1228 +---------------+---------------+---------------+---------------+ 1230 The Address extension 1232 +---------------+---------------+---------------+---------------+ 1233 | sadb_address_len | sadb_address_exttype | 1234 +---------------+---------------+---------------+---------------+ 1235 | _address_proto| ..._prefixlen | sadb_address_reserved | 1236 +---------------+---------------+---------------+---------------+ 1237 > Some form of 64-bit aligned struct sockaddr goes here. < 1238 +---------------+---------------+---------------+---------------+ 1240 The Key extension 1242 +---------------+---------------+---------------+---------------+ 1243 | sadb_key_len | sadb_key_exttype | 1244 +---------------+---------------+---------------+---------------+ 1245 | sadb_key_bits | sadb_key_reserved | 1246 +---------------+---------------+---------------+---------------+ 1247 > A key, padded to 64-bits, most significant bits to least. > 1248 +---------------+---------------+---------------+---------------+ 1250 The Identity extension 1252 +---------------+---------------+---------------+---------------+ 1253 | sadb_ident_len | sadb_ident_exttype | 1254 +---------------+---------------+---------------+---------------+ 1255 | sadb_ident_type | sadb_ident_reserved | 1256 +---------------+---------------+---------------+---------------+ 1257 | sadb_ident_id | 1258 | (64 bits) | 1259 +---------------+---------------+---------------+---------------+ 1260 > A null-terminated C-string which MUST be padded out for > 1261 < 64-bit alignment. < 1262 +---------------+---------------+---------------+---------------+ 1264 The Sensitivity extension 1266 +---------------+---------------+---------------+---------------+ 1267 | sadb_sens_len | sadb_sens_exttype | 1268 +---------------+---------------+---------------+---------------+ 1269 | sadb_sens_dpd | 1270 +---------------+---------------+---------------+---------------+ 1271 | ...sens_level | ...sens_len |..._integ_level| ..integ_len | 1272 +---------------+---------------+---------------+---------------+ 1273 | sadb_sens_reserved | 1274 +---------------+---------------+---------------+---------------+ 1275 > The sensitivity bitmap, followed immediately by the < 1276 < integrity bitmap, each is an array of uint64_t. > 1277 +---------------+---------------+---------------+---------------+ 1279 The Proposal extension 1281 +---------------+---------------+---------------+---------------+ 1282 | sadb_prop_len | sadb_prop_exttype | 1283 +---------------+---------------+---------------+---------------+ 1284 |...prop_replay | sadb_prop_reserved | 1285 +---------------+---------------+---------------+---------------+ 1286 > One or more combinations, specified as follows... < 1287 +---------------+---------------+---------------+---------------+ 1289 Combination 1290 +---------------+---------------+---------------+---------------+ 1291 |sadb_comb_auth |sadb_comb_encr | sadb_comb_flags | 1292 +---------------+---------------+---------------+---------------+ 1293 | sadb_comb_auth_minbits | sadb_comb_auth_maxbits | 1294 +---------------+---------------+---------------+---------------+ 1295 | sadb_comb_encrypt_minbits | sadb_comb_encrypt_maxbits | 1296 +---------------+---------------+---------------+---------------+ 1297 | sadb_comb_reserved | 1298 +---------------+---------------+---------------+---------------+ 1299 | sadb_comb_soft_allocations | 1300 +---------------+---------------+---------------+---------------+ 1301 | sadb_comb_hard_allocations | 1302 +---------------+---------------+---------------+---------------+ 1303 | sadb_comb_soft_bytes | 1304 | (64 bits) | 1305 +---------------+---------------+---------------+---------------+ 1306 | sadb_comb_hard_bytes | 1307 | (64 bits) | 1308 +---------------+---------------+---------------+---------------+ 1309 | sadb_comb_soft_addtime | 1310 | (64 bits) | 1311 +---------------+---------------+---------------+---------------+ 1312 | sadb_comb_hard_addtime | 1313 | (64 bits) | 1314 +---------------+---------------+---------------+---------------+ 1315 | sadb_comb_soft_usetime | 1316 | (64 bits) | 1317 +---------------+---------------+---------------+---------------+ 1318 | sadb_comb_hard_usetime | 1319 | (64 bits) | 1320 +---------------+---------------+---------------+---------------+ 1322 The Supported Algorithms extension 1324 +---------------+---------------+---------------+---------------+ 1325 | sadb_supported_len | sadb_supported_exttype | 1326 +---------------+---------------+---------------+---------------+ 1327 | sadb_supported_reserved | 1328 +---------------+---------------+---------------+---------------+ 1330 Followed by one or more Algorithm Descriptors 1332 +---------------+---------------+---------------+---------------+ 1333 | sadb_alg_id | sadb_alg_ivlen| sadb_alg_minbits | 1334 +---------------+---------------+---------------+---------------+ 1335 | sadb_alg_maxbits | sadb_alg_reserved | 1336 +---------------+---------------+---------------+---------------+ 1338 The SPI Range extension 1340 +---------------+---------------+---------------+---------------+ 1341 | sadb_spirange_len | sadb_spirange_exttype | 1342 +---------------+---------------+---------------+---------------+ 1343 | sadb_spirange_min | 1344 +---------------+---------------+---------------+---------------+ 1345 | sadb_spirange_max | 1346 +---------------+---------------+---------------+---------------+ 1347 | sadb_spirange_reserved | 1348 +---------------+---------------+---------------+---------------+ 1350 3 Symbolic Names 1352 This section defines various symbols used with PF_KEY and the 1353 semantics associated with each symbol. Applications MUST use the 1354 symbolic names in order to be portable. The numeric definitions 1355 shown are for illustrative purposes, unless explicitly stated 1356 otherwise. The numeric definition MAY vary on other systems. The 1357 symbolic name MUST be kept the same for all conforming 1358 implementations. 1360 3.1 Message Types 1362 The following message types are used with PF_KEY. These are 1363 defined in the file . 1365 #define SADB_RESERVED 0 1366 #define SADB_GETSPI 1 1367 #define SADB_UPDATE 2 1368 #define SADB_ADD 3 1369 #define SADB_DELETE 4 1370 #define SADB_GET 5 1371 #define SADB_ACQUIRE 6 1372 #define SADB_REGISTER 7 1373 #define SADB_EXPIRE 8 1374 #define SADB_FLUSH 9 1376 #define SADB_DUMP 10 /* not used normally */ 1378 #define SADB_MAX 10 1380 Each message has a behavior. A behavior is defined as where the 1381 initial message travels (e.g. user to kernel), and what subsequent 1382 actions are expected to take place. Contents of messages are 1383 illustrated as: 1385 1387 The SA extension is sometimes used only for its SPI field. If all 1388 other fields MUST be ignored, this is represented by "SA(*)". 1390 The lifetime extensions are represented with one to three letters 1391 after the word "lifetime," representing (H)ARD, (S)OFT, and 1392 (C)URRENT. 1394 The address extensions are represented with one to three letters 1395 after the word "address," representing (S)RC, (D)ST, (P)ROXY. 1396 NOTE: Some security association types do not use a source 1397 address for SA identification, where others do. This 1398 may cause EEXIST errors for some SA types where others 1399 do not report collisions. It is expected that 1400 application authors know enough about the underlying 1401 security association types to understand these 1402 differences. 1404 The key extensions are represented with one or two letters after the 1405 word "key," representing (A)UTH and (E)NCRYPT. 1407 The identity extensions are represented with one or two letters after 1408 the word "identity," representing (S)RC and (D)ST. 1410 In the case of an error, only the base header is returned. 1412 Note that any standard error could be returned for any message. 1414 Typically, they will be either one of the errors specifically listed 1415 in the description for a message or one of the following: 1417 EINVAL Various message improprieties, including SPI ranges 1418 that are malformed. 1419 ENOMEM Needed memory was not available. 1420 ENOBUFS Needed memory was not available. 1421 EMSGSIZ The message exceeds the maximum length allowed. 1423 3.1.1 SADB_GETSPI 1425 The SADB_GETSPI message allows a process to obtain a unique SPI 1426 value for given security association type, source address, and 1427 destination address. This message followed by a SADB_UPDATE is one 1428 way to create a security association (SADB_ADD is the other method). 1429 The process specifies the type in the base header, the source and 1430 destination address in address extension. If the SADB_GETSPI message 1431 is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq 1432 MUST be the same as the SADB_ACQUIRE message. The application may 1433 also specify the SPI. This is done by having the kernel select 1434 within a range of SPI values by using the SPI range extension. To 1435 specify a single SPI value to be verified, the application sets the 1436 high and low values to be equal. Permitting range specification is 1437 important because the kernel can allocate an SPI value based on what 1438 it knows about SPI values already in use. The kernel returns the 1439 same message with the allocated SPI value stored in the spi field of 1440 an association extension. An SADB_UPDATE message can later be used 1441 to add an entry with the requested SPI value. 1443 The message behavior of the SADB_GETSPI message is: 1445 Send a SADB_GETSPI message from a user process to the kernel. 1447 1449 The kernel returns the SADB_GETSPI message to all listening 1450 processes. 1452 1454 Errors: 1456 EEXIST Requested SPI or SPI range is not available or already 1457 used. 1459 3.1.2 SADB_UPDATE Message 1461 The SADB_UPDATE message allows a process to update the information 1463 in an existing Security Association. Since SADB_GETSPI does not 1464 allow setting of certain parameters, this message is needed to fully 1465 form the SADB_SASTATE_LARVAL security association created with 1466 SADB_GETSPI. The format of the update message is a base header, 1467 followed by an association header and possibly by several extension 1468 headers. The kernel searches for the security association with the 1469 same type, spi, source address and destination address specified in 1470 the message and updates the Security Association information using 1471 the content of the SADB_UPDATE message. 1473 The kernel MAY disallow SADB_UPDATE to succeed unless the message 1474 is issued from the same socket that created the security association. 1475 Such enforcement significantly reduces the chance of accidental 1476 changes to an in-use security associations. Malicious trusted 1477 parties could still issue a SADB_FLUSH or SADB_DELETE message, but 1478 deletion of associations is more easily detected and less likely to 1479 occur accidentally than an erroneous SADB_UPDATE. The counter 1480 argument to supporting this behavior involves the case where a user- 1481 space key management application fails and is restarted. The new 1482 instance of the application will not have the same socket as the 1483 creator of the security association. 1485 The kernel MUST sanity check all significant values submitted in a 1486 SADB_UPDATE message before changing the SA in its database and MUST 1487 return EINVAL if any of the values are invalid. Examples of checks 1488 that should be performed are DES key parity bit, key length checking, 1489 checks for keys known to be weak for the specified algorithm, and 1490 checks for flags or parameters known to be incompatible with the 1491 specified algorithm. 1493 Only SADB_SASTATE_MATURE SAs may be submitted in a SADB_UPDATE 1494 message. If the original SA is a SADB_SASTATE_LARVAL SA, then any 1495 value in the SA may be changed except for the source address, 1496 destination address, and SPI. If the original SA is a 1497 SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA 1498 MUST return EINVAL. It is not valid for established keying or 1499 algorithm information to change without the SPI changing, which would 1500 require creation of a new SA rather than a change to an existing SA. 1501 Once keying and algorithm information is negotiated, address and 1502 identity information is fixed for the SA. Therefore, if the original 1503 SA is a SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state field 1504 in the SA header and lifetimes (hard, soft, and current) may be 1505 changed and any attempt to change other values MUST result in an 1506 error return of EINVAL. 1508 The message behavior of the SADB_UPDATE message is: 1510 Send a SADB_UPDATE message from a user process to the kernel. 1512 1515 The kernel returns the SADB_UPDATE message to all listening 1516 processes. 1518 1521 The keying material is not returned on the message from the kernel 1522 to listening sockets because listeners might not have the privileges 1523 to see such keying material. 1525 Errors: 1526 ESRCH The security association to be updated was not found. 1527 EINVAL In addition to other possible causes, this error is 1528 returned if sanity checking on the SA values (such 1529 as the keys) fails. 1530 EACCES Insufficient privilege to update entry. The socket 1531 issuing the SADB_UPDATE is not creator of the entry 1532 to be updated. 1534 3.1.3 SADB_ADD 1536 The SADB_ADD message is nearly identical to the SADB_UPDATE 1537 message, except that it does not require a previous call to 1538 SADB_GETSPI. The SADB_ADD message is used in manual keying 1539 applications, and in other cases where the uniqueness of the SPI is 1540 known immediately. 1542 An SADB_ADD message is also used when negotiation is finished, and 1543 the second of a pair of associations is added. The SPI for this 1544 association was determined by the peer machine. The sadb_msg_seq 1545 MUST be set to the value set in a kernel-generated SADB_ACQUIRE so 1546 that both associations in a pair are bound to the same ACQUIRE 1547 request. 1549 The kernel MUST sanity check all used fields in the SA submitted in 1550 a SADB_ADD message before adding the SA to its database and MUST 1551 return EINVAL if any of the values are invalid. 1553 Only SADB_SASTATE_MATURE SAs may be submitted in a SADB_ADD 1554 message. SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is 1555 not sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state. 1556 Therefore, the sadb_sa_state field of all submitted SAs MUST be 1557 SADB_SASTATE_MATURE and the kernel MUST return an error if this is 1558 not true. 1560 The message behavior of the SADB_ADD message is: 1562 Send a SADB_ADD message from a user process to the kernel. 1564 1567 The kernel returns the SADB_ADD message to all listening 1568 processes. 1570 1573 The keying material is not returned on the message from the kernel to 1574 listening sockets because listeners may not have the privileges to see 1575 such keying material. 1577 Errors: 1579 EEXIST The security association that was to be added already 1580 exists. 1581 EINVAL In addition to other possible causes, this error is 1582 returned if sanity checking on the SA values (such 1583 as the keys) fails. 1585 3.1.4 SADB_DELETE 1587 The SADB_DELETE message causes the kernel to delete a Security 1588 Association from the key table. The delete message consists of the 1589 base header followed by the association, and the source and 1590 destination sockaddrs in the address extension. The kernel deletes 1591 the security association matching the type, spi, source address, and 1592 destination address in the message. 1594 The message behavior for SADB_DELETE is as follows: 1596 Send a SADB_DELETE message from a user process to the kernel. 1598 1600 The kernel returns the SADB_DELETE message to all listening 1601 processes. 1603 1605 3.1.5 SADB_GET 1607 The SADB_GET message allows a process to retrieve a copy of a 1608 Security Association from the kernel's key table. The get message 1609 consists of the base header follows by the relevant extension fields. 1610 The Security Association matching the type, spi, source address, and 1611 destination address is returned. 1613 The message behavior of the SADB_GET message is: 1615 Send a SADB_GET message from a user process to the kernel. 1617 1619 The kernel returns the SADB_GET message to the socket that sent 1620 the SADB_GET message. 1622 1625 Errors: 1626 ESRCH The sought security association was not found. 1628 3.1.6 SADB_ACQUIRE 1630 The SADB_ACQUIRE message is typically sent only by the kernel to 1631 key socket listeners who have registered their key socket (see 1632 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 1633 application-level consumers of security associations (such as an 1634 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 1635 message is a base header along with an address extension, possibly an 1636 identity extension, and a proposal extension. The proposed situation 1637 contains a list of desirable algorithms that can be used if the 1638 algorithms in the base header are not available. The values for the 1639 fields in the base header and in the security association data which 1640 follows the base header indicate the properties of the Security 1641 Association that the listening process should attempt to acquire. If 1642 the message originates from the kernel (i.e. the sadb_msg_pid is 0), 1643 the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and 1644 SADB_UPDATE, or subsequent SADB_ADD message to bind a security 1645 association to the request. This avoids the race condition of two 1646 TCP connections between two IP hosts that each require unique 1647 associations, and having one steal another's security association. 1648 The sadb_msg_errno and sadb_msg_state fields should be ignored by the 1649 listening process. 1651 The SADB_ACQUIRE message is typically triggered by an outbound 1652 packet that needs security but for which there is no applicable 1653 Security Association existing in the key table. If the packet can be 1654 sufficiently protected by more than one algorithm or combination of 1655 options, the SADB_ACQUIRE message MUST order the preference of 1656 possibilities in the Proposal extension. 1658 There are three messaging behaviors for SADB_ACQUIRE. The first is 1659 where the kernel needs a security association (e.g. for IPsec). 1661 The kernel sends an SADB_ACQUIRE message to registered sockets. 1663 1666 NOTE: The address(SD) extensions MUST have the port fields 1667 filled in with the port numbers of the session requiring 1668 keys if appropriate. 1670 The second is when, for some reason, key management fails, it can 1671 send an ACQUIRE message with the same sadb_msg_seq as the initial 1672 ACQUIRE with a non-zero errno. 1674 Send an SADB_ACQUIRE to indicate key management failure. 1676 1678 The third is where an application-layer consumer of security 1679 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 1680 association. 1682 Send an SADB_ACQUIRE message from a user process to the kernel. 1684 1687 The kernel returns an SADB_ACQUIRE message to registered sockets. 1689 1692 The user-level consumer waits for a SADB_UPDATE or SADB_ADD 1693 message for its particular type, and then can use that 1694 association by using SADB_GET messages. 1696 Errors: 1697 EINVAL Invalid acquire request. 1698 EPROTONOSUPPORT No KM application has registered with the Key 1699 Engine as being able to obtain the requested SA type, so 1700 the requested SA cannot be acquired. 1702 3.1.7 SADB_REGISTER 1704 The SADB_REGISTER message allows an application to register its key 1705 socket as able to acquire new security associations for the kernel. 1706 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 1707 the type of security association specified in sadb_msg_satype. The 1708 application specifies the type of security association that it can 1709 acquire for the kernel in the type field of its register message. If 1710 an application can acquire multiple types of security association, it 1711 MUST register each type in a separate message. Only the base header 1712 is needed for the register message. Key management applications MAY 1713 register for a type not known to the kernel, because the consumer may 1714 be in user-space (e.g. OSPFv2 security). 1716 The reply of the SADB_REGISTER message contains a supported 1717 algorithm extension. That field contains an array of supported 1718 algorithm, one per octet. This allows key management applications to 1719 know what algorithm are supported by the kernel. 1721 In an environment where algorithms can be dynamically loaded and 1722 unloaded, an asynchronous SADB_REGISTER reply MAY be generated. The 1723 list of supported algorithms MUST be a complete list, so the 1724 application can make note of omissions or additions. 1726 The messaging behavior of the SADB_REGISTER message is: 1728 Send a SADB_REGISTER message from a user process to the kernel. 1730 1732 The kernel returns a SADB_REGISTER message to registered 1733 sockets, with algorithm types supported by the kernel being 1734 indicated in the supported algorithms field. 1736 NOTE: This message may arrive asynchronously due to an 1737 algorithm being loaded or unloaded into a dynamically 1738 linked kernel. 1740 1742 3.1.8 SADB_EXPIRE Message 1744 The operating system kernel is responsible for tracking SA 1745 expirations for security protocols that are implemented inside the 1746 kernel. If the soft limit or hard limit of a Security Association 1747 has expired for a security protocol implemented inside the kernel, 1748 then the kernel MUST issue an SADB_EXPIRE message to all key socket 1749 listeners. If the soft limit or hard limit of a Security Association 1750 for a user-level security protocol has expired, the user-level 1751 protocol SHOULD issue a SADB_EXPIRE message. 1753 The base header will contain the security association information 1754 followed by the source sockaddr, destination sockaddr, (and, if 1755 present, internal sockaddr,) (and, if present, one or both 1756 compartment bitmaps). 1758 The lifetime extension of an SADB_EXPIRE message is important to 1759 indicate which lifetime expired. If a HARD lifetime extension is 1760 included, it indicates that the HARD lifetime expired. This means 1761 the association MAY be deleted already from the SADB. If a SOFT 1762 lifetime extension is included, it indicates that the SOFT lifetime 1763 expired. The CURRENT lifetime extension will indicate the current 1764 status, and comparisons to the HARD or SOFT lifetime will indicate 1765 which limit was reached. HARD lifetimes MUST take precedence over 1766 SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same, 1767 the HARD lifetime will appear on the EXPIRE message. The 1768 pathological case of HARD lifetimes being shorter than SOFT lifetimes 1769 is handled such that the SOFT lifetime will never expire. 1771 The messaging behavior of the SADB_EXPIRE message is: 1773 The kernel sends a SADB_EXPIRE message to all listeners when 1774 the soft limit of a security association has been expired. 1776 1778 Note that the SADB_EXPIRE message is ONLY sent by the kernel to the 1779 KMd. It is a one-way informational message that does not have a 1780 reply. 1782 3.1.9 SADB_FLUSH 1784 The SADB_FLUSH message causes the kernel to delete all entries in 1785 its key table for a certain sadb_msg_satype. Only the base header is 1786 required for a flush message. If sadb_msg_satype is filled in with a 1787 specific value, only associations of that type are deleted. If it is 1788 filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted. 1790 The messaging behavior for SADB_FLUSH is: 1792 Send a SADB_FLUSH message from a user process to the kernel. 1794 1795 The kernel will return a SADB_FLUSH message to all listening 1796 sockets. 1798 1800 The reply message happens only after the actual flushing 1801 of security associations has been attempted. 1803 3.1.10 SADB_DUMP 1805 The SADB_DUMP message causes the kernel to dump the operating 1806 system's entire Key Table to the requesting key socket. As in 1807 SADB_FLUSH, if a sadb_msg_satype value is in the message, only 1808 associations of that type will be dumped. If SADB_SATYPE_UNSPEC is 1809 specified, all associations will be dumped. Each Security Association 1810 is returned in its own SADB_DUMP message. A SADB_DUMP message with a 1811 sadb_seq field of zero indicates the end of the dump transaction. The 1812 dump message is used for debugging purposes only and is not intended 1813 for production use. 1815 Support for the dump message MAY be discontinued in future versions 1816 of PF_KEY. Key management applications MUST NOT depend on this 1817 message for basic operation. 1819 The messaging behavior for SADB_DUMP is: 1821 Send a SADB_DUMP message from a user process to the kernel. 1823 1825 Several SADB_DUMP messages will return from the kernel to the 1826 sending socket. 1828 1831 3.2 Security Association Flags 1833 The Security Association's flags are a bitmask field. These flags 1834 also appear in a combination that is part of a PROPOSAL extension. 1835 The related symbolic definitions below should be used in order that 1836 applications will be portable: 1838 #define SADB_SAFLAGS_PFS 1 /* perfect forward secrecy */ 1840 The SADB_SAFLAGS_PFS flag indicates to key management that this 1841 association should have perfect forward secrecy in its key. (In 1842 other words, any given session key cannot be determined by 1843 cryptanalysis of previous session keys or some master key.) 1845 3.3 Security Association States 1847 The security association state field is an integer that describes 1848 the states of a security association. They are: 1850 #define SADB_SASTATE_LARVAL 0 1851 #define SADB_SASTATE_MATURE 1 1852 #define SADB_SASTATE_DYING 2 1853 #define SADB_SASTATE_DEAD 3 1855 #define SADB_SASTATE_MAX 3 1857 A SADB_SASTATE_LARVAL security association is one that was created 1858 by the SADB_GETSPI message. A SADB_SASTATE_MATURE association is one 1859 that was updated with the SADB_UPDATE message or added with the 1860 SADB_ADD message. A DYING association is one whose soft lifetime has 1861 expired. A SADB_SASTATE_DEAD association is one whose hard lifetime 1862 has expired, but hasn't been reaped by system garbage collection. If 1863 a consumer of security associations has to extend an association 1864 beyond its normal lifetime (e.g. OSPF Security) it MUST only set the 1865 soft lifetime for an association. 1867 3.4 Security Association Types 1869 This defines the type of Security Association in this message. The 1870 symbolic names are always the same, even on different 1871 implementations. Applications SHOULD use the symbolic name in order 1872 to have maximum portability across different implementations. These 1873 are defined in the file . 1875 #define SADB_SATYPE_UNSPEC 0 1877 #define SADB_SATYPE_AH 1 /* RFC-1826 */ 1878 #define SADB_SATYPE_ESP 2 /* RFC-1827 */ 1880 #define SADB_SATYPE_RSVP 3 /* RSVP Authentication */ 1881 #define SADB_SATYPE_OSPFV2 4 /* OSPFv2 Authentication */ 1882 #define SADB_SATYPE_RIPV2 5 /* RIPv2 Authentication */ 1883 #define SADB_SATYPE_MIP 6 /* Mobile IP Auth. */ 1885 #define SADB_SATYPE_MAX 6 1887 SADB_SATYPE_UNSPEC is defined for completeness and means no specific 1888 type of security association. This type is never used with PF_KEY 1889 SAs. 1891 SADB_SATYPE_AH is for the IP Authentication Header [Atk95b]. 1893 SADB_SATYPE_ESP is for the IP Encapsulating Security Payload 1894 [Atk95c]. 1896 SADB_SATYPE_RSVP is for the RSVP Integrity Object [Baker97]. 1898 SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication 1899 [Moy97]. 1901 SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97]. 1903 SADB_SATYPE_MIP is for Mobile IP's authentication extensions 1904 [Perkins97]. 1906 SADB_SATYPE_MAX is always set to the highest valid numeric value. 1907 There MUST not be gaps in the numbering of security types; all 1908 numbers must be used sequentially. 1910 3.5 Algorithm Types 1912 The algorithm type is interpreted in the context of the Security 1913 Association type defined above. The numeric value might vary between 1914 implementations, but the symbolic name MUST NOT vary between 1915 implementations. Applications should use the symbolic name in order 1916 to have maximum portability to various implementations. 1918 Some of the algorithm types defined below might not be standardized 1919 or might be deprecated in the future. To obtain an assignment for a 1920 symbolic name, contact the authors. 1922 The symbols below are defined in . 1924 /* Authentication algorithms */ 1925 #define SADB_AALG_NONE 0 1926 #define SADB_AALG_MD5HMAC 1 1927 #define SADB_AALG_SHA1HMAC 2 1928 #define SADB_AALG_MAX 2 1930 /* Encryption algorithms */ 1931 #define SADB_EALG_NONE 0 1932 #define SADB_EALG_DESCBC 1 1933 #define SADB_EALG_3DESCBC 2 1934 #define SADB_EALG_MAX 2 1936 The algorithm for SADB_AALG_MD5_HMAC is defined in [OG96]. The 1937 algorithm for SADB_AALG_SHA1HMAC is defined in [CG96]. The algorithm 1938 for SADB_EALG_DESCBC is defined in [Hug96]. 1940 3.6 Extension Header Values 1942 To briefly recap the extension header values: 1944 #define SADB_EXT_RESERVED 0 1945 #define SADB_EXT_SA 1 1946 #define SADB_EXT_LIFETIME_CURRENT 2 1947 #define SADB_EXT_LIFETIME_HARD 3 1948 #define SADB_EXT_LIFETIME_SOFT 4 1949 #define SADB_EXT_ADDRESS_SRC 5 1950 #define SADB_EXT_ADDRESS_DST 6 1951 #define SADB_EXT_ADDRESS_PROXY 7 1952 #define SADB_EXT_KEY_AUTH 8 1953 #define SADB_EXT_KEY_ENCRYPT 9 1954 #define SADB_EXT_IDENTITY_SRC 10 1955 #define SADB_EXT_IDENTITY_DST 11 1956 #define SADB_EXT_SENSITIVITY 12 1957 #define SADB_EXT_PROPOSAL 13 1958 #define SADB_EXT_SUPPORTED_AUTH 14 1959 #define SADB_EXT_SUPPORTED_ENCRYPT 15 1960 #define SADB_EXT_SPIRANGE 16 1962 #define SADB_EXT_MAX 16 1964 3.7 Identity Extension Values 1966 Each identity can have a certain type. 1968 #define SADB_IDENTTYPE_RESERVED 0 1969 #define SADB_IDENTTYPE_PREFIX 1 1970 #define SADB_IDENTTYPE_FQDN 2 1971 #define SADB_IDENTTYPE_USERFQDN 3 1973 #define SADB_IDENTTYPE_MAX 3 1975 The PREFIX identity string consists of a network address followed 1976 by a forward slash and a prefix length. The network address is in a 1977 printable numeric form appropriate for the protocol family. The 1978 prefix length is a decimal number greater than or equal to zero and 1979 less than the number of bits in the network address. It indicates the 1980 number of bits in the network address that are significant; all bits 1981 in the network address that are not significant MUST be set to zero. 1982 Note that implementations MUST parse the contents of the printable 1983 address into a binary form for comparison purposes because multiple 1984 printable strings are valid representations of the same address in 1985 many protocol families (for example, some allow leading zeros and 1986 some have letters that are case insensitive). Examples of PREFIX 1987 identities are "199.33.248.64/27" and 1988 "5f00:3000:c721::f800:19:1/128". If the source or destination 1989 identity is a PREFIX identity, the source or destination address for 1990 the SA (respectively) MUST be within that prefix. The sadb_ident_id 1991 field is zeroed for these identity types. 1993 The FQDN identity string contains a fully qualified domain name. An 1994 example FQDN identity is "ministry-of-truth.inner.net". The 1995 sadb_ident_id field is zeroed for these identity types. 1997 The UserFQDN identity consists of a text string in the format 1998 commonly used for Internet-standard electronic mail. The syntax is 1999 the text username, followed by the "@" character, followed in turn by 2000 the appropriate fully qualified domain name. This identity specifies 2001 both a username and an associated FQDN. There is no requirement that 2002 this string specify a mailbox valid for SMTP or other electronic mail 2003 use. This identity is useful with protocols supporting user-oriented 2004 keying. It is a convenient identity form because the DNS Security 2005 extensions can be used to distribute signed public key values by 2006 associating KEY and SIG records with an appropriate MB DNS record. An 2007 example UserFQDN identity is "julia@ministry-of-love.inner.net". The 2008 sadb_ident_id field is used to contain a POSIX user id in the absence 2009 of an identity string itself so that a user-level application can use 2010 the getpwuid{,_r}() routine to obtain a textual user login id. If a 2011 string is present, it SHOULD match the numeric value in the 2012 sadb_ident_id field. If it does not match, the string SHOULD 2013 override the numeric value. 2015 3.8 Sensitivity Extension Values 2017 The only field currently defined in the sensitivity extension is 2018 the sadb_sens_dpd, which represents the data protection domain. The 2019 other data in the sensitivity extension is based off the 2020 sadb_sens_dpd value. 2022 The DP/DOI is defined to be the same as the "Labeled Domain 2023 Identifier Value" of the IP Security DOI specification [Piper97]. As 2024 noted in that specification, values in the range 0x80000000 to 2025 0xffffffff (inclusive) are reserved for private use and values in the 2026 range 0x00000001 through 0x7fffffff are assigned by IANA. The all- 2027 zeros DP/DOI value is permanently reserved to mean that "no DP/DOI is 2028 in use". 2030 3.9 Proposal Extension Values 2032 These are already mentioned in the ALGORITHM TYPES and ASSOCIATION 2033 FLAGS sections. 2035 4 Future Directions 2037 While the current specification for the Sensitivity and Integrity 2038 Labels is believed to be general enough, if a case should arise that 2039 can't work with the current specification then this might cause a 2040 change in a future version of PF_KEY. 2042 Similarly, PF_KEY might need extensions to work with other kinds of 2043 Security Associations in future. It is strongly desirable for such 2044 extensions to be made in a backwards-compatible manner should they be 2045 needed. 2047 When more experience is gained with certificate management, it is 2048 possible that the IDENTITY extension will have to be revisited to 2049 allow a finer grained selection of certificate identities. 2051 5 Examples 2053 The following examples illustrate how PF_KEY is used. The first 2054 example is an IP Security example, where the consumer of the security 2055 associations is inside an operating system kernel. The second example 2056 is an OSPF Security example, which illustrates a user-level consumer 2057 of security associations. The third example covers things not 2058 mentioned by the first two examples. A real system may closely 2059 conform to one of these examples, or take parts of them. These 2060 examples are purely illustrative, and are not intended to mandate a 2061 particular implementation method. 2063 5.1 Simple IP Security Example 2065 +---------------+ +-------------+ 2066 |Key Mgmt Daemon| | Application | 2067 +---------------+ +-------------+ 2068 | | / 2069 | | / 2070 | | | Applications 2071 ======[PF_KEY]====[PF_INET]========================== 2072 | | | OS Kernel 2073 +------------+ +-----------------+ 2074 | Key Engine | | TCP/IP, | 2075 | or SADB |---| including IPsec | 2076 +------------+ | | 2077 +-----------------+ 2079 When the Key Management daemon (KMd) begins. It must tell PF_KEY 2080 that it is willing to accept message for the two IPsec services, AH 2081 and ESP. It does this by sending down two SADB_REGISTER messages. 2083 KMd->Kernel: SADB_REGISTER for ESP 2084 Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms 2085 KMd->Kernel: SADB_REGISTER for AH 2086 Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms 2088 Each REGISTER message will cause a reply to go to all PF_KEY sockets 2089 registered for ESP and AH respectively (including the requester). 2091 Assume that no security associations currently exist for IPsec to 2092 use. Consider when a network application begins transmitting data 2093 (e.g. a TCP SYN). Because of policy, or the application's request, 2094 the kernel IPsec module needs an AH security association for this 2095 data. Since there is not one present, the following message is 2096 generated: 2098 Kernel->Registered: SADB_ACQUIRE for AH, addrs, ID, sens, 2099 proposals 2101 The KMd reads the ACQUIRE message, especially the sadb_msg_seq 2102 number. Before it begins the negotiation, it sends down an 2103 SADB_GETSPI message with the sadb_msg_seq number equal to the one 2104 received in the ACQUIRE. The kernel returns the results of the 2105 GETSPI to all listening sockets. 2107 KMd->Kernel: SADB_GETSPI for AH, addr, SPI range 2108 Kernel->All: SADB_GETSPI for AH, assoc, addrs 2110 The KMd may perform a second GETSPI operation if it needs both 2111 directions of IPsec SPI values. Now that the KMd has an SPI for at 2112 least one of the security associations, it begins negotiation. After 2113 deriving keying material, and negotiating other parameters, it sends 2114 down one (or more) SADB_UPDATE messages with the same value in 2115 sadb_msg_seq. 2117 If a KMd has any error at all during its negotiation, it can send 2118 down 2120 KMd->Kernel: SADB_UPDATE for AH, assoc (with an error) 2121 Kernel->All: SADB_UPDATE for AH, assoc (same error) 2123 but if it succeeds, it can instead 2125 KMd->Kernel: SADB_UPDATE for AH, assoc, addrs, keys, 2126 2127 Kernel->All: SADB_UPDATE for AH, assoc, addrs, 2129 The results of the UPDATE (minus the actual keys) are sent to all 2130 listening sockets. If only one SPI value was determined locally, the 2131 other SPI (since IPsec SAs are unidirectional) must be added with an 2132 SADB_ADD message. 2134 KMd->Kernel: SADB_ADD for AH, assoc, addrs, keys, 2135 Kernel->All: SADB_ADD for AH, assoc, addrs, 2137 If one of the extensions passed down was a Lifetime extension, it 2138 is possible at some point an SADB_EXPIRE message will arrive when one 2139 of the lifetimes has expired. 2141 Kernel->All: SADB_EXPIRE for AH, assoc, addrs, 2142 Hard or Soft, Current, 2144 The KMd can use this as a clue to begin negotiation, or, if it has 2145 some say in policy, send an SADB_UPDATE down with a lifetime 2146 extension. 2148 5.2 Proxy IP Security Example 2150 Many people are interested in using IP Security in a "proxy" 2151 or "firewall" configuration in which an intermediate system provides 2152 security services for "inside" hosts. In these environments, the 2153 intermediate systems can use PF_KEY to communicate with key 2154 management applications almost exactly as they would if they were the 2155 actual endpoints. The messaging behavior of PF_KEY in these cases is 2156 exactly the same as the previous example, but the address information 2157 is slightly different. 2159 Consider this case: 2161 A ========= B --------- C 2163 Key: 2164 A "outside" host that implements IPsec 2165 B "firewall" that implements IPsec 2166 C "inside" host that does not implement IPsec 2168 === IP_{A<->B} ESP [ IP_{A<->C} ULP ] 2169 --- IP_{A<->C} ULP 2171 A is a single system that wishes to communicate with the "inside" 2172 system C. B is a "firewall" between C and the outside world that 2173 will do ESP and tunneling on C's behalf. A discovers that it needs 2174 to send traffic to C via B through methods not described here (Use of 2175 the DNS' KX record might be one method for discovering this). 2177 For packets that flow from left to right, A and B need an 2178 IPsec Security Association with: 2180 SA type of ESP tunnel-mode 2181 Source Identity that dominates A (e.g. A's address) 2182 Destination Identity that dominates B (e.g. B's address) 2183 No Proxy Identity or a Proxy Identity that dominates A. 2185 For packets to flow from right to left, A and B need an IPsec 2186 Security Association with: 2187 SA type of ESP tunnel-mode 2188 Source Identity that dominates C. 2189 Destination Identity that dominates A. 2190 Proxy Identity that dominates B. 2192 For this second SA (for packets flowing from C towards A), node A 2193 MUST verify that the outer source address is dominated by the Proxy 2194 Identity for the SA used with those packets. If node A does not do 2195 this, node B could forge packets with an arbitrary Source Identity 2196 and defeat the packet origin protections provided by IPsec. 2198 Now consider a slightly more complex case: 2200 A_1 --| |-- D_1 2201 |--- B ====== C ---| 2202 A_2 --| |-- D_2 2204 Key: 2205 A_n "inside" host on net 1 that does not do IPsec. 2206 B "firewall" for net 1 that supports IPsec. 2207 C "firewall" for net 2 that supports IPsec. 2208 D_n "inside" host on net 2 that does not do IPsec. 2209 === IP_{B<->C} ESP [ IP_{A<->C} ULP ] 2210 --- IP_{A<->C} ULP 2212 For A_1 to send a packet to D_1, B and C need a SA with: 2214 SA Type of ESP 2215 Source Identity that dominates A_1. 2216 Destination Identity that dominates C. 2217 Proxy Identity that dominates B. 2219 For D_1 to send a packet to A_1, C and B need a SA with: 2220 SA Type of ESP Tunnel-mode 2221 Source Identity that dominates D_1. 2222 Destination Identity that dominates B. 2223 Proxy Identity that dominates C. 2225 Note that A_2 and D_2 could be substituted for A_1 and D_1 2226 (respectively) here; the association of an SA with a particular pair 2227 of ends or group of those pairs is a policy decision on B and/or C 2228 and not necessarily a function of key management. The same check of 2229 the Proxy Identity against the outer source IP address MUST also be 2230 performed in this case for the same reason. 2232 For a more detailed discussion of the use of IP Security in complex 2233 cases, please see [Atk97]. 2235 NOTE: The notion of identity domination might be unfamiliar. 2236 Let H represent some node. Let Hn represent H's fully qualified 2237 domain name. Let Ha represent the IP address of H. Let Hs 2238 represent the IP subnet containing Ha. Let Hd represent a fully 2239 qualified domain name that is a parent of the fully qualified 2240 domain name of H. Let M be a UserFQDN identity that whose right- 2241 hand part is Hn or Ha. 2243 Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the 2244 example above. Hs dominates any node having an IP address 2245 within the IP address range represented by Hs. Hd dominates any 2246 node having a fully qualified domain name within underneath Hd. 2248 5.3 OSPF Security Example 2250 +---------------+ +-------------+ 2251 |Key Mgmt Daemon| | OSPF daemon | 2252 +---------------+ +-------------+ 2253 | | / / | 2254 | /------|----+ / | 2255 | / | +---+ | Applications 2256 ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================ 2257 | | | | OS Kernel 2258 +------------+ +-----------------+ +---------+ 2259 | Key Engine | | TCP/IP, | | Routing | 2260 | or SADB |---| including IPsec |--| Table | 2261 +------------+ | | +---------+ 2262 +-----------------+ 2264 As in the previous examples, the KMd registers itself with the Key 2265 Engine via PF_KEY. Even though the consumer of the security 2266 associations is in user-space, the PF_KEY and Key Engine 2267 implementation knows enough to store SAs and to relay messages. 2269 When the OSPF daemon needs to communicate securely with its peers, 2270 it would perform an SADB_GET message and retrieve the appropriate 2271 association: 2273 OSPFd->Kernel: SADB_GET of OSPF, assoc, addrs 2274 Kernel->OSPFd: SADB_GET of OSPF, assoc, addrs, keys, 2276 If this GET fails, the OSPFd may need to acquire a new security 2277 association. This interaction is as follows: 2279 OSPFd->Kernel: SADB_ACQUIRE of OSPF, addrs, 2280 proposal 2281 Kernel->Registered: SADB_ACQUIRE of OSPF, 2283 The KMd sees this and performs actions similar to the previous 2284 example. One difference, however, is that when the UPDATE message 2285 comes back, the OSPFd will then perform a GET of the updated SA to 2286 retrieve all of its parameters. 2288 5.4 Miscellaneous 2290 Some messages work well only in system maintenance programs, for 2292 debugging, or for auditing. In a system panic situation, such as a 2293 detected compromise, an SADB_FLUSH message should be issued for a 2294 particular SA type, or for ALL SA types. 2296 Program->Kernel: SADB_FLUSH for ALL 2297 2298 Kernel->All: SADB_FLUSH for ALL 2300 Some SAs may need to be explicitly deleted, either by a KMd, or by 2301 a system maintenance program. 2303 Program->Kernel: SADB_DELETE for AH, association, addrs 2304 Kernel->All: SADB_DELETE for AH, association, addrs 2306 Common usage of the SADB_DUMP message is discouraged. For 2307 debugging purposes, however, it can be quite useful. The output of a 2308 DUMP message should be read quickly, in order to avoid socket buffer 2309 overflows. 2311 Program->Kernel: SADB_DUMP for ESP 2312 Kernel->Program: SADB_DUMP for ESP, association, 2313 Kernel->Program: SADB_DUMP for ESP, association, 2314 Kernel->Program: SADB_DUMP for ESP, association, 2315 2317 6 Security Considerations 2319 This draft discusses a method for creating, reading, modifying, and 2320 deleting Security Associations from an operating system. Only 2321 trusted, privileged users and processes should be able to perform any 2322 of these operations. It is unclear whether this mechanism provides 2323 any security when used with operating systems not having the concept 2324 of a trusted, privileged user. 2326 If an unprivileged user is able to perform any of these operations, 2327 then the operating system cannot actually provide the related 2328 security services. If an adversary knows the keys and algorithms in 2329 use, then cryptography cannot provide any form of protection. 2331 This mechanism is not a panacea, but it does provide an important 2332 operating system component that can be useful in creating a secure 2333 internetwork. 2335 Users need to understand that the quality of the security provided 2336 by an implementation of this specification depends completely upon 2337 the overall security of the operating system, the correctness of the 2338 PF_KEY implementation, and upon the security and correctness of the 2339 applications that connect to PF_KEY. It is appropriate to use high 2340 assurance development techniques when implementing PF_KEY and the 2341 related security association components of the operating system. 2343 Acknowledgments 2345 The authors of this document are listed primarily in alphabetical 2346 order. Randall Atkinson and Ron Lee provided useful feedback on 2347 earlier versions of this document. 2349 At one time or other, all of the authors worked at the Center for 2350 High Assurance Computer Systems at the U.S. Naval Research 2351 Laboratory. This work was sponsored by the Information Security 2352 Program Office (PMW-161), U.S. Space and Naval Warfare Systems 2353 Command (SPAWAR) and the Computing Systems Technology Office, Defense 2354 Advanced Research Projects Agency (DARPA/CSTO). We really appreciate 2355 their sponsorship of our efforts and their continued support of 2356 PF_KEY development. Without that support, PF_KEY would not exist. 2358 The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST97]. 2360 Finally, the authors would like to thank those who sent in comments 2361 and questions on the various iterations of this document. This 2362 specification and implementations of it are discussed on the PF_KEY 2363 mailing list. If you would like to be added to this list, send a note 2364 to . 2366 References 2368 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig 2369 W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 2370 4.4-Lite BSD", Proceedings of the 1996 USENIX Conference, 2371 San Diego, CA, January 1996, USENIX Association. 2373 [Atk95a] Randall J. Atkinson, "IP Security Architecture", RFC 1825, 2374 August 1995. 2376 [Atk95b] Randall J. Atkinson, "IP Authentication Header", RFC 1826, 2377 August 1995. 2379 [Atk95c] Randall J. Atkinson, "IP Encapsulating Security Payload", 2380 RFC 1827, August 1995. 2382 [Atk97] Atkinson, Randall, "Key Exchange Delegation Record for the 2383 Domain Name System", Internet-draft, June 1997." 2385 [BA97] F. Baker and R. Atkinson, "RIP-2 MD5 Authentication", 2386 RFC 2082, January 1997. 2388 [Baker97] Fred Baker, "RSVP Cryptographic Authentication", Internet 2389 Draft, May 1997. 2391 [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer 2392 Systems", MTR-3153, The MITRE Corporation, June 1975; 2393 ESD-TR-76-372, April 1977. 2395 [BL74] D. Elliot Bell and Leonard J. LaPadula, "Secure Computer 2396 Systems: Unified Exposition and Multics Interpretation", 2397 MTR 2997, The MITRE Corporation, April 1974. (AD/A 020 445) 2399 [CG96] S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with 2400 Replay Prevention", Internet Draft, May 1996. 2402 [CW87] D. D. Clark and D. R. Wilson, "A Comparison of Commercial 2403 and Military Computer Security Policies", Proceedings of the 2404 1987 Symposium on Security and Privacy, pp. 184-195, IEEE 2405 Computer Society, Washington, D.C., 1987 2407 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 2408 Workstation Specification", Technical Report 2409 DDS-2600-6243-87. 2411 [DMS97] Dorsaway, N., Metzger, P., Simpson, W. A., "The ESP Triple- 2412 DES Transform," Internet-Draft. 2414 [HM97a] H. Harney, C. Muckenhirn, "Group Key Management Protocol 2415 (GKMP) Specification", RFC 2093, July 1997. 2417 [HM97b] H. Harney, C. Muckenhirn, "Group Key Management Protocol 2418 (GKMP) Architecture", RFC 2094, July 1997. 2420 [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay 2421 Prevention Security Transform", Internet Draft, April 1996. 2423 [MSST97] Douglas Maughan, Mark Schertler, Mark Schneider, Jeff 2424 Turner, "Internet Security Association and Key Management 2425 Protocol (ISAKMP)", Internet Draft, February 1997. 2427 [Moy97] J. Moy, "OSPF Version 2", Internet Draft, April 1997. 2429 [OG96] Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with 2430 Replay Prevention", Internet Draft, May 1996. 2432 [Perkins97] C. Perkins, "IP Mobility Support", RFC 2002, 2433 October 1996. 2435 [Piper97] Derrel Piper, "The Internet IP Security Domain of 2436 Interpretation for ISAKMP", Internet Draft, February 1997. 2438 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for 2439 Berkeley UNIX", Proceedings of the Winter 1991 USENIX 2440 Conference, Dallas, TX, USENIX Association. 1991. 2441 pp. 93-103. 2443 Disclaimer 2445 The views and specification here are those of the editors and are 2446 not necessarily those of their employers. The employers have not 2447 passed judgment on the merits, if any, of this work. The editors and 2448 their employers specifically disclaim responsibility for any problems 2449 arising from correct or incorrect implementation or use of this 2450 specification. 2452 Authors' Addresses 2454 Daniel L. McDonald 2455 Sun Microsystems, Inc. 2456 901 San Antonio Road, MS UMPK17-202 2457 Palo Alto, CA 94303 2458 E-mail: danmcd@eng.sun.com 2460 Craig Metz 2461 The Inner Net 2462 Box 10314-1932 2463 Blacksburg, VA 24062-0314 2464 DSN: 754-8590 2465 E-mail: cmetz@inner.net 2467 Bao G. Phan 2468 U. S. Naval Research Laboratory 2469 phan@itd.nrl.navy.mil 2471 Appendix A: Promiscuous Send/Receive Extension 2473 A kernel supporting PF_KEY MAY implement the following extension 2474 for development and debugging purposes. If it does, it MUST implement 2475 the extension as specified here. An implementation MAY require an 2476 application to have additional privileges to perform promiscuous send 2477 and/or receive operations. 2479 The SADB_X_PROMISC message allows an application to send and 2480 receive messages in a "promiscuous mode." There are two forms of this 2481 message: control and data. The control form consists of only a 2482 message header. This message is used to toggle the promiscuous- 2483 receive function. A value of one in the sadb_msg_satype field enables 2484 promiscuous message reception for this socket, while a value of zero 2485 in that field disables it. 2487 The second form of this message is the data form. This is used to 2488 send or receive messages in their raw form. Messages in the data form 2489 consist of a message header followed by an entire new message. There 2490 will be two message headers in a row: one for the SADB_X_PROMISC 2491 message, and one for the payload message. 2493 Data messages sent from the application are sent to either the 2494 PF_KEY socket of a single process identified by a nonzero 2495 sadb_msg_seq or to all PF_KEY sockets if sadb_msg_seq is zero. These 2496 messages are sent without any processing of their contents by the 2497 PF_KEY interface (including sanity checking). This promiscuous-send 2498 capability allows an application to send messages as if it were the 2499 kernel. This also allows it to send erroneous messages. 2501 If the promiscuous-receive function has been enabled, a copy of any 2502 message sent via PF_KEY by another application or by the kernel is 2503 sent to the promiscuous application. This is done before any 2504 processing of the message's contents by the PF_KEY interface (again, 2505 including sanity checking). This promiscuous-receive capability 2506 allows an application to receive all messages sent by other parties 2507 using PF_KEY. 2509 The messaging behavior of the SADB_X_PROMISC message is: 2511 Send a control-form SADB_X_PROMISC message from a user process 2512 to the kernel. 2514 2516 The kernel returns the SADB_X_PROMISC message to all listening 2517 processes. 2519 2521 Send a data-form SADB_X_PROMISC message from a user process to 2522 the kernel. 2524 2526 The kernel sends the encapsulated message to the target 2527 process(s). 2529 2531 If promiscuous-receive is enabled, the kernel will encapsulate 2532 and send copies of all messages sent via the PF_KEY interface. 2534 2536 Errors: 2537 EPERM Additional privileges are required to perform the 2538 requested operations. 2539 ESRCH (Data form, sending) The target process in sadb_msg_seq 2540 does not exist or does not have an open PF_KEY Version 2 2541 socket. 2543 Appendix B: Passive Change Message Extension 2545 The SADB_X_PCHANGE message is a passive-side (aka. the "listener" 2546 or "receiver") counterpart to the SADB_ACQUIRE message. It is useful 2547 for when key management applications wish to more effectively handle 2548 incoming key management requests for passive-side sessions that 2549 deviate from systemwide default security services. If a passive 2550 session requests that only certain levels of security service be 2551 allowed, the SADB_X_PCHANGE message expresses this change to any 2552 registered PF_KEY sockets. Unlike SADB_ACQUIRE, this message is 2553 purely informational, and demands no other PF_KEY interaction. 2555 The SADB_X_PCHANGE message is typically triggered by either a 2556 change in an endpoint's requested security services, or when an 2557 endpoint that made a special request disappears. In the former case, 2558 an SADB_X_PCHANGE looks like an SADB_ACQUIRE, complete with an 2559 sadb_proposal extension indicating the preferred algorithms, 2560 lifetimes, and other attributes. When a passive session either 2561 disappears, or reverts to a default behavior, an SADB_X_PCHANGE will 2562 be issued with _no_ sadb_proposal extension, indicating that the 2563 exception to systemwide default behavior has disappeared. 2565 There are two messaging behaviors for SADB_X_PCHANGE. The first is 2566 the kernel-originated case: 2568 The kernel sends an SADB_X_PCHANGE message to registered sockets. 2569 n 2570 2572 NOTE: The address(SD) extensions MUST have the port fields 2573 filled in with the port numbers of the session requiring 2574 keys if appropriate. 2576 The second is for a user-level consumer of SAs. 2578 Send an SADB_X_PCHANGE message from a user process to the kernel. 2580 2582 The kernel returns an SADB_X_PCHANGE message to registered sockets. 2584 2586 Appendix C: Sample Header File 2588 /* 2589 This file defines structures and symbols for the PF_KEY Version 2 2590 key management interface. It was written at the U.S. Naval Research 2591 Laboratory. This file is in the public domain. The authors ask that 2592 you leave this credit intact on any copies of this file. 2593 */ 2594 #ifndef __PFKEY_V2_H 2595 #define __PFKEY_V2_H 1 2597 #define PF_KEY_V2 2 2598 #define PFKEYV2_REVISION 199802L 2600 #define SADB_RESERVED 0 2601 #define SADB_GETSPI 1 2602 #define SADB_UPDATE 2 2603 #define SADB_ADD 3 2604 #define SADB_DELETE 4 2605 #define SADB_GET 5 2606 #define SADB_ACQUIRE 6 2607 #define SADB_REGISTER 7 2608 #define SADB_EXPIRE 8 2609 #define SADB_FLUSH 9 2610 #define SADB_DUMP 10 2611 #define SADB_X_PROMISC 11 2612 #define SADB_X_PCHANGE 12 2613 #define SADB_MAX 12 2615 struct sadb_msg { 2616 uint8_t sadb_msg_version; 2617 uint8_t sadb_msg_type; 2618 uint8_t sadb_msg_errno; 2619 uint8_t sadb_msg_satype; 2620 uint16_t sadb_msg_len; 2621 uint16_t sadb_msg_reserved; 2622 uint32_t sadb_msg_seq; 2623 uint32_t sadb_msg_pid; 2624 }; 2626 struct sadb_ext { 2627 uint16_t sadb_ext_len; 2628 uint16_t sadb_ext_type; 2629 }; 2630 struct sadb_sa { 2631 uint16_t sadb_sa_len; 2632 uint16_t sadb_sa_exttype; 2633 uint32_t sadb_sa_spi; 2634 uint8_t sadb_sa_replay; 2635 uint8_t sadb_sa_state; 2636 uint8_t sadb_sa_auth; 2637 uint8_t sadb_sa_encrypt; 2638 uint32_t sadb_sa_flags; 2639 }; 2641 struct sadb_lifetime { 2642 uint16_t sadb_lifetime_len; 2643 uint16_t sadb_lifetime_exttype; 2644 uint32_t sadb_lifetime_allocations; 2645 uint64_t sadb_lifetime_bytes; 2646 uint64_t sadb_lifetime_addtime; 2647 uint64_t sadb_lifetime_usetime; 2648 }; 2650 struct sadb_address { 2651 uint16_t sadb_address_len; 2652 uint16_t sadb_address_exttype; 2653 uint8_t sadb_address_proto; 2654 uint8_t sadb_address_prefixlen; 2655 uint16_t sadb_address_reserved; 2656 }; 2658 struct sadb_key { 2659 uint16_t sadb_key_len; 2660 uint16_t sadb_key_exttype; 2661 uint16_t sadb_key_bits; 2662 uint16_t sadb_key_reserved; 2663 }; 2665 struct sadb_ident { 2666 uint16_t sadb_ident_len; 2667 uint16_t sadb_ident_exttype; 2668 uint16_t sadb_ident_type; 2669 uint16_t sadb_ident_reserved; 2670 uint64_t sadb_ident_id; 2671 }; 2672 struct sadb_sens { 2673 uint16_t sadb_sens_len; 2674 uint16_t sadb_sens_exttype; 2675 uint32_t sadb_sens_dpd; 2676 uint8_t sadb_sens_sens_level; 2677 uint8_t sadb_sens_sens_len; 2678 uint8_t sadb_sens_integ_level; 2679 uint8_t sadb_sens_integ_len; 2680 uint32_t sadb_sens_reserved; 2681 }; 2683 struct sadb_prop { 2684 uint16_t sadb_prop_len; 2685 uint16_t sadb_prop_exttype; 2686 uint8_t sadb_prop_replay; 2687 uint8_t sadb_prop_reserved[3]; 2688 }; 2690 struct sadb_comb { 2691 uint8_t sadb_comb_auth; 2692 uint8_t sadb_comb_encrypt; 2693 uint16_t sadb_comb_flags; 2694 uint16_t sadb_comb_auth_minbits; 2695 uint16_t sadb_comb_auth_maxbits; 2696 uint16_t sadb_comb_encrypt_minbits; 2697 uint16_t sadb_comb_encrypt_maxbits; 2698 uint32_t sadb_comb_reserved; 2699 uint32_t sadb_comb_soft_allocations; 2700 uint32_t sadb_comb_hard_allocations; 2701 uint64_t sadb_comb_soft_bytes; 2702 uint64_t sadb_comb_hard_bytes; 2703 uint64_t sadb_comb_soft_addtime; 2704 uint64_t sadb_comb_hard_addtime; 2705 uint64_t sadb_comb_soft_usetime; 2706 uint64_t sadb_comb_hard_usetime; 2707 }; 2708 struct sadb_supported { 2709 uint16_t sadb_supported_len; 2710 uint16_t sadb_supported_exttype; 2711 uint32_t sadb_supported_reserved; 2712 }; 2714 struct sadb_alg { 2715 uint8_t sadb_alg_id; 2716 uint8_t sadb_alg_ivlen; 2717 uint16_t sadb_alg_minbits; 2718 uint16_t sadb_alg_maxbits; 2719 uint16_t sadb_alg_reserved; 2720 }; 2722 struct sadb_spirange { 2723 uint16_t sadb_spirange_len; 2724 uint16_t sadb_spirange_exttype; 2725 uint32_t sadb_spirange_min; 2726 uint32_t sadb_spirange_max; 2727 uint32_t sadb_spirange_reserved; 2728 }; 2730 #define SADB_EXT_RESERVED 0 2731 #define SADB_EXT_SA 1 2732 #define SADB_EXT_LIFETIME_CURRENT 2 2733 #define SADB_EXT_LIFETIME_HARD 3 2734 #define SADB_EXT_LIFETIME_SOFT 4 2735 #define SADB_EXT_ADDRESS_SRC 5 2736 #define SADB_EXT_ADDRESS_DST 6 2737 #define SADB_EXT_ADDRESS_PROXY 7 2738 #define SADB_EXT_KEY_AUTH 8 2739 #define SADB_EXT_KEY_ENCRYPT 9 2740 #define SADB_EXT_IDENTITY_SRC 10 2741 #define SADB_EXT_IDENTITY_DST 11 2742 #define SADB_EXT_SENSITIVITY 12 2743 #define SADB_EXT_PROPOSAL 13 2744 #define SADB_EXT_SUPPORTED_AUTH 14 2745 #define SADB_EXT_SUPPORTED_ENCRYPT 15 2746 #define SADB_EXT_SPIRANGE 16 2747 #define SADB_EXT_MAX 16 2749 #define SADB_SATYPE_UNSPEC 0 2750 #define SADB_SATYPE_AH 1 2751 #define SADB_SATYPE_ESP 2 2752 #define SADB_SATYPE_RSVP 3 2753 #define SADB_SATYPE_OSPFV2 4 2754 #define SADB_SATYPE_RIPV2 5 2755 #define SADB_SATYPE_MIP 6 2756 #define SADB_SATYPE_MAX 6 2758 #define SADB_SASTATE_LARVAL 0 2759 #define SADB_SASTATE_MATURE 1 2760 #define SADB_SASTATE_DYING 2 2761 #define SADB_SASTATE_DEAD 3 2762 #define SADB_SASTATE_MAX 3 2764 #define SADB_SAFLAGS_PFS 1 2766 #define SADB_AALG_NONE 0 2767 #define SADB_AALG_MD5HMAC 1 2768 #define SADB_AALG_SHA1HMAC 2 2769 #define SADB_AALG_MAX 2 2771 #define SADB_EALG_NONE 0 2772 #define SADB_EALG_DESCBC 1 2773 #define SADB_EALG_3DESCBC 2 2774 #define SADB_EALG_MAX 2 2776 #define SADB_IDENTTYPE_RESERVED 0 2777 #define SADB_IDENTTYPE_PREFIX 1 2778 #define SADB_IDENTTYPE_FQDN 2 2779 #define SADB_IDENTTYPE_USERFQDN 3 2780 #define SADB_IDENTTYPE_MAX 3 2782 #define SADB_KEY_FLAGS_MAX 0 2783 #endif /* __PFKEY_V2_H */ 2785 Appendix D: Change Log 2787 The following changes were made between 04 and 05: 2789 * New appendix on Passive Change message. 2791 * New sadb_address_prefixlen field. 2793 * Small clarifications on sadb_ident_id usage. 2795 * New PFKEYV2_REVISION value. 2797 * Small clarification on what a PROXY address is. 2799 * Corrected sadb_spirange_{min,max} language. 2801 * In ADD messages that are in response to an ACQUIRE, the sadb_msg_seq MUST 2802 be the same as that of the originating ACQUIRE. 2804 * Corrected ACQUIRE message behavior, ACQUIRE message SHOULD send up PROXY 2805 addresses when it needs them. 2807 * Clarification on SADB_EXPIRE and user-level security protocols. 2809 The following changes were made between 03 and 04: 2811 * Stronger language about manual keying. 2813 * PFKEYV2_REVISION, ala POSIX. 2815 * Put in language about sockaddr ports in ACQUIRE messages. 2817 * Mention of asymmetric algorithms. 2819 * New sadb_ident_id field for easier construction of USER_FQDN identity 2820 strings. 2822 * Caveat about source addresses not always used for collision detection. 2823 (e.g. IPsec) 2825 The following changes were made between 02 and 03: 2827 * Formatting changes. 2829 * Many editorial cleanups, rewordings, clarifications. 2831 * Restrictions that prevent many strange and invalid cases. 2833 * Added definitions section. 2835 * Removed connection identity type (this will reappear when it is 2836 more clear what it should look like). 2838 * Removed 5.2.1 (Why involve the kernel?). 2840 * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed 2841 from src, dst, and proxy and you had to anyway for sanity checking. 2843 * Removed REPLAY flag; sadb_sa_replay==0 means the same thing. 2845 * Renamed bit lengths to "bits" to avoid potential confusion. 2847 * Explicitly listed lengths for structures. 2849 * Reworked identities to always use a string format. 2851 * Removed requirements for support of shutdown() and SO_USELOOPBACK. 2853 * 64 bit alignment and 64 bit lengths instead of 32 bit. 2855 * time_t replaced with uint64 in lifetimes. 2857 * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER 2858 FILE). 2860 * Explicit error if PF_KEY_V2 not set at socket() call. 2862 * More text on SO_USELOOPBACK. 2864 * Made fields names and symbol names more consistent. 2866 * Explicit error if PF_KEY_V2 is not in sadb_msg_version field. 2868 * Bytes lifetime field now a 64-bit quantity. 2870 * Explicit len/exttype wording. 2872 * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.) 2874 * UI example (0x123 == 0x1230 or 0x0123). 2876 * Cleaned up and fixed some message behavior examples. 2878 The following changes were made between 01 and 02: 2880 * Mentioned that people COULD use these same messages between user 2881 progs. (Also mentioned why you still might want to use the actual 2882 socket.) 2884 * Various wordsmithing changes. 2886 * Took out netkey/ directory, and make net/pfkeyv2.h 2888 * Inserted PF_KEY_V2 proto argument per C. Metz. 2890 * Mentioned other socket calls and how their PF_KEY behavior is 2891 undefined. 2893 * SADB_EXPIRE now communicates both hard and soft lifetime expires. 2895 * New "association" extension, even smaller base header. 2897 * Lifetime extension improvements. 2899 * Length now first in extensions. 2901 * Errors can be sent from kernel to user, also. 2903 * Examples section inserted. 2905 * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup. 2907 * Key splitting now only across auth algorithm and encryption 2908 algorithm. Thanks for B. Sommerfeld for clues here. 2910 The following changes were made between 00 and 01: 2912 * Added this change log. 2914 * Simplified TLV header syntax. 2916 * Splitting of algorithms. This may be controversial, but it allows 2917 PF_KEY to be used for more than just IPsec. It also allows some 2918 kinds of policies to be placed in the KMd easier. 2920 * Added solid definitions and formats for certificate identities, 2921 multiple keys, etc. 2923 * Specified how keys are to be layed out (most-to-least bits). 2925 * Changed sequence number semantics to be like an RPC transaction ID 2926 number.