IPv6 Application Programming Interface

IPv6 Standard ApplicationProgramming- APT-NAv6 Center Joint Workshop on IPv6 -USAGI/WIDE Project / Keio UniversityYOSHIFUJI Hideaki yoshfuji@linux-ipv6.org hideaki@yoshifuji.org Copyright (C)2002, 2004, 2006 YOSHIFUJI Hideaki / USAGI/WIDE Project,All Rights Reserved.

Goal of This Session Learn Standard, Basic Socket API (RFC3493) Overview of specificationQuestion / Answers / DiscussionLearn Advanced Socket API (RFC3542) If time allowsOverview of specificationSlides and sample codes will be available Av6-IPV6-WORKSHOP/

Table of Contents IPv6-aware Network ApplicationProgramming Basic Socket API(RFC3493)Advanced Socket API(RFC3542)

Socket API Extensions for IPv6 Sockets Interface The de-facto standard Application Programming Interface(API) for TCP/IP applicationsdeveloped for Unix in the early 1980s, also beenimplemented on a wide variety of non-Unix systemsTCP/IP applications written using the sockets API have inthe past enjoyed a high degree of portabilityFor similar portability with IPv6 applications RFC3493 (Basic Socket Interface Extensions for IPv6)RFC3542 (Advanced Socket API for IPv6)

RFC3493Basic Socket Interface Extensions for IPv6 Source and binary compatibility Changes do not break existing programs Minimum changes to the API Simplify the task of conversion Interoperability with IPv6 and IPv4 hosts Applications do not need to know which type ofhost they are communicating with 64-bit allignment MT-Safe

Compoments of Basic APIExtentions Core socket functionsAddress data structuresName-to-address translation functionsAddress conversion functions

Core Socket Functions (1)int socket(int domain, int type, int protocol);int bind(int sockfd, struct sockaddr *myaddr,socklen t addrlen);int connect(int sockfd, const struct sockaddr *serv addr,socklen t addrlen);int accept(int sockfd, struct sockaddr *addr,socklen t *addrlen);int listen(int sockfd, int backlog);int getsockopt(int sockfd, int level, int optname,void *optval, socklen t *optlen);int setsockopt(int sockfd, int level, int optname,const void *optval, socklen t optlen);

Core Socket Functions (2) Protocol independent framework Protocol and/or address family numberPointer to the socket address structure (via opaquesockaddr{}) and its length protocol/address family number and protocolspecific socket address structure defined for eachprotocol No need to change this framework New address family: AF INET6 Usually, PF INET6 equals to AF INET6New socket options to support new functions

Address Structure(1) IPv6 address structurestruct in6 addr {uint8 t s6 addr[16];}; Trivial, no scope informationQuestion 1 Definition on your system What you should note

Address Structure(2)IPv6 socket address structure struct sockaddr in6 {sa family tsin6 family;in port tsin6 port;uint32 tsin6 flowinfo;struct in6 addr sin6 addr;uint32 tsin6 scope id;};/*/*/*/*/*AF INET6 */port number */flow information */IPv6 address */Scope Identifier */ Used in (most of) socket API AF INET6 IPv6 address family number In most systems, PF INET6 is defined as AF INET6IPv6 address alligned on 64-bit boundaryFlow information and spope information

Address Structure(3) Storage for all socket address structures#define SS MAXSIZE#define SS ALIGNSIZE128(sizeof (int64 t))/* maxumum size *//* desired alignment */#define SS PAD1SIZE( SS ALIGNSIZE - sizeof(sa family t))#define SS PAD2SIZE( SS MAXSIZE - (sizeof(sa family t) \SS PAD1SIZE SS ALIGNSIZE))struct sockaddr storage {sa family t ss family;charss pad1[ SS PAD1SIZE];int64 tss align;charss pad2[ SS PAD2SIZE];}; /* address family *//* force allignment */Storage for all socket address structures on the systemaligned on 64-bit boundary (w/ systems supporting IPv6)

Question 2: Address Structuresa)Look into the actual definitions of in6 addr{},sockaddr in6{} netinet/in.hb)Discuss what we should note

Question 3: Core Socket Functions Refer the following and make it support IPv6int s;struct sockaddr in sn;s socket(AF INET, SOCK STREAM, 0);/* setup sn */if (connect(s, (struct sockaddr*)sn, sizeof(sn)) 0)perror(“connect”);/* . */

Trivial Usage of Core Socket API IPv4:int s;struct sockaddr in sn;s socket(AF NET, SOCK STREAM, 0);/* setup sn */connect(s, (struct sockaddr*)sn, sizeof(sn));/* . */ IPv6:int s;struct sockaddr in6 sn;s socket(AF INET6, SOCK STREAM, 0);/* setup sn */connect(s, (struct sockaddr*)sn, sizeof(sn));/* . */

Compatibility with IPv4 Nodes ::ffff: IPv4-address Providing ability for IPv6 applications to interoperatewith IPv4 applications IPv4-mapped addressAll IPv4 addresses are mapped on IPv6 address spacee.g. 192.168.0.1 ::ffff:192.168.0.1Specify the destination, to connect() or sendto()Getting peer information via accept(), recvfrom(),getpeername()Do not need to open socket for each protocolNote: IPv4-mapped address is not always available.

IPv4-mapped Address Pros/Cons Pros Easy to convert IPv4 applications to IPv6Cons Complexity of kernelComplexity of access control People usually build access control using IPv4 addressNote: “Some” systems do not support this. OpenBSD, NetBSD (by default), FreeBSD 6.x (bydefault), Windows

Special Address Definitions IPv6 Wildcard Address(::) const struct in6 addr in6addr any; // assignmentIN6ADDR ANY INIT sin6.sin6 addr in6addr any;struct in6 addr in6 IN6ADDR ANY INIT;//initializationIPv6 Loopback Address(::1) const struct in6 addr in6addr loopback; sin6.sin6 addr in6addr loopback;//assignmentIN6ADDR LOOPBACK INIT struct in6 addr in6 IN6ADDR LOOPBACK INIT; //initialization

New Socket Options IPV6 UNICAST HOPS Controls the hop limit used in outgoing unicast IPv6 packetsIPV6 MULTICAST IF Set the interface to use for outgoing multicast packetsIPV6 MULTICAST HOP Set the hop limit to use for outgoing multicast packets Default: 1IPV6 MULTICAST LOOP Loopback a copy of the datagram if the host itself joins the destination group ofthe outgoing multicast packet. Default: 1IPV6 JOIN GROUP / IPV6 LEAVE GROUP Joint / Leave a multicast group on a specified local interface Note: New IGMPv3/MLDv2 Interface is also availableIPV6 V6ONLY Restricts AF INET6 sockets to IPv6 communication onlyDefault: 0 Note: on some systems, default is 1.

Requirements of Name-ConversionFunctions Protocol IndependentFlexibilityMT-Safety

Historical Name-vs-AddressTranslation Functions Name to addressstruct hostent *gethostbyname(const char *name); Address to namestruct hostent *gethostbyaddr(const char *addr,int len, int type); Host entry structurestruct hostent {char *h name;char **h aliases;charh addrtype;inth length;char **h addr list;}; /*/*/*/*/*official name */alias list */type of address: AF xxx */length of the address: 4 for IPv4 */list of addresses from name server */Issues The structure itself is af-independent, but gethostbyname(). Unflexible – no searching optionsNot MT-safe

Historical Name-vs-AddressTranslation Functions (2) Name to addressstruct hostent *getipnodebyname(const char *name, int af, int flags,int *error num); Address to namestruct hostent *getipnodebyaddr(const void *src, size t len, int af,int *error num);Pros Support both IPv6/IPv4 in similar semantics of gethostby{name,addr}() Searching optionsAI DEFAULT to the flags for standard queryNumeric address, IPv4-mapped addressMT-Safe Free memory be freehostent()Cons No scopes Uneasy to create socket Not widely deployed, deprecated now

Question 4 Convert obs-client.c and obs-server.c tosupport IPv6 Hint: Use AI DEFAULT for flags

Name-vs-Address Translation Functions(Protocol Independent) Name to addressint getaddrinfo(const char *nodename,const char *servname,const struct addrinfo *hints,struct addrinfo **res); Address to nameint getnameinfo(const struct sockaddr *sa,socklen t salen,char *host, size t hostlen,char *serv, size t servlen,int flags);

getaddrinfo()int getaddrinfo(const char *nodename, const char *servname,const struct addrinfo *hints,struct addrinfo **res);struct addrinfo {intai flags;/* flags */intai family;/* protocol family PF xxx */intai socktype; /* socket type SOCK xxx */intai protocol; /* protocol type; IPPROTO xxx in IP */socklen tai addrlen;/* length of socket address structure */char*ai canonname; /* canonical name of the node */struct sockaddr *ai addr;/* socket address structure */struct addrinfo *ai next;/* next address information in the list */}; Protocol independent Name-to-address translation functionSearch by node name, service name and searching optionsSocket address structure instead of raw address structureScope informationMT-Safe

Options of getaddrinfo() (1) ai flags AI PASSIVE: socket address returned from the functionwill be used for bind(). AI CANONNAME: Request canonical name of the node switch for nodename NULLResult stored in the first element in the listAI NUMERICHOST / AI NUMERICSERV: Assumenodename / servname as numeric address and do notlook up nodename / servnameAI ADDRCONFG: Search for addresses if local addressfor the corresponding protocol is available

Options of getaddrinfo() (2) Searching options NULL in nodename denotes loopback or wildcard do not search service if servname is NULL wildcard if AI PASSIVE, otherwise loopbacknumeric address allowed(e.g. “::1”)numeric service allowed(e.g. “80”)AF UNSPEC in ai family, 0 in ai socktype, ai protocolmeans caller does not care.

Result of getaddrinfo() (1) Return value 0 if succeeded Dynamically allocated result returned via res freeaddrinfo(): free resultOtherwise getaddrinfo-specific error code EAI FAMILY, EAI NONAME, EAI SERVICE etc.gai strerror(): human readable string for error codeResult comes with information required to createsocket and to connect (or to bind) Address family, socket type, protocol, and length of thesocket address structureYield differences among address families / protocols

Result of getaddrinfo() (2)

Usage of addrinfo{}

Example of getaddrinfo() for Clientsstruct addrinfo hints, *res, *ai;int s;memset(&hints, 0, sizeof(hints));hints.ai family PF UNSPEC;hints.ai socktype SOCK STREAM;hints.ai protocol IPPROTO TCP;if (gai getaddrinfo(name, service, &hints, &res)) {printf("getaddrinfo failed: %s\n", gai strerror(gai)); return -1;}for (ai res; ai ! NULL; ai ai- ai next) {s socket(res- ai family, res- ai socktype, res- ai protocol);if (s 0) continue;if (connect(s, ai- ai addr, ai- ai addrlen) 0) {close(s);s -1;continue;}break;}freeaddrinfo(res);return s;

Example of getaddrinfo() for Serversstruct addrinfo hints, *res, *ai;int s;memset(&hints, 0, sizeof(hints));hints.ai family PF UNSPEC;hints.ai socktype SOCK STREAM;hints.ai protocol IPPROTO TCP;hints.ai flags AI PASSIVE;gai getaddrinfo(name, service, &hints, &res);if (gai) {printf("getaddrinfo failed: %s\n", gai strerror(gai));return NULL;}

Example of getaddrinfo() for Servers(cont'ed)for (ai res; ai ! NULL; ai ai- ai next) {s socket(ai- ai family, ai- ai socktype,ai- ai protocol);if (s 0) continue;if (bind(s, ai- ai addr, ai- ai addrlen) 0) {close(s);s -1;continue;}break;}freeaddrinfo(res);

Note on Servers Semantics (or policy) of bind(2) is verydifferent aming systems AF INET6 and AF INET share portsAF INET6 and AF INET share ports unlessAF INET6 socket does not set IPV6 V6ONLYAF INET6 and AF INET share ports, butautomatically separatedThus, how to listen is different among systems

getnameinfo()int getnameinfo(const struct sockaddr *sa, socklen t salen,char *host, socklen t hostlen,char *serv, socklen t servlen,int flags);#define NI MAXHOST 1025#define NI MAXSERV32 Address-to-name translation functionExtract node name, service name from socket address structureand put in human readable formatNot an address structure but a socket address structure support scope architecture e.g. “ff02::1%link0”, “fec0::1%site0”MT-SafeNI MAXHOST, NI MAXSERV: size enough for host, serv