Description

The authoritative reference text on KAME and IPv6!

IPv6 was introduced in 1994 and has been in development at the IETF for over 10 years. It has now reached the deployment stage. KAME, the de-facto open-source reference implementation of the IPv6 standards, played a significant role in the acceptance and the adoption of the IPv6 technology. The adoption of KAME by key companies in a wide spectrum of commercial products is a testimonial to the success of the KAME project, which concluded not long ago.

This book is the first and the only one of its kind, which reveals all of the details of the KAME IPv6 protocol stack, explaining exactly what every line of code does and why it was designed that way. Through the dissection of both the code and its design, the authors illustrate how IPv6 and its related protocols have been interpreted and implemented from the specifications. This reference will demystify those ambiguous areas in the standards, which are open to interpretation and problematic in deployment, and presents solutions offered by KAME in dealing with these implementation challenges.

About the Authors
Qing Li is a senior architect at Blue Coat Systems, Inc. leading the design and development efforts of the next-generation IPv6 enabled secure proxy appliances. Qing holds multiple US patents. Qing is a contributing author of the book titled Handbook of Networked and Embedded Control Systems published in June 2005. He is the author of the embedded systems development book titled Real-Time Concepts for Embedded Systems published in April 2003. Tatuya Jinmei Ph.D. is a research scientist at Corporate Research & Development Center, Toshiba Corporation. He had been a core developer of the KAME project since the launch of the project through its conclusion. In 2003, he received the Ph.D. degree from Keio University, Japan, based on his work at KAME. Keiichi Shima is a senior researcher at Internet Initiative Japan Inc. He was a core developer of the KAME project from 2001 to the end of the project and developed Mobile IPv6/NEMO Basic Support protocol stack. He is now working on the new mobility stack (the SHISA stack) for BSD operating systems.

 

Table of Contents

Foreword
Preface
1 Introduction
1.1 Introduction
1.2 A Brief History of IPv6 and KAME
1.2.1 Commercial Success of KAME
1.3 Overview of the KAME Distribution
1.3.1 Source Tree Structure
1.3.2 Build Procedure
1.4 Overview of BSD Network Implementation
1.5 Source Code Narrations
1.5.1 Typographical Conventions
1.5.2 Sample Source Code Description
1.5.3 Preprocessor Variables
1.5.4 Networking Device and Architecture Assumptions
1.6 Mbufs and IPv6
1.6.1 Common Mbuf Manipulation Macros and Functions
1.6.2 Mbuf Tagging
1.6.3 Mbuf Requirement for IPv6
1.6.4 Diagnosing Mbuf Chain

2 IPv6 Addressing Architecture
2.1 Introduction
2.2 IPv6 Addresses
2.3 Textual Representation of IPv6 Addresses
2.4 Address Scopes
2.4.1 Scope Zones
2.4.2 Zone Indices
2.4.3 Textual Representation of Scoped Addresses
2.4.4 Deprecation of Unicast Site-local Addresses
2.5 IPv6 Address Format
2.5.1 Interface Identifier Generation
2.5.2 Notes about Address Format
2.5.3 Multicast Address Format
2.6 Node Address Requirements
2.7 IPv6 Address Space Management
2.8 Code Introduction
2.8.1 IPv6 Address Structures—in6_addr{} and sockaddr_in6{}
2.8.2 Macros and Variables
2.9 Handling Scope Zones
2.9.1 Initialization of Scope Zones
2.9.2 Scope Zone IDs
2.9.3 Zone IDs in Address Structures
2.9.4 Scope-Related Utility Functions
2.10 Interface Address Structures
2.10.1 ifaddr{} and in6_ifaddr{} Structures
2.10.2 in6_ifreq{} and in6_aliasreq{} Structures
2.10.3 Multicast Address Structures
2.11 IPv6 Prefix Structure
2.12 Overview of Address Manipulation Routines
2.13 Interface Initialization for IPv6
2.13.1 in6_if_up() Function
2.13.2 in6_ifattach() Function
2.13.3 in6_ifattach_loopback() Function
2.13.4 in6_ifattach_linklocal() Function
2.13.5 get_ifid() Function
2.13.6 get_hw_ifid() Function
2.13.7 get_rand_ifid() Function
2.13.8 in6if_do_dad() Function
2.14 IPv6 Interface Address Configuration
2.14.1 in6_control() Function
2.14.2 in6_update_ifa() Function
2.14.3 in6_joingroup() and in6_leavegroup() Functions
2.14.4 in6_addmulti() and in6_delmulti()Functions
2.14.5 in6_ifinit() Function
2.14.6 in6_ifaddloop() and in6_ifloop_request() Functions
2.15 Deleting an IPv6 Address
2.15.1 in6_purgeaddr() Function
2.15.2 in6_ifremloop() Function
2.15.3 in6_unlink_ifa() Function
2.16 Operation with Address Configuration Utility

3 Internet Protocol version 6
3.1 Introduction
3.2 IPv6 Header Format
3.2.1 Comparison to the IPv4 Header
3.3 IPv6 Extension Headers
3.3.1 Order of Extension Headers
3.3.2 Hop-by-Hop Options Header
3.3.3 Destination Options Header
3.3.4 Routing Header
3.3.5 Fragment Header
3.3.6 IPv6 Options
3.4 Source Address Selection
3.4.1 Default Address Selection
3.4.2 Source Address Selection
3.4.3 Destination Address Selection
3.5 Code Introduction
3.5.1 Statistics
3.5.2 Header Structures
3.5.3 ip6protosw{} Structure
3.6 IPv6 Packet Address Information in Mbuf
3.6.1 ip6_setdstifaddr() Function
3.6.2 ip6_getdstifaddr() Function
3.6.3 ip6_setpktaddrs() Function
3.6.4 ip6_getpktaddrs() Function
3.7 Input Processing: ip6_input() Function
3.8 Processing Hop-by-Hop Options Header: ip6_hopopts_input() Function
3.8.1 Processing Each Option: ip6_process_hopopts()Function
3.8.2 Processing Unknown Option: ip6_unknown_opt()Function
3.9 Processing Destination Options Header: dest6_input() Function
3.10 Reassembling Fragmented Packets
3.10.1 Structures for Packet Reassembly
3.10.2 frag6_input()F unction 1
3.11 Processing Routing Header: route6_input()Function
3.12 Forwarding: ip6_forward() Function
3.13 Output Processing
3.13.1 Source Address Selection—in6_selectsrc() Function
3.13.2 Route Selection: ip6_selectroute() Function
3.13.3 ip6_output() Function
3.13.4 Make Extension Headers: ip6_copyexthdr()Function
3.13.5 Split Headers: ip6_splithdr() Function
3.13.6 Insert Jumbo Payload Option: ip6_insert_jumboopt() Function
3.13.7 Fragmentation: ip6_insertfraghdr() Function
3.13.8 Path MTU Determination: ip6_getpmtu()Function
3.13.9 Multicast Loopback: ip6_mloopback() Function

4 Internet Control Message Protocol for IPv6
4.1 Introduction
4.2 ICMPv6 Message
4.2.1 Destination Unreachable Message
4.2.2 Packet Too Big Message
4.2.3 Time Exceeded Message
4.2.4 Parameter Problem Message
4.2.5 Echo Request Message
4.2.6 Echo Reply Message
4.2.7 ICMPv6 Message Processing Rules
4.3 Path MTU Discovery Mechanism
4.4 Node Information Query
4.4.1 Node Information Message Format
4.4.2 NOOP Query
4.4.3 Supported Qtypes Query
4.4.4 Node Name Query
4.4.5 Node Addresses Query
4.4.6 IPv4 Addresses Query
4.5 Code Introduction
4.5.1 Statistics
4.5.2 ICMPv6 Header
4.6 ICMPv6 Input Processing
4.6.1 icmp6_input() Function
4.6.2 Notifying Errors: icmp6_notify_error()Function
4.7 Path MTU Discovery Implementation
4.7.1 icmp6_mtudisc_update() Function
4.8 ICMPv6 Output Processing
4.8.1 Sending Error: icmp6_error() Function
4.8.2 Error Rate Limitation: icmp6_ratelimit()Function
4.8.3 icmp6_reflect() Function
4.9 Node Information Query Implementation
4.9.1 Types and Variables
4.9.2 ping6 Command: Send Queries
4.9.3 ping6 Command: Receive Replies
4.9.4 ping6 Command: Print Supported Qtypes
4.9.5 ping6 Command: Print Node Addresses
4.9.6 Query Processing: ni6_input() Function
4.9.7 Node Name Manipulation
4.9.8 Create Node Addresses Reply: ni6_store_addrs()Function
4.10 NodeInformation Operation

5 Neighbor Discovery and Stateless Address Autoconfiguration
5.1 Introduction
5.2 Neighbor Discovery Protocol Overview
5.3 Stateless Address Autoconfiguration Overview
5.4 ND Protocol Messages
5.5 Example Exchanges of ND Protocol Messages
5.6 ND Protocol Packet Types and Formats
5.6.1 Router Solicitation Message
5.6.2 Router Advertisement Message
5.6.3 Neighbor Solicitation Message
5.6.4 Neighbor Advertisement Message
5.6.5 Redirect Message
5.7 Neighbor Discovery Option Types and Formats
5.7.1 Link-Layer Address Options
5.7.2 Prefix Information Option
5.7.3 Redirected Header Option
5.7.4 MTU Option
5.7.5 Route Information Option
5.8 Next-Hop Determination and Address Resolution
5.9 Neighbor Unreachability Detection Algorithm
5.10 Stateless Address Autoconfiguration
5.10.1 Address Formation and Address States
5.10.2 Duplicate Address Detection Algorithm
5.10.3 Processing Router Advertisement
5.10.4 Privacy Extensions
5.11 Router Specific Operation
5.11.1 Sending Unsolicited Router Advertisements
5.11.2 Processing Router Solicitations
5.11.3 Processing Router Advertisements
5.12 Host Specific Operations
5.12.1 Sending Router Solicitations
5.12.2 Processing Router Advertisements
5.12.3 Default Router Selection
5.13 Code Introduction
5.13.1 ND Message Definitions
5.13.2 Neighbor Cache—llinfo_nd6{} Structure
5.13.3 Operational Variables—nd_ifinfo{} Structure
5.13.4 Default Router—nd_defrouter{} Structure
5.13.5 Prefix—nd_prefix{} Structure
5.13.6 Prefix Control—nd_prefixctl{} Structure
5.13.7 ND Message Options—nd_opts{} Structure
5.13.8 DAD Queue Entry—dadq{} Structure
5.13.9 IPv6 Address—in6_ifaddr{} Structure
5.13.10 Destination Cache
5.13.11 Operation Constants
5.14 Initialization Functions
5.14.1 nd6_init() Function
5.14.2 nd6_ifattach() Function
5.15 Neighbor Cache Management Functions
5.15.1 nd6_rtrequest() Function
5.15.2 nd6_cache_lladdr() Function
5.15.3 nd6_lookup() Function
5.15.4 nd6_free() Function
5.15.5 nd6_timer() Function
5.16 ND Protocol Messages Processing Functions
5.16.1 nd6_ns_output() Function
5.16.2 nd6_ns_input() Function
5.16.3 nd6_na_input() Function
5.16.4 nd6_na_output() Function
5.16.5 nd6_rs_input() Function
5.16.6 nd6_ra_input() Function
5.16.7 icmp6_redirect_input() Function
5.16.8 icmp6_redirect_output() Function
5.17 ND Protocol Message Options Processing Functions
5.17.1 nd6_option_init() Function
5.17.2 nd6_option() Function
5.17.3 nd6_options() Function
5.18 Default Router Management Functions
5.18.1 defrouter_addreq() Function
5.18.2 defrouter_delreq() Function
5.18.3 defrouter_addifreq() Function
5.18.4 defrouter_delifreq() Function
5.18.5 defrouter_lookup() Function
5.18.6 defrouter_select() Function
5.18.7 defrtrlist_del() Function
5.18.8 defrtrlist_update() Function
5.19 Prefix Management Functions
5.19.1 nd6_prelist_add() Function
5.19.2 prelist_remove() Function
5.19.3 prelist_update() Function
5.19.4 find_pfxlist_reachable_router() Function
5.19.5 Prefix and Address State about On-link Condition
5.19.6 pfxlist_onlink_check() Function
5.19.7 nd6_prefix_onlink() Function
5.19.8 nd6_prefix_offlink() Function
5.20 Stateless Address Autoconfiguration Functions
5.20.1 in6_ifadd() Function
5.20.2 in6_tmpifadd() Function
5.20.3 regen_tmpaddr() Function
5.21 Duplicate Address Detection Functions
5.21.1 nd6_dad_find() Function
5.21.2 nd6_dad_starttimer() Function
5.21.3 nd6_dad_stoptimer() Function
5.21.4 nd6_dad_start() Function
5.21.5 nd6_dad_stop() Function
5.21.6 nd6_dad_timer() Function
5.21.7 nd6_dad_duplicated() Function
5.21.8 nd6_dad_ns_output() Function
5.21.9 nd6_dad_ns_input() Function
5.21.10 nd6_dad_na_input() Function
5.22 Miscellaneous Functions
5.22.1 nd6_is_addr_neighbor() Function
5.22.2 nd6_output() Function
5.22.3 rt6_flush() Function
5.22.4 nd6_rtmsg() Function

6 Transport Layer Implications
6.1 Introduction
6.2 TCP and UDP over IPv6
6.3 Pseudo Header for IPv6
6.4 Checksum Difference between IPv4 and IPv6
6.5 IPv4-mapped IPv6 Address Usage
6.6 Code Introduction
6.6.1 Protocol Control Blocks for IPv6
6.7 General Operations on PCBs and Sockets
6.7.1 IPv6 PCB Allocation—in_pcballoc() Function
6.7.2 Bind Local Address—in6_pcbbind() Function
6.7.3 Fix Remote Address—in6_pcbconnect() Function
6.7.4 Function in6_pcbladdr()
6.7.5 Search for a PCB Entry—in6_pcblookup_local()Function
6.7.6 Search for IPv4-mapped PCB—in_pcblookup_local() Function
6.7.7 Search for a PCB Entry—in6_pcblookup_hash()Function
6.7.8 Search for IPv4-mapped PCB—in_pcblookup_hash()
Function
6.7.9 Detach an IPv6 PCB—in6_pcbdetach() Function
6.7.10 Control Message Signaling—in6_pcbnotify()
Function
6.7.11 Flush PCB Cached Route—in6_rtchange()Function
6.7.12 Retrieve Peer Address—in6_setpeeraddr()Function
6.7.13 Retrieve Local Address—in6_setscokaddr()
Function
6.8 TCP-over-IPv6
6.8.1 TCP-over-IPv6 Instance of ip6protosw{}
6.8.2 TCP Output
6.8.3 Initializing Headers—tcp_fillheaders() Function
6.8.4 TCP Input—tcp6_input() and tcp_input()
Functions
6.8.5 TCP Control Input—tcp6_ctlinput() Function
6.8.6 TCP User Requests
6.9 UDP-over-IPv6
6.9.1 UDP-over-IPv6 Instance of ip6protosw{}
6.9.2 UDP Output—udp6_output() Function
6.9.3 UDP Input—udp6_input() Function
6.9.4 UDP Control Input—udp6_ctlinput() Function
6.9.5 UDP User Requests Handling
6.10 Raw IPv6
6.10.1 Raw IPv6 Statistics
6.10.2 Raw IPv6 Output—rip6_output() Function
6.10.3 Raw IPv6 Input—rip6_input() Function
6.10.4 ICMPv6 Input—icmp6_rip6_input() Function
6.10.5 Raw IPv6 Control Input—rip6_ctlinput()Function
6.10.6 Raw IPv6 Control Output—rip6_ctloutput()
Function
6.10.7 Raw IPv6 User Requests Handling
6.11 Summary of Operation with IPv4-mapped IPv6 Addresses
6.12 Viewing IPv6 Connections with netstat
6.13 Configuring IPv4-mapped IPv6 Address Support

7 Socket API Extensions
7.1 Introduction
7.2 The Basic Socket API—RFC3493
7.2.1 Basic Definitions
7.2.2 Interface Identification
7.2.3 IPv4 Communication over AF_INET6 Socket
7.2.4 Address and Name Conversion Functions
7.2.5 Basic Socket Options
7.3 The Advanced Socket API—RFC3542
7.3.1 Advanced Definitions
7.3.2 IPv6 Raw Sockets
7.3.3 Introduction to Ancillary Data
7.3.4 IPv6 Packet Information
7.3.5 Manipulation of IPv6 Extension Headers
7.3.6 Path MTU APIs
7.3.7 Socket Extensions for the “r” Commands
7.3.8 Summary Tables of Socket Options
7.4 Kernel Implementation of IPv6 Socket APIs
7.4.1 Code Introduction
7.4.2 ip6_pktopts{} Structure
7.4.3 IPv6 Socket Option Processing—ip6_ctloutput()
Function
7.4.4 Getting Socket Options—ip6_getpcbopt() Function
7.4.5 Setting Socket Options and Ancillary Data
7.4.6 Cleaning Up—ip6_freepcbopts() Function
7.4.7 IPv6 Multicast Socket Options
7.4.8 IPv6 Raw Socket Options—ip6_raw_ctloutput()
Function
7.4.9 ICMPv6 Socket Options—icmp6_ctloutput()
Function
7.4.10 Delivering Incoming Information—ip6_savecontrol()Function
7.5 Socket Options and Ancillary Data Examples
7.5.1 Example of the Send Path
7.5.2 Example of the Receive Path
7.6 Implementation of Library Functions—libinet6 7.6.1 inet_pton() and inet_pton6() Functions
7.6.2 inet_ntop() and inet_ntop6() Functions
7.6.3 getaddrinfo() Function
7.6.4 Address Ordering Examples
7.6.5 freeaddrinfo() Function
7.6.6 gai_strerror() Function
7.6.7 getnameinfo() Function
7.6.8 Other Library Functions

References