idnits 2.17.1 draft-ietf-btns-channel-binding-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 9, 2009) is 5489 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-btns-abstract-api' is defined on line 287, but no explicit reference was found in the text == Unused Reference: 'I-D.bellovin-useipsec' is defined on line 315, but no explicit reference was found in the text == Unused Reference: 'I-D.dondeti-useipsec-430x' is defined on line 320, but no explicit reference was found in the text -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-btns-abstract-api' == Outdated reference: A later version (-11) exists of draft-ietf-btns-connection-latching-09 ** Obsolete normative reference: RFC 4306 (Obsoleted by RFC 5996) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETWORK WORKING GROUP N. Williams 3 Internet-Draft Sun 4 Intended status: Standards Track April 9, 2009 5 Expires: October 11, 2009 7 IPsec End-Point Channel Bindings and API 8 draft-ietf-btns-channel-binding-api-00.txt 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on October 11, 2009. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This document defines channel bindings for IPsec and describes an 47 abstract API and a BSD sockets API extension for obtaining channel 48 bindings of "connection latches". 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Conventions used in this document . . . . . . . . . . . . . . 3 54 2. End-Point Channel Binding Types for IPsec . . . . . . . . . . 3 55 2.1. ipsec-end-point-sha256 . . . . . . . . . . . . . . . . . . . 3 56 2.2. ipsec-responder-end-point . . . . . . . . . . . . . . . . . . 4 57 2.3. Hash Agility and Channel Binding Type Negotiation . . . . . . 4 58 3. Abstract API . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4. BSD Sockets C API . . . . . . . . . . . . . . . . . . . . . . 5 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 63 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 8.1. Normative References . . . . . . . . . . . . . . . . . . . . 7 65 8.2. Informative References . . . . . . . . . . . . . . . . . . . 8 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . 8 68 1. Introduction 70 With connection latching [I-D.ietf-btns-connection-latching] IPsec 71 now has a notion of "secure channel" that can be used in conjunction 72 with channel binding [RFC5056]. This document defines the channel 73 bindings for IPsec channels where each peers use public keys to 74 authenticate to the other. It also provides an abstract API for 75 accessing the channel bindings of an IPsec channel. And it provides 76 a BSD sockets C language binding of that abstract API. 78 We assume reader familiarity with channel binding [RFC5056], IPsec 79 [RFC4301] and connection latching 80 [I-D.ietf-btns-connection-latching]. 82 These channel binding types also work with Better Than Nothing 83 Security (BTNS) [RFC5386] [RFC5387], and make its use safe. 85 1.1. Conventions used in this document 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 89 document are to be interpreted as described in [RFC2119]. 91 2. End-Point Channel Binding Types for IPsec 93 We define several end-point channel bindings suitable for any IPsec 94 channel where one or both peers are authenticated by a public key. 95 These channel binding types use a hash function whereas they could 96 use the raw un-hashed inputs. We use a hash function so as to 97 produce manageably sized channel binding data (consider that this 98 data often has to be held in kernel memory). 100 2.1. ipsec-end-point-sha256 102 Given a channel C, initiator public key PKi, and responder public key 103 PKr: 105 ipsec-end-point-sha256(C) := SHA256(PKi) XOR SHA256(PKr) 107 The reason for the XOR is that in IPsec there's no deterministic rule 108 for which peer will be an IKE initiator or responder. It is possible 109 for both peers to have been initiators of Security Associtiations 110 (SAs) used in the connection latching 111 [I-D.ietf-btns-connection-latching] process, thus we need an 112 operation that binds both peers' public keys without any kind of 113 order (we don't want to do any sorting). 115 PKi and PKr MUST be the bytes that appear as the value of the 116 subjectPublicKeyInfo field (including the DER/BER TLV 117 [CCITT.X690.2002]) of the corresponding certificates as sent in CERT 118 payloads, or, in the case of Raw RSA keys, the bytes that appear in 119 the peer's CERT payload (see section 3.6 of [RFC4306]). 121 2.2. ipsec-responder-end-point 123 Given a channel C where only one peer authenticated via a public key 124 PKp (and the other, presumably, via EAP): 126 ipsec-single-end-point-sha256(C) := SHA256(PKp) 128 PKp is encoded as described in the previous section. 130 2.3. Hash Agility and Channel Binding Type Negotiation 132 Hash agility is obtained by negotiating channel binding types. 133 Variants of ipsec-end-point-sha256 based on other hash functions can 134 be added as needed. 136 Note that there's no in-band channel binding type negotiation in 137 IKEv2 [RFC4306]. It's possible and preferable that the peer's 138 available channel binding types be determined from IKEv2 context. 140 The algorithm or protocol for deciding the availability of any given 141 variant of ipsec-end-point-sha256 MUST be specified by any such 142 variant. For example, a putative ipsec-end-point-sha3 could be 143 available if a putative SHA-3 function were used in any part of the 144 IKEv2 exchanges that setup an SA linked to a connection latch. Or 145 NOTIFY payloads might be added to IKEv2 for negotiating the use of a 146 putative ipsec-end-point-sha3. 148 ipsec-end-point-sha256 MUST always be available (at least until SHA- 149 256 is deprecated). 151 3. Abstract API 153 To use channel binding to IPsec channels applications MUST first 154 indicate their intention to do so and MAY provide a set of channel 155 binding types that the application prefers. This should be done as 156 part of the procedure to actively connect to peers or passively 157 accept connections from peers. 159 Once an IPsec channel is established the application may then request 160 the channel's channel binding data for a specific channel binding 161 type. 163 4. BSD Sockets C API 165 We define three socket options for the IPPROTO_IP socket level: 166 o IP_SEC_CBINDING, a socket option to be used prior to calling 167 connect() and listen() or accept(). Applications MUST use this 168 socket option to indicate their intention to used channel binding. 169 This option does not take an argument; the actual socket option 170 argument passed by the caller MUST be NULL. 171 o IP_SEC_CBINDING_TYPES, a socket option that applications can use 172 after a connection is established to determine what channel 173 binding types are available. This option takes as argument a 174 pointer to a memory buffer into which an ordered list of channel 175 binding type names will be written, separated by ASCII colons 176 (':') and terminated by a NUL. If the provided buffer is too 177 small then an error must be returned (EOVERFLOW?). 178 o IP_SEC_CBINDING_DATA, a socket option that applications can use 179 after a connection is established to obtain the channel binding 180 data for the given socket and the given channel binding type. 181 This option takes as argument a pointer to a memory buffer 182 containing the name of the requested channel binding type followed 183 by an ASCII colon (':') and enough space for the system to place 184 the channel binding data in return. If the provided buffer is too 185 small then an error must be returned (EOVERFLOW?). 187 #define IP_SEC_CBINDING 188 #define IP_SEC_CBINDING_TYPES 189 #define IP_SEC_CBINDING_DATA 191 #define IP_SEC_CBINDING_TYPES_BUFSIZE 192 #define IP_SEC_CBINDING_DATA_BUFSIZE 194 #define IP_SEC_CBINDING_ENDPOINT_SHA256_NAME \ 195 "ipsec-end-point-sha256" 196 #define IP_SEC_CBINDING_ENDPOINT_SHA256_NAME \ 197 "ipsec-single-end-point-sha256" 199 201 IP_SEC_CBINDING_TYPES_BUFSIZE and IP_SEC_CBINDING_DATA_BUFSIZE are 202 advisory. Applications may need to resize their buffers. A pair of 203 "sysconf" system variables providing actual maximum buffer sizes 204 SHOULD be provided, and MUST be named 205 _SC_IP_SEC_CBINDING_TYPES_BUFSIZE and 206 _SC_IP_SEC_CBINDING_DATA_BUFSIZE. 208 int rc; 209 char cbinding_types[IP_SEC_CBINDING_TYPES_BUFSIZE]; 210 char cbinding_data[IP_SEC_CBINDING_DATA_BUFSIZE]; 212 /* create and bind a socket, then: */ 213 ... 214 rc = setsockopt(sock_fd, IPPROTO_IP, IP_SEC_CBINDING, NULL, 0) 215 if (rc != 0) 216 ... 218 /* connect() or listen()/accept() */ 219 ... 221 /* 222 * get the channel binding types available in order of 223 * system preference 224 */ 225 rc = getsockopt(sock_fd, IPPROTO_IP, IP_SEC_CBINDING_TYPES, 226 cbinding_types, sizeof (cbinding_types)); 227 if (rc != 0) 228 ... 230 /* 231 * Pick a channel binding type (possibly by looking for types 232 * listed in cbinding_types[] that are listed in an application 233 * configuration file or command-line argument, possibly by 234 * negotiation with the application's peer). 235 */ 236 ... 238 /* Get the channel bindings */ 239 (void) strlcpy(cbinding_data, 240 , sizeof(cbinding_data)); 241 (void) strlcat(cbinding_data, ":", sizeof(cbinding_data)); 242 rc = getsockopt(sock_fd, IPPROTO_IP, IP_SEC_CBINDING_DATA, 243 cbinding_data, sizeof (cbinding_data)); 244 if (rc != 0) 245 ... 247 /* 248 * Use the channel bindings (by passing them to GSS-API or SASL 249 * functions). 250 */ 251 ... 253 Example code 255 5. IANA Considerations 257 [Add text about the two IPsec channel binding type registrations for 258 the IANA channel binding type registry.] 260 6. Security Considerations 262 All the security considerations of [RFC5056] apply. 264 This specification makes used of cryptographic hash functions. As 265 such hash agility concerns arise. We do not provide a method for 266 negotiation of future new channel binding types -- we leave it to 267 their authors to do so. We do describe a couple of methods that they 268 might use to do this. 270 [NOTE: Perhaps we should specify new NOTIFYs now. Comments? -Nico] 272 7. Acknowledgements 274 ... 276 8. References 278 8.1. Normative References 280 [CCITT.X690.2002] 281 International International Telephone and Telegraph 282 Consultative Committee, "ASN.1 encoding rules: 283 Specification of basic encoding Rules (BER), Canonical 284 encoding rules (CER) and Distinguished encoding rules 285 (DER)", CCITT Recommendation X.690, July 2002. 287 [I-D.ietf-btns-abstract-api] 288 Richardson, M., "An abstract interface between 289 applications and IPsec", draft-ietf-btns-abstract-api-02 290 (work in progress), November 2008. 292 [I-D.ietf-btns-connection-latching] 293 Williams, N., "IPsec Channels: Connection Latching", 294 draft-ietf-btns-connection-latching-09 (work in progress), 295 March 2009. 297 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 298 Requirement Levels", BCP 14, RFC 2119, March 1997. 300 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 301 Internet Protocol", RFC 4301, December 2005. 303 [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", 304 RFC 4306, December 2005. 306 [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure 307 Channels", RFC 5056, November 2007. 309 [RFC5386] Williams, N. and M. Richardson, "Better-Than-Nothing 310 Security: An Unauthenticated Mode of IPsec", RFC 5386, 311 November 2008. 313 8.2. Informative References 315 [I-D.bellovin-useipsec] 316 Bellovin, S., "Guidelines for Specifying the Use of IPsec 317 Version 2", draft-bellovin-useipsec-10 (work in progress), 318 August 2008. 320 [I-D.dondeti-useipsec-430x] 321 Dondeti, L. and V. Narayanan, "Guidelines for using IPsec 322 and IKEv2", draft-dondeti-useipsec-430x-00 (work in 323 progress), October 2006. 325 [RFC5387] Touch, J., Black, D., and Y. Wang, "Problem and 326 Applicability Statement for Better-Than-Nothing Security 327 (BTNS)", RFC 5387, November 2008. 329 Author's Address 331 Nicolas Williams 332 Sun Microsystems 333 5300 Riata Trace Ct 334 Austin, TX 78727 335 US 337 Email: Nicolas.Williams@sun.com