idnits 2.17.1 draft-ietf-btns-abstract-api-00.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 360. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 371. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 378. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 384. 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 == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- 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 (June 25, 2007) is 6122 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: 'RFC4301' is defined on line 332, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 2367 ** Downref: Normative reference to an Experimental RFC: RFC 2692 Summary: 3 errors (**), 0 flaws (~~), 4 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: December 27, 2007 June 25, 2007 6 An interface between applications and keying systems 7 draft-ietf-btns-abstract-api-00.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 December 27, 2007. 34 Copyright Notice 36 Copyright (C) The IETF Trust (2007). 38 Abstract 40 The "BTNS" (Better Than Nothing Security) protocols specifies how to 41 use IKEv1 and IKEv2 to do unauthenticated IPsec. This document 42 explains in the abstract (no language bindings are provided) how an 43 application may learn that BTNS IPsec has been applied to a 44 conversation, such that the application can plan to do it's own 45 authentication using a channel binding. In addition, applications 46 can use this API (Application Programming Interface) to request BTNS 47 treatment of the applications' connections. 49 Table of Contents 51 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 53 3. Objects involved . . . . . . . . . . . . . . . . . . . . . . 5 54 3.1. Scope of Protection Token . . . . . . . . . . . . . . . . . 5 55 3.2. Scope of Identity Token . . . . . . . . . . . . . . . . . . 5 56 3.3. Validity period of Protection Token . . . . . . . . . . . . 5 57 3.4. Validity period of Identity Token . . . . . . . . . . . . . 6 58 4. Namespace . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 5. pToken discovery . . . . . . . . . . . . . . . . . . . . . . 8 60 6. Properties of pToken objects . . . . . . . . . . . . . . . . 9 61 7. Properties of iToken objects . . . . . . . . . . . . . . . . 10 62 8. Accessor Functions . . . . . . . . . . . . . . . . . . . . . 12 63 9. Security Considerations . . . . . . . . . . . . . . . . . . 13 64 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 14 65 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 15 66 12. TRACKING . . . . . . . . . . . . . . . . . . . . . . . . . . 16 67 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 68 13.1. Normative references . . . . . . . . . . . . . . . . . . . . 17 69 13.2. Non-normative references . . . . . . . . . . . . . . . . . . 17 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . 18 71 Intellectual Property and Copyright Statements . . . . . . . 19 73 1. Overview 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in RFC2119 [RFC2119]. 79 2. Introduction 81 Purpose of this API. 83 3. Objects involved 85 There are two major kinds of objects that are defined by this 86 document. These are the Protection Token (pToken) and the Identity 87 Token (iToken). Both objects are abstracted into unique opaque 88 tokens which may be manipulated only indirectly by applications. 90 Each object has a series of attributes associated with it. The API 91 provides a mechanism to query the value of attributes of the token. 92 The attributes are where all of the content of the objects are. 94 Each token has a scope - the place and time in which it can be 95 considered valid. There are many conflicting qualities that one 96 would wish for the token, and the result is a different compromise 97 among these qualities for each token type. The tokens should be: 99 small 101 easy to allocate and deallocate 103 automatically cleaned up when an application terminates (both 104 properly and inproperly) 106 easily compared 108 easily passed back in a recvmsg(2) call as auxiliary data (for 109 pToken) 111 3.1. Scope of Protection Token 113 The protection token has a per-process (i.e. per-address space) 114 scope. The scope of the token is not related to the underlying 115 protection provided by IPsec. The token is a handle. 117 3.2. Scope of Identity Token 119 The identity token has a per-system scope, although two applications 120 running on the same system may not be able to compare it literally. 122 3.3. Validity period of Protection Token 124 The pToken is valid only within the scope of a single process. The 125 token may not be saved in any long term storage. 127 It is permitted for one protection token to be replaced with another 128 (equivalent) protection token due to a node moving, suspending and 129 resuming, or due to extended network outages, however the underlying 130 identity token would be guaranteed to be the same. This would most 131 likely occur with unconnected sockets, where due to the outage/ 132 downtime, the keying system was unable to maintain a keying channel, 133 and had to re-create the keys from scratch. 135 3.4. Validity period of Identity Token 137 The iToken may be valid across the entire system, although it may 138 need to be turned into an external representation. Some forms of 139 identity token may be valid across systems, but in general an 140 identity token is only valid in reference to a local set of trust 141 anchors. (See [RFC2692]). 143 4. Namespace 145 All functions and macros defined by this API are prefixed with 146 "ipsec_" for functions and variables, and with "IPSEC_" if they are 147 macros or enumerated types. (cf. to appropriate POSIX section?) 149 Whenever sensible, the enumerated values defined in [RFC2367] are 150 used if appropriate. 152 5. pToken discovery 154 An application that receives a connection using accept(2), or with 155 recvmsg(2) needs to get a protection token that is associated with 156 the socket. 158 For connected sockets (such as TCP and some SCTP modes), the 159 protection token should not change during the lifetime of the socket, 160 so a simple process is appropriate. 162 For unconnected sockets (such as UDP and some SCTP modes), each 163 datagram received may be received may arrive from a different source, 164 and therefore may have different protections applied. A protection 165 token needs to be returned with each datagram, so it must be returned 166 as ancilliary data with recvmsg(2). 168 For connected sockets, the pToken will not change during the 169 connection. (see notes about rekeying). A simple function is 170 provided to return a pToken from a file descriptor. Many 171 implementions are likely to implement this using getsockopt(2), but 172 an interface in those terms is not specified in order to keep it more 173 abstract, and therefore more portable. 175 6. Properties of pToken objects 177 privacyProtected - boolean. readonly on responder, get/set on 178 initiator. set to false if the connection has either no privacy 179 configured (AH, ESP-null), or if the privacy configured is known 180 to be untrustworthy by the administrator. Returns true otherwise. 181 (XXX: False does not mean that there will be no IPsec, but that it 182 should not be considered useful) 184 integrityProtected - boolean. readonly on responder, get/set on 185 initiator. set to false if there is no data integrity protection 186 other than the UDP/TCP checksum. 188 compressionAvailable - boolean. readonly on responder, get/set on 189 initiator. Set to true if data count sent/received from socket 190 may not map linearly to data sent/received on wire. 192 iToken - object. readonly on responder. get/set on initiator. Set 193 to iToken object which represents identity of remote system. 195 auditString - string. readonly on responder and readonly on 196 initiator after connection establishment. Contains a string which 197 can be used in system auditing and logging functions which 198 describes the details of the IPsec SA that was negotiated. No 199 structure of this string may be assumed. No session keys are 200 disclosed by this string. 202 7. Properties of iToken objects 204 auditString - string. readonly on responder and readonly on 205 initiator after connection establishment. Contains a string which 206 can be used in system auditing and logging functions which 207 describes the remote identity, and the method by which it was 208 authenticated (i.e. it may list the CA or origin of a public key) 210 authenticationMethod - enumerated type. Indicates which method 211 was used to authenticate the peer, possible values are: 213 NONE - the peer was not authenticated in anyway 215 BTNS - the peer was authenticated using an inline key which was 216 not verified in anyway 218 LEAFOFFAITH - the peer was authenticated using a key which was 219 previously cached, but was previously received inline, and was 220 not verified in anyway. 222 PRESHAREDKEY - the peer was authenticated using a unique pre- 223 shared key 225 GROUPKEY - the peer was authenticated using a non-unique pre- 226 shared key 228 XAUTH - the type of phase1/PARENT-SA is not relevant, as the 229 peer was authenticated using a username/password. 231 EAP - the type of phase1/PARENT-SA is not relevant, as the peer 232 was authenticated using an EAP method. (Additional properties 233 may provide more information) 235 PKIX_TRUSTED - the peer was authenticated using a PKIX/X.509 236 certificate that was found in the trusted store. 238 PKIX_INLINE - the peer was authenticated using a PKIX/X.509 239 certificate that was transmitted inline, and was verified by 240 using a Certificate Authority that was found in the trusted 241 store. 243 PKIX_OFFLINE - the peer was authenticated using a PKIX/X.509 244 certificate that was retrieved out-of-band (such as by LDAP or 245 HTTP), and was verified by using a Certificate Authority that 246 was found in the trusted store. 248 certificateAuthorityDN - string. readonly. the Distinguished Name 249 (DN) of certificate authority that was used to verify the key (for 250 methods that involved PKIX) 252 certificateDN - string. readonly. the DN of the peer that was 253 authenticated 255 pubKeyID - string. readonly. a somewhat unique identifier for the 256 public key. A suggestion is to use the first 9 base64 digits of 257 the RFC3110 public key modulus, but this is a local matter. 259 channelBinding - binary blog. readonly. provides the concatenated 260 set of public keys 262 8. Accessor Functions 264 Methods to access the properties of the two objects are specific to 265 the language in which the bindings are done. See YYYY for 266 C-bindings. 268 9. Security Considerations 270 Probably lots to say here. Please help. 272 10. IANA Considerations 274 There are no registries created by this document. The names (and 275 language specific enum, if applicable) of the pToken and iToken 276 proprties are internal to a single system, and therefore do not need 277 standization. 279 11. Acknowledgments 281 stuff 283 12. TRACKING 285 Document RCS tracking info 287 $Revision: 1.1 $ 288 $Log: ietf-btns-abstract-api-00.txt,v $ 289 Revision 1.1 2007/06/25 15:37:06 mcr 290 added ietf-btns-abstract-api 292 Revision 1.1 2007/06/25 15:34:08 mcr 293 renamed drafts in Makefile 295 Revision 1.3 2007/05/14 19:56:37 mcr 296 added abstract 298 Revision 1.2 2007/05/12 20:38:56 mcr 299 fixed id string 301 Revision 1.1 2007/05/12 01:31:00 mcr 302 updates to abstract api document 304 Revision 1.4 2007/02/16 03:24:09 mcr 305 updated to make XML happy, and dates corrected 306 Revision 1.3 2007/02/16 03:04:44 mcr 307 C API document. 308 Revision 1.2 2006/03/21 22:02:47 mcr 309 added API requirements and skeleton of original API spec 310 Revision 1.1 2006/03/21 21:04:43 mcr 311 added documents from ipsp WG 312 Revision 1.1 2003/06/03 20:45:06 mcr 313 initial template 315 Figure 1: document tracking 317 13. References 319 13.1. Normative references 321 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 322 Requirement Levels", BCP 14, RFC 2119, March 1997. 324 [RFC2367] McDonald, D., Metz, C., and B. Phan, "PF_KEY Key 325 Management API, Version 2", RFC 2367, July 1998. 327 [RFC2692] Ellison, C., "SPKI Requirements", RFC 2692, 328 September 1999. 330 13.2. Non-normative references 332 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 333 Internet Protocol", RFC 4301, December 2005. 335 Author's Address 337 Michael C. Richardson 338 Sandelman Software Works 339 470 Dawson Avenue 340 Ottawa, ON K1Z 5V7 341 CA 343 Email: mcr@sandelman.ottawa.on.ca 344 URI: http://www.sandelman.ottawa.on.ca/ 346 Full Copyright Statement 348 Copyright (C) The IETF Trust (2007). 350 This document is subject to the rights, licenses and restrictions 351 contained in BCP 78, and except as set forth therein, the authors 352 retain all their rights. 354 This document and the information contained herein are provided on an 355 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 356 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 357 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 358 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 359 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 360 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 362 Intellectual Property 364 The IETF takes no position regarding the validity or scope of any 365 Intellectual Property Rights or other rights that might be claimed to 366 pertain to the implementation or use of the technology described in 367 this document or the extent to which any license under such rights 368 might or might not be available; nor does it represent that it has 369 made any independent effort to identify any such rights. Information 370 on the procedures with respect to rights in RFC documents can be 371 found in BCP 78 and BCP 79. 373 Copies of IPR disclosures made to the IETF Secretariat and any 374 assurances of licenses to be made available, or the result of an 375 attempt made to obtain a general license or permission for the use of 376 such proprietary rights by implementers or users of this 377 specification can be obtained from the IETF on-line IPR repository at 378 http://www.ietf.org/ipr. 380 The IETF invites any interested party to bring to its attention any 381 copyrights, patents or patent applications, or other proprietary 382 rights that may cover technology that may be required to implement 383 this standard. Please address the information to the IETF at 384 ietf-ipr@ietf.org. 386 Acknowledgment 388 Funding for the RFC Editor function is provided by the IETF 389 Administrative Support Activity (IASA).