1 2 3 4 5 6 7Network Working Group D. McDonald 8Request for Comments: 2367 C. Metz 9Category: Informational B. Phan 10 July 1998 11 12 13 PF_KEY Key Management API, Version 2 14 15Status of this Memo 16 17 This memo provides information for the Internet community. It does 18 not specify an Internet standard of any kind. Distribution of this 19 memo is unlimited. 20 21Copyright Notice 22 23 Copyright (C) The Internet Society (1998). All Rights Reserved. 24 25Abstract 26 27 A generic key management API that can be used not only for IP 28 Security [Atk95a] [Atk95b] [Atk95c] but also for other network 29 security services is presented in this document. Version 1 of this 30 API was implemented inside 4.4-Lite BSD as part of the U. S. Naval 31 Research Laboratory's freely distributable and usable IPv6 and IPsec 32 implementation[AMPMC96]. It is documented here for the benefit of 33 others who might also adopt and use the API, thus providing increased 34 portability of key management applications (e.g. a manual keying 35 application, an ISAKMP daemon, a GKMP daemon [HM97a][HM97b], a 36 Photuris daemon, or a SKIP certificate discovery protocol daemon). 37 38Table of Contents 39 40 1 Introduction ............................................. 3 41 1.1 Terminology .............................................. 3 42 1.2 Conceptual Model ......................................... 4 43 1.3 PF_KEY Socket Definition ................................. 8 44 1.4 Overview of PF_KEY Messaging Behavior .................... 8 45 1.5 Common PF_KEY Operations ................................. 9 46 1.6 Differences Between PF_KEY and PF_ROUTE .................. 10 47 1.7 Name Space ............................................... 11 48 1.8 On Manual Keying ..........................................11 49 2 PF_KEY Message Format .................................... 11 50 2.1 Base Message Header Format ............................... 12 51 2.2 Alignment of Headers and Extension Headers ............... 14 52 2.3 Additional Message Fields ................................ 14 53 2.3.1 Association Extension .................................... 15 54 2.3.2 Lifetime Extension ....................................... 16 55 56 57 58McDonald, et. al. Informational [Page 1] 59 60RFC 2367 PF_KEY Key Management API July 1998 61 62 63 2.3.3 Address Extension ........................................ 18 64 2.3.4 Key Extension ............................................ 19 65 2.3.5 Identity Extension ....................................... 21 66 2.3.6 Sensitivity Extension .................................... 21 67 2.3.7 Proposal Extension ....................................... 22 68 2.3.8 Supported Algorithms Extension ........................... 25 69 2.3.9 SPI Range Extension ...................................... 26 70 2.4 Illustration of Message Layout ........................... 27 71 3 Symbolic Names ........................................... 30 72 3.1 Message Types ............................................ 31 73 3.1.1 SADB_GETSPI .............................................. 32 74 3.1.2 SADB_UPDATE .............................................. 33 75 3.1.3 SADB_ADD ................................................. 34 76 3.1.4 SADB_DELETE .............................................. 35 77 3.1.5 SADB_GET ................................................. 36 78 3.1.6 SADB_ACQUIRE ............................................. 36 79 3.1.7 SADB_REGISTER ............................................ 38 80 3.1.8 SADB_EXPIRE .............................................. 39 81 3.1.9 SADB_FLUSH ............................................... 40 82 3.1.10 SADB_DUMP ................................................ 40 83 3.2 Security Association Flags ............................... 41 84 3.3 Security Association States .............................. 41 85 3.4 Security Association Types ............................... 41 86 3.5 Algorithm Types .......................................... 42 87 3.6 Extension Header Values .................................. 43 88 3.7 Identity Extension Values ................................ 44 89 3.8 Sensitivity Extension Values ............................. 45 90 3.9 Proposal Extension Values ................................ 45 91 4 Future Directions ........................................ 45 92 5 Examples ................................................. 45 93 5.1 Simple IP Security Example ............................... 46 94 5.2 Proxy IP Security Example ................................ 47 95 5.3 OSPF Security Example .................................... 50 96 5.4 Miscellaneous ............................................ 50 97 6 Security Considerations .................................. 51 98 Acknowledgments ............,............................. 52 99 References ............................................... 52 100 Disclaimer ............................................... 54 101 Authors' Addresses ....................................... 54 102 A Promiscuous Send/Receive Extension ....................... 55 103 B Passive Change Message Extension ......................... 57 104 C Key Management Private Data Extension .................... 58 105 D Sample Header File ....................................... 59 106 E Change Log ............................................... 64 107 F Full Copyright Statement ................................. 68 108 109 110 111 112 113 114McDonald, et. al. Informational [Page 2] 115 116RFC 2367 PF_KEY Key Management API July 1998 117 118 1191 Introduction 120 121 PF_KEY is a new socket protocol family used by trusted privileged key 122 management applications to communicate with an operating system's key 123 management internals (referred to here as the "Key Engine" or the 124 Security Association Database (SADB)). The Key Engine and its 125 structures incorporate the required security attributes for a session 126 and are instances of the "Security Association" (SA) concept 127 described in [Atk95a]. The names PF_KEY and Key Engine thus refer to 128 more than cryptographic keys and are retained for consistency with 129 the traditional phrase, "Key Management". 130 131 PF_KEY is derived in part from the BSD routing socket, PF_ROUTE. 132 [Skl91] This document describes Version 2 of PF_KEY. Version 1 was 133 implemented in the first five alpha test versions of the NRL 134 IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco 135 ISAKMP/Oakley key management daemon. Version 2 extends and refines 136 this interface. Theoretically, the messages defined in this document 137 could be used in a non-socket context (e.g. between two directly 138 communicating user-level processes), but this document will not 139 discuss in detail such possibilities. 140 141 Security policy is deliberately omitted from this interface. PF_KEY 142 is not a mechanism for tuning systemwide security policy, nor is it 143 intended to enforce any sort of key management policy. The developers 144 of PF_KEY believe that it is important to separate security 145 mechanisms (such as PF_KEY) from security policies. This permits a 146 single mechanism to more easily support multiple policies. 147 1481.1 Terminology 149 150 Even though this document is not intended to be an actual Internet 151 standard, the words that are used to define the significance of 152 particular features of this interface are usually capitalized. Some 153 of these words, including MUST, MAY, and SHOULD, are detailed in 154 [Bra97]. 155 156 - CONFORMANCE and COMPLIANCE 157 158 Conformance to this specification has the same meaning as compliance 159 to this specification. In either case, the mandatory-to-implement, 160 or MUST, items MUST be fully implemented as specified here. If any 161 mandatory item is not implemented as specified here, that 162 implementation is not conforming and not compliant with this 163 specification. 164 165 166 167 168 169 170McDonald, et. al. Informational [Page 3] 171 172RFC 2367 PF_KEY Key Management API July 1998 173 174 175 This specification also uses many terms that are commonly used in the 176 context of network security. Other documents provide more 177 definitions and background information on these [VK83, HA94, Atk95a]. 178 Two terms deserve special mention: 179 180 - (Encryption/Authentication) Algorithm 181 182 For PF_KEY purposes, an algorithm, whether encryption or 183 authentication, is the set of operations performed on a packet to 184 complete authentication or encryption as indicated by the SA type. A 185 PF_KEY algorithm MAY consist of more than one cryptographic 186 algorithm. Another possibility is that the same basic cryptographic 187 algorithm may be applied with different modes of operation or some 188 other implementation difference. These differences, henceforth called 189 _algorithm differentiators_, distinguish between different PF_KEY 190 algorithms, and options to the same algorithm. Algorithm 191 differentiators will often cause fundamentally different security 192 properties. 193 194 For example, both DES and 3DES use the same cryptographic algorithm, 195 but they are used differently and have different security properties. 196 The triple-application of DES is considered an algorithm 197 differentiator. There are therefore separate PF_KEY algorithms for 198 DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same hash function, but 199 construct their message authentication codes differently. The use of 200 HMAC is an algorithm differentiator. DES-ECB and DES-CBC are the 201 same cryptographic algorithm, but use a different mode. Mode (e.g., 202 chaining vs. code-book) is an algorithm differentiator. Blowfish with 203 a 128-bit key, however, is similar to Blowfish with a 384-bit key, 204 because the algorithm's workings are otherwise the same and therefore 205 the key length is not an algorithm differentiator. 206 207 In terms of IP Security, a general rule of thumb is that whatever 208 might be labeled the "encryption" part of an ESP transform is 209 probably a PF_KEY encryption algorithm. Whatever might be labelled 210 the "authentication" part of an AH or ESP transform is probably a 211 PF_KEY authentication algorithm. 212 2131.2 Conceptual Model 214 215 This section describes the conceptual model of an operating system 216 that implements the PF_KEY key management application programming 217 interface. This section is intended to provide background material 218 useful to understand the rest of this document. Presentation of this 219 conceptual model does not constrain a PF_KEY implementation to 220 strictly adhere to the conceptual components discussed in this 221 subsection. 222 223 224 225 226McDonald, et. al. Informational [Page 4] 227 228RFC 2367 PF_KEY Key Management API July 1998 229 230 231 Key management is most commonly implemented in whole or in part at 232 the application layer. For example, the ISAKMP/Oakley, GKMP, and 233 Photuris proposals for IPsec key management are all application-layer 234 protocols. Manual keying is also done at the application layer. 235 Even parts of the SKIP IP-layer keying proposal can be implemented at 236 the application layer. Figure 1 shows the relationship between a Key 237 Management daemon and PF_KEY. Key management daemons use PF_KEY to 238 communicate with the Key Engine and use PF_INET (or PF_INET6 in the 239 case of IPv6) to communicate, via the network, with a remote key 240 management entity. 241 242 The "Key Engine" or "Security Association Database (SADB)" is a 243 logical entity in the kernel that stores, updates, and deletes 244 Security Association data for various security protocols. There are 245 logical interfaces within the kernel (e.g. getassocbyspi(), 246 getassocbysocket()) that security protocols inside the kernel (e.g. 247 IP Security, aka IPsec) use to request and obtain Security 248 Associations. 249 250 In the case of IPsec, if by policy a particular outbound packet needs 251 processing, then the IPsec implementation requests an appropriate 252 Security Association from the Key Engine via the kernel-internal 253 interface. If the Key Engine has an appropriate SA, it allocates the 254 SA to this session (marking it as used) and returns the SA to the 255 IPsec implementation for use. If the Key Engine has no such SA but a 256 key management application has previously indicated (via a PF_KEY 257 SADB_REGISTER message) that it can obtain such SAs, then the Key 258 Engine requests that such an SA be created (via a PF_KEY SADB_ACQUIRE 259 message). When the key management daemon creates a new SA, it places 260 it into the Key Engine for future use. 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282McDonald, et. al. Informational [Page 5] 283 284RFC 2367 PF_KEY Key Management API July 1998 285 286 287 +---------------+ 288 |Key Mgmt Daemon| 289 +---------------+ 290 | | 291 | | 292 | | Applications 293 ======[PF_KEY]====[PF_INET]========================== 294 | | OS Kernel 295 +------------+ +-----------------+ 296 | Key Engine | | TCP/IP, | 297 | or SADB |---| including IPsec | 298 +------------+ | | 299 +-----------------+ 300 | 301 +-----------+ 302 | Network | 303 | Interface | 304 +-----------+ 305 306 Figure 1: Relationship of Key Mgmt to PF_KEY 307 308 For performance reasons, some security protocols (e.g. IP Security) 309 are usually implemented inside the operating system kernel. Other 310 security protocols (e.g. OSPFv2 Cryptographic Authentication) are 311 implemented in trusted privileged applications outside the kernel. 312 Figure 2 shows a trusted, privileged routing daemon using PF_INET to 313 communicate routing information with a remote routing daemon and 314 using PF_KEY to request, obtain, and delete Security Associations 315 used with a routing protocol. 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338McDonald, et. al. Informational [Page 6] 339 340RFC 2367 PF_KEY Key Management API July 1998 341 342 343 +---------------+ 344 |Routing Daemon| 345 +---------------+ 346 | | 347 | | 348 | | Applications 349 ======[PF_KEY]====[PF_INET]========================== 350 | | OS Kernel 351 +------------+ +---------+ 352 | Key Engine | | TCP/IP | 353 | or SADB |---| | 354 +------------+ +---------+ 355 | 356 +-----------+ 357 | Network | 358 | Interface | 359 +-----------+ 360 361 Figure 2: Relationship of Trusted Application to PF_KEY 362 363 When a trusted privileged application is using the Key Engine but 364 implements the security protocol within itself, then operation varies 365 slightly. In this case, the application needing an SA sends a PF_KEY 366 SADB_ACQUIRE message down to the Key Engine, which then either 367 returns an error or sends a similar SADB_ACQUIRE message up to one or 368 more key management applications capable of creating such SAs. As 369 before, the key management daemon stores the SA into the Key Engine. 370 Then, the trusted privileged application uses an SADB_GET message to 371 obtain the SA from the Key Engine. 372 373 In some implementations, policy may be implemented in user-space, 374 even though the actual cryptographic processing takes place in the 375 kernel. Such policy communication between the kernel mechanisms and 376 the user-space policy MAY be implemented by PF_KEY extensions, or 377 other such mechanism. This document does not specify such 378 extensions. A PF_KEY implementation specified by the memo does NOT 379 have to support configuring systemwide policy using PF_KEY. 380 381 Untrusted clients, for example a user's web browser or telnet client, 382 do not need to use PF_KEY. Mechanisms not specified here are used by 383 such untrusted client applications to request security services (e.g. 384 IPsec) from an operating system. For security reasons, only trusted, 385 privileged applications are permitted to open a PF_KEY socket. 386 387 388 389 390 391 392 393 394McDonald, et. al. Informational [Page 7] 395 396RFC 2367 PF_KEY Key Management API July 1998 397 398 3991.3 PF_KEY Socket Definition 400 401 The PF_KEY protocol family (PF_KEY) symbol is defined in 402 <sys/socket.h> in the same manner that other protocol families are 403 defined. PF_KEY does not use any socket addresses. Applications 404 using PF_KEY MUST NOT depend on the availability of a symbol named 405 AF_KEY, but kernel implementations are encouraged to define that 406 symbol for completeness. 407 408 The key management socket is created as follows: 409 410 #include <sys/types.h> 411 #include <sys/socket.h> 412 #include <net/pfkeyv2.h> 413 414 int s; 415 s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2); 416 417 The PF_KEY domain currently supports only the SOCK_RAW socket type. 418 The protocol field MUST be set to PF_KEY_V2, or else EPROTONOSUPPORT 419 will be returned. Only a trusted, privileged process can create a 420 PF_KEY socket. On conventional UNIX systems, a privileged process is 421 a process with an effective userid of zero. On non-MLS proprietary 422 operating systems, the notion of a "privileged process" is 423 implementation-defined. On Compartmented Mode Workstations (CMWs) or 424 other systems that claim to provide Multi-Level Security (MLS), a 425 process MUST have the "key management privilege" in order to open a 426 PF_KEY socket[DIA]. MLS systems that don't currently have such a 427 specific privilege MUST add that special privilege and enforce it 428 with PF_KEY in order to comply and conform with this specification. 429 Some systems, most notably some popular personal computers, do not 430 have the concept of an unprivileged user. These systems SHOULD take 431 steps to restrict the programs allowed to access the PF_KEY API. 432 4331.4 Overview of PF_KEY Messaging Behavior 434 435 A process interacts with the key engine by sending and receiving 436 messages using the PF_KEY socket. Security association information 437 can be inserted into and retrieved from the kernel's security 438 association table using a set of predefined messages. In the normal 439 case, all properly-formed messages sent to the kernel are returned to 440 all open PF_KEY sockets, including the sender. Improperly formed 441 messages will result in errors, and an implementation MUST check for 442 a properly formed message before returning it to the appropriate 443 listeners. Unlike the routing socket, most errors are sent in reply 444 messages, not the errno field when write() or send() fails. PF_KEY 445 message delivery is not guaranteed, especially in cases where kernel 446 or socket buffers are exhausted and messages are dropped. 447 448 449 450McDonald, et. al. Informational [Page 8] 451 452RFC 2367 PF_KEY Key Management API July 1998 453 454 455 Some messages are generated by the operating system to indicate that 456 actions need to be taken, and are not necessarily in response to any 457 message sent down by the user. Such messages are not received by all 458 PF_KEY sockets, but by sockets which have indicated that kernel- 459 originated messages are to be received. These messages are special 460 because of the expected frequency at which they will occur. Also, an 461 implementation may further wish to restrict return messages from the 462 kernel, in cases where not all PF_KEY sockets are in the same trust 463 domain. 464 465 Many of the normal BSD socket calls have undefined behavior on PF_KEY 466 sockets. These include: bind(), connect(), socketpair(), accept(), 467 getpeername(), getsockname(), ioctl(), and listen(). 468 4691.5 Common PF_KEY Operations 470 471 There are two basic ways to add a new Security Association into the 472 kernel. The simplest is to send a single SADB_ADD message, 473 containing all of the SA information, from the application into the 474 kernel's Key Engine. This approach works particularly well with 475 manual key management, which is required for IPsec, and other 476 security protocols. 477 478 The second approach to add a new Security Association into the kernel 479 is for the application to first request a Security Parameters Index 480 (SPI) value from the kernel using the SADB_GETSPI message and then 481 send an SADB_UPDATE message with the complete Security Association 482 data. This second approach works well with key management daemons 483 when the SPI values need to be known before the entire Security 484 Association data is known (e.g. so the SPI value can be indicated to 485 the remote end of the key management session). 486 487 An individual Security Association can be deleted using the 488 SADB_DELETE message. Categories of SAs or the entire kernel SA table 489 can be deleted using the SADB_FLUSH message. 490 491 The SADB_GET message is used by a trusted application-layer process 492 (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 493 SA) from the kernel's Key Engine. 494 495 The kernel or an application-layer can use the SADB_ACQUIRE message 496 to request that a Security Association be created by some 497 application-layer key management process that has registered with the 498 kernel via an SADB_REGISTER message. This ACQUIRE message will have 499 a sequence number associated with it. This sequence number MUST be 500 used by followup SADB_GETSPI, SADB_UPDATE, and SADB_ADD messages, in 501 order to keep track of which request gets its keying material. The 502 sequence number (described below) is similar to a transaction ID in a 503 504 505 506McDonald, et. al. Informational [Page 9] 507 508RFC 2367 PF_KEY Key Management API July 1998 509 510 511 remote procedure call. 512 513 The SADB_EXPIRE message is sent from the kernel to key management 514 applications when the "soft lifetime" or "hard lifetime" of a 515 Security Association has expired. Key management applications should 516 use receipt of a soft lifetime SADB_EXPIRE message as a hint to 517 negotiate a replacement SA so the replacement SA will be ready and in 518 the kernel before it is needed. 519 520 A SADB_DUMP message is also defined, but this is primarily intended 521 for PF_KEY implementor debugging and is not used in ordinary 522 operation of PF_KEY. 523 5241.6 Differences Between PF_KEY and PF_ROUTE 525 526 The following bullets are points of difference between the routing 527 socket and PF_KEY. Programmers who are used to the routing socket 528 semantics will find some differences in PF_KEY. 529 530 * PF_KEY message errors are usually returned in PF_KEY messages 531 instead of causing write() operations to fail and returning the 532 error number in errno. This means that other listeners on a PF_KEY 533 socket can be aware that requests from another process failed, 534 which can be useful for auditing purposes. This also means that 535 applications that fail to read PF_KEY messages cannot do error 536 checking. 537 538 An implementation MAY return the errors EINVAL, ENOMEM, and ENOBUFS 539 by causing write() operations to fail and returning the error 540 number in errno. This is an optimization for common error cases in 541 which it does not make sense for any other process to receive the 542 error. An application MUST NOT depend on such errors being set by 543 the write() call, but it SHOULD check for such errors, and handle 544 them in an appropriate manner. 545 546 * The entire message isn't always reflected in the reply. A SADB_ADD 547 message is an example of this. 548 549 * The PID is not set by the kernel. The process that originates the 550 message MUST set the sadb_msg_pid to its own PID. If the kernel 551 ORIGINATES a message, it MUST set the sadb_msg_pid to 0. A reply 552 to an original message SHOULD have the pid of the original message. 553 (E.g. the kernel's response to an SADB_ADD SHOULD have its pid set 554 to the pid value of the original SADB_ADD message.) 555 556 557 558 559 560 561 562McDonald, et. al. Informational [Page 10] 563 564RFC 2367 PF_KEY Key Management API July 1998 565 566 5671.7 Name Space 568 569 All PF_KEYv2 preprocessor symbols and structure definitions are 570 defined as a result of including the header file <net/pfkeyv2.h>. 571 There is exactly one exception to this rule: the symbol "PF_KEY" (two 572 exceptions if "AF_KEY" is also counted), which is defined as a result 573 of including the header file <sys/socket.h>. All PF_KEYv2 574 preprocessor symbols start with the prefix "SADB_" and all structure 575 names start with "sadb_". There are exactly two exceptions to this 576 rule: the symbol "PF_KEY_V2" and the symbol "PFKEYV2_REVISION". 577 578 The symbol "PFKEYV2_REVISION" is a date-encoded value not unlike 579 certain values defined by POSIX and X/Open. The current value for 580 PFKEYV2_REVISION is 199806L, where 1998 is the year and 06 is the 581 month. 582 583 Inclusion of the file <net/pfkeyv2.h> MUST NOT define symbols or 584 structures in the PF_KEYv2 name space that are not described in this 585 document without the explicit prior permission of the authors. Any 586 symbols or structures in the PF_KEYv2 name space that are not 587 described in this document MUST start with "SADB_X_" or "sadb_x_". An 588 implementation that fails to obey these rules IS NOT COMPLIANT WITH 589 THIS SPECIFICATION and MUST NOT make any claim to be. These rules 590 also apply to any files that might be included as a result of 591 including the file <net/pfkeyv2.h>. This rule provides implementors 592 with some assurance that they will not encounter namespace-related 593 surprises. 594 5951.8 On Manual Keying 596 597 Not unlike the 4.4-Lite BSD PF_ROUTE socket, this interface allows an 598 application full-reign over the security associations in a kernel 599 that implements PF_KEY. A PF_KEY implementation MUST have some sort 600 of manual interface to PF_KEY, which SHOULD allow all of the 601 functionality of the programmatic interface described here. 602 6032. PF_KEY Message Format 604 605 PF_KEY messages consist of a base header followed by additional data 606 fields, some of which may be optional. The format of the additional 607 data is dependent on the type of message. 608 609 PF_KEY messages currently do not mandate any specific ordering for 610 non-network multi-octet fields. Unless otherwise specified (e.g. SPI 611 values), fields MUST be in host-specific byte order. 612 613 614 615 616 617 618McDonald, et. al. Informational [Page 11] 619 620RFC 2367 PF_KEY Key Management API July 1998 621 622 6232.1 Base Message Header Format 624 625 PF_KEY messages consist of the base message header followed by 626 security association specific data whose types and lengths are 627 specified by a generic type-length encoding. 628 629 This base header is shown below, using POSIX types. The fields are 630 arranged primarily for alignment, and where possible, for reasons of 631 clarity. 632 633 struct sadb_msg { 634 uint8_t sadb_msg_version; 635 uint8_t sadb_msg_type; 636 uint8_t sadb_msg_errno; 637 uint8_t sadb_msg_satype; 638 uint16_t sadb_msg_len; 639 uint16_t sadb_msg_reserved; 640 uint32_t sadb_msg_seq; 641 uint32_t sadb_msg_pid; 642 }; 643 /* sizeof(struct sadb_msg) == 16 */ 644 645 sadb_msg_version 646 The version field of this PF_KEY message. This MUST 647 be set to PF_KEY_V2. If this is not set to PF_KEY_V2, 648 the write() call MAY fail and return EINVAL. 649 Otherwise, the behavior is undetermined, given that 650 the application might not understand the formatting 651 of the messages arriving from the kernel. 652 653 sadb_msg_type Identifies the type of message. The valid message 654 types are described later in this document. 655 656 sadb_msg_errno Should be set to zero by the sender. The responder 657 stores the error code in this field if an error has 658 occurred. This includes the case where the responder 659 is in user space. (e.g. user-space negotiation 660 fails, an errno can be returned.) 661 662 sadb_msg_satype Indicates the type of security association(s). Valid 663 Security Association types are declared in the file 664 <net/pfkeyv2.h>. The current set of Security 665 Association types is enumerated later in this 666 document. 667 668 669 670 671 672 673 674McDonald, et. al. Informational [Page 12] 675 676RFC 2367 PF_KEY Key Management API July 1998 677 678 679 sadb_msg_len Contains the total length, in 64-bit words, of all 680 data in the PF_KEY message including the base header 681 length and additional data after the base header, if 682 any. This length includes any padding or extra space 683 that might exist. Unless otherwise stated, all other 684 length fields are also measured in 64-bit words. 685 686 On user to kernel messages, this field MUST be 687 verified against the length of the inbound message. 688 EMSGSIZE MUST be returned if the verification fails. 689 On kernel to user messages, a size mismatch is most 690 likely the result of the user not providing a large 691 enough buffer for the message. In these cases, the 692 user application SHOULD drop the message, but it MAY 693 try and extract what information it can out of the 694 message. 695 696 sadb_msg_reserved 697 Reserved value. It MUST be zeroed by the sender. All 698 fields labeled reserved later in the document have 699 the same semantics as this field. 700 701 sadb_msg_seq Contains the sequence number of this message. This 702 field, along with sadb_msg_pid, MUST be used to 703 uniquely identify requests to a process. The sender 704 is responsible for filling in this field. This 705 responsibility also includes matching the 706 sadb_msg_seq of a request (e.g. SADB_ACQUIRE). 707 708 This field is similar to a transaction ID in a 709 remote procedure call implementation. 710 711 sadb_msg_pid Identifies the process which originated this message, 712 or which process a message is bound for. For 713 example, if process id 2112 sends an SADB_UPDATE 714 message to the kernel, the process MUST set this 715 field to 2112 and the kernel will set this field 716 to 2112 in its reply to that SADB_UPDATE 717 message. This field, along with sadb_msg_seq, can 718 be used to uniquely identify requests to a 719 process. 720 721 It is currently assumed that a 32-bit quantity will 722 hold an operating system's process ID space. 723 724 725 726 727 728 729 730McDonald, et. al. Informational [Page 13] 731 732RFC 2367 PF_KEY Key Management API July 1998 733 734 7352.2 Alignment of Headers and Extension Headers 736 737 The base message header is a multiple of 64 bits and fields after it 738 in memory will be 64 bit aligned if the base itself is 64 bit 739 aligned. Some of the subsequent extension headers have 64 bit fields 740 in them, and as a consequence need to be 64 bit aligned in an 741 environment where 64 bit quantities need to be 64 bit aligned. 742 743 The basic unit of alignment and length in PF_KEY Version 2 is 64 744 bits. Therefore: 745 746 * All extension headers, inclusive of the sadb_ext overlay fields, 747 MUST be a multiple of 64 bits long. 748 749 * All variable length data MUST be padded appropriately such that 750 its length in a message is a multiple of 64 bits. 751 752 * All length fields are, unless otherwise specified, in units of 753 64 bits. 754 755 * Implementations may safely access quantities of between 8 and 64 756 bits directly within a message without risk of alignment faults. 757 758 All PF_KEYv2 structures are packed and already have all intended 759 padding. Implementations MUST NOT insert any extra fields, including 760 hidden padding, into any structure in this document. This forbids 761 implementations from "extending" or "enhancing" existing headers 762 without changing the extension header type. As a guard against such 763 insertion of silent padding, each structure in this document is 764 labeled with its size in bytes. The size of these structures in an 765 implementation MUST match the size listed. 766 7672.3 Additional Message Fields 768 769 The additional data following the base header consists of various 770 length-type-values fields. The first 32-bits are of a constant form: 771 772 struct sadb_ext { 773 uint16_t sadb_ext_len; 774 uint16_t sadb_ext_type; 775 }; 776 /* sizeof(struct sadb_ext) == 4 */ 777 778 sadb_ext_len Length of the extension header in 64 bit words, 779 inclusive. 780 781 782 783 784 785 786McDonald, et. al. Informational [Page 14] 787 788RFC 2367 PF_KEY Key Management API July 1998 789 790 791 sadb_ext_type The type of extension header that follows. Values for 792 this field are detailed later. The value zero is 793 reserved. 794 795 Types of extension headers include: Association, Lifetime(s), 796 Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and 797 Supported. There MUST be only one instance of a extension type in a 798 message. (e.g. Base, Key, Lifetime, Key is forbidden). An EINVAL 799 will be returned if there are duplicate extensions within a message. 800 Implementations MAY enforce ordering of extensions in the order 801 presented in the EXTENSION HEADER VALUES section. 802 803 If an unknown extension type is encountered, it MUST be ignored. 804 Applications using extension headers not specified in this document 805 MUST be prepared to work around other system components not 806 processing those headers. Likewise, if an application encounters an 807 unknown extension from the kernel, it must be prepared to work around 808 it. Also, a kernel that generates extra extension header types MUST 809 NOT _depend_ on applications also understanding extra extension 810 header types. 811 812 All extension definitions include these two fields (len and exttype) 813 because they are instances of a generic extension (not unlike 814 sockaddr_in and sockaddr_in6 are instances of a generic sockaddr). 815 The sadb_ext header MUST NOT ever be present in a message without at 816 least four bytes of extension header data following it, and, 817 therefore, there is no problem with it being only four bytes long. 818 819 All extensions documented in this section MUST be implemented by a 820 PF_KEY implementation. 821 8222.3.1 Association Extension 823 824 The Association extension specifies data specific to a single 825 security association. The only times this extension is not present is 826 when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being 827 passed and on the SADB_ACQUIRE message. 828 829 struct sadb_sa { 830 uint16_t sadb_sa_len; 831 uint16_t sadb_sa_exttype; 832 uint32_t sadb_sa_spi; 833 uint8_t sadb_sa_replay; 834 uint8_t sadb_sa_state; 835 uint8_t sadb_sa_auth; 836 uint8_t sadb_sa_encrypt; 837 uint32_t sadb_sa_flags; 838 }; 839 840 841 842McDonald, et. al. Informational [Page 15] 843 844RFC 2367 PF_KEY Key Management API July 1998 845 846 847 /* sizeof(struct sadb_sa) == 16 */ 848 849 sadb_sa_spi The Security Parameters Index value for the security 850 association. Although this is a 32-bit field, some 851 types of security associations might have an SPI or 852 key identifier that is less than 32-bits long. In 853 this case, the smaller value shall be stored in the 854 least significant bits of this field and the unneeded 855 bits shall be zero. This field MUST be in network 856 byte order. 857 858 sadb_sa_replay The size of the replay window, if not zero. If zero, 859 then no replay window is in use. 860 861 sadb_sa_state The state of the security association. The currently 862 defined states are described later in this document. 863 864 sadb_sa_auth The authentication algorithm to be used with this 865 security association. The valid authentication 866 algorithms are described later in this document. A 867 value of zero means that no authentication is used 868 for this security association. 869 870 sadb_sa_encrypt The encryption algorithm to be used with this 871 security association. The valid encryption algorithms 872 are described later in this document. A value of zero 873 means that no encryption is used for this security 874 association. 875 876 sadb_sa_flags A bitmap of options defined for the security 877 association. The currently defined flags are 878 described later in this document. 879 880 The kernel MUST check these values where appropriate. For example, 881 IPsec AH with no authentication algorithm is probably an error. 882 883 When used with some messages, the values in some fields in this 884 header should be ignored. 885 8862.3.2 Lifetime Extension 887 888 The Lifetime extension specifies one or more lifetime variants for 889 this security association. If no Lifetime extension is present the 890 association has an infinite lifetime. An association SHOULD have a 891 lifetime of some sort associated with it. Lifetime variants come in 892 three varieties, HARD - indicating the hard-limit expiration, SOFT - 893 indicating the soft-limit expiration, and CURRENT - indicating the 894 current state of a given security association. The Lifetime 895 896 897 898McDonald, et. al. Informational [Page 16] 899 900RFC 2367 PF_KEY Key Management API July 1998 901 902 903 extension looks like: 904 905 struct sadb_lifetime { 906 uint16_t sadb_lifetime_len; 907 uint16_t sadb_lifetime_exttype; 908 uint32_t sadb_lifetime_allocations; 909 uint64_t sadb_lifetime_bytes; 910 uint64_t sadb_lifetime_addtime; 911 uint64_t sadb_lifetime_usetime; 912 }; 913 /* sizeof(struct sadb_lifetime) == 32 */ 914 915 sadb_lifetime_allocations 916 For CURRENT, the number of different connections, 917 endpoints, or flows that the association has been 918 allocated towards. For HARD and SOFT, the number of 919 these the association may be allocated towards 920 before it expires. The concept of a connection, 921 flow, or endpoint is system specific. 922 923 sadb_lifetime_bytes 924 For CURRENT, how many bytes have been processed 925 using this security association. For HARD and SOFT, 926 the number of bytes that may be processed using 927 this security association before it expires. 928 929 sadb_lifetime_addtime 930 For CURRENT, the time, in seconds, when the 931 association was created. For HARD and SOFT, the 932 number of seconds after the creation of the 933 association until it expires. 934 935 For such time fields, it is assumed that 64-bits is 936 sufficiently large to hold the POSIX time_t value. 937 If this assumption is wrong, this field will have to 938 be revisited. 939 940 sadb_lifetime_usetime 941 For CURRENT, the time, in seconds, when association 942 was first used. For HARD and SOFT, the number of 943 seconds after the first use of the association until 944 it expires. 945 946 The semantics of lifetimes are inclusive-OR, first-to-expire. This 947 means that if values for bytes and time, or multiple times, are 948 passed in, the first of these values to be reached will cause a 949 lifetime expiration. 950 951 952 953 954McDonald, et. al. Informational [Page 17] 955 956RFC 2367 PF_KEY Key Management API July 1998 957 958 9592.3.3 Address Extension 960 961 The Address extension specifies one or more addresses that are 962 associated with a security association. Address extensions for both 963 source and destination MUST be present when an Association extension 964 is present. The format of an Address extension is: 965 966 struct sadb_address { 967 uint16_t sadb_address_len; 968 uint16_t sadb_address_exttype; 969 uint8_t sadb_address_proto; 970 uint8_t sadb_address_prefixlen; 971 uint16_t sadb_address_reserved; 972 }; 973 /* sizeof(struct sadb_address) == 8 */ 974 975 /* followed by some form of struct sockaddr */ 976 977 The sockaddr structure SHOULD conform to the sockaddr structure of 978 the system implementing PF_KEY. If the system has an sa_len field, so 979 SHOULD the sockaddrs in the message. If the system has NO sa_len 980 field, the sockaddrs SHOULD NOT have an sa_len field. All non-address 981 information in the sockaddrs, such as sin_zero for AF_INET sockaddrs, 982 and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out. The 983 zeroing of ports (e.g. sin_port and sin6_port) MUST be done for all 984 messages except for originating SADB_ACQUIRE messages, which SHOULD 985 fill them in with ports from the relevant TCP or UDP session which 986 generates the ACQUIRE message. If the ports are non-zero, then the 987 sadb_address_proto field, normally zero, MUST be filled in with the 988 transport protocol's number. If the sadb_address_prefixlen is non- 989 zero, then the address has a prefix (often used in KM access control 990 decisions), with length specified in sadb_address_prefixlen. These 991 additional fields may be useful to KM applications. 992 993 The SRC and DST addresses for a security association MUST be in the 994 same protocol family and MUST always be present or absent together in 995 a message. The PROXY address MAY be in a different protocol family, 996 and for most security protocols, represents an actual originator of a 997 packet. (For example, the inner-packets's source address in a 998 tunnel.) 999 1000 The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY) 1001 address. The DST address can be any valid destination address 1002 (unicast, multicast, or even broadcast). The PROXY address SHOULD be 1003 a unicast address (there are experimental security protocols where 1004 PROXY semantics may be different than described above). 1005 1006 1007 1008 1009 1010McDonald, et. al. Informational [Page 18] 1011 1012RFC 2367 PF_KEY Key Management API July 1998 1013 1014 10152.3.4 Key Extension 1016 1017 The Key extension specifies one or more keys that are associated with 1018 a security association. A Key extension will not always be present 1019 with messages, because of security risks. The format of a Key 1020 extension is: 1021 1022 struct sadb_key { 1023 uint16_t sadb_key_len; 1024 uint16_t sadb_key_exttype; 1025 uint16_t sadb_key_bits; 1026 uint16_t sadb_key_reserved; 1027 }; 1028 /* sizeof(struct sadb_key) == 8 */ 1029 1030 /* followed by the key data */ 1031 1032 sadb_key_bits The length of the valid key data, in bits. A value of 1033 zero in sadb_key_bits MUST cause an error. 1034 1035 The key extension comes in two varieties. The AUTH version is used 1036 with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT 1037 version is used with encryption keys (e.g. IPsec ESP). PF_KEY deals 1038 only with fully formed cryptographic keys, not with "raw key 1039 material". For example, when ISAKMP/Oakley is in use, the key 1040 management daemon is always responsible for transforming the result 1041 of the Diffie-Hellman computation into distinct fully formed keys 1042 PRIOR to sending those keys into the kernel via PF_KEY. This rule is 1043 made because PF_KEY is designed to support multiple security 1044 protocols (not just IP Security) and also multiple key management 1045 schemes including manual keying, which does not have the concept of 1046 "raw key material". A clean, protocol-independent interface is 1047 important for portability to different operating systems as well as 1048 for portability to different security protocols. 1049 1050 If an algorithm defines its key to include parity bits (e.g. DES) 1051 then the key used with PF_KEY MUST also include those parity bits. 1052 For example, this means that a single DES key is always a 64-bit 1053 quantity. 1054 1055 When a particular security protocol only requires one authentication 1056 and/or one encryption key, the fully formed key is transmitted using 1057 the appropriate key extension. When a particular security protocol 1058 requires more than one key for the same function (e.g. Triple-DES 1059 using 2 or 3 keys, and asymmetric algorithms), then those two fully 1060 formed keys MUST be concatenated together in the order used for 1061 outbound packet processing. In the case of multiple keys, the 1062 algorithm MUST be able to determine the lengths of the individual 1063 1064 1065 1066McDonald, et. al. Informational [Page 19] 1067 1068RFC 2367 PF_KEY Key Management API July 1998 1069 1070 1071 keys based on the information provided. The total key length (when 1072 combined with knowledge of the algorithm in use) usually provides 1073 sufficient information to make this determination. 1074 1075 Keys are always passed through the PF_KEY interface in the order that 1076 they are used for outbound packet processing. For inbound processing, 1077 the correct order that keys are used might be different from this 1078 canonical concatenation order used with the PF_KEY interface. It is 1079 the responsibility of the implementation to use the keys in the 1080 correct order for both inbound and outbound processing. 1081 1082 For example, consider a pair of nodes communicating unicast using an 1083 ESP three-key Triple-DES Security Association. Both the outbound SA 1084 on the sender node, and the inbound SA on the receiver node will 1085 contain key-A, followed by key-B, followed by key-C in their 1086 respective ENCRYPT key extensions. The outbound SA will use key-A 1087 first, followed by key-B, then key-C when encrypting. The inbound SA 1088 will use key-C, followed by key-B, then key-A when decrypting. 1089 (NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.) 1090 The canonical ordering of key-A, key-B, key-C is used for 3DES, and 1091 should be documented. The order of "encryption" is the canonical 1092 order for this example. [Sch96] 1093 1094 The key data bits are arranged most-significant to least significant. 1095 For example, a 22-bit key would take up three octets, with the least 1096 significant two bits not containing key material. Five additional 1097 octets would then be used for padding to the next 64-bit boundary. 1098 1099 While not directly related to PF_KEY, there is a user interface issue 1100 regarding odd-digit hexadecimal representation of keys. Consider the 1101 example of the 16-bit number: 1102 1103 0x123 1104 1105 That will require two octets of storage. In the absence of other 1106 information, however, unclear whether the value shown is stored as: 1107 1108 01 23 OR 12 30 1109 1110 It is the opinion of the authors that the former (0x123 == 0x0123) is 1111 the better way to interpret this ambiguity. Extra information (for 1112 example, specifying 0x0123 or 0x1230, or specifying that this is only 1113 a twelve-bit number) would solve this problem. 1114 1115 1116 1117 1118 1119 1120 1121 1122McDonald, et. al. Informational [Page 20] 1123 1124RFC 2367 PF_KEY Key Management API July 1998 1125 1126 11272.3.5 Identity Extension 1128 1129 The Identity extension contains endpoint identities. This 1130 information is used by key management to select the identity 1131 certificate that is used in negotiations. This information may also 1132 be provided by a kernel to network security aware applications to 1133 identify the remote entity, possibly for access control purposes. If 1134 this extension is not present, key management MUST assume that the 1135 addresses in the Address extension are the only identities for this 1136 Security Association. The Identity extension looks like: 1137 1138 struct sadb_ident { 1139 uint16_t sadb_ident_len; 1140 uint16_t sadb_ident_exttype; 1141 uint16_t sadb_ident_type; 1142 uint16_t sadb_ident_reserved; 1143 uint64_t sadb_ident_id; 1144 }; 1145 /* sizeof(struct sadb_ident) == 16 */ 1146 1147 /* followed by the identity string, if present */ 1148 1149 sadb_ident_type The type of identity information that follows. 1150 Currently defined identity types are described later 1151 in this document. 1152 1153 sadb_ident_id An identifier used to aid in the construction of an 1154 identity string if none is present. A POSIX user id 1155 value is one such identifier that will be used in this 1156 field. Use of this field is described later in this 1157 document. 1158 1159 A C string containing a textual representation of the identity 1160 information optionally follows the sadb_ident extension. The format 1161 of this string is determined by the value in sadb_ident_type, and is 1162 described later in this document. 1163 11642.3.6 Sensitivity Extension 1165 1166 The Sensitivity extension contains security labeling information for 1167 a security association. If this extension is not present, no 1168 sensitivity-related data can be obtained from this security 1169 association. If this extension is present, then the need for 1170 explicit security labeling on the packet is obviated. 1171 1172 struct sadb_sens { 1173 uint16_t sadb_sens_len; 1174 uint16_t sadb_sens_exttype; 1175 1176 1177 1178McDonald, et. al. Informational [Page 21] 1179 1180RFC 2367 PF_KEY Key Management API July 1998 1181 1182 1183 uint32_t sadb_sens_dpd; 1184 uint8_t sadb_sens_sens_level; 1185 uint8_t sadb_sens_sens_len; 1186 uint8_t sadb_sens_integ_level; 1187 uint8_t sadb_sens_integ_len; 1188 uint32_t sadb_sens_reserved; 1189 }; 1190 /* sizeof(struct sadb_sens) == 16 */ 1191 1192 /* followed by: 1193 uint64_t sadb_sens_bitmap[sens_len]; 1194 uint64_t sadb_integ_bitmap[integ_len]; */ 1195 1196 sadb_sens_dpd Describes the protection domain, which allows 1197 interpretation of the levels and compartment 1198 bitmaps. 1199 sadb_sens_sens_level 1200 The sensitivity level. 1201 sadb_sens_sens_len 1202 The length, in 64 bit words, of the sensitivity 1203 bitmap. 1204 sadb_sens_integ_level 1205 The integrity level. 1206 sadb_sens_integ_len 1207 The length, in 64 bit words, of the integrity 1208 bitmap. 1209 1210 This sensitivity extension is designed to support the Bell-LaPadula 1211 [BL74] security model used in compartmented-mode or multi-level 1212 secure systems, the Clark-Wilson [CW87] commercial security model, 1213 and/or the Biba integrity model [Biba77]. These formal models can be 1214 used to implement a wide variety of security policies. The definition 1215 of a particular security policy is outside the scope of this 1216 document. Each of the bitmaps MUST be padded to a 64-bit boundary if 1217 they are not implicitly 64-bit aligned. 1218 12192.3.7 Proposal Extension 1220 1221 The Proposal extension contains a "proposed situation" of algorithm 1222 preferences. It looks like: 1223 1224 struct sadb_prop { 1225 uint16_t sadb_prop_len; 1226 uint16_t sadb_prop_exttype; 1227 uint8_t sadb_prop_replay; 1228 uint8_t sadb_prop_reserved[3]; 1229 }; 1230 /* sizeof(struct sadb_prop) == 8 */ 1231 1232 1233 1234McDonald, et. al. Informational [Page 22] 1235 1236RFC 2367 PF_KEY Key Management API July 1998 1237 1238 1239 /* followed by: 1240 struct sadb_comb sadb_combs[(sadb_prop_len * 1241 sizeof(uint64_t) - sizeof(struct sadb_prop)) / 1242 sizeof(struct sadb_comb)]; */ 1243 1244 Following the header is a list of proposed parameter combinations in 1245 preferential order. The values in these fields have the same 1246 definition as the fields those values will move into if the 1247 combination is chosen. 1248 1249 NOTE: Some algorithms in some security protocols will have 1250 variable IV lengths per algorithm. Variable length IVs 1251 are not supported by PF_KEY v2. If they were, however, 1252 proposed IV lengths would go in the Proposal Extension. 1253 1254 These combinations look like: 1255 1256 struct sadb_comb { 1257 uint8_t sadb_comb_auth; 1258 uint8_t sadb_comb_encrypt; 1259 uint16_t sadb_comb_flags; 1260 uint16_t sadb_comb_auth_minbits; 1261 uint16_t sadb_comb_auth_maxbits; 1262 uint16_t sadb_comb_encrypt_minbits; 1263 uint16_t sadb_comb_encrypt_maxbits; 1264 uint32_t sadb_comb_reserved; 1265 uint32_t sadb_comb_soft_allocations; 1266 uint32_t sadb_comb_hard_allocations; 1267 uint64_t sadb_comb_soft_bytes; 1268 uint64_t sadb_comb_hard_bytes; 1269 uint64_t sadb_comb_soft_addtime; 1270 uint64_t sadb_comb_hard_addtime; 1271 uint64_t sadb_comb_soft_usetime; 1272 uint64_t sadb_comb_hard_usetime; 1273 }; 1274 1275 /* sizeof(struct sadb_comb) == 72 */ 1276 1277 sadb_comb_auth If this combination is accepted, this will be the 1278 value of sadb_sa_auth. 1279 1280 sadb_comb_encrypt 1281 If this combination is accepted, this will be the 1282 value of sadb_sa_encrypt. 1283 1284 1285 1286 1287 1288 1289 1290McDonald, et. al. Informational [Page 23] 1291 1292RFC 2367 PF_KEY Key Management API July 1998 1293 1294 1295 sadb_comb_auth_minbits; 1296 sadb_comb_auth_maxbits; 1297 The minimum and maximum acceptable authentication 1298 key lengths, respectably, in bits. If sadb_comb_auth 1299 is zero, both of these values MUST be zero. If 1300 sadb_comb_auth is nonzero, both of these values MUST 1301 be nonzero. If this combination is accepted, a value 1302 between these (inclusive) will be stored in the 1303 sadb_key_bits field of KEY_AUTH. The minimum MUST 1304 NOT be greater than the maximum. 1305 1306 sadb_comb_encrypt_minbits; 1307 sadb_comb_encrypt_maxbits; 1308 The minimum and maximum acceptable encryption key 1309 lengths, respectably, in bits. If sadb_comb_encrypt 1310 is zero, both of these values MUST be zero. If 1311 sadb_comb_encrypt is nonzero, both of these values 1312 MUST be nonzero. If this combination is accepted, a 1313 value between these (inclusive) will be stored in 1314 the sadb_key_bits field of KEY_ENCRYPT. The minimum 1315 MUST NOT be greater than the maximum. 1316 1317 sadb_comb_soft_allocations 1318 sadb_comb_hard_allocations 1319 If this combination is accepted, these are proposed 1320 values of sadb_lifetime_allocations in the SOFT and 1321 HARD lifetimes, respectively. 1322 1323 sadb_comb_soft_bytes 1324 sadb_comb_hard_bytes 1325 If this combination is accepted, these are proposed 1326 values of sadb_lifetime_bytes in the SOFT and HARD 1327 lifetimes, respectively. 1328 1329 sadb_comb_soft_addtime 1330 sadb_comb_hard_addtime 1331 If this combination is accepted, these are proposed 1332 values of sadb_lifetime_addtime in the SOFT and HARD 1333 lifetimes, respectively. 1334 1335 sadb_comb_soft_usetime 1336 sadb_comb_hard_usetime 1337 If this combination is accepted, these are proposed 1338 values of sadb_lifetime_usetime in the SOFT and HARD 1339 lifetimes, respectively. 1340 1341 1342 1343 1344 1345 1346McDonald, et. al. Informational [Page 24] 1347 1348RFC 2367 PF_KEY Key Management API July 1998 1349 1350 1351 Each combination has an authentication and encryption algorithm, 1352 which may be 0, indicating none. A combination's flags are the same 1353 as the flags in the Association extension. The minimum and maximum 1354 key lengths (which are in bits) are derived from possible a priori 1355 policy decisions, along with basic properties of the algorithm. 1356 Lifetime attributes are also included in a combination, as some 1357 algorithms may know something about their lifetimes and can suggest 1358 lifetime limits. 1359 13602.3.8 Supported Algorithms Extension 1361 1362 The Supported Algorithms extension contains a list of all algorithms 1363 supported by the system. This tells key management what algorithms it 1364 can negotiate. Available authentication algorithms are listed in the 1365 SUPPORTED_AUTH extension and available encryption algorithms are 1366 listed in the SUPPORTED_ENCRYPT extension. The format of these 1367 extensions is: 1368 1369 struct sadb_supported { 1370 uint16_t sadb_supported_len; 1371 uint16_t sadb_supported_exttype; 1372 uint32_t sadb_supported_reserved; 1373 }; 1374 /* sizeof(struct sadb_supported) == 8 */ 1375 1376 /* followed by: 1377 struct sadb_alg sadb_algs[(sadb_supported_len * 1378 sizeof(uint64_t) - sizeof(struct sadb_supported)) / 1379 sizeof(struct sadb_alg)]; */ 1380 1381 This header is followed by one or more algorithm descriptions. An 1382 algorithm description looks like: 1383 1384 struct sadb_alg { 1385 uint8_t sadb_alg_id; 1386 uint8_t sadb_alg_ivlen; 1387 uint16_t sadb_alg_minbits; 1388 uint16_t sadb_alg_maxbits; 1389 uint16_t sadb_alg_reserved; 1390 }; 1391 /* sizeof(struct sadb_alg) == 8 */ 1392 1393 sadb_alg_id The algorithm identification value for this 1394 algorithm. This is the value that is stored in 1395 sadb_sa_auth or sadb_sa_encrypt if this algorithm is 1396 selected. 1397 1398 1399 1400 1401 1402McDonald, et. al. Informational [Page 25] 1403 1404RFC 2367 PF_KEY Key Management API July 1998 1405 1406 1407 sadb_alg_ivlen The length of the initialization vector to be used 1408 for the algorithm. If an IV is not needed, this 1409 value MUST be set to zero. 1410 1411 sadb_alg_minbits 1412 The minimum acceptable key length, in bits. A value 1413 of zero is invalid. 1414 1415 sadb_alg_maxbits 1416 The maximum acceptable key length, in bits. A value 1417 of zero is invalid. The minimum MUST NOT be greater 1418 than the maximum. 1419 14202.3.9 SPI Range Extension 1421 1422 One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI 1423 values. This extension performs such a function. 1424 1425 struct sadb_spirange { 1426 uint16_t sadb_spirange_len; 1427 uint16_t sadb_spirange_exttype; 1428 uint32_t sadb_spirange_min; 1429 uint32_t sadb_spirange_max; 1430 uint32_t sadb_spirange_reserved; 1431 }; 1432 /* sizeof(struct sadb_spirange) == 16 */ 1433 1434 sadb_spirange_min 1435 The minimum acceptable SPI value. 1436 1437 sadb_spirange_max 1438 The maximum acceptable SPI value. The maximum MUST 1439 be greater than or equal to the minimum. 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458McDonald, et. al. Informational [Page 26] 1459 1460RFC 2367 PF_KEY Key Management API July 1998 1461 1462 14632.4 Illustration of Message Layout 1464 1465 The following shows how the octets are laid out in a PF_KEY message. 1466 Optional fields are indicated as such. 1467 1468 The base header is as follows: 1469 1470 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 1471 +---------------+---------------+---------------+---------------+ 1472 | ...version | sadb_msg_type | sadb_msg_errno| ...msg_satype | 1473 +---------------+---------------+---------------+---------------+ 1474 | sadb_msg_len | sadb_msg_reserved | 1475 +---------------+---------------+---------------+---------------+ 1476 | sadb_msg_seq | 1477 +---------------+---------------+---------------+---------------+ 1478 | sadb_msg_pid | 1479 +---------------+---------------+---------------+---------------+ 1480 1481 The base header may be followed by one or more of the following 1482 extension fields, depending on the values of various base header 1483 fields. The following fields are ordered such that if they appear, 1484 they SHOULD appear in the order presented below. 1485 1486 An extension field MUST not be repeated. If there is a situation 1487 where an extension MUST be repeated, it should be brought to the 1488 attention of the authors. 1489 1490 The Association extension 1491 1492 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 1493 +---------------+---------------+---------------+---------------+ 1494 | sadb_sa_len | sadb_sa_exttype | 1495 +---------------+---------------+---------------+---------------+ 1496 | sadb_sa_spi | 1497 +---------------+---------------+---------------+---------------+ 1498 | ...replay | sadb_sa_state | sadb_sa_auth |sadb_sa_encrypt| 1499 +---------------+---------------+---------------+---------------+ 1500 | sadb_sa_flags | 1501 +---------------+---------------+---------------+---------------+ 1502 1503 The Lifetime extension 1504 1505 +---------------+---------------+---------------+---------------+ 1506 | sadb_lifetime_len | sadb_lifetime_exttype | 1507 +---------------+---------------+---------------+---------------+ 1508 | sadb_lifetime_allocations | 1509 +---------------+---------------+---------------+---------------+ 1510 1511 1512 1513 1514McDonald, et. al. Informational [Page 27] 1515 1516RFC 2367 PF_KEY Key Management API July 1998 1517 1518 1519 +---------------+---------------+---------------+---------------+ 1520 | sadb_lifetime_bytes | 1521 | (64 bits) | 1522 +---------------+---------------+---------------+---------------+ 1523 | sadb_lifetime_addtime | 1524 | (64 bits) | 1525 +---------------+---------------+---------------+---------------+ 1526 | sadb_lifetime_usetime | 1527 | (64 bits) | 1528 +---------------+---------------+---------------+---------------+ 1529 1530 The Address extension 1531 1532 +---------------+---------------+---------------+---------------+ 1533 | sadb_address_len | sadb_address_exttype | 1534 +---------------+---------------+---------------+---------------+ 1535 | _address_proto| ..._prefixlen | sadb_address_reserved | 1536 +---------------+---------------+---------------+---------------+ 1537 > Some form of 64-bit aligned struct sockaddr goes here. < 1538 +---------------+---------------+---------------+---------------+ 1539 1540 The Key extension 1541 1542 +---------------+---------------+---------------+---------------+ 1543 | sadb_key_len | sadb_key_exttype | 1544 +---------------+---------------+---------------+---------------+ 1545 | sadb_key_bits | sadb_key_reserved | 1546 +---------------+---------------+---------------+---------------+ 1547 > A key, padded to 64-bits, most significant bits to least. > 1548 +---------------+---------------+---------------+---------------+ 1549 1550 The Identity extension 1551 1552 +---------------+---------------+---------------+---------------+ 1553 | sadb_ident_len | sadb_ident_exttype | 1554 +---------------+---------------+---------------+---------------+ 1555 | sadb_ident_type | sadb_ident_reserved | 1556 +---------------+---------------+---------------+---------------+ 1557 | sadb_ident_id | 1558 | (64 bits) | 1559 +---------------+---------------+---------------+---------------+ 1560 > A null-terminated C-string which MUST be padded out for > 1561 < 64-bit alignment. < 1562 +---------------+---------------+---------------+---------------+ 1563 1564 1565 1566 1567 1568 1569 1570McDonald, et. al. Informational [Page 28] 1571 1572RFC 2367 PF_KEY Key Management API July 1998 1573 1574 1575 The Sensitivity extension 1576 1577 +---------------+---------------+---------------+---------------+ 1578 | sadb_sens_len | sadb_sens_exttype | 1579 +---------------+---------------+---------------+---------------+ 1580 | sadb_sens_dpd | 1581 +---------------+---------------+---------------+---------------+ 1582 | ...sens_level | ...sens_len |..._integ_level| ..integ_len | 1583 +---------------+---------------+---------------+---------------+ 1584 | sadb_sens_reserved | 1585 +---------------+---------------+---------------+---------------+ 1586 > The sensitivity bitmap, followed immediately by the < 1587 < integrity bitmap, each is an array of uint64_t. > 1588 +---------------+---------------+---------------+---------------+ 1589 1590 The Proposal extension 1591 1592 +---------------+---------------+---------------+---------------+ 1593 | sadb_prop_len | sadb_prop_exttype | 1594 +---------------+---------------+---------------+---------------+ 1595 |...prop_replay | sadb_prop_reserved | 1596 +---------------+---------------+---------------+---------------+ 1597 > One or more combinations, specified as follows... < 1598 +---------------+---------------+---------------+---------------+ 1599 1600 Combination 1601 +---------------+---------------+---------------+---------------+ 1602 |sadb_comb_auth |sadb_comb_encr | sadb_comb_flags | 1603 +---------------+---------------+---------------+---------------+ 1604 | sadb_comb_auth_minbits | sadb_comb_auth_maxbits | 1605 +---------------+---------------+---------------+---------------+ 1606 | sadb_comb_encrypt_minbits | sadb_comb_encrypt_maxbits | 1607 +---------------+---------------+---------------+---------------+ 1608 | sadb_comb_reserved | 1609 +---------------+---------------+---------------+---------------+ 1610 | sadb_comb_soft_allocations | 1611 +---------------+---------------+---------------+---------------+ 1612 | sadb_comb_hard_allocations | 1613 +---------------+---------------+---------------+---------------+ 1614 | sadb_comb_soft_bytes | 1615 | (64 bits) | 1616 +---------------+---------------+---------------+---------------+ 1617 | sadb_comb_hard_bytes | 1618 | (64 bits) | 1619 +---------------+---------------+---------------+---------------+ 1620 | sadb_comb_soft_addtime | 1621 | (64 bits) | 1622 +---------------+---------------+---------------+---------------+ 1623 1624 1625 1626McDonald, et. al. Informational [Page 29] 1627 1628RFC 2367 PF_KEY Key Management API July 1998 1629 1630 1631 +---------------+---------------+---------------+---------------+ 1632 | sadb_comb_hard_addtime | 1633 | (64 bits) | 1634 +---------------+---------------+---------------+---------------+ 1635 | sadb_comb_soft_usetime | 1636 | (64 bits) | 1637 +---------------+---------------+---------------+---------------+ 1638 | sadb_comb_hard_usetime | 1639 | (64 bits) | 1640 +---------------+---------------+---------------+---------------+ 1641 1642 The Supported Algorithms extension 1643 1644 +---------------+---------------+---------------+---------------+ 1645 | sadb_supported_len | sadb_supported_exttype | 1646 +---------------+---------------+---------------+---------------+ 1647 | sadb_supported_reserved | 1648 +---------------+---------------+---------------+---------------+ 1649 1650 Followed by one or more Algorithm Descriptors 1651 1652 +---------------+---------------+---------------+---------------+ 1653 | sadb_alg_id | sadb_alg_ivlen| sadb_alg_minbits | 1654 +---------------+---------------+---------------+---------------+ 1655 | sadb_alg_maxbits | sadb_alg_reserved | 1656 +---------------+---------------+---------------+---------------+ 1657 1658 The SPI Range extension 1659 1660 +---------------+---------------+---------------+---------------+ 1661 | sadb_spirange_len | sadb_spirange_exttype | 1662 +---------------+---------------+---------------+---------------+ 1663 | sadb_spirange_min | 1664 +---------------+---------------+---------------+---------------+ 1665 | sadb_spirange_max | 1666 +---------------+---------------+---------------+---------------+ 1667 | sadb_spirange_reserved | 1668 +---------------+---------------+---------------+---------------+ 1669 16703 Symbolic Names 1671 1672 This section defines various symbols used with PF_KEY and the 1673 semantics associated with each symbol. Applications MUST use the 1674 symbolic names in order to be portable. The numeric definitions 1675 shown are for illustrative purposes, unless explicitly stated 1676 otherwise. The numeric definition MAY vary on other systems. The 1677 symbolic name MUST be kept the same for all conforming 1678 implementations. 1679 1680 1681 1682McDonald, et. al. Informational [Page 30] 1683 1684RFC 2367 PF_KEY Key Management API July 1998 1685 1686 16873.1 Message Types 1688 1689 The following message types are used with PF_KEY. These are defined 1690 in the file <net/pfkeyv2.h>. 1691 1692 #define SADB_RESERVED 0 1693 #define SADB_GETSPI 1 1694 #define SADB_UPDATE 2 1695 #define SADB_ADD 3 1696 #define SADB_DELETE 4 1697 #define SADB_GET 5 1698 #define SADB_ACQUIRE 6 1699 #define SADB_REGISTER 7 1700 #define SADB_EXPIRE 8 1701 #define SADB_FLUSH 9 1702 1703 #define SADB_DUMP 10 /* not used normally */ 1704 1705 #define SADB_MAX 10 1706 1707 Each message has a behavior. A behavior is defined as where the 1708 initial message travels (e.g. user to kernel), and what subsequent 1709 actions are expected to take place. Contents of messages are 1710 illustrated as: 1711 1712 <base, REQUIRED EXTENSION, REQ., (OPTIONAL EXT.,) (OPT)> 1713 1714 The SA extension is sometimes used only for its SPI field. If all 1715 other fields MUST be ignored, this is represented by "SA(*)". 1716 1717 The lifetime extensions are represented with one to three letters 1718 after the word "lifetime," representing (H)ARD, (S)OFT, and 1719 (C)URRENT. 1720 1721 The address extensions are represented with one to three letters 1722 after the word "address," representing (S)RC, (D)ST, (P)ROXY. 1723 1724 NOTE: Some security association types do not use a source 1725 address for SA identification, where others do. This may 1726 cause EEXIST errors for some SA types where others do not 1727 report collisions. It is expected that application 1728 authors know enough about the underlying security 1729 association types to understand these differences. 1730 1731 The key extensions are represented with one or two letters after the 1732 word "key," representing (A)UTH and (E)NCRYPT. 1733 1734 1735 1736 1737 1738McDonald, et. al. Informational [Page 31] 1739 1740RFC 2367 PF_KEY Key Management API July 1998 1741 1742 1743 The identity extensions are represented with one or two letters after 1744 the word "identity," representing (S)RC and (D)ST. 1745 1746 In the case of an error, only the base header is returned. 1747 1748 Note that any standard error could be returned for any message. 1749 1750 Typically, they will be either one of the errors specifically listed 1751 in the description for a message or one of the following: 1752 1753 EINVAL Various message improprieties, including SPI ranges 1754 that are malformed. 1755 ENOMEM Needed memory was not available. 1756 ENOBUFS Needed memory was not available. 1757 EMSGSIZ The message exceeds the maximum length allowed. 1758 17593.1.1 SADB_GETSPI 1760 1761 The SADB_GETSPI message allows a process to obtain a unique SPI value 1762 for given security association type, source address, and destination 1763 address. This message followed by an SADB_UPDATE is one way to 1764 create a security association (SADB_ADD is the other method). The 1765 process specifies the type in the base header, the source and 1766 destination address in address extension. If the SADB_GETSPI message 1767 is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq 1768 MUST be the same as the SADB_ACQUIRE message. The application may 1769 also specify the SPI. This is done by having the kernel select 1770 within a range of SPI values by using the SPI range extension. To 1771 specify a single SPI value to be verified, the application sets the 1772 high and low values to be equal. Permitting range specification is 1773 important because the kernel can allocate an SPI value based on what 1774 it knows about SPI values already in use. The kernel returns the 1775 same message with the allocated SPI value stored in the spi field of 1776 an association extension. The allocate SPI (and destination address) 1777 refer to a LARVAL security association. An SADB_UPDATE message can 1778 later be used to add an entry with the requested SPI value. 1779 1780 It is recommended that associations that are created with SADB_GETSPI 1781 SHOULD be automatically deleted within a fixed amount of time if they 1782 are not updated by an SADB_UPDATE message. This allows SA storage 1783 not to get cluttered with larval associations. 1784 1785 The message behavior of the SADB_GETSPI message is: 1786 1787 Send an SADB_GETSPI message from a user process to the kernel. 1788 1789 <base, address, SPI range> 1790 1791 1792 1793 1794McDonald, et. al. Informational [Page 32] 1795 1796RFC 2367 PF_KEY Key Management API July 1998 1797 1798 1799 The kernel returns the SADB_GETSPI message to all listening 1800 processes. 1801 1802 <base, SA(*), address(SD)> 1803 1804 Errors: 1805 1806 EEXIST Requested SPI or SPI range is not available or already 1807 used. 1808 18093.1.2 SADB_UPDATE Message 1810 1811 The SADB_UPDATE message allows a process to update the information in 1812 an existing Security Association. Since SADB_GETSPI does not allow 1813 setting of certain parameters, this message is needed to fully form 1814 the SADB_SASTATE_LARVAL security association created with 1815 SADB_GETSPI. The format of the update message is a base header, 1816 followed by an association header and possibly by several extension 1817 headers. The kernel searches for the security association with the 1818 same type, spi, source address and destination address specified in 1819 the message and updates the Security Association information using 1820 the content of the SADB_UPDATE message. 1821 1822 The kernel MAY disallow SADB_UPDATE to succeed unless the message is 1823 issued from the same socket that created the security association. 1824 Such enforcement significantly reduces the chance of accidental 1825 changes to an in-use security association. Malicious trusted parties 1826 could still issue an SADB_FLUSH or SADB_DELETE message, but deletion 1827 of associations is more easily detected and less likely to occur 1828 accidentally than an erroneous SADB_UPDATE. The counter argument to 1829 supporting this behavior involves the case where a user-space key 1830 management application fails and is restarted. The new instance of 1831 the application will not have the same socket as the creator of the 1832 security association. 1833 1834 The kernel MUST sanity check all significant values submitted in an 1835 SADB_UPDATE message before changing the SA in its database and MUST 1836 return EINVAL if any of the values are invalid. Examples of checks 1837 that should be performed are DES key parity bits, key length 1838 checking, checks for keys known to be weak for the specified 1839 algorithm, and checks for flags or parameters known to be 1840 incompatible with the specified algorithm. 1841 1842 Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_UPDATE 1843 message. If the original SA is an SADB_SASTATE_LARVAL SA, then any 1844 value in the SA may be changed except for the source address, 1845 destination address, and SPI. If the original SA is an 1846 SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA 1847 1848 1849 1850McDonald, et. al. Informational [Page 33] 1851 1852RFC 2367 PF_KEY Key Management API July 1998 1853 1854 1855 MUST return EINVAL. It is not valid for established keying or 1856 algorithm information to change without the SPI changing, which would 1857 require creation of a new SA rather than a change to an existing SA. 1858 Once keying and algorithm information is negotiated, address and 1859 identity information is fixed for the SA. Therefore, if the original 1860 SA is an SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state 1861 field in the SA header and lifetimes (hard, soft, and current) may be 1862 changed and any attempt to change other values MUST result in an 1863 error return of EINVAL. 1864 1865 The message behavior of the SADB_UPDATE message is: 1866 1867 Send an SADB_UPDATE message from a user process to the kernel. 1868 1869 <base, SA, (lifetime(HSC),) address(SD), (address(P),) 1870 key(AE), (identity(SD),) (sensitivity)> 1871 1872 The kernel returns the SADB_UPDATE message to all listening 1873 processes. 1874 1875 <base, SA, (lifetime(HSC),) address(SD), (address(P),) 1876 (identity(SD),) (sensitivity)> 1877 1878 1879 The keying material is not returned on the message from the kernel to 1880 listening sockets because listeners might not have the privileges to 1881 see such keying material. 1882 1883 Errors: 1884 ESRCH The security association to be updated was not found. 1885 EINVAL In addition to other possible causes, this error is 1886 returned if sanity checking on the SA values (such 1887 as the keys) fails. 1888 EACCES Insufficient privilege to update entry. The socket 1889 issuing the SADB_UPDATE is not creator of the entry 1890 to be updated. 1891 18923.1.3 SADB_ADD 1893 1894 The SADB_ADD message is nearly identical to the SADB_UPDATE message, 1895 except that it does not require a previous call to SADB_GETSPI. The 1896 SADB_ADD message is used in manual keying applications, and in other 1897 cases where the uniqueness of the SPI is known immediately. 1898 1899 An SADB_ADD message is also used when negotiation is finished, and 1900 the second of a pair of associations is added. The SPI for this 1901 association was determined by the peer machine. The sadb_msg_seq 1902 1903 1904 1905 1906McDonald, et. al. Informational [Page 34] 1907 1908RFC 2367 PF_KEY Key Management API July 1998 1909 1910 1911 MUST be set to the value set in a kernel-generated SADB_ACQUIRE so 1912 that both associations in a pair are bound to the same ACQUIRE 1913 request. 1914 1915 The kernel MUST sanity check all used fields in the SA submitted in 1916 an SADB_ADD message before adding the SA to its database and MUST 1917 return EINVAL if any of the values are invalid. 1918 1919 Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_ADD message. 1920 SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is not 1921 sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state. 1922 Therefore, the sadb_sa_state field of all submitted SAs MUST be 1923 SADB_SASTATE_MATURE and the kernel MUST return an error if this is 1924 not true. 1925 1926 The message behavior of the SADB_ADD message is: 1927 1928 Send an SADB_ADD message from a user process to the kernel. 1929 1930 <base, SA, (lifetime(HS),) address(SD), (address(P),) 1931 key(AE), (identity(SD),) (sensitivity)> 1932 1933 The kernel returns the SADB_ADD message to all listening 1934 processes. 1935 1936 <base, SA, (lifetime(HS),) address(SD), (identity(SD),) 1937 (sensitivity)> 1938 1939 The keying material is not returned on the message from the kernel to 1940 listening sockets because listeners may not have the privileges to 1941 see such keying material. 1942 1943 Errors: 1944 1945 EEXIST The security association that was to be added already 1946 exists. 1947 EINVAL In addition to other possible causes, this error is 1948 returned if sanity checking on the SA values (such 1949 as the keys) fails. 1950 19513.1.4 SADB_DELETE 1952 1953 The SADB_DELETE message causes the kernel to delete a Security 1954 Association from the key table. The delete message consists of the 1955 base header followed by the association, and the source and 1956 destination sockaddrs in the address extension. The kernel deletes 1957 the security association matching the type, spi, source address, and 1958 destination address in the message. 1959 1960 1961 1962McDonald, et. al. Informational [Page 35] 1963 1964RFC 2367 PF_KEY Key Management API July 1998 1965 1966 1967 The message behavior for SADB_DELETE is as follows: 1968 1969 Send an SADB_DELETE message from a user process to the kernel. 1970 1971 <base, SA(*), address(SD)> 1972 1973 The kernel returns the SADB_DELETE message to all listening 1974 processes. 1975 1976 <base, SA(*), address(SD)> 1977 19783.1.5 SADB_GET 1979 1980 The SADB_GET message allows a process to retrieve a copy of a 1981 Security Association from the kernel's key table. The get message 1982 consists of the base header follows by the relevant extension fields. 1983 The Security Association matching the type, spi, source address, and 1984 destination address is returned. 1985 1986 The message behavior of the SADB_GET message is: 1987 1988 Send an SADB_GET message from a user process to the kernel. 1989 1990 <base, SA(*), address(SD)> 1991 1992 The kernel returns the SADB_GET message to the socket that sent 1993 the SADB_GET message. 1994 1995 <base, SA, (lifetime(HSC),) address(SD), (address(P),) key(AE), 1996 (identity(SD),) (sensitivity)> 1997 1998 Errors: 1999 ESRCH The sought security association was not found. 2000 20013.1.6 SADB_ACQUIRE 2002 2003 The SADB_ACQUIRE message is typically sent only by the kernel to key 2004 socket listeners who have registered their key socket (see 2005 SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 2006 application-level consumers of security associations (such as an 2007 OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 2008 message is a base header along with an address extension, possibly an 2009 identity extension, and a proposal extension. The proposed situation 2010 contains a list of desirable algorithms that can be used if the 2011 algorithms in the base header are not available. The values for the 2012 fields in the base header and in the security association data which 2013 follows the base header indicate the properties of the Security 2014 Association that the listening process should attempt to acquire. If 2015 2016 2017 2018McDonald, et. al. Informational [Page 36] 2019 2020RFC 2367 PF_KEY Key Management API July 1998 2021 2022 2023 the message originates from the kernel (i.e. the sadb_msg_pid is 0), 2024 the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and 2025 SADB_UPDATE, or subsequent SADB_ADD message to bind a security 2026 association to the request. This avoids the race condition of two 2027 TCP connections between two IP hosts that each require unique 2028 associations, and having one steal another's security association. 2029 The sadb_msg_errno and sadb_msg_state fields should be ignored by the 2030 listening process. 2031 2032 The SADB_ACQUIRE message is typically triggered by an outbound packet 2033 that needs security but for which there is no applicable Security 2034 Association existing in the key table. If the packet can be 2035 sufficiently protected by more than one algorithm or combination of 2036 options, the SADB_ACQUIRE message MUST order the preference of 2037 possibilities in the Proposal extension. 2038 2039 There are three messaging behaviors for SADB_ACQUIRE. The first is 2040 where the kernel needs a security association (e.g. for IPsec). 2041 2042 The kernel sends an SADB_ACQUIRE message to registered sockets. 2043 2044 <base, address(SD), (address(P)), (identity(SD),) (sensitivity,) 2045 proposal> 2046 2047 NOTE: The address(SD) extensions MUST have the port fields 2048 filled in with the port numbers of the session requiring 2049 keys if appropriate. 2050 2051 The second is when, for some reason, key management fails, it can 2052 send an ACQUIRE message with the same sadb_msg_seq as the initial 2053 ACQUIRE with a non-zero errno. 2054 2055 Send an SADB_ACQUIRE to indicate key management failure. 2056 2057 <base> 2058 2059 The third is where an application-layer consumer of security 2060 associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 2061 association. 2062 2063 Send an SADB_ACQUIRE message from a user process to the kernel. 2064 2065 <base, address(SD), (address(P),) (identity(SD),) (sensitivity,) 2066 proposal> 2067 2068 The kernel returns an SADB_ACQUIRE message to registered 2069 sockets. 2070 2071 2072 2073 2074McDonald, et. al. Informational [Page 37] 2075 2076RFC 2367 PF_KEY Key Management API July 1998 2077 2078 2079 <base, address(SD), (address(P),) (identity(SD),) (sensitivity,) 2080 proposal> 2081 2082 The user-level consumer waits for an SADB_UPDATE or SADB_ADD 2083 message for its particular type, and then can use that 2084 association by using SADB_GET messages. 2085 2086 Errors: 2087 EINVAL Invalid acquire request. 2088 EPROTONOSUPPORT No KM application has registered with the Key 2089 Engine as being able to obtain the requested SA type, so 2090 the requested SA cannot be acquired. 2091 20923.1.7 SADB_REGISTER 2093 2094 The SADB_REGISTER message allows an application to register its key 2095 socket as able to acquire new security associations for the kernel. 2096 SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 2097 the type of security association specified in sadb_msg_satype. The 2098 application specifies the type of security association that it can 2099 acquire for the kernel in the type field of its register message. If 2100 an application can acquire multiple types of security association, it 2101 MUST register each type in a separate message. Only the base header 2102 is needed for the register message. Key management applications MAY 2103 register for a type not known to the kernel, because the consumer may 2104 be in user-space (e.g. OSPFv2 security). 2105 2106 The reply of the SADB_REGISTER message contains a supported algorithm 2107 extension. That field contains an array of supported algorithms, one 2108 per octet. This allows key management applications to know what 2109 algorithm are supported by the kernel. 2110 2111 In an environment where algorithms can be dynamically loaded and 2112 unloaded, an asynchronous SADB_REGISTER reply MAY be generated. The 2113 list of supported algorithms MUST be a complete list, so the 2114 application can make note of omissions or additions. 2115 2116 The messaging behavior of the SADB_REGISTER message is: 2117 2118 Send an SADB_REGISTER message from a user process to the kernel. 2119 2120 <base> 2121 2122 The kernel returns an SADB_REGISTER message to registered 2123 sockets, with algorithm types supported by the kernel being 2124 indicated in the supported algorithms field. 2125 2126 2127 2128 2129 2130McDonald, et. al. Informational [Page 38] 2131 2132RFC 2367 PF_KEY Key Management API July 1998 2133 2134 2135 NOTE: This message may arrive asynchronously due to an 2136 algorithm being loaded or unloaded into a dynamically 2137 linked kernel. 2138 2139 <base, supported> 2140 21413.1.8 SADB_EXPIRE Message 2142 2143 The operating system kernel is responsible for tracking SA 2144 expirations for security protocols that are implemented inside the 2145 kernel. If the soft limit or hard limit of a Security Association 2146 has expired for a security protocol implemented inside the kernel, 2147 then the kernel MUST issue an SADB_EXPIRE message to all key socket 2148 listeners. If the soft limit or hard limit of a Security Association 2149 for a user-level security protocol has expired, the user-level 2150 protocol SHOULD issue an SADB_EXPIRE message. 2151 2152 The base header will contain the security association information 2153 followed by the source sockaddr, destination sockaddr, (and, if 2154 present, internal sockaddr,) (and, if present, one or both 2155 compartment bitmaps). 2156 2157 The lifetime extension of an SADB_EXPIRE message is important to 2158 indicate which lifetime expired. If a HARD lifetime extension is 2159 included, it indicates that the HARD lifetime expired. This means 2160 the association MAY be deleted already from the SADB. If a SOFT 2161 lifetime extension is included, it indicates that the SOFT lifetime 2162 expired. The CURRENT lifetime extension will indicate the current 2163 status, and comparisons to the HARD or SOFT lifetime will indicate 2164 which limit was reached. HARD lifetimes MUST take precedence over 2165 SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same, 2166 the HARD lifetime will appear on the EXPIRE message. The 2167 pathological case of HARD lifetimes being shorter than SOFT lifetimes 2168 is handled such that the SOFT lifetime will never expire. 2169 2170 The messaging behavior of the SADB_EXPIRE message is: 2171 2172 The kernel sends an SADB_EXPIRE message to all listeners when 2173 the soft limit of a security association has been expired. 2174 2175 <base, SA, lifetime(C and one of HS), address(SD)> 2176 2177 Note that the SADB_EXPIRE message is ONLY sent by the kernel to the 2178 KMd. It is a one-way informational message that does not have a 2179 reply. 2180 2181 2182 2183 2184 2185 2186McDonald, et. al. Informational [Page 39] 2187 2188RFC 2367 PF_KEY Key Management API July 1998 2189 2190 21913.1.9 SADB_FLUSH 2192 2193 The SADB_FLUSH message causes the kernel to delete all entries in its 2194 key table for a certain sadb_msg_satype. Only the base header is 2195 required for a flush message. If sadb_msg_satype is filled in with a 2196 specific value, only associations of that type are deleted. If it is 2197 filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted. 2198 2199 The messaging behavior for SADB_FLUSH is: 2200 2201 Send an SADB_FLUSH message from a user process to the kernel. 2202 2203 <base> 2204 2205 The kernel will return an SADB_FLUSH message to all listening 2206 sockets. 2207 2208 <base> 2209 2210 The reply message happens only after the actual flushing 2211 of security associations has been attempted. 2212 22133.1.10 SADB_DUMP 2214 2215 The SADB_DUMP message causes the kernel to dump the operating 2216 system's entire Key Table to the requesting key socket. As in 2217 SADB_FLUSH, if a sadb_msg_satype value is in the message, only 2218 associations of that type will be dumped. If SADB_SATYPE_UNSPEC is 2219 specified, all associations will be dumped. Each Security Association 2220 is returned in its own SADB_DUMP message. A SADB_DUMP message with a 2221 sadb_seq field of zero indicates the end of the dump transaction. The 2222 dump message is used for debugging purposes only and is not intended 2223 for production use. 2224 2225 Support for the dump message MAY be discontinued in future versions 2226 of PF_KEY. Key management applications MUST NOT depend on this 2227 message for basic operation. 2228 2229 The messaging behavior for SADB_DUMP is: 2230 2231 Send an SADB_DUMP message from a user process to the kernel. 2232 2233 <base> 2234 2235 Several SADB_DUMP messages will return from the kernel to the 2236 sending socket. 2237 2238 2239 2240 2241 2242McDonald, et. al. Informational [Page 40] 2243 2244RFC 2367 PF_KEY Key Management API July 1998 2245 2246 2247 <base, SA, (lifetime (HSC),) address(SD), (address(P),) 2248 key(AE), (identity(SD),) (sensitivity)> 2249 22503.2 Security Association Flags 2251 2252 The Security Association's flags are a bitmask field. These flags 2253 also appear in a combination that is part of a PROPOSAL extension. 2254 The related symbolic definitions below should be used in order that 2255 applications will be portable: 2256 2257 #define SADB_SAFLAGS_PFS 1 /* perfect forward secrecy */ 2258 2259 The SADB_SAFLAGS_PFS flag indicates to key management that this 2260 association should have perfect forward secrecy in its key. (In 2261 other words, any given session key cannot be determined by 2262 cryptanalysis of previous session keys or some master key.) 2263 22643.3 Security Association States 2265 2266 The security association state field is an integer that describes the 2267 states of a security association. They are: 2268 2269 #define SADB_SASTATE_LARVAL 0 2270 #define SADB_SASTATE_MATURE 1 2271 #define SADB_SASTATE_DYING 2 2272 #define SADB_SASTATE_DEAD 3 2273 2274 #define SADB_SASTATE_MAX 3 2275 2276 A SADB_SASTATE_LARVAL security association is one that was created by 2277 the SADB_GETSPI message. A SADB_SASTATE_MATURE association is one 2278 that was updated with the SADB_UPDATE message or added with the 2279 SADB_ADD message. A DYING association is one whose soft lifetime has 2280 expired. A SADB_SASTATE_DEAD association is one whose hard lifetime 2281 has expired, but hasn't been reaped by system garbage collection. If 2282 a consumer of security associations has to extend an association 2283 beyond its normal lifetime (e.g. OSPF Security) it MUST only set the 2284 soft lifetime for an association. 2285 22863.4 Security Association Types 2287 2288 This defines the type of Security Association in this message. The 2289 symbolic names are always the same, even on different 2290 implementations. Applications SHOULD use the symbolic name in order 2291 to have maximum portability across different implementations. These 2292 are defined in the file <net/pfkeyv2.h>. 2293 2294 2295 2296 2297 2298McDonald, et. al. Informational [Page 41] 2299 2300RFC 2367 PF_KEY Key Management API July 1998 2301 2302 2303 #define SADB_SATYPE_UNSPEC 0 2304 2305 #define SADB_SATYPE_AH 2 /* RFC-1826 */ 2306 #define SADB_SATYPE_ESP 3 /* RFC-1827 */ 2307 2308 #define SADB_SATYPE_RSVP 5 /* RSVP Authentication */ 2309 #define SADB_SATYPE_OSPFV2 6 /* OSPFv2 Authentication */ 2310 #define SADB_SATYPE_RIPV2 7 /* RIPv2 Authentication */ 2311 #define SADB_SATYPE_MIP 8 /* Mobile IP Auth. */ 2312 2313 #define SADB_SATYPE_MAX 8 2314 2315 SADB_SATYPE_UNSPEC is defined for completeness and means no specific 2316 type of security association. This type is never used with PF_KEY 2317 SAs. 2318 2319 SADB_SATYPE_AH is for the IP Authentication Header [Atk95b]. 2320 2321 SADB_SATYPE_ESP is for the IP Encapsulating Security Payload 2322 [Atk95c]. 2323 2324 SADB_SATYPE_RSVP is for the RSVP Integrity Object. 2325 2326 SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication 2327 [Moy98]. 2328 2329 SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97]. 2330 2331 SADB_SATYPE_MIP is for Mobile IP's authentication extensions [Per97]. 2332 2333 SADB_SATYPE_MAX is always set to the highest valid numeric value. 2334 23353.5 Algorithm Types 2336 2337 The algorithm type is interpreted in the context of the Security 2338 Association type defined above. The numeric value might vary between 2339 implementations, but the symbolic name MUST NOT vary between 2340 implementations. Applications should use the symbolic name in order 2341 to have maximum portability to various implementations. 2342 2343 Some of the algorithm types defined below might not be standardized 2344 or might be deprecated in the future. To obtain an assignment for a 2345 symbolic name, contact the authors. 2346 2347 The symbols below are defined in <net/pfkeyv2.h>. 2348 2349 2350 2351 2352 2353 2354McDonald, et. al. Informational [Page 42] 2355 2356RFC 2367 PF_KEY Key Management API July 1998 2357 2358 2359 /* Authentication algorithms */ 2360 #define SADB_AALG_NONE 0 2361 #define SADB_AALG_MD5HMAC 2 2362 #define SADB_AALG_SHA1HMAC 3 2363 #define SADB_AALG_MAX 3 2364 2365 /* Encryption algorithms */ 2366 #define SADB_EALG_NONE 0 2367 #define SADB_EALG_DESCBC 2 2368 #define SADB_EALG_3DESCBC 3 2369 #define SADB_EALG_NULL 11 2370 #define SADB_EALG_MAX 11 2371 2372 The algorithm for SADB_AALG_MD5_HMAC is defined in [MG98a]. The 2373 algorithm for SADB_AALG_SHA1HMAC is defined in [MG98b]. The 2374 algorithm for SADB_EALG_DESCBC is defined in [MD98]. SADB_EALG_NULL 2375 is the NULL encryption algorithm, defined in [GK98]. The 2376 SADB_EALG_NONE value is not to be used in any security association 2377 except those which have no possible encryption algorithm in them 2378 (e.g. IPsec AH). 2379 23803.6 Extension Header Values 2381 2382 To briefly recap the extension header values: 2383 2384 #define SADB_EXT_RESERVED 0 2385 #define SADB_EXT_SA 1 2386 #define SADB_EXT_LIFETIME_CURRENT 2 2387 #define SADB_EXT_LIFETIME_HARD 3 2388 #define SADB_EXT_LIFETIME_SOFT 4 2389 #define SADB_EXT_ADDRESS_SRC 5 2390 #define SADB_EXT_ADDRESS_DST 6 2391 #define SADB_EXT_ADDRESS_PROXY 7 2392 #define SADB_EXT_KEY_AUTH 8 2393 #define SADB_EXT_KEY_ENCRYPT 9 2394 #define SADB_EXT_IDENTITY_SRC 10 2395 #define SADB_EXT_IDENTITY_DST 11 2396 #define SADB_EXT_SENSITIVITY 12 2397 #define SADB_EXT_PROPOSAL 13 2398 #define SADB_EXT_SUPPORTED_AUTH 14 2399 #define SADB_EXT_SUPPORTED_ENCRYPT 15 2400 #define SADB_EXT_SPIRANGE 16 2401 2402 #define SADB_EXT_MAX 16 2403 2404 2405 2406 2407 2408 2409 2410McDonald, et. al. Informational [Page 43] 2411 2412RFC 2367 PF_KEY Key Management API July 1998 2413 2414 24153.7 Identity Extension Values 2416 2417 Each identity can have a certain type. 2418 2419 #define SADB_IDENTTYPE_RESERVED 0 2420 #define SADB_IDENTTYPE_PREFIX 1 2421 #define SADB_IDENTTYPE_FQDN 2 2422 #define SADB_IDENTTYPE_USERFQDN 3 2423 2424 #define SADB_IDENTTYPE_MAX 3 2425 2426 The PREFIX identity string consists of a network address followed by a 2427 forward slash and a prefix length. The network address is in a 2428 printable numeric form appropriate for the protocol family. The 2429 prefix length is a decimal number greater than or equal to zero and 2430 less than the number of bits in the network address. It indicates the 2431 number of bits in the network address that are significant; all bits 2432 in the network address that are not significant MUST be set to zero. 2433 Note that implementations MUST parse the contents of the printable 2434 address into a binary form for comparison purposes because multiple 2435 printable strings are valid representations of the same address in 2436 many protocol families (for example, some allow leading zeros and some 2437 have letters that are case insensitive). Examples of PREFIX identities 2438 are "199.33.248.64/27" and "3ffe::1/128". If the source or destination 2439 identity is a PREFIX identity, the source or destination address for 2440 the SA (respectively) MUST be within that prefix. The sadb_ident_id 2441 field is zeroed for these identity types. 2442 2443 The FQDN identity string contains a fully qualified domain name. An 2444 example FQDN identity is "ministry-of-truth.inner.net". The 2445 sadb_ident_id field is zeroed for these identity types. 2446 2447 The UserFQDN identity consists of a text string in the format commonly 2448 used for Internet-standard electronic mail. The syntax is the text 2449 username, followed by the "@" character, followed in turn by the 2450 appropriate fully qualified domain name. This identity specifies both 2451 a username and an associated FQDN. There is no requirement that this 2452 string specify a mailbox valid for SMTP or other electronic mail 2453 use. This identity is useful with protocols supporting user-oriented 2454 keying. It is a convenient identity form because the DNS Security 2455 extensions can be used to distribute signed public key values by 2456 associating KEY and SIG records with an appropriate MB DNS record. An 2457 example UserFQDN identity is "julia@ministry-of-love.inner.net". The 2458 sadb_ident_id field is used to contain a POSIX user id in the absence 2459 of an identity string itself so that a user-level application can use 2460 the getpwuid{,_r}() routine to obtain a textual user login id. If a 2461 string is present, it SHOULD match the numeric value in the 2462 sadb_ident_id field. If it does not match, the string SHOULD override 2463 2464 2465 2466McDonald, et. al. Informational [Page 44] 2467 2468RFC 2367 PF_KEY Key Management API July 1998 2469 2470 2471 the numeric value. 2472 24733.8 Sensitivity Extension Values 2474 2475 The only field currently defined in the sensitivity extension is the 2476 sadb_sens_dpd, which represents the data protection domain. The other 2477 data in the sensitivity extension is based off the sadb_sens_dpd 2478 value. 2479 2480 The DP/DOI is defined to be the same as the "Labeled Domain Identifier 2481 Value" of the IP Security DOI specification [Pip98]. As noted in that 2482 specification, values in the range 0x80000000 to 0xffffffff 2483 (inclusive) are reserved for private use and values in the range 2484 0x00000001 through 0x7fffffff are assigned by IANA. The all-zeros 2485 DP/DOI value is permanently reserved to mean that "no DP/DOI is in 2486 use". 2487 24883.9 Proposal Extension Values 2489 2490 These are already mentioned in the Algorithm Types and Security 2491 Association Flags sections. 2492 24934 Future Directions 2494 2495 While the current specification for the Sensitivity and Integrity 2496 Labels is believed to be general enough, if a case should arise that 2497 can't work with the current specification then this might cause a 2498 change in a future version of PF_KEY. 2499 2500 Similarly, PF_KEY might need extensions to work with other kinds of 2501 Security Associations in future. It is strongly desirable for such 2502 extensions to be made in a backwards-compatible manner should they be 2503 needed. 2504 2505 When more experience is gained with certificate management, it is 2506 possible that the IDENTITY extension will have to be revisited to 2507 allow a finer grained selection of certificate identities. 2508 25095. Examples 2510 2511 The following examples illustrate how PF_KEY is used. The first 2512 example is an IP Security example, where the consumer of the security 2513 associations is inside an operating system kernel. The second example 2514 is an OSPF Security example, which illustrates a user-level consumer 2515 of security associations. The third example covers things not 2516 mentioned by the first two examples. A real system may closely 2517 conform to one of these examples, or take parts of them. These 2518 examples are purely illustrative, and are not intended to mandate a 2519 2520 2521 2522McDonald, et. al. Informational [Page 45] 2523 2524RFC 2367 PF_KEY Key Management API July 1998 2525 2526 2527 particular implementation method. 2528 25295.1 Simple IP Security Example 2530 2531 +---------------+ +-------------+ 2532 |Key Mgmt Daemon| | Application | 2533 +---------------+ +-------------+ 2534 | | / 2535 | | / 2536 | | | Applications 2537 ======[PF_KEY]====[PF_INET]========================== 2538 | | | OS Kernel 2539 +------------+ +-----------------+ 2540 | Key Engine | | TCP/IP, | 2541 | or SADB |---| including IPsec | 2542 +------------+ | | 2543 +-----------------+ 2544 2545 When the Key Management daemon (KMd) begins. It must tell PF_KEY 2546 that it is willing to accept message for the two IPsec services, AH 2547 and ESP. It does this by sending down two SADB_REGISTER messages. 2548 2549 KMd->Kernel: SADB_REGISTER for ESP 2550 Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms 2551 KMd->Kernel: SADB_REGISTER for AH 2552 Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms 2553 2554 Each REGISTER message will cause a reply to go to all PF_KEY sockets 2555 registered for ESP and AH respectively (including the requester). 2556 2557 Assume that no security associations currently exist for IPsec to 2558 use. Consider when a network application begins transmitting data 2559 (e.g. a TCP SYN). Because of policy, or the application's request, 2560 the kernel IPsec module needs an AH security association for this 2561 data. Since there is not one present, the following message is 2562 generated: 2563 2564 Kernel->Registered: SADB_ACQUIRE for AH, addrs, ID, sens, 2565 proposals 2566 2567 The KMd reads the ACQUIRE message, especially the sadb_msg_seq 2568 number. Before it begins the negotiation, it sends down an 2569 SADB_GETSPI message with the sadb_msg_seq number equal to the one 2570 received in the ACQUIRE. The kernel returns the results of the 2571 GETSPI to all listening sockets. 2572 2573 KMd->Kernel: SADB_GETSPI for AH, addr, SPI range 2574 Kernel->All: SADB_GETSPI for AH, assoc, addrs 2575 2576 2577 2578McDonald, et. al. Informational [Page 46] 2579 2580RFC 2367 PF_KEY Key Management API July 1998 2581 2582 2583 The KMd may perform a second GETSPI operation if it needs both 2584 directions of IPsec SPI values. Now that the KMd has an SPI for at 2585 least one of the security associations, it begins negotiation. After 2586 deriving keying material, and negotiating other parameters, it sends 2587 down one (or more) SADB_UPDATE messages with the same value in 2588 sadb_msg_seq. 2589 2590 If a KMd has any error at all during its negotiation, it can send 2591 down: 2592 2593 KMd->Kernel: SADB_ACQUIRE for AH, assoc (with an error) 2594 Kernel->All: SADB_ACQUIRE for AH, assoc (same error) 2595 2596 but if it succeeds, it can instead: 2597 2598 KMd->Kernel: SADB_UPDATE for AH, assoc, addrs, keys, 2599 <etc.> 2600 Kernel->All: SADB_UPDATE for AH, assoc, addrs, <etc.> 2601 2602 The results of the UPDATE (minus the actual keys) are sent to all 2603 listening sockets. If only one SPI value was determined locally, the 2604 other SPI (since IPsec SAs are unidirectional) must be added with an 2605 SADB_ADD message. 2606 2607 KMd->Kernel: SADB_ADD for AH, assoc, addrs, keys, <etc.> 2608 Kernel->All: SADB_ADD for AH, assoc, addrs, <etc.> 2609 2610 If one of the extensions passed down was a Lifetime extension, it is 2611 possible at some point an SADB_EXPIRE message will arrive when one of 2612 the lifetimes has expired. 2613 2614 Kernel->All: SADB_EXPIRE for AH, assoc, addrs, 2615 Hard or Soft, Current, <etc.> 2616 2617 The KMd can use this as a clue to begin negotiation, or, if it has 2618 some say in policy, send an SADB_UPDATE down with a lifetime 2619 extension. 2620 26215.2 Proxy IP Security Example 2622 2623 Many people are interested in using IP Security in a "proxy" or 2624 "firewall" configuration in which an intermediate system provides 2625 security services for "inside" hosts. In these environments, the 2626 intermediate systems can use PF_KEY to communicate with key 2627 management applications almost exactly as they would if they were the 2628 actual endpoints. The messaging behavior of PF_KEY in these cases is 2629 exactly the same as the previous example, but the address information 2630 is slightly different. 2631 2632 2633 2634McDonald, et. al. Informational [Page 47] 2635 2636RFC 2367 PF_KEY Key Management API July 1998 2637 2638 2639 Consider this case: 2640 2641 A ========= B --------- C 2642 2643 Key: 2644 A "outside" host that implements IPsec 2645 B "firewall" that implements IPsec 2646 C "inside" host that does not implement IPsec 2647 2648 === IP_{A<->B} ESP [ IP_{A<->C} ULP ] 2649 --- IP_{A<->C} ULP 2650 2651 A is a single system that wishes to communicate with the "inside" 2652 system C. B is a "firewall" between C and the outside world that 2653 will do ESP and tunneling on C's behalf. A discovers that it needs 2654 to send traffic to C via B through methods not described here (Use of 2655 the DNS' KX record might be one method for discovering this). 2656 2657 For packets that flow from left to right, A and B need an IPsec 2658 Security Association with: 2659 2660 SA type of ESP tunnel-mode 2661 Source Identity that dominates A (e.g. A's address) 2662 Destination Identity that dominates B (e.g. B's address) 2663 Source Address of A 2664 Destination Address of B 2665 2666 For packets to flow from right to left, A and B need an IPsec 2667 Security Association with: 2668 2669 SA type of ESP tunnel-mode 2670 Source Identity that dominates C 2671 Destination Identity that dominates A 2672 Source Address of B 2673 Destination Address of A 2674 Proxy Address of C 2675 2676 For this second SA (for packets flowing from C towards A), node A 2677 MUST verify that the inner source address is dominated by the Source 2678 Identity for the SA used with those packets. If node A does not do 2679 this, an adversary could forge packets with an arbitrary Source 2680 Identity and defeat the packet origin protections provided by IPsec. 2681 2682 Now consider a slightly more complex case: 2683 2684 A_1 --| |-- D_1 2685 |--- B ====== C ---| 2686 A_2 --| |-- D_2 2687 2688 2689 2690McDonald, et. al. Informational [Page 48] 2691 2692RFC 2367 PF_KEY Key Management API July 1998 2693 2694 2695 Key: 2696 A_n "inside" host on net 1 that does not do IPsec. 2697 B "firewall" for net 1 that supports IPsec. 2698 C "firewall" for net 2 that supports IPsec. 2699 D_n "inside" host on net 2 that does not do IPsec. 2700 === IP_{B<->C} ESP [ IP_{A<->C} ULP ] 2701 --- IP_{A<->C} ULP 2702 2703 For A_1 to send a packet to D_1, B and C need an SA with: 2704 2705 SA Type of ESP 2706 Source Identity that dominates A_1 2707 Destination Identity that dominates C 2708 Source Address of B 2709 Destination Address of C 2710 Proxy Address of A_1 2711 2712 For D_1 to send a packet to A_1, C and B need an SA with: 2713 SA Type of ESP Tunnel-mode 2714 Source Identity that dominates D_1 2715 Destination Identity that dominates B 2716 Source Address of C 2717 Destination Address of B 2718 Proxy Address of D_1 2719 2720 Note that A_2 and D_2 could be substituted for A_1 and D_1 2721 (respectively) here; the association of an SA with a particular pair 2722 of ends or group of those pairs is a policy decision on B and/or C 2723 and not necessarily a function of key management. The same check of 2724 the Source Identity against the inner source IP address MUST also be 2725 performed in this case for the same reason. 2726 2727 For a more detailed discussion of the use of IP Security in complex 2728 cases, please see [Atk97]. 2729 2730 NOTE: The notion of identity domination might be unfamiliar. Let H 2731 represent some node. Let Hn represent H's fully qualified domain 2732 name. Let Ha represent the IP address of H. Let Hs represent the IP 2733 subnet containing Ha. Let Hd represent a fully qualified domain 2734 name that is a parent of the fully qualified domain name of H. Let 2735 M be a UserFQDN identity that whose right-hand part is Hn or Ha. 2736 2737 Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the 2738 example above. Hs dominates any node having an IP address within 2739 the IP address range represented by Hs. Hd dominates any node 2740 having a fully qualified domain name within underneath Hd. 2741 2742 2743 2744 2745 2746McDonald, et. al. Informational [Page 49] 2747 2748RFC 2367 PF_KEY Key Management API July 1998 2749 2750 27515.3 OSPF Security Example 2752 2753 +---------------+ +-------------+ 2754 |Key Mgmt Daemon| | OSPF daemon | 2755 +---------------+ +-------------+ 2756 | | / / | 2757 | /------|----+ / | 2758 | / | +---+ | Applications 2759 ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================ 2760 | | | | OS Kernel 2761 +------------+ +-----------------+ +---------+ 2762 | Key Engine | | TCP/IP, | | Routing | 2763 | or SADB |---| including IPsec |--| Table | 2764 +------------+ | | +---------+ 2765 +-----------------+ 2766 2767 As in the previous examples, the KMd registers itself with the Key 2768 Engine via PF_KEY. Even though the consumer of the security 2769 associations is in user-space, the PF_KEY and Key Engine 2770 implementation knows enough to store SAs and to relay messages. 2771 2772 When the OSPF daemon needs to communicate securely with its peers, it 2773 would perform an SADB_GET message and retrieve the appropriate 2774 association: 2775 2776 OSPFd->Kernel: SADB_GET of OSPF, assoc, addrs 2777 Kernel->OSPFd: SADB_GET of OSPF, assoc, addrs, keys, <etc.> 2778 2779 If this GET fails, the OSPFd may need to acquire a new security 2780 association. This interaction is as follows: 2781 2782 OSPFd->Kernel: SADB_ACQUIRE of OSPF, addrs, <ID, sens,> 2783 proposal 2784 Kernel->Registered: SADB_ACQUIRE of OSPF, <same as sent message> 2785 2786 The KMd sees this and performs actions similar to the previous 2787 example. One difference, however, is that when the UPDATE message 2788 comes back, the OSPFd will then perform a GET of the updated SA to 2789 retrieve all of its parameters. 2790 27915.4 Miscellaneous 2792 2793 Some messages work well only in system maintenance programs, for 2794 debugging, or for auditing. In a system panic situation, such as a 2795 detected compromise, an SADB_FLUSH message should be issued for a 2796 particular SA type, or for ALL SA types. 2797 2798 2799 2800 2801 2802McDonald, et. al. Informational [Page 50] 2803 2804RFC 2367 PF_KEY Key Management API July 1998 2805 2806 2807 Program->Kernel: SADB_FLUSH for ALL 2808 <Kernel then flushes all internal SAs> 2809 Kernel->All: SADB_FLUSH for ALL 2810 2811 Some SAs may need to be explicitly deleted, either by a KMd, or by a 2812 system maintenance program. 2813 2814 Program->Kernel: SADB_DELETE for AH, association, addrs 2815 Kernel->All: SADB_DELETE for AH, association, addrs 2816 2817 Common usage of the SADB_DUMP message is discouraged. For debugging 2818 purposes, however, it can be quite useful. The output of a DUMP 2819 message should be read quickly, in order to avoid socket buffer 2820 overflows. 2821 2822 Program->Kernel: SADB_DUMP for ESP 2823 Kernel->Program: SADB_DUMP for ESP, association, <all fields> 2824 Kernel->Program: SADB_DUMP for ESP, association, <all fields> 2825 Kernel->Program: SADB_DUMP for ESP, association, <all fields> 2826 <ad nauseam...> 2827 28286 Security Considerations 2829 2830 This memo discusses a method for creating, reading, modifying, and 2831 deleting Security Associations from an operating system. Only 2832 trusted, privileged users and processes should be able to perform any 2833 of these operations. It is unclear whether this mechanism provides 2834 any security when used with operating systems not having the concept 2835 of a trusted, privileged user. 2836 2837 If an unprivileged user is able to perform any of these operations, 2838 then the operating system cannot actually provide the related 2839 security services. If an adversary knows the keys and algorithms in 2840 use, then cryptography cannot provide any form of protection. 2841 2842 This mechanism is not a panacea, but it does provide an important 2843 operating system component that can be useful in creating a secure 2844 internetwork. 2845 2846 Users need to understand that the quality of the security provided by 2847 an implementation of this specification depends completely upon the 2848 overall security of the operating system, the correctness of the 2849 PF_KEY implementation, and upon the security and correctness of the 2850 applications that connect to PF_KEY. It is appropriate to use high 2851 assurance development techniques when implementing PF_KEY and the 2852 related security association components of the operating system. 2853 2854 2855 2856 2857 2858McDonald, et. al. Informational [Page 51] 2859 2860RFC 2367 PF_KEY Key Management API July 1998 2861 2862 2863Acknowledgments 2864 2865 The authors of this document are listed primarily in alphabetical 2866 order. Randall Atkinson and Ron Lee provided useful feedback on 2867 earlier versions of this document. 2868 2869 At one time or other, all of the authors worked at the Center for 2870 High Assurance Computer Systems at the U.S. Naval Research 2871 Laboratory. This work was sponsored by the Information Security 2872 Program Office (PMW-161), U.S. Space and Naval Warfare Systems 2873 Command (SPAWAR) and the Computing Systems Technology Office, Defense 2874 Advanced Research Projects Agency (DARPA/CSTO). We really appreciate 2875 their sponsorship of our efforts and their continued support of 2876 PF_KEY development. Without that support, PF_KEY would not exist. 2877 2878 The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST98]. 2879 2880 Finally, the authors would like to thank those who sent in comments 2881 and questions on the various iterations of this document. This 2882 specification and implementations of it are discussed on the PF_KEY 2883 mailing list. If you would like to be added to this list, send a note 2884 to <pf_key-request@inner.net>. 2885 2886References 2887 2888 [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig 2889 W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite 2890 BSD", Proceedings of the 1996 USENIX Conference, San Diego, CA, 2891 January 1996, USENIX Association. 2892 2893 [Atk95a] Atkinson, R., "IP Security Architecture", RFC 1825, August 2894 1995. 2895 2896 [Atk95b] Atkinson, R., "IP Authentication Header", RFC 1826, August 2897 1995. 2898 2899 [Atk95c] Atkinson, R., "IP Encapsulating Security Payload", RFC 1827, 2900 August 1995. 2901 2902 [Atk97] Atkinson, R., "Key Exchange Delegation Record for the Domain 2903 Name System", RFC 2230, October 1997. 2904 2905 [BA97] Baker, F., and R. Atkinson, "RIP-2 MD5 Authentication", RFC 2906 2082, January 1997. 2907 2908 [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer 2909 Systems", MTR-3153, The MITRE Corporation, June 1975; ESD-TR-76-372, 2910 April 1977. 2911 2912 2913 2914McDonald, et. al. Informational [Page 52] 2915 2916RFC 2367 PF_KEY Key Management API July 1998 2917 2918 2919 [BL74] D. Elliot Bell and Leonard J. LaPadula, "Secure Computer 2920 Systems: Unified Exposition and Multics Interpretation", MTR 2997, 2921 The MITRE Corporation, April 1974. (AD/A 020 445) 2922 2923 [Bra97] Bradner, S., "Key words for use in RFCs to Indicate 2924 Requirement Levels", BCP 14, RFC 2119, March 1997. 2925 2926 [CW87] D. D. Clark and D. R. Wilson, "A Comparison of Commercial and 2927 Military Computer Security Policies", Proceedings of the 1987 2928 Symposium on Security and Privacy, pp. 184-195, IEEE Computer 2929 Society, Washington, D.C., 1987. 2930 2931 [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 2932 Workstation Specification", Technical Report DDS-2600-6243-87. 2933 2934 [GK98] Glenn, R., and S. Kent, "The NULL Encryption Algorithm and Its 2935 Use with IPsec", Work in Progress. 2936 2937 [HM97a] Harney, H., and C. Muckenhirn, "Group Key Management Protocol 2938 (GKMP) Specification", RFC 2093, July 1997. 2939 2940 [HM97b] Harney, H., and C. Muckenhirn, "Group Key Management Protocol 2941 (GKMP) Architecture", RFC 2094, July 1997. 2942 2943 [MD98] Madsen, C., and N. Doraswamy, "The ESP DES-CBC Cipher 2944 Algorithm With Explicit IV", Work in Progress. 2945 2946 [MG98a] Madsen, C., and R. Glenn, "The Use of HMAC-MD5-96 within ESP 2947 and AH", Work in Progress. 2948 2949 [MG98b] Madsen, C., and R. Glenn, "The Use of HMAC-SHA-1-96 within 2950 ESP and AH", Work in Progress. 2951 2952 [MSST98] Maughan, D., Schertler, M., Schneider, M., and J. Turner, 2953 "Internet Security Association and Key Management Protocol (ISAKMP)", 2954 Work in Progress. 2955 2956 [Moy98] Moy, J., "OSPF Version 2", STD 54, RFC 2328, April 1998. 2957 2958 [Per97] Perkins, C., "IP Mobility Support", RFC 2002, October 1996. 2959 2960 [Pip98] Piper, D., "The Internet IP Security Domain of Interpretation 2961 for ISAKMP", Work in Progress. 2962 2963 [Sch96] Bruce Schneier, Applied Cryptography, p. 360, John Wiley & 2964 Sons, Inc., 1996. 2965 2966 2967 2968 2969 2970McDonald, et. al. Informational [Page 53] 2971 2972RFC 2367 PF_KEY Key Management API July 1998 2973 2974 2975 [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for 2976 Berkeley UNIX", Proceedings of the Winter 1991 USENIX Conference, 2977 Dallas, TX, USENIX Association. 1991. pp. 93-103. 2978 2979Disclaimer 2980 2981 The views and specification here are those of the editors and are not 2982 necessarily those of their employers. The employers have not passed 2983 judgment on the merits, if any, of this work. The editors and their 2984 employers specifically disclaim responsibility for any problems 2985 arising from correct or incorrect implementation or use of this 2986 specification. 2987 2988Authors' Addresses 2989 2990 Daniel L. McDonald 2991 Sun Microsystems, Inc. 2992 901 San Antonio Road, MS UMPK17-202 2993 Palo Alto, CA 94303 2994 2995 Phone: +1 650 786 6815 2996 EMail: danmcd@eng.sun.com 2997 2998 2999 Craig Metz 3000 (for Code 5544) 3001 U.S. Naval Research Laboratory 3002 4555 Overlook Ave. SW 3003 Washington, DC 20375 3004 3005 Phone: (DSN) 754-8590 3006 EMail: cmetz@inner.net 3007 3008 3009 Bao G. Phan 3010 U. S. Naval Research Laboratory 3011 3012 EMail: phan@itd.nrl.navy.mil 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026McDonald, et. al. Informational [Page 54] 3027 3028RFC 2367 PF_KEY Key Management API July 1998 3029 3030 3031Appendix A: Promiscuous Send/Receive Message Type 3032 3033 A kernel supporting PF_KEY MAY implement the following extension for 3034 development and debugging purposes. If it does, it MUST implement the 3035 extension as specified here. An implementation MAY require an 3036 application to have additional privileges to perform promiscuous send 3037 and/or receive operations. 3038 3039 The SADB_X_PROMISC message allows an application to send and receive 3040 messages in a "promiscuous mode." There are two forms of this 3041 message: control and data. The control form consists of only a 3042 message header. This message is used to toggle the promiscuous- 3043 receive function. A value of one in the sadb_msg_satype field enables 3044 promiscuous message reception for this socket, while a value of zero 3045 in that field disables it. 3046 3047 The second form of this message is the data form. This is used to 3048 send or receive messages in their raw form. Messages in the data form 3049 consist of a message header followed by an entire new message. There 3050 will be two message headers in a row: one for the SADB_X_PROMISC 3051 message, and one for the payload message. 3052 3053 Data messages sent from the application are sent to either the PF_KEY 3054 socket of a single process identified by a nonzero sadb_msg_seq or to 3055 all PF_KEY sockets if sadb_msg_seq is zero. These messages are sent 3056 without any processing of their contents by the PF_KEY interface 3057 (including sanity checking). This promiscuous-send capability allows 3058 an application to send messages as if it were the kernel. This also 3059 allows it to send erroneous messages. 3060 3061 If the promiscuous-receive function has been enabled, a copy of any 3062 message sent via PF_KEY by another application or by the kernel is 3063 sent to the promiscuous application. This is done before any 3064 processing of the message's contents by the PF_KEY interface (again, 3065 including sanity checking). This promiscuous-receive capability 3066 allows an application to receive all messages sent by other parties 3067 using PF_KEY. 3068 3069 The messaging behavior of the SADB_X_PROMISC message is: 3070 3071 Send a control-form SADB_X_PROMISC message from a user process 3072 to the kernel. 3073 3074 <base> 3075 3076 The kernel returns the SADB_X_PROMISC message to all listening 3077 processes. 3078 3079 3080 3081 3082McDonald, et. al. Informational [Page 55] 3083 3084RFC 2367 PF_KEY Key Management API July 1998 3085 3086 3087 <base> 3088 3089 Send a data-form SADB_X_PROMISC message from a user process to 3090 the kernel. 3091 3092 <base, base(, others)> 3093 3094 The kernel sends the encapsulated message to the target 3095 process(s). 3096 3097 <base(, others)> 3098 3099 If promiscuous-receive is enabled, the kernel will encapsulate 3100 and send copies of all messages sent via the PF_KEY interface. 3101 3102 <base, base(, others)> 3103 3104 Errors: 3105 EPERM Additional privileges are required to perform the 3106 requested operations. 3107 ESRCH (Data form, sending) The target process in sadb_msg_seq 3108 does not exist or does not have an open PF_KEY Version 2 3109 socket. 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138McDonald, et. al. Informational [Page 56] 3139 3140RFC 2367 PF_KEY Key Management API July 1998 3141 3142 3143Appendix B: Passive Change Message Type 3144 3145 The SADB_X_PCHANGE message is a passive-side (aka. the "listener" or 3146 "receiver") counterpart to the SADB_ACQUIRE message. It is useful 3147 for when key management applications wish to more effectively handle 3148 incoming key management requests for passive-side sessions that 3149 deviate from systemwide default security services. If a passive 3150 session requests that only certain levels of security service be 3151 allowed, the SADB_X_PCHANGE message expresses this change to any 3152 registered PF_KEY sockets. Unlike SADB_ACQUIRE, this message is 3153 purely informational, and demands no other PF_KEY interaction. 3154 3155 The SADB_X_PCHANGE message is typically triggered by either a change 3156 in an endpoint's requested security services, or when an endpoint 3157 that made a special request disappears. In the former case, an 3158 SADB_X_PCHANGE looks like an SADB_ACQUIRE, complete with an 3159 sadb_proposal extension indicating the preferred algorithms, 3160 lifetimes, and other attributes. When a passive session either 3161 disappears, or reverts to a default behavior, an SADB_X_PCHANGE will 3162 be issued with _no_ sadb_proposal extension, indicating that the 3163 exception to systemwide default behavior has disappeared. 3164 3165 There are two messaging behaviors for SADB_X_PCHANGE. The first is 3166 the kernel-originated case: 3167 3168 The kernel sends an SADB_X_PCHANGE message to registered 3169 sockets. 3170 3171 <base, address(SD), (identity(SD),) (sensitivity,) (proposal)> 3172 3173 NOTE: The address(SD) extensions MUST have the port fields 3174 filled in with the port numbers of the session 3175 requiring keys if appropriate. 3176 3177 The second is for a user-level consumer of SAs. 3178 3179 Send an SADB_X_PCHANGE message from a user process to the 3180 kernel. 3181 3182 <base, address(SD), (identity(SD),) (sensitivity,) (proposal)> 3183 3184 The kernel returns an SADB_X_PCHANGE message to registered 3185 sockets. 3186 3187 <base, address(SD), (identity(SD),) (sensitivity,) (proposal)> 3188 3189 3190 3191 3192 3193 3194McDonald, et. al. Informational [Page 57] 3195 3196RFC 2367 PF_KEY Key Management API July 1998 3197 3198 3199Appendix C: Key Management Private Data Extension 3200 3201 The Key Management Private Data extension is attached to either an 3202 SADB_ADD or an SADB_UPDATE message. It attaches a single piece of 3203 arbitrary data to a security association. It may be useful for key 3204 managment applications that could use an SADB_DUMP or SADB_GET 3205 message to obtain additional state if it needs to restart or recover 3206 after a crash. The format of this extension is: 3207 3208 #define SADB_X_EXT_KMPRIVATE 17 3209 3210 struct sadb_x_kmprivate { 3211 uint16_t sadb_x_kmprivate_len; 3212 uint16_t sadb_x_kmprivate_exttype; 3213 uint32_t sadb_x_kmprivate_reserved; 3214 }; 3215 /* sizeof(struct sadb_x_kmprivate) == 8 */ 3216 3217 /* followed by arbitrary data */ 3218 3219 3220 The data following the sadb_x_kmprivate extension can be anything. 3221 It will be stored with the actual security association in the kernel. 3222 Like all data, it must be padded to an eight byte boundary. 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250McDonald, et. al. Informational [Page 58] 3251 3252RFC 2367 PF_KEY Key Management API July 1998 3253 3254 3255Appendix D: Sample Header File 3256 3257 /* 3258 This file defines structures and symbols for the PF_KEY Version 2 3259 key management interface. It was written at the U.S. Naval Research 3260 Laboratory. This file is in the public domain. The authors ask that 3261 you leave this credit intact on any copies of this file. 3262 */ 3263 #ifndef __PFKEY_V2_H 3264 #define __PFKEY_V2_H 1 3265 3266 #define PF_KEY_V2 2 3267 #define PFKEYV2_REVISION 199806L 3268 3269 #define SADB_RESERVED 0 3270 #define SADB_GETSPI 1 3271 #define SADB_UPDATE 2 3272 #define SADB_ADD 3 3273 #define SADB_DELETE 4 3274 #define SADB_GET 5 3275 #define SADB_ACQUIRE 6 3276 #define SADB_REGISTER 7 3277 #define SADB_EXPIRE 8 3278 #define SADB_FLUSH 9 3279 #define SADB_DUMP 10 3280 #define SADB_X_PROMISC 11 3281 #define SADB_X_PCHANGE 12 3282 #define SADB_MAX 12 3283 3284 struct sadb_msg { 3285 uint8_t sadb_msg_version; 3286 uint8_t sadb_msg_type; 3287 uint8_t sadb_msg_errno; 3288 uint8_t sadb_msg_satype; 3289 uint16_t sadb_msg_len; 3290 uint16_t sadb_msg_reserved; 3291 uint32_t sadb_msg_seq; 3292 uint32_t sadb_msg_pid; 3293 }; 3294 3295 struct sadb_ext { 3296 uint16_t sadb_ext_len; 3297 uint16_t sadb_ext_type; 3298 }; 3299 3300 struct sadb_sa { 3301 uint16_t sadb_sa_len; 3302 uint16_t sadb_sa_exttype; 3303 3304 3305 3306McDonald, et. al. Informational [Page 59] 3307 3308RFC 2367 PF_KEY Key Management API July 1998 3309 3310 3311 uint32_t sadb_sa_spi; 3312 uint8_t sadb_sa_replay; 3313 uint8_t sadb_sa_state; 3314 uint8_t sadb_sa_auth; 3315 uint8_t sadb_sa_encrypt; 3316 uint32_t sadb_sa_flags; 3317 }; 3318 3319 struct sadb_lifetime { 3320 uint16_t sadb_lifetime_len; 3321 uint16_t sadb_lifetime_exttype; 3322 uint32_t sadb_lifetime_allocations; 3323 uint64_t sadb_lifetime_bytes; 3324 uint64_t sadb_lifetime_addtime; 3325 uint64_t sadb_lifetime_usetime; 3326 }; 3327 3328 struct sadb_address { 3329 uint16_t sadb_address_len; 3330 uint16_t sadb_address_exttype; 3331 uint8_t sadb_address_proto; 3332 uint8_t sadb_address_prefixlen; 3333 uint16_t sadb_address_reserved; 3334 }; 3335 3336 struct sadb_key { 3337 uint16_t sadb_key_len; 3338 uint16_t sadb_key_exttype; 3339 uint16_t sadb_key_bits; 3340 uint16_t sadb_key_reserved; 3341 }; 3342 3343 struct sadb_ident { 3344 uint16_t sadb_ident_len; 3345 uint16_t sadb_ident_exttype; 3346 uint16_t sadb_ident_type; 3347 uint16_t sadb_ident_reserved; 3348 uint64_t sadb_ident_id; 3349 }; 3350 3351 struct sadb_sens { 3352 uint16_t sadb_sens_len; 3353 uint16_t sadb_sens_exttype; 3354 uint32_t sadb_sens_dpd; 3355 uint8_t sadb_sens_sens_level; 3356 uint8_t sadb_sens_sens_len; 3357 uint8_t sadb_sens_integ_level; 3358 uint8_t sadb_sens_integ_len; 3359 3360 3361 3362McDonald, et. al. Informational [Page 60] 3363 3364RFC 2367 PF_KEY Key Management API July 1998 3365 3366 3367 uint32_t sadb_sens_reserved; 3368 }; 3369 3370 struct sadb_prop { 3371 uint16_t sadb_prop_len; 3372 uint16_t sadb_prop_exttype; 3373 uint8_t sadb_prop_replay; 3374 uint8_t sadb_prop_reserved[3]; 3375 }; 3376 3377 struct sadb_comb { 3378 uint8_t sadb_comb_auth; 3379 uint8_t sadb_comb_encrypt; 3380 uint16_t sadb_comb_flags; 3381 uint16_t sadb_comb_auth_minbits; 3382 uint16_t sadb_comb_auth_maxbits; 3383 uint16_t sadb_comb_encrypt_minbits; 3384 uint16_t sadb_comb_encrypt_maxbits; 3385 uint32_t sadb_comb_reserved; 3386 uint32_t sadb_comb_soft_allocations; 3387 uint32_t sadb_comb_hard_allocations; 3388 uint64_t sadb_comb_soft_bytes; 3389 uint64_t sadb_comb_hard_bytes; 3390 uint64_t sadb_comb_soft_addtime; 3391 uint64_t sadb_comb_hard_addtime; 3392 uint64_t sadb_comb_soft_usetime; 3393 uint64_t sadb_comb_hard_usetime; 3394 }; 3395 3396 struct sadb_supported { 3397 uint16_t sadb_supported_len; 3398 uint16_t sadb_supported_exttype; 3399 uint32_t sadb_supported_reserved; 3400 }; 3401 3402 struct sadb_alg { 3403 uint8_t sadb_alg_id; 3404 uint8_t sadb_alg_ivlen; 3405 uint16_t sadb_alg_minbits; 3406 uint16_t sadb_alg_maxbits; 3407 uint16_t sadb_alg_reserved; 3408 }; 3409 3410 struct sadb_spirange { 3411 uint16_t sadb_spirange_len; 3412 uint16_t sadb_spirange_exttype; 3413 uint32_t sadb_spirange_min; 3414 uint32_t sadb_spirange_max; 3415 3416 3417 3418McDonald, et. al. Informational [Page 61] 3419 3420RFC 2367 PF_KEY Key Management API July 1998 3421 3422 3423 uint32_t sadb_spirange_reserved; 3424 }; 3425 3426 struct sadb_x_kmprivate { 3427 uint16_t sadb_x_kmprivate_len; 3428 uint16_t sadb_x_kmprivate_exttype; 3429 uint32_t sadb_x_kmprivate_reserved; 3430 }; 3431 3432 #define SADB_EXT_RESERVED 0 3433 #define SADB_EXT_SA 1 3434 #define SADB_EXT_LIFETIME_CURRENT 2 3435 #define SADB_EXT_LIFETIME_HARD 3 3436 #define SADB_EXT_LIFETIME_SOFT 4 3437 #define SADB_EXT_ADDRESS_SRC 5 3438 #define SADB_EXT_ADDRESS_DST 6 3439 #define SADB_EXT_ADDRESS_PROXY 7 3440 #define SADB_EXT_KEY_AUTH 8 3441 #define SADB_EXT_KEY_ENCRYPT 9 3442 #define SADB_EXT_IDENTITY_SRC 10 3443 #define SADB_EXT_IDENTITY_DST 11 3444 #define SADB_EXT_SENSITIVITY 12 3445 #define SADB_EXT_PROPOSAL 13 3446 #define SADB_EXT_SUPPORTED_AUTH 14 3447 #define SADB_EXT_SUPPORTED_ENCRYPT 15 3448 #define SADB_EXT_SPIRANGE 16 3449 #define SADB_X_EXT_KMPRIVATE 17 3450 #define SADB_EXT_MAX 17 3451 #define SADB_SATYPE_UNSPEC 0 3452 #define SADB_SATYPE_AH 2 3453 #define SADB_SATYPE_ESP 3 3454 #define SADB_SATYPE_RSVP 5 3455 #define SADB_SATYPE_OSPFV2 6 3456 #define SADB_SATYPE_RIPV2 7 3457 #define SADB_SATYPE_MIP 8 3458 #define SADB_SATYPE_MAX 8 3459 3460 #define SADB_SASTATE_LARVAL 0 3461 #define SADB_SASTATE_MATURE 1 3462 #define SADB_SASTATE_DYING 2 3463 #define SADB_SASTATE_DEAD 3 3464 #define SADB_SASTATE_MAX 3 3465 3466 #define SADB_SAFLAGS_PFS 1 3467 3468 #define SADB_AALG_NONE 0 3469 #define SADB_AALG_MD5HMAC 2 3470 #define SADB_AALG_SHA1HMAC 3 3471 3472 3473 3474McDonald, et. al. Informational [Page 62] 3475 3476RFC 2367 PF_KEY Key Management API July 1998 3477 3478 3479 #define SADB_AALG_MAX 3 3480 3481 #define SADB_EALG_NONE 0 3482 #define SADB_EALG_DESCBC 2 3483 #define SADB_EALG_3DESCBC 3 3484 #define SADB_EALG_NULL 11 3485 #define SADB_EALG_MAX 11 3486 3487 #define SADB_IDENTTYPE_RESERVED 0 3488 #define SADB_IDENTTYPE_PREFIX 1 3489 #define SADB_IDENTTYPE_FQDN 2 3490 #define SADB_IDENTTYPE_USERFQDN 3 3491 #define SADB_IDENTTYPE_MAX 3 3492 3493 #define SADB_KEY_FLAGS_MAX 0 3494 #endif /* __PFKEY_V2_H */ 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530McDonald, et. al. Informational [Page 63] 3531 3532RFC 2367 PF_KEY Key Management API July 1998 3533 3534 3535Appendix E: Change Log 3536 3537 The following changes were made between 05 and 06: 3538 3539 * Last change before becoming an informational RFC. Removed all 3540 Internet-Draft references. Also standardized citation strings. 3541 Now cite RFC 2119 for MUST, etc. 3542 3543 * New appendix on optional KM private data extension. 3544 3545 * Fixed example to indicate the ACQUIRE messages with errno mean 3546 KM failure. 3547 3548 * Added SADB_EALG_NULL. 3549 3550 * Clarified proxy examples to match definition of PROXY address being 3551 the inner packet's source address. (Basically a sign-flip. The 3552 example still shows how to protect against policy vulnerabilities 3553 in tunnel endpoints.) 3554 3555 * Loosened definition of a destination address to include broadcast. 3556 3557 * Recommended that LARVAL security associations have implicit short 3558 lifetimes. 3559 3560 The following changes were made between 04 and 05: 3561 3562 * New appendix on Passive Change message. 3563 3564 * New sadb_address_prefixlen field. 3565 3566 * Small clarifications on sadb_ident_id usage. 3567 3568 * New PFKEYV2_REVISION value. 3569 3570 * Small clarification on what a PROXY address is. 3571 3572 * Corrected sadb_spirange_{min,max} language. 3573 3574 * In ADD messages that are in response to an ACQUIRE, the 3575 sadb_msg_seq MUST be the same as that of the originating ACQUIRE. 3576 3577 * Corrected ACQUIRE message behavior, ACQUIRE message SHOULD send up 3578 PROXY addresses when it needs them. 3579 3580 * Clarification on SADB_EXPIRE and user-level security protocols. 3581 3582 The following changes were made between 03 and 04: 3583 3584 3585 3586McDonald, et. al. Informational [Page 64] 3587 3588RFC 2367 PF_KEY Key Management API July 1998 3589 3590 3591 * Stronger language about manual keying. 3592 3593 * PFKEYV2_REVISION, ala POSIX. 3594 3595 * Put in language about sockaddr ports in ACQUIRE messages. 3596 3597 * Mention of asymmetric algorithms. 3598 3599 * New sadb_ident_id field for easier construction of USER_FQDN 3600 identity strings. 3601 3602 * Caveat about source addresses not always used for collision 3603 detection. (e.g. IPsec) 3604 3605 The following changes were made between 02 and 03: 3606 3607 3608 * Formatting changes. 3609 3610 * Many editorial cleanups, rewordings, clarifications. 3611 3612 * Restrictions that prevent many strange and invalid cases. 3613 3614 * Added definitions section. 3615 3616 * Removed connection identity type (this will reappear when it is 3617 more clear what it should look like). 3618 3619 * Removed 5.2.1 (Why involve the kernel?). 3620 3621 * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed 3622 from src, dst, and proxy and you had to anyway for sanity checking. 3623 3624 * Removed REPLAY flag; sadb_sa_replay==0 means the same thing. 3625 3626 * Renamed bit lengths to "bits" to avoid potential confusion. 3627 3628 * Explicitly listed lengths for structures. 3629 3630 * Reworked identities to always use a string format. 3631 3632 * Removed requirements for support of shutdown() and SO_USELOOPBACK. 3633 3634 * 64 bit alignment and 64 bit lengths instead of 32 bit. 3635 3636 * time_t replaced with uint64 in lifetimes. 3637 3638 3639 3640 3641 3642McDonald, et. al. Informational [Page 65] 3643 3644RFC 2367 PF_KEY Key Management API July 1998 3645 3646 3647 * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER 3648 FILE). 3649 3650 * Explicit error if PF_KEY_V2 not set at socket() call. 3651 3652 * More text on SO_USELOOPBACK. 3653 3654 * Made fields names and symbol names more consistent. 3655 3656 * Explicit error if PF_KEY_V2 is not in sadb_msg_version field. 3657 3658 * Bytes lifetime field now a 64-bit quantity. 3659 3660 * Explicit len/exttype wording. 3661 3662 * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.) 3663 3664 * UI example (0x123 == 0x1230 or 0x0123). 3665 3666 * Cleaned up and fixed some message behavior examples. 3667 3668 The following changes were made between 01 and 02: 3669 3670 * Mentioned that people COULD use these same messages between user 3671 progs. (Also mentioned why you still might want to use the actual 3672 socket.) 3673 3674 * Various wordsmithing changes. 3675 3676 * Took out netkey/ directory, and make net/pfkeyv2.h 3677 3678 * Inserted PF_KEY_V2 proto argument per C. Metz. 3679 3680 * Mentioned other socket calls and how their PF_KEY behavior is 3681 undefined. 3682 3683 * SADB_EXPIRE now communicates both hard and soft lifetime expires. 3684 3685 * New "association" extension, even smaller base header. 3686 3687 * Lifetime extension improvements. 3688 3689 * Length now first in extensions. 3690 3691 * Errors can be sent from kernel to user, also. 3692 3693 * Examples section inserted. 3694 3695 3696 3697 3698McDonald, et. al. Informational [Page 66] 3699 3700RFC 2367 PF_KEY Key Management API July 1998 3701 3702 3703 * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup. 3704 3705 * Key splitting now only across auth algorithm and encryption 3706 algorithm. Thanks for B. Sommerfeld for clues here. 3707 3708 The following changes were made between 00 and 01: 3709 3710 * Added this change log. 3711 3712 * Simplified TLV header syntax. 3713 3714 * Splitting of algorithms. This may be controversial, but it allows 3715 PF_KEY to be used for more than just IPsec. It also allows some 3716 kinds of policies to be placed in the KMd easier. 3717 3718 * Added solid definitions and formats for certificate identities, 3719 multiple keys, etc. 3720 3721 * Specified how keys are to be layed out (most-to-least bits). 3722 3723 * Changed sequence number semantics to be like an RPC transaction ID 3724 number. 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754McDonald, et. al. Informational [Page 67] 3755 3756RFC 2367 PF_KEY Key Management API July 1998 3757 3758 3759F. Full Copyright Statement 3760 3761 Copyright (C) The Internet Society (1998). All Rights Reserved. 3762 3763 This document and translations of it may be copied and furnished to 3764 others, and derivative works that comment on or otherwise explain it 3765 or assist in its implementation may be prepared, copied, published 3766 and distributed, in whole or in part, without restriction of any 3767 kind, provided that the above copyright notice and this paragraph are 3768 included on all such copies and derivative works. However, this 3769 document itself may not be modified in any way, such as by removing 3770 the copyright notice or references to the Internet Society or other 3771 Internet organizations, except as needed for the purpose of 3772 developing Internet standards in which case the procedures for 3773 copyrights defined in the Internet Standards process must be 3774 followed, or as required to translate it into languages other than 3775 English. 3776 3777 The limited permissions granted above are perpetual and will not be 3778 revoked by the Internet Society or its successors or assigns. 3779 3780 This document and the information contained herein is provided on an 3781 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3782 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3783 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3784 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3785 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810McDonald, et. al. Informational [Page 68] 3811 3812