idnits 2.17.1 draft-ietf-btns-abstract-api-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 492. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 503. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 510. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 516. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: For connected sockets (UDP, TCP, some SCTP modes, etc.), the protection token MUST not change during the lifetime of the socket, so a simple process is appropriate. ([I-D.ietf-btns-connection-latching]) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 2, 2008) is 5653 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-btns-core' is defined on line 442, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-btns-prob-and-applic' is defined on line 447, but no explicit reference was found in the text == Outdated reference: A later version (-11) exists of draft-ietf-btns-connection-latching-07 ** Downref: Normative reference to an Informational draft: draft-ietf-btns-prob-and-applic (ref. 'I-D.ietf-btns-prob-and-applic') ** Downref: Normative reference to an Informational RFC: RFC 2367 ** Downref: Normative reference to an Experimental RFC: RFC 2692 Summary: 4 errors (**), 0 flaws (~~), 6 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Richardson 3 Internet-Draft SSW 4 Expires: May 6, 2009 November 2, 2008 6 An abstract interface between applications and IPsec 7 draft-ietf-btns-abstract-api-02.txt 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on May 6, 2009. 34 Copyright Notice 36 Copyright (C) The IETF Trust (2008). 38 Abstract 40 This document explains in the abstract (no language bindings are 41 provided) how an application may learn that IPsec has been applied to 42 a conversation or specify that IPsec should be used. Though this is 43 useful in general it is particularly useful for applications that 44 wish to use BTNS (Better Than Nothing Security -- a mode of IPsec 45 keying), either in conjunction with channel binding or otherwise. 47 Table of Contents 49 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 51 3. Objects involved . . . . . . . . . . . . . . . . . . . . . 5 52 3.1. Scope of Protection Token . . . . . . . . . . . . . . . . 5 53 3.2. Scope of Identity Token . . . . . . . . . . . . . . . . . 6 54 3.3. Validity period of Protection Token . . . . . . . . . . . 6 55 3.4. Validity period of Identity Token . . . . . . . . . . . . 6 56 3.5. Serialization . . . . . . . . . . . . . . . . . . . . . . 6 57 3.5.1. Serialization of Protection Token . . . . . . . . . . . . 6 58 3.5.2. Serialization of Identity Token . . . . . . . . . . . . . 7 59 4. Name space . . . . . . . . . . . . . . . . . . . . . . . . 8 60 5. pToken discovery . . . . . . . . . . . . . . . . . . . . . 9 61 6. pToken templates . . . . . . . . . . . . . . . . . . . . . 10 62 7. Properties of pToken objects . . . . . . . . . . . . . . . 11 63 8. Properties of iToken objects . . . . . . . . . . . . . . . 12 64 9. Accessors Functions . . . . . . . . . . . . . . . . . . . 14 65 10. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 15 66 11. Security Considerations . . . . . . . . . . . . . . . . . 16 67 12. IANA Considerations . . . . . . . . . . . . . . . . . . . 17 68 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 18 69 14. TRACKING . . . . . . . . . . . . . . . . . . . . . . . . . 19 70 15. References . . . . . . . . . . . . . . . . . . . . . . . . 21 71 15.1. Normative references . . . . . . . . . . . . . . . . . . . 21 72 15.2. Non-normative references . . . . . . . . . . . . . . . . . 21 73 Author's Address . . . . . . . . . . . . . . . . . . . . . 22 74 Intellectual Property and Copyright Statements . . . . . . 23 76 1. Overview 78 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 79 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 80 document are to be interpreted as described in RFC2119 [RFC2119]. 82 2. Introduction 84 Implementation of application protocols that depend on IPsec 85 [RFC4301] tend to depend on configuration of IPsec, without having 86 any portable (or even non-portable) way to ensure that IPsec is being 87 used properly. This state of affairs is unfortunate, as it limits 88 use of IPsec and encourages applications not to rely on IPsec, which 89 in environments that do use IPsec, may lead to redundant 90 cryptographic protection layers. 92 This document describes an abstract application programming interface 93 (API) that is intended to interface applications with IPsec. It is 94 abstract in that no programming language specific bindings are given 95 here, nor is this API specified in terms of familiar APIs such as the 96 "BSD sockets API," for example. Programming language specific 97 bindings, and operating system specific bindings are left to other 98 documents. 100 3. Objects involved 102 There are two major kinds of objects that are defined by this 103 document. These are the Protection Token (pToken) and the Identity 104 Token (iToken). Both objects are abstracted into unique opaque 105 tokens which may be manipulated only indirectly by applications. 106 Here we use the term "opaque token" to mean much what "object" means 107 in a typical object-oriented programming language, but with no public 108 fields (only methods or generic functions). Additionally, the iToken 109 may be serialized -- that is, converted, by application of a suitable 110 function, into an octet string that can later be imported to create a 111 new iToken object that is equivalent to the original (though a value 112 equality test applied to both iTokens may fail). 114 Each object has a series of attributes associated with it. The API 115 provides a mechanism to query the value of attributes of the token. 116 The attributes are where all of the content of the objects are. 118 Each token has a scope - the place and time in which it can be 119 considered valid. There are many conflicting qualities that one 120 would wish for the token, and the result is a different compromise 121 among these qualities for each token type. The tokens should be: 123 easy to allocate and release 125 automatically cleaned up when an application terminates (both 126 properly and improperly) 128 easily compared (for equivalence) 130 easily interfaced with existing APIs (such as the BSD sockets API, 131 in that case as "auxiliary data") 133 We use terms such as "process" and "address space" without explaining 134 them or providing references, much as with "object." The terms refer 135 to pervasive, common concepts in operating systems theory and 136 practice over the past several decades. 138 3.1. Scope of Protection Token 140 The protection token has a per-process (i.e. per-address space) 141 scope, though it may be inherited by child processes in operating 142 systems that have a "fork()" operation. It SHOULD always be possible 143 to obtain a current protection token for an established connection 144 (whether for a connection-oriented transport protocol or for a 145 "connected" UDP socket). that is equivalent to any previous 146 protection token that was obtained. The scope of the token is not 147 related to any specific underlying Security Associations used by 148 IPsec, but to the entire set of past, current and future SAs that 149 will be used by IPsec to protect that connection 150 [I-D.ietf-btns-connection-latching]. 152 3.2. Scope of Identity Token 154 The identity token also has a per-process scope, but is serializable 155 such that its serialized form has a per-system or even universal, 156 scope. (We have to consider whether we want universal scope for 157 serialized iTokens, much as with exported name objects in the GSS- 158 API, which would mean agreeing on a standard, extensible 159 representation and encoding.) 161 3.3. Validity period of Protection Token 163 A pToken is valid only within the scope of a single process (though 164 it may be inherited by child processes which share the parent's 165 address space with copy on write semantics). The token may not be 166 serialized, and, therefore, may not be saved in any long term 167 storage. 169 It is permitted for one protection token to be replaced with another 170 (equivalent) protection token due to a node moving, suspending and 171 resuming, or due to extended network outages, however the underlying 172 identity token would be guaranteed to be the same. This would most 173 likely occur with unconnected sockets, where due to the outage/ 174 downtime, the keying system was unable to maintain a keying channel, 175 and had to re-create the keys from scratch. 177 3.4. Validity period of Identity Token 179 The iToken may be valid across the entire system, although it may 180 need to be turned into an external representation (serialization). 181 Some forms of identity token may be valid across systems, but in 182 general an identity token is only valid in reference to a local 183 policy. (See [RFC2692]). 185 3.5. Serialization 187 Serialization refers to the process of turning an in memory object 188 into a format which can be saved on disk, and re-imported by the same 189 implementation. This document does not require a specification for 190 the serialization format, only that it be possible. The format is a 191 local matter. 193 3.5.1. Serialization of Protection Token 195 There is no requirement to serialize the protection token, or the 196 attributes contained within. There is a desire to serialize 197 templates for protection tokens such that a set of minimum security 198 requirements can be saved for future connections to the same peer. 200 3.5.2. Serialization of Identity Token 202 There is a desire to be able to to serialize the identity token in 203 such a way that future communications can be confirmed to be with the 204 same identity as before. 206 4. Name space 208 All symbols (functions, macros, etc.) defined by this API are 209 prefixed with "ipsec_". Specific rules for capitalizations should be 210 driven by the specific language binding. 212 Whenever sensible, the enumerated values defined in [RFC2367] are 213 used if appropriate. 215 5. pToken discovery 217 An application that receives a connection using accept(2) (or 218 recvmsg(2)), or makes a connection using connect(2), needs to get a 219 protection token that is associated with the socket. 221 For connected sockets (UDP, TCP, some SCTP modes, etc.), the 222 protection token MUST not change during the lifetime of the socket, 223 so a simple process is appropriate. 224 ([I-D.ietf-btns-connection-latching]) 226 As the pToken will not change during the connection. (see notes about 227 re-keying). A simple function is provided to return a pToken from a 228 file descriptor. Many implementations are likely to implement this 229 using getsockopt(2), but an interface in those terms is not specified 230 in order to keep it more abstract, and therefore more portable. 232 For unconnected sockets (such as UDP and some SCTP modes), each 233 datagram received may be received may arrive from a different source, 234 and therefore may have different protections applied. A protection 235 token needs to be returned with each datagram, so it must be returned 236 as ancillary data with recvmsg(2). 238 A server using unconnected sockets, would receive a protection token 239 as ancillary data, and then would provide the same protection token 240 as ancillary data on the corresponding sendmsg(2) call. 242 6. pToken templates 244 A pToken template is a type of pToken which is used only when setting 245 up a connection, or setting up a socket to listen for connections. 247 Properties which are not set on a pToken, are assumed to be do-not- 248 care values. 250 7. Properties of pToken objects 252 privacyProtected - boolean. Set to false if the connection has 253 either no privacy configured (AH, ESP-null), or if the privacy 254 configured is known to be untrustworthy by the administrator. 255 Returns true otherwise. (XXX: False does not mean that there will 256 be no IPsec, but that it should not be considered useful) 258 integrityProtected - boolean. Set to false if there is no data 259 integrity protection other than the UDP/TCP checksum. 261 compressionAvailable - boolean. Set to true if data count sent/ 262 received from socket may not map linearly to data sent/received on 263 wire. 265 policyName - string. A handle which describes the system policy 266 which was used (or is desired), to establish the connection. This 267 is a string, such as: "secure", "ospf", "iSCSI", "very-secure", 268 "do-not-tell-mom-secure", "minimum-security", "was-posted-on- 269 usenet-security". 271 iToken - object. Set to iToken object which represents identity 272 of remote system. 274 remote_iToken - object. Set to iToken object which was used to 275 represent our identity to the remote system. 277 tunnelMode - boolean. Set if tunnel mode was used, or if it is 278 desired. 280 ipoptionsProtected - boolean. Set if ip options (and IPv6 header 281 extensions), are protected. 283 auditString - string. readonly. Not part of a template. Valid 284 only after connection establishment. Contains a string which can 285 be used in system auditing and logging functions which describes 286 the details of the IPsec SA that was negotiated. No structure of 287 this string may be assumed. No session keys are disclosed by this 288 string. 290 informationString - string. readonly. Not part of a template. 291 Valid only after connection establishment. Contains a string 292 which can be displayed to a user, informing them of what kind of 293 security association was established for this connection. This 294 string may be localized. No session keys are disclosed by this 295 string. 297 8. Properties of iToken objects 299 auditString - string. readonly on responder and readonly on 300 initiator after connection establishment. Contains a string which 301 can be used in system auditing and logging functions which 302 describes the remote identity, and the method by which it was 303 authenticated (i.e. it may list the CA or origin of a public key) 305 authenticationMethod - enumerated type. Indicates which method 306 was used to authenticate the peer, possible values are: 308 NONE - the peer was not authenticated in anyway 310 BTNS - the peer was authenticated using an inline key which was 311 not verified in anyway 313 LEAPOFFAITH - the peer was authenticated using a key which was 314 previously cached, but was previously received inline, and was 315 not verified in anyway. 317 PRESHAREDKEY - the peer was authenticated using a unique pre- 318 shared key 320 GROUPKEY - the peer was authenticated using a non-unique pre- 321 shared key 323 XAUTH - the type of phase1/PARENT-SA is not relevant, as the 324 peer was authenticated using a username/password. 326 EAP - the type of phase1/PARENT-SA is not relevant, as the peer 327 was authenticated using an EAP method. (Additional properties 328 may provide more information) 330 PKIX_TRUSTED - the peer was authenticated using a PKIX/X.509 331 certificate that was found in the trusted store. 333 PKIX_INLINE - the peer was authenticated using a PKIX/X.509 334 certificate that was transmitted inline, and was verified by 335 using a Certificate Authority that was found in the trusted 336 store. 338 PKIX_OFFLINE - the peer was authenticated using a PKIX/X.509 339 certificate that was retrieved out-of-band (such as by LDAP or 340 HTTP), and was verified by using a Certificate Authority that 341 was found in the trusted store. 343 certificateAuthorityDN - string. readonly. the Distinguished Name 344 (DN) of certificate authority that was used to verify the key (for 345 methods that involved PKIX) 347 certificateDN - string. readonly. the DN of the peer that was 348 authenticated 350 pubKeyID - string. readonly. a somewhat unique identifier for the 351 public key. A suggestion is to use the first 9 base64 digits of 352 the RFC3110 public key modulus, but this is a local matter. 354 channelBinding - binary blog. readonly. provides the concatenated 355 set of public keys 357 9. Accessors Functions 359 Methods to access the properties of the two objects are specific to 360 the language in which the bindings are done. See YYYY for 361 C-bindings. 363 10. Use Cases 365 Explain slides from IETF68. 367 11. Security Considerations 369 Probably lots to say here. Please help. 371 12. IANA Considerations 373 There are no registries created by this document. The names (and 374 language specific enum, if applicable) of the pToken and iToken 375 properties are internal to a single system, and therefore do not need 376 standardization. 378 13. Acknowledgments 380 stuff 382 14. TRACKING 384 Document RCS tracking info 386 $Revision: 1.7 $ 387 $Log: ietf-btns-abstract-api.xml,v $ 388 Revision 1.7 2008/11/03 02:45:52 mcr 389 spell check and updated references 391 Revision 1.6 2008/02/18 02:37:45 mcr 392 updated edits. 394 Revision 1.5 2007/07/24 22:15:51 nico 396 New abstract, new intro, various minor changes (scope of objects, 397 etc...). 399 Revision 1.4 2007/07/24 03:30:19 mcr 400 edits to token scope, in collaboration with Nico. 402 Revision 1.3 2007/07/19 20:09:50 mcr 403 added more properties to describe the type of the SA. 405 Revision 1.2 2007/07/19 19:45:55 mcr 406 edits from 2007-07-19 discussion. 408 Revision 1.1 2007/06/25 15:34:08 mcr 409 renamed drafts in Makefile 411 Revision 1.3 2007/05/14 19:56:37 mcr 412 added abstract 414 Revision 1.2 2007/05/12 20:38:56 mcr 415 fixed id string 417 Revision 1.1 2007/05/12 01:31:00 mcr 418 updates to abstract api document 420 Revision 1.4 2007/02/16 03:24:09 mcr 421 updated to make XML happy, and dates corrected 422 Revision 1.3 2007/02/16 03:04:44 mcr 423 C API document. 424 Revision 1.2 2006/03/21 22:02:47 mcr 425 added API requirements and skeleton of original API spec 426 Revision 1.1 2006/03/21 21:04:43 mcr 427 added documents from ipsp WG 428 Revision 1.1 2003/06/03 20:45:06 mcr 429 initial template 431 Figure 1: document tracking 433 15. References 435 15.1. Normative references 437 [I-D.ietf-btns-connection-latching] 438 Williams, N., "IPsec Channels: Connection Latching", 439 draft-ietf-btns-connection-latching-07 (work in progress), 440 April 2008. 442 [I-D.ietf-btns-core] 443 Williams, N. and M. Richardson, "Better-Than-Nothing- 444 Security: An Unauthenticated Mode of IPsec", 445 draft-ietf-btns-core-07 (work in progress), August 2008. 447 [I-D.ietf-btns-prob-and-applic] 448 Touch, J., Black, D., and Y. Wang, "Problem and 449 Applicability Statement for Better Than Nothing Security 450 (BTNS)", draft-ietf-btns-prob-and-applic-07 (work in 451 progress), July 2008. 453 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 454 Requirement Levels", BCP 14, RFC 2119, March 1997. 456 [RFC2367] McDonald, D., Metz, C., and B. Phan, "PF_KEY Key 457 Management API, Version 2", RFC 2367, July 1998. 459 [RFC2692] Ellison, C., "SPKI Requirements", RFC 2692, 460 September 1999. 462 15.2. Non-normative references 464 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 465 Internet Protocol", RFC 4301, December 2005. 467 Author's Address 469 Michael C. Richardson 470 Sandelman Software Works 471 470 Dawson Avenue 472 Ottawa, ON K1Z 5V7 473 CA 475 Email: mcr@sandelman.ottawa.on.ca 476 URI: http://www.sandelman.ottawa.on.ca/ 478 Full Copyright Statement 480 Copyright (C) The IETF Trust (2008). 482 This document is subject to the rights, licenses and restrictions 483 contained in BCP 78, and except as set forth therein, the authors 484 retain all their rights. 486 This document and the information contained herein are provided on an 487 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 488 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 489 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 490 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 491 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 492 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 494 Intellectual Property 496 The IETF takes no position regarding the validity or scope of any 497 Intellectual Property Rights or other rights that might be claimed to 498 pertain to the implementation or use of the technology described in 499 this document or the extent to which any license under such rights 500 might or might not be available; nor does it represent that it has 501 made any independent effort to identify any such rights. Information 502 on the procedures with respect to rights in RFC documents can be 503 found in BCP 78 and BCP 79. 505 Copies of IPR disclosures made to the IETF Secretariat and any 506 assurances of licenses to be made available, or the result of an 507 attempt made to obtain a general license or permission for the use of 508 such proprietary rights by implementers or users of this 509 specification can be obtained from the IETF on-line IPR repository at 510 http://www.ietf.org/ipr. 512 The IETF invites any interested party to bring to its attention any 513 copyrights, patents or patent applications, or other proprietary 514 rights that may cover technology that may be required to implement 515 this standard. Please address the information to the IETF at 516 ietf-ipr@ietf.org. 518 Acknowledgment 520 Funding for the RFC Editor function is provided by the IETF 521 Administrative Support Activity (IASA).