Better than Nothing Security M. Richardson
Internet-Draft Williams
Intended status: Informational SSW
Expires: January 9, 2008 M. Komu
Tarkoma
Helsinki Institute for Information
Technology
July 8, 2007
IPsec Application Programming Interfaces
draft-ietf-btns-c-api-01
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
This document may not be modified, and derivative works of it may not
be created, except to publish it as an RFC and to translate it into
languages other than English.
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 January 9, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2007).
Abstract
IPsec based security is usually transparent for applications and and
Richardson, et al. Expires January 9, 2008 [Page 1]
Internet-Draft IPsec APIs July 2007
they have no standard APIs for gathering information about protected
network connections and for detecting the underlying security
mechanisms. This document specifies an API that increases the
visibility of IPsec to applications. The API allows applications to
allow BTNS extensions, control the channel bindigs, and control also
other security properties related to IPsec.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. IPsec APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Token Attributes . . . . . . . . . . . . . . . . . . . . . 5
2.2. Identity Tokens . . . . . . . . . . . . . . . . . . . . . 5
2.2.1. Creation of Identity Tokens . . . . . . . . . . . . . 5
2.2.2. Attributes of Identity Tokens . . . . . . . . . . . . 6
2.3. Protection Tokens . . . . . . . . . . . . . . . . . . . . 8
2.3.1. Creation of Protection Tokens . . . . . . . . . . . . 8
2.3.2. Attributes of Protection Tokens . . . . . . . . . . . 9
2.3.3. Connection Oriented Communications . . . . . . . . . . 9
2.3.4. Datagram Oriented Communications . . . . . . . . . . . 10
2.3.5. Equivalency of Protection Tokens . . . . . . . . . . . 10
2.3.6. Duplication of Protection Tokens . . . . . . . . . . . 11
3. Security Considerations . . . . . . . . . . . . . . . . . . . 11
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Normative References . . . . . . . . . . . . . . . . . . . 12
6.2. Informative References . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
Intellectual Property and Copyright Statements . . . . . . . . . . 15
Richardson, et al. Expires January 9, 2008 [Page 2]
Internet-Draft IPsec APIs July 2007
1. Introduction
The "better than nothing" (BTNS) extensions for IKE
[I-D.ietf-btns-core] are intended to protect network traffic on their
own (Stand Alone BTNS, or SAB), and may be useful in providing
network layer security that can be authenticated by higher layers in
the protocol stack, called Channel Bound BTNS (CBB). The motivation
for SAB is to remove the need to deploy authentication information
altogether. The motivation for CBB is to remove the need for
redundant authentication at multiple layers. This document defines
APIs for these purposes. The APIs can also be used by other
protocols such as HIP.
The network communications of applications are usually secured
explicitly with TLS on transport layer [RFC4346], or using even
higher layer interfaces such as GSS [RFC2744] or SASL [RFC4422] APIs.
However, such interfaces do not exist for IPsec because it operates
on lower layers and is mostly transparent to applications. Using
IPsec to protect existing applications is therefore easier than with,
for example, TLS because IPsec does not require changes in the
application. However, it is difficult for an application to detect
when network connections are secured using IPsec. IPsec can be used
as an "all or nothing" security measure, which can be problematic
especially in deployments where the number of IPsec enabled machines
is small. An alternative approach is to use IPsec when peer supports
it. However, the application or the user may not have any knowledge
that the communications was actually protected by IPsec in this case.
In addition, it is more efficient to remove redundant authentications
when IPsec and TLS are being used for the same connection.
In this document, we defined APIs that increase the visibility of the
IPsec layer to the applications. This document fulfisl the BTNS
requirements presented in [I-D.ietf-btns-ipsec-apireq] and present
C-bindings to the abstract APIs [I-D.ietf-btns-abstract-api]. The
APIs defined in this document are based on the sockets API [POSIX] or
similar APIs that provide socket descriptors for applications. For
related API work, please refer to [I-D.ietf-hip-native-api],
[mcdonald] and [atkinson].
The documents defines an explicit way of enabling IPsec in
applications. This API allows the dual use of both IPsec and higher
layer security mechanisms (TLS, GSS or SASL) simultaneously. The
security and performance related benefits of this are described in
more detail in [I-D.ietf-btns-prob-and-applic].
Richardson, et al. Expires January 9, 2008 [Page 3]
Internet-Draft IPsec APIs July 2007
+---------+---------+---------+---------+
| App # 1 | App # 2 | App # 3 | App #4 |
+-----+---+-----+---+---+-----+----+----+
| | | |
| +---v-------v--+ |
| | TLS/GSS/SASL | |
+-----v-----+-------+------+ |
Appl. Layer | IPsec APIs | | |
+-----+---------+---+ | |
| | | |
+-----v---------v-------v-----------v---+
Sockets Layer | IPv4 and IPv6 APIs |
+-----------+--------------+------------+
Transport Layer | SCTP | TCP | UDP |
+-----------+--------------+------------+
IPsec Layer | IPsec |
+--------------------+------------------+
Network Layer | IPv4 | IPv6 |
+--------------------+------------------+
Link Layer | Ethernet | Etc |
+--------------------+------------------+
Figure 1: API Layering
Figure 1 illustrates four different applications. The first
application is using only the IPsec APIs based on either IKE based
authentication or Stand-alone BTNS. The second application is using
both TLS (or other similar APIs) and IPsec APIs. In this case, the
application can skip IKE authentication because of it is already
provided by TLS. On the other hand, the application can avoid the
use of TLS altogether when IKE authentication is available.'The third
application is using only TLS and the fourth one is using neither
IPsec or TLS APIs.
In the first three cases, the application is explicitly modified to
use either TLS or IPsec. In contrast, the fourth application is not
using either TLS or IPsec explicitly, but it may be using IPsec
implicitly. This document covers the use of applications one and
two.
2. IPsec APIs
This section defines constants, data structures and functions for
manipulating IPsec related data structures. The definitions are
based on C-language. The integer values are always in host byte
order.
Richardson, et al. Expires January 9, 2008 [Page 4]
Internet-Draft IPsec APIs July 2007
2.1. Token Attributes
IPsec properties are handled indirectly using objects called tokens.
They are are opaque data structures that must not be manipulated
directly. Instead, the application uses the accessor functions shown
in Figure 2.
int ipsec_get_token_attr(const void *token,
uint32_t attr_type,
uint32_t *attr_len,
void **attr_val);
int ipsec_set_token_attr(const void *token,
uint32_t attr_type,
uint32_t attr_len,
const void *attr_val);
Figure 2
Function ipsec_token_attr_get() searches for the given attribute type
(attr_type) from the token. The attr_val pointer may have memory
allocated for it already. If so, it will be non-NULL, and the
attr_len must have the size of the allocated memory set. When
attr_val pointer is NULL, the function allocates memory into attr_val
(using malloc) and copies the attribute into the allocated memory.
On successful operation, the function sets the attribute length in
attr_len. When attr_val is NULL, then no object will be returned,
but attr_len will still be set to the size of the attr_val.
Function ipsec_set_token_attr() writes the attribute (attr_val) to
the token. The type and length of the attribute must be set in
attr_type and attr_len.
2.2. Identity Tokens
This section describes the use of IPsec identity tokens. The
identity tokes can be used for querying the peer identity and for
requiring certain channel bindings for a socket to implement ACLs or
for logging purposes. Then, the application can communicate with a
peer through the socket and the communication succeeds only when
channel bindings are acceptable to the application. The application
can also communicate with an peer of unkown identity, and to store
and require the same peer identity in subsequent communications.
2.2.1. Creation of Identity Tokens
Identity tokens, iTokens, are machine-readable, opaque data
structures. They can present either the local or remote identity,
such as a public key. The iToken has a typedef which is illustrated
Richardson, et al. Expires January 9, 2008 [Page 5]
Internet-Draft IPsec APIs July 2007
in Figure 3.
typedef struct ipsec_iToken * ipsec_iToken_t;
Figure 3
The size of a iToken is variable and applications MUST NOT declare it
directly. Instead, the application uses the constructor and
destructor functions shown in Figure 4.
ipsec_iToken_t ipsec_create_iToken();
int ipsec_free_iToken(ipsec_iToken_t p);
Figure 4
Function ipsec_create_iToken() allocates memory for a iToken and
initializes it. The function returns the created iToken, or NULL
upon failure.
Function ipsec_free_iToken() deinitializes and frees the memory
allocated to an iToken. It returns zero on success, and non-zero
upon failure.
2.2.2. Attributes of Identity Tokens
Identity token attributes are shown in Figure 5. They are accessed
using the functions defined in Section 2.1.
Richardson, et al. Expires January 9, 2008 [Page 6]
Internet-Draft IPsec APIs July 2007
enum {
IPSEC_API_ATTR_auditString,
IPSEC_API_ATTR_authenticationMethod,
IPSEC_API_ATTR_certificateAuthorityDN,
IPSEC_API_ATTR_certificateDN,
IPSEC_API_ATTR_pubKeyID,
IPSEC_API_ATTR_channelBinding
} iToken_attribute;
enum {
IPSEC_API_ATTR_authMeth_NONE,
IPSEC_API_ATTR_authMeth_BTNS,
IPSEC_API_ATTR_authMeth_LEAFOFFAITH,
IPSEC_API_ATTR_authMeth_PRESHAREDKEY,
IPSEC_API_ATTR_authMeth_GROUPKEY,
IPSEC_API_ATTR_authMeth_XAUTH,
IPSEC_API_ATTR_authMeth_EAP,
IPSEC_API_ATTR_authMeth_PKIX_TRUSTED,
IPSEC_API_ATTR_authMeth_PKIX_INLINE,
IPSEC_API_ATTR_authMeth_PKIX_OFFLINE
} iToken_auth_meth;
Figure 5
The first group of attributes defined in iToken_attribute enumeration
cannot be modified. The auditString attribute is a character array
ending with a zero byte. It contains a human-readable description of
the peer identity. The authenticationMethod attribute defines the
key manager authentication method in an unsigned integer of two
octets. Possible values are XX TBD. The certificateAuthorityDN
attribute is a character array ending with a zero byte and contains a
human-readable description of the peer certificate authority. The
pubKeyID attribute contains a binary presentation of the peer public
key. The channelBinding attribute s a character array ending with a
zero byte. It contains a human-readable description of the channel
binding. Two channel bindings can be compared with the memcmp()
function.
The second group of attributes in iToken_auth_meth enumeration
contains a list of authentication methods. These attributes are both
writable before network communications and readable after network
communications. Here the use of the attributes is described only
from writing point of view.
The attibutes for the second group are 2-octet unsigned integer
values, with values IPSEC_API_ATTR_ENABLE, IPSEC_API_ATTR_DISABLE and
IPSEC_API_ATTR_ANY. The first two of the values enable or disable
the attribute, and third one refers that the application relies on
Richardson, et al. Expires January 9, 2008 [Page 7]
Internet-Draft IPsec APIs July 2007
the system defaults. NONE describes that no authentication should be
used.
In the second group, BTNS enables or disables the extensions in
[I-D.ietf-btns-core] . The LEAFOFFAITH attribute declares that the
application does not have to know the peer identity beforehand. The
PRESHAREDKEY attribute denotes that a preshared key should be used
(XX REF) and GROUPKEY correspondingly refers to a group key (XX REF).
The XAUTH and EAP attributes refer to the authentication methods
defined in (XX REFS). The PKIX methods refer to the authentication
methods in (XX REF).
2.3. Protection Tokens
An application creates a "protection token" and attaches some
attributes for it. For example, the application can define in the
attributes of protection token that it accepts BTNS extensions for a
certain socket.
2.3.1. Creation of Protection Tokens
Protection tokens, or pTokens, are used as handles to the key
management or the IPsec module of the host. The two main pToken
attributes are enabling the BTNS extensions and controlling of
iTokens. The former allows the use of IPSec without authentication,
and the latter allows e.g. quering of channel bindings.
The data structure that represents a pToken is contained in an opaque
ipsec_pToken structure. The application must not alter the data
structure contents directly, but rather use the accessor functions
introduced in the following sections. The application can use
ipsec_pToken_t typedef as a short hand for the policy structure. The
typedef is shown in Figure 6.
typedef struct ipsec_pToken * ipsec_pToken_t;
Figure 6
The size of a policy is variable and applications MUST NOT declare
them directly. Instead, the application uses the constructor and
destructor functions shown in Figure 7.
ipsec_pToken_t ipsec_create_pToken();
int ipsec_free_pToken(ipsec_pToken_t p);
Figure 7
Function ipsec_create_pToken() allocates memory for a pToken and
Richardson, et al. Expires January 9, 2008 [Page 8]
Internet-Draft IPsec APIs July 2007
initializes it. The function returns the created pToken, or NULL
upon failure.
Function ipsec_free_pToken() deinitializes and frees the memory
allocated to a pToken. It returns zero on success, and non-zero upon
failure.
2.3.2. Attributes of Protection Tokens
Protection token attributes are shown in Figure 8. They are get or
set using the functions defined in Section 2.1.
enum {
IPSEC_API_ATTR_privacyProtection,
IPSEC_API_ATTR_integrityProtection,
IPSEC_API_ATTR_compression,
IPSEC_API_ATTR_iToken,
IPSEC_API_ATTR_auditString
} pToken_attribute;
Figure 8
The privacy, intergrity and compression attributes are 2-octet
unsigned integer values. These attributes are writable before
network communication and readable after network communications.
Here the use of the attributes is described only from writing point
of view. Value IPSEC_API_ATTR_DISABLE defines that the attribute
should not be used. Value IPSEC_API_ATTR_ENABLE describes that the
corresponding attribute should be used. It is possible to enable the
attribute by declaring the "level" of the attribute with
IPSEC_API_ATTR_LEVEL_LOW, IPSEC_API_ATTR_LEVEL_MEDIUM or
IPSEC_API_ATTR_LEVEL_HIGH.
The attribute iToken is the peer identity in an iToken data
structure. The auditString is a character array ending in zero byte
and contains a human readable description of the protection token.
2.3.3. Connection Oriented Communications
Declaring a pToken does not affect the networking communications of
an application. For connection oriented communications, the
application must first attach the pToken to the socket before the
pToken is effective. It is also possible to query for the pToken
attached to a socket as shown in Figure 9.
int ipsec_set_socket_pToken(int fd, const ipsec_pToken_t pToken);
int ipsec_get_socket_pToken(int fd, ipsec_pToken_t *pToken);
Richardson, et al. Expires January 9, 2008 [Page 9]
Internet-Draft IPsec APIs July 2007
Figure 9
Both functions input an socket descriptor as the first argument and a
pToken as the second argument. Function ipsec_set_socket_pToken()
attaches the given pToken to the socket descriptor fd. For
ipsec_get_socket_pToken(), the pToken is actually a double pointer
because the function also allocates the memory for the queried
pToken.
Both functions return zero upon success, and non-zero upon failure.
2.3.4. Datagram Oriented Communications
The previous section covered the use of connected sockets. Datagram
oriented communications based on sendmsg() and recvmsg() functions
are supported in the API, but sendto() and recvfrom() are not
supported. Datagram related functions are applicable both to
incoming and outgoing packets. The IPsec API functions related
sendmsg() and recvmsg() are shown in Figure 10.
int ipsec_set_msg_pToken(const struct msghdr *msg,
const ipsec_pToken_t pToken);
int ipsec_get_msg_pToken(const struct msghdr *msg,
ipsec_pToken_t *pToken);
Figure 10
Function ipsec_set_msg_pToken() attaches the given pToken to the
ancillary data of msg. The pToken of a msg can be queried using
ipsec_get_msg_pToken(). The function allocates the memory required
for the pToken and returns it to the caller in pToken, which is
effectively a double pointer.
Both functions return zero on success and non-zero on failure.
2.3.5. Equivalency of Protection Tokens
An application is not allowed to read or write to pTokens directly.
The same restriction applies also to comparison of pTokens. The
function for comparing two pTokens is shown in Figure 11.
int ipsec_cmp_pToken(ipsec_pToken_t p1, ipsec_pToken_t p2);
Figure 11
Function ipsec_cmp_policy() inputs two policies, p1 and p2, and
returns zero if they represent two SAs that cover identical SPD
ranges, and have equivalent cryptographic security properties. The
Richardson, et al. Expires January 9, 2008 [Page 10]
Internet-Draft IPsec APIs July 2007
two SAs need not represent SAs that identical --- they might vary in
many different ways, including, but not limited to:
o Time: One SA may have been created later, but both are valid.
o Jitter/performance properties: One SA may be on hardware and the
other on software, and have different properties about what kind
of latency or jitter a packet might experience
o Algorithm: one SA might use AES128-CBC while the other uses
AES128-CTR (DISCUSS) for performance reasons.
o IPsec SA endpoints. The two SAs may cover the same inner IP
packets, but might connect using differing outer IP addresses, and
be used in some kind of multipath IPsec (such as MOBIKE).
2.3.6. Duplication of Protection Tokens
Byte-wise copying of pTokens is not allowed e.g. with memcpy().
Function ipsec_dup_pToken() duplicates given pToken p and writes it
to p_dup. The function allocates the memory for duplicated pToken
that the caller is responsible of freeing. Return value is zero on
success and non-zero on failure.
int ipsec_dup_pToken(ipsec_pToken_t *p, ipsec_pToken_t *p_dup);
Figure 12
3. Security Considerations
The BTNS Stand Alone mode allows applications to omit network layer
authentication. In this case, an application is using a higher level
security mechanism, such as TLS, and thus the required level of
security is maintained. The application has the control and
duplicate security techniques are not applied.
The channel bindings allow applications to create and manage security
channels. Given that applications omit higher layer security
techniques based on information in an existing pToken and the
corresping channel binding, there is a possibility for a security
channel downgrade attack. In this attack, another application
modifies the current application's channel binding in such a way that
the application believes that an authenticated IPsec security channel
to be active eventhough there is no such channel. If the application
omits TLS or other higher level security mechanism, then there will
not be a secured channel and transmitted data is exposed.
Richardson, et al. Expires January 9, 2008 [Page 11]
Internet-Draft IPsec APIs July 2007
4. IANA Considerations
TBD
5. Acknowledgements
Thanks for Love Hoernquist Aestrand, Julien Laganier for feedback,
ideas and discussion on the topic. The authors wish to thank also
Simon Josefsson and Daniel McDonald for comments on the draft.
6. References
6.1. Normative References
[I-D.ietf-btns-abstract-api]
Richardson, M., "An interface between applications and
keying systems", draft-ietf-btns-abstract-api-00 (work in
progress), June 2007.
[I-D.ietf-btns-core]
Richardson, M. and N. Williams, "Better-Than-Nothing-
Security: An Unauthenticated Mode of IPsec",
draft-ietf-btns-core-03 (work in progress), May 2007.
[I-D.ietf-btns-ipsec-apireq]
Richardson, M. and B. Sommerfeld, "Requirements for an
IPsec API", draft-ietf-btns-ipsec-apireq-00 (work in
progress), April 2006.
[I-D.ietf-btns-prob-and-applic]
Touch, J., "Problem and Applicability Statement for Better
Than Nothing Security (BTNS)",
draft-ietf-btns-prob-and-applic-03 (work in progress),
June 2006.
[POSIX] Institute of Electrical and Electronics Engineers, "IEEE
Std. 1003.1-2001 Standard for Information Technology -
Portable Operating System Interface (POSIX)", Dec 2001.
6.2. Informative References
[I-D.ietf-hip-native-api]
Komu, M., "Native Application Programming Interfaces for
SHIM Layer Prococols", draft-ietf-hip-native-api-01 (work
in progress), March 2007.
Richardson, et al. Expires January 9, 2008 [Page 12]
Internet-Draft IPsec APIs July 2007
[RFC2744] Wray, J., "Generic Security Service API Version 2 :
C-bindings", RFC 2744, January 2000.
[RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.1", RFC 4346, April 2006.
[RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and
Security Layer (SASL)", RFC 4422, June 2006.
[atkinson]
USENIX 1996 Annual Technical Conference, "Implementation
of IPv6 in 4.4 BSD", Jan 1996.
[mcdonald]
Internet Engineering Task Force, "A Simple IP Security API
Extension to BSD Sockets", Mar 1997.
Authors' Addresses
Michael C. Richardson
Sandelman Software Works
470 Dawson Avenue
Ottawa, ON K1Z 5V7
CA
Email: mcr@sandelman.ottawa.on.ca
URI: http://www.sandelman.ottawa.on.ca/
Nicolas Williams
SUN Microsystems
5300 Riata Trace Ct
Austin, TX TX 78727
US
Email: Nicolas.Williams@sun.com
Richardson, et al. Expires January 9, 2008 [Page 13]
Internet-Draft IPsec APIs July 2007
Miika Komu
Helsinki Institute for Information Technology
Tammasaarenkatu 3
Helsinki
Finland
Phone: +358503841531
Fax: +35896949768
Email: miika@iki.fi
URI: http://www.iki.fi/miika/
Sasu Tarkoma
Helsinki Institute for Information Technology
Tammasaarenkatu 3
Helsinki
Finland
Phone: +358503841517
Fax: +35896949768
Email: sasu.tarkoma@hiit.fi
URI: http://www.cs.helsinki.fi/u/starkoma/
Richardson, et al. Expires January 9, 2008 [Page 14]
Internet-Draft IPsec APIs July 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Richardson, et al. Expires January 9, 2008 [Page 15]
