draft-ietf-tsvwg-sctpsocket-31.txt   draft-ietf-tsvwg-sctpsocket-32.txt 
Network Working Group R. Stewart Network Working Group R. Stewart
Internet-Draft Adara Networks Internet-Draft Adara Networks
Intended status: Informational M. Tuexen Intended status: Informational M. Tuexen
Expires: February 11, 2012 Muenster Univ. of Appl. Sciences Expires: April 13, 2012 Muenster Univ. of Appl. Sciences
K. Poon K. Poon
Oracle Corporation Oracle Corporation
P. Lei P. Lei
Cisco Systems, Inc. Cisco Systems, Inc.
V. Yasevich V. Yasevich
HP HP
August 10, 2011 October 11, 2011
Sockets API Extensions for Stream Control Transmission Protocol (SCTP) Sockets API Extensions for Stream Control Transmission Protocol (SCTP)
draft-ietf-tsvwg-sctpsocket-31.txt draft-ietf-tsvwg-sctpsocket-32.txt
Abstract Abstract
This document describes a mapping of the Stream Control Transmission This document describes a mapping of the Stream Control Transmission
Protocol (SCTP) into a sockets API. The benefits of this mapping Protocol (SCTP) into a sockets API. The benefits of this mapping
include compatibility for TCP applications, access to new SCTP include compatibility for TCP applications, access to new SCTP
features and a consolidated error and event notification scheme. features and a consolidated error and event notification scheme.
Status of this Memo Status of this Memo
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 11, 2012. This Internet-Draft will expire on April 13, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 13 skipping to change at page 3, line 13
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8 2. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 8
3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8 3. One-to-Many Style Interface . . . . . . . . . . . . . . . . . 8
3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8 3.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 8
3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 10 3.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 10
3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 10 3.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 10
3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 11 3.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 12
3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 12 3.1.4. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 12
3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 14 3.1.5. close() . . . . . . . . . . . . . . . . . . . . . . . 14
3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 15 3.1.6. connect() . . . . . . . . . . . . . . . . . . . . . . 15
3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 15 3.2. Non-blocking mode . . . . . . . . . . . . . . . . . . . . 16
3.3. Special considerations . . . . . . . . . . . . . . . . . 16 3.3. Special considerations . . . . . . . . . . . . . . . . . 17
4. One-to-One Style Interface . . . . . . . . . . . . . . . . . 18 4. One-to-One Style Interface . . . . . . . . . . . . . . . . . 18
4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 18 4.1. Basic Operation . . . . . . . . . . . . . . . . . . . . . 18
4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 19 4.1.1. socket() . . . . . . . . . . . . . . . . . . . . . . 19
4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 19 4.1.2. bind() . . . . . . . . . . . . . . . . . . . . . . . 20
4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 21 4.1.3. listen() . . . . . . . . . . . . . . . . . . . . . . 21
4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . 21 4.1.4. accept() . . . . . . . . . . . . . . . . . . . . . . 21
4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 22 4.1.5. connect() . . . . . . . . . . . . . . . . . . . . . . 22
4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 23 4.1.6. close() . . . . . . . . . . . . . . . . . . . . . . . 23
4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . 23 4.1.7. shutdown() . . . . . . . . . . . . . . . . . . . . . 23
4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 24 4.1.8. sendmsg() and recvmsg() . . . . . . . . . . . . . . . 24
4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 25 4.1.9. getpeername() . . . . . . . . . . . . . . . . . . . . 25
5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 25 5. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 25
5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 25 5.1. The msghdr and cmsghdr Structures . . . . . . . . . . . . 25
5.2. Ancillary Data Considerations and Semantics . . . . . . . 26 5.2. Ancillary Data Considerations and Semantics . . . . . . . 26
skipping to change at page 6, line 13 skipping to change at page 6, line 13
9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 92 9.6. sctp_freeladdrs() . . . . . . . . . . . . . . . . . . . . 92
9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 92 9.7. sctp_sendmsg() - DEPRECATED . . . . . . . . . . . . . . . 92
9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 93 9.8. sctp_recvmsg() - DEPRECATED . . . . . . . . . . . . . . . 93
9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 94 9.9. sctp_connectx() . . . . . . . . . . . . . . . . . . . . . 94
9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 95 9.10. sctp_send() - DEPRECATED . . . . . . . . . . . . . . . . 95
9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 96 9.11. sctp_sendx() - DEPRECATED . . . . . . . . . . . . . . . . 96
9.12. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 97 9.12. sctp_sendv() . . . . . . . . . . . . . . . . . . . . . . 97
9.13. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 100 9.13. sctp_recvv() . . . . . . . . . . . . . . . . . . . . . . 100
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 102
11. Security Considerations . . . . . . . . . . . . . . . . . . . 102 11. Security Considerations . . . . . . . . . . . . . . . . . . . 102
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 102 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 103
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 103 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 103
13.1. Normative References . . . . . . . . . . . . . . . . . . 103 13.1. Normative References . . . . . . . . . . . . . . . . . . 103
13.2. Informative References . . . . . . . . . . . . . . . . . 103 13.2. Informative References . . . . . . . . . . . . . . . . . 104
Appendix A. One-to-One Style Code Example . . . . . . . . . . . 104 Appendix A. One-to-One Style Code Example . . . . . . . . . . . 104
Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 106 Appendix B. One-to-Many Style Code Example . . . . . . . . . . . 107
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 112
1. Introduction 1. Introduction
The sockets API has provided a standard mapping of the Internet The sockets API has provided a standard mapping of the Internet
Protocol suite to many operating systems. Both TCP [RFC0793] and UDP Protocol suite to many operating systems. Both TCP [RFC0793] and UDP
[RFC0768] have benefited from this standard representation and access [RFC0768] have benefited from this standard representation and access
method across many diverse platforms. SCTP is a new protocol that method across many diverse platforms. SCTP is a new protocol that
provides many of the characteristics of TCP but also incorporates provides many of the characteristics of TCP but also incorporates
semantics more akin to UDP. This document defines a method to map semantics more akin to UDP. This document defines a method to map
skipping to change at page 8, line 13 skipping to change at page 8, line 13
mainly on the nature of applications. mainly on the nature of applications.
A mechanism is defined to extract a one-to-many style SCTP A mechanism is defined to extract a one-to-many style SCTP
association into a one-to-one style socket. association into a one-to-one style socket.
Some of the SCTP mechanisms cannot be adequately mapped to an Some of the SCTP mechanisms cannot be adequately mapped to an
existing socket interface. In some cases, it is more desirable to existing socket interface. In some cases, it is more desirable to
have a new interface instead of using existing socket calls. have a new interface instead of using existing socket calls.
Section 9 of this document describes these new interfaces. Section 9 of this document describes these new interfaces.
Please note that some elements of the SCTP socket API are declared as
deprecated. During the evolution of this document, elements of the
API were introduced, implemented and later on replaced by other
elements. These replaced elements are declared as deprecated since
they are still available in some implementations and the replacement
functions are not. This applies especially to older versions of
operating systems supporting SCTP. New SCTP socket implementations
must implement at least the non deprecated elements. Implementations
intending interoperability with older versions of the API should also
include the deprecated functions.
2. Data Types 2. Data Types
Whenever possible, data types from Draft 6.6 (March 1997) of POSIX Whenever possible, POSIX data types defined in [IEEE-1003.1-2008] are
1003.1g are used: uintN_t means an unsigned integer of exactly N bits used: uintN_t means an unsigned integer of exactly N bits (e.g.
(e.g. uint16_t). This document also assumes the argument data types uint16_t). This document also assumes the argument data types from
from 1003.1g when possible (e.g. the final argument to setsockopt() POSIX when possible (e.g. the final argument to setsockopt() is a
is a size_t value). Whenever buffer sizes are specified, the POSIX socklen_t value). Whenever buffer sizes are specified, the POSIX
1003.1 size_t data type is used. size_t data type is used.
3. One-to-Many Style Interface 3. One-to-Many Style Interface
In the one-to-many style interface there is a 1 to many relationship In the one-to-many style interface there is a 1 to many relationship
between sockets and associations. between sockets and associations.
3.1. Basic Operation 3.1. Basic Operation
A typical server in this style uses the following socket calls in A typical server in this style uses the following socket calls in
sequence to prepare an endpoint for servicing requests: sequence to prepare an endpoint for servicing requests:
skipping to change at page 70, line 19 skipping to change at page 70, line 19
the given value is used as the path MTU. If SPP_PMTUD_ENABLE is the given value is used as the path MTU. If SPP_PMTUD_ENABLE is
set in the spp_flags, the spp_pathmtu field is ignored. set in the spp_flags, the spp_pathmtu field is ignored.
spp_ipv6_flowlabel: This field is used in conjunction with the spp_ipv6_flowlabel: This field is used in conjunction with the
SPP_IPV6_FLOWLABEL flag and contains the IPv6 flowlabel. The 20 SPP_IPV6_FLOWLABEL flag and contains the IPv6 flowlabel. The 20
least significant bits are used for the flowlabel. This setting least significant bits are used for the flowlabel. This setting
has precedence over any IPv6 layer setting. has precedence over any IPv6 layer setting.
spp_dscp: This field is used in conjunction with the SPP_DSCP flag spp_dscp: This field is used in conjunction with the SPP_DSCP flag
and contains the Differentiated Services Code Point (DSCP). The 6 and contains the Differentiated Services Code Point (DSCP). The 6
least significant bits are used for the DSCP. This setting has most significant bits are used for the DSCP. This setting has
precedence over any IPv4 or IPv6 layer setting. precedence over any IPv4 or IPv6 layer setting.
spp_flags: These flags are used to control various features on an spp_flags: These flags are used to control various features on an
association. The flag field is a bit mask which may contain zero association. The flag field is a bit mask which may contain zero
or more of the following options: or more of the following options:
SPP_HB_ENABLE: Enable heartbeats on the specified address. SPP_HB_ENABLE: Enable heartbeats on the specified address.
SPP_HB_DISABLE: Disable heartbeats on the specified address. SPP_HB_DISABLE: Disable heartbeats on the specified address.
Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually Note that SPP_HB_ENABLE and SPP_HB_DISABLE are mutually
skipping to change at page 102, line 44 skipping to change at page 102, line 44
If an unprivileged user inherits a one-to-many style socket with open If an unprivileged user inherits a one-to-many style socket with open
associations on a privileged port, it may be permitted to accept new associations on a privileged port, it may be permitted to accept new
associations, but it should not be permitted to open new associations, but it should not be permitted to open new
associations. This could be relevant for the r* family of protocols. associations. This could be relevant for the r* family of protocols.
Applications using the one-to-many style sockets and using the Applications using the one-to-many style sockets and using the
interleave level if 0 are subject to denial of service attacks as interleave level if 0 are subject to denial of service attacks as
described in Section 8.1.20. described in Section 8.1.20.
Applications needing transport layer security can use DTLS/SCTP as
specified in [RFC6083]. This can be implemented using the socket API
described in this document.
12. Acknowledgments 12. Acknowledgments
Special acknowledgment is given to Ken Fujita, Jonathan Woods, Special acknowledgment is given to Ken Fujita, Jonathan Woods,
Qiaobing Xie, and La Monte Yarroll, who helped extensively in the Qiaobing Xie, and La Monte Yarroll, who helped extensively in the
early formation of this document. early formation of this document.
The authors also wish to thank Kavitha Baratakke, Mike Bartlett, The authors also wish to thank Kavitha Baratakke, Mike Bartlett,
Martin Becke, Jon Berger, Mark Butler, Thomas Dreibholz, Scott Martin Becke, Jon Berger, Mark Butler, Thomas Dreibholz, Andreas
Kimble, Renee Revis, Andreas Fink, Jonathan Leighton, Irene Fink, Scott Kimble, Jonathan Leighton, Renee Revis, Irene Ruengeler,
Ruengeler, Dan Wing, and many others on the TSVWG mailing list for Dan Wing, and many others on the TSVWG mailing list for contributing
contributing valuable comments. valuable comments.
A special thanks to Phillip Conrad, for his suggested text, quick and A special thanks to Phillip Conrad, for his suggested text, quick and
constructive insights, and most of all his persistent fighting to constructive insights, and most of all his persistent fighting to
keep the interface to SCTP usable for the application programmer. keep the interface to SCTP usable for the application programmer.
13. References 13. References
13.1. Normative References 13.1. Normative References
[IEEE-1003.1-2008]
Institute of Electrical and Electronics Engineers,
"Information Technology - Portable Operating System
Interface (POSIX)", IEEE Standard 1003.1, 2008.
[RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
Stevens, "Basic Socket Interface Extensions for IPv6", Stevens, "Basic Socket Interface Extensions for IPv6",
RFC 3493, February 2003. RFC 3493, February 2003.
[RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei,
"Advanced Sockets Application Program Interface (API) for "Advanced Sockets Application Program Interface (API) for
IPv6", RFC 3542, May 2003. IPv6", RFC 3542, May 2003.
[RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P. [RFC3758] Stewart, R., Ramalho, M., Xie, Q., Tuexen, M., and P.
Conrad, "Stream Control Transmission Protocol (SCTP) Conrad, "Stream Control Transmission Protocol (SCTP)
skipping to change at page 104, line 6 skipping to change at page 104, line 17
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, [RFC0793] Postel, J., "Transmission Control Protocol", STD 7,
RFC 793, September 1981. RFC 793, September 1981.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
August 1980. August 1980.
[RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions [RFC1644] Braden, B., "T/TCP -- TCP Extensions for Transactions
Functional Specification", RFC 1644, July 1994. Functional Specification", RFC 1644, July 1994.
[RFC6083] Tuexen, M., Seggelmann, R., and E. Rescorla, "Datagram
Transport Layer Security (DTLS) for Stream Control
Transmission Protocol (SCTP)", RFC 6083, January 2011.
Appendix A. One-to-One Style Code Example Appendix A. One-to-One Style Code Example
The following code is an implementation of a simple client which The following code is an implementation of a simple client which
sends a number of messages marked for unordered delivery to an echo sends a number of messages marked for unordered delivery to an echo
server making use of all outgoing streams. The example shows how to server making use of all outgoing streams. The example shows how to
use some features of one-to-one style IPv4 SCTP sockets, including: use some features of one-to-one style IPv4 SCTP sockets, including:
o Creating and connecting an SCTP socket. o Creating and connecting an SCTP socket.
o Requesting to negotiate a number of outgoing streams. o Requesting to negotiate a number of outgoing streams.
o Determining the negotiated number of outgoing streams. o Determining the negotiated number of outgoing streams.
o Setting an adaptation layer indication. o Setting an adaptation layer indication.
o Sending messages with a given payload protocol identifier on a o Sending messages with a given payload protocol identifier on a
particular stream using sctp_sendv(). particular stream using sctp_sendv().
/*
Copyright (c) 2011 IETF Trust and the persons identified
as authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with
or without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents (http://trustee.ietf.org/license-info).
*/
#include <sys/types.h> #include <sys/types.h>
#include <sys/socket.h> #include <sys/socket.h>
#include <netinet/in.h> #include <netinet/in.h>
#include <netinet/sctp.h> #include <netinet/sctp.h>
#include <arpa/inet.h> #include <arpa/inet.h>
#include <string.h> #include <string.h>
#include <stdio.h> #include <stdio.h>
#include <unistd.h> #include <unistd.h>
#include <stdlib.h> #include <stdlib.h>
skipping to change at page 106, line 48 skipping to change at page 107, line 29
o Handling notifications. o Handling notifications.
o Configuring the auto close timer. o Configuring the auto close timer.
o Using sctp_recvv() to receive messages. o Using sctp_recvv() to receive messages.
Please note that this server can be used in combination with the Please note that this server can be used in combination with the
client described in Appendix A. client described in Appendix A.
/*
Copyright (c) 2011 IETF Trust and the persons identified
as authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with
or without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents (http://trustee.ietf.org/license-info).
*/
#include <sys/types.h> #include <sys/types.h>
#include <sys/socket.h> #include <sys/socket.h>
#include <netinet/in.h> #include <netinet/in.h>
#include <netinet/sctp.h> #include <netinet/sctp.h>
#include <arpa/inet.h> #include <arpa/inet.h>
#include <string.h> #include <string.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <unistd.h> #include <unistd.h>
#define BUFFER_SIZE (1<<16) #define BUFFER_SIZE (1<<16)
#define PORT 9 #define PORT 9
#define ADDR "0.0.0.0" #define ADDR "0.0.0.0"
#define TIMEOUT 5 #define TIMEOUT 5
static void static void
print_notification(void *buf) print_notification(void *buf)
{ {
struct sctp_assoc_change *sac; struct sctp_assoc_change *sac;
struct sctp_paddr_change *spc; struct sctp_paddr_change *spc;
 End of changes. 20 change blocks. 
23 lines changed or deleted 72 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/