idnits 2.17.1 draft-mcdonald-pf-key-v2-03.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-26) 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 552 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** 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 127: '... - MUST...' RFC 2119 keyword, line 132: '... - SHOULD...' RFC 2119 keyword, line 139: '... - MAY...' RFC 2119 keyword, line 149: '... implement, or MUST, items MUST b...' RFC 2119 keyword, line 163: '...PF_KEY algorithm MAY consist of more t...' (108 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 10 has weird spacing: '... This docum...' == Line 14 has weird spacing: '... Drafts may b...' == Line 15 has weird spacing: '...iate to use ...' == Line 16 has weird spacing: '... Drafts as r...' == Line 24 has weird spacing: '...generic key ...' == (547 more instances...) -- 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 (25 July 1997) is 9772 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 156, but not defined == Missing Reference: 'HA94' is mentioned on line 156, but not defined -- Looks like a reference, but probably isn't: '3' on line 2584 -- 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: 18 errors (**), 0 flaws (~~), 9 warnings (==), 19 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group D. L. McDonald 2 Internet Draft C. W. Metz 3 draft-mcdonald-pf-key-v2-03.txt B. G. Phan 4 25 July 1997 6 PF_KEY Key Management API, Version 2 8 Status of this Memo 10 This document is an Internet Draft. Internet Drafts are working 11 documents. 13 Internet Drafts are draft documents valid for a maximum of 6 14 months. Internet Drafts may be updated, replaced, or obsoleted by 15 other documents at any time. It is not appropriate to use Internet 16 Drafts as reference material or to cite them other than as "work in 17 progress". 19 A future version of this draft will be submitted to the RFC Editor 20 for publication as an Informational document. 22 Abstract 24 A generic key management API that can be used not only for IP 25 Security [Atk95a] [Atk95b] [Atk95c] but also for other network 26 security services is presented in this document. Version 1 of this 27 API was implemented inside 4.4-Lite BSD as part of the U. S. Naval 28 Research Laboratory's freely distributable and usable IPv6 and IPsec 29 implementation[AMPMC96]. It is documented here for the benefit of 30 others who might also adopt and use the API, thus providing increased 31 portability of key management applications (e.g. a manual keying 32 application, an ISAKMP daemon, a GKMP daemon [HM97a,HM97b], a 33 Photuris daemon, or a SKIP certificate discovery protocol daemon). 35 Table of Contents 36 1 Introduction ............................................. 4 37 1.1 Terminology .............................................. 4 38 1.2 Conceptual Model ......................................... 6 39 1.3 PF_KEY Socket Definition ................................. 8 40 1.4 Overview of PF_KEY Messaging Behavior .................... 9 41 1.5 Common PF_KEY Operations ................................. 10 42 1.6 Differences Between PF_KEY and PF_ROUTE .................. 11 43 1.7 Name Space ............................................... 11 44 2 PF_KEY Message Format .................................... 13 45 2.1 Base Message Header Format ............................... 13 46 2.2 Alignment of Headers and Extension Headers ............... 15 47 2.3 Additional Message Fields ................................ 15 48 2.3.1 Association Extension .................................... 16 49 2.3.2 Lifetime Extension ....................................... 18 50 2.3.3 Address Extension ........................................ 19 51 2.3.4 Key Extension ............................................ 19 52 2.3.5 Identity Extension ....................................... 21 53 2.3.6 Sensitivity Extension .................................... 22 54 2.3.7 Proposal Extension ....................................... 23 55 2.3.8 Supported Algorithms Extension ........................... 25 56 2.3.9 SPI Range Extension ...................................... 26 57 2.4 Illustration of Message Layout ........................... 27 58 3 Symbolic Names ........................................... 31 59 3.1 Message Types ............................................ 31 60 3.1.1 SADB_GETSPI .............................................. 33 61 3.1.2 SADB_UPDATE .............................................. 33 62 3.1.3 SADB_ADD ................................................. 35 63 3.1.4 SADB_DELETE .............................................. 36 64 3.1.5 SADB_GET ................................................. 36 65 3.1.6 SADB_ACQUIRE ............................................. 37 66 3.1.7 SADB_REGISTER ............................................ 38 67 3.1.8 SADB_EXPIRE .............................................. 39 68 3.1.9 SADB_FLUSH ............................................... 40 69 3.1.10 SADB_DUMP ................................................ 40 70 3.2 Security Association Flags ............................... 41 71 3.3 Security Association States .............................. 41 72 3.4 Security Association Types ............................... 42 73 3.5 Algorithm Types .......................................... 43 74 3.6 Extension Header Values .................................. 43 75 3.7 Identity Extension Values ................................ 44 76 3.8 Sensitivity Extension Values ............................. 45 77 3.9 Proposal Extension Values ................................ 45 78 4 Future Directions ........................................ 46 79 5 Examples ................................................. 47 80 5.1 Simple IP Security Example ............................... 47 81 5.2 Proxy IP Security Example ................................ 49 82 5.3 OSPF Security Example .................................... 50 83 5.4 Miscellaneous ............................................ 51 84 6 Security Considerations .................................. 52 85 Acknowledgments ............,............................. 53 86 References ............................................... 54 87 Disclaimer ............................................... 56 88 Authors' Addresses ....................................... 56 89 A Promiscuous Send/Receive Extension ....................... 57 90 B Sample Header File ....................................... 59 91 C Change Log ............................................... 64 93 1 Introduction 95 PF_KEY is a new socket protocol family used by trusted privileged 96 key management applications to communicate with an operating system's 97 key management internals (referred to here as the "Key Engine" or the 98 SADB). The Key Engine and its structures incorporate the required 99 security attributes for a session and are instances of the "Security 100 Association" concept described in [Atk95a]. The names PF_KEY and Key 101 Engine thus refer to more than cryptographic keys and are retained 102 for consistency with the traditional phrase, "Key Management". 104 PF_KEY is derived in part from the BSD routing socket, PF_ROUTE. 105 [Skl91] This document describes Version 2 of PF_KEY. Version 1 was 106 implemented in the first three alpha test versions of the NRL 107 IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco 108 ISAKMP/Oakley key management daemon. Version 2 extends and refines 109 this interface. Theoretically, the messages defined in this document 110 could be used in a non-socket context (e.g. between two directly 111 communicating user-level processes), but this document will not 112 discuss in detail such possibilities. 114 Security policy is deliberately omitted from this interface. PF_KEY 115 is not a mechanism for tuning systemwide security policy, nor is it 116 intended to enforce any sort of key management policy. The developers 117 of PF_KEY believed that it was important to separate security 118 mechanisms (such as PF_KEY) from security policies. This permits a 119 single mechanism to more easily support multiple policies. 121 1.1 Terminology 123 Even though this document is not intended to be a standard, the 124 words that are used to define the significance of particular features 125 of this interface are usually capitalized. These words are: 127 - MUST 129 This word or the adjective "REQUIRED" means that the item is an 130 absolute requirement of the specification. 132 - SHOULD 134 This word or the adjective "RECOMMENDED" means that there might 135 exist valid reasons in particular circumstances to ignore this item, 136 but the full implications should be understood and the case carefully 137 weighed before taking a different course. 139 - MAY 140 This word or the adjective "OPTIONAL" means that this item is truly 141 optional. One vendor might choose to include the item because a 142 particular marketplace requires it or because it enhances the 143 product, for example; another vendor may omit the same item. 145 - CONFORMANCE and COMPLIANCE 147 Conformance to this specification has the same meaning as 148 compliance to this specification. In either case, the mandatory-to- 149 implement, or MUST, items MUST be fully implemented as specified 150 here. If any mandatory item is not implemented as specified here, 151 that implementation is not conforming and not compliant with this 152 specification. 154 This specification also uses many terms that are commonly used in 155 the context of network security. Other documents provide more 156 definitions and background information on these [VK83, HA94, Atk95a]. 157 A few terms deserve special mention: 159 (Encryption/Authentication) Algorithm 160 For PF_KEY purposes, an algorithm, whether encryption or 161 authentication, is the set of operations performed on a packet to 162 complete authentication or encryption as indicated by the SA type. 163 A PF_KEY algorithm MAY consist of more than one cryptographic 164 algorithm. Another possibility is that the same basic cryptographic 165 algorithm may be applied with different modes of operation or some 166 other implementation difference. These differences, henceforth 167 called _algorithm differentiators_, distinguish between different 168 PF_KEY algorithms, and options to the same algorithm. Algorithm 169 differentiators will often cause fundamentally different security 170 properties. 172 For example, both DES and 3DES use the same cryptographic 173 algorithm, but they are used differently and have different 174 security properties. The triple-application of DES is considered an 175 algorithm differentiator. There are therefore two different PF_KEY 176 algorithms for DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same 177 hash function, but construct their message authentication codes 178 differently. The use of HMAC is an algorithm differentiator. 179 DES-ECB and DES-CBC are the same cryptographic algorithm, but use a 180 different mode. Mode (e.g., chaining vs. code-book) is an algorithm 181 differentiator. Blowfish with a 128-bit key, however, is similar to 182 Blowfish with a 384-bit key, because the algorithm's workings are 183 otherwise the same and therefore the key length is not an algorithm 184 differentiator. 186 In terms of IP Security, a general rule of thumb is that whatever 187 might be labeled the "encryption" part of an ESP transform is 188 probably a PF_KEY encryption algorithm. Whatever might be labelled 189 the "authentication" part of an AH or ESP transform is probably a 190 PF_KEY authentication algorithm. 192 [cmetz-What other definitions should go here?] 194 1.2 Conceptual Model 196 This section describes the conceptual model of an operating system 197 that implements the PF_KEY key management application programming 198 interface. This section is intended to provide background material 199 useful to understand the rest of this document. Presentation of this 200 conceptual model does not constrain a PF_KEY implementation to 201 strictly adhere to the conceptual components discussed in this 202 subsection. 204 Key management is most commonly implemented in whole or part at the 205 application-layer. For example, the ISAKMP/Oakley, GKMP, and 206 Photuris proposals for IPsec key management are all application-layer 207 protocols. Even parts of the SKIP IP-layer keying proposal can be 208 implemented at the application layer. Figure 1 shows the 209 relationship between a Key Management daemon and PF_KEY, which it 210 uses to communicate with the Key Engine, and PF_INET (or PF_INET6 in 211 the case of IPv6), which it uses to communicate via the network with 212 a remote key management entity. 214 The "Key Engine" or "Security Association Database (SADB)" is a 215 logical entity in the kernel that stores, updates, and deletes 216 Security Association data for various security protocols. There are 217 logical interfaces within the kernel (e.g. getassocbyspi(), 218 getassocbysocket()) that security protocols inside the kernel (e.g. 219 IP Security, aka IPsec) use to request and obtain Security 220 Associations. 222 In the case of IPsec, if by policy a particular outbound packet 223 needs processing, then the IPsec implementation requests an 224 appropriate Security Association from the Key Engine via the kernel- 225 internal interface. If the Key Engine has an appropriate SA, it 226 allocates the SA to this session (marking it as used) and returns the 227 SA to the IPsec implementation for use. If the Key Engine has no 228 such SA but a key management application has previously indicated 229 (via a PF_KEY SADB_REGISTER message) that it can obtain such SAs, 230 then the Key Engine requests that such an SA be created (via a PF_KEY 231 SADB_ACQUIRE message). When the key management daemon creates a new 232 SA, it places it into the Key Engine for future use. 234 +---------------+ 235 |Key Mgmt Daemon| 236 +---------------+ 237 | | 238 | | 239 | | Applications 240 ======[PF_KEY]====[PF_INET]========================== 241 | | OS Kernel 242 +------------+ +-----------------+ 243 | Key Engine | | TCP/IP, | 244 | or SADB |---| including IPsec | 245 +------------+ | | 246 +-----------------+ 247 | 248 +-----------+ 249 | Network | 250 | Interface | 251 +-----------+ 253 Figure 1: Relationship of Key Mgmt to PF_KEY 255 For performance reasons, some security protocols (e.g. IP Security) 256 are usually implemented inside the operating system kernel. Other 257 security protocols (e.g. OSPFv2 Cryptographic Authentication) are 258 implemented in trusted privileged applications outside the kernel. 259 Figure 2 shows a trusted, privileged routing daemon using PF_INET to 260 communicate routing information with a remote routing daemon and 261 using PF_KEY to request, obtain, and delete Security Associations 262 used with a routing protocol. 264 +---------------+ 265 |Routing Daemon| 266 +---------------+ 267 | | 268 | | 269 | | Applications 270 ======[PF_KEY]====[PF_INET]========================== 271 | | OS Kernel 272 +------------+ +---------+ 273 | Key Engine | | TCP/IP | 274 | or SADB |---| | 275 +------------+ +---------+ 276 | 277 +-----------+ 278 | Network | 279 | Interface | 280 +-----------+ 282 Figure 2: Relationship of Trusted Application to PF_KEY 284 When a trusted privileged application is using the Key Engine but 285 implements the security protocol within itself, then operation varies 286 slightly. In this case, the application needing an SA sends a PF_KEY 287 SADB_ACQUIRE message down to the Key Engine, which then either 288 returns an error or sends a similar SADB_ACQUIRE message up to one or 289 more key management applications capable of creating such SAs. As 290 before, the key management daemon stores the SA into the Key Engine. 291 Then, the trusted privileged application uses a SADB_GET message to 292 obtain the SA from the Key Engine. 294 In some implementations, policy may be implemented in user-space, 295 even though the actual cryptographic processing takes place in the 296 kernel. Such policy communication between the kernel mechanisms and 297 the user-space policy MAY be implemented by PF_KEY extensions, or 298 other such mechanism. This document does not specify such 299 extensions. 301 Untrusted clients, for example a user's web browser or telnet 302 client, do not need to use PF_KEY. Mechanisms not specified here are 303 used by such untrusted client applications to request security 304 services (e.g. IPsec) from an operating system. For security 305 reasons, only trusted, privileged applications are permitted to open 306 a PF_KEY socket. 308 1.3 PF_KEY Socket Definition 310 The PF_KEY protocol family (PF_KEY) symbol is defined in 311 in the same manner that other protocol families are 312 defined. PF_KEY does not use any socket addresses. Applications 313 using PF_KEY MUST NOT depend on the availability of a symbol named 314 AF_KEY, but kernel implementations are encouraged to define that 315 symbol for completeness. 317 The key management socket is created as follows: 319 #include 321 int s; 322 s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2); 324 The PF_KEY domain currently supports only the SOCK_RAW socket type. 325 The protocol field MUST be set to PF_KEY_V2, or else EPROTONOSUPPORT 326 will be returned. Only a trusted, privileged process can create a 327 PF_KEY socket. On conventional UNIX systems, a privileged process is 328 a process with an effective userid of zero. On non-MLS proprietary 329 operating systems, the notion of a "privileged process" is 330 implementation-defined. On Compartmented Mode Workstations (CMWs) or 331 other systems that claim to provide Multi-Level Security (MLS), a 332 process MUST have the "key management privilege" in order to open a 333 PF_KEY socket[DIA]. MLS systems that don't currently have such a 334 specific privilege MUST add that special privilege and enforce it 335 with PF_KEY in order to comply and conform with this specification. 336 Some systems, most notably some popular personal computers, do not 337 have the concept of an unprivileged user. These systems SHOULD take 338 steps to restrict the programs allowed to access the PF_KEY API. 340 1.4 Overview of PF_KEY Messaging Behavior 342 A process interacts with the key engine by sending and receiving 343 messages using the PF_KEY socket. Security association information 344 can be inserted into and retrieved from the kernel's security 345 association table using a set of predefined messages. In the normal 346 case, all properly-formed messages sent to the kernel are returned to 347 all open PF_KEY sockets, including the sender. Improperly formed 348 messages will result in errors, and an implementation MUST check for 349 a properly formed message before returning it to the appropriate 350 listeners. Unlike the routing socket, most errors are sent in reply 351 messages, not the errno field when write() or send() fails. PF_KEY 352 message delivery is not guaranteed, especially in cases where kernel 353 or socket buffers are exhausted and messages are dropped. 355 Some messages are generated by the operating system to indicate 356 that actions need to be taken, and are not necessarily in response to 357 any message sent down by the user. Such messages are not received by 358 all PF_KEY sockets, but by sockets which have indicated that kernel- 359 originated messages are to be received. These messages are special 360 because of the expected frequency at which they will occur. Also, an 361 implementation may further wish to restrict return message from the 362 kernel, in cases where not all PF_KEY sockets are in the same trust 363 domain. 365 Many of the normal BSD socket calls have undefined behavior on 366 PF_KEY sockets. These include: bind(), connect(), socketpair(), 367 accept(), getpeername(), getsockname(), ioctl(), and listen(). 369 1.5 Common PF_KEY Operations 371 There are two basic ways to add a new Security Association into the 372 kernel. The simplest is to send a single SADB_ADD message, 373 containing all of the SA information, from the application into the 374 kernel's Key Engine. This approach works particularly well with 375 manual key management. 377 The second approach to add a new Security Association into the 378 kernel is for the application to first request an SPI value from the 379 kernel using the SADB_GETSPI message and then send a SADB_UPDATE 380 message with the complete Security Association data. This second 381 approach works well with key management daemons when the SPI values 382 need to be known before the entire Security Association data is known 383 (e.g. so the SPI value can be indicated to the remote end of the key 384 management session). 386 An individual Security Association can be deleted using the 387 SADB_DELETE message. Categories of SAs or the entire kernel SA table 388 can be deleted using the SADB_FLUSH message. 390 The SADB_GET message is used by a trusted application-layer process 391 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 392 SA) from the kernel's Key Engine. 394 The kernel or an application-layer can use the SADB_ACQUIRE message 395 to request that a Security Association be created by some 396 application-layer key management process that has registered with the 397 kernel via a SADB_REGISTER message. This ACQUIRE message will have a 398 sequence number associated with it. This sequence number MUST be 399 used by followup SADB_GETSPI and SADB_UPDATE messages, in order to 400 keep track of which request gets its keying material. The sequence 401 number (described below) is analogous to a transaction ID in a remote 402 procedure call. 404 The SADB_EXPIRE message is sent from the kernel to key management 405 applications when the "soft lifetime" or "hard lifetime" of a 406 Security Association has expired. Key management applications should 407 use receipt of a soft lifetime SADB_EXPIRE message as a hint to 408 negotiate a replacement SA so the replacement SA will be ready and in 409 the kernel before it is needed. 411 A SADB_DUMP message is also defined, but this is primarily intended 412 for PF_KEY implementor debugging and is not used in ordinary 413 operation of PF_KEY. 415 1.6 Differences Between PF_KEY and PF_ROUTE 417 The following bullets are points of difference between the routing 418 socket and PF_KEY. Programmers who are used to the routing socket 419 semantics will find some differences in PF_KEY. 421 * PF_KEY message errors are usually returned in PF_KEY messages 422 instead of causing write() operations to fail and returning the 423 error number in errno. This means that other listeners on a 424 PF_KEY socket can be aware that requests from another process 425 failed, which can be useful for auditing purposes. This also 426 means that applications that fail to read PF_KEY messages 427 cannot do error checking. 429 An implementation MAY return the errors EINVAL, ENOMEM, and 430 ENOBUFS by causing write() operations to fail and returning the 431 error number in errno. This is an optimization for common error 432 cases in which it does not make sense for any other process to 433 receive the error. An application MUST NOT depend on such errors 434 being set by the write() call, but can save itself time by checking 435 for such errors. 437 * The entire message isn't always reflected in the reply. A SADB_ADD 438 message is an example of this. 440 * The PID is not set by the kernel. The process that originates the 441 message MUST set the sadb_msg_pid to its own PID. If the kernel 442 ORIGINATES a message, it MUST set the sadb_msg_pid to 0. A reply 443 to an original message SHOULD have the pid of the original message. 444 (E.g. The kernel's response to an SADB_ADD SHOULD have its pid set 445 to the pid value of the original SADB_ADD message.) 447 1.7 Name Space 449 All PF_KEYv2 preprocessor symbols and structure definitions are 450 defined as a result of including the header file . 451 There is exactly one exception to this rule: the symbol "PF_KEY", 452 which is defined as a result of including the header file 453 . All PF_KEYv2 preprocessor symbols start with the 454 prefix "SADB_" and all structure names start with "sadb_". There is 455 exactly one exception to this rule: the symbol "PF_KEY_V2". 457 Inclusion of the file MUST NOT define symbols or 458 structures in the PF_KEYv2 name space that are not described in this 459 document without the explicit prior permission of the authors. Any 460 symbols or structures in the PF_KEYv2 name space that are not 461 described in this document MUST start with "SADB_X_" or "sadb_x_". 462 An implementation that fails to obey these rules IS NOT COMPLIANT 463 WITH THIS SPECIFICATION and MUST NOT make any claim to be. These 464 rules also apply to any files that might be included as a result of 465 including the file . This rule provides implementors 466 with some assurance that they will not encounter namespace-related 467 surprises. 469 2 PF_KEY Message Format 471 PF_KEY messages consist of a base header followed by additional 472 data fields, some of which may be optional. The format of the 473 additional data is dependent on the type of message. 475 PF_KEY messages currently do not mandate any specific ordering for 476 non-network multi-octet fields. Fields that may go across the wire 477 (e.g. SPI) MUST be in network byte order. 479 2.1 Base Message Header Format 481 PF_KEY messages consist of the base message header followed by 482 security association specific data whose types and lengths are 483 specified by a generic type-length encoding. 485 This base header is shown below, using POSIX types. The fields are 486 arranged primarily for alignment, and where possible, for reasons of 487 clarity. 489 struct sadb_msg { 490 uint8_t sadb_msg_version; 491 uint8_t sadb_msg_type; 492 uint8_t sadb_msg_errno; 493 uint8_t sadb_msg_satype; 494 uint16_t sadb_msg_len; 495 uint16_t sadb_msg_reserved; 496 uint32_t sadb_msg_seq; 497 uint32_t sadb_msg_pid; 498 }; 499 /* sizeof(struct sadb_msg) == 16 */ 501 sadb_msg_version 502 The version field of this PF_KEY message. This MUST 503 be set to PF_KEY_V2. If this is not set to PF_KEY_V2, 504 the write() call MAY fail and return EINVAL. 505 Otherwise, the behavior is undetermined, given that 506 the application might not understand the formatting 507 of the messages arriving from the kernel. 508 [cmetz-I'd like to remove this field; it's redundant 509 with the third arg of socket()] 511 sadb_msg_type Identifies the type of message. The valid message 512 types are described later in this document. 514 sadb_msg_errno Should be set to zero by the sender. The responder 515 stores the error code in this field if an error has 516 occurred. This includes the case where the responder 517 is in user space. (e.g. user-space negotiation 518 fails, an errno can be returned.) 520 sadb_msg_satype Indicates the type of security association(s). Valid 521 Security Association types are declared in the file 522 . The current set of Security 523 Association types are enumerated later in this 524 document. 526 sadb_msg_len Contains the total length, in 64-bit words, of all 527 data in the PF_KEY message including the base header 528 length and additional data after the base header, if 529 any. This length includes any padding or extra space 530 that might exist. Unless otherwise stated, all other 531 length fields are also measured in 64-bit words. 533 On user to kernel messages, this field MUST be 534 verified against the length of the inbound message. 535 EMSGSIZE MUST be returned if the verification fails. 536 On kernel to user messages, a size mismatch is most 537 likely the result of the user not providing a large 538 enough buffer for the message. In these cases, the 539 user application SHOULD drop the message, but it MAY 540 try and extract what information it can out of the 541 message. 543 sadb_msg_reserved 544 Reserved value. It MUST be zeroed by the sender. All 545 fields labeled reserved later in the document have 546 the same semantics as this field. 548 sadb_msg_seq Contains the sequence number of this message. This 549 field, along with sadb_msg_pid, MUST be used to 550 uniquely identify requests to a process. The sender 551 is responsible for filling in this field. This 552 responsibility also includes matching the 553 sadb_msg_seq of a request (e.g. SADB_ACQUIRE). 555 This field is analogous to a transaction ID in a 556 remote procedure call implementation. 558 sadb_msg_pid Identifies the process which originated this message, 559 or which process a message is bound for. For example, 560 if process id 2112 sends a SADB_UPDATE message to the 561 kernel, the process MUST set this field to 2112 and 562 the kernel will set this field to 2112 in its reply 563 to that SADB_UPDATE message. This field, along with 564 sadb_msg_seq, can be used to uniquely identify 565 requests to a process. 567 It is currently assumed that a 32-bit quantity will 568 hold an operating system's process ID space. 570 2.2 Alignment of Headers and Extension Headers 572 The base message header is a multiple of 64 bits and fields after 573 it in memory will be 64 bit aligned if the base itself is 64 bit 574 aligned. Some of the subsequent extension headers have 64 bit fields 575 in them, and as a consequence need to be 64 bit aligned in an 576 environment where 64 bit quantities need to be 64 bit aligned. 578 The basic unit of alignment and length in PF_KEY Version 2 is 64 579 bits. Therefore: 581 * All extension headers, inclusive of the sadb_ext overlay fields, 582 MUST be a multiple of 64 bits long. 583 * All variable length data MUST be padded appropriately such that 584 its length in a message is a multiple of 64 bits. 585 * All length fields are, unless otherwise specified, in units of 586 64 bits. 587 * Implementations may safely access quantities of between 8 and 64 588 bits directly within a message without risk of alignment faults. 590 All PF_KEYv2 structures are packed and already have all intended 591 padding. Implementations MUST NOT insert any extra fields, including 592 hidden padding, into any structure in this document. This forbids 593 implementations from "extending" or "enhancing" existing headers 594 without changing the extension header type. As a guard against such 595 insertion of silent padding, each structure in this document is 596 labeled with its size in bytes. The size of these structures in an 597 implementation MUST match the size listed. 599 2.3 Additional Message Fields 601 The additional data following the base header consists of various 602 length-type-values fields. The first 32-bits are of a constant form: 604 struct sadb_ext { 605 uint16_t sadb_ext_len; 606 uint16_t sadb_ext_type; 607 }; 608 /* sizeof(struct sadb_ext) == 4 */ 610 sadb_ext_len Length of the extension header in 64 bit words, 611 inclusive. 613 sadb_ext_type The type of extension header that follows. Values for 614 this field are detailed later. The value zero is 615 reserved. 617 Types of extensions headers include: Association, Lifetime(s), 618 Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and 619 Supported. There MUST be only one instance of a extension type in a 620 message. (e.g. Base, Key, Lifetime, Key is forbidden), an EINVAL will 621 be returned if there are duplicate extensions within a message. 622 Implementations MAY enforce ordering of extensions in the order 623 presented in the EXTENSION HEADER VALUES section. 625 If an unknown extension type is encountered, it MUST be ignored. 626 Applications using extension headers not specified in this document 627 MUST be prepared to work around other system components not 628 processing those headers. Likewise, if an application encounters an 629 unknown extension from the kernel, it must be prepared to work around 630 it. Also, a kernel that generates extra extension header types MUST 631 NOT _depend_ on applications also understanding extra extension 632 header types. 634 All extension definitions include these two fields (len and 635 exttype) because they are instances of a generic extension (not 636 unlike sockaddr_in and sockaddr_in6 are instances of a generic 637 sockaddr). The sadb_ext header MUST NOT ever be present in a message 638 without at least four bytes of extension header data following it, 639 and, therefore, there is no problem with it being only four bytes 640 long. 642 All extensions documented in this section MUST be implemented by a 643 PF_KEY implementation. 645 2.3.1 Association Extension 647 The Association extension specifies data specific to a single 648 security association. The only times this extension is not present is 649 when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being 650 passed and on the SADB_ACQUIRE message. 652 struct sadb_sa { 653 uint16_t sadb_sa_len; 654 uint16_t sadb_sa_exttype; 655 uint32_t sadb_sa_spi; 656 uint8_t sadb_sa_replay; 657 uint8_t sadb_sa_state; 658 uint8_t sadb_sa_auth; 659 uint8_t sadb_sa_encrypt; 660 uint32_t sadb_sa_flags; 661 }; 662 /* sizeof(struct sadb_sa) == 16 */ 664 sadb_sa_spi The Security Parameters Index value for the security 665 association. Although this is a 32-bit field, some 666 types of security associations might have a SPI or 667 key identifier that is less than 32-bits long. In 668 this case, the smaller value shall be stored in the 669 least significant bits of this field and the unneeded 670 bits shall be zero. This field MUST be in network 671 byte order. 673 sadb_sa_replay The size of the replay window, if not zero. If zero, 674 then no replay window is in use. 676 sadb_sa_state The state of the security association. The currently 677 defined states are described later in this document. 679 sadb_sa_auth The authentication algorithm to be used with this 680 security association. The valid authentication 681 algorithms are described later in this document. A 682 value of zero means that no authentication is used 683 for this security association. 685 sadb_sa_encrypt The encryption algorithm to be used with this 686 security association. The valid encryption algorithms 687 are described later in this document. A value of zero 688 means that no encryption is used for this security 689 association. 691 sadb_sa_flags A bitmap of options defined for the security 692 association. The currently defined flags are 693 described later in this document. 695 The kernel MUST check these values where appropriate. For example, 696 IPsec AH with no authentication algorithm is probably an error. 698 When used with some messages, the values in some fields in this 699 header should be ignored. 701 2.3.2 Lifetime Extension 703 The Lifetime extension specifies one or more lifetime variants for 704 this security association. If no Lifetime extension is present the 705 association has an infinite lifetime. An association SHOULD have a 706 lifetime of some sort associated with it. Lifetime variants come in 707 three varieties, HARD - indicating the hard-limit expiration, SOFT - 708 indicating the soft-limit expiration, and CURRENT - indicating the 709 current state of a given security association. The Lifetime 710 extension looks like: 712 struct sadb_lifetime { 713 uint16_t sadb_lifetime_len; 714 uint16_t sadb_lifetime_exttype; 715 uint32_t sadb_lifetime_allocations; 716 uint64_t sadb_lifetime_bytes; 717 uint64_t sadb_lifetime_addtime; 718 uint64_t sadb_lifetime_usetime; 719 }; 720 /* sizeof(struct sadb_lifetime) == 32 */ 722 sadb_lifetime_allocations 723 For CURRENT, the number of different connections, 724 endpoints, or flows that the association has been 725 allocated towards. For HARD and SOFT, the number of 726 these the association may be allocated towards 727 before it expires. The concept of a connection, 728 flow, or endpoint is system specific. 730 sadb_lifetime_bytes 731 For CURRENT, how many bytes have been processed 732 using this security association. For HARD and SOFT, 733 the number of bytes that may be processed using 734 this security association before it expires. 736 sadb_lifetime_addtime 737 For CURRENT, the time, in seconds, when the 738 association was created. For HARD and SOFT, the 739 number of seconds after the creation of the 740 association until it expires. 742 For such time fields, it is assumed that 64-bits is 743 sufficiently large to hold the POSIX time_t value. 744 If this assumption is wrong, this field will have to 745 be revisited. 747 sadb_lifetime_usetime 748 For CURRENT, the time, in seconds, when association 749 was first used. For HARD and SOFT, the number of 750 seconds after the first use of the association until 751 it expires. 753 The semantics of lifetimes are inclusive-OR, first-to-expire. This 754 means that if values for bytes and time, or multiple times, are 755 passed in, the first of these values to be reached will cause a 756 lifetime expiration. 758 2.3.3 Address Extension 760 The Address extension specifies one or more addresses that are 761 associated with a security association. Address extensions for both 762 source and destination MUST be present when an Association extension 763 is present. The format of an Address extension is: 765 struct sadb_address { 766 uint16_t sadb_address_len; 767 uint16_t sadb_address_exttype; 768 uint32_t sadb_address_reserved; 769 }; 770 /* sizeof(struct sadb_address) == 8 */ 772 /* followed by some form of struct sockaddr */ 774 The sockaddr structure SHOULD conform to the sockaddr structure of 775 the system implementing PF_KEY. If the system has an sa_len field, so 776 SHOULD the sockaddrs in the message. If the system has NO sa_len 777 field, the sockaddrs SHOULD NOT have an sa_len field. All non-address 778 information in the sockaddrs, such as sin_zero and sin_port for 779 AF_INET sockaddrs, and sin6_port and sin6_flowinfo for AF_INET6 780 sockaddrs, MUST be zeroed out. 782 The SRC and DST addresses for a security association MUST be in the 783 same protocol family and MUST always be present or absent together in 784 a message. The PROXY address MAY be in a different protocol family. 786 The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY) 787 address. The DST address MUST be a unicast or multicast address. The 788 PROXY address MUST be a unicast address. 790 2.3.4 Key Extension 792 The Key extension specifies one or more keys that are associated 793 with a security association. A Key extension will not always be 794 present with messages, because of security risks. The format of a 795 Key extension is: 797 struct sadb_key { 798 uint16_t sadb_key_len; 799 uint16_t sadb_key_exttype; 800 uint16_t sadb_key_bits; 801 uint16_t sadb_key_reserved; 802 }; 803 /* sizeof(struct sadb_key) == 8 */ 805 /* followed by the key data */ 807 sadb_key_bits The length of the valid key data, in bits. A value of 808 zero in sadb_key_bits MUST cause an error. 810 The key extension comes in two varieties. The AUTH version is used 811 with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT 812 version is used with encryption keys (e.g. IPsec ESP). PF_KEY deals 813 only with fully formed cryptographic keys, not with "raw key 814 material". For example, when ISAKMP/Oakley is in use, the key 815 management daemon is always responsible for transforming the result 816 of the Diffie-Hellman computation into distinct fully formed keys 817 PRIOR to sending those keys into the kernel via PF_KEY. This rule is 818 made because PF_KEY is designed to support multiple security 819 protocols (not just IP Security) and also multiple key management 820 schemes (some of which do not have the concept of "raw key 821 material"). A clean, protocol-independent interface is important for 822 portability to different operating systems as well as for portability 823 to different security protocols. 825 If an algorithm defines its key to include parity bits (e.g. DES) 826 then the key used with PF_KEY MUST also include those parity bits. 827 For example, this means that a single DES key is always a 64-bit 828 quantity. 830 When a particular security protocol only requires one 831 authentication and/or one encryption key, the fully formed key is 832 transmitted using the appropriate key extension. When a particular 833 security protocol requires more than one key for the same function 834 (e.g. Triple-DES using 2 keys), then those two fully formed keys 835 concatenated together in the order used for outbound packet 836 processing. In the case of multiple keys, the algorithm MUST be able 837 to determine the lengths of the individual keys based on the 838 information provided. The total key length (when combined with 839 knowledge of the algorithm in use) usually provides sufficient 840 information to make this determination. 842 Keys are always passed through the PF_KEY interface in the order 844 that they are used for outbound packet processing. For inbound 845 processing, the correct order that keys are used might be different 846 from this canonical concatenation order used with the PF_KEY 847 interface. It is the responsibility of the implementation to use the 848 keys in the correct order for both inbound and outbound processing. 850 For example, consider a pair of nodes communicating unicast using 851 an ESP three-key Triple-DES Security Association. Both the outbound 852 SA on the sender node, and the inbound SA on the receiver node will 853 contain key-A, followed by key-B, followed by key-C in their 854 respective ENCRYPT key extensions. The outbound SA will use key-A 855 first, followed by key-B, then key-C when encrypting. The inbound SA 856 will use key-C, followed by key-B, then key-A when decrypting. 857 (NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.) 858 The canonical ordering of key-A, key-B, key-C is used for 3DES, and 859 should be documented. The order of "encryption" is the canonical 860 order for this example. [DMS97] 862 The key data bits are arranged most-significant to least 863 significant. For example, a 22-bit key would take up three octets, 864 with the least significant two bits not containing key material. Five 865 additional octets would then be used for padding to the next 64-bit 866 boundary. 868 While not directly related to PF_KEY, there is a user interface 869 issue regarding odd-digit hexadecimal representation of keys. 870 Consider the example of the 16-bit number: 872 0x123 874 That will require two octets of storage. In the absence of other 875 information, however, unclear whether the value shown is stored as: 877 01 23 OR 12 30 879 It is the opinion of the authors that the former (0x123 == 0x0123) is 880 the better way to interpret this ambiguity. Extra information (for 881 example, specifying 0x0123 or 0x1230, or specifying that this is only 882 a twelve-bit number) would solve this problem. 884 2.3.5 Identity Extension 886 The Identity extension contains endpoint identities. This 887 information is used by key management to select the identity 888 certificate that is used in negotiations. This information may also 889 be provided by a kernel to network security aware applications to 890 identify the remote entity, possibly for access control purposes. If 891 this extension is not present, key management MUST assume that the 892 addresses in the Address extension are the only identities for this 893 Security Association. The Identity extension looks like: 895 struct sadb_ident { 896 uint16_t sadb_ident_len; 897 uint16_t sadb_ident_exttype; 898 uint16_t sadb_ident_type; 899 uint16_t sadb_ident_reserved; 900 }; 901 /* sizeof(struct sadb_ident) == 8 */ 903 /* followed by the identity string */ 905 sadb_ident_type The type of identity information that follows. 906 Currently defined identity types are described later 907 in this document. 909 Following each sadb_ident is a C string containing a textual 910 representation of the identity information. The format of this string 911 is determined by the value in sadb_ident_type, and is described later 912 in this document. 914 2.3.6 Sensitivity Extension 916 The Sensitivity extension contains security labeling information 917 for a security association. If this extension is not present, no 918 sensitivity-related data can be obtained from this security 919 association. If this extension is present, then the need for 920 explicit security labeling on the packet is obviated. 922 struct sadb_sens { 923 uint16_t sadb_sens_len; 924 uint16_t sadb_sens_exttype; 925 uint32_t sadb_sens_dpd; 926 uint8_t sadb_sens_sens_level; 927 uint8_t sadb_sens_sens_len; 928 uint8_t sadb_sens_integ_level; 929 uint8_t sadb_sens_integ_len; 930 uint32_t sadb_sens_reserved; 931 }; 932 /* sizeof(struct sadb_sens) == 16 */ 934 /* followed by: 935 uint64_t sadb_sens_bitmap[sens_len]; 936 uint64_t sadb_integ_bitmap[integ_len]; */ 938 sadb_sens_dpd Describes the protection domain, which allows 939 interpretation of the levels and compartment 940 bitmaps. 941 sadb_sens_sens_level 942 The sensitivity level. 943 sadb_sens_sens_len 944 The length, in 64 bit words, of the sensitivity 945 bitmap. 946 sadb_sens_integ_level 947 The integrity level. 948 sadb_sens_integ_len 949 The length, in 64 bit words, of the integrity 950 bitmap. 952 This sensitivity extension is designed to support the Bell-LaPadula 953 [BL74] security model used in compartmented-mode or multi-level 954 secure systems, the Clark-Wilson [CW87] commercial security model, 955 and/or the Biba integrity model [Biba77]. These formal models can be 956 used to implement a wide variety of security policies. The definition 957 of a particular security policy is outside the scope of this 958 document. 960 2.3.7 Proposal Extension 962 The Proposal extension contains a "proposed situation" of algorithm 963 preferences. It looks like: 965 struct sadb_prop { 966 uint16_t sadb_prop_len; 967 uint16_t sadb_prop_exttype; 968 uint8_t sadb_prop_replay; 969 uint8_t sadb_prop_reserved[3]; 970 }; 971 /* sizeof(struct sadb_prop) == 8 */ 973 /* followed by: 974 struct sadb_comb sadb_combs[(sadb_prop_len * 975 sizeof(uint64_t) - sizeof(struct sadb_prop)) / 976 sizeof(struct sadb_comb)]; */ 978 Following the header are a list of proposed parameter combinations in 979 preferential order. The values in these fields have the same 980 definition as the fields those values will move into if the 981 combination is chosen. These combinations look like: 983 struct sadb_comb { 984 uint8_t sadb_comb_auth; 985 uint8_t sadb_comb_encrypt; 986 uint16_t sadb_comb_flags; 987 uint16_t sadb_comb_auth_minbits; 988 uint16_t sadb_comb_auth_maxbits; 989 uint16_t sadb_comb_encrypt_minbits; 990 uint16_t sadb_comb_encrypt_maxbits; 991 uint32_t sadb_comb_reserved; 992 uint32_t sadb_comb_soft_allocations; 993 uint32_t sadb_comb_hard_allocations; 994 uint64_t sadb_comb_soft_bytes; 995 uint64_t sadb_comb_hard_bytes; 996 uint64_t sadb_comb_soft_addtime; 997 uint64_t sadb_comb_hard_addtime; 998 uint64_t sadb_comb_soft_usetime; 999 uint64_t sadb_comb_hard_usetime; 1000 }; 1001 /* sizeof(struct sadb_comb) == 72 */ 1003 sadb_comb_auth If this combination is accepted, this will be the 1004 value of sadb_sa_auth. 1006 sadb_comb_encrypt 1007 If this combination is accepted, this will be the 1008 value of sadb_sa_encrypt. 1010 sadb_comb_auth_minbits; 1011 sadb_comb_auth_maxbits; 1012 The minimum and maximum acceptable authentication 1013 key lengths, respectably, in bits. If sadb_comb_auth 1014 is zero, both of these values MUST be zero. If 1015 sadb_comb_auth is nonzero, both of these values MUST 1016 be nonzero. If this combination is accepted, a value 1017 between these (inclusive) will be stored in the 1018 sadb_key_bits field of KEY_AUTH. The minimum MUST 1019 NOT be greater than the maximum. 1021 sadb_comb_encrypt_minbits; 1022 sadb_comb_encrypt_maxbits; 1023 The minimum and maximum acceptable encryption key 1024 lengths, respectably, in bits. If sadb_comb_encrypt 1025 is zero, both of these values MUST be zero. If 1026 sadb_comb_encrypt is nonzero, both of these values 1027 MUST be nonzero. If this combination is accepted, a 1028 value between these (inclusive) will be stored in 1029 the sadb_key_bits field of KEY_ENCRYPT. The minimum 1030 MUST NOT be greater than the maximum. 1032 sadb_comb_soft_allocations 1033 sadb_comb_hard_allocations 1034 If this combination is accepted, these are proposed 1035 values of sadb_lifetime_allocations in the SOFT and 1036 HARD lifetimes, respectively. 1038 sadb_comb_soft_bytes 1039 sadb_comb_hard_bytes 1040 If this combination is accepted, these are proposed 1041 values of sadb_lifetime_bytes in the SOFT and HARD 1042 lifetimes, respectively. 1044 sadb_comb_soft_addtime 1045 sadb_comb_hard_addtime 1046 If this combination is accepted, these are proposed 1047 values of sadb_lifetime_addtime in the SOFT and HARD 1048 lifetimes, respectively. 1050 sadb_comb_soft_usetime 1051 sadb_comb_hard_usetime 1052 If this combination is accepted, these are proposed 1053 values of sadb_lifetime_usetime in the SOFT and HARD 1054 lifetimes, respectively. 1056 Each combination has an authentication and encryption algorithm, 1057 which may be 0, indicating none. A combination's flags are the same 1058 as the flags in the Association extension. The minimum and maximum 1059 key lengths (which are in bits) are derived from possible a priori 1060 policy decisions, along with basic properties of the algorithm. 1061 Lifetime attributes are also included in a combination, as some 1062 algorithms may know something about their lifetimes and can suggest 1063 lifetime limits. 1065 2.3.8 Supported Algorithms Extension 1067 The Supported Algorithms extension contains a list of all 1068 algorithms supported by the system. This tells key management what 1069 algorithms it can negotiate. Available authentication algorithms are 1070 listed in the SUPPORTED_AUTH extension and available encryption 1071 algorithms are listed in the SUPPORTED_ENCRYPT extension. The format 1072 of these extensions is: 1074 struct sadb_supported { 1075 uint16_t sadb_supported_len; 1076 uint16_t sadb_supported_exttype; 1077 uint32_t sadb_supported_reserved; 1078 }; 1079 /* sizeof(struct sadb_supported) == 8 */ 1080 /* followed by: 1081 struct sadb_alg sadb_algs[(sadb_supported_len * 1082 sizeof(uint64_t) - sizeof(struct sadb_supported)) / 1083 sizeof(struct sadb_alg)]; */ 1085 This header is followed by one or more algorithm descriptions. An 1086 algorithm description looks like: 1088 struct sadb_alg { 1089 uint8_t sadb_alg_id; 1090 uint8_t sadb_alg_ivlen; 1091 uint16_t sadb_alg_minbits; 1092 uint16_t sadb_alg_maxbits; 1093 uint16_t sadb_alg_reserved; 1094 }; 1095 /* sizeof(struct sadb_alg) == 8 */ 1097 sadb_alg_id The algorithm identification value for this 1098 algorithm. This is the value that is stored in 1099 sadb_sa_auth or sadb_sa_encrypt if this algorithm is 1100 selected. 1102 sadb_alg_ivlen The length of the initialization vector to be used 1103 for the algorithm. If an IV is not needed, this 1104 value MUST be set to zero. 1106 sadb_alg_minbits 1107 The minimum acceptable key length, in bits. A value 1108 of zero is invalid. 1110 sadb_alg_maxbits 1111 The maximum acceptable key length, in bits. A value 1112 of zero is invalid. The minimum MUST NOT be greater 1113 than the maximum. 1115 2.3.9 SPI Range Extension 1117 One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI 1118 values. This extension performs such a function. 1120 struct sadb_spirange { 1121 uint16_t sadb_spirange_len; 1122 uint16_t sadb_spirange_exttype; 1123 uint32_t sadb_spirange_min; 1124 uint32_t sadb_spirange_max; 1125 uint32_t sadb_spirange_reserved; 1126 }; 1127 /* sizeof(struct sadb_spirange) == 16 */ 1129 sadb_spirange_min 1130 The minimum acceptable SPI value. 1132 sadb_spirange_max 1133 The maximum acceptable SPI value. The maximum MUST 1134 NOT be greater than the minimum. 1136 2.4 Illustration of Message Layout 1138 The following shows how the octets are layed out in a PF_KEY message. 1139 Optional fields are indicated as such. 1141 The base header is as follows: 1143 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 1144 +---------------+---------------+---------------+---------------+ 1145 | ...version | sadb_msg_type | sadb_msg_errno| ...msg_satype | 1146 +---------------+---------------+---------------+---------------+ 1147 | sadb_msg_len | sadb_msg_reserved | 1148 +---------------+---------------+---------------+---------------+ 1149 | sadb_msg_seq | 1150 +---------------+---------------+---------------+---------------+ 1151 | sadb_msg_pid | 1152 +---------------+---------------+---------------+---------------+ 1154 The base header may be followed by one or more of the following 1155 extension fields, depending on the values of various base header 1156 fields. The following fields are ordered such that if they appear, 1157 they SHOULD appear in the order presented below. 1159 An extension field MUST not be repeated. If there is a situation 1160 where an extension MUST be repeated, it should be brought to the 1161 attention of the authors. 1163 The Association extension 1165 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 1166 +---------------+---------------+---------------+---------------+ 1167 | sadb_sa_len | sadb_sa_exttype | 1168 +---------------+---------------+---------------+---------------+ 1169 | sadb_sa_spi | 1170 +---------------+---------------+---------------+---------------+ 1171 | ...replay | sadb_sa_state | sadb_sa_auth |sadb_sa_encrypt| 1172 +---------------+---------------+---------------+---------------+ 1173 | sadb_sa_flags | 1174 +---------------+---------------+---------------+---------------+ 1176 The Lifetime extension 1178 +---------------+---------------+---------------+---------------+ 1179 | sadb_lifetime_len | sadb_lifetime_exttype | 1180 +---------------+---------------+---------------+---------------+ 1181 | sadb_lifetime_allocations | 1182 +---------------+---------------+---------------+---------------+ 1183 | sadb_lifetime_bytes | 1184 | (64 bits) | 1185 +---------------+---------------+---------------+---------------+ 1186 | sadb_lifetime_addtime | 1187 | (64 bits) | 1188 +---------------+---------------+---------------+---------------+ 1189 | sadb_lifetime_usetime | 1190 | (64 bits) | 1191 +---------------+---------------+---------------+---------------+ 1193 The Address extension 1195 +---------------+---------------+---------------+---------------+ 1196 | sadb_address_len | sadb_address_exttype | 1197 +---------------+---------------+---------------+---------------+ 1198 | sadb_address_reserved | 1199 +---------------+---------------+---------------+---------------+ 1200 > Some form of 64-bit aligned struct sockaddr goes here. < 1201 +---------------+---------------+---------------+---------------+ 1203 The Key extension 1205 +---------------+---------------+---------------+---------------+ 1206 | sadb_key_len | sadb_key_exttype | 1207 +---------------+---------------+---------------+---------------+ 1208 | sadb_key_bits | sadb_key_reserved | 1209 +---------------+---------------+---------------+---------------+ 1210 > A key, padded to 64-bits, most significant bits to least. > 1211 +---------------+---------------+---------------+---------------+ 1213 The Identity extension 1215 +---------------+---------------+---------------+---------------+ 1216 | sadb_ident_len | sadb_ident_exttype | 1217 +---------------+---------------+---------------+---------------+ 1218 | sadb_ident_type | sadb_ident_reserved | 1219 +---------------+---------------+---------------+---------------+ 1220 > A null-terminated C-string which MUST be padded out for > 1221 < 64-bit alignment. < 1222 +---------------+---------------+---------------+---------------+ 1224 The Sensitivity extension 1226 +---------------+---------------+---------------+---------------+ 1227 | sadb_sens_len | sadb_sens_exttype | 1228 +---------------+---------------+---------------+---------------+ 1229 | sadb_sens_dpd | 1230 +---------------+---------------+---------------+---------------+ 1231 | ...sens_level | ...sens_len |..._integ_level| ..integ_len | 1232 +---------------+---------------+---------------+---------------+ 1233 | sadb_sens_reserved | 1234 +---------------+---------------+---------------+---------------+ 1235 > The sensitivity bitmap, followed immediately by the < 1236 < integrity bitmap, each is an array of uint64_t. > 1237 +---------------+---------------+---------------+---------------+ 1239 The Proposal extension 1241 +---------------+---------------+---------------+---------------+ 1242 | sadb_prop_len | sadb_prop_exttype | 1243 +---------------+---------------+---------------+---------------+ 1244 |...prop_replay | sadb_prop_reserved | 1245 +---------------+---------------+---------------+---------------+ 1246 > One or more combinations, specified as follows... < 1247 +---------------+---------------+---------------+---------------+ 1249 Combination 1250 +---------------+---------------+---------------+---------------+ 1251 |sadb_comb_auth |sadb_comb_encr | sadb_comb_flags | 1252 +---------------+---------------+---------------+---------------+ 1253 | sadb_comb_auth_minbits | sadb_comb_auth_maxbits | 1254 +---------------+---------------+---------------+---------------+ 1255 | sadb_comb_encrypt_minbits | sadb_comb_encrypt_maxbits | 1256 +---------------+---------------+---------------+---------------+ 1257 | sadb_comb_reserved | 1258 +---------------+---------------+---------------+---------------+ 1259 | sadb_comb_soft_allocations | 1260 +---------------+---------------+---------------+---------------+ 1261 | sadb_comb_hard_allocations | 1262 +---------------+---------------+---------------+---------------+ 1263 | sadb_comb_soft_bytes | 1264 | (64 bits) | 1265 +---------------+---------------+---------------+---------------+ 1266 | sadb_comb_hard_bytes | 1267 | (64 bits) | 1268 +---------------+---------------+---------------+---------------+ 1269 | sadb_comb_soft_addtime | 1270 | (64 bits) | 1271 +---------------+---------------+---------------+---------------+ 1272 | sadb_comb_hard_addtime | 1273 | (64 bits) | 1274 +---------------+---------------+---------------+---------------+ 1275 | sadb_comb_soft_usetime | 1276 | (64 bits) | 1277 +---------------+---------------+---------------+---------------+ 1278 | sadb_comb_hard_usetime | 1279 | (64 bits) | 1280 +---------------+---------------+---------------+---------------+ 1282 The Supported Algorithms extension 1284 +---------------+---------------+---------------+---------------+ 1285 | sadb_supported_len | sadb_supported_exttype | 1286 +---------------+---------------+---------------+---------------+ 1287 | sadb_supported_reserved | 1288 +---------------+---------------+---------------+---------------+ 1290 Followed by one or more Algorithm Descriptors 1292 +---------------+---------------+---------------+---------------+ 1293 | sadb_alg_id | sadb_alg_ivlen| sadb_alg_minbits | 1294 +---------------+---------------+---------------+---------------+ 1295 | sadb_alg_maxbits | sadb_alg_reserved | 1296 +---------------+---------------+---------------+---------------+ 1298 The SPI Range extension 1300 +---------------+---------------+---------------+---------------+ 1301 | sadb_spirange_len | sadb_spirange_exttype | 1302 +---------------+---------------+---------------+---------------+ 1303 | sadb_spirange_min | 1304 +---------------+---------------+---------------+---------------+ 1305 | sadb_spirange_max | 1306 +---------------+---------------+---------------+---------------+ 1307 | sadb_spirange_reserved | 1308 +---------------+---------------+---------------+---------------+ 1310 3 Symbolic Names 1312 This section defines various symbols used with PF_KEY and the 1313 semantics associated with each symbol. Applications MUST use the 1314 symbolic names in order to be portable. The numeric definitions 1315 shown are for illustrative purposes, unless explicitly stated 1316 otherwise. The numeric definition MAY vary on other systems. The 1317 symbolic name MUST be kept the same for all conforming 1318 implementations. 1320 3.1 Message Types 1322 The following message types are used with PF_KEY. These are 1323 defined in the file . 1325 #define SADB_RESERVED 0 1326 #define SADB_GETSPI 1 1327 #define SADB_UPDATE 2 1328 #define SADB_ADD 3 1329 #define SADB_DELETE 4 1330 #define SADB_GET 5 1331 #define SADB_ACQUIRE 6 1332 #define SADB_REGISTER 7 1333 #define SADB_EXPIRE 8 1334 #define SADB_FLUSH 9 1336 #define SADB_DUMP 10 /* not used normally */ 1338 #define SADB_MAX 10 1340 Each message has a behavior. A behavior is defined as where the 1341 initial message travels (e.g. user to kernel), and what subsequent 1342 actions are expected to take place. Contents of messages are 1343 illustrated as: 1345 1347 The SA extension is sometimes used only for its SPI field. If all 1348 other fields MUST be ignored, this is represented by "SA(*)". 1350 The lifetime extensions are represented with one to three letters 1351 after the word "lifetime," representing (H)ARD, (S)OFT, and 1352 (C)URRENT. 1354 The address extensions are represented with one to three letters 1355 after the word "address," representing (S)RC, (D)ST, (P)ROXY. 1357 The key extensions are represented with one or two letters after the 1358 word "key," representing (A)UTH and (E)NCRYPT. 1360 The identity extensions are represented with one or two letters after 1361 the word "identity," representing (S)RC and (D)ST. 1363 In the case of an error, only the base header is returned. 1365 Note that any standard error could be returned for any message. 1366 Typically, they will be either one of the errors specifically listed 1367 in the description for a message or one of the following: 1369 EINVAL Various message improprieties, including SPI ranges 1370 that are malformed. 1371 ENOMEM Needed memory was not available. 1372 ENOBUFS Needed memory was not available. 1374 EMSGSIZ The message exceeds the maximum length allowed. 1376 3.1.1 SADB_GETSPI 1378 The SADB_GETSPI message allows a process to obtain a unique SPI 1379 value for given security association type, source address, and 1380 destination address. This message followed by a SADB_UPDATE is one 1381 way to create a security association (SADB_ADD is the other method). 1382 The process specifies the type in the base header, the source and 1383 destination address in address extension, and, if proxy key 1384 management is in use, the internal sockaddrs or the proxy sockaddr 1385 are also included in the address extension. If the SADB_GETSPI 1386 message is in response to a kernel-generated SADB_ACQUIRE, the 1387 sadb_msg_seq MUST be the same as the SADB_ACQUIRE message. The 1388 application may also specify the SPI. This is done by having the 1389 kernel select within a range of SPI values by using the SPI range 1390 extension. To specify a single SPI value to be verified, the 1391 application sets the high and low values to be equal. Permitting 1392 range specification is important because the kernel can allocate an 1393 SPI value based on what it knows about SPI values already in use. 1394 The kernel returns the same message with the allocated SPI value 1395 stored in the spi field of an association extension. An SADB_UPDATE 1396 message can later be used to add an entry with the requested SPI 1397 value. 1399 The message behavior of the SADB_GETSPI message is: 1401 Send a SADB_GETSPI message from a user process to the kernel. 1403 1405 The kernel returns the SADB_GETSPI message to all listening 1406 processes. 1408 1410 Errors: 1412 EEXIST Requested SPI or SPI range is not available or already 1413 used. 1415 3.1.2 SADB_UPDATE Message 1417 The SADB_UPDATE message allows a process to update the information 1418 in an existing Security Association. Since SADB_GETSPI does not 1419 allow setting of certain parameters, this message is needed to fully 1420 form the SADB_SASTATE_LARVAL security association created with 1421 SADB_GETSPI. The format of the update message is a base header, 1422 followed by an association header and possibly by several extension 1423 headers. The kernel searches for the security association with the 1424 same type, spi, source address and destination address specified in 1425 the message and updates the Security Association information using 1426 the content of the SADB_UPDATE message. 1428 The kernel MAY disallow SADB_UPDATE to succeed unless the message 1429 is issued from the same socket that created the security association. 1430 Such enforcement significantly reduces the chance of accidental 1431 changes to an in-use security associations. Malicious trusted 1432 parties could still issue a SADB_FLUSH or SADB_DELETE message, but 1433 deletion of associations is more easily detected and less likely to 1434 occur accidentally than an erroneous SADB_UPDATE. The counter 1435 argument to supporting this behavior involves the case where a user- 1436 space key management application fails and is restarted. The new 1437 instance of the application will not have the same socket as the 1438 creator of the security association. 1440 The kernel MUST sanity check all significant values submitted in a 1441 SADB_UPDATE message before changing the SA in its database and MUST 1442 return EINVAL if any of the values are invalid. Examples of checks 1443 that should be performed are DES key parity bit, key length checking, 1444 checks for keys known to be weak for the specified algorithm, and 1445 checks for flags or parameters known to be incompatible with the 1446 specified algorithm. 1448 Only SADB_SASTATE_MATURE SAs may be submitted in a SADB_UPDATE 1449 message. If the original SA is a SADB_SASTATE_LARVAL SA, then any 1450 value in the SA may be changed except for the source address, 1451 destination address, and SPI. If the original SA is a 1452 SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA 1453 MUST return EINVAL. It is not valid for established keying or 1454 algorithm information to change without the SPI changing, which would 1455 require creation of a new SA rather than a change to an existing SA. 1456 Once keying and algorithm information is negotiated, address and 1457 identity information is fixed for the SA. Therefore, if the original 1458 SA is a SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state field 1459 in the SA header and lifetimes (hard, soft, and current) may be 1460 changed and any attempt to change other values MUST result in an 1461 error return of EINVAL. 1463 The message behavior of the SADB_UPDATE message is: 1465 Send a SADB_UPDATE message from a user process to the kernel. 1467 1470 The kernel returns the SADB_UPDATE message to all listening 1471 processes. 1473 1476 The keying material is not returned on the message from the kernel 1477 to listening sockets because listeners might not have the privileges 1478 to see such keying material. 1480 Errors: 1481 ESRCH The security association to be updated was not found. 1482 EINVAL In addition to other possible causes, this error is 1483 returned if sanity checking on the SA values (such 1484 as the keys) fails. 1485 EACCES Insufficient privilege to update entry. The socket 1486 issuing the SADB_UPDATE is not creator of the entry 1487 to be updated. 1489 3.1.3 SADB_ADD 1491 The SADB_ADD message is nearly identical to the SADB_UPDATE 1492 message, except that it does not require a previous call to 1493 SADB_GETSPI. The SADB_ADD message is used in manual keying 1494 applications, and in other cases where the uniqueness of the SPI is 1495 known immediately. 1497 An SADB_ADD message is also used when negotiation is finished, and 1498 the second of a pair of associations is added. The SPI for this 1499 association was determined by the peer machine. It MAY be useful to 1500 set the sadb_msg_seq to that of a kernel-generated SADB_ACQUIRE so 1501 that both associations in a pair are bound to the same ACQUIRE 1502 request. 1504 The kernel MUST sanity check all used fields in the SA submitted in 1505 a SADB_ADD message before adding the SA to its database and MUST 1506 return EINVAL if any of the values are invalid. 1508 Only SADB_SASTATE_MATURE SAs may be submitted in a SADB_ADD 1509 message. SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is 1510 not sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state. 1511 Therefore, the sadb_sa_state field of all submitted SAs MUST be 1512 SADB_SASTATE_MATURE and the kernel MUST return an error if this is 1513 not true. 1515 The message behavior of the SADB_ADD message is: 1517 Send a SADB_ADD message from a user process to the kernel. 1519 1522 The kernel returns the SADB_ADD message to all listening 1523 processes. 1525 1528 The keying material is not returned on the message from the kernel to 1529 listening sockets because listeners may not have the privileges to see 1530 such keying material. 1532 Errors: 1534 EEXIST The security association that was to be added already 1535 exists. 1536 EINVAL In addition to other possible causes, this error is 1537 returned if sanity checking on the SA values (such 1538 as the keys) fails. 1540 3.1.4 SADB_DELETE 1542 The SADB_DELETE message causes the kernel to delete a Security 1543 Association from the key table. The delete message consists of the 1544 base header followed by the association, and the source and 1545 destination sockaddrs in the address extension. The kernel deletes 1546 the security association matching the type, spi, source address, and 1547 destination address in the message. 1549 The message behavior for SADB_DELETE is as follows: 1551 Send a SADB_DELETE message from a user process to the kernel. 1553 1555 The kernel returns the SADB_DELETE message to all listening 1556 processes. 1558 1560 3.1.5 SADB_GET 1562 The SADB_GET message allows a process to retrieve a copy of a 1563 Security Association from the kernel's key table. The get message 1564 consists of the base header follows by the relevant extension fields. 1565 The Security Association matching the type, spi, source address, and 1566 destination address is returned. 1568 The message behavior of the SADB_GET message is: 1570 Send a SADB_GET message from a user process to the kernel. 1572 1574 The kernel returns the SADB_GET message to the socket that sent 1575 the SADB_GET message. 1577 1580 Errors: 1581 ESRCH The sought security association was not found. 1583 3.1.6 SADB_ACQUIRE 1585 The SADB_ACQUIRE message is typically sent only by the kernel to 1586 key socket listeners who have registered their key socket (see 1587 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 1588 application-level consumers of security associations (such as an 1589 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 1590 message is a base header along with an address extension, possibly a 1591 identity extension, and a proposal extension. The proposed situation 1592 contains a list of desirable algorithms that can be used if the 1593 algorithms in the base header are not available. The values for the 1594 fields in the base header and in the security association data which 1595 follows the base header indicate the properties of the Security 1596 Association that the listening process should attempt to acquire. If 1597 the message originates from the kernel (i.e. the sadb_msg_pid is 0), 1598 the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI 1599 message to bind a security association to the request. This avoids 1600 the race condition of two TCP connections between two IP hosts that 1601 each require unique associations, and having one steal another's 1602 security association. The sadb_msg_errno and sadb_msg_state fields 1603 should be ignored by the listening process. 1605 The SADB_ACQUIRE message is typically triggered by an outbound 1606 packet that needs security but for which there is no applicable 1607 Security Association existing in the key table. If the packet can be 1608 sufficiently protected by more than one algorithm or combination of 1609 options, the SADB_ACQUIRE message MUST order the preference of 1610 possibilities in the Proposal extension. 1612 There are three messaging behaviors for SADB_ACQUIRE. The first is 1613 where the kernel needs a security association (e.g. for IPsec). 1615 The kernel sends a SADB_ACQUIRE message to registered sockets. 1617 1619 The second is when, for some reason, key management fails, it can 1620 send an ACQUIRE message with the same sadb_msg_seq as the initial 1621 ACQUIRE with a non-zero errno. 1623 Send an SADB_ACQUIRE to indicate key management failure. 1625 1627 The third is where an application-layer consumer of security 1628 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 1629 association. 1631 Send a SADB_ACQUIRE message from a user process to the kernel. 1633 1635 The kernel returns a SADB_ACQUIRE message to registered sockets. 1637 1639 The user-level consumer waits for a SADB_UPDATE or SADB_ADD 1640 message for its particular type, and then can use that 1641 association by using SADB_GET messages. 1643 Errors: 1644 EINVAL Invalid acquire request. 1645 EPROTONOSUPPORT No KM application has registered with the Key 1646 Engine as being able to obtain the requested SA type, so 1647 the requested SA cannot be acquired. 1649 3.1.7 SADB_REGISTER 1651 The SADB_REGISTER message allows an application to register its key 1652 socket as able to acquire new security associations for the kernel. 1653 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 1654 the type of security association specified in sadb_msg_satype. The 1655 application specifies the type of security association that it can 1656 acquire for the kernel in the type field of its register message. If 1657 an application can acquire multiple types of security association, it 1658 MUST register each type in a separate message. Only the base header 1659 is needed for the register message. Key management applications MAY 1660 register for a type not known to the kernel, because the consumer may 1661 be in user-space (e.g. OSPFv2 security). 1663 The reply of the SADB_REGISTER message contains a supported 1664 algorithm extension. That field contains an array of supported 1665 algorithm, one per octet. This allows key management applications to 1666 know what algorithm are supported by the kernel. 1668 In an environment where algorithms can be dynamically loaded and 1669 unloaded, an asynchronous SADB_REGISTER reply MAY be generated. The 1670 list of supported algorithms MUST be a complete list, so the 1671 application can make note of omissions or additions. 1673 The messaging behavior of the SADB_REGISTER message is: 1675 Send a SADB_REGISTER message from a user process to the kernel. 1677 1679 The kernel returns a SADB_REGISTER message to registered 1680 sockets, with algorithm types supported by the kernel being 1681 indicated in the supported algorithms field. 1683 NOTE: This message may arrive asynchronously due to an 1684 algorithm being loaded or unloaded into a dynamically 1685 linked kernel. 1687 1689 3.1.8 SADB_EXPIRE Message 1691 The operating system kernel is responsible for tracking SA 1692 expirations for security protocols that are implemented inside the 1693 kernel. If the soft limit or hard limit of a Security Association 1694 has expired for a security protocol implemented inside the kernel, 1695 then the kernel MUST issue an SADB_EXPIRE message to all key socket 1696 listeners. If the soft limit or hard limit of a Security Association 1697 has expired, the user application SHOULD issue a SADB_EXPIRE message. 1699 The base header will contain the security association information 1700 followed by the source sockaddr, destination sockaddr, (and, if 1701 present, internal sockaddr,) (and, if present, one or both 1702 compartment bitmaps). 1704 The lifetime extension of an SADB_EXPIRE message is important to 1705 indicate which lifetime expired. If a HARD lifetime extension is 1706 included, it indicates that the HARD lifetime expired. This means 1707 the association MAY be deleted already from the SADB. If a SOFT 1708 lifetime extension is included, it indicates that the SOFT lifetime 1709 expired. The CURRENT lifetime extension will indicate the current 1710 status, and comparisons to the HARD or SOFT lifetime will indicate 1711 which limit was reached. HARD lifetimes MUST take precedence over 1712 SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same, 1713 the HARD lifetime will appear on the EXPIRE message. The 1714 pathological case of HARD lifetimes being shorter than SOFT lifetimes 1715 is handled such that the SOFT lifetime will never expire. 1717 The messaging behavior of the SADB_EXPIRE message is: 1719 The kernel sends a SADB_EXPIRE message to all listeners when 1720 the soft limit of a security association has been expired. 1722 1724 Note that the SADB_EXPIRE message is ONLY sent by the kernel to the 1725 KMd. It is a one-way informational message that does not have a 1726 reply. 1728 3.1.9 SADB_FLUSH 1730 The SADB_FLUSH message causes the kernel to delete all entries in 1731 its key table for a certain sadb_msg_satype. Only the base header is 1732 required for a flush message. If sadb_msg_satype is filled in with a 1733 specific value, only associations of that type are deleted. If it is 1734 filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted. 1736 The messaging behavior for SADB_FLUSH is: 1738 Send a SADB_FLUSH message from a user process to the kernel. 1740 1742 The kernel will return a SADB_FLUSH message to all listening 1743 sockets. 1745 1747 The reply message happens only after the actual flushing 1748 of security associations has been attempted. 1750 3.1.10 SADB_DUMP 1752 The SADB_DUMP message causes the kernel to dump the operating 1753 system's entire Key Table to the requesting key socket. As in 1754 SADB_FLUSH, if a sadb_msg_satype value is in the message, only 1755 associations of that type will be dumped. If SADB_SATYPE_UNSPEC is 1756 specified, all associations will be dumped. Each Security Association 1757 is returned in its own SADB_DUMP message. A SADB_DUMP message with a 1758 sadb_seq field of zero indicates the end of the dump transaction. The 1759 dump message is used for debugging purposes only and is not intended 1760 for production use. 1762 Support for the dump message MAY be discontinued in future versions 1763 of PF_KEY. Key management applications MUST NOT depend on this 1764 message for basic operation. 1766 The messaging behavior for SADB_DUMP is: 1768 Send a SADB_DUMP message from a user process to the kernel. 1770 1772 Several SADB_DUMP messages will return from the kernel to the 1773 sending socket. 1775 1778 3.2 Security Association Flags 1780 The Security Association's flags are a bitmask field. These flags 1781 also appear in a combination that is part of a PROPOSAL extension. 1782 The related symbolic definitions below should be used in order that 1783 applications will be portable: 1785 #define SADB_SAFLAGS_PFS 1 /* perfect forward secrecy */ 1787 The SADB_SAFLAGS_PFS flag indicates to key management that this 1788 association should have perfect forward secrecy in its key. (In 1789 other words, any given session key cannot be determined by 1790 cryptanalysis of previous session keys or some master key.) 1792 3.3 Security Association States 1794 The security association state field is an integer that describes 1795 the states of a security association. They are: 1797 #define SADB_SASTATE_LARVAL 0 1798 #define SADB_SASTATE_MATURE 1 1799 #define SADB_SASTATE_DYING 2 1800 #define SADB_SASTATE_DEAD 3 1802 #define SADB_SASTATE_MAX 3 1804 A SADB_SASTATE_LARVAL security association is one that was created 1805 by the SADB_GETSPI message. A SADB_SASTATE_MATURE association is one 1806 that was updated with the SADB_UPDATE message or added with the 1807 SADB_ADD message. A DYING association is one whose soft lifetime has 1808 expired. A SADB_SASTATE_DEAD association is one whose hard lifetime 1809 has expired, but hasn't been reaped by system garbage collection. If 1810 a consumer of security associations has to extend an association 1811 beyond its normal lifetime (e.g. OSPF Security) it MUST only set the 1812 soft lifetime for an association. 1814 3.4 Security Association Types 1816 This defines the type of Security Association in this message. The 1817 symbolic names are always the same, even on different 1818 implementations. Applications SHOULD use the symbolic name in order 1819 to have maximum portability across different implementations. These 1820 are defined in the file . 1822 #define SADB_SATYPE_UNSPEC 0 1824 #define SADB_SATYPE_AH 1 /* RFC-1826 */ 1825 #define SADB_SATYPE_ESP 2 /* RFC-1827 */ 1827 #define SADB_SATYPE_RSVP 3 /* RSVP Authentication */ 1828 #define SADB_SATYPE_OSPFV2 4 /* OSPFv2 Authentication */ 1829 #define SADB_SATYPE_RIPV2 5 /* RIPv2 Authentication */ 1830 #define SADB_SATYPE_MIP 6 /* Mobile IP Auth. */ 1832 #define SADB_SATYPE_MAX 6 1834 SADB_SATYPE_UNSPEC is defined for completeness and means no specific 1835 type of security association. This type is never used with PF_KEY 1836 SAs. 1838 SADB_SATYPE_AH is for the IP Authentication Header [Atk95b]. 1840 SADB_SATYPE_ESP is for the IP Encapsulating Security Payload 1841 [Atk95c]. 1843 SADB_SATYPE_RSVP is for the RSVP Integrity Object [Baker97]. 1845 SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication 1846 [Moy97]. 1848 SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97]. 1850 SADB_SATYPE_MIP is for Mobile IP's authentication extensions 1851 [Perkins97]. 1853 SADB_SATYPE_MAX is always set to the highest valid numeric value. 1854 There MUST not be gaps in the numbering of security types; all 1855 numbers must be used sequentially. 1857 3.5 Algorithm Types 1859 The algorithm type is interpreted in the context of the Security 1860 Association type defined above. The numeric value might vary between 1861 implementations, but the symbolic name MUST NOT vary between 1862 implementations. Applications should use the symbolic name in order 1863 to have maximum portability to various implementations. 1865 Some of the algorithm types defined below might not be standardized 1866 or might be deprecated in the future. To obtain an assignment for a 1867 symbolic name, contact the authors. 1869 The symbols below are defined in . 1871 /* Authentication algorithms */ 1872 #define SADB_AALG_NONE 0 1873 #define SADB_AALG_MD5HMAC 1 1874 #define SADB_AALG_SHA1HMAC 2 1875 #define SADB_AALG_MAX 2 1877 /* Encryption algorithms */ 1878 #define SADB_EALG_NONE 0 1879 #define SADB_EALG_DESCBC 1 1880 #define SADB_EALG_3DESCBC 2 1881 #define SADB_EALG_MAX 2 1883 The algorithm for SADB_AALG_MD5_HMAC is defined in [OG96]. The 1884 algorithm for SADB_AALG_SHA1HMAC is defined in [CG96]. The algorithm 1885 for SADB_EALG_DESCBC is defined in [Hug96]. 1887 3.6 Extension Header Values 1889 To briefly recap the extension header values: 1891 #define SADB_EXT_RESERVED 0 1892 #define SADB_EXT_SA 1 1893 #define SADB_EXT_LIFETIME_CURRENT 2 1894 #define SADB_EXT_LIFETIME_HARD 3 1895 #define SADB_EXT_LIFETIME_SOFT 4 1896 #define SADB_EXT_ADDRESS_SRC 5 1897 #define SADB_EXT_ADDRESS_DST 6 1898 #define SADB_EXT_ADDRESS_PROXY 7 1899 #define SADB_EXT_KEY_AUTH 8 1900 #define SADB_EXT_KEY_ENCRYPT 9 1901 #define SADB_EXT_IDENTITY_SRC 10 1902 #define SADB_EXT_IDENTITY_DST 11 1903 #define SADB_EXT_SENSITIVITY 12 1904 #define SADB_EXT_PROPOSAL 13 1905 #define SADB_EXT_SUPPORTED_AUTH 14 1906 #define SADB_EXT_SUPPORTED_ENCRYPT 15 1907 #define SADB_EXT_SPIRANGE 16 1909 #define SADB_EXT_MAX 16 1911 3.7 Identity Extension Values 1913 Each identity can have a certain type. 1915 #define SADB_IDENTTYPE_RESERVED 0 1916 #define SADB_IDENTTYPE_PREFIX 1 1917 #define SADB_IDENTTYPE_FQDN 2 1918 #define SADB_IDENTTYPE_USER_FQDN 3 1920 #define SADB_IDENTTYPE_MAX 3 1922 The PREFIX identity string consists of a network address followed 1923 by a forward slash and a prefix length. The network address is in a 1924 printable numeric form appropriate for the protocol family. The 1925 prefix length is a decimal number greater than or equal to zero and 1926 less than the number of bits in the network address. It indicates the 1927 number of bits in the network address that are significant; all bits 1928 in the network address that are not significant MUST be set to zero. 1929 Note that implementations MUST parse the contents of the printable 1930 address into a binary form for comparison purposes because multiple 1931 printable strings are valid representations of the same address in 1932 many protocol families (for example, some allow leading zeros and 1933 some have letters that are case insensitive). Examples of PREFIX 1934 identities are "199.33.248.64/27" and 1935 "5f00:3000:c721::f800:19:1/128". If the source or destination 1936 identity is a PREFIX identity, the source or destination address for 1937 the SA (respectively) MUST be within that prefix. 1939 The FQDN identity string contains a fully qualified domain name. An 1940 example FQDN identity is "ministry-of-truth.inner.net". 1942 The USER_FQDN identity consists of a text string in the format 1943 commonly used for Internet-standard electronic mail. The syntax is 1944 the text username, followed by the "@" character, followed in turn by 1945 the appropriate fully qualified domain name. This identity specifies 1946 both a username and an associated FQDN. There is no requirement that 1947 this string specify a mailbox valid for SMTP or other electronic mail 1948 use. This identity is useful with protocols supporting user-oriented 1949 keying. It is a convenient identity form because the DNS Security 1950 extensions can be used to distribute signed public key values by 1951 associating KEY and SIG records with an appropriate MB DNS record. An 1952 example USER_FQDN identity is "julia@ministry-of-love.inner.net". 1954 [cmetz: We may want to have an identity for certain protocol/port 1955 "service" combinations. The requirements of such an identity are not 1956 yet certain, so we will wait until later to define it for PF_KEYv2. 1957 Remember that we can add new identity types later as needed.] 1959 3.8 Sensitivity Extension Values 1961 The only field currently defined in the sensitivity extension is 1962 the sadb_sens_dpd, which represents the data protection domain. The 1963 other data in the sensitivity extension is based off the 1964 sadb_sens_dpd value. 1966 The DP/DOI is defined to be the same as the "Labeled Domain 1967 Identifier Value" of the IP Security DOI specification [Piper97]. As 1968 noted in that specification, values in the range 0x80000000 to 1969 0xffffffff (inclusive) are reserved for private use and values in the 1970 range 0x00000001 through 0x7fffffff are assigned by IANA. The all- 1971 zeros DP/DOI value is permanently reserved to mean that "no DP/DOI is 1972 in use". 1974 3.9 Proposal Extension Values 1976 These are already mentioned in the ALGORITHM TYPES and ASSOCIATION 1977 FLAGS sections. 1979 4 Future Directions 1981 While the current specification for the Sensitivity and Integrity 1982 Labels is believed to be general enough, if a case should arise that 1983 can't work with the current specification then this might cause a 1984 change in a future version of PF_KEY. 1986 Similarly, PF_KEY might need extensions to work with other kinds of 1987 Security Associations in future. It is strongly desirable for such 1988 extensions to be made in a backwards-compatible manner should they be 1989 needed. 1991 ******* 1992 [ALL: What else belongs here ? ] 1993 ******* 1995 5 Examples 1997 The following examples illustrate how PF_KEY is used. The first 1998 example is an IP Security example, where the consumer of the security 1999 associations is inside an operating system kernel. The second example 2000 is an OSPF Security example, which illustrates a user-level consumer 2001 of security associations. The third example covers things not 2002 mentioned by the first two examples. A real system may closely 2003 conform to one of these examples, or take parts of them. These 2004 examples are purely illustrative, and are not intended to mandate a 2005 particular implementation method. 2007 5.1 Simple IP Security Example 2009 +---------------+ +-------------+ 2010 |Key Mgmt Daemon| | Application | 2011 +---------------+ +-------------+ 2012 | | / 2013 | | / 2014 | | | Applications 2015 ======[PF_KEY]====[PF_INET]========================== 2016 | | | OS Kernel 2017 +------------+ +-----------------+ 2018 | Key Engine | | TCP/IP, | 2019 | or SADB |---| including IPsec | 2020 +------------+ | | 2021 +-----------------+ 2023 When the Key Management daemon (KMd) begins. It must tell PF_KEY 2024 that it is willing to accept message for the two IPsec services, AH 2025 and ESP. It does this by sending down two SADB_REGISTER messages. 2027 KMd->Kernel: SADB_REGISTER for ESP 2028 Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms 2029 KMd->Kernel: SADB_REGISTER for AH 2030 Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms 2032 Each REGISTER message will cause a reply to go to all PF_KEY sockets 2033 registered for ESP and AH respectively (including the requester). 2035 Assume that no security associations currently exist for IPsec to 2036 use. Consider when a network application begins transmitting data 2037 (e.g. a TCP SYN). Because of policy, or the application's request, 2038 the kernel IPsec module needs an AH security association for this 2039 data. Since there is not one present, the following message is 2040 generated: 2042 Kernel->Registered: SADB_ACQUIRE for AH, addrs, ID, sens, 2043 proposals 2045 The KMd reads the ACQUIRE message, especially the sadb_msg_seq 2046 number. Before it begins the negotiation, it sends down an 2047 SADB_GETSPI message with the sadb_msg_seq number equal to the one 2048 received in the ACQUIRE. The kernel returns the results of the 2049 GETSPI to all listening sockets. 2051 KMd->Kernel: SADB_GETSPI for AH, addr, SPI range 2052 Kernel->All: SADB_GETSPI for AH, assoc, addrs 2054 The KMd may perform a second GETSPI operation if it needs both 2055 directions of IPsec SPI values. Now that the KMd has an SPI for at 2056 least one of the security associations, it begins negotiation. After 2057 deriving keying material, and negotiating other parameters, it sends 2058 down one (or more) SADB_UPDATE messages with the same value in 2059 sadb_msg_seq. 2061 If a KMd has any error at all during its negotiation, it can send 2062 down 2064 KMd->Kernel: SADB_UPDATE for AH, assoc (with an error) 2065 Kernel->All: SADB_UPDATE for AH, assoc (same error) 2067 but if it succeeds, it can instead 2069 KMd->Kernel: SADB_UPDATE for AH, assoc, addrs, keys, 2070 2071 Kernel->All: SADB_UPDATE for AH, assoc, addrs, 2073 The results of the UPDATE (minus the actual keys) are sent to all 2074 listening sockets. If only one SPI value was determined locally, the 2075 other SPI (since IPsec SAs are unidirectional) must be added with an 2076 SADB_ADD message. 2078 KMd->Kernel: SADB_ADD for AH, assoc, addrs, keys, 2079 Kernel->All: SADB_ADD for AH, assoc, addrs, 2081 If one of the extensions passed down was a Lifetime extension, it 2082 is possible at some point an SADB_EXPIRE message will arrive when one 2083 of the lifetimes has expired. 2085 Kernel->All: SADB_EXPIRE for AH, assoc, addrs, 2086 Hard or Soft, Current, 2088 The KMd can use this as a clue to begin negotiation, or, if it has 2089 some say in policy, send an SADB_UPDATE down with a lifetime 2090 extension. 2092 5.2 Proxy IP Security Example 2094 Many people are interested in using IP Security in a "proxy" 2095 or "firewall" configuration in which an intermediate system provides 2096 security services for "inside" hosts. In these environments, the 2097 intermediate systems can use PF_KEY to communicate with key 2098 management applications almost exactly as they would if they were the 2099 actual endpoints. The messaging behavior of PF_KEY in these cases is 2100 exactly the same as the previous example, but the address information 2101 is slightly different. 2103 Consider this case: 2105 A ========= B --------- C 2107 Key: 2108 A "outside" host that implements IPsec 2109 B "firewall" that implements IPsec 2110 C "inside" host that does not implement IPsec 2112 === IP_{A<->B} ESP [ IP_{A<->C} ULP ] 2113 --- IP_{A<->C} ULP 2115 A is a single system that wishes to communicate with the "inside" 2116 system C. B is a "firewall" between C and the outside world that 2117 will do ESP and tunnelling on C's behalf. A discovers that it needs 2118 to send traffic to C via B through methods not described here (Use of 2119 the DNS' KX record might be one method for discovering this). 2121 For packets that flow from left to right, A and B need an 2122 IPsec Security Association with: 2124 SA type of ESP tunnel-mode 2125 Source Identity that dominates A (e.g. A's address) 2126 Destination Identity that dominates B (e.g. B's address) 2127 No Proxy Identity or a Proxy Identity that dominates A. 2129 For packets to flow from right to left, A and B need an IPsec 2130 Security Association with: 2131 SA type of ESP tunnel-mode 2132 Source Identity that dominates C. 2133 Destination Identity that dominates A. 2134 Proxy Identity that dominates B. 2136 For this second SA (for packets flowing from C towards A), node A 2137 MUST verify that the outer source address is dominated by the Proxy 2138 Identity for the SA used with those packets. If node A does not do 2139 this, node B could forge packets with an arbitrary Source Identity 2140 and defeat the packet origin protections provided by IPsec. 2142 Now consider a slightly more complex case: 2144 A_1 --| |-- D_1 2145 |--- B ====== C ---| 2146 A_2 --| |-- D_2 2148 Key: 2149 A_n "inside" host on net 1 that does not do IPsec. 2150 B "firewall" for net 1 that supports IPsec. 2151 C "firewall" for net 2 that supports IPsec. 2152 D_n "inside" host on net 2 that does not do IPsec. 2153 === IP_{B<->C} ESP [ IP_{A<->C} ULP ] 2154 --- IP_{A<->C} ULP 2156 For A_1 to send a packet to D_1, B and C need a SA with: 2158 SA Type of ESP 2159 Source Identity that dominates A_1. 2160 Destination Identity that dominates C. 2161 Proxy Identity that dominates B. 2163 For D_1 to send a packet to A_1, C and B need a SA with: 2164 SA Type of ESP Tunnel-mode 2165 Source Identity that dominates D_1. 2166 Destination Identity that dominates B. 2167 Proxy Identity that dominates C. 2169 Note that A_2 and D_2 could be substituted for A_1 and D_1 2170 (repectively) here; the association of an SA with a particular pair 2171 of ends or group of those pairs is a policy decision on B and/or C 2172 and not necessarily a function of key management. The same check of 2173 the Proxy Identity against the outer source IP address MUST also be 2174 performed in this case for the same reason. 2176 For a more detailed discussion of the use of IP Security in complex 2177 cases, please see [Atk97]. 2179 NOTE: The notion of identity domination might be unfamiliar. 2180 Let H represent some node. Let Hn represent H's fully qualified 2181 domain name. Let Ha represent the IP address of H. Let Hs 2182 represent the IP subnet containing Ha. Let Hd represent a fully 2183 qualified domain name that is a parent of the fully qualified 2184 domain name of H. Let M be a MBOX identity that whose right- 2185 hand part is Hn or Ha. 2187 Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the 2188 example above. Hs dominates any node having an IP address 2189 within the IP address range represented by Hs. Hd dominates any 2190 node having a fully qualified domain name within underneath Hd. 2192 5.3 OSPF Security Example 2194 +---------------+ +-------------+ 2195 |Key Mgmt Daemon| | OSPF daemon | 2196 +---------------+ +-------------+ 2197 | | / / | 2198 | /------|----+ / | 2199 | / | +---+ | Applications 2200 ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================ 2201 | | | | OS Kernel 2202 +------------+ +-----------------+ +---------+ 2203 | Key Engine | | TCP/IP, | | Routing | 2204 | or SADB |---| including IPsec |--| Table | 2205 +------------+ | | +---------+ 2206 +-----------------+ 2208 As in the previous examples, the KMd registers itself with the Key 2209 Engine via PF_KEY. Even though the consumer of the security 2210 associations is in user-space, the PF_KEY and Key Engine 2211 implementation knows enough to store SAs and to relay messages. 2213 When the OSPF daemon needs to communicate securely with its peers, 2214 it would perform an SADB_GET message and retrieve the appropriate 2215 association: 2217 OSPFd->Kernel: SADB_GET of OSPF, assoc, addrs 2218 Kernel->OSPFd: SADB_GET of OSPF, assoc, addrs, keys, 2220 If this GET fails, the OSPFd may need to acquire a new security 2221 association. This interaction is as follows: 2223 OSPFd->Kernel: SADB_ACQUIRE of OSPF, addrs, 2224 proposal 2225 Kernel->Registered: SADB_ACQUIRE of OSPF, 2227 The KMd sees this and performs actions similar to the previous 2228 example. One difference, however, is that when the UPDATE message 2229 comes back, the OSPFd will then perform a GET of the updated SA to 2230 retrieve all of its parameters. 2232 5.4 Miscellaneous 2234 Some messages work well only in system maintenance programs, for 2236 debugging, or for auditing. In a system panic situation, such as a 2237 detected compromise, an SADB_FLUSH message should be issued for a 2238 particular SA type, or for ALL SA types. 2240 Program->Kernel: SADB_FLUSH for ALL 2241 2242 Kernel->All: SADB_FLUSH for ALL 2244 Some SAs may need to be explicitly deleted, either by a KMd, or by 2245 a system maintenance program. 2247 Program->Kernel: SADB_DELETE for AH, association, addrs 2248 Kernel->All: SADB_DELETE for AH, association, addrs 2250 Common usage of the SADB_DUMP message is discouraged. For 2251 debugging purposes, however, it can be quite useful. The output of a 2252 DUMP message should be read quickly, in order to avoid socket buffer 2253 overflows. 2255 Program->Kernel: SADB_DUMP for ESP 2256 Kernel->Program: SADB_DUMP for ESP, association, 2257 Kernel->Program: SADB_DUMP for ESP, association, 2258 Kernel->Program: SADB_DUMP for ESP, association, 2259 2261 6 Security Considerations 2263 This draft discusses a method for creating, reading, modifying, and 2264 deleting Security Associations from an operating system. Only 2265 trusted, privileged users and processes should be able to perform any 2266 of these operations. It is unclear whether this mechanism provides 2267 any security when used with operating systems not having the concept 2268 of a trusted, privileged user. 2270 If an unprivileged user is able to perform any of these operations, 2271 then the operating system cannot actually provide the related 2272 security services. If an adversary knows the keys and algorithms in 2273 use, then cryptography cannot provide any form of protection. 2275 This mechanism is not a panacea, but it does provide an important 2276 operating system component that can be useful in creating a secure 2277 internetwork. 2279 Users need to understand that the quality of the security provided 2280 by an implementation of this specification depends completely upon 2281 the overall security of the operating system, the correctness of the 2282 PF_KEY implementation, and upon the security and correctness of the 2283 applications that connect to PF_KEY. It is appropriate to use high 2284 assurance development techniques when implementing PF_KEY and the 2285 related security association components of the operating system. 2287 Acknowledgments 2289 The authors of this document are listed primarily in alphabetical 2290 order. Randall Atkinson and Ron Lee provided useful feedback on 2291 earlier versions of this document. 2293 At one time or other, all of the authors worked at the Center for 2294 High Assurance Computer Systems at the U.S. Naval Research 2295 Laboratory. This work was sponsored by the Information Security 2296 Program Office (PMW-161), U.S. Space and Naval Warfare Systems 2297 Command (SPAWAR) and the Computing Systems Technology Office, Defense 2298 Advanced Research Projects Agency (DARPA/CSTO). We really appreciate 2299 their sponsorship of our efforts and their continued support of 2300 PF_KEY development. Without that support, PF_KEY would not exist. 2302 The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST97]. 2304 Finally, the authors would like to thank those who sent in comments 2305 and questions on the various iterations of this document. This 2306 specification and implementations of it are discussed on the PF_KEY 2307 mailing list. If you would like to be added to this list, send a note 2308 to . 2310 References 2312 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig 2313 W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 2314 4.4-Lite BSD", Proceedings of the 1996 USENIX Conference, 2315 San Diego, CA, January 1996, USENIX Association. 2317 [Atk95a] Randall J. Atkinson, "IP Security Architecture", RFC 1825, 2318 August 1995. 2320 [Atk95b] Randall J. Atkinson, "IP Authentication Header", RFC 1826, 2321 August 1995. 2323 [Atk95c] Randall J. Atkinson, "IP Encapsulating Security Payload", 2324 RFC 1827, August 1995. 2326 [Atk97] Atkinson, Randall, "Key Exchange Delegation Record for the 2327 Domain Name System", Internet-draft, June 1997." 2329 [BA97] F. Baker and R. Atkinson, "RIP-2 MD5 Authentication", 2330 RFC 2082, January 1997. 2332 [Baker97] Fred Baker, "RSVP Cryptographic Authentication", Internet 2333 Draft, May 1997. 2335 [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer 2336 Systems", MTR-3153, The MITRE Corporation, June 1975; 2337 ESD-TR-76-372, April 1977. 2339 [BL74] D. Elliot Bell and Leonard J. LaPadula, "Secure Computer 2340 Systems: Unified Exposition and Multics Interpretation", 2341 MTR 2997, The MITRE Corporation, April 1974. (AD/A 020 445) 2343 [CG96] S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with 2344 Replay Prevention", Internet Draft, May 1996. 2346 [CW87] D. D. Clark and D. R. Wilson, "A Comparison of Commercial 2347 and Military Computer Security Policies", Proceedings of the 2348 1987 Symposium on Security and Privacy, pp. 184-195, IEEE 2349 Computer Society, Washington, D.C., 1987 2351 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 2352 Workstation Specification", Technical Report 2353 DDS-2600-6243-87. 2355 [DMS97] Dorsaway, N., Metzger, P., Simpson, W. A., "The ESP Triple- 2356 DES Transform," Internet-Draft. 2358 [HM97a] H. Harney, C. Muckenhirn, "Group Key Management Protocol 2359 (GKMP) Specification", RFC 2093, July 1997. 2361 [HM97b] H. Harney, C. Muckenhirn, "Group Key Management Protocol 2362 (GKMP) Architecture", RFC 2094, July 1997. 2364 [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay 2365 Prevention Security Transform", Internet Draft, April 1996. 2367 [MSST97] Douglas Maughan, Mark Schertler, Mark Schneider, Jeff 2368 Turner, "Internet Security Association and Key Management 2369 Protocol (ISAKMP)", Internet Draft, February 1997. 2371 [Moy97] J. Moy, "OSPF Version 2", Internet Draft, April 1997. 2373 [OG96] Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with 2374 Replay Prevention", Internet Draft, May 1996. 2376 [Perkins97] C. Perkins, "IP Mobility Support", RFC 2002, 2377 October 1996. 2379 [Piper97] Derrel Piper, "The Internet IP Security Domain of 2380 Interpretation for ISAKMP", Internet Draft, February 1997. 2382 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for 2383 Berkeley UNIX", Proceedings of the Winter 1991 USENIX 2384 Conference, Dallas, TX, USENIX Association. 1991. 2385 pp. 93-103. 2387 Disclaimer 2389 The views and specification here are those of the editors and are 2390 not necessarily those of their employers. The employers have not 2391 passed judgment on the merits, if any, of this work. The editors and 2392 their employers specifically disclaim responsibility for any problems 2393 arising from correct or incorrect implementation or use of this 2394 specification. 2396 Authors' Addresses 2398 Daniel L. McDonald 2399 Sun Microsystems, Inc. 2400 2550 Garcia Avenue, MS UMPK17-202 2401 Mountain View, CA 94043-1100 2402 E-mail: danmcd@eng.sun.com 2404 Craig Metz 2405 The Inner Net 2406 Box 10314-1932 2407 Blacksburg, VA 24062-0314 2408 PSTN: +1 202 404 8590 2409 DSN: 354-8590 2410 E-mail: cmetz@inner.net 2412 Bao G. Phan 2413 Advanced Network Systems 2414 E-mail: phan@reston.ans.net 2416 Appendix A: Promiscuous Send/Receive Extension 2418 A kernel supporting PF_KEY MAY implement the following extension 2419 for development and debugging purposes. If it does, it MUST implement 2420 the extension as specified here. An implementation MAY require an 2421 application to have additional privileges to perform promiscuous send 2422 and/or receive operations. 2424 The SADB_X_PROMISC message allows an application to send and 2425 receive messages in a "promiscuous mode." There are two forms of this 2426 message: control and data. The control form consists of only a 2427 message header. This message is used to toggle the promiscuous- 2428 receive function. A value of one in the sadb_msg_satype field enables 2429 promiscuous message reception for this socket, while a value of zero 2430 in that field disables it. 2432 The second form of this message is the data form. This is used to 2433 send or receive messages in their raw form. Messages in the data form 2434 consist of a message header followed by an entire new message. There 2435 will be two message headers in a row: one for the SADB_X_PROMISC 2436 message, and one for the payload message. 2438 Data messages sent from the application are sent to either the 2439 PF_KEY socket of a single process identified by a nonzero 2440 sadb_msg_seq or to all PF_KEY sockets if sadb_msg_seq is zero. These 2441 messages are sent without any processing of their contents by the 2442 PF_KEY interface (including sanity checking). This promiscuous-send 2443 capability allows an application to send messages as if it were the 2444 kernel. This also allows it to send erroneous messages. 2446 If the promiscuous-receive function has been enabled, a copy of any 2447 message sent via PF_KEY by another application or by the kernel is 2448 sent to the promiscuous application. This is done before any 2449 processing of the message's contents by the PF_KEY interface (again, 2450 including sanity checking). This promiscuous-receive capability 2451 allows an application to receive all messages sent by other parties 2452 using PF_KEY. 2454 The messaging behavior of the SADB_X_PROMISC message is: 2456 Send a control-form SADB_X_PROMISC message from a user process 2457 to the kernel. 2459 2461 The kernel returns the SADB_X_PROMISC message to all listening 2462 processes. 2464 2466 Send a data-form SADB_X_PROMISC message from a user process to 2467 the kernel. 2469 2471 The kernel sends the encapsulated message to the target 2472 process(s). 2474 2476 If promiscuous-receive is enabled, the kernel will encapsulate 2477 and send copies of all messages sent via the PF_KEY interface. 2479 2481 Errors: 2482 EPERM Additional privileges are required to perform the 2483 requested operations. 2484 ESRCH (Data form, sending) The target process in sadb_msg_seq 2485 does not exist or does not have an open PF_KEY Version 2 2486 socket. 2488 Appendix B: Sample Header File 2490 /* 2491 This file defines structures and symbols for the PF_KEY Version 2 2492 key management interface. It was written at the U.S. Naval Research 2493 Laboratory. This file is in the public domain. The authors ask that 2494 you leave this credit intact on any copies of this file. 2495 */ 2496 #ifndef __PFKEY_V2_H 2497 #define __PFKEY_V2_H 1 2499 #define PF_KEY_V2 2 2501 #define SADB_RESERVED 0 2502 #define SADB_GETSPI 1 2503 #define SADB_UPDATE 2 2504 #define SADB_ADD 3 2505 #define SADB_DELETE 4 2506 #define SADB_GET 5 2507 #define SADB_ACQUIRE 6 2508 #define SADB_REGISTER 7 2509 #define SADB_EXPIRE 8 2510 #define SADB_FLUSH 9 2511 #define SADB_DUMP 10 2512 #define SADB_X_PROMISC 11 2513 #define SADB_MAX 11 2515 struct sadb_msg { 2516 uint8_t sadb_msg_version; 2517 uint8_t sadb_msg_type; 2518 uint8_t sadb_msg_errno; 2519 uint8_t sadb_msg_satype; 2520 uint16_t sadb_msg_len; 2521 uint16_t sadb_msg_reserved; 2522 uint32_t sadb_msg_seq; 2523 uint32_t sadb_msg_pid; 2524 }; 2526 struct sadb_ext { 2527 uint16_t sadb_ext_len; 2528 uint16_t sadb_ext_type; 2529 }; 2530 struct sadb_sa { 2531 uint16_t sadb_sa_len; 2532 uint16_t sadb_sa_exttype; 2533 uint32_t sadb_sa_spi; 2534 uint8_t sadb_sa_replay; 2535 uint8_t sadb_sa_state; 2536 uint8_t sadb_sa_auth; 2537 uint8_t sadb_sa_encrypt; 2538 uint32_t sadb_sa_flags; 2539 }; 2541 struct sadb_lifetime { 2542 uint16_t sadb_lifetime_len; 2543 uint16_t sadb_lifetime_exttype; 2544 uint32_t sadb_lifetime_allocations; 2545 uint64_t sadb_lifetime_bytes; 2546 uint64_t sadb_lifetime_addtime; 2547 uint64_t sadb_lifetime_usetime; 2548 }; 2550 struct sadb_address { 2551 uint16_t sadb_address_len; 2552 uint16_t sadb_address_exttype; 2553 uint32_t sadb_address_reserved; 2554 }; 2556 struct sadb_key { 2557 uint16_t sadb_key_len; 2558 uint16_t sadb_key_exttype; 2559 uint16_t sadb_key_bits; 2560 uint16_t sadb_key_reserved; 2561 }; 2563 struct sadb_ident { 2564 uint16_t sadb_ident_len; 2565 uint16_t sadb_ident_exttype; 2566 uint16_t sadb_ident_type; 2567 uint16_t sadb_ident_reserved; 2568 }; 2569 struct sadb_sens { 2570 uint16_t sadb_sens_len; 2571 uint16_t sadb_sens_exttype; 2572 uint32_t sadb_sens_dpd; 2573 uint8_t sadb_sens_sens_level; 2574 uint8_t sadb_sens_sens_len; 2575 uint8_t sadb_sens_integ_level; 2576 uint8_t sadb_sens_integ_len; 2577 uint32_t sadb_sens_reserved; 2578 }; 2580 struct sadb_prop { 2581 uint16_t sadb_prop_len; 2582 uint16_t sadb_prop_exttype; 2583 uint8_t sadb_prop_replay; 2584 uint8_t sadb_prop_reserved[3]; 2585 }; 2587 struct sadb_comb { 2588 uint8_t sadb_comb_auth; 2589 uint8_t sadb_comb_encrypt; 2590 uint16_t sadb_comb_flags; 2591 uint16_t sadb_comb_auth_minbits; 2592 uint16_t sadb_comb_auth_maxbits; 2593 uint16_t sadb_comb_encrypt_minbits; 2594 uint16_t sadb_comb_encrypt_maxbits; 2595 uint32_t sadb_comb_reserved; 2596 uint32_t sadb_comb_soft_allocations; 2597 uint32_t sadb_comb_hard_allocations; 2598 uint64_t sadb_comb_soft_bytes; 2599 uint64_t sadb_comb_hard_bytes; 2600 uint64_t sadb_comb_soft_addtime; 2601 uint64_t sadb_comb_hard_addtime; 2602 uint64_t sadb_comb_soft_usetime; 2603 uint64_t sadb_comb_hard_usetime; 2604 }; 2606 struct sadb_alg { 2607 uint16_t sadb_alg_len; 2608 uint16_t sadb_alg_exttype; 2609 uint32_t sadb_alg_reserved; 2610 }; 2611 struct sadb_algd { 2612 uint8_t sadb_algd_id; 2613 uint8_t sadb_algd_ivlen; 2614 uint16_t sadb_algd_minbits; 2615 uint16_t sadb_algd_maxbits; 2616 uint16_t sadb_algd_reserved; 2617 }; 2619 struct sadb_spirange { 2620 uint16_t sadb_spirange_len; 2621 uint16_t sadb_spirange_exttype; 2622 uint32_t sadb_spirange_min; 2623 uint32_t sadb_spirange_max; 2624 uint32_t sadb_spirange_reserved; 2625 }; 2627 #define SADB_EXT_RESERVED 0 2628 #define SADB_EXT_SA 1 2629 #define SADB_EXT_LIFETIME_CURRENT 2 2630 #define SADB_EXT_LIFETIME_HARD 3 2631 #define SADB_EXT_LIFETIME_SOFT 4 2632 #define SADB_EXT_ADDRESS_SRC 5 2633 #define SADB_EXT_ADDRESS_DST 6 2634 #define SADB_EXT_ADDRESS_PROXY 7 2635 #define SADB_EXT_KEY_AUTH 8 2636 #define SADB_EXT_KEY_ENCRYPT 9 2637 #define SADB_EXT_IDENTITY_SRC 10 2638 #define SADB_EXT_IDENTITY_DST 11 2639 #define SADB_EXT_SENSITIVITY 12 2640 #define SADB_EXT_PROPOSAL 13 2641 #define SADB_EXT_SUPPORTED_AUTH 14 2642 #define SADB_EXT_SUPPORTED_ENCRYPT 14 2643 #define SADB_EXT_SPIRANGE 15 2644 #define SADB_EXT_MAX 15 2646 #define SADB_SATYPE_UNSPEC 0 2647 #define SADB_SATYPE_AH 1 2648 #define SADB_SATYPE_ESP 2 2649 #define SADB_SATYPE_RSVP 3 2650 #define SADB_SATYPE_OSPFV2 4 2651 #define SADB_SATYPE_RIPV2 5 2652 #define SADB_SATYPE_MIP 6 2653 #define SADB_SATYPE_MAX 6 2655 #define SADB_SASTATE_LARVAL 0 2656 #define SADB_SASTATE_MATURE 1 2657 #define SADB_SASTATE_DYING 2 2658 #define SADB_SASTATE_DEAD 3 2659 #define SADB_SASTATE_MAX 3 2661 #define SADB_SAFLAGS_PFS 1 2663 #define SADB_AALG_NONE 0 2664 #define SADB_AALG_MD5HMAC 1 2665 #define SADB_AALG_SHA1HMAC 2 2666 #define SADB_AALG_MAX 2 2668 #define SADB_EALG_NONE 0 2669 #define SADB_EALG_DESCBC 1 2670 #define SADB_EALG_3DESCBC 2 2671 #define SADB_EALG_MAX 2 2673 #define SADB_IDENTTYPE_RESERVED 0 2674 #define SADB_IDENTTYPE_PREFIX 1 2675 #define SADB_IDENTTYPE_FQDN 2 2676 #define SADB_IDENTTYPE_MBOX 3 2677 #define SADB_IDENTTYPE_MAX 3 2679 #define SADB_KEY_FLAGS_MAX 0 2680 #endif /* __PFKEY_V2_H */ 2682 Appendix C: Change Log 2684 The following changes were made between 02 and 03: 2686 * Formatting changes. 2688 * Many editorial cleanups, rewordings, clarifications. 2690 * Restrictions that prevent many strange and invalid cases. 2692 * Added definitions section. 2694 * Removed connnection identity type (this will reappear when it is 2695 more clear what it should look like). 2697 * Removed 5.2.1 (Why involve the kernel?). 2699 * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed 2700 from src, dst, and proxy and you had to anyway for sanity checking. 2702 * Removed REPLAY flag; sadb_sa_replay==0 means the same thing. 2704 * Renamed bit lengths to "bits" to avoid potential confusion. 2706 * Explicitly listed lengths for structures. 2708 * Reworked identities to always use a string format. 2710 * Removed requirements for support of shutdown() and SO_USELOOPBACK. 2712 * 64 bit alignment and 64 bit lengths instead of 32 bit. 2714 * time_t replaced with uint64 in lifetimes. 2716 * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER 2717 FILE). 2719 * Explicit error if PF_KEY_V2 not set at socket() call. 2721 * More text on SO_USELOOPBACK. 2723 * Made fields names and symbol names more consistent. 2725 * Explicit error if PF_KEY_V2 is not in sadb_msg_version field. 2727 * Bytes lifetime field now a 64-bit quantity. 2729 * Explicit len/exttype wording. 2731 * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.) 2733 * UI example (0x123 == 0x1230 or 0x0123). 2735 * Cleaned up and fixed some message behavior examples. 2737 The following changes were made between 01 and 02: 2739 * Mentioned that people COULD use these same messages between user 2740 progs. (Also mentioned why you still might want to use the actual 2741 socket.) 2743 * Various wordsmithing changes. 2745 * Took out netkey/ directory, and make net/pfkeyv2.h 2747 * Inserted PF_KEY_V2 proto argument per C. Metz. 2749 * Mentioned other socket calls and how their PF_KEY behavior is 2750 undefined. 2752 * SADB_EXPIRE now communicates both hard and soft lifetime expires. 2754 * New "association" extension, even smaller base header. 2756 * Lifetime extension improvements. 2758 * Length now first in extensions. 2760 * Errors can be sent from kernel to user, also. 2762 * Examples section inserted. 2764 * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup. 2766 * Key splitting now only across auth algorithm and encryption 2767 algorithm. Thanks for B. Sommerfeld for clues here. 2769 The following changes were made between 00 and 01: 2771 * Added this change log. 2773 * Simplified TLV header syntax. 2775 * Splitting of algorithms. This may be controversial, but it allows 2776 PF_KEY to be used for more than just IPsec. It also allows some 2777 kinds of policies to be placed in the KMd easier. 2779 * Added solid definitions and formats for certificate identities, 2780 multiple keys, etc. 2782 * Specified how keys are to be layed out (most-to-least bits). 2784 * Changed sequence number semantics to be like an RPC transaction ID 2785 number.