Internet DRAFT - draft-ietf-sip-bsd-api
draft-ietf-sip-bsd-api
Internet Engineering Task Force Robert E. Gilligan
INTERNET-DRAFT Sun Microsystems, Inc.
December 20, 1993
SIPP Program Interfaces for BSD Systems
Abstract
In order to implement the Simple Internet Protocol (SIPP) [1] in an
operating system based on 4.x BSD, changes must be made to some of the
application program interfaces (APIs). TCP/IP applications written for
BSD-based operating systems have in the past enjoyed a high degree of
portability because most of the systems derived from BSD provide the
same API, known informally as "the socket interface". We would like the
same portability to be possible with SIPP applications. This memo
presents a set of changes to the BSD socket API to support SIPP. The
changes include a new data structure to carry 64-bit SIPP addresses, a
new name to address translation library function, new address conversion
functions, and some new setsockopt() options. The changes are designed
to be minimal and to provide source and binary compatibility for
existing applications.
Status of this Memo
This document is an Internet Draft. 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.
This Internet Draft expires on June 20, 1994. Internet Drafts may be
updated, replaced, or obsoleted by other documents at any time. It is
not appropriate to use Internet Drafts as reference material or to cite
them other than as a "working draft" or "work in progress."
Please check the I-D abstract listing contained in each Internet Draft
directory to learn the current status of this or any other Internet
Draft.
Distribution of this memo is unlimited.
draft-ietf-sip-bsd-api-01.txt [Page 1]
INTERNET-DRAFT SIPP API Specification December 1993
1. Introduction.
The most visible feature of SIPP is its extension of the length of an IP
address from 32 bits to 64 bits. The APIs that the BSD system provides
make the size of an IP address quite visible to an application.
Virtually all TCP/IP applications for BSD-based systems have knowledge
of the size of an IP address. Generally speaking, those parts of the
API that make addresses visible need to be changed. This paper presents
a first attempt to define the API changes needed to support SIPP in BSD
systems. These APIs are expected to evolve as we gain more
implementation experience.
2. Design considerations
There are two important considerations in designing changes to these
well-worn APIs. First, the modified API should provide both source and
binary compatibility for programs written to the existing API. That is,
exiting program binaries should continue to operate when run on or
re-compiled and run a system supporting the new APIs. The API changes
for SIPP should not cause existing program binaries to break, nor should
they cause programs written to the existing APIs to fail to compile or
break when re-compiled.
Second, the changes should be as minimal as possible and should make it
as easy as possible to change an existing application to be SIPP
knowledgeable.
2.1 What needs to be changed
Since their address arguments are all opaque pointers, none of the
socket system calls need to changed directly.
The in_addr structure is 4-bytes long and can not be changed without
breaking applications. The sockaddr_in structure, which is passed into
and returned by the socket functions, contains 8 bytes of unused space
which can be used to hold a SIPP address without incompatibility.
The gethostbyaddr() function includes an address type argument, so this
function does not need to be changed. However, the gethostbyname()
function does not include a type argument, and most applications that
use it assume that the address array that it returns consists of 4-byte
IP addresses. Thus a new function similar to gethostbyname(), but
knowledgeable of SIPP addresses, must be defined.
Finally, a new interface is needed in order to set the SIPP flow ID. The
most straightforward way to do this is to define new setsockopt()
options at the IPPROTO_IP level.
draft-ietf-sip-bsd-api-01.txt [Page 2]
INTERNET-DRAFT SIPP API Specification December 1993
2.2 Implementation experience
The Sun IPAE/SIPP prototype exposed some of the issues in designing a
compatible interface. The initial prototype passed SIPP addresses
between the kernel and applications using the sockaddr_in structure with
the sin_family field set to AF_INET. The 8-byte SIPP address occupied
the 4 bytes of the "sin_addr" field plus the first 4 bytes of the
"sin_zero" field. The kernel distinguished between 8-byte SIPP
addresses and 4-byte IPv4 addresses passed in by checking the sin_zero
field. If sin_zero was zero, the kernel would assume that the sin_addr
field held a 4-byte IPv4 address. If sin_zero was non-zero, it would
assume that an 8-byte SIPP address was being passed in.
While this technique works for most existing applications, we discovered
that some applications do not set the sin_zero field of the sockaddr_in
structure to zero. Thus we concluded that it would be unworkable in the
general case and that some specific indication was needed to distinguish
a 8-byte SIPP address from a 4-byte IPv4 address in a sockaddr_in
structure.
Another useful lesson learned from the initial Sun implementation was
that the form of addresses (IPv4 or SIPP) passed in and out of the
socket functions did not always need to constrain the form of packets
(IPv4, IPAE or SIPP) transmitted or received. For example, a
pre-existing TCP server application that knows nothing of SIPP could
accept a connection that was transmitting and receiving TCP segments
encapsulated within SIPP packets. Because SIPP and IPv4 addresses are
mappable, the accept() system call can return to the application the
client's address as a 4-byte IPv4 address.
What does matter, however, is that pre-existing applications never be
given address structures that they don't understand. We found that the
most convenient way for the kernel to decide what form of address to
pass back to applications was to look at the form of addresses passed
in. That is, if an application passes in IPv4 form addresses, then it
should always be given IPv4 form addresses. If the application passes
in SIPP form addresses, the kernel can return SIPP form addresses to the
application.
3. Interface specification
3.1. New address family
We define a address family macro in <sys/socket.h>:
#define AF_SIPP 24 /* Simple Internet Protocol */
The AF_SIPP definition is used only to distinguish between the original
AF_INET form of the sockaddr_in structure, and a new form that we have
draft-ietf-sip-bsd-api-01.txt [Page 3]
INTERNET-DRAFT SIPP API Specification December 1993
defined. Thus there is no corresponding PF_SIPP definition.
3.2 Sockaddr_in structure
The sockaddr_in structure is used in the socket system calls to pass
addresses between the application and the kernel. Keeping the
sockaddr_in structure the same size is necessary to provide binary
compatibility for existing IPv4 applications. We can avoid changing the
size of the sockaddr_in structure by appropriating the currently unused
sin_zero field to hold the 64 bit SIPP address.
We can add a structure element for the SIPP address without changing the
original structure definition by just adding two new macros. The
resulting definition in the <netinet/in.h> header file is:
struct sockaddr_in {
short sin_family;
u_short sin_port;
in_addr sin_addr;
char sin_zero[8];
}
#define sipp_addr sin_zero
#define sipp_zero sin_addr
The value of the sin_family field determines whether the sockaddr_in
structure is holding a 32 bit IPv4 address or a 64 bit SIPP address.
The sin_family field may have one of two values: AF_INET or AF_SIPP. If
sin_family is AF_SIPP, then the sipp_addr field contains a 8-byte SIPP
address and the sipp_zero field must be set to zero. If the sin_family
field is AF_INET, then the sockaddr_in keeps its original semantics: The
sin_addr field contains a 4-byte IPv4 address and the sin_zero field
must be set to zero.
We refer to the the two variants as the "AF_INET form" or the "AF_SIPP
form" of the sockaddr_in structure.
The two structure layouts can be understood better when viewed
graphically. This is the AF_INET form of the sockaddr_in structure:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AF_INET | port number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| IPv4 address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ all zero bits +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
draft-ietf-sip-bsd-api-01.txt [Page 4]
INTERNET-DRAFT SIPP API Specification December 1993
And this is the layout of the AF_SIPP form of the sockaddr_in structure:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| AF_SIPP | port number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| all zero bits |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
+ SIPP address +
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
We considered an alternative form that overlays the high-order four
bytes of the SIPP address with sin_addr. The form presented has a few
advantages:
- The SIPP address is aligned on a 64-bit boundary within the
structure.
- The kernel can do some consistency checking on AF_SIPP addresses
passed in. Because the sipp_zero field, which overlays the
sin_addr field, must always zero, the kernel can detect cases
where the application incorrectly treats an AF_SIPP form
sockaddr_in as an AF_INET form.
- The structure declaration is simpler than the alternative.
3.3 The socket functions
Even though we define a new address family for SIPP, there is no change
to the way that applications get sockets. There is not a new "type" of
socket for SIPP. SIPP applications continue use AF_INET in the "domain"
argument (the first argument) of the socket() call. For example, to get
a TCP socket, a SIPP application would call:
s = socket (AF_INET, SOCK_STREAM, 0);
and to get a UDP socket, a SIPP application would call:
s = socket (AF_INET, SOCK_DGRAM, 0);
Once the application has a socket, it may use either the AF_SIPP or the
AF_INET form of the sockaddr_in structure in the system calls that pass
addresses in to the kernel.
The form of sockaddr_in structure returned to the application by the
socket functions is determined by the form of addresses passed in most
recently. For example, if an application uses an AF_SIPP form address
in its bind() call, then a subsequent accept() call would return a
sockaddr_in structure in the AF_SIPP form. If the application calls no
socket function that passes in an address before calling one that
draft-ietf-sip-bsd-api-01.txt [Page 5]
INTERNET-DRAFT SIPP API Specification December 1993
returns an address, then that function returns an AF_INET form address.
The socket functions to which an application passes in an address
argument are:
bind()
connect()
sendto()
The socket functions that return an address to the application are:
accept()
recvfrom()
getpeername()
getsockname()
3.4 Sockets passed across exec()
Having two forms of sockaddr_in address that may be used interchageably
with all AF_INET sockets means that existing applications are supported
straightforwardly, and that new applications simply need to be written
to use the AF_SIPP form of sockaddr_in. However, Unix allows open
sockets to be passed across an exec() call. Thus a newly written
application may find itself holding an open socket that was passed to it
via exec(), but not knowing what form of addresses that will be
returned. Similarly, a newly written SIPP knowledgeable application may
wish to use AF_SIPP form addresses in its bind() or connect() calls, and
then pass the socket to a pre-existing application. To remedy these
problems, we defined a new setsockopt() option that allows an
application to explicitly set the form of sockaddr_in addresses returned
by the socket functions. A SIPP knowledgeable application that is
passed an open socket from an unknown process may do use the
SIPP_ADDRFORM setsockopt() option to "convert" the socket to return
AF_SIPP form addresses. Similarly, a SIPP knowledgeable application
that is about to pass an open socket to a program that may not be SIPP
knowledgeable may "downgrade" the socket to return AF_INET form
addresses using the same setsockopt option.
The macro definition for this new option in <netinet/in.h> is:
#define SIPP_ADDRFORM 0x16 /* get/set form of returned addrs */
The SIPP_ADDRFORM option is at the IPPROTO_IP level. The only valid
option values are AF_SIPP and AF_INET. For example, to convert a socket
to return AF_INET form addresses, a program would call:
int addrform = AF_SIPP;
if (setsockopt(s, IPPROTO_IP, SIPP_ADDRFORM, (char *) &addrform,
sizeof(addrform)) == -1)
draft-ietf-sip-bsd-api-01.txt [Page 6]
INTERNET-DRAFT SIPP API Specification December 1993
perror("setsockopt SIPP_ADDRFORM");
An application may use SIPP_ADDRFORM in the getsockopt() function to
learn the form of addresses that will be returned by an open socket.
3.5 IPv4 addresses in AF_SIPP form sockaddr_in structures
An application may need to pass 32 bit IPv4 address in a sockaddr_in
structure, but want to set the sin_family field to AF_SIPP in order to
set the form of addresses to be returned. To allow for this, we have
defined a convention for storing 32 bit IPv4 addresses in 64 bit SIPP
addresses. The 32-bit IPv4 address is stored in the low-order 32 bits
of the SIPP address and the high-order 32 bits (i.e. the prefix part)
are set to zero. For example, the following structure:
struct sockaddr_in sin1;
sin1.sin_family = AF_SIPP;
sin1.sipp_zero = 0;
*((long *) sin1.sipp_addr) = 0;
*((long *) &sin1.sipp_addr[4]) = inet_addr("192.9.9.1");
And this structure:
struct sockaddr_in sin2;
sin2.sin_family = AF_INET;
sin2.sin_addr.s_addr = inet_addr("192.9.9.1");
bzero(sin2.sin_zero, sizeof(sin_zero);
are alternative ways to represent the same IPv4 address.
All of the socket functions that accept sockaddr_in addresses passed in
as arguments accept IPv4 addresses in the AF_SIPP form.
3.6 Flow IDs
The SIPP header has a 28 bit field reserved to hold a "flow ID". The
usage of this field has not yet been specified. But in order to allow
application programmers to experiment with SIPP flows, we have defined a
setsockopt() option that can be used to set the value to be assigned to
the flow ID field of transmitted SIPP packets. So far, we have not
defined any interface for an application to learn the flow ID set in
received SIPP packets.
The macro definition for this new option in <netinet/in.h> is:
#define SIPP_FLOWID 0x15 /* SIPP flow identifier */
draft-ietf-sip-bsd-api-01.txt [Page 7]
INTERNET-DRAFT SIPP API Specification December 1993
The SIPP_FLOWID option is at the IPPROTO_IP level. An example of how an
application might use this option is:
int flowid = 0x0f3c91ab; /* made up for this example */
if (setsockopt(s, IPPROTO_IP, SIPP_FLOWID, (char *) &flowid,
sizeof(flowid)) == -1)
perror("setsockopt SIPP_ADDRFORM");
The SIPP_FLOWID option can also be used with the getsockopt() option to
retrieve the flow ID value given in the last setsockopt() call.
Since the definition of SIPP flows may change as the protocol develops,
this option may also change in the future. Thus application developers
should consider this option "experimental."
3.7 Name-to-address translation functions
We have defined a new function call with the form:
struct hostent *hostname2addr(const char *name, int af,
char *buf, int buflen);
This interface looks the given host name up in the naming service and
returns a list of addresses. The name argument is the name of the host
to look up. The af argument specifies what form of address -- 4-byte
IPv4 or 8-byte SIPP address -- to return to the caller in the
h_addr_list field of the hostent structure. The buf argument points to
a buffer that the function can use to store the hostent structure that
is returned. The buflen argument is the size of the buffer. If buf is
a null pointer, the function uses its own static buffer.
If the af argument is AF_INET, hostname2addr() behaves like
gethostbyname(). That is, it returns a hostent structure which includes
an array of 4-byte IPv4 addresses. If AA (SIPP address) records are
found, then the low-order 4 bytes of each SIPP address are returned. If
only A records are found, then the associated 4-byte IP address is
returned.
If the type argument is AF_SIPP, then the h_addr_list field of the
hostent structure contains an array of 8-byte SIPP addresses. If AA
records are found, then the full SIPP address of each record is
returned. If only A records are found, then each 8-byte address
returned holds the IPv4 address in the low-order 4 bytes and the
high-order 4 bytes are set to zero. (i.e. it uses the convention for
storing IPv4 addresses in SIPP addresses defined above).
There was some discussion on the SIPP mailing list of some other ways to
cast this function. This proposal allows the application to be simple.
Since it passes in the address family, the application knows the size of
draft-ietf-sip-bsd-api-01.txt [Page 8]
INTERNET-DRAFT SIPP API Specification December 1993
the returned addresses and can unconditionally bcopy() them into
sockaddr_in structures. Also, the semantics of the hostname2addr() when
af is AF_INET lets us implement the existing gethostbyname() function in
terms of the new function.
The gethostbyaddr() function remains unchanged:
struct hostent *gethostbyaddr(const char *addr, int len, int af);
If the af argument is AF_INET, then len must be 4 and addr points to a
4-byte IPv4 address. If af is AF_SIPP, then len must be 8 and addr
points to an 8-byte SIPP address.
3.8 Address input/output functions
BSD Unix provides two functions -- inet_addr() and inet_ntoa() -- to
convert IPv4 address between binary and printable form. SIPP
applications need similar functions. We have defined the following two
functions to convert SIPP and IPv4 addresses:
int ascii2addr(long af, char *cp, char *ap);
and
char *addr2ascii(long af, char *ap, char *buf, int buflen)
The first function is used to transform an ascii string into an address
data structure. The af argument specifies that address family of the
address. Currently AF_INET and AF_SIPP are supported. The cp argument
points to the ascii string being passed in. The ap argument points to
the 4-byte or 8-byte buffer that the address will be converted into.
If the af argument is AF_INET, the function accepts a string in the
standard IPv4 dotted decimal form:
ddd.ddd.ddd.ddd
Where ddd is a one to three digit decimal number between 0 and 255.
If the af argument is AF_SIPP, then the function accepts a string in the
standard IPv4 dotted decimal form given above, or a string in one of the
two standard SIPP printing forms:
xxxx:xxxx:ddd.ddd.ddd.ddd
or
xxxx:xxxx:xxxx:xxxx
where xxxx is a 1 to 4 digit hex value and ddd is a 1 to 3 digit decimal
number between 0 and 255. If the string is in the IPv4 dotted decimal
draft-ietf-sip-bsd-api-01.txt [Page 9]
INTERNET-DRAFT SIPP API Specification December 1993
form, the high order 4 bytes of the address buffer pointed to by ap are
set to zero and the low-order 4 bytes are set to the IPv4 address.
Having the AF_SIPP variant of the ascii2addr() function accept either
IPv4 addresses or SIPP addresses allows an application to easily accept
either form of address from the user.
The second function transforms an address buffer into a printable
string. The af argument specifies the form of the address. This can be
AF_INET or AF_SIPP. The ap argument points to a buffer holding a 4-byte
IPv4 address or an 8-byte SIPP address. The buf argument points to a
buffer that the function can convert into, and the buflen argument gives
the size of this buffer. If the buf argument is zero, then the function
will convert the address unto a private static buffer of its own. In
either case, the function returns a pointer to the buffer that the
address has been converted into.
The ascii2addr() function returns 0 if the conversion succeeded, and -1
if it failed. The function does not modify the storage pointed to by ap
if the conversion fails. The addr2ascii() function returns a pointer to
the buffer if the conversion succeeded, and -1 if the conversion failed.
These two functions are derived from suggestions by Craig Partridge on
the SIPP mailing list. There was some discussion about whether the
buffer that addr2ascii() converts into should be static within the
function() or passed in by the application. In the interface presented
here, we try to provide the best of both worlds.
4. Open Issues
The API changes described here are likely to change as we get experience
writing SIPP applications. There are also some issues left unresolved.
Some of the things we need to think about are:
- There is a type defined (in_addr) to represent a 32-bit IPv4
address. Should we define a structure to hold the 64-bit SIPP
address? There was some discussion of this on the SIPP mailing
list with opinions on both sides.
- The format of the "/etc/hosts" file currently supports only IPv4
addresses. Should we extend the format of the existing file to
handle SIPP addresses? Or should we invent a file with a new
name for storing SIPP host addresses? Andrew Cherenson suggests
a clever, but ugly, hack to re-use the same file and allow old
and new versions of gethostb* to co-exist: precede SIPP lines
with "#SIPP", which acts as comment for old versions.
- How do datagram applications participate in path MTU discovery?
- What about the SIOC* ioctl() commands that get and set interface
parameters and manipulate the IP routing table?
draft-ietf-sip-bsd-api-01.txt [Page 10]
INTERNET-DRAFT SIPP API Specification December 1993
- Posix is changing and standardizing the socket interface.
Should we track the posix changes? In particular, 4.3-Reno has
split the 16-bit address family field of the sockaddr struct
into two 8-bit fields: a length field and an address family
field. Should we adopt this here?
- This spec has concentrated on the BSD socket interface. What
about the System V Transport Library Interface (TLI)? Does
anyone really care about TLI?
- The BSD "net-2" release includes setsockopt options to set the
IP TTL. Should we specify that this option sets the SIPP hop
limit, or is this just obvious?
5. Security Considerations
Security issues are not discussed in this document.
6. Acknowledgements
Thanks to all who provided feedback to the first revision of this
document, including Christian Huitema, Craig Partridge, Steve Deering,
Andrew Cherenson, Charles Lynn, Ran Atkinson, Erik Nordmark, Glenn
Trewitt, Fred Baker, Robert Elz, and Dean D. Throop.
7. References
[1] Deering, S., "Simple Internet Protocol (SIP) Specification",
Internet Draft November 1992
8. Authors' Address
Robert E. Gilligan
Sun Microsystems, Inc.
2550 Garcia Avenue
Mailstop UMTV05-44
Mountain View, California 94043-1100
415-336-1012
bob.gilligan@eng.sun.com
draft-ietf-sip-bsd-api-01.txt [Page 11]
