FYI.
A draft has been submitted in the 'mobileip' wg to discuss
extension of IPv6 socket APIs for MIPv6.
The draft includes mechanism :
* to observe MH(Mobility Header) packets at the user level
* to access HOA and Routing header type 2 at the user level
* Defines MH protocol in /etc/protocols
* Defines basic MIPv6 data structure for portability of apps.
Please provide comments in the mobileip wg alias and to the authors.
Thanks,
-Samita
INTERNET-DRAFT Samita Chakrabarti
Expires: August, 2003 Erik Nordmark
Sun Microsystems, Inc.
February, 2003
Extension to Sockets API for Mobile IPv6
<draft-chakrabarti-mobileip-mipext-advapi-00.txt>
Status of this Memo
This document is an Internet-Draft and is subject to
all provisions of Section 10 of RFC2026.
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 expires August, 2003.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract
This document describes data structures and API support for Mobile
IPv6 as an extension to Advanced Socket API support for IPv6.
Mobility Support in IPv6 introduces mobility protocol header
for IPv6. It is expected that future Mobile IPv6 applications
and implementations may need to access Mobility binding messages
and Return Routability messages for diagnostic, packet accounting
and local policy setting purposes. In order to provide portability
for Mobile IP applications that use sockets under IPv6,
standardization is needed for the Mobile IPv6 specific APIs.
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 1]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
This document provides mechanism for API access to retrieve and set
information for Mobility Header messages, Home address destination
option and Routing header type 2 extension headers. It also discusses
the common data structures and defines that might be used by the
advanced Mobile IPv6 socket applications.
Table of Contents
1. Introduction ........................................... 3
2. Common Structures and Definitions ...................... 4
2.1 The Mobility Header Data Structures ................ 5
2.2 Mobility Header Constants .......................... 7
2.3 IPv6 Home Address Destination Option ................ 8
2.4 Routing Header Type 2 ................................8
3. Access to Home Address Destination Option and Routing Headers
................................ 9
3.1 Routing Header Access Functions ..................... 10
3.2 Home Address Destination Option Access Functions .....10
4. Mobility Protocol Headers ............................... 11
4.1 Receiving and Sending Mobility Header Messages ..... 11
5. Protocols File ............................................12
6. IPv4-Mapped IPv6 Addresses ................................12
7. Security Considerations ...................................12
8. References ................................................13
9. Authors' Addresses .................................... ..13
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 2]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
1. Introduction
Mobility Support in IPv6 [2] defines a new mobility protocol header,
home address destination option and a new routing header type.
It is expected that Mobile IPv6 user level implementations and some
applications will need to access and process these IPv6 extension
headers. This document is an extension to existing Advanced Sockets
API document [1]; it addresses the IPv6 Sockets API for Mobile IPv6
protocol support. The target applications for this socket APIs are
believed to be the debugging and diagnostic applications as well as
some policy applications which would like to receive a copy of
protocol information at the application layer.
This document can be divided into the following parts.
1. Definitions of constants and structures for C programs that
capture the Mobile IPv6 packet formats on the wire. A common
definition of these is useful at least for packet snooping
appplications. This is captured in section 2.
2. Notes on how to use the IPv6 Advanced API to access home address
options and routing headers of type 2. This is captured in
section 3.
3. Notes on how user-level applications can observe MH (Mobility
Header) packets using raw sockets (in section 4). The IPv6 RAW
socket interface described in this document, allows applications
to receive MH packets whether or not the systems MH processing
takes place in the "kernel" or at the "user space".
4. Suggested name for /etc/protocols (in section 5).
It is anticipated that Mobile IPv6 will be used widely from mobile
devices to Server and Routing platforms. Thus it is useful to have
a standard API for portability of Mobile IPv6 applications on a
wide variety of platforms and operating systems.
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 3]
INTERNET-DRAFT Extensions to Sockets API for MIPv6 February, 2003
The packet information along with access to the extension headers
(Routing header and Destination options) are specified using the
"ancillary data" fields that were added to the 4.3BSD Reno sockets
API in 1990. The reason is that these ancillary data fields are
part of the Posix.1g standard and should therefore be adopted by
most vendors. This is in conformance with Advanced API for
IPv6 sockets [1].
This document does not address application access to either the
authentication header or the encapsulating security payload header.
All examples in this document omit error checking in the favor of
brevity.
We note that many of the functions and socket options defined in this
document may have error returns that are not defined in this
document. Many of these possible error returns will be recognized
only as implementations proceed.
Datatypes in this document follow the Posix.1g format: intN_t means a
signed integer of exactly N bits (e.g., int16_t) and uintN_t means an
unsigned integer of exactly N bits (e.g., uint32_t).
This document provides guidelines on MIPv6 socket applications and
believes that some other appropriate standardization body will
standardize the APIs along with other IPv6 advanced socket APIs.
2. Common Structures and Definitions
This API assumes that the fields in the protocol headers are left in
the network byte order, which is big-endian for the Internet
protocols. If not, then either these constants or the fields being
tested must be converted at run-time, using something like htons() or
htonl().
A new header file : <netinet/mh.h>
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 4]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
2.1. The Mobility Header Data Structures
2.1.1 The mh_hdr Structure
The following structure is defined as a result of including
<netinet/mh.h>. This is fixed part of the mobility header.
struct mh_hdr {
uint8_t mh_proto; /* NO_NXTHDR by default */
uint8_t mh_hdrlen; /* Header Len in unit of 8 Octets */
uint8_t mh_type; /* Type of Mobility Header */
uint8_t mh_resvd; /* Reserved */
uint16_t mh_cksum; /* Mobility Header Checksum */
/* Followed by BU/BR/BA/BM/HOT[I]/COT[I] specific parts */
};
2.1.2 Binding Update Mobility Message
struct mh_binding_update {
struct mh_hdr mh_bu_hdr;
uint16_t mh_bu_seqno; /* Sequence Number */
uint16_t
mh_bu_flags_ack : 1, /* Request a binding ack */
mh_bu_flags_home : 1, /* Home Registration */
mh_bu_flags_ll : 1, /* Link Local address capability */
mh_bu_flags_sa : 1, /* Key management capability */
mh_bu_flags_resvd : 12; /* Reserved */
uint16_t mh_bu_lifetime; /* Time in unit of 4 sec */
/* Followed by optional Mobility Options */
};
2.1.3 Binding Acknowledgment Mobility Message
struct mh_binding_ack {
struct mh_hdr mh_ba_hdr;
uint8_t mh_ba_status; /* Status code */
uint8_t
mh_ba_flags_sa : 1, /* IPSec Key managemnt flag */
mh_ba_flags_resvd : 7; /* Reserved */
uint16_t mh_ba_seqno;
uint16_t mh_ba_lifetime;
/* Followed by optional Mobility Options */
};
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 5]
INTERNET DRAFT Extension to Sockets API for MIPv6 February, 2003
2.1.4 Binding Request Mobility Message
struct mh_binding_request {
struct mh_hdr mh_br_hdr;
uint16_t mh_br_resvd;
/* Followed by optional Mobility Options */
};
2.1.5 Binding Error Mobility Message
struct mh_binding_error {
struct mh_hdr mh_be_hdr;
uint8_t mh_be_status; /* Error Status */
uint8_t mh_be_resvd;
struct in6_addr mh_be_homeaddr;
/* Followed by optional Mobility Options */
};
2.1.6 Common Data structure used by HOTI/COTI messages
HOTI/COTI messages are defined in IPv6 Mobility Support [2]
document. These messages are sent by Mobile node in order
to initiate Return Routability Procedure in Route Optimization
protocol.
struct mh_hoti_coti {
struct mh_hdr mh_hc_hdr;
uint16_t mh_hc_resvd;
uint32_t mh_hc_cookie[2]; /* 64 bit Cookie by MN */
/* Followed by optional Mobility Options */
};
2.1.7 Home Address Test (HOT) Message
struct mh_hot {
struct mh_hdr mh_hot_hdr;
uint16_t mh_hot_nonceId;
uint32_t mh_hot_cookie[2]; /* Cookie from HOTI msg */
uint32_t mh_hot_hm_keygen[2]; /* 64 Bit Key by CN */
/* Followed by optional Mobility Options */
};
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 6]
INTERNET DRAFT Extension to Sockets API for MIPv6 February, 2003
2.1.8 Care Of Address Test (COT) Message
struct mh_cot {
struct mh_hdr mh_cot_hdr;
uint16_t mh_cot_nonceId;
uint32_t mh_cot_cookie[2]; /* Cookie from COTI message */
uint32_t mh_cot_coa_keygen[2]; /* 64bit key by CN */
/* Followed by optional Mobility Options */
};
2.1.9 Mobility Option TLV data structure
struct mh_mobility_opt {
uint8_t mh_mopt_type; /* Option Type */
uint8_t mh_mopt_len; /* Option Length */
/* Variable Option Data in bytes */
};
2.1.10 Mobility Option Data Structures
TBD
2.2 Mobility Header Constants
IPv6 Next Header Value for Mobility:
<netinet/in.h>
#define IPPROTO_MH 62 /* IPv6 Mobility Header: IANA-TBD */
Mobility Header Message Types:
<netinet/mh.h>
#define MH_TYPE_BRR 0 /* Binding Request */
#define MH_TYPE_HOTI 1 /* HOTI Message */
#define MH_TYPE_COTI 2 /* COTI Message */
#define MH_TYPE_HOT 3 /* HOT Message */
#define MH_TYPE_COT 4 /* COT Message */
#define MH_TYPE_BU 5 /* Binding Update */
#define MH_TYPE_BACK 6 /* Binding ACK */
#define MH_TYPE_BERROR 7 /* Binding Error */
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 7]
INTERNET DRAFT Extension to Sockets API for MIPv6 February, 2003
Mobility Header Message Option Types:
<netinet/mh.h>
#define MHOPT_PAD1 0x00 /* PAD1 */
#define MHOPT_PDAN 0x01 /* PADN */
#define MHOPT_UID 0x02 /* Unique ID */
#define MHOPT_ALTCOA 0x03 /* Alternate COA */
#define MHOPT_NONCEID 0x04 /* Nonce Index */
#define MHOPT_BAUTH 0x05 /* Binding Auth Data */
#define MHOPT_BREFRESH 0x06 /* Binding Refresh */
Status values accompanied with Mobility Binding Acknowledgement:
<netinet/mh.h>
#define MH_BAS_ACCPETED 0 /* Binding update accepted */
#define MH_BAS_UNSPECIFIED 128 /* Reason unspecified */
#define MH_BAS_ADMIN 129 /* Administratively prohibited */
#define MH_BAS_INSUFFICIENT 130 /* Insufficient resources */
#define MH_BAS_NOT_HA 131 /* HA registration not supported */
#define MH_BAS_NOT_HOME_SUBNET 132 /* Not Home subnet */
#define MH_BAS_WRONG_HA 133 /* Not HA for this mobile node */
#define MH_BAS_DAD_FAILED 134 /* DAD failed */
#define MH_BAS_SEQNO_BAD 135 /* Sequence number out of range */
#define MH_BAS_EXP_HOME_NI 136 /* Expired Home nonce index */
#define MH_BAS_EXP_COA_NI 137 /* Expired Care-of nonce index */
#define MH_BAS_EXP_NI 138 /* Expired Nonce Indices */
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 8]
INTERNET DRAFT Extension to Sockets API for MIPv6 February, 2003
2.3. IPv6 Home Address Destination Option
<netinet/ip6.h>
/* Home Address Destination Option */
struct ip6_opt_hoa {
uint8_t ip6hoa_type;
uint8_t ip6hoa_len;
uint8_t ip6hoa_addr[16];
}
Option Type Definition:
#define IP6OPT_HOME_ADDRESS 0xc9 /* 11 0 01001 */
2.4 Routing Header Type 2
<netinet/ip6.h>
/* Type 2 Routing header for Mobility Protocol */
struct ip6_rthdr2 {
uint8_t ip6r2_nxt; /* next header */
uint8_t ip6r2_len; /* length : always 2 */
uint8_t ip6r2_type; /* always 2 */
uint8_t ip6r2_segleft; /* segments left: always 1 */
uint32_t ip6r2_reserved; /* reserved field */
struct in6_addr ip6r2_homeaddr; /* Home Address */
};
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 9]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
3. Access to Home Address Destination Option and Routing Headers
Applications that need to be able to access home address destination
option and routing header type 2 information should use the same
mechanism defined in Advanced Sockets API for IPv6 in section 4.
In order to receive Home Address destination option or route header
type 2 extension header, application must call setsockopt() to turn
on the corresponding flag:
int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on));
When any of these options are enabled, the corresponding data is
returned as control information by recvmsg(), as one or more
ancillary data objects. Receiving the above information for TCP
applications is not defined in this document (see section 4.1 of
Advanced Sockets API for IPv6[1].
For sending home address destination option, ancillary data can be
used to specify the option content for a single datagram. This
only applies to datagram and raw sockets; not to TCP sockets.
For TCP data packets with home-address destination option may be
used with "sticky" option for all transmitted packets. However,
at this point, it is unknown why an application would want to
set home-address option along with its data packets as Mobile IPv6
protocol takes care of it transparently at the protocol stack.
Similarly it is not clear that if an application would need to
set Router Header Type 2 extension to send data packets as it
is taken care by the Mobile IPv6 protocol depending on the
binding cache information. Thus this document does not specifically
discuss the sending of Route Header Type 2 extension header.
However, the following socket option parameters and cmsghdr fields
may be used for sending the Home Address destination options.
opt level/ optname/ optval/
cmsg_level cmsg_type cmsg_data[]
------------ ------------ ------------------------
IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure
Some IPv6 implementations may support "sticky" options [1] for IPv6
destination option for datagram sockets.
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 10]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
3.1 Routing Header access functions
While accessing Routing header Type 2 extension header, one MUST
use type = 2 and segment = 1. The following functions are supported
for Mobile IPv6 applications for sending and receiving Routing
Header Type 2 headers:
size_t inet6_rth_space(int type, int segments);
void *inet6_rth_init(void *bp, int bp_len, int type, int segments);
int inet6_rth_add(void *bp, const struct in6_addr *addr);
int inet6_rth_segments(const void *bp);
struct in6_addr *inet6_rth_getaddr(const void *bp, int index);
NOTE: Reversing operation is not possible using Route Header Type 2
extension header.
Detail description and examples of accessing a IPv6 Route Header
are discussed in Advanced API for IPv6 Sockets [1].
3.2 Home Address Destination Option access functions
The application must enable the IPV6_RECVDSTOPTS socket option in
order to receive the home address destination option:
int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on));
Each Destination option header is returned as one ancillary data
object described by a cmsghdr structure with cmsg_level set to
IPPROTO_IPV6 and cmsg_type set to IPV6_DSTOPTS.
These options are then processed by calling the inet6_opt_next(),
inet6_opt_find(), and inet6_opt_get_value() functions as defined
in Advanced API for IPv6 sockets [1].
This document assumes that MobileIPv6 applications will not be
allowed to send Home Address Destination Option from the
application level, as Mobile IPv6 kernel takes care of sending
home-address option and routing header type 2. However, the order
of extension headers in conjunction with Home Address option sending
is specified in Mobility Support in IPv6 [2] in section 6.3.
The Destination options are normally constructed using the
inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and
inet6_opt_set_val() functions, described in Section 10 of IPv6
Advanced API sockets [1].
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 11]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
4. Mobility Protocol Headers
Mobile IPv6 [2] defines a new IPv6 protocol header to carry mobility
control messages among mobile devices and Home Agents and
Correspondent Nodes. These protocol headers carry Mobile IPv6 Binding
messages as well as Return Routability [2] messages. Currently the
specification does not allow transport packets along with the
mobility protocol header. Thus mobility protocol header can be
accessed through IPv6 RAW sockets. A IPv6 RAW socket that is opened
for protocol IPPROTO_MH should always be able to see all the MH
(Mobility Header) packets. It is possible that future applications
may implement part of Mobile IPv6 signal processing at the
application level. Having a RAW socket interface may also enable
an application to execute the Return Routability protocol or other
future authentication protocol involving mobility header at the user
level.
4.1 Receiving and Sending Mobility Header Messages
This specification recommends IPv6 RAW sockets mechanism to send
and receive Mobility Header (MH) packets. The behavior is similar to
ICMPV6 processing, where kernel passes a copy of the mobility header
packet to the receiving socket. Depending on the implementation
kernel may process the mobility header as well in addition to passing
the mobility header to the application. If IPV6_CHECKSUM socket
option is set on the RAW socket, kernel will calculate the checksum
by default and place it on the mobility header before sending it out.
Similarly, if IPV6_CHECKSUM is set, the protocol stack will verify
the MH checksum on the inbound path and it will discard any MH
packet with invalid checksums. Mobility Header checksum procedure
is described in Mobile IPv6 Protocol [2] specification.
Thus when IPPROTO_MH is used as the protocol field in the RAW
socket() call and IPV6_CHECKSUM option is not set, the application
needs to fill the checksum field of the mobility header for outbound
data. Similarly the application needs to do checksum validity check
for the received packet. Note that it is recommended that the
application set the IPV6_CHECKSUM socket option along with the RAW
sockets for IPPROTO_MH.
As an example, a program that wants to send or receive mobility
header protocol(MH), could open a socket as following:
fd = socket(AF_INET6, SOCK_RAW, IPPROTO_MH);
int offset = 4;
setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset,
sizeof(offset));
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 12]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
If the program likes to handle HOTI/HOT and COTI/COT message
processing, it can do so by using IPv6 RAW Sockets for IPPROTO_MH.
The same application may also set IPV6_RECVDSTOPTS socket option for
receiving home address option in a binding update [2] from the mobile
node.
5. Protocols File
Many hosts provide the file /etc/protocols that contains the names
of the various IP protocols and their protocol numbers. The protocol
numbers are obtained through function getprotoXXX() functions.
The following addition should be made to the /etc/protocols file,
in addition to what is defined in section 2.4 of Advanced Sockets
API for IPv6 [1].
The protocol number for Mobility is pending IANA
(http://www.iana.orgassignments/protocol-numbers) assignment.
ipv6-mh 62(?) # Mobility Protocol Header
6. IPv4-Mapped IPv6 Addresses
The same rule applies as described in section 13 of IPv6 Advanced
API for Sockets [1]. Thus processing of IPv4-mapped IPv6 addresses
for the MobileIPv6 specific socket options are out of scope of this
document.
7. Security Considerations
The setting of Home Address Destination option and route header
Type 2 IPV6_RTHDR socket option may not be allowed at the
application level in order to prevent denial-of-service attacks
or man in the middle attacks by hackers.
Sending and receiving of mobility header messages are possible by
IPv6 RAW sockets. Thus it is assumed that this operation is only
possible by priviledged users. However, it does not prevent the
existing security threat by a hacker sending bogus mobility header
or other IPv6 packets using home-address option and Type 2 routing
extension header.
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 13]
INTERNET-DRAFT Extension to Sockets API for MIPv6 February, 2003
8. References
[1] Stevens, W. R, Thomas, M., Nordmark, E., Jinmei, T., "Advanced
Sockets API for IPv6", draft-ietf-ipngwg-rfc2292bis-07.txt
April 19, 2002.
[2] Johnson, D., Perkins, C., Arkko, J., "Mobility Support in IPv6"
draft-ietf-mobileip-ipv6-20.txt, January, 2003.
[3] Deering, S., Hinden, R., "Internet Protocol, Version 6
(IPv6), Specification", RFC 2460, Dec. 1998.
9. Authors' Addresses
Samita Chakrabarti
Sun Microsystems, Inc.
4150 Network Circle
Santa Clara, CA 95054, USA
Email: [EMAIL PROTECTED]
Erik Nordmark
Sun Microsystems Laboratories
180, avenue de l'Europe
38334 SAINT ISMIER Cedex, France
Email: [EMAIL PROTECTED]
draft-chakrabarti-mobileip-mipext-advapi-00.txt [Page 14]
