idnits 2.17.1 draft-mcdonald-pf-key-v2-02.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-23) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 459 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 71 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** The abstract seems to contain references ([Atk95c], [AMPMC96], [Atk95a], [Atk95b]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 70: '... - MUST...' RFC 2119 keyword, line 75: '... - SHOULD...' RFC 2119 keyword, line 82: '... - MAY...' RFC 2119 keyword, line 193: '...r-space policy MAY be implemented b...' RFC 2119 keyword, line 209: '... using PF_KEY MUST NOT depend on t...' (58 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 11 has weird spacing: '... Drafts are ...' == Line 15 has weird spacing: '... Drafts may b...' == Line 16 has weird spacing: '...iate to use ...' == Line 17 has weird spacing: '... Drafts as r...' == Line 25 has weird spacing: '...hat can be u...' == (454 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: An implementation MAY use the write() error number to indicate an error, but an application MUST not depend on this behavior. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: An extension field MUST not be repeated. If there is a situation where an extension MUST be repeated, it should be brought to the attention of the authors. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: SADB_SATYPE_MAX is never used with PF_KEY but is defined for completeness. It is always set to the highest valid numeric value. There MUST not be gaps in the numbering of security types; all numbers must be used sequentially. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (21 April 1997) is 9864 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '3' on line 617 -- Possible downref: Non-RFC (?) normative reference: ref. 'AMPMC96' ** Obsolete normative reference: RFC 1825 (ref. 'Atk95a') (Obsoleted by RFC 2401) ** Obsolete normative reference: RFC 1826 (ref. 'Atk95b') (Obsoleted by RFC 2402) ** Obsolete normative reference: RFC 1827 (ref. 'Atk95c') (Obsoleted by RFC 2406) -- Possible downref: Non-RFC (?) normative reference: ref. 'CG96' -- Possible downref: Non-RFC (?) normative reference: ref. 'DIA' -- Possible downref: Non-RFC (?) normative reference: ref. 'Hug96' -- Possible downref: Non-RFC (?) normative reference: ref. 'OG96' -- Possible downref: Non-RFC (?) normative reference: ref. 'Skl91' Summary: 17 errors (**), 0 flaws (~~), 10 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. L. McDonald 3 Internet Draft C. W. Metz 4 draft-mcdonald-pf-key-v2-02.txt B. G. Phan 5 21 April 1997 7 PF_KEY Key Management API, Version 2 9 STATUS OF THIS MEMO 11 This document is an Internet Draft. Internet Drafts are working 12 documents. 14 Internet Drafts are draft documents valid for a maximum of 6 15 months. Internet Drafts may be updated, replaced, or obsoleted by 16 other documents at any time. It is not appropriate to use Internet 17 Drafts as reference material or to cite them other than as "work in 18 progress". 20 A future version of this draft will be submitted to the RFC Editor 21 for publication as an Informational document. 23 ABSTRACT 25 A generic key management API that can be used not only for IP 26 Security [Atk95a] [Atk95b] [Atk95c] but also for other network 27 security services is presented in this document. Version 1 of this 28 API was implemented inside 4.4-Lite BSD as part of the U. S. Naval 29 Research Laboratory's freely distributable and usable IPv6 and IPsec 30 implementation[AMPMC96]. It is documented here for the benefit of 31 others who might also adopt and use the API, thus providing increased 32 portability of key management applications (e.g. an ISAKMP daemon, a 33 Photuris daemon or SKIP certificate discovery protocol daemon). 35 1. INTRODUCTION 37 PF_KEY is a new socket protocol family used by trusted privileged 38 key management applications to communicate with an operating system's 39 key management internals (referred to here as the "Key Engine" or the 40 SADB). The Key Engine and its structures incorporate the required 41 security attributes for a session and are instances of the "Security 42 Association" concept described in [Atk95a]. The names, PF_KEY and 43 Key Engine, thus refer to more than cryptographic keys and are 44 retained for consistency with the traditional phrase, "Key 45 Management". 47 PF_KEY is derived in part from the BSD routing socket, PF_ROUTE. 48 [Skl91] This document describes Version 2 of PF_KEY. Version 1 was 49 implemented in the first three alpha test versions of the NRL 50 IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco 51 ISAKMP/Oakley key management daemon. Version 2 extends and refines 52 this interface. Theoretically, the messages defined in this document 53 could be used in a non-socket context (e.g. between two communicating 54 user-level processes), but this document will not discuss in detail 55 such possibilities. 57 Security policy is deliberately omitted from this interface. 58 PF_KEY is not a mechanism for tuning systemwide security policy, nor 59 is it intended to enforce any sort of key management policy. The 60 developers of PF_KEY believed that it was important to separate 61 security mechanisms (such as PF_KEY) from security policies. This 62 permits a single mechanism to more easily support multiple policies. 64 1.1 TERMINOLOGY 66 Even though this document is not intended to be a standard, the 67 words that are used to define the significance of particular features 68 of this proposal are usually capitalized. These words are: 70 - MUST 72 This word or the adjective "REQUIRED" means that the item is an 73 absolute requirement of the specification. 75 - SHOULD 77 This word or the adjective "RECOMMENDED" means that there might 78 exist valid reasons in particular circumstances to ignore this item, 79 but the full implications should be understood and the case carefully 80 weighed before taking a different course. 82 - MAY 84 This word or the adjective "OPTIONAL" means that this item is truly 85 optional. One vendor might choose to include the item because a 86 particular marketplace requires it or because it enhances the 87 product, for example; another vendor may omit the same item. 89 1.2 CONCEPTUAL MODEL 91 This section describes the conceptual model of an operating system 92 that implements the PF_KEY key management application programming 93 interface. This section is intended to provide background material 94 useful to understand the rest of this document. Presentation of this 95 conceptual model does not constrain a PF_KEY implementation to 96 strictly adhere to the conceptual components discussed in this 97 subsection. 99 Key management is most commonly implemented in whole or part at the 100 application-layer. For example, the Photuris, ISAKMP, and Oakley 101 proposals for IPsec key management are all application-layer 102 protocols. Even parts of the SKIP IP-layer keying proposal can be 103 implemented at the application layer. Figure 1 shows the 104 relationship between a Key Management daemon and PF_KEY, which it 105 uses to communicate with the Key Engine, and PF_INET (or PF_INET6 in 106 the case of IPv6), which it uses to communicate via the network with 107 a remote key management entity. 109 The "Key Engine" or "Security Association Database (SADB)" is a 110 logical entity in the kernel that stores, updates, and deletes 111 Security Association data for various security protocols. There are 112 logical interfaces within the kernel (e.g. getassocbyspi(), 113 getassocbysocket()) that security protocols inside the kernel (e.g. 114 IP Security, aka IPsec) use to request and obtain Security 115 Associations. 117 In the case of IPsec, if by policy a particular outbound packet 118 needs processing, then the IPsec implementation requests an 119 appropriate Security Association from the Key Engine via the kernel- 120 internal interface. If the Key Engine has an appropriate SA, it 121 allocates the SA to this session (marking it as used) and returns the 122 SA to the IPsec implementation for use. If the Key Engine has no 123 such SA but a key management application has previously indicated 124 (via a PF_KEY SADB_REGISTER message) that it can obtain such SAs, 125 then the Key Engine requests that such an SA be created (via a PF_KEY 126 SADB_ACQUIRE message). When the key management daemon creates a new 127 SA, it places it into the Key Engine for future use. 129 +---------------+ 130 |Key Mgmt Daemon| 131 +---------------+ 132 | | 133 | | 134 | | Applications 135 ======[PF_KEY]====[PF_INET]========================== 136 | | OS Kernel 138 +------------+ +-----------------+ 139 | Key Engine | | TCP/IP, | 140 | or SADB |---| including IPsec | 141 +------------+ | | 142 +-----------------+ 143 | 144 +-----------+ 145 | Network | 146 | Interface | 147 +-----------+ 149 Figure 1: Relationship of Key Mgmt to PF_KEY 151 For performance reasons, some security protocols (e.g. IP Security) 152 are usually implemented inside the operating system kernel. Other 153 security protocols (e.g. OSPFv2 Cryptographic Authentication) are 154 implemented in trusted privileged applications outside the kernel. 155 Figure 2 shows a trusted, privileged routing daemon using PF_INET to 156 communicate routing information with a remote routing daemon and 157 using PF_KEY to request, obtain, and delete Security Associations 158 used with a routing protocol. 160 +---------------+ 161 |Routing Daemon| 162 +---------------+ 163 | | 164 | | 165 | | Applications 166 ======[PF_KEY]====[PF_INET]========================== 167 | | OS Kernel 168 +------------+ +---------+ 169 | Key Engine | | TCP/IP | 170 | or SADB |---| | 171 +------------+ +---------+ 172 | 173 +-----------+ 174 | Network | 175 | Interface | 176 +-----------+ 178 Figure 2: Relationship of Trusted Application to PF_KEY 180 When a trusted privileged application is using the Key Engine but 181 implements the security protocol within itself, then operation varies 182 slightly. In this case, the application needing an SA sends a PF_KEY 183 SADB_ACQUIRE message down to the Key Engine, which then either 184 returns an error or sends a similar SADB_ACQUIRE message up to one or 185 more key management applications capable of creating such SAs. As 186 before, the key management daemon stores the SA into the Key Engine. 187 Then, the trusted privileged application uses a SADB_GET message to 188 obtain the SA from the Key Engine. 190 In some implementations, policy may be implemented in user-space, 191 even though the actually cryptographic processing takes place in the 192 kernel. Such policy communication between the kernel mechanisms and 193 the user-space policy MAY be implemented by PF_KEY extensions, or 194 other such mechanism. This document will not specify such 195 extensions. 197 Untrusted clients, for example a user's web browser or telnet 198 client, do not need to use PF_KEY. Mechanisms not specified here are 199 used by such untrusted client applications to request security 200 services (e.g. IPsec) from an operating system. For security 201 reasons, only trusted, privileged applications are permitted to open 202 a PF_KEY socket. 204 1.3 PF_KEY SOCKET DEFINITION 206 The PF_KEY protocol family (PF_KEY) symbol is defined in 207 in the same manner that other protocol families are 208 defined. PF_KEY does not use any socket addresses. Applications 209 using PF_KEY MUST NOT depend on the availability of a symbol named 210 AF_KEY, but kernel implementations are encouraged to define that 211 symbol for completeness. 213 The key socket is created as follows: 215 #include 217 int s; 218 s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2) 220 The PF_KEY domain currently supports only the SOCK_RAW socket type. 221 The protocol field MUST be set to PF_KEY_V2. Only a trusted, 222 privileged process can create a PF_KEY socket. On conventional UNIX 223 systems, a privileged process is a process with an effective userid 224 of zero. On non-MLS proprietary operating systems, the notion of a 225 "privileged process" is implementation-defined. On Compartmented 226 Mode Workstations (CMWs) or other systems that claim to provide 227 Multi-Level Security (MLS), a process MUST have the "key management 228 privilege" in order to open a PF_KEY socket[DIA]. MLS systems that 229 don't currently have such a specific privilege MUST add that special 230 privilege and enforce it with PF_KEY in order to comply and conform 231 with this specification. Some systems, most notably some popular 232 personal computers, do not have the concept of a privileged user. 233 These systems SHOULD take steps to restrict the programs allowed to 234 access the PF_KEY API. 236 1.4 OVERVIEW OF PF_KEY MESSAGING BEHAVIOR 238 A process interacts with the key engine by sending and receiving 239 messages using the PF_KEY socket. Security association information 240 can be inserted into and retrieved from the kernel's security 241 association table using a set of predefined messages. In the normal 242 case, all messages sent to the kernel are returned to all open PF_KEY 243 sockets, including the sender. A process can disable this looping 244 back of messages it generates by disabling the SO_USELOOPBACK option 245 using the setsockopt(2) call. A PF_KEY socket listener, which by 246 default receives all replies may disable message reception by 247 terminating socket input with the shutdown(2) call. PF_KEY message 248 delivery is not guaranteed, especially in cases where kernel or 249 socket buffers are exhausted and messages are dropped. 251 Some messages are generated by the operating system to indicate 252 that actions need to be taken, and are not necessarily in response to 253 any message sent down by the user. Such messages are not received by 254 all PF_KEY sockets, but by sockets which have indicated that kernel- 255 originated messages are to be received. These messages are special 256 because of the expected frequency at which they will occur. Also, an 257 implementation may further wish to restrict return message from the 258 kernel, in cases where not all PF_KEY sockets are in the same trust 259 domain. 261 Many of the normal BSD socket calls have undefined behavior on 262 PF_KEY sockets. These include: bind(), connect(), socketpair(), 263 accept(), getpeername(), getsockname(), ioctl(), and listen(). 265 1.5 COMMON PF_KEY OPERATIONS 267 There are two basic ways to add a new Security Association into the 268 kernel. The simplest is to send a single SADB_ADD message, 269 containing all of the SA information, from the application into the 270 kernel's Key Engine. This approach works particularly well with 271 manual key management. 273 The second approach to add a new Security Association into the 274 kernel is for the application to first request an SPI value from the 275 kernel using the SADB_GETSPI message and then send a SADB_UPDATE 276 message with the complete Security Association data. This second 277 approach works well with key management daemons when the SPI values 278 need to be known before the entire Security Association data is known 279 (e.g. so the SPI value can be indicated to the remote end of the key 280 management session). 282 An individual Security Association can be deleted using the 283 SADB_DELETE message. Categories of SAs or the entire kernel SA table 284 can be deleted using the SADB_FLUSH message. 286 The SADB_GET message is used by a trusted application-layer process 287 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 288 SA) from the kernel's Key Engine. 290 The kernel or an application-layer can use the SADB_ACQUIRE message 291 to request that a Security Association be created by some 292 application-layer key management process that has registered with the 293 kernel via a SADB_REGISTER message. This ACQUIRE message will have a 294 sequence number associated with it. This sequence number MUST be 295 used by followup SADB_GETSPI and SADB_UPDATE messages, in order to 296 keep track of which request gets its keying material. The sequence 297 number (described below) is analogous to a transaction ID in a remote 298 procedure call. 300 The SADB_EXPIRE message is sent from the kernel to key management 301 applications when the "soft lifetime" or "hard lifetime" of a 302 Security Association has expired. Key management applications should 303 use receipt of a soft lifetime SADB_EXPIRE message as a hint to 304 negotiate a replacement SA so the replacement SA will be ready and in 305 the kernel before it is needed. 307 A SADB_DUMP message is also defined, but this is primarily intended 308 for PF_KEY implementor debugging and is not used in ordinary 309 operation of PF_KEY. 311 1.6 DIFFERENCES BETWEEN PF_KEY AND THE PF_ROUTE ROUTING SOCKET 313 The following bullets are points of difference between the routing 314 socket and PF_KEY. Programmers who are used to the routing socket 315 semantics will find some subtle differences in PF_KEY. 317 * The write() call doesn't return the PF_KEY error number, only the 318 return message has the PF_KEY error number in cases of malformed 319 fields. This means that if SO_USELOOPBACK is disabled, error checking 320 is hard. 322 An implementation MAY use the write() error number to indicate an error, 323 but an application MUST not depend on this behavior. 325 * The entire message isn't always reflected in the reply. An SADB_ADD is 326 a good example of this. 328 * The PID is not set by the kernel. The process that originates the 329 message MUST set the sadb_msg_pid to its own PID. If the kernel 330 originates a message, it MUST set the sadb_msg_pid to 0. 332 2. PF_KEY MESSAGE FORMAT 334 PF_KEY messages consist of a base header followed by additional 335 data fields, some of which may be optional. The format of the 336 additional data is dependent on the type of message. 338 PF_KEY messages currently do not mandate any specific ordering for 339 non-network multi-octet fields. Fields that may go across the wire 340 (e.g. SPI) MUST be in network byte order. 342 2.1 BASE MESSAGE HEADER FORMAT 344 PF_KEY messages consist of the base message header followed by 345 security association specific data whose types and lengths are 346 specified by a generic type-length encoding. 348 This base header is shown below, using POSIX types. The fields are 349 arranged primarily for alignment, and where possible, for reasons of 350 clarity. 352 struct sadb_msg { 353 uint8_t sadb_msg_version; 354 uint8_t sadb_msg_type; 355 uint8_t sadb_msg_errno; 356 uint8_t sadb_msg_sa_type; 357 uint16_t sadb_msg_len; 358 uint16_t sadb_msg_reserved; 359 uint32_t sadb_msg_seq; 360 uint32_t sadb_msg_pid; 361 }; 363 sadb_version The version field of this PF_KEY message. This MUST be 364 set to PF_KEY_V2. 366 sadb_msg_type Identifies the type of message. The valid message types 367 are described later in this document. 369 sadb_msg_errno Should be set to zero by the sender. The replier stores 370 the error code in this field if an error has occured. 371 This includes the case where the replier is in user 372 space. (E.g. User-space negotiation fails, an errno can 373 be returned.) 375 sadb_msg_sa_type 376 Indicates the type of security association(s) (e.g. AH, 377 ESP, OSPF, etc). Valid Security Association types are 378 declared in the file . The current set of 379 Security Association types are enumerated later in this 380 document. 382 sadb_msg_len Contains the total length, in 32-bit words, of all data 383 in the PF_KEY message including the base header length 384 and additional data after the base header, if any. This 385 length includes any padding or extra space that might 386 exist. Unless otherwise stated, all other length fields 387 are also measured in 32-bit words. 389 If this field mismatches the actual length of data, 390 EMSGSIZE MUST be returned. 392 sadb_msg_reserved 393 Reserved value. It MUST be zeroed by the sender, and it 394 MUST be ignored by the receiver. All fields labelled 395 reserved later in the document have the same semantics 396 as this field. 398 sadb_msg_seq Contains the sequence number of this message. This 399 field, along with sadb_msg_pid, MUST be used to uniquely 400 identify requests to a process. The sender is 401 responsible for filling in this field. This 402 resposibility also includes matching the sadb_msg_seq of 403 a request (e.g. SADB_ACQUIRE). 405 This field is analogous to a transaction ID in a remote 406 procedure call implementation. 408 sadb_msg_pid Identifies the process which originated this message, or 409 which process a message is bound for. For example: If 410 process id 2112 sends a SADB_UPDATE message to the 411 kernel, the message to the kernel MUST set its process 412 id to 2112, and the SADB_UPDATE reply from the kernel 413 will fill in this fields with 2112. This field, along 414 with sadb_msg_seq, can be used to uniquely identify 415 requests to a process. 417 It is currently believed that a 32-bit quantity will 418 hold an operating system's process ID space. If this 419 assumption is not true, then sadb_msg_pid will have to 420 be revisited. 422 2.3 ADDITIONAL MESSAGE FIELDS 424 The additional data following the base header consists of various 425 type-length-values fields. The first 32-bits are of a constant form: 427 struct sadb_hdr { 428 uint16_t sadb_hdr_len; /* In 32-bit words, inclusive */ 429 uint16_t sadb_hdr_hdrtype; /* 0 is reserved */ 430 }; 432 Types of extensions headers include: Association, Lifetime(s), 433 Address, Key, Identity, Sensitivity, Proposal, and Supported. There 434 MUST be only one instance of a extension type in a message. (e.g. 435 Base, Key, Lifetime, Key is forbidden), an EINVAL will be returned if 436 there are duplicate extensions within a message. Implementations MAY 437 enforce ordering of extensions in the order presented in the 438 EXTENSION HEADER VALUES section. 440 All extensions documented in this section MUST be implemented by a 441 PF_KEY implementation. 443 2.3.1 ASSOCIATION EXTENSION 445 The Association extension specifies data specific to a single 446 security association. The only times this extension is not present 447 is when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being 448 passed. 450 struct sadb_sa { 451 uint16_t sadb_sa_len; 452 uint16_t sadb_sa_hdrtype; /* ASSOCIATION */ 453 uint32_t sadb_sa_spi; 454 uint8_t sadb_sa_replay_window_len; 455 uint8_t sadb_sa_state; 456 uint8_t sadb_sa_encrypt; 457 uint8_t sadb_sa_auth; 458 uint32_t sadb_sa_flags; 459 }; 461 The sadb_sa_spi field contains the Security Parameters Index value 462 for the Security Association. Although this is a 32-bit field, some 463 types of Security Association might have an SPI or key identifier 464 that is less than 32-bits long. In this case, the smaller value shall 465 be stored in the least significant bits of this field and the 466 unneeded bits shall be zero. This field MUST be in network byte 467 order. 469 The sadb_sa_replay_window_len specifies the size of the replay 470 window, if not zero. If zero, then no replay window is in use. 472 The sadb_sa_state field is an integer field containing the state of 473 the Security Association. This field should be set to zero by the 474 sending process and is set to the state of the Security Association 475 when the message is received. The current set of States are 476 enumerated later in this document. 478 The sadb_sa_encrypt and sadb_sa_auth fields identify the encryption 479 and authentication algorithm(s) used for this security association. 480 This can identify that no encryption or authentication is used for 481 this association. See section 3.4 for values that can be placed in 482 this field. The kernel MUST check sanity where relevant. For 483 example IPsec AH with no authentication algorithm is probably an 484 error. 486 The sadb_sa_flags field contains a bitmap of options defined for the 487 security assocation (e.g. replay protection, PFS, EXPIRED, etc.). 488 These flags are enumerated later in this document. 490 2.3.2 LIFETIME EXTENSION 492 The Lifetime extension specifies one or more lifetime variants for 493 this security association. If no Lifetime extension is present the 494 association has an infinite lifetime. An association SHOULD have a 495 lifetime of some sort associated with it. Lifetime variants come in 496 three varieties, HARD - indicating the hard-limit expiration, SOFT - 497 indicating the soft-limit expiration, and CURRENT - indicating the 498 current state of limits in a given security association. The 499 Lifetime extension looks like: 501 struct sadb_lifetime { 502 uint16_t sadb_lifetime_len; 503 uint16_t sadb_lifetime_hdrtype; /* LIFETIME */ 504 uint8_t sadb_lifetime_which; /* Bitmask */ 505 uint8_t sadb_lifetime_reserved[3]; /* Padding */ 506 }; 508 The sadb_lifetime_which field contains a bitmask indicating what 509 lifetimes; hard, soft, and current; follow. A lifetime value is 510 encoded as follows: 512 struct sadb_lifetime_val { 513 /* The following corresponds to sadb_lifetime_which */ 514 uint8_t sadb_lifetime_val_which; 515 uint8_t sadb_lifetime_val_reserved; 516 uint16_t sadb_lifetime_val_allocations; 517 uint32_t sadb_lifetime_val_bytes; 518 time_t sadb_lifetime_val_absolute; 519 time_t sadb_lifetime_val_updatetime; 520 time_t sadb_lifetime_val_usetime; 521 }; 523 The sadb_lifetime_val_bytes field contains how many bytes this 524 security association can consume before it expires for HARD and 525 SOFT. In the case of CURRENT, it indicates how many bytes have been 526 consumed. The sadb_lifetime_val_allocations field contains how many 527 different connections, endpoints, or flows an association can be 528 allocated towards, or in the case of CURRENT, how many times the 529 association has been allocated. (The concept of a connection, flow, 530 or endpoint is somewhat system-specific.) There are three time 531 fields, one indicating absolute expiration time, one indicating time 532 after SA update, and another inidicating time after first use of 533 this SA. The update time and use time will indicate remaining time 534 in the case of CURRENT, and the assigned limits in the case of HARD 535 or SOFT. 537 The semantics of lifetimes are inclusive-OR, first-to-expire 538 semantics. This means if values for bytes and time, or multiple 539 times, are passed in, the first of these values to be reached will 540 cause a lifetime expiration. 542 2.3.3 ADDRESS EXTENSION 544 The Address extension specifies one or more addresses that are 545 associated with a security association. An Address extension MUST 546 be present when an Association address is present, and MUST specify 547 at least the source and destination addresses. (The source address 548 can be INADDR_ANY or it's IPv6 counterpart.) The format of an 549 Address extension is: 551 struct sadb_address { 552 uint16_t sadb_address_len; 553 uint16_t sadb_address_hdrtype; /* ADDRESS */ 554 uint8_t sadb_address_which; /* Bitmask */ 555 uint8_t sadb_address_reserved[3]; /* Padding */ 556 /* Followed by one or more sockaddr structures. */ 557 }; 559 The sadb_address_which field contains a bitmask indicating what 560 addresses; source, destination, inner-source, inner-destination, and 561 proxy; follow. For each bit set in the sadb_address_which field, a 562 struct sockaddr follows, in the order specified above. The sockaddr 563 structure SHOULD conform to the sockaddr structure of the system 564 implementing PF_KEY. (E.g. If the system has an sa_len field, so 565 SHOULD the sockaddrs in the message. If the system has NO sa_len 566 field, the sockaddrs SHOULD not have an sa_len field.) All non- 567 address information in the sockaddrs MUST be zeroed out. 569 2.3.4 KEY EXTENSION 571 The Key extension specifies one or more keys that are associated 572 with a security association. A Key extension will not always be 573 present with messages, because of security risks. The format of a 574 Key extension is: 576 struct sadb_keyblk { 577 uint16_t sadb_keyblk_len; 578 uint16_t sadb_keyblk_hdrtype; /* KEY */ 579 uint8_t sadb_keyblk_which; /* Bitmask, which keys? */ 580 uint8_t sadb_keyblk_reserved[3]; /* Padding */ 581 /* Followed by sadb_key */ 582 }; 584 The Key extension is followed by the appropriate number of keys, 585 which contain information to correspond it to which keys are in the 586 keyblock. These keys are encoded as follows: 588 struct sadb_key { 589 uint16_t sadb_key_len; /* Length of key in bits */ 590 uint8_t sadb_key_which; /* Corresponds to keyblk_which */ 591 uint8_t sadb_key_type; /* 3DES, DES, HMAC-MD5, etc. */ 592 /* Actual key follows */ 593 }; 595 The length of individual keys is in bits, and is interpreted by the 596 algorithm. Each key is padded to a 32-bit boundary. The key bits 597 are arranged most-sigificant to least significant. For example, a 598 22-bit key would take up three octets, with the least significant 599 two bits not containing key material. An additional octet would be 600 used for padding to a 32-bit boundary. 602 The sadb_key_which field indicates what sort of key this is, and is 603 one bit out of the list of bits in sadb_keyblk_which. These values 604 are detailed later. 606 2.3.5 IDENTITY EXTENSION 608 The Identity extension contains endpoint identities. If this 609 extension is not present, key management MUST assume that the 610 addresses in the Address extension are the only identities for this 611 Security Association. The Identity extension looks like: 613 struct sadb_id { 614 uint16_t sadb_id_len; 615 uint16_t sadb_id_hdrtype; /* IDENTITY */ 616 uint8_t sadb_id_which; /* bitmask */ 617 uint8_t sadb_id_reserved[3]; /* Padding */ 618 /* Followed by one or more sadb_certids */ 619 }; 621 The sadb_id_which field is a bitmask, indicating if source or 622 destination certificate identities are present. Each identity is a 623 32-bit aligned quantity, specified as: 625 struct sadb_certid { 626 uint16_t sadb_certid_len; /* In 32-bit words */ 627 uint16_t sadb_certid_type; 628 /* Cert id. follows */ 629 }; 631 Following each sadb_certid is 32-bit aligned data. The type of data 632 can either be nothing (if the specified identity is the address), a 633 null-terminated C string (for fully-qualified domain names, or 634 mailbox identities), and address/mask pair (for address ranges), or 635 a port-pair/protocol tuple, used in concert with the addresses. See 636 the ILLUSTRATION OF MESSAGE LAYOUT section for details. 638 2.3.6 SENSITIVITY EXTENSION 640 The Sensitiviy extension contains security labelling information 641 for a security association. If this extension is not present, no 642 sensitivity-related data can be obtained from this security 643 association. If this extension is present, then the need for 644 explicit security labelling on the packet is obviated. 646 struct sadb_sens { 647 uint16_t sadb_sens_len; 648 uint16_t sadb_sens_hdrtype; /* SENSITIVITY */ 649 uint32_t sadb_sens_dpd; 650 uint8_t sadb_sens_sens_level; 651 uint8_t sadb_sens_sens_bitmap_len; /* 32-bit words */ 652 uint8_t sadb_sens_integ_level; 653 uint8_t sadb_sens_integ_bitmap_len; /* 32-bit words */ 654 /* 655 * followed by two uint32_t arrays 656 * uint32_t sadb_sens_bitmap[sens_bitmap_len]; 657 * uint32_t integ_bitmap[integ_bitmap_len]; 658 */ 659 }; 661 The lengths of the bitmaps are in bytes. Following this field are 662 the bitmaps. Only at the end of the second bitmap does padding to 663 32-bits occur. The sadb_sens_dpd describes the protection domain, 664 which allows interpretation of the levels and compartment bitmaps. 666 2.3.7 PROPOSAL EXTENSION 668 The Proposal extension contains a "proposed situation" of 669 algorithm preferences. It looks like: 671 struct sadb_prop { 672 uint16_t sadb_prop_len; 673 uint16_t sadb_prop_hdrtype; /* PROPOSAL */ 674 uint8_t sadb_prop_num; 675 uint8_t sadb_prop_replay; /* Replay win. size. */ 676 uint16_t sadb_prop_reserved; 677 }; 679 Following the header are a list of combinations in preferential 680 order. A combination contains an algorithm, pair, 681 and some other parameters. These combinations look like: 683 struct sadb_comb { 684 uint8_t sadb_comb_auth; 685 uint8_t sadb_comb_encr; 686 uint16_t sadb_comb_flags; 687 uint16_t sadb_comb_auth_keylen_min; 688 uint16_t sadb_comb_auth_keylen_max; 689 uint16_t sadb_comb_encr_keylen_min; 690 uint16_t sadb_comb_encr_keylen_max; 691 }; 693 Each combination has an authentication and encryption algorithm, 694 which may be 0, indicating none. A combination's flags are the same 695 as the flags in the Association extension. The minimum and maximum 696 keylengths are derived from possible a priori policy decisions, 697 along with basic properties of the algorithm. 699 2.3.8 SUPPORTED ALGORITHMS EXTENSION 701 The Supported Algorithms extension contains a list of all 702 algorithms supported by the system. This is useful for key 703 management, as it now knows what algorithms it can negotiate. Its 704 format is: 706 struct sadb_alg { 707 uint16_t sadb_alg_len; 708 uint16_t sadb_alg_hdrtype; /* SUPPORTED */ 709 uint8_t sadb_alg_num_auth; /* # of auth algs */ 710 uint8_t sadb_alg_num_encrypt; /* # of encrypt algs */ 711 uint16_t sadb_alg_reserved; 712 /* Followed by one or more alg_desc */ 713 }; 715 It is followed by one or more algorithm descriptors. An algorithm 716 descriptor looks like: 718 struct sadb_algd { 719 uint8_t sadb_algd_type; /* Algorithm type. */ 720 uint8_t sadb_algd_ivlen; /* IV len, in bits */ 721 uint16_t sadb_algd_minlen; /* Min. key len (in bits) */ 722 uint16_t sadb_algd_maxlen; /* Max. key length */ 723 uint16_t sadb_algd_reserved; 724 }; 726 32-bit alignment is guaranteed by the fields automatically. The 727 initialization vector length is 0 if not needed, and 0 if needed. 728 The minlen and maxlen are key lengths in bits. 730 2.3.9 SPI RANGE EXTENSION 732 One PF_KEY message, SADB_GETSPI, might need a range of acceptable 733 SPI values. This extension performs such a function. 735 struct sadb_spirange { 736 uint16_t sadb_spirange_len; 737 uint16_t sadb_spirange_hdrtype; /* SPI_RANGE */ 738 uint32_t sadb_spirange_low; 739 uint32_t sadb_spirange_hi; 740 } 742 2.4 ILLUSTRATION OF MESSAGE LAYOUT 744 The following shows how the octets are layed out in a PF_KEY message. 745 Optional fields are indicated as such. 747 The base header is as follows: 749 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 750 +---------------+---------------+---------------+---------------+ 751 | sadb_version | sadb_msg_type | sadb_msg_errno| sadb_sa_type | 752 +---------------+---------------+---------------+---------------+ 753 | sadb_msg_len | sadb_msg_reserved | 754 +---------------+---------------+---------------+---------------+ 755 | sadb_msg_seq | 756 +---------------+---------------+---------------+---------------+ 757 | sadb_msg_pid | 758 +---------------+---------------+---------------+---------------+ 760 The base header may be followed by one or more of the following 761 extension fields, depending on the values of various base header 762 fields. The following fields are ordered such that if they appear, 763 they SHOULD appear in the order presented below. 765 An extension field MUST not be repeated. If there is a situation 766 where an extension MUST be repeated, it should be brought to the 767 attention of the authors. 769 The Association extension 771 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 772 +---------------+---------------+---------------+---------------+ 773 | sadb_sa_len | sadb_sa_hdrtype | 774 +---------------+---------------+---------------+---------------+ 775 | sadb_sa_spi | 776 +---------------+---------------+---------------+---------------+ 777 | ...replay... | sadb_sa_state |sadb_sa_encrypt| sadb_sa_auth | 778 +---------------+---------------+---------------+---------------+ 779 | sadb_sa_flags | 780 +---------------+---------------+---------------+---------------+ 782 The Lifetime extension 784 +---------------+---------------+---------------+---------------+ 785 | sadb_lifetime_len | sadb_lifetime_hdrtype | 786 +---------------+---------------+---------------+---------------+ 787 | ..._which | sadb_lifetime_reserved | 788 +---------------+---------------+---------------+---------------+ 790 A lifetime value 792 +---------------+---------------+---------------+---------------+ 793 | ..._val_which | ..._reserved | sadb_lifetime_val_allocations | 794 +---------------+---------------+---------------+---------------+ 795 | sadb_lifetime_val_bytes | 796 +---------------+---------------+---------------+---------------+ 797 > sadb_lifetime_val_absolute < 798 +---------------+---------------+---------------+---------------+ 799 > sadb_lifetime_val_updatetime < 800 +---------------+---------------+---------------+---------------+ 801 > sadb_lifetime_val_usetime < 802 +---------------+---------------+---------------+---------------+ 804 The Address extension 806 +---------------+---------------+---------------+---------------+ 807 | sadb_address_len | sadb_address_hdrtype | 808 +---------------+---------------+---------------+---------------+ 809 |sadb_addr_which| sadb_addr_reserved | 810 +---------------+---------------+---------------+---------------+ 811 > 32-bit aligned struct sockaddr(s) < 812 +---------------+---------------+---------------+---------------+ 814 The Key extension 816 +---------------+---------------+---------------+---------------+ 817 | sadb_keyblk_len | sadb_keyblk_hdrtype | 818 +---------------+---------------+---------------+---------------+ 819 |...keyblk_which| sadb_keyblk_reserved | 820 +---------------+---------------+---------------+---------------+ 821 > One or more actual keys, encoded as follows... < 822 +---------------+---------------+---------------+---------------+ 824 An actual key 826 +---------------+---------------+---------------+---------------+ 827 | sadb_key_len | sadb_key_which| sadb_key_type | 828 +---------------+---------------+---------------+---------------+ 829 > A key, padded to 32-bits, most sigificant bits to least. < 830 +---------------+---------------+---------------+---------------+ 832 The Identity extension 834 +---------------+---------------+---------------+---------------+ 835 | sadb_id_len | sadb_id_hdrtype | 836 +---------------+---------------+---------------+---------------+ 837 | sadb_id_which | sadb_id_reserved | 838 +---------------+---------------+---------------+---------------+ 839 > One or more certificate identities of the following forms < 840 +---------------+---------------+---------------+---------------+ 842 IPv6 address or IPv4 address should look in the previous Address 843 extension for actual values. 845 +---------------+---------------+---------------+---------------+ 846 | sadb_certid_len | sadb_certid_type | 847 +---------------+---------------+---------------+---------------+ 848 > Certificate data < 849 +---------------+---------------+---------------+---------------+ 851 NOTE that the Certificate data gets filled with useful fields for 852 most identity types. 854 An IPv6 or IPv4 address prefix 856 +---------------+---------------+---------------+---------------+ 857 | sadb_certid_len | sadb_certid_type | 858 +---------------+---------------+---------------+---------------+ 859 |pref_len (bits)| reserved | 860 +---------------+---------------+---------------+---------------+ 861 > 16-bytes of IPv6 or 4-bytes of IPv4 address prefix < 862 +---------------+---------------+---------------+---------------+ 864 A Fully-qualified domain name, or a mailbox ID. 866 +---------------+---------------+---------------+---------------+ 867 | sadb_certid_len | sadb_certid_type | 868 +---------------+---------------+---------------+---------------+ 869 > A null-terminated C-string which MUST be padded out for 32- > 870 < bit alignment < 871 +---------------+---------------+---------------+---------------+ 873 A connection ID, which uses address plus port/protocol information. 875 +---------------+---------------+---------------+---------------+ 876 | sadb_certid_len | sadb_certid_type | 877 +---------------+---------------+---------------+---------------+ 878 | protocol_id | reserved | 879 +---------------+---------------+---------------+---------------+ 880 | source_port | destination_port | 881 +---------------+---------------+---------------+---------------+ 883 The Sensitivity extension 885 +---------------+---------------+---------------+---------------+ 886 | sadb_sens_len | sadb_sens_hdrtype | 887 +---------------+---------------+---------------+---------------+ 888 | sadb_sens_dpd | 889 +---------------+---------------+---------------+---------------+ 890 | ...sens_level | ...bitmap_len |..._integ_level| ...bitmap_len | 891 +---------------+---------------+---------------+---------------+ 892 > The sensitivity bitmap, followed immediately by the integrity < 893 < bitmap, each is an array of uint32_t. > 894 +---------------+---------------+---------------+---------------+ 896 The Proposal extension 898 +---------------+---------------+---------------+---------------+ 899 | sadb_prop_len | sadb_prop_hdrtype | 900 +---------------+---------------+---------------+---------------+ 901 | sadb_prop_num | ..prop_replay | sadb_prop_reserved | 902 +---------------+---------------+---------------+---------------+ 903 > One or more combinations, specified as follows... < 904 +---------------+---------------+---------------+---------------+ 906 Combination 907 +---------------+---------------+---------------+---------------+ 908 |sadb_comb_auth |sadb_comb_encr | sadb_comb_flags | 909 +---------------+---------------+---------------+---------------+ 910 | sadb_comb_auth_keylen_min | sadb_comb_auth_keylen_max | 911 +---------------+---------------+---------------+---------------+ 912 | sadb_comb_encr_keylen_min | sadb_comb_encr_keylen_max | 913 +---------------+---------------+---------------+---------------+ 915 The Supported Algorithms extension 917 +---------------+---------------+---------------+---------------+ 918 | sadb_alg_len | sadb_alg_hdrtype | 919 +---------------+---------------+---------------+---------------+ 920 | ...num_auth | ...num_encr. | sadb_alg_reserved | 921 +---------------+---------------+---------------+---------------+ 923 Followed by one or more Algorithm Descriptors 925 +---------------+---------------+---------------+---------------+ 926 |sadb_algd_type |sadb_algd_ivlen| sadb_algd_minlen | 927 +---------------+---------------+---------------+---------------+ 928 | sadb_algd_maxlen | sadb_algd_reserved | 929 +---------------+---------------+---------------+---------------+ 931 The SPI Range extension 933 +---------------+---------------+---------------+---------------+ 934 | sadb_spirange_len | sadb_spirange_hdrtype | 935 +---------------+---------------+---------------+---------------+ 936 | sadb_spirange_low | 937 +---------------+---------------+---------------+---------------+ 938 | sadb_spirange_hi | 939 +---------------+---------------+---------------+---------------+ 941 3. SYMBOLIC NAMES 943 This section defines various symbols used with PF_KEY and the 944 semantics associated with each symbol. Applications MUST use the 945 symbolic names in order to be portable. The numeric definitions 946 shown are for illustrative purposes, unless explicitly stated 947 otherwise. The numeric definition MAY vary on other systems. The 948 symbolic name MUST be kept the same for all conforming 949 implementations. 951 If an implementation has implementation specific extensions the 952 SADB_X_ prefix MUST be used to name such extensions. 954 3.1 MESSAGE TYPES 956 The following message types are used with PF_KEY. These are 957 defined in the file . 959 #define SADB_GETSPI 1 960 #define SADB_UPDATE 2 961 #define SADB_ADD 3 962 #define SADB_DELETE 4 963 #define SADB_GET 5 964 #define SADB_ACQUIRE 6 965 #define SADB_REGISTER 7 966 #define SADB_EXPIRE 8 967 #define SADB_FLUSH 9 969 #define SADB_DUMP 10 /* not used normally */ 971 #define SADB_MAX 10 973 Each message has a behavior. A behavior is defined as where the 974 initial message travels (e.g. user to kernel), and what subsequent 975 actions are expected to take place. Contents of messages are 976 illustrated as: 978 980 The Lifetime extension is represented with one to three letters after 981 it, to represent (H)ard, (S)oft, or (C)urrent. 983 In the case of an error, only the base header is returned. 985 3.1.1 SADB_GETSPI Message 987 The SADB_GETSPI message allows a process to obtain a unique SPI 988 value for given security association type, source address, and 989 destination address. This message followed by a SADB_UPDATE is one 990 way to create a security association (SADB_ADD is the other method). 991 The process specifies the type in the base header, the source and 992 destination address in address extension, and, if proxy key 993 management is in use, the internal sockaddrs or the proxy sockaddr 994 are also included in the address extension. If the SADB_GETSPI 995 message is in response to a kernel-generated SADB_ACQUIRE, the 996 sadb_msg_seq MUST be the same as the SADB_ACQUIRE message. The 997 application may also specifiy the SPI. This is done by having the 998 kernel select within a range of SPI values by using the SPI range 999 extension. To specify a single SPI value to be verified, the 1000 application sets the high and low values to be equal. Permitting 1001 range specification is important because the kernel can allocate an 1002 SPI value based on what it knows about SPI values already in use. 1003 The kernel returns the same message with the allocated SPI value 1004 stored in the spi field of an association extension. An SADB_UPDATE 1005 message can later be used to add an entry with the requested SPI 1006 value. 1008 The message behavior of the SADB_GETSPI message is: 1010 Send a SADB_GETSPI message from a user process to the kernel. 1012 1014 The kernel returns the SADB_GETSPI message to all listening 1015 processes. 1017 1019 Errors: 1021 EINVAL Various message improprieties, including SPI ranges that 1022 are malformed. 1023 ENOBUFS No buffer space is available to process request. 1024 EEXIST Requested SPI or SPI range is not available/already used. 1026 3.1.2 SADB_UPDATE Message 1028 The SADB_UPDATE message allows a process to update the information 1029 in an existing Security Association. Since SADB_GETSPI does not 1030 allow setting of certain parameters, this message is needed to fully 1031 form the larval security association created with SADB_GETSPI. The 1032 format of the update message is a base header, followed by an 1033 association header and any relevant extensions. If the keying 1034 material, lifetimes, compartment bitmaps, or certificate identities 1035 need to be updated, these extensions should be included. The kernel 1036 searches for the security association with the same type, spi, source 1037 address and destination address specified in the message and updates 1038 the Security Association information using the content of the 1039 SADB_UPDATE message. 1041 The kernel SHOULD perform sanity checking on various technical 1042 parameters passed in as part of the SADB_UPDATE message. One example 1043 is DES key parity bit checking. Other examples include key length 1044 checking, and checks for keys known to be weak for the specified 1045 algorithm. 1047 The kernel MAY disallow SADB_UPDATE to succeed unless the message 1048 is issued from the same socket that created the security association. 1049 Such enforcement significantly reduces the chance of accidental 1050 changes to an in-use security associations. Malicious trusted 1051 parties could still issue a SADB_FLUSH or SADB_DELETE message, but 1052 deletion of associations is more easily detected and less likely to 1053 occur accidentally than an erroneous SADB_UPDATE. 1055 The counter argument involves the case where a user-space key 1056 management application fails, and is restarted. The new instance of 1057 the application will not have the same socket as the creator of the 1058 security association. 1060 The message behavior of the SADB_UPDATE message is: 1062 Send a SADB_UPDATE message from a user process to the kernel. 1064 1067 The kernel returns the SADB_UPDATE message to all listening 1068 processes. 1070 1073 The keying material is not returned on the message from the kernel 1074 to listening sockets because listeners might not have the privileges 1075 to see such keying material. 1077 Errors: 1078 ESRCH The security association to be updated was not found. 1079 EINVAL Various message improprieties, including sanity check 1080 failures on keys. 1081 EACCES Insufficient privilege to update entry. Socket issuing 1082 the SADB_UPDATE is not creator of the entry to be updated. 1084 3.1.3 SADB_ADD Message 1086 The SADB_ADD message is nearly identical to the SADB_UPDATE 1088 message, except that it does not require a previous call to 1089 SADB_GETSPI. The SADB_ADD message is used in manual keying 1090 applications, and in other cases where the uniqueness of the SPI is 1091 known immediately. 1093 An SADB_ADD message is also used when negotiation is finished, and 1094 the second of a pair of associations is added. The SPI for this 1095 association was determined by the peer machine. It MAY be useful to 1096 set the sadb_msg_seq to that of a kernel-generated SADB_ACQUIRE so 1097 that both associations in a pair are bound to the same ACQUIRE 1098 request. 1100 The message behavior of the SADB_ADD message is: 1102 Send a SADB_ADD message from a user process to the kernel. 1104 1107 The kernel returns the SADB_ADD message to all listening 1108 processes. 1110 1113 The keying material is not returned on the message from the kernel to 1114 listening sockets because listeners may not have the privileges to see 1115 such keying material. 1117 Errors: 1119 EEXIST The security association that was to be added already 1120 exists. 1121 EINVAL Various message improprieties, including sanity check 1122 failures on keys. 1124 3.1.4 SADB_DELETE Message 1126 The SADB_DELETE message causes the kernel to delete a Security 1127 Association from the key table. The delete message consists of the 1128 base header followed by the association, and the source and 1129 destination sockaddrs in the address extension. The kernel deletes 1130 the security association matching the type, spi, source address, and 1131 destination address in the message. 1133 The message behavior for SADB_DELETE is as follows: 1135 Send a SADB_DELETE message from a user process to the kernel. 1137 1139 The kernel returns the SADB_DELETE message to all listening 1140 processes. 1142 1144 3.1.5 SADB_GET Message 1146 The SADB_GET message allows a process to retrieve a copy of a 1147 Security Association from the kernel's key table. The get message 1148 consists of the base header follows by the relevant extension fields. 1149 The Security Association matching the type, spi, source address, and 1150 destination address is returned. The K_USED flag is set inside the 1151 Key Engine for the returned Security Association. 1153 The message behavior of the SADB_GET message is: 1155 Send a SADB_GET message from a user process to the kernel. 1157 1159 The kernel returns the SADB_GET message to the socket that sent 1160 the SADB_GET message. 1162 1165 Errors: 1166 ESRCH The sought security association was not found. 1168 3.1.6 SADB_ACQUIRE Message 1170 The SADB_ACQUIRE message is typically sent only by the kernel to 1171 key socket listeners who have registered their key socket (see 1172 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 1173 application-level consumers of security associations (such as an 1174 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 1175 message is a base header along with an address extension, possibly a 1176 certificate identity extension, and if more than one algorithm and 1177 options is acceptable, a proposal extension. The proposed situation 1178 contains a list of desirable algorithms that can be used if the 1179 algorithms in the base header are not available. The values for the 1180 fields in the base header and in the security association data which 1181 follows the base header indicate the properties of the Security 1182 Association that the listening process should attempt to acquire. If 1183 the message originates from the kernel (i.e. the sadb_msg_pid is 0), 1184 the sadb_seq number MUST be used by a subsequent SADB_GETSPI message 1185 to bind a security association to the request. This avoids the race 1186 condition of two TCP connections between two IP hosts that each 1187 require unique associations, and having one steal another's security 1188 association. The sadb_errno and sadb_state fields should be ignored 1189 by the listening process. 1191 The SADB_ACQUIRE message is typically triggered by an outbound 1192 packet that needs security but for which there is no applicable 1193 Security Association existing in the key table. If the packet can be 1194 sufficiently protected by more than one algorithm or combination of 1195 options, the SADB_ACQUIRE message MUST order the preference of 1196 possibilities in the Proposal extension. 1198 There are three messaging behaviors for SADB_ACQUIRE. The first is 1199 where the kernel needs a security association (e.g. for IPsec). 1201 The kernel sends a SADB_ACQUIRE message to registered sockets. 1203 1205 The second is when, for some reason, key management fails, it can 1206 send an ACQUIRE message with the same sadb_msg_seq as the initial 1207 ACQUIRE with a non-zero errno. 1209 Send an SADB_ACQUIRE to inidicate key management failure. 1211 1213 The third is where an application-layer consumer of security 1214 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 1215 association. 1217 Send a SADB_ACQUIRE message from a user process to the kernel. 1219 1221 The kernel returns a SADB_ACQUIRE message to registered sockets. 1223 1225 The user-level consumer waits for a SADB_UPDATE or SADB_ADD 1226 message for its particular type, and then can use that 1227 association by using SADB_GET messages. 1229 Errors: 1230 EINVAL Invalid acquire request. 1231 EPROTONOSUPPORT No KM application has registered with the Key 1232 Engine as being able to obtain the requested SA type, so 1233 the requested SA cannot be acquired. 1235 3.1.7 SADB_REGISTER Message 1237 The SADB_REGISTER message allows an application to register its key 1238 socket as able to acquire new security associations for the kernel. 1239 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 1240 the type of security association specified in sadb_sa_type. The 1241 application specifies the type of security association that it can 1242 acquire for the kernel in the type field of its register message. If 1243 an application can acquire multiple types of security association, it 1244 MUST register each type in a separate message. Only the base header 1245 is needed for the register message. Key management applications MAY 1246 register for a type not known to the kernel, because the consumer may 1247 be in user-space (e.g. OSPFv2 security). 1249 The reply of the SADB_REGISTER message contains a supported 1250 algorithm extension. That field contains an array of supported 1251 algorithm, one per octet. This allows key management applications to 1252 know what algorithm are supported by the kernel. 1254 In an enviroment where algorithms can be dynamically loaded and 1255 unloaded, an asyncryonous SADB_REGISTER reply MAY be generated. The 1256 list of supported algorithms MUST be a complete list, so the 1257 application can make note of omissions or additions. 1259 The messaging behavior of the SADB_REGISTER message is: 1261 Send a SADB_REGISTER message from a user process to the kernel. 1263 1265 The kernel returns a SADB_REGISTER message to registered 1266 sockets, with algorithm types supported by the kernel being 1267 indicated in the supported algorithms field. 1269 NOTE: This message may arrive asynchronously due to an algorithm 1270 being loaded or unloaded into a dynamically linked kernel. 1272 1274 3.1.8 SADB_EXPIRE Message 1275 The operating system kernel is responsible for tracking SA 1276 expirations for security protocols that are implemented inside the 1277 kernel. If the soft limit or hard limit of a Security Association 1278 has expired for a security protocol implemented inside the kernel, 1279 then the kernel MUST issue an SADB_EXPIRE message to all key socket 1280 listeners. A user application is responsible for tracking SA 1281 expirations for security protocols (e.g. OSPF Authentication) that 1282 are implemented inside that user application. If the soft limit or 1283 hard limit of a Security Association has expired, the user 1284 application SHOULD issue a SADB_EXPIRE message. 1286 The base header will contain the security association information 1287 followed by the source sockaddr, destination sockaddr, (and, if 1288 present, internal sockaddr,) (and, if present, one or both 1289 compartment bitmaps). 1291 The lifetime extension of an SADB_EXPIRE message is important to 1292 indicate which lifetime expired. If a HARD lifetime extension is 1293 included, it inidicates that the HARD lifetime expired. This means 1294 the association MAY be deleted already from the SADB. If a SOFT 1295 lifetime extension is included, it indicates that the SOFT lifetime 1296 expired. The CURRENT lifetime extension will indicate the current 1297 status, and comparisons to the HARD or SOFT lifetime will indicate 1298 which limit was reached. HARD lifetimes MUST take precedence over 1299 SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same, 1300 the HARD lifetime will appear on the EXPIRE message. The 1301 pathological case of HARD lifetimes being shorter than SOFT lifetimes 1302 is handled such that the SOFT lifetime will never expire. 1304 The messaging behavior of the SADB_EXPIRE message is: 1306 The kernel sends a SADB_EXPIRE message to all listeners when the 1307 soft limit of a security association has been expired. 1309 1312 ERRORS: 1313 EINVAL Message Invalid for some reason. 1314 EPROTONOSUPPORT ??? 1316 3.1.9 SADB_FLUSH Message 1318 The SADB_FLUSH message causes the kernel to delete all entries in 1319 its key table for a certain sadb_sa_type. Only the base header is 1320 required for a flush message. If sadb_sa_type is filled in with a 1321 specific value, only associations of that type are deleted. If it is 1322 filled in with SADB_SATYPE_NONE, ALL associations are deleted. 1324 The messaging behavior for SADB_FLUSH is: 1326 Send a SADB_FLUSH message from a user process to the kernel. 1328 1330 The kernel will return a SADB_FLUSH message to all listening 1331 sockets. 1333 1335 The reply message happens only after the actual flushing 1336 of security associations has been attempted. 1338 3.1.10 SADB_DUMP Message 1340 The SADB_DUMP message causes the kernel to dump the operating 1341 system's entire Key Table to the requesting key socket. As in 1342 SADB_FLUSH, if a sadb_sa_type value is in the message, only 1343 associations of that type will be dumped. If SADB_SATYPE_NONE is 1344 specified, all associations will be used. Each Security Association 1345 is returned in its own SADB_DUMP message. A SADB_DUMP message with a 1346 sadb_seq field of zero indicates the end of the dump transaction. 1347 Unlike other key messages, the dump message is returned only to the 1348 key socket originating the dump request because of the potentially 1349 large amount of data it can generate. The dump message is used for 1350 debugging purposes only and is not intended for production use. 1351 Support for the dump message MAY be discontinued in future versions 1352 of the key socket, hence key management applications MUST NOT depend 1353 on this message for basic operation. 1355 The messaging behavior for SADB_DUMP is: 1357 Send a SADB_DUMP message from a user process to the kernel. 1359 1361 Several SADB_DUMP messages will return from the kernel to the 1362 sending socket. 1364 1367 3.2 SECURITY ASSOCIATION FLAGS 1368 The Security Association's flags are a bitmask field. These flags 1369 also appear in a combination that is part of a PROPOSAL extension. 1370 The related symbolic definitions below should be used in order that 1371 applications will be portable: 1373 #define SA_USED 0x1 /* SA used/not used */ 1374 #define SA_UNIQUE 0x2 /* SA unique/reusable */ 1375 #define SA_INBOUND 0x4 /* SA for packets destined here */ 1376 #define SA_OUTBOUND 0x8 /* SA for packets sourced here */ 1377 #define SA_FORWARD 0x10 /* SA for packets forwarded thru */ 1378 #define SA_PFS 0x20 /* Perfect forward secrecy? */ 1379 #define SA_REPLAY 0x40 /* Replay protection? */ 1381 SA_USED is set by the operating system if the Security Association 1382 has been used. Otherwise this flag is not set. If SADB_GET is used 1383 to read an SA from the Key Engine, the Key Engine will set SA_USED on 1384 the SA that was read via SADB_GET. 1386 SA_UNIQUE is set by the operating system if the Security 1387 Association has been allocated uniquely to a single user (e.g. a 1388 particular network socket). If this is not set, then the Security 1389 Association is considered sharable. 1391 SA_INBOUND is set for an inbound Security Association and 1392 SA_OUTBOUND is set for an outbound Security Association. SA_FORWARD 1393 is used for a Security Association used only for packets originating 1394 elsewhere and destined elsewhere that have security processing on 1395 this node. Both flags can be set in environments where bidirectional 1396 security associations exist. 1398 ******* 1399 [Dan McD.: Why SA_FORWARD? Isn't SA_OUTBOUND sufficient? I may 1400 implement forwarding such that it's hard or impossible for 1401 the key engine/SADB to tell the difference. ] 1402 ******* 1404 The SA_PFS flag indicates to key management that this association 1405 should have perfect forward secrecy in its key. (In other words, the 1406 session key cannot be determined by cryptanalysis of previous keying 1407 material.) 1409 The SA_REPLAY specifies that replay protection should be enabled on 1410 this association. 1412 3.3 SECURITY ASSOCIATION STATE 1414 The security association state field is an integer that describes 1416 the states of a security association. They are: 1418 #define SA_STATE_LARVAL 0 1419 #define SA_STATE_MATURE 1 1420 #define SA_STATE_DYING 2 1421 #define SA_STATE_DEAD 3 1423 #define SA_STATE_MAX 3 1425 A LARVAL security association is one that was created by the 1426 SADB_GETSPI message. A MATURE association is one that was updated 1427 with the SADB_UPDATE message or added with the SADB_ADD message. A 1428 DYING association is one whose soft lifetime has expired. A DEAD 1429 association is one whose hard lifetime has expired, but hasn't been 1430 reaped by system garbage collection. If a consumer of security 1431 associations has to extend an association beyond its normal lifetime 1432 (e.g. OSPF Security) MUST only set the soft lifetime for an 1433 association. 1435 3.4 SECURITY ASSOCIATION TYPE 1437 This defines the type of Security Association in this message. The 1438 symbolic names are always the same, even on different 1439 implementations. Applications SHOULD use the symbolic name in order 1440 to have maximum portability across different implementations. These 1441 are defined in the file . 1443 #define SADB_SATYPE_NONE 0 1445 #define SADB_SATYPE_AH 1 /* RFC-1826 */ 1446 #define SADB_SATYPE_ESP 2 /* RFC-1827 */ 1448 #define SADB_SATYPE_RSVP 3 /* RSVP Authentication */ 1449 #define SADB_SATYPE_OSPFV2 4 /* OSPFv2 Authentication */ 1450 #define SADB_SATYPE_RIPV2 5 /* RIPv2 Authentication */ 1451 #define SADB_SATYPE_MIPV4 6 /* Mobile IPv4 Authentication */ 1453 #define SADB_SATYPE_MAX 6 1455 SADB_SATYPE_NONE is defined for completeness and means no 1456 Security Association. This type is never used with PF_KEY. 1458 SADB_SATYPE_AH is for the IP Authentication Header defined in 1459 [Atk95b]. SADB_SATYPE_ESP is for the IP Encapsulating Security 1460 Payload defined in [Atk95c]. 1462 SADB_SATYPE_RSVP is for the RSVP Integrity Object. 1464 SADB_SATYPE_OSPFv2 is for OSPFv2 Cryptographic 1465 authentication, while SADB_SATYPE_RIPv2 is for RIPv2 Cryptographic 1466 authentication. 1468 SADB_SATYPE_MAX is never used with PF_KEY but is defined for 1469 completeness. It is always set to the highest valid numeric value. 1470 There MUST not be gaps in the numbering of security types; all 1471 numbers must be used sequentially. 1473 3.5 ALGORITHM TYPES 1475 The algorithm type is interpreted in the context of the Security 1476 Association type defined above. The numeric value might vary between 1477 implementations, but the symbolic name MUST NOT vary between 1478 implementations. Applications should use the symbolic name in order 1479 to have maximum portability to various implementations. 1481 Some of the algorithm types defined below might not be standardized 1482 or might be deprecated in the future. To obtain an assignment for a 1483 symbolic name, contact the editor. 1485 The symbols below are defined in . 1487 /* Authentication algorithms */ 1488 #define SADB_AALG_NONE 0 1490 #define SADB_AALG_MD5_HMAC 1 1491 #define SADB_AALG_SHA1_HMAC 2 1493 #define SADB_AALG_MAX 2 1495 /* Encryption algorithms */ 1496 #define SADB_EALG_NONE 0 1498 #define SADB_EALG_DES_CBC 1 1499 #define SADB_EALG_3DES 2 1500 #define SADB_EALG_RC5 3 1502 #define SADB_EALG_MAX 3 1504 The algorithm for SADB_AALG_MD5_HMAC is defined in [OG96]. The 1505 algorithm for SADB_AALG_SHA1_HMAC is defined in [CG96]. The 1506 algorithm for SADB_EALG_DES_CBC is defined in [Hug96]. 1508 3.6 EXTENSION HEADER VALUES 1510 To briefly recap the extension header values: 1512 #define SA_EXT_ASSOCIATION 1 1513 #define SA_EXT_LIFETIME 2 1514 #define SA_EXT_ADDRESS 3 1515 #define SA_EXT_KEY 4 1516 #define SA_EXT_IDENTITY 5 1517 #define SA_EXT_SENSITIVITY 6 1518 #define SA_EXT_PROPOSAL 7 1519 #define SA_EXT_SUPPORTED 8 1520 #define SA_EXT_SPI_RANGE 9 1522 #define SA_EXT_MAX 9 1524 3.7 ADDRESS EXTENSION VALUES 1526 The sadb_address_which field is a bitmask which can indicate what 1527 sockaddrs follow, and what they represent. These bit values are: 1529 #define SADB_ADDR_SRC 0x1 /* Source */ 1530 #define SADB_ADDR_DST 0x2 /* Destination */ 1531 #define SADB_ADDR_INNER_SRC 0x4 /* Inner-packet src */ 1532 #define SADB_ADDR_INNNER_DST 0x8 /* Inner-packet dst */ 1533 #define SADB_ADDR_PROXY 0x10 /* Proxy address */ 1535 3.8 LIFETIME EXTENSION VALUES 1537 The sadb_lifetime_which field is a bitmask which represents which 1538 lifetime values are in the extension. These bit values are: 1540 #define SADB_LIFETYPE_HARD 0x1 /* Hard lifetime */ 1541 #define SADB_LIFETYPE_SOFT 0x2 /* Soft lifetime */ 1542 #define SADB_LIFETYPE_CURRENT 0x4 /* Current lifetime left */ 1544 3.9 KEY EXTENSION VALUES 1546 The sadb_keyblk_which field is a bitmask which represents which 1547 keys are in the key block. These bit values are: 1549 #define SADB_KEYBLK_AUTH 0x1 /* Authentication key */ 1550 #define SADB_KEYBLK_ENCRYPT 0x2 /* Encryption key */ 1552 3.10 IDENTITY EXTENSION VALUES 1554 The idh_which field is a bitmask which indicates what identities 1555 follow. 1557 #define SADB_ID_SRC 0x1 1558 #define SADB_ID_DST 0x2 1560 Each identity can have a certain type. 1562 #define SADB_IDT_IPV4_ADDR 1 1563 #define SADB_IDT_IPV6_ADDR 2 1564 #define SADB_IDT_IPV4_RANGE 3 1565 #define SADB_IDT_IPV6_RANGE 4 1566 #define SADB_IDT_FQDN 5 1567 #define SADB_IDT_USER_FQDN 6 1568 #define SADB_IDT_IPV4_CONNID 7 1569 #define SADB_IDT_IPV6_CONNID 8 1571 #define SADB_IDT_MAX 8 1573 3.11 SENSITIVITY EXTENSION VALUES 1575 The only field currently defined in the sensitivity extension is 1576 the sadb_sens_dpd, which represents the data protection domain. The 1577 other data in the senstivity extension is based off the sadb_sens_dpd 1578 value. 1580 If the highest order bit of the DP/DOI is set to 1, then the DP/DOI 1581 is not necessarily globally unique and is from a number space set 1582 aside for private use among consenting users. 1584 If the highest order bit of the DP/DOI is set to zero, the DP/DOI 1585 is globally unique from a number space administered by the Internet 1586 Assigned Numbers Authority. In order to conserve the limited amount 1587 of globally unique DP/DOI number space, IANA will not normally permit 1588 any one organization to obtain very many DP/DOI values. The all 1589 zeros DP/DOI value is permanently reserved to mean that "no DP/DOI is 1590 in use". 1592 #define SADB_DPD_NONE 0 1593 #define SADB_DPD_DOD_GENSER 1 1594 #define SADB_DPD_DOD_SCI 2 1595 #define SADB_DPD_DOE 3 1596 #define SADB_DPD_NATO 4 1598 #define SADB_DPD_MAX 4 1600 3.12 PROPOSAL EXTENSION VALUES 1602 These are already mentioned in the ALGORITHM TYPES and ASSOCIATION 1603 FLAGS sections. 1605 4. FUTURE DIRECTIONS 1607 While the current specification for the Sensitivity and Integrity 1608 Labels is believed to be general enough, if a case should arise that 1609 can't work with the current specification then this might cause a 1610 change in a future version of PF_KEY. 1612 Similarly, PF_KEY might need extensions to work with other kinds of 1613 Security Associations in future. It is strongly desirable for such 1614 extensions to be made in a backwards-compatible manner should they be 1615 needed. 1617 ******* 1618 [ALL: What else belongs here ? ] 1619 ******* 1621 5. EXAMPLES 1623 The following examples illustrate how PF_KEY is used. The first 1624 example is an IP Security example, where the consumer of the security 1625 associations is inside an operating system kernel. The second 1626 example is an OSPF Security example, which illustrates a user-level 1627 consumer of security associations. The third example covers things 1628 not mentioned by the first two examples. A real system may closely 1629 conform to one of these examples, or take parts of both. These 1630 examples are purely illustrative, and are not intended to mandate a 1631 particular implementation method. 1633 5.1 IP SECURITY EXAMPLE 1635 +---------------+ +-------------+ 1636 |Key Mgmt Daemon| | Application | 1637 +---------------+ +-------------+ 1638 | | / 1639 | | / 1640 | | | Applications 1641 ======[PF_KEY]====[PF_INET]========================== 1642 | | | OS Kernel 1643 +------------+ +-----------------+ 1644 | Key Engine | | TCP/IP, | 1645 | or SADB |---| including IPsec | 1646 +------------+ | | 1647 +-----------------+ 1649 When the Key Management daemon (KMd) begins. It must tell PF_KEY 1650 that it is willing to accept message for the two IPsec services, AH 1651 and ESP. It does this by sending down two SADB_REGISTER messages. 1653 KMd->Kernel: SADB_REGISTER for ESP 1654 Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms 1655 KMd->Kernel: SADB_REGISTER for AH 1656 Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms 1658 Each REGISTER message will cause a reply to go to all PF_KEY sockets 1659 registered for ESP and AH respectively (including the requester). 1661 Assume that no security associations currently exist for IPsec to 1662 use. Consider when a network application begins transmitting data 1663 (e.g. a TCP SYN). Because of policy, or the application's request, 1664 the kernel IPsec module needs an AH security association for this 1665 data. Since there is not one present, the following message is 1666 generated: 1668 Kernel->Registered: SADB_ACQUIRE for AH, addr, ID, sens, proposal 1670 The KMd reads the ACQUIRE message, espcially the sadb_msg_seq 1671 number. Before it begins the negotiation, it sends down an 1672 SADB_GETSPI message with the sadb_msg_seq number equal to the one 1673 received in the ACQUIRE. The kernel returns the results of the 1674 GETSPI to all listening sockets. 1676 KMd->Kernel: SADB_GETSPI for AH, addr, SPI range 1677 Kernel->All: SADB_GETSPI for AH, assoc, addr 1679 The KMd may perform a second GETSPI operation if it needs both 1680 directions of IPsec SPI values. Now that the KMd has an SPI for at 1681 least one of the security associations, it begins negotiation. After 1682 deriving keying material, and negotiating other parameters, it sends 1683 down one (or more) SADB_UPDATE messages. 1685 Kebe 1686 If a KMd has any error at all during its negotiation, it can send 1687 down 1689 KMd->Kernel: SADB_UPDATE for AH, assoc, addr, key, 1690 Kernel->All: SADB_UPDATE for AH, assoc, addr, 1692 The results of the UPDATE (minus the actual keying material) are sent 1693 to all listening sockets. If only one SPI value was determined 1694 locally, the other SPI (since IPsec SAs are unidirectional) must be 1695 added with an SADB_ADD message. 1697 KMd->Kernel: SADB_ADD for AH, assoc, addr, key, 1698 Kernel->All: SADB_ADD for AH, assoc, addr, 1700 If one of the extensions passed down was a Lifetime extension, it 1702 is possible at some point an SADB_EXPIRE message will arrive when one 1703 of the lifetimes has expired. 1705 Kernel->All: SADB_EXPIRE for AH, assoc, addr, 1706 Hard or Soft, Current, 1708 The KMd can use this as a clue to begin negotiation, or, if it has 1709 some say in policy, send an SADB_UPDATE down with a lifetime 1710 extension. 1712 5.2 OSPF SECURITY EXAMPLE 1714 +---------------+ +-------------+ 1715 |Key Mgmt Daemon| | OSPF daemon | 1716 +---------------+ +-------------+ 1717 | | / / | 1718 | /------|----+ / | 1719 | / | +---+ | Applications 1720 ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================ 1721 | | | | OS Kernel 1722 +------------+ +-----------------+ +---------+ 1723 | Key Engine | | TCP/IP, | | Routing | 1724 | or SADB |---| including IPsec |--| Table | 1725 +------------+ | | +---------+ 1726 +-----------------+ 1728 As in the previous example, the KMd registers itself. Even though 1729 the consumer of the security associations is in user-space, the 1730 PF_KEY implementation knows enough to store SAs and to relay 1731 messages. 1733 When the OSPF daemon needs to communicate securely with its peers, 1734 it would perform an SADB_GET message and retreive the appropriate 1735 association: 1737 OSPFd->Kernel: SADB_GET of OSPF, assoc, address 1738 Kernel->OSPFd: SADB_GET of OSPF, assoc, address, key, 1740 If this GET fails, the OSPFd may need to acquire a new security 1741 association. This interaction is as follows: 1743 OSPFd->Kernel: SADB_ACQUIRE of OSPF, addr, proposal 1744 Kernel->Registered: SADB_ACQUIRE of OSPF, 1746 The KMd sees this and performs actions similar to the previous 1747 example. One difference, however, is that when the UPDATE message 1748 comes back, the OSPFd will then perform a GET of the updated SA to 1749 retrieve ALL of its parameters. 1751 5.2.1 WHY INVOLVE THE KERNEL? 1753 Some have suggested using the PF_KEY messages over something like a 1754 UNIX pipe, or direct communication for situations like the one in 1755 this example. It is a valid approach, but this document does not 1756 pursue this possibility and leaves it to a willing party to document 1757 it. 1759 The two main reasons for involving the kernel are compatibility and 1760 leverage. Compatibility is important so that a KMd can service as 1761 many consumers of SAs as it can. Leverage means that an enhanced 1762 kernel implementation (or specialized user-space OS components) can 1763 provide common SA maintenance routines (such as expiration 1764 generation). 1766 5.3 MISCELLANY 1768 Some messages work well only in system maintenance programs, for 1769 debugging, or for auditing. In a system panic situation, such as a 1770 detected compromise, an SADB_FLUSH message should be issued for a 1771 particular SA type, or for ALL SA types. 1773 Program->Kernel: SADB_FLUSH for ALL 1774 1775 Kernel->All: SADB_FLUSH for ALL 1777 Some SAs may need to be explicitly deleted, either my a KMd, or by 1778 a system maintenance program. 1780 Program->Kernel: SADB_DELETE for AH, association, address 1781 Kernel->All: SADB_DELETE for AH, association, address 1783 Common usage of the SADB_DUMP message is discouraged. For 1784 debugging purposes, however, it can be quite useful. The output of a 1785 DUMP message should be read quickly, in order to avoid socket buffer 1786 overflows. 1788 Program->Kernel: SADB_DUMP for ESP 1789 Kernel->Program: SADB_DUMP for ESP, association, 1790 Kernel->Program: SADB_DUMP for ESP, association, 1791 Kernel->Program: SADB_DUMP for ESP, association, 1792 1794 6. SECURITY CONSIDERATIONS 1796 This draft discusses a method for creating, reading, and deleting 1797 Security Associations from an operating system. Only trusted, 1798 privileged users and processes should be able to perform any of these 1799 operations. It is unclear whether this mechanism provides any 1800 security when used with operating systems not having the concept of a 1801 trusted, privileged user. 1803 If an unprivileged user is able to perform any of these operations, 1804 then the operating system cannot actually provide the related 1805 security services. If an adversary knows the keys and algorithms in 1806 use, then cryptography cannot provide any form of protection. 1808 This mechanism is not a panacea, but it does provide an important 1809 operating system component that can be useful in creating a secure 1810 internetwork. 1812 Users need to understand that the quality of the security provided 1813 by an implementation of this specification depends completely upon 1814 the overall security of the operating system, the correctness of the 1815 PF_KEY implementation, and upon the security and correctness of the 1816 applications that connect to PF_KEY. It is appropriate to use high 1817 assurance development techniques when implementing PF_KEY and the 1818 related security association components of the operating system. 1820 ACKNOWLEDGEMENTS 1822 The editors of this document are listed primarily in Alphabetical 1823 order. A side effect of this particular alphabetical listing is to 1824 also show the history (starting with the most recent) of text 1825 contribution to this document. Ran Atkinson also contributed much 1826 advice and wisdom toward this document. Finally, the editors would 1827 like to thank the PF_KEY reviewers list. 1829 REFERENCES 1830 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig 1831 W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 1832 4.4-Lite BSD", Proceedings of the 1996 USENIX Conference, San 1833 Diego, CA, January 1996, USENIX Association. 1835 [Atk95a] Randall J. Atkinson, IP Security Architecture, RFC-1825, 1836 August 1995. 1838 [Atk95b] Randall J. Atkinson, IP Authentication Header, RFC-1826, 1839 August 1995. 1841 [Atk95c] Randall J. Atkinson, IP Encapsulating Security Payload, RFC-1827, 1842 August 1995. 1844 [CG96] S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with Replay 1845 Prevention", Internet Draft, May 1996. 1847 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 1848 Workstation Specification", Technical Report DDS-2600-6243-87. 1850 [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay 1851 Prevention Security Transform", Internet Draft, April 1996. 1853 [OG96] Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with 1854 Replay Prevention", Internet Draft, May 1996. 1856 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for Berkeley 1857 UNIX", Proceedings of the Winter 1991 USENIX Conference, Dallas, 1858 TX, USENIX Association. 1991. pp. 93-103. 1860 DISCLAIMER 1862 The views and specification here are those of the editors and are not 1863 necessarily those of their employers. The employers have not passed 1864 judgement on the merits, if any, of this work. The editors and their 1865 employers specifically disclaim responsibility for any problems arising 1866 from correct or incorrect implementation or use of this specification. 1868 EDITOR INFORMATION 1870 Daniel L. McDonald 1871 Sun Microsystems, Inc. 1872 2550 Garcia Avenue, MS UMPK17-202 1873 Mountain View, CA 94043-1100 1874 E-mail: danmcd@eng.sun.com 1876 Craig W. Metz 1877 The Inner Net 1878 E-mail: cmetz@inner.net 1880 Bao G. Phan 1881 U. S. Naval Research Laboratory 1882 Code 5544 1883 4555 Overlook Ave. SW 1884 Washington, DC 20375 1885 E-mail: phan@itd.nrl.navy.mil 1887 APPENDIX A: CHANGE LOG 1889 The following changes were made between 01 and 02: 1891 * Mentioned that people COULD use these same messages between user progs. 1892 (Also mentioned why you still might want to use the actual socket.) 1894 * Various wordsmithing changes. 1896 * Took out netkey/ directory, and make net/pfkeyv2.h 1898 * Inserted PF_KEY_V2 proto arguement per C. Metz. 1900 * Mentioned other socket calls and how their PF_KEY behavior is undefined. 1902 * SADB_EXPIRE now communicates both hard and soft lifetime expires. 1904 * New "association" extension, even smaller base header. 1906 * Lifetime extension improvements. 1908 * Length now first in extensions. 1910 * Errors can be sent from kernel to user, also. 1912 * Examples section inserted. 1914 * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup. 1916 * Key splitting now only across auth algorithm and encryption algorithm. 1917 Thanks for B. Sommerfeld for clues here. 1919 The following changes were made between 00 and 01: 1921 * Added this change log. 1923 * Simplified TLV header syntax. 1925 * Splitting of algorithms. This may be controversial, but it allows 1926 PF_KEY to be used for more than just IPsec. It also allows policy to 1927 be placed in the KMd easier. 1929 * Added solid definitions and formats for certificate identities, multiple 1930 keys, etc. 1932 * Specified how keys are to be layed out (most-to-least bits). 1934 * Changed sequence number semantics to be like an RPC transaction ID number.