idnits 2.17.1 draft-mcdonald-pf-key-v2-00.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. ** 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 279 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 208 instances of too long lines in the document, the longest one being 9 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 67: '... - MUST...' RFC 2119 keyword, line 72: '... - SHOULD...' RFC 2119 keyword, line 79: '... - MAY...' RFC 2119 keyword, line 199: '... using PF_KEY MUST NOT depend on t...' RFC 2119 keyword, line 211: '...protocol field MUST be set to th...' (39 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...' == (274 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 (15 November 1996) is 10024 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) -- 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 (~~), 7 warnings (==), 9 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-00.txt B. G. Phan 5 15 November 1996 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 or 33 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"). The 40 Key Engine and its structures incorporate the required security 41 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. 54 Security policy is deliberately omitted from this interface. 55 PF_KEY is not a mechanism for tuning systemwide security policy, nor 56 is it intended to enforce any sort of key management policy. The 57 developers of PF_KEY believed that it was important to separate 58 security mechanisms (such as PF_KEY) from security policies. This 59 permits a single mechanism to more easily support multiple policies. 61 1.1 TERMINOLOGY 63 In this document, the words that are used to define the 64 significance of each particular requirement are usually capitalized. 65 These words are: 67 - MUST 69 This word or the adjective "REQUIRED" means that the item is an 70 absolute requirement of the specification. 72 - SHOULD 74 This word or the adjective "RECOMMENDED" means that there might 75 exist valid reasons in particular circumstances to ignore this item, 76 but the full implications should be understood and the case carefully 77 weighed before taking a different course. 79 - MAY 81 This word or the adjective "OPTIONAL" means that this item is truly 82 optional. One vendor might choose to include the item because a 83 particular marketplace requires it or because it enhances the 84 product, for example; another vendor may omit the same item. 86 1.2 CONCEPTUAL MODEL 88 This section describes the conceptual model of an operating system 89 that implements the PF_KEY key management application programming 90 interface. This section is intended to provide background material 91 useful to understand the rest of this document. Presentation of this 92 conceptual model does not constrain a PF_KEY implementation to 93 strictly adhere to the conceptual components discussed in this 94 subsection. 96 Key management is most commonly implemented in whole or part at the 97 application-layer. For example, the Photuris, ISAKMP, and Oakley 98 proposals for IPsec key management are all application-layer 99 protocols. Even parts of the SKIP IP-layer keying proposal can be 100 implemented at the application layer. Figure 1 shows the 101 relationship between a Key Management daemon and PF_KEY, which it 102 uses to communicate with the Key Engine, and PF_INET (or PF_INET6 in 103 the case of IPv6), which it uses to communicate via the network with 104 a remote key management entity. 106 The "Key Engine" or "Security Association DataBase (SADB)" is a 107 logical entity in the kernel that stores, updates, and deletes 108 Security Association data for various security protocols. There are 109 logical interfaces within the kernel (e.g. getassocbyspi(), 110 getassocbysocket()) that security protocols inside the kernel (e.g. 111 IP Security, aka IPsec) use to request and obtain Security 112 Associations. 114 In the case of IPsec, if by policy a particular outbound packet 115 needs processing, then the IPsec implementation requests an 116 appropriate Security Association from the Key Engine via the kernel- 117 internal interface. If the Key Engine has an appropriate SA, it 118 allocates the SA to this session (marking it as used) and returns the 119 SA to the IPsec implementation for use. If the Key Engine has no 120 such SA but a key management application has previously indicated 121 (via a PF_KEY SADB_REGISTER message) that it can obtain such SAs, 122 then the Key Engine requests that such an SA be created (via a PF_KEY 123 SADB_ACQUIRE message). When the key management daemon creates a new 124 SA, it places it into the Key Engine for future use. 126 +---------------+ 127 |Key Mgmt Daemon| 128 +---------------+ 129 | | 130 | | 131 | | Applications 132 ======[PF_KEY]====[PF_INET]========================== 133 | | OS Kernel 135 +------------+ +-----------------+ 136 | Key Engine | | TCP/IP, | 137 | or SADB |---| including IPsec | 138 +------------+ | | 139 +-----------------+ 140 | 141 +-----------+ 142 | Network | 143 | Interface | 144 +-----------+ 146 Figure 1: Relationship of Key Mgmt to PF_KEY 148 For performance reasons, some security protocols (e.g. IP Security) 149 are usually implemented inside the operating system kernel. Other 150 security protocols (e.g. OSPFv2 Cryptographic Authentication) are 151 implemented in trusted privileged applications outside the kernel. 152 Figure 2 shows a trusted, privileged routing daemon using PF_INET to 153 communicate routing information with a remote routing daemon and 154 using PF_KEY to request, obtain, and delete Security Associations 155 used with a routing protocol. 157 +---------------+ 158 |Routing Daemon| 159 +---------------+ 160 | | 161 | | 162 | | Applications 163 ======[PF_KEY]====[PF_INET]========================== 164 | | OS Kernel 165 +------------+ +---------+ 166 | Key Engine | | TCP/IP | 167 | or SADB |---| | 168 +------------+ +---------+ 169 | 170 +-----------+ 171 | Network | 172 | Interface | 173 +-----------+ 175 Figure 2: Relationship of Trusted Application to PF_KEY 177 When a trusted privileged application is using the Key Engine but 178 implements the security protocol within itself, then operation varies 179 slightly. In this case, the application needing an SA sends a PF_KEY 180 SADB_ACQUIRE message down to the Key Engine, which then either 181 returns an error or sends a similar SADB_ACQUIRE message up to one or 182 more key management applications capable of creating such SAs. As 183 before, the key management daemon stores the SA into the Key Engine. 184 Then, the trusted privileged application uses a SADB_GET message to 185 obtain the SA from the Key Engine. 187 Untrusted clients, for example a user's web browser or telnet 188 client, do not need to use PF_KEY. Mechanisms not specified here are 189 used by such untrusted client applications to request security 190 services (e.g. IPsec) from an operating system. For security 191 reasons, only trusted, privileged applications are permitted to open 192 a PF_KEY socket. 194 1.3 PF_KEY SOCKET DEFINITION 196 The PF_KEY protocol family (PF_KEY) symbol is defined in 197 in the same manner that other protocol families are 198 defined. PF_KEY does not use any socket addresses. Applications 199 using PF_KEY MUST NOT depend on the availability of a symbol named 200 AF_KEY, but kernel implementations are encouraged to define that 201 symbol for completeness. 203 The key socket is created as follows: 205 #include 207 int s; 208 s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2) 210 The PF_KEY domain currently supports only the SOCK_RAW socket type. 211 The protocol field MUST be set to the symbol PF_KEY_V2, which 212 indicates to the kernel that the client would like to use Version 2 213 of the PF_KEY interface. 215 Only a trusted, privileged process can create a PF_KEY socket. On 216 conventional UNIX systems, a privileged process is a process with an 217 effective userid of zero. On non-MLS proprietary operating systems, 218 the notion of a "privileged process" is implementation-defined. On 219 Compartmented Mode Workstations (CMWs) or other systems that claim to 220 provide Multi-Level Security (MLS), a process MUST have the "key 221 management privilege" in order to open a PF_KEY socket[DIA]. MLS 222 systems that don't currently have such a specific privilege MUST add 223 that special privilege and enforce it with PF_KEY in order to comply 224 and conform with this specification. Some systems, most notably some 225 popular personal computers, do not have the concept of a privileged 226 user. These systems SHOULD take steps to restrict the programs 227 allowed to access the PF_KEY API. 229 1.4 OVERVIEW OF PF_KEY MESSAGING BEHAVIOR 231 A process interacts with the key engine by sending and receiving 232 messages using the PF_KEY socket. Security association information 233 can be inserted into and retrieved from the kernel's security 234 association table using a set of predefined messages. In the normal 235 case, all messages sent to the kernel are returned to all open PF_KEY 236 sockets, including the sender. A process can disable this looping 237 back of messages it generates by disabling the SO_USELOOPBACK option 238 using the setsockopt(2) call. A PF_KEY socket listener, which by 239 default receives all replies may disable message reception by 240 terminating socket input with the shutdown(2) call. PF_KEY message 241 delivery is not guaranteed, especially in cases where kernel or 242 socket buffers are exhausted and messages are dropped. 244 Some messages are generated by the operating system to indicate 245 that actions need to be taken, and are not necessarily in response to 246 any message sent down by the user. Such messages are not received by 247 all PF_KEY sockets, but by sockets which have indicated that kernel- 248 originated messages are to be received. These messages are special 249 because of the expected frequency at which they will occur. Also, an 250 implementation may further wish to restrict return message from the 251 kernel, in cases where not all PF_KEY sockets are in the same trust 252 domain. 254 ******* 255 NOTE: SECTIONS LIKE THIS, INSIDE ******* ARE META-COMMENTS AND OPEN 256 ISSUES THAT NEED CONTEXT TO BE CLEAR. 258 [RJA: Clarifying text on security restrictions is needed here, IMHO.] 259 ******* 261 1.5 COMMON PF_KEY OPERATIONS 263 There are two basic ways to add a new Security Association into the 264 kernel. The simplist is to send a single SADB_ADD message, 265 containing all of the SA information, from the application into the 266 kernel's Key Engine. This approach works particularly well with 267 manual key management. 269 The second approach to add a new Security Association into the 270 kernel is for the application to first request an SPI value from the 271 kernel using the SADB_GETSPI message and then send a SADB_UPDATE 272 message with the complete Security Association data. This second 273 approach works well with key management daemons when the SPI values 274 need to be known before the entire Security Association data is known 275 (e.g. so the SPI value can be indicated to the remote end of the key 276 management session). 278 An individual Security Association can be deleted using the 279 SADB_DELETE message. Categories of SAs or the entire kernel SA table 280 can be deleted using the SADB_FLUSH message. 282 The SADB_GET message is used by a trusted application-layer process 283 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 284 SA) from the kernel's Key Engine. 286 The kernel or an application-layer can use the SADB_ACQUIRE message 287 to request that a Security Association be created by some 288 application-layer key management process that has registered with the 289 kernel via a SADB_REGISTER message. 291 The SADB_EXPIRE message is sent from the kernel to key management 292 applications when the "soft lifetime" or "hard lifetime" of a 293 Security Association has expired. Key management applications should 294 use receipt of a SADB_EXPIRE message as a hint to negotiate a 295 replacement SA so the replacement SA will be ready and in the kernel 296 before it is needed. 298 A SADB_DUMP message is also defined, but this is primarily intended 299 for PF_KEY implementer debugging and is not used in ordinary 300 operation of PF_KEY. 302 2. PF_KEY MESSAGE FORMAT 304 PF_KEY messages consist of a base header followed by additional 305 data fields, some of which may be optional. The format of the 306 additional data is dependent on the type of message. 308 PF_KEY messages currently do not mandate any specific ordering for 309 multi-octet fields. In the case that this becomes an issue, network 310 byte order MUST be used. 312 2.1 BASE MESSAGE HEADER FORMAT 314 PF_KEY messages consist of the base message header followed by 315 security association specific data whose lengths (and in some cases, 316 types) are specified in the base message header itself. The data that 317 follow the base header MUST follow in the order that their length 318 fields appear in the security association base message header. A zero 319 length implies that field is not present. 321 This header is shown below, using POSIX types. The fields are 322 arranged primarily for alignment, and where possible, for reasons of 323 clarity. 325 struct sadb_msg_hdr { 326 u_int16_t sadb_msg_len; 327 u_int8_t sadb_msg_type; 328 u_int8_t sadb_msg_errno; 329 u_int32_t sadb_msg_seq; 330 u_int32_t sadb_msg_pid; 332 u_int8_t sadb_sa_type; 333 u_int8_t sadb_sa_state; 334 u_int8_t sadb_sa_transform; 336 u_int8_t sadb_sa_srclen; 337 u_int8_t sadb_sa_dstlen; 338 u_int8_t sadb_sa_proxylen; 339 u_int16_t sadb_sa_keylen; 340 u_int16_t sadb_sa_ivlen; 342 u_int8_t sadb_proposal_len; 343 u_int8_t sadb_reserved; 345 u_int32_t sadb_sa_spi; 346 u_int32_t sadb_sa_sens_domain; 347 u_int32_t sadb_sa_typeopt; 348 u_int32_t sadb_sa_transopt; 350 u_int8_t sadb_sa_lifetype; 351 u_int8_t sadb_sa_lifetimelen; 352 u_int8_t sadb_sa_replay_window_len; 353 u_int8_t sadb_supported_xform_len; 355 u_int8_t sadb_sa_sens_label; 356 u_int8_t sadb_sa_sens_bitmap_len 357 u_int8_t sadb_sa_integ_label; 358 u_int8_t sadb_sa_integ_bitmap_len 360 u_int8_t sadb_sa_src_identtype; 361 u_int8_t sadb_sa_src_identlen; 362 u_int8_t sadb_sa_dst_identtype; 363 u_int8_t sadb_sa_dst_identlen; 364 }; 366 sadb_msg_seq Contains a count of the requests originated by the 367 sender. This field, along with sadb_msg_pid, can be 368 used to uniquely identify requests to a process. The 369 sender is responsible for filling in this field. 371 sadb_msg_len Contains the total length, in octets, of all data in 372 the PF_KEY message including the additional data after 373 the base header, if any. This length includes any 374 padding or extra space that might exist. Unless 375 otherwise stated, all other length fields are also 376 measured in octets. 378 sadb_msg_type Identifies the type of message. The valid message types 379 are described later in this document. 381 sadb_msg_errno Should be set to zero by the sender. The kernel stores 382 the error code in this field if an error has occured. 384 sadb_msg_pid Identifies the process which the kernel thinks the 385 message is bound for. For example: If process id 2112 386 sends a SADB_UPDATE message to the kernel, the 387 SADB_UPDATE reply from the kernel will fill in this 388 fields with 2112. This field, along with sadb_msg_seq, 389 can be used to uniquely identify requests to a process. 391 It is currently believed that a 32-bit quantity will 392 hold an operating system's process ID space. If this 393 assumption is not true, then sadb_msg_pid will have to 394 be revisited. 396 ******* 397 [Dan McD.: In BSD routing sockets, the write() or sendto() return 398 errno immediately to the caller. In System V STREAMS, 399 this is annoying. I propose that we say explicitly 400 that applications _MUST NOT_ depend on errno being 401 returned immediately from write() and SHOULD use the 402 sadb_msg_errno field instead. 404 There are also other properties of routing sockets 405 (pid) that required the bletch we needed for the errno. 406 I've consulted our routing sockets folks, and there are 407 some issues. The PID issue isn't as harsh as the 408 failing write() or sendto() calls, but both are issues 409 in STREAMS. They are solvable, but annoying. ] 411 ******* 413 sadb_sa_type indicates the type of security association (e.g. AH, 414 ESP, OSPF, etc). Valid Security Association types are 415 declared in the file . The current set of 416 Security Association types are enumerated later in this 417 document. 419 sadb_sa_state Is a bitmask field containing the state of the Security 420 Association. This field should be set to zero by the 421 sending process and is set to the state of the Security 422 Association when the message is received. The current 423 set of State flags are enumerated later in this 424 document. 426 sadb_sa_transform 427 Identifies the cryptographic transform to use. The 428 current set of transform names are enumerated later in 429 this document. See section 3.4 for values that can 430 be placed in this field. 432 sadb_sa_srclen Contains the length of the source address for the 433 security association. The source address is the address 434 that will be present in the source address field of 435 protocol headers to be processed by this security 436 association. A value of zero indicates that no source 437 address is present. 439 sadb_sa_dstlen Contains the length of the destination address for the 440 security association. The destination address is the 441 address that will be present in the destination address 442 field of protocol headers to be processed by this 443 security association. A value of zero indicates that no 444 destination address is present. 446 sadb_sa_proxylen 447 Contains the length of the proxy address for the 448 security association. The proxy address is the address 449 of the remote system with which the security 450 association was negotiated (i.e., the node that provided 451 proxy security services on behalf of the system 452 identified in the source address field). 453 A length of zero indicates that proxy key management 454 was not used for this SA and that no proxy address 455 (i.e. "sadb_sa_proxy") will appear below. 457 sadb_sa_keylen Contains the length of the key for the security 458 association, expressed in bits. The key is the data used by 459 the cryptographic transform to process a packet, and it 460 usually secret. A value of zero indicates that no key 461 is present. 463 sadb_sa_ivlen Contains the length of the initialization vector (IV) 464 for the security association, expressed in bits. The IV is 465 the random data used by the cryptographic transform to 466 process a packet. The PF_KEY interface does not communicate 467 or generate the IV data, but it does communicate the 468 length of data needed. A value of zero indicates that 469 no IV is needed. 471 sadb_proposal_len 472 Size of the proposed_situation field. A size of zero 473 indicates that field is not present in this message. 475 sadb_sa_spi Contains the Security Parameters Index value for the 476 Security Association. Although this is a 32-bit field, 477 some types of Security Association might have an SPI or 478 key identifier that is less than 32-bits long. In this 479 case, the smaller value shall be stored in the least 480 significant bits of this field and the unneeded bits 481 shall be zero. 483 sadb_sa_dpd_domain 484 Contains the "Data Protection Domain of Interpretation (DOI)" 485 for the Sensitivity and Integrity data of this security 486 association. A value of zero indicates that sensitivity/ 487 integrity labelling is not in use for this security 488 association. This field contains a 32-bit unsigned integer. 490 Different organizations typically have different values 491 for the Domain of Interpretation. A single 492 organization can have multiple Domains of 493 Interpretation (e.g. one for use by engineering and 494 another for use by personnel) for the sensitivity 495 labelling. See Appendix A for more on the DOI field. 497 The DOI value in a PF_KEY message is used with key 498 management. In an environment where sensitivity labels 499 are in use, communicating or negotiating the 500 sensitivity/integrity information with the remote node 501 can be an important part of the key management process. 502 The Key Engine will typically need to map between the 503 DOI value used with PF_KEY (and thence with key management) 504 and the implementation-specific internal representation. 505 See Appendix A for information on the semantics of DOI values. 507 sadb_sa_typeopt Contains a bitmap of options (e.g. PFS) defined for 508 each specific security association type. 510 sadb_sa_transopt 511 Contains a bitmap of options defined for the transform 512 (e.g. replay protection) specified in the security 513 association. 515 sadb_sa_lifetype 516 Contains the type of the lifetime information being 517 specified for this security association. A value of 518 zero indicates that no lifetime information is being 519 specified. Nonzero values indicate, for example, if 520 the lifetime is in units of data, or in units of time. 522 sadb_sa_lifetimelen 523 Contains the length of each lifetime information datum 524 being specified for this security association. A value 525 of zero indicates that no lifetime information is being 526 specified. If lifetime information is provided, two 527 lifetimes MUST be specified: the first specifying a 528 lower bound, or soft limit; and, the second specifying 529 an upper bound, or hard limit. The hard limit must be 530 greater than, or equal to the soft limit. The lifetime 531 length must be large enough to hold the hard limit. 533 sadb_sa_replay_window_len 534 Size of the Replay Protection window in number of packets. 535 Field is treated as unsigned. If replay protection is 536 not in use, this will have value 0. 538 sadb_supported_xform_len 539 Size of the supported_transforms field. A size of zero 540 indicates that field is not present in this message. 542 sadb_sa_sens_level 543 Indicates the hierarchical ("vertical") sensitivity 544 level associated with this Security Association. The 545 value 0 means "no associated sensitivity level". 546 Values 1 through 255 are interpreted within the context 547 of the sensitivity_domain of this Security Association. 548 Higher values of sensitivity_level indicate greater 549 sensitivity. For example "Top Secret" or "Mergers & 550 Acquisitions" might have value 255 and "Unclassified 551 but sensitive" or "employees only" might have value 552 10. This field is useful in enforcing any security 553 policy following the Bell-LaPadula model. 555 sadb_sa_integ_level 556 Indicates the hierarchical ("vertical") integrity 557 level associated with this Security Association. The 558 value 0 means "no associated integrity level". 559 Values 1 through 255 are interpreted within the context 560 of the sensitivity_domain of this Security Association. 561 Higher values of integrity level indicate greater 562 integrity requirements. For example "Top Secret" or 563 "Mergers & Acquisitions" might have value 255 and 564 "Unclassified but sensitive" or "employees only" might 565 have value 10. This field is useful in supporting 566 any integrity policy following the Biba model. 568 sadb_sa_sens_bitmap_len 569 Contains the length of the compartment bitmap of 570 ("horizontal") sensitivity information being specified 571 for this security association. A value of zero indicates 572 that no sensitivty compartments are in use with this security 573 association. 575 sadb_sa_integ_bitmap_len 576 Contains the length of the compartment bitmap of 577 ("horizontal") integrity information being specified 578 for this security association. A value of zero indicates 579 that no integrity compartments are in use with this security 580 association. 582 sadb_sa_src_identtype 583 sadb_sa_dst_identtype 584 Contains the type of the identity information 585 being specified for this security association. 586 A value of zero indicates that the source/destination 587 addresses are the only identity information and 588 that the corresponding identlen must also be zero. 589 Source and/or destination identities may be specified. 591 sadb_sa_src_identlen 592 sadb_sa_dst_identlen 593 Contains the length of the identity certificate 594 information being specified for this security 595 association. A value of zero indicates that no 596 identity information is being specified (other than 597 the identity implicit in the source/destination 598 addresses). Source and/or destination identities 599 may be specified. 601 2.3 ADDITIONAL MESSAGE FIELDS 603 The additional data following the base header consists of the 604 following variable length fields: 606 sadb_sa_src, sadb_sa_dst, sadb_sa_proxy 608 The src, dst, and proxy addresses are stored in socket address 609 format. The header file MUST define a symbol 610 named KEY_SOCKADDR, which must resolve to the data type of the 611 host's socket address structure. This socket address structure 612 MUST either be compatible with 4.3BSD's struct sockaddr (no 613 sa_len field) or with 4.4BSD's struct sockaddr (with an sa_len 614 field). This will normally be defined as: 616 #define KEY_SOCKADDR struct sockaddr 618 If the host OS provides the option of using 619 4.4BSD-style sockaddrs with an sa_len field, then they MUST be 620 used with the PF_KEY interface. If the host OS does not 621 normally define a socket address structure for use with its 622 sockets interface, it MUST use the definition from 4.4BSD, 623 which includes a sa_len field. The sa_len field in sockaddrs, 624 while compatible with 4.4 BSD, is not strictly needed for PF_KEY 625 sockaddrs, because the lengths are specified in the base 626 header. A PF_KEY implementation MAY require its sockaddrs to have 627 a valid value for sa_len. 629 All KEY_SOCKADDRs MUST have valid address family 630 (sa_family) fields and, if appropriate, address length (sa_len) 631 fields. All other fields in the sockaddr MUST be zeroed out if 632 not used (e.g. sin_port, sin6_port, sin_zero, sin6_flowinfo, 633 etc.). All additional data fields after the base header MUST 634 be 32-bit word aligned to maintain overall message word 635 alignment. Zero padding may be used. Padding MUST be ignored 636 when processing messages. Zero length fields do not require 637 padding. 639 When proxy key management was not used with a particular 640 SA, then that SA will have no sadb_sa_proxy field in the PF_KEY 641 messages or the proxy sockaddr will contain all zeros. 643 security_association_key 644 The cryptographic key to use with this security 645 association. This MUST be padded to a 32-bit boundary. 647 ******* 648 [RJA: Triple-DES and other algorithms/transforms can require more than one 649 crypto key. How do we handle that case ? 651 Dan McD.: Also, if lengths are in octets, we can only support 2040 bits 652 of key. If lengths are in 4-byte words, then we can support 653 longer keys. ] 654 ******* 656 life_time_soft, life_time_hard 657 These designators are in units specified by the 658 sadb_sa_lifetype field and are each sadb_sa_lifelen octets in 659 length. Allowable types of lifetimes are: 661 LIFETYPE_SEC units of seconds of existance of the security 662 association 663 LIFETYPE_KB units of kilobytes of data to which the 664 security association has been applied 665 LIFETIME_PACKETS units of packets to which this SA has been 666 applied. This might be used with Replay Protection. 668 sensitivity_compartment_bitmap 669 This is a variable-length array of octets, padded to a 670 32-bit boundary. The entire set of octets are treated as a 671 single bitmap with each bit being associated with a particular 672 ("horizontal") sensitivity compartment. The values must be 673 interpreted in the context of the sensitivity_domain of this 674 Security Association. For a given bit location, the value 0 675 means that compartment is not present in this Security 676 Association while the value 1 means that compartment is present 677 in this Security Association. 679 If sensitivity compartments are not in use, this field 680 will not exist. Implementations on systems claiming to provide 681 MLS MUST support compartment bitmaps of the larger of (A) at 682 least 32 32-bit words or (B) the number of compartments natively 683 supported on that MLS system. Systems not claiming to provide 684 MLS SHOULD support system administrator configuration of a single 685 static sens_compartment_bitmap value that can be used by key 686 management applications communicating with MLS systems. 688 integrity_compartment_bitmap 689 This is a variable-length array of octets, padded to a 690 32-bit boundary. The entire set of octets are treated as a 691 single bitmap with each bit being associated with a particular 692 ("horizontal") integrity compartment. The values must be 693 interpreted in the context of the sensitivity_domain of this 694 Security Association. For a given bit location, the value 0 695 means that compartment is not present in this Security 696 Association while the value 1 means that compartment is present 697 in this Security Association. If integrity compartments are not 698 in use for a session, this field will not exist. Systems 699 SHOULD permit configuration of at least a single static 700 integ_compartment_bitmap value that can be used by key management 701 applications communicating with that system. 703 supported_transforms 704 This is a variable-length array of octets, padded to a 705 32-bit boundary. Each octet contains a single transform 706 identifier. The value zero means "no transform" and is used 707 only to pad to a 32-bit boundary. This field allows key management 708 applications to know what transforms are supported by the kernel. 709 This is used with the SADB_REGISTER message. The size of this 710 field is indicated by the sadb_supported_xform_len field in the 711 base header. 713 The transforms in this fields SHOULD be ordered in 714 preferential order. 716 ****** 717 [RJA: Transform value assignment remains an open issue. 719 Dan McD: Let's also not forget that when Steve Kent rewhacks 720 things, the representation of supported comes 721 into question. 723 Also, I mention preferential order, but how do I order ESP 724 and AH relative to each other? First the ESP xforms, then 725 AH? ] 726 ****** 728 src_identity, dst_identity 730 These fields denote identity certificate information 731 for the parties using this security association. They are of 732 the type specified by their corresponding identity type field 733 and a length in octets specified by their corresponding 734 identity length field. 736 Identity certificate information is supplied to the key 737 management application for use in negotiation. Certain key 738 management protocols (e.g. ISAKMP) allow for refined policy 739 checks based upon the identities of the parties which will use 740 the security association. 742 Allowable identity types are: 744 ID_IPV4_ADDR an IPv4 address 746 ID_IPV4_ADDR_RANGE an IPv4 address and netmask denoting a 747 subnet 749 ID_IPV6_ADDR an IPv6 address 751 ID_IPV6_ADDR_RANGE an IPv6 address and netmask denoting a 752 subnet 754 ID_FQDN a fully-qualified domain name 756 ID_USER_FQDN user@fully-qualified-domain-name 758 ID_IPV4_CONNID A 5-tuple of . IP addr is IPv4 or 761 IPv6 as appropriate. The protocol 762 number is the same value as appears in 763 the IP protocol field, or the IPv6 764 next-header field. 766 proposed_situation 767 This is a variable-length array of octets, padded to a 768 32-bit boundary. The term, "proposed situation," is borrowed from 769 ISAKMP. A proposed situation is a list of possible algorithms and 770 algorithm options (or transforms) which the kernel requests of 771 key management. 773 The transforms in this field MUST be ordered in 774 preferential order. This field only appears in outgoing 775 SADB_ACQUIRE messages, and indicates that other transforms, 776 in addition to the one in the base header, may be acceptable. 778 ****** 779 [Dan McD.: Same issues as supported_transforms, plus an open question 780 about if we included lifetimes in here as well. ] 781 ****** 783 2.4 ILLUSTRATION OF MESSAGE LAYOUT 785 The following shows how the octets are layed out in a PF_KEY message. 786 Optional fields are indicated as such. 788 The base header is as follows: 790 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 791 +---------------+---------------+---------------+---------------+ 792 | sadb_msg_seq | 793 +---------------+---------------+---------------+---------------+ 794 | sadb_msg_len | sadb_msg_type | sadb_msg_errno| 795 +---------------+---------------+---------------+---------------+ 796 | sadb_msg_pid (NOTE: Assuming pid_t is 32 bits) | 797 +---------------+---------------+---------------+---------------+ 798 | sadb_sa_type | sadb_sa_state | ..transform |sadb_sa_srclen | 799 +---------------+---------------+---------------+---------------+ 800 |sadb_sa_dstlen |sadb_sa_proxylen|sadb_sa_keylen| sadb_sa_ivlen | 801 +---------------+---------------+---------------+---------------+ 802 | sadb_sa_spi | 803 +---------------+---------------+---------------+---------------+ 804 | sadb_sa_sens_domain | 805 +---------------+---------------+---------------+---------------+ 806 | sadb_sa_typeopt | 807 +---------------+---------------+---------------+---------------+ 808 | sadb_sa_transopt | 809 +---------------+---------------+---------------+---------------+ 810 | ..lifetype | ..lifetimelen | ..sens_label | ..bitmap_len | 811 +---------------+---------------+---------------+---------------+ 812 |..src_identtype| ..src_identlen|..dst_identtype| ..dst_identlen| 813 +---------------+---------------+---------------+---------------+ 815 The base header may be followed by one or more of the following 816 optional fields, depending on the values of various base header 817 fields. The following fields are ordered such that if they appear, 818 they MUST appear in the order presented below. 820 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 821 +---------------+---------------+---------------+---------------+ 822 < < 823 | Source sockaddr (optional) | 824 > (Padded to 32 bits) > 825 +---------------+---------------+---------------+---------------+ 827 +---------------+---------------+---------------+---------------+ 828 < < 829 | Destination sockaddr (optional) | 830 > (Padded to 32 bits) > 831 +---------------+---------------+---------------+---------------+ 833 +---------------+---------------+---------------+---------------+ 834 < < 835 | Proxy sockaddr (optional) | 836 > (Padded to 32 bits) > 837 +---------------+---------------+---------------+---------------+ 839 +---------------+---------------+---------------+---------------+ 840 < < 841 | Cryptographic Key (optional) | 842 > (Padded to 32 bits) > 843 +---------------+---------------+---------------+---------------+ 845 +---------------+---------------+---------------+---------------+ 846 < < 847 | Initialization vector (optional) | 848 > (Padded to 32 bits) > 849 +---------------+---------------+---------------+---------------+ 851 +---------------+---------------+---------------+---------------+ 852 < < 853 | Soft and hard lifetime | 854 > (Padded to 32 bits) > 855 +---------------+---------------+---------------+---------------+ 857 +---------------+---------------+---------------+---------------+ 858 < < 859 | Compartment bitmap (optional) | 860 > (Padded to 32 bits) > 861 +---------------+---------------+---------------+---------------+ 863 +---------------+---------------+---------------+---------------+ 864 < < 865 | Supported Transforms (optional) | 866 > (Padded to 32 bits) > 867 +---------------+---------------+---------------+---------------+ 868 +---------------+---------------+---------------+---------------+ 869 < < 870 | Source Identity information (optional) | 871 > (Padded to 32 bits) > 872 +---------------+---------------+---------------+---------------+ 874 +---------------+---------------+---------------+---------------+ 875 < < 876 | Destination Identity information (optional) | 877 > (Padded to 32 bits) > 878 +---------------+---------------+---------------+---------------+ 880 3. SYMBOLIC NAMES 882 This section defines various symbols used with PF_KEY and the 883 semantics associated with each symbol. Applications should use the 884 symbolic name in order to be maximally portable. The numeric 885 definitions shown are for illustrative purposes, unless explicitly 886 stated otherwise. The numeric definition might vary on other 887 systems. The symbolic name MUST be kept the same for all conforming 888 implementations. 890 3.1 MESSAGE TYPES 892 The following message types are used with PF_KEY. These are 893 defined in the file : 895 #define SADB_GETSPI 1 896 #define SADB_UPDATE 2 897 #define SADB_ADD 3 898 #define SADB_DELETE 4 899 #define SADB_GET 5 900 #define SADB_ACQUIRE 6 901 #define SADB_REGISTER 7 902 #define SADB_EXPIRE 8 903 #define SADB_FLUSH 9 905 #define SADB_DUMP 10 /* not used by normal applications */ 907 Each message has a behavior. A behavior is defined as where the 908 initial message travels (e.g. user to kernel), and what subsequent 909 actions are expected to take place. Contents of messages are 910 illustrated as: 912 914 3.1.1 SADB_GETSPI Message 916 The SADB_GETSPI message allows a process to obtain a unique SPI value for 917 given security association type, source address, and destination address. 918 This message followed by a SADB_UPDATE is one way to create a security 919 association (SADB_ADD is the other method). The process specifies the type 920 in the base header, the source and destination address in the source and 921 destination sockaddrs, and, if proxy key management is in use, followed by 922 the proxy sockaddr. The application also specifies the SPI. This is done by 923 either setting the sadb_sa_spi field to a single SPI, or having the kernel 924 select within a range of SPI values by setting the sadb_sa_spi value to 0, 925 and setting the lowest value and highest value by using 4 octet lifetimes. 926 Setting sadb_sa_lifetype to LIFETYPE_SPI_RANGE (seen earlier in this document 927 along with other LIFETYPE_* values), setting the sadb_sa_lifetimelen to 4, 928 and setting the 4-octect lifetime values to the lower and upper bounds for 929 SPI selection. Permitting range specification is important because the 930 kernel can allocate an SPI value based on what it knows about SPI values 931 already in use. The kernel returns the same message with the allocated SPI 932 value stored in the spi field. An update message can later be used to add an 933 entry with the requested SPI value. 935 The message behavior of the SADB_GETSPI message is: 937 Send a SADB_GETSPI message from a user process to the kernel. 939 941 The kernel returns the SADB_GETSPI message to all listening 942 processes. 944 946 Errors: 948 EINVAL Various message improprieties, including SPI ranges that 949 are malformed. 950 ENOBUFS No buffer space is available to process request. 951 EEXIST Requested SPI or SPI range is not available/already used. 953 3.1.2 SADB_UPDATE Message 955 The SADB_UPDATE message allows a process to update the information 956 in an existing Security Association. Since SADB_GETSPI does not 957 allow setting of certain parameters, this message is needed to fully 958 form the larval security association created with SADB_GETSPI. The 959 format of the update message is a base header, followed by source, 960 destination, and possibly proxy. If the key, IV, lifetimes, or 961 compartment bitmap need to be updated, these fields should be 962 included. The kernel searches for the security association with the 963 same type, spi, source address and destination address specified in 964 the message and updates the Security Association information using 965 the content of the SADB_UPDATE message. 967 The kernel SHOULD perform sanity checking on various technical 968 parameters passed in as part of the SADB_UPDATE message. One example 969 is DES key parity bit checking. Other examples include key length 970 checking, and checks for keys known to be weak for the specified 971 algorithm. 973 The kernel SHOULD NOT allow SADB_UPDATE to succeed unless the 974 message is issued from the same socket that created the security 975 association. Such enforcement significantly reduces the chance of 976 accidental changes to an in-use security associations. Malicious 977 trusted parties could still issue a SADB_FLUSH or SADB_DELETE 978 message, but deletion of associations is more easily detected and 979 less likely to occur accidentally than an erroneous SADB_UPDATE. 981 The message behavior of the SADB_UPDATE message is: 983 Send a SADB_UPDATE message from a user process to the kernel. 985 987 The kernel returns the SADB_UPDATE message to all listening 988 processes. 990 992 The keying material is not returned on the message from the kernel 993 to listening sockets because listeners might not have the privileges 994 to see such keying material. 996 Errors: 997 ESRCH The security association to be updated was not found. 998 EINVAL Various message improprieties, including sanity check 999 failures on keys. 1000 EACCES Insufficient privilege to update entry. Socket issuing 1001 the SADB_UPDATE is not creator of the entry to be updated. 1003 3.1.3 SADB_ADD Message 1005 The SADB_ADD message is nearly identical to the SADB_UPDATE 1006 message, except that it does not require a previous call to 1007 SADB_GETSPI. The SADB_ADD message is optimal for manual keying 1008 applications, and other strategies where the uniqueness of the SPI is 1009 known immediately. 1011 The message behavior of the SADB_ADD message is: 1013 Send a SADB_ADD message from a user process to the kernel. 1015 1017 The kernel returns the SADB_ADD message to all listening 1018 processes. 1020 1022 The keying material is not returned on the message from the kernel to 1023 listening sockets because listeners may not have the privileges to see 1024 such keying material. 1026 Errors: 1028 EEXIST The security association that was to be added already 1029 exists. 1030 EINVAL Various message improprieties, including sanity check 1031 failures on keys. 1033 3.1.4 SADB_DELETE Message 1035 The SADB_DELETE message causes the kernel to delete a Security 1036 Association from the key table. The delete message consists of the 1037 base header followed by the source sockaddr and the destination 1038 sockaddr. The kernel deletes the security association matching the 1039 type, spi, source address, and destination address in the message. 1041 There are two message behaviors for SADB_DELETE. The first is a 1042 user- originated deletion 1044 Send a SADB_DELETE message from a user process to the kernel. 1046 1048 The kernel returns the SADB_DELETE message to all listening 1049 processes. 1051 1053 The second behavior is in the case of a hard-limit lifetime 1054 expiration. 1056 The kernel sends a SADB_DELETE message to all listening 1057 processes when a security association times out. 1059 1061 Errors: 1062 ESRCH The security association to be deleted was not found. 1064 3.1.5 SADB_GET Message 1066 The SADB_GET message allows a process to retrieve a copy of a 1067 Security Association from the kernel's key table. The get message 1068 consists of the base header follows by the source sockaddr, 1069 destination sockaddr, and, if it is present in the requested SA, the 1070 proxy sockaddr. The Security Association matching the type, spi, 1071 source address, and destination address is returned. The K_USED flag 1072 is set inside the Key Engine for the returned Security Association. 1074 The message behavior of the SADB_GET message is: 1076 Send a SADB_GET message from a user process to the kernel. 1078 1080 The kernel returns the SADB_GET message to the socket that sent 1081 the SADB_GET message. 1083 1086 Errors: 1087 ESRCH The sought security association was not found. 1089 3.1.6 SADB_ACQUIRE Message 1091 The SADB_ACQUIRE message is typically sent only by the kernel to 1092 key socket listeners who have registered their key socket (see 1093 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 1094 application-level consumers of security associations (such as an 1095 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 1096 message is a base header along with a source sockaddr, destination 1097 sockaddr, possibly certificate identity information, and if more than 1098 one algorithm and options is acceptable, a proposed stuation. The 1099 source and destination sockaddr contains the source and destination 1100 address of the desired Security Association. The proposed situation 1101 contains a list of desirable algorithms and options that can be used 1102 if the algorithm and option in the base header is not available. The 1103 values for the fields in the base header and in the security 1104 association data which follows the base header indicate the 1105 properties of the Security Association that the listening process 1106 should attempt to acquire, except that the sadb_pid, sadb_seq, 1107 sadb_errno, and state fields should be ignored by the listening 1108 process. 1110 The SADB_ACQUIRE message is typically triggered by an outbound 1111 packet that needs security but for which there is no applicable 1112 Security Association existing in the key table. If the packet can be 1113 sufficiently protected by more than one algorithm or combination of 1114 options, the SADB_ACQUIRE message MUST order the preference of 1115 possibilities by placing the most preferred algorithm in the base 1116 header, and the subsequent ones in the proposed_situation field in 1117 order of preference. 1119 There are two messaging behaviors for SADB_ACQUIRE. The first is 1120 where the kernel needs a security association (e.g. for IPsec). 1122 The kernel sends a SADB_ACQUIRE message to registered sockets. 1124 1127 The second is where an application-layer consumer of security 1128 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 1129 association. 1131 Send a SADB_ACQUIRE message from a user process to the kernel. 1133 1136 The kernel returns a SADB_ACQUIRE message to registered sockets. 1138 1141 The user-level consumer waits for a SADB_UPDATE or SADB_ADD message 1142 for its particular type, and then can use that association by using 1143 SADB_GET messages. 1145 Errors: 1146 EINVAL Invalid acquire request. 1147 EPROTONOSUPPORT No KM application has registered with the Key 1148 Engine as being able to obtain the requested SA type, so 1149 the requested SA cannot be acquired. 1151 3.1.7 SADB_REGISTER Message 1153 The SADB_REGISTER message allows an application to register its key 1154 socket as able to acquire new security associations for the kernel. 1155 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 1156 the type of security association specified in sadb_sa_type. The 1157 application specifies the type of security association that it can 1158 acquire for the kernel in the type field of its register message. If 1159 an application can acquire multiple types of security association, it 1160 MUST register each type in a separate message. Only the base header 1161 is needed for the register message. For portability reasons, key 1162 management applications MAY register for a type not known to the 1163 kernel. 1165 The reply of the SADB_REGISTER message contains a 1166 supported_transforms field. That field contains an array of 1167 supported transforms, one per octet. This allows key management 1168 applications to know what transforms are supported by the kernel. 1170 The messaging behavior of the SADB_REGISTER message is: 1172 Send a SADB_REGISTER message from a user process to the kernel. 1174 1176 The kernel returns a SADB_REGISTER message, with transform types 1177 supported by the kernel being indicated in the supported transforms 1178 field. 1180 1182 3.1.8 SADB_EXPIRE Message 1183 The operating system kernel is responsible for tracking SA 1184 expirations for security protocols that are implemented inside the 1185 kernel. If the soft limit of a Security Association has expired for 1186 a security protocol implemented inside the kernel, then the kernel 1187 MUST issue a SADB_EXPIRE message to all key socket listeners. A user 1188 application is responsible for tracking SA expirations for security 1189 protocols (e.g. OSPF Authentication) that are implemented inside that 1190 user application. If the soft limit of a Security Association has 1191 expired, the user application SHOULD issue a SADB_EXPIRE message. 1192 Regardless of where the security protocol is implemented, if both the 1193 soft limit and the hard limit expire at the same time, both 1194 SADB_DELETE and SADB_EXPIRE messages MUST be sent. 1196 The base header will contain the security association information 1197 followed by the source sockaddr, destination sockaddr, (and, if 1198 present, proxy sockaddr,) (and, if present, one or both compartment 1199 bitmaps). 1201 The messaging behavior of the SADB_EXPIRE message is: 1203 The kernel sends a SADB_EXPIRE message when the soft limit of a 1204 security association has been expired. 1206 1208 ERRORS: 1209 EINVAL Message Invalid for some reason. 1210 EPROTONOSUPPORT ??? 1212 3.1.9 SADB_FLUSH Message 1214 The SADB_FLUSH message causes the kernel to delete all entries in 1215 its key table for a certain sadb_sa_type. Only the base header is 1216 required for a flush message. If sadb_sa_type is filled in with a 1217 specific value, only associations of that type are deleted. If it is 1218 filled in with SEC_TYPE_NONE, ALL associations are deleted. 1220 The messaging behavior for SADB_FLUSH is: 1222 Send a SADB_FLUSH message from a user process to the kernel. 1224 1226 The kernel will return a SADB_FLUSH message to all listening 1227 sockets. 1229 1231 The reply message happens only after the actual flushing 1232 of security associations has been attempted. 1234 3.1.10 SADB_DUMP Message 1236 The SADB_DUMP message causes the kernel to dump the operating 1237 system's entire Key Table to the requesting key socket. As in 1238 SADB_FLUSH, if a sadb_sa_type value is in the message, only 1239 associations of that type will be dumped. If SEC_TYPE_NONE is 1240 specified, all associations will be used. Each Security Association 1241 is returned in its own SADB_DUMP message. A SADB_DUMP message with a 1242 sadb_seq field of zero indicates the end of the dump transaction. 1243 Unlike other key messages, the dump message is returned only to the 1244 key socket originating the dump request because of the potentially 1245 large amount of data it can generate. The dump message is used for 1246 debugging purposes only and is not intended for production use. 1247 Support for the dump message MAY be discontinued in future versions 1248 of the key socket, hence key management applications MUST NOT depend 1249 on this message for basic operation. 1251 The messaging behavior for SADB_DUMP is: 1253 Send a SADB_DUMP message from a user process to the kernel. 1255 1257 Several SADB_DUMP messages will return from the kernel to the 1258 sending socket. 1260 1263 3.2 SECURITY ASSOCIATION STATE 1264 The Security Association's state is a bitmask field. The related 1265 symbolic definitions below should be used in order that applications 1266 will be maximally portable: 1268 #define SA_USED 0x01 /* SA used/not used */ 1269 #define SA_UNIQUE 0x02 /* SA unique/reusable */ 1270 #define SA_LARVAL 0x04 /* SPI assigned, but SA incomplete */ 1271 #define SA_ZOMBIE 0x08 /* SA expired but still useable */ 1272 #define SA_DEAD 0x10 /* SA marked for deletion */ 1273 #define SA_INBOUND 0x20 /* SA for packets destined here */ 1274 #define SA_OUTBOUND 0x40 /* SA for packets sourced here */ 1275 #define SA_FORWARD 0x80 /* SA for packets forwarded thru */ 1277 All unspecified values in the bitmask field are reserved and MUST 1278 NOT be used. 1280 SA_USED is set by the operating system if the Security Association 1281 has been used. Otherwise this flag is not set. If SADB_GET is used 1282 to read an SA from the Key Engine, the Key Engine will set SA_USED on 1283 the SA that was read via SADB_GET. 1285 SA_UNIQUE is set by the operating system if the Security 1286 Association has been allocated uniquely to a single user (e.g. a 1287 particular network socket). If this is not set, then the Security 1288 Association is considered sharable. 1290 SA_LARVAL indicates that the operating system has assigned this SPI 1291 value but that there is no complete Security Association yet stored 1292 in the kernel. 1294 SA_ZOMBIE indicates a Security Association that has expired but is 1295 still useable until a replacement Security Association is added. 1296 This is primarily used with OSPFv2 and RIPv2 cryptographic 1297 authentication. 1299 SA_DEAD indicates a Security Association that exists but is marked 1300 for deletion. 1302 SA_INBOUND is set for an inbound Security Association and 1303 SA_OUTBOUND is set for an outbound Security Association. SA_FORWARD 1304 is used for a Security Association used only for packets originating 1305 elsewhere and destined elsewhere that have security processing on 1306 this node. All Security Associations used with PF_KEY are 1307 unidirectional. 1309 ******* [Dan McD.: Why SA_FORWARD? Isn't SA_OUTBOUND 1310 sufficient? I may implement forwarding such that 1311 it's hard or impossible for the key engine/SADB to 1312 tell the difference. ] ******* 1314 3.3 SECURITY ASSOCIATION TYPE 1316 This defines the type of Security Association in this message. The 1317 numeric definitions are those used in the prototype NRL 1318 implementation, but might be different on other implementations. The 1319 symbolic names are always the same, even on different 1320 implementations. Applications should use the symbolic name in order 1321 to have maximum portability across different implementations. These 1322 are defined in the file . 1324 #define SEC_TYPE_NONE 0 1326 #define SEC_TYPE_AH 1 /* RFC-1826 */ 1327 #define SEC_TYPE_ESP 2 /* RFC-1827 */ 1329 #define SEC_TYPE_RSVP 3 /* RSVP Authentication */ 1330 #define SEC_TYPE_OSPFV2 4 /* OSPFv2 Authentication */ 1331 #define SEC_TYPE_RIPV2 5 /* RIPv2 Authentication */ 1332 #define SEC_TYPE_MIPV4 6 /* Mobile IPv4 Authentication */ 1334 #define SEC_TYPE_MAX 6 1336 SEC_TYPE_NONE is defined for completeness and means no 1337 Security Association. This type is never used with PF_KEY. 1339 SEC_TYPE_AH is for the IP Authentication Header defined in 1340 [Atk95b]. SEC_TYPE_ESP is for the IP Encapsulating Security Payload 1341 defined in [Atk95c]. 1343 SEC_TYPE_RSVP is for the RSVP Integrity Object. 1345 SEC_TYPE_OSPFv2 is for OSPFv2 Cryptographic authentication, 1346 while SEC_TYPE_RIPv2 is for RIPv2 Cryptographic authentication. 1348 SEC_TYPE_MAX is never used with PF_KEY but is defined for 1349 completeness. It is always set to the highest valid numeric value. 1350 There must not be gaps in the numbering of security types; all 1351 numbers must be used sequentially. 1353 3.4 ALGORITHM TYPE 1355 The algorithm type is interpreted in the context of the Security 1356 Association type defined above. The numeric value might vary between 1357 implementations, but the symbolic name MUST NOT vary between 1358 implementations. Applications should use the symbolic name in order 1359 to have maximum portability to various implementations. 1361 Some of the algorithm types defined below might not be standardized 1362 or might be deprecated in the future. To obtain an assignment for a 1363 symbolic name, contact the editor. 1365 The symbols below are defined in . 1367 #define SEC_ALGTYPE_AH_MD5 0 /* deprecated */ 1368 #define SEC_ALGTYPE_AH_SHA 1 /* deprecated */ 1369 #define SEC_ALGTYPE_AH_MD5_HMAC 2 1370 #define SEC_ALGTYPE_AH_SHA1_HMAC 3 1372 #define SEC_ALGTYPE_ESP_DES_CBC 0 /* deprecated */ 1373 #define SEC_ALGTYPE_ESP_3DES 1 /* deprecated */ 1374 #define SEC_ALGTYPE_ESP_COM_DES_CBC_MD5 2 1376 #define SEC_ALGTYPE_RSVP_MD5 0 1377 #define SEC_ALGTYPE_OSPF_MD5 0 1378 #define SEC_ALGTYPE_RIP_MD5 0 1380 ******* 1381 [RJA: With the coming Steve Kent editorial changes to IPsec, this section 1382 is likely to change slightly to just specify "algorithms" and not 1383 specify "transforms". 1385 Dan McD: Given this, the "transform options" become MUCH more 1386 critical. ] 1388 ******* 1390 The algorithm for SEC_ALGTYPE_AH_MD5_HMAC is defined in [OG96]. The 1391 algorithm for SEC_ALGTYPE_AH_SHA1_HMAC is defined in [CG96]. The 1392 algorithm for SEC_ALGTYPE_ESP_COM_DES_CBC_MD5 is defined in [Hug96]. 1394 Mobile IP does not yet have a named algorithm type. 1396 3.5 TYPE OPTIONS 1398 Security association types can have various options defined. 1399 Options are denoted by a bit setting in the "Type Options" field of 1400 the base header. The bitmasks for defined options MUST NOT vary 1401 between implementations. 1403 #define SEC_TYPEOPTION_PFS 0x00000001 /* Use Perfect Forward Secrecy */ 1405 The SEC_TYPEOPTION_PFS flag indicates to key management that this 1406 association should have perfect forward secrecy in its key. (In 1407 other words, the session key cannot be determined by cryptanalysis of 1408 previous keying material.) 1410 3.6 TRANSFORM OPTIONS 1412 Algorithm-specific options are specified by the "Transform Options" 1413 bitmap of the base header. The bitmasks for defined options MUST NOT 1414 vary between applications. Note that if SEC_TRANSOPTION_TUNNEL is 1415 not set for an IPsec SA, then that SA must be a transport-mode SA. 1417 #define SEC_TRANSOPTION_REPLAY 0x00000001 /* Replay Protection enabled */ 1418 #define SEC_TRANSOPTION_TUNNEL 0x00000002 /* Tunnel Mode enabled */ 1419 #define SEC_TRANSOPTION_AH_PAD 0x00000004 /* Pad AH to 64-bit boundary */ 1421 ******* [Dan McD.: We may need another one SEC_TRANSOPTION_HMAC, 1422 for ESP, and if that's the case, we may need a 1423 secondary algorithm identifier for ESP. ] ******* 1425 4. FUTURE DIRECTIONS 1427 While the current specification for the Sensitivity and Integrity 1428 Labels is believed to be general enough, if a case should arise that 1429 can't work with the current specification then this might cause a 1430 change in a future version of PF_KEY. 1432 Similarly, PF_KEY might need extensions to work with other kinds of 1433 Security Associations in future. It is strongly desirable for such 1434 extensions to be made in a backwards-compatible manner should they be 1435 needed. 1437 ******* 1438 [RJA: What else belongs here ? ] 1439 ******* 1441 5. SECURITY CONSIDERATIONS 1443 This draft discusses a method for creating, reading, and deleting 1444 Security Associations from an operating system. Only trusted, 1445 privileged users and processes should be able to perform any of these 1446 operations. It is unclear whether this mechanism provides any 1447 security when used with operating systems not having the concept of a 1448 trusted, privileged user. 1450 If an unprivileged user is able to perform any of these operations, 1451 then the operating system cannot actually provide the related 1452 security services. If an adversary knows the keys and algorithms in 1453 use, then cryptography cannot provide any form of protection. 1455 This mechanism is not a panacea, but it does provide an important 1456 operating system component that can be useful in creating a secure 1457 internetwork. 1459 Users need to understand that the quality of the security provided 1460 by an implementation of this specification depends completely upon 1461 the overall security of the operating system, the correctness of the 1462 PF_KEY implementation, and upon the security and correctness of the 1463 applications that connect to PF_KEY. It is appropriate to use high 1464 assurance development techniques when implementing PF_KEY and the 1465 related security association components of the operating system. 1467 ACKNOWLEDGEMENTS 1469 The editors of this document are listed primarily in Alphabetical 1470 order. A side effect of this particular alphabetical listing is to 1471 also show the history (starting with the most recent) of text 1472 contribution to this document. Ran Atkinson also contributed much 1473 advice and wisdom toward this document. 1475 REFERENCES 1476 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig W. Metz, 1477 and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite BSD", 1478 Proceedings of the 1996 USENIX Conference, San Diego, CA, 1479 January 1996, USENIX Association. 1481 [Atk95a] Randall J. Atkinson, IP Security Architecture, RFC-1825, 1482 August 1995. 1484 [Atk95b] Randall J. Atkinson, IP Authentication Header, RFC-1826, 1485 August 1995. 1487 [Atk95c] Randall J. Atkinson, IP Encapsulating Security Payload, RFC-1827, 1488 August 1995. 1490 [CG96] S. Chang & Rob Glenn, "HMAC-SHA IP Authentication with Replay 1491 Prevention", Internet Draft, May 1996. 1493 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 1494 Workstation Specification", Technical Report DDS-2600-6243-87. 1496 [Hug96] Jim Hughes (Editor), "Combined DES-CBC, HMAC, and Replay 1497 Prevention Security Transform", Internet Draft, April 1996. 1499 [OG96] Mike Oehler & Rob Glenn, "HMAC-MD5 IP Authentication with 1500 Replay Prevention", Internet Draft, May 1996. 1502 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for Berkeley 1503 UNIX", Proceedings of the Winter 1991 USENIX Conference, Dallas, 1504 TX, USENIX Association. 1991. pp. 93-103. 1506 DISCLAIMER 1508 The views and specification here are those of the editors and are not 1509 necessarily those of their employers. The employers have not passed 1510 judgement on the merits, if any, of this work. The editors and their 1511 employers specifically disclaim responsibility for any problems arising 1512 from correct or incorrect implementation or use of this specification. 1514 EDITOR INFORMATION 1516 Daniel L. McDonald 1517 Sun Microsystems, Inc. 1518 2550 Garcia Avenue, MS UMPK17-202 1519 Mountain View, CA 94043-1100 1520 E-mail: danmcd@eng.sun.com 1522 Craig W. Metz 1523 The Inner Net 1524 Code 1123, Box 10314 1525 Blacksburg, VA 24062-0314 1526 E-mail: cmetz@inner.net 1528 Bao G. Phan 1529 U. S. Naval Research Laboratory 1530 Code 5544 1531 4555 Overlook Ave. SW 1532 Washington, DC 20375 1533 E-mail: phan@itd.nrl.navy.mil 1535 APPENDIX A: DATA PROTECTION DOI ASSIGNMENTS 1537 The Data Protection Domain of Interpretation (DP/DOI) indicates the context 1538 in which particular values of a Sensitivity Label, Integrity Label, 1539 Sensitivity Bitmap, and Integrity Bitmap are interpreted. This is a 32-bit 1540 opaque value. 1542 If the highest order bit of the DP/DOI is set to 1, then the DP/DOI is not 1543 necessarily globally unique and is from a number space set aside for private 1544 use among consenting users. 1546 If the highest order bit of the DP/DOI is set to zero, the DP/DOI is 1547 globally unique from a number space administered by the Internet Assigned 1548 Numbers Authority. In order to conserve the limited amount of globally 1549 unique DP/DOI number space, IANA will not normally permit any one 1550 organization to obtain very many DP/DOI values. The all zeros DP/DOI value 1551 is permanently reserved to mean that "no DP/DOI is in use". 1553 INITIAL VALUES: 1555 Organization: Value: 1556 ------------------- ------ 1557 No DP/DOI is in use 0 1558 US Dept of Defense GENSER 1 1559 US Dept of Defense SCI 2 1560 US Dept of Energy 3 1561 NATO 4 1563 (REMAINDER OF THIS SECTION IS TBD)