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 November 6, 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".

Table of Contents

1.  Introduction
1.1.  Conventions used in this document
2.  End-Point Channel Binding Types for IPsec
2.1.  ipsec-end-point-sha256
2.2.  ipsec-responder-end-point
2.3.  Hash Agility and Channel Binding Type Negotiation
3.  Abstract API
4.  BSD Sockets C API
5.  IANA Considerations
6.  Security Considerations
7.  Acknowledgements
8.  References
8.1.  Normative References
8.2.  Informative References
§  Author's Address

1.  Introduction

With connection latching [I‑D.ietf‑btns‑connection‑latching] (Williams, N., “IPsec Channels: Connection Latching,” August 2009.) IPsec now has a notion of "secure channel" that can be used in conjunction with channel binding [RFC5056] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.). 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] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.), IPsec [RFC4301] (Kent, S. and K. Seo, “Security Architecture for the Internet Protocol,” December 2005.) and connection latching [I‑D.ietf‑btns‑connection‑latching] (Williams, N., “IPsec Channels: Connection Latching,” August 2009.).

These channel binding types also work with Better Than Nothing Security (BTNS) [RFC5386] (Williams, N. and M. Richardson, “Better-Than-Nothing Security: An Unauthenticated Mode of IPsec,” November 2008.) [RFC5387] (Touch, J., Black, D., and Y. Wang, “Problem and Applicability Statement for Better-Than-Nothing Security (BTNS),” November 2008.), 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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

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] (Williams, N., “IPsec Channels: Connection Latching,” August 2009.) 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).

PKi and PKr MUST be the bytes that appear as the value of the subjectPublicKeyInfo field (including the DER/BER TLV [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),” July 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] (Kaufman, C., “Internet Key Exchange (IKEv2) Protocol,” December 2005.)).

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] (Kaufman, C., “Internet Key Exchange (IKEv2) Protocol,” December 2005.). 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.

4.  BSD Sockets C API

We define three socket options for the IPPROTO_IP socket level:

• 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.
• 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?).
• 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               <OS-specific value>
#define IP_SEC_CBINDING_TYPES         <OS-specific value>
#define IP_SEC_CBINDING_DATA          <OS-specific value>

#define IP_SEC_CBINDING_TYPES_BUFSIZE <OS-specific value>
#define IP_SEC_CBINDING_DATA_BUFSIZE  <OS-specific value>

#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.

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,
    <selected channel binding type>, 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).
 */
...

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] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.) 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

8.2. Informative References

Author's Address