Request for Comments: 4584 E. Nordmark
Category: Informational Sun Microsystems
July 2006
Extension to Sockets API for Mobile IPv6
Status of This Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document describes data structures and API support for Mobile
IPv6 as an extension to the Advanced Socket API for IPv6.
Just as the Advanced Sockets API for IPv6 gives access to various
extension headers and the ICMPv6 protocol, this document specifies
the same level of access for Mobile IPv6 components. It specifies a
mechanism for applications to retrieve and set information for
Mobility Header messages, Home Address destination options, and
Routing Header Type 2 extension headers. It also specifies the
common data structures and definitions that might be used by certain
advanced Mobile IPv6 socket applications.
Table of Contents
1. Introduction ....................................................3
2. Applicability ...................................................4
3. Overview ........................................................5
4. Common Structures and Definitions ...............................6
4.1. The Mobility Header Data Structures ........................6
4.1.1. The ip6_mh Structure ................................6
4.1.2. Binding Refresh Request Mobility Message ............7
4.1.3. Home Address Test Init (HoTI) Message ...............7
4.1.4. Care-of Address Test Init (CoTI) Message ............7
4.1.5. Home Address Test (HOT) Message .....................8
4.1.6. Care Of Address Test (COT) Message ..................8
4.1.7. Binding Update Mobility Message .....................8
4.1.8. Binding Acknowledgement Mobility Message ............9
4.1.9. Binding Error Mobility Message ......................9
4.1.10. Mobility Option TLV data structure .................9
4.1.11. Mobility Option Data Structures ...................10
4.1.11.1. Binding Refresh Advice ...................10
4.1.11.2. Alternate Care-of Address ................10
4.1.11.3. Nonce Indices ............................10
4.1.11.4. Binding Authorization Data ...............10
4.2. Mobility Header Constants .................................10
4.3. IPv6 Home Address Destination Option ......................12
4.4. Type 2 Routing Header .....................................12
4.5. New ICMP Messages for Mobile IPv6 .........................13
4.6. IPv6 Neighbor Discovery Changes ...........................14
5. Access to Home Address Destination Option and Routing Headers ..15
5.1. Routing Header Access Functions ...........................17
5.2. Content of Type 2 Routing Header ..........................18
5.3. Order of Extension Headers for Home Address
Destination Options .......................................19
5.4. Home Address Destination Option Access Functions ..........20
5.5. Content of Home Address Destination Option ................20
6. Mobility Protocol Headers ......................................21
6.1. Receiving and Sending Mobility Header Messages ............21
7. Protocols File .................................................22
8. IPv4-Mapped IPv6 Addresses .....................................23
9. Security Considerations ........................................23
10. IANA Considerations ...........................................23
11. Acknowledgements ..............................................23
12. References ....................................................24
12.1. Normative References .....................................24
12.2. Informative References ...................................24
1. Introduction
Mobility Support in IPv6 [2] defines a new Mobility Protocol header,
a Home Address destination option and a new Routing Header type. It
is expected that Mobile IPv6 user-level implementations and some
special applications will need to access and process these IPv6
extension headers. This document is an extension to the existing
Advanced Sockets API document [1]; it addresses the Advanced IPv6
Sockets API for these new protocol elements defined by Mobile IPv6.
The applicability of this API mainly targets user-level applications.
However, it has also been shown to be useful within some Mobile IPv6
implementations; for instance, where part of the Mobile IPv6 protocol
is implemented at user-level and part in the kernel. It is up to any
such implementations to architect which part of the Mobile IPv6 and
IP Security (IPSec) packet processing should be done at the user-
level in order to meet the design needs of the particular platform
and operating system.
The target user-level applications for this socket API are believed
to be debugging and diagnostic applications and some policy
applications that would like to receive copies of protocol
information at the application layer.
The packet information and 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 document is consistent with Advanced Sockets API for IPv6 [1] in
structure definitions, header files, and function definitions. Thus,
the implementors of this API document are assumed to be familiar with
the data structures, data sending and receiving procedures, and the
IPv6 extension header access functions described in the Advanced
Sockets API for IPv6 [1].
Non-goals
This document does not address application access to either the
Authentication Header or the Encapsulating Security Payload header.
This document also does not address any API that might be necessary
for Mobile Network [4] specific needs. Furthermore, note that this
API document excludes discussion on application-level API. It
assumes that address selection socket API [5] takes care of selection
of care-of address or home address as the source address by the
application, when source address selection is required due to the
nature of the application.
Providing mobility "awareness" to applications, such as applications’
being able to tell whether the host is at home or not, is out of
scope for this API.
2. Applicability
This API document can be applied in the following cases:
1. User-level debugging and monitoring tools: This socket API is
useful for accessing Mobility Headers, Home Address destination
options and Type 2 Routing Headers . For example, mh-ping might
be a monitoring tool that can process mobility headers on the
receiving side to check binding status.
2. Partial user-level implementation of Mobile IPv6: We assume that
some implementations may choose to do the Mobility header
processing at user level. In that case, this document recommends
implementing at least the handling of Home Address destination
options and Type 2 Routing Header in the main IP processing paths
in the kernel. The API can then be used to send and receive the
Mobility Header packets used for Mobile IPv6 signaling.
3. Complete header processing at the kernel-level: Many
implementations of Mobile IPv6 [2] perform processing of Home
Address destination options, Type 2 Routing Headers, and Mobility
headers at the kernel level. However, the kernel keeps a copy of
the received extension headers and passes them up to the API,
which is used by the user-level applications purely for
monitoring and debugging Mobile IPv6 packets.
On an IPv6 host that does not implement Mobile IPv6, the IPv6
specification [3] requires that packets with the Home Address option
or Type 2 Routing Header (where segments left is non-zero) be dropped
on receipt. This means that it is not possible to implement Mobile
IPv6 as an application on such a system. Thus, on such a system, the
applicability of this API is limited to the first case above,
enabling debugging and monitoring applications (such as tcpdump) to
parse and interpret Mobile IPv6 packets.
3. Overview
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
applications. This is captured in Section 4. In addition,
Section 4 also defines data structures for Home Address
destination option, Type 2 Routing Header, and new ICMPv6
messages related to Mobile IPv6.
2. Notes on how to use the IPv6 Advanced API to access Home Address
options and Type 2 Routing Headers. This is captured in Section
5.
3. Notes on how user-level applications can observe MH (Mobility
Header) packets using raw sockets (in Section 6). The IPv6 RAW
socket interface described in this document allows applications
to receive MH packets whether or not the system’s MH processing
takes place in the "kernel" or at the "user space".
4. A name is suggested for IPv6 Mobility Header protocol in /etc/
protocols (in Section 7).
All examples in this document omit error checking in favor of
brevity, as it is following the same style as the Advanced Socket API
[1].
Note that many of the functions and socket options defined in this
document may have error returns that are not defined in this
document.
Data types 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).
Once the API specification becomes mature and is deployed, it may be
formally standardized by a more appropriate body, as has been done
with the Basic API [6]. However, since this specification largely
builds upon the Advanced Socket API [1], such standardization would
make sense only if the Advanced Socket API [1] were also
standardized.
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 RFC 2119.
4. Common Structures and Definitions
In this section, the structures are specified in a way so that they
maximize the probability that the compiler-layout of data structures
are identical to the packet formats on the wire. However, ANSI-C
provides few guarantees about the size and alignment of data
structures.
The assumption is that the Advanced Socket API [1] will pass up the
actual packet content (the wire format) in the buffer and in the
ancillary data objects. Thus, if an implementor has to handle a
system where the ANSI-C compiler does not and can not lay out these
structures to match the wire formats in RFC 3775 [2], the structures
defined by this API can not be supported on such a system.
The constants and structures shown below are in network byte order,
so an application needs to perform the appropriate byte order
conversion (ntohs(), etc) when necessary.
The structures and constants below will be included when the (new)
header file is included : <netinet/ip6mh.h>
4.1. The Mobility Header Data Structures
4.1.1. The ip6_mh Structure
The following structure is defined as a result of including
<netinet/ip6mh.h>. This is the fixed part of the Mobility Header.
Different Mobility message types are defined in Mobile IPv6 [2]. For
portability and alignment reasons, each mobility message type
includes the mobility header fields instead of including the ip6_mh
structure, followed by the message-specific fields.
struct ip6_mh {
uint8_t ip6mh_proto; /* NO_NXTHDR by default */
uint8_t ip6mh_hdrlen; /* Header Len in unit of 8 Octets
excluding the first 8 Octets */
uint8_t ip6mh_type; /* Type of Mobility Header */
uint8_t ip6mh_reserved; /* Reserved */
uint16_t ip6mh_cksum; /* Mobility Header Checksum */
/* Followed by type specific messages */
};
4.1.2. Binding Refresh Request Mobility Message
struct ip6_mh_binding_request {
uint8_t ip6mhbr_proto;
uint8_t ip6mhbr_hdrlen;
uint8_t ip6mhbr_type;
uint8_t ip6mhbr_reserved;
uint16_t ip6mhbr_cksum;
uint16_t ip6mhbr_reserved2;
/* Followed by optional Mobility Options */
};
4.1.3. Home Address Test Init (HoTI) Message
struct ip6_mh_home_test_init {
uint8_t ip6mhhti_proto;
uint8_t ip6mhhti_hdrlen;
uint8_t ip6mhhti_type;
uint8_t ip6mhhti_reserved;
uint16_t ip6mhhti_cksum;
uint16_t ip6mhhti_reserved2;
uint32_t ip6mhhti_cookie[2]; /* 64 bit Cookie by MN */
/* Followed by optional Mobility Options */
};
4.1.4. Care-of Address Test Init (CoTI) Message
struct ip6_mh_careof_test_init {
uint8_t ip6mhcti_proto;
uint8_t ip6mhcti_hdrlen;
uint8_t ip6mhcti_type;
uint8_t ip6mhcti_reserved;
uint16_t ip6mhcti_cksum;
uint16_t ip6mhcti_reserved2;
uint32_t ip6mhcti_cookie[2]; /* 64 bit Cookie by MN */
/* Followed by optional Mobility Options */
};
4.1.5. Home Address Test (HOT) Message
struct ip6_mh_home_test {
uint8_t ip6mhht_proto;
uint8_t ip6mhht_hdrlen;
uint8_t ip6mhht_type;
uint8_t ip6mhht_reserved;
uint16_t ip6mhht_cksum;
uint16_t ip6mhht_nonce_index;
uint32_t ip6mhht_cookie[2]; /* Cookie from HOTI msg */
uint32_t ip6mhht_keygen[2]; /* 64 Bit Key by CN */
/* Followed by optional Mobility Options */
};
4.1.6. Care Of Address Test (COT) Message
struct ip6_mh_careof_test {
uint8_t ip6mhct_proto;
uint8_t ip6mhct_hdrlen;
uint8_t ip6mhct_type;
uint8_t ip6mhct_reserved;
uint16_t ip6mhct_cksum;
uint16_t ip6mhct_nonce_index;
uint32_t ip6mhct_cookie[2]; /* Cookie from COTI message */
uint32_t ip6mhct_keygen[2]; /* 64bit key by CN */
/* Followed by optional Mobility Options */
};
4.1.7. Binding Update Mobility Message
struct ip6_mh_binding_update {
uint8_t ip6mhbu_proto;
uint8_t ip6mhbu_hdrlen;
uint8_t ip6mhbu_type;
uint8_t ip6mhbu_reserved;
uint16_t ip6mhbu_cksum;
uint16_t ip6mhbu_seqno; /* Sequence Number */
uint16_t ip6mhbu_flags;
uint16_t ip6mhbu_lifetime; /* Time in unit of 4 sec */
/* Followed by optional Mobility Options */
};
/* Binding Update Flags, in network byte-order */
#define IP6_MH_BU_ACK 0x8000 /* Request a binding ack */
#define IP6_MH_BU_HOME 0x4000 /* Home Registration */
#define IP6_MH_BU_LLOCAL 0x2000 /* Link-local compatibility */
#define IP6_MH_BU_KEYM 0x1000 /* Key management mobility */
4.1.8. Binding Acknowledgement Mobility Message
struct ip6_mh_binding_ack {
uint8_t ip6mhba_proto;
uint8_t ip6mhba_hdrlen;
uint8_t ip6mhba_type;
uint8_t ip6mhba_reserved;
uint16_t ip6mhba_cksum;
uint8_t ip6mhba_status; /* Status code */
uint8_t ip6mhba_flags;
uint16_t ip6mhba_seqno;
uint16_t ip6mhba_lifetime;
/* Followed by optional Mobility Options */
};
/* Binding Acknowledgement Flags */
#define IP6_MH_BA_KEYM 0x80 /* Key management mobility */
4.1.9. Binding Error Mobility Message
struct ip6_mh_binding_error {
uint8_t ip6mhbe_proto;
uint8_t ip6mhbe_hdrlen;
uint8_t ip6mhbe_type;
uint8_t ip6mhbe_reserved;
uint16_t ip6mhbe_cksum;
uint8_t ip6mhbe_status; /* Error Status */
uint8_t ip6mhbe_reserved2;
struct in6_addr ip6mhbe_homeaddr;
/* Followed by optional Mobility Options */
};
4.1.10. Mobility Option TLV data structure
struct ip6_mh_opt {
uint8_t ip6mhopt_type; /* Option Type */
uint8_t ip6mhopt_len; /* Option Length */
/* Followed by variable length Option Data in bytes */
};
4.1.11. Mobility Option Data Structures
4.1.11.1. Binding Refresh Advice
struct ip6_mh_opt_refresh_advice {
uint8_t ip6mora_type;
uint8_t ip6mora_len;
uint16_t ip6mora_interval; /* Refresh interval in 4 sec */
};
4.1.11.2. Alternate Care-of Address
struct ip6_mh_opt_altcoa {
uint8_t ip6moa_type;
uint8_t ip6moa_len;
struct in6_addr ip6moa_addr; /* Alternate CoA */
};
4.1.11.3. Nonce Indices
struct ip6_mh_opt_nonce_index {
uint8_t ip6moni_type;
uint8_t ip6moni_len;
uint16_t ip6moni_home_nonce;
uint16_t ip6moni_coa_nonce;
};
4.1.11.4. Binding Authorization Data
struct ip6_mh_opt_auth_data {
uint8_t ip6moad_type;
uint8_t ip6moad_len;
uint8_t ip6moad_data[12];
};
4.2. Mobility Header Constants
IPv6 Next Header Value for Mobility:
<netinet/in.h>
#define IPPROTO_MH 135 /* IPv6 Mobility Header: IANA */
Mobility Header Message Types:
<netinet/ip6mh.h>
#define IP6_MH_TYPE_BRR 0 /* Binding Refresh Request */
#define IP6_MH_TYPE_HOTI 1 /* HOTI Message */
#define IP6_MH_TYPE_COTI 2 /* COTI Message */
#define IP6_MH_TYPE_HOT 3 /* HOT Message */
#define IP6_MH_TYPE_COT 4 /* COT Message */
#define IP6_MH_TYPE_BU 5 /* Binding Update */
#define IP6_MH_TYPE_BACK 6 /* Binding ACK */
#define IP6_MH_TYPE_BERROR 7 /* Binding Error */
Mobility Header Message Option Types:
<netinet/ip6mh.h>
#define IP6_MHOPT_PAD1 0x00 /* PAD1 */
#define IP6_MHOPT_PADN 0x01 /* PADN */
#define IP6_MHOPT_BREFRESH 0x02 /* Binding Refresh */
#define IP6_MHOPT_ALTCOA 0x03 /* Alternate COA */
#define IP6_MHOPT_NONCEID 0x04 /* Nonce Index */
#define IP6_MHOPT_BAUTH 0x05 /* Binding Auth Data */
Status values accompanied with Mobility Binding Acknowledgement:
<netinet/ip6mh.h>
#define IP6_MH_BAS_ACCEPTED 0 /* BU accepted */
#define IP6_MH_BAS_PRFX_DISCOV 1 /* Accepted, but prefix
discovery Required */
#define IP6_MH_BAS_UNSPECIFIED 128 /* Reason unspecified */
#define IP6_MH_BAS_PROHIBIT 129 /* Administratively
prohibited */
#define IP6_MH_BAS_INSUFFICIENT 130 /* Insufficient
resources */
#define IP6_MH_BAS_HA_NOT_SUPPORTED 131 /* HA registration not
supported */
#define IP6_MH_BAS_NOT_HOME_SUBNET 132 /* Not Home subnet */
#define IP6_MH_BAS_NOT_HA 133 /* Not HA for this
mobile node */
#define IP6_MH_BAS_DAD_FAILED 134 /* DAD failed */
#define IP6_MH_BAS_SEQNO_BAD 135 /* Sequence number out
of range */
#define IP6_MH_BAS_HOME_NI_EXPIRED 136 /* Expired Home nonce
index */
#define IP6_MH_BAS_COA_NI_EXPIRED 137 /* Expired Care-of
nonce index */
#define IP6_MH_BAS_NI_EXPIRED 138 /* Expired Nonce
Indices */
#define IP6_MH_BAS_REG_NOT_ALLOWED 139 /* Registration type
change disallowed */
Status values for the Binding Error mobility messages:
<netinet/ip6mh.h>
#define IP6_MH_BES_UNKNOWN_HAO 1 /* Unknown binding for HOA */
#define IP6_MH_BES_UNKNOWN_MH 2 /* Unknown MH Type */
4.3. IPv6 Home Address Destination Option
Due to alignment issues in the compiler, and the alignment
requirements for this option, the included IPv6 address must be