NETWORK WORKING GROUP N. Williams Internet-Draft Sun Intended status: Standards Track April 9, 2009 Expires: October 11, 2009 IPsec End-Point Channel Bindings and API draft-ietf-btns-channel-binding-api-00.txt Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on October 11, 2009. Copyright Notice Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Abstract This document defines channel bindings for IPsec and describes an abstract API and a BSD sockets API extension for obtaining channel bindings of "connection latches". Williams Expires October 11, 2009 [Page 1] Internet-Draft IPsec Channel Bindings/API April 2009 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Conventions used in this document . . . . . . . . . . . . . . 3 2. End-Point Channel Binding Types for IPsec . . . . . . . . . . 3 2.1. ipsec-end-point-sha256 . . . . . . . . . . . . . . . . . . . 3 2.2. ipsec-responder-end-point . . . . . . . . . . . . . . . . . . 4 2.3. Hash Agility and Channel Binding Type Negotiation . . . . . . 4 3. Abstract API . . . . . . . . . . . . . . . . . . . . . . . . 4 4. BSD Sockets C API . . . . . . . . . . . . . . . . . . . . . . 5 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 8.1. Normative References . . . . . . . . . . . . . . . . . . . . 7 8.2. Informative References . . . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . 8 Williams Expires October 11, 2009 [Page 2] Internet-Draft IPsec Channel Bindings/API April 2009 1. Introduction With connection latching [I-D.ietf-btns-connection-latching] IPsec now has a notion of "secure channel" that can be used in conjunction with channel binding [RFC5056]. This document defines the channel bindings for IPsec channels where each peers use public keys to authenticate to the other. It also provides an abstract API for accessing the channel bindings of an IPsec channel. And it provides a BSD sockets C language binding of that abstract API. We assume reader familiarity with channel binding [RFC5056], IPsec [RFC4301] and connection latching [I-D.ietf-btns-connection-latching]. These channel binding types also work with Better Than Nothing Security (BTNS) [RFC5386] [RFC5387], and make its use safe. 1.1. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. End-Point Channel Binding Types for IPsec We define several end-point channel bindings suitable for any IPsec channel where one or both peers are authenticated by a public key. These channel binding types use a hash function whereas they could use the raw un-hashed inputs. We use a hash function so as to produce manageably sized channel binding data (consider that this data often has to be held in kernel memory). 2.1. ipsec-end-point-sha256 Given a channel C, initiator public key PKi, and responder public key PKr: ipsec-end-point-sha256(C) := SHA256(PKi) XOR SHA256(PKr) The reason for the XOR is that in IPsec there's no deterministic rule for which peer will be an IKE initiator or responder. It is possible for both peers to have been initiators of Security Associtiations (SAs) used in the connection latching [I-D.ietf-btns-connection-latching] process, thus we need an operation that binds both peers' public keys without any kind of order (we don't want to do any sorting). Williams Expires October 11, 2009 [Page 3] Internet-Draft IPsec Channel Bindings/API April 2009 PKi and PKr MUST be the bytes that appear as the value of the subjectPublicKeyInfo field (including the DER/BER TLV [CCITT.X690.2002]) of the corresponding certificates as sent in CERT payloads, or, in the case of Raw RSA keys, the bytes that appear in the peer's CERT payload (see section 3.6 of [RFC4306]). 2.2. ipsec-responder-end-point Given a channel C where only one peer authenticated via a public key PKp (and the other, presumably, via EAP): ipsec-single-end-point-sha256(C) := SHA256(PKp) PKp is encoded as described in the previous section. 2.3. Hash Agility and Channel Binding Type Negotiation Hash agility is obtained by negotiating channel binding types. Variants of ipsec-end-point-sha256 based on other hash functions can be added as needed. Note that there's no in-band channel binding type negotiation in IKEv2 [RFC4306]. It's possible and preferable that the peer's available channel binding types be determined from IKEv2 context. The algorithm or protocol for deciding the availability of any given variant of ipsec-end-point-sha256 MUST be specified by any such variant. For example, a putative ipsec-end-point-sha3 could be available if a putative SHA-3 function were used in any part of the IKEv2 exchanges that setup an SA linked to a connection latch. Or NOTIFY payloads might be added to IKEv2 for negotiating the use of a putative ipsec-end-point-sha3. ipsec-end-point-sha256 MUST always be available (at least until SHA- 256 is deprecated). 3. Abstract API To use channel binding to IPsec channels applications MUST first indicate their intention to do so and MAY provide a set of channel binding types that the application prefers. This should be done as part of the procedure to actively connect to peers or passively accept connections from peers. Once an IPsec channel is established the application may then request the channel's channel binding data for a specific channel binding type. Williams Expires October 11, 2009 [Page 4] Internet-Draft IPsec Channel Bindings/API April 2009 4. BSD Sockets C API We define three socket options for the IPPROTO_IP socket level: o IP_SEC_CBINDING, a socket option to be used prior to calling connect() and listen() or accept(). Applications MUST use this socket option to indicate their intention to used channel binding. This option does not take an argument; the actual socket option argument passed by the caller MUST be NULL. o IP_SEC_CBINDING_TYPES, a socket option that applications can use after a connection is established to determine what channel binding types are available. This option takes as argument a pointer to a memory buffer into which an ordered list of channel binding type names will be written, separated by ASCII colons (':') and terminated by a NUL. If the provided buffer is too small then an error must be returned (EOVERFLOW?). o IP_SEC_CBINDING_DATA, a socket option that applications can use after a connection is established to obtain the channel binding data for the given socket and the given channel binding type. This option takes as argument a pointer to a memory buffer containing the name of the requested channel binding type followed by an ASCII colon (':') and enough space for the system to place the channel binding data in return. If the provided buffer is too small then an error must be returned (EOVERFLOW?). #define IP_SEC_CBINDING #define IP_SEC_CBINDING_TYPES #define IP_SEC_CBINDING_DATA #define IP_SEC_CBINDING_TYPES_BUFSIZE #define IP_SEC_CBINDING_DATA_BUFSIZE #define IP_SEC_CBINDING_ENDPOINT_SHA256_NAME \ "ipsec-end-point-sha256" #define IP_SEC_CBINDING_ENDPOINT_SHA256_NAME \ "ipsec-single-end-point-sha256" IP_SEC_CBINDING_TYPES_BUFSIZE and IP_SEC_CBINDING_DATA_BUFSIZE are advisory. Applications may need to resize their buffers. A pair of "sysconf" system variables providing actual maximum buffer sizes SHOULD be provided, and MUST be named _SC_IP_SEC_CBINDING_TYPES_BUFSIZE and _SC_IP_SEC_CBINDING_DATA_BUFSIZE. Williams Expires October 11, 2009 [Page 5] Internet-Draft IPsec Channel Bindings/API April 2009 int rc; char cbinding_types[IP_SEC_CBINDING_TYPES_BUFSIZE]; char cbinding_data[IP_SEC_CBINDING_DATA_BUFSIZE]; /* create and bind a socket, then: */ ... rc = setsockopt(sock_fd, IPPROTO_IP, IP_SEC_CBINDING, NULL, 0) if (rc != 0) ... /* connect() or listen()/accept() */ ... /* * get the channel binding types available in order of * system preference */ rc = getsockopt(sock_fd, IPPROTO_IP, IP_SEC_CBINDING_TYPES, cbinding_types, sizeof (cbinding_types)); if (rc != 0) ... /* * Pick a channel binding type (possibly by looking for types * listed in cbinding_types[] that are listed in an application * configuration file or command-line argument, possibly by * negotiation with the application's peer). */ ... /* Get the channel bindings */ (void) strlcpy(cbinding_data, , sizeof(cbinding_data)); (void) strlcat(cbinding_data, ":", sizeof(cbinding_data)); rc = getsockopt(sock_fd, IPPROTO_IP, IP_SEC_CBINDING_DATA, cbinding_data, sizeof (cbinding_data)); if (rc != 0) ... /* * Use the channel bindings (by passing them to GSS-API or SASL * functions). */ ... Example code Williams Expires October 11, 2009 [Page 6] Internet-Draft IPsec Channel Bindings/API April 2009 5. IANA Considerations [Add text about the two IPsec channel binding type registrations for the IANA channel binding type registry.] 6. Security Considerations All the security considerations of [RFC5056] apply. This specification makes used of cryptographic hash functions. As such hash agility concerns arise. We do not provide a method for negotiation of future new channel binding types -- we leave it to their authors to do so. We do describe a couple of methods that they might use to do this. [NOTE: Perhaps we should specify new NOTIFYs now. Comments? -Nico] 7. Acknowledgements ... 8. References 8.1. Normative References [CCITT.X690.2002] International International Telephone and Telegraph Consultative Committee, "ASN.1 encoding rules: Specification of basic encoding Rules (BER), Canonical encoding rules (CER) and Distinguished encoding rules (DER)", CCITT Recommendation X.690, July 2002. [I-D.ietf-btns-abstract-api] Richardson, M., "An abstract interface between applications and IPsec", draft-ietf-btns-abstract-api-02 (work in progress), November 2008. [I-D.ietf-btns-connection-latching] Williams, N., "IPsec Channels: Connection Latching", draft-ietf-btns-connection-latching-09 (work in progress), March 2009. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Williams Expires October 11, 2009 [Page 7] Internet-Draft IPsec Channel Bindings/API April 2009 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the Internet Protocol", RFC 4301, December 2005. [RFC4306] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol", RFC 4306, December 2005. [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure Channels", RFC 5056, November 2007. [RFC5386] Williams, N. and M. Richardson, "Better-Than-Nothing Security: An Unauthenticated Mode of IPsec", RFC 5386, November 2008. 8.2. Informative References [I-D.bellovin-useipsec] Bellovin, S., "Guidelines for Specifying the Use of IPsec Version 2", draft-bellovin-useipsec-10 (work in progress), August 2008. [I-D.dondeti-useipsec-430x] Dondeti, L. and V. Narayanan, "Guidelines for using IPsec and IKEv2", draft-dondeti-useipsec-430x-00 (work in progress), October 2006. [RFC5387] Touch, J., Black, D., and Y. Wang, "Problem and Applicability Statement for Better-Than-Nothing Security (BTNS)", RFC 5387, November 2008. Author's Address Nicolas Williams Sun Microsystems 5300 Riata Trace Ct Austin, TX 78727 US Email: Nicolas.Williams@sun.com Williams Expires October 11, 2009 [Page 8]