sctp

README

Pion SCTP

A Go implementation of SCTP

Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Slack.

Follow the Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible

License

MIT License - see LICENSE for full text

Documentation

Overview

Package sctp implements the SCTP spec

Index

• Constants
• Variables
• func TryMarshalUnmarshal(msg []byte) int
• type Association
  • func Client(config Config) (*Association, error)
  • func Server(config Config) (*Association, error)
  • func (a *Association) Abort(reason string)
  • func (a *Association) AcceptStream() (*Stream, error)
  • func (a *Association) BytesReceived() uint64
  • func (a *Association) BytesSent() uint64
  • func (a *Association) CWND() uint32
  • func (a *Association) Close() error
  • func (a *Association) MTU() uint32
  • func (a *Association) MaxMessageSize() uint32
  • func (a *Association) OpenStream(streamIdentifier uint16, defaultPayloadType PayloadProtocolIdentifier) (*Stream, error)
  • func (a *Association) RWND() uint32
  • func (a *Association) SRTT() float64
  • func (a *Association) SetMaxMessageSize(maxMsgSize uint32)
  • func (a *Association) Shutdown(ctx context.Context) error
• type Config
• type PayloadProtocolIdentifier
  • func (p PayloadProtocolIdentifier) String() string
• type Stream
  • func (s *Stream) BufferedAmount() uint64
  • func (s *Stream) BufferedAmountLowThreshold() uint64
  • func (s *Stream) Close() error
  • func (s *Stream) OnBufferedAmountLow(f func())
  • func (s *Stream) Read(p []byte) (int, error)
  • func (s *Stream) ReadSCTP(p []byte) (int, PayloadProtocolIdentifier, error)
  • func (s *Stream) SetBufferedAmountLowThreshold(th uint64)
  • func (s *Stream) SetDefaultPayloadType(defaultPayloadType PayloadProtocolIdentifier)
  • func (s *Stream) SetReadDeadline(deadline time.Time) error
  • func (s *Stream) SetReliabilityParams(unordered bool, relType byte, relVal uint32)
  • func (s *Stream) State() StreamState
  • func (s *Stream) StreamIdentifier() uint16
  • func (s *Stream) Write(p []byte) (n int, err error)
  • func (s *Stream) WriteSCTP(p []byte, ppi PayloadProtocolIdentifier) (int, error)
• type StreamState
  • func (ss StreamState) String() string

Constants

const (
	// ReliabilityTypeReliable is used for reliable transmission
	ReliabilityTypeReliable byte = 0
	// ReliabilityTypeRexmit is used for partial reliability by retransmission count
	ReliabilityTypeRexmit byte = 1
	// ReliabilityTypeTimed is used for partial reliability by retransmission duration
	ReliabilityTypeTimed byte = 2
)

Variables

var (
	ErrChunk                         = errors.New("abort chunk, with following errors")
	ErrShutdownNonEstablished        = errors.New("shutdown called in non-established state")
	ErrAssociationClosedBeforeConn   = errors.New("association closed before connecting")
	ErrAssociationClosed             = errors.New("association closed")
	ErrSilentlyDiscard               = errors.New("silently discard")
	ErrInitNotStoredToSend           = errors.New("the init not stored to send")
	ErrCookieEchoNotStoredToSend     = errors.New("cookieEcho not stored to send")
	ErrSCTPPacketSourcePortZero      = errors.New("sctp packet must not have a source port of 0")
	ErrSCTPPacketDestinationPortZero = errors.New("sctp packet must not have a destination port of 0")
	ErrInitChunkBundled              = errors.New("init chunk must not be bundled with any other chunk")
	ErrInitChunkVerifyTagNotZero     = errors.New("init chunk expects a verification tag of 0 on the packet when out-of-the-blue")
	ErrHandleInitState               = errors.New("todo: handle Init when in state")
	ErrInitAckNoCookie               = errors.New("no cookie in InitAck")
	ErrInflightQueueTSNPop           = errors.New("unable to be popped from inflight queue TSN")
	ErrTSNRequestNotExist            = errors.New("requested non-existent TSN")
	ErrResetPacketInStateNotExist    = errors.New("sending reset packet in non-established state")
	ErrParamterType                  = errors.New("unexpected parameter type")
	ErrPayloadDataStateNotExist      = errors.New("sending payload data in non-established state")
	ErrChunkTypeUnhandled            = errors.New("unhandled chunk type")
	ErrHandshakeInitAck              = errors.New("handshake failed (INIT ACK)")
	ErrHandshakeCookieEcho           = errors.New("handshake failed (COOKIE ECHO)")
	ErrTooManyReconfigRequests       = errors.New("too many outstanding reconfig requests")
)

Association errors

var (
	ErrChunkTypeNotAbort     = errors.New("ChunkType is not of type ABORT")
	ErrBuildAbortChunkFailed = errors.New("failed build Abort Chunk")
)

Abort chunk errors

var (
	ErrChunkTypeNotCtError   = errors.New("ChunkType is not of type ctError")
	ErrBuildErrorChunkFailed = errors.New("failed build Error Chunk")
)

Error chunk errors

var (
	ErrMarshalStreamFailed = errors.New("failed to marshal stream")
	ErrChunkTooShort       = errors.New("chunk too short")
)

Forward TSN chunk errors

var (
	ErrChunkTypeNotHeartbeat      = errors.New("ChunkType is not of type HEARTBEAT")
	ErrHeartbeatNotLongEnoughInfo = errors.New("heartbeat is not long enough to contain Heartbeat Info")
	ErrParseParamTypeFailed       = errors.New("failed to parse param type")
	ErrHeartbeatParam             = errors.New("heartbeat should only have HEARTBEAT param")
	ErrHeartbeatChunkUnmarshal    = errors.New("failed unmarshalling param in Heartbeat Chunk")
)

Heartbeat chunk errors

var (
	ErrUnimplemented                = errors.New("unimplemented")
	ErrHeartbeatAckParams           = errors.New("heartbeat Ack must have one param")
	ErrHeartbeatAckNotHeartbeatInfo = errors.New("heartbeat Ack must have one param, and it should be a HeartbeatInfo")
	ErrHeartbeatAckMarshalParam     = errors.New("unable to marshal parameter for Heartbeat Ack")
)

Heartbeat ack chunk errors

var (
	ErrChunkTypeNotTypeInit          = errors.New("ChunkType is not of type INIT")
	ErrChunkValueNotLongEnough       = errors.New("chunk Value isn't long enough for mandatory parameters exp")
	ErrChunkTypeInitFlagZero         = errors.New("ChunkType of type INIT flags must be all 0")
	ErrChunkTypeInitUnmarshalFailed  = errors.New("failed to unmarshal INIT body")
	ErrChunkTypeInitMarshalFailed    = errors.New("failed marshaling INIT common data")
	ErrChunkTypeInitInitateTagZero   = errors.New("ChunkType of type INIT ACK InitiateTag must not be 0")
	ErrInitInboundStreamRequestZero  = errors.New("INIT ACK inbound stream request must be > 0")
	ErrInitOutboundStreamRequestZero = errors.New("INIT ACK outbound stream request must be > 0")
	ErrInitAdvertisedReceiver1500    = errors.New("INIT ACK Advertised Receiver Window Credit (a_rwnd) must be >= 1500")
	ErrInitUnknownParam              = errors.New("INIT with unknown param")
)

Init chunk errors

var (
	ErrChunkTypeNotInitAck              = errors.New("ChunkType is not of type INIT ACK")
	ErrChunkNotLongEnoughForParams      = errors.New("chunk Value isn't long enough for mandatory parameters exp")
	ErrChunkTypeInitAckFlagZero         = errors.New("ChunkType of type INIT ACK flags must be all 0")
	ErrInitAckUnmarshalFailed           = errors.New("failed to unmarshal INIT body")
	ErrInitCommonDataMarshalFailed      = errors.New("failed marshaling INIT common data")
	ErrChunkTypeInitAckInitateTagZero   = errors.New("ChunkType of type INIT ACK InitiateTag must not be 0")
	ErrInitAckInboundStreamRequestZero  = errors.New("INIT ACK inbound stream request must be > 0")
	ErrInitAckOutboundStreamRequestZero = errors.New("INIT ACK outbound stream request must be > 0")
	ErrInitAckAdvertisedReceiver1500    = errors.New("INIT ACK Advertised Receiver Window Credit (a_rwnd) must be >= 1500")
)

Init ack chunk errors

var (
	ErrInitChunkParseParamTypeFailed = errors.New("failed to parse param type")
	ErrInitAckMarshalParam           = errors.New("unable to marshal parameter for INIT/INITACK")
)

Init chunk errors

var (
	ErrChunkParseParamTypeFailed        = errors.New("failed to parse param type")
	ErrChunkMarshalParamAReconfigFailed = errors.New("unable to marshal parameter A for reconfig")
	ErrChunkMarshalParamBReconfigFailed = errors.New("unable to marshal parameter B for reconfig")
)

Reconfigure chunk errors

var (
	ErrChunkTypeNotSack           = errors.New("ChunkType is not of type SACK")
	ErrSackSizeNotLargeEnoughInfo = errors.New("SACK Chunk size is not large enough to contain header")
	ErrSackSizeNotMatchPredicted  = errors.New("SACK Chunk size does not match predicted amount from header values")
)

Selective ack chunk errors

var (
	ErrInvalidChunkSize     = errors.New("invalid chunk size")
	ErrChunkTypeNotShutdown = errors.New("ChunkType is not of type SHUTDOWN")
)

Shutdown chunk errors

var (
	ErrChunkHeaderTooSmall       = errors.New("raw is too small for a SCTP chunk")
	ErrChunkHeaderNotEnoughSpace = errors.New("not enough data left in SCTP packet to satisfy requested length")
	ErrChunkHeaderPaddingNonZero = errors.New("chunk padding is non-zero at offset")
)

SCTP chunk header errors

var (
	ErrPacketRawTooSmall           = errors.New("raw is smaller than the minimum length for a SCTP packet")
	ErrParseSCTPChunkNotEnoughData = errors.New("unable to parse SCTP chunk, not enough data for complete header")
	ErrUnmarshalUnknownChunkType   = errors.New("failed to unmarshal, contains unknown chunk type")
	ErrChecksumMismatch            = errors.New("checksum mismatch theirs")
)

SCTP packet errors

var (
	ErrParamHeaderTooShort                  = errors.New("param header too short")
	ErrParamHeaderSelfReportedLengthShorter = errors.New("param self reported length is shorter than header length")
	ErrParamHeaderSelfReportedLengthLonger  = errors.New("param self reported length is longer than header length")
	ErrParamHeaderParseFailed               = errors.New("failed to parse param type")
)

Parameter header parse errors

var (
	ErrUnexpectedChuckPoppedUnordered = errors.New("unexpected chunk popped (unordered)")
	ErrUnexpectedChuckPoppedOrdered   = errors.New("unexpected chunk popped (ordered)")
	ErrUnexpectedQState               = errors.New("unexpected q state (should've been selected)")
)

Pending queue errors

var (
	ErrOutboundPacketTooLarge = errors.New("outbound packet larger than maximum message size")
	ErrStreamClosed           = errors.New("stream closed")
	ErrReadDeadlineExceeded   = fmt.Errorf("read deadline exceeded: %w", os.ErrDeadlineExceeded)
)

SCTP stream errors

var (
	ErrBuildErrorCaseHandle = errors.New("BuildErrorCause does not handle")
)

Error and abort chunk errors

var (
	ErrChunkPayloadSmall = errors.New("packet is smaller than the header size")
)

Data chunk errors

var (
	ErrChunkTypeNotCookieAck = errors.New("ChunkType is not of type COOKIEACK")
)

Cookie ack chunk errors

var (
	ErrChunkTypeNotCookieEcho = errors.New("ChunkType is not of type COOKIEECHO")
)

Cookie echo chunk errors

var (
	ErrChunkTypeNotShutdownAck = errors.New("ChunkType is not of type SHUTDOWN-ACK")
)

Shutdown ack chunk errors

var (
	ErrChunkTypeNotShutdownComplete = errors.New("ChunkType is not of type SHUTDOWN-COMPLETE")
)

Shutdown complete chunk errors

var ErrInvalidAlgorithmType = errors.New("invalid algorithm type")

ErrInvalidAlgorithmType is returned if unknown auth algorithm is specified.

var ErrInvalidChunkLength = errors.New("invalid chunk length")

ErrInvalidChunkLength is returned if the chunk length is invalid.

var ErrInvalidSCTPChunk = errors.New("invalid SCTP chunk")

ErrInvalidSCTPChunk is returned when an SCTP chunk is invalid

var (
	ErrParamPacketTooShort = errors.New("packet to short")
)

Parameter packet errors

var ErrParamTypeUnhandled = errors.New("unhandled ParamType")

ErrParamTypeUnhandled is returned if unknown parameter type is specified.

var (
	ErrProtocolViolationUnmarshal = errors.New("unable to unmarshal Protocol Violation error")
)

Abort chunk errors

var (
	ErrReconfigRespParamTooShort = errors.New("reconfig response parameter too short")
)

Reconfiguration response errors

var (
	ErrSSNResetRequestParamTooShort = errors.New("outgoing SSN reset request parameter too short")
)

Outgoing reset request parameter errors

var (
	ErrZeroChecksumParamTooShort = errors.New("zero checksum parameter too short")
)

Zero Checksum parameter error

Functions

func TryMarshalUnmarshal

func TryMarshalUnmarshal(msg []byte) int

TryMarshalUnmarshal attempts to marshal and unmarshal a message. Added for fuzzing.

Types

type Association

type Association struct {
	// contains filtered or unexported fields
}

Association represents an SCTP association 13.2. Parameters Necessary per Association (i.e., the TCB)

Peer        : Tag value to be sent in every packet and is received
Verification: in the INIT or INIT ACK chunk.
Tag         :
State       : A state variable indicating what state the association
            : is in, i.e., COOKIE-WAIT, COOKIE-ECHOED, ESTABLISHED,
            : SHUTDOWN-PENDING, SHUTDOWN-SENT, SHUTDOWN-RECEIVED,
            : SHUTDOWN-ACK-SENT.

Note: No "CLOSED" state is illustrated since if a association is "CLOSED" its TCB SHOULD be removed. Note: By nature of an Association being constructed with one net.Conn, it is not a multi-home supporting implementation of SCTP.

func Client

func Client(config Config) (*Association, error)

Client opens a SCTP stream over a conn

func Server

func Server(config Config) (*Association, error)

Server accepts a SCTP stream over a conn

func (*Association) Abort

func (a *Association) Abort(reason string)

Abort sends the abort packet with user initiated abort and immediately closes the connection.

func (*Association) AcceptStream

func (a *Association) AcceptStream() (*Stream, error)

AcceptStream accepts a stream

func (*Association) BytesReceived

func (a *Association) BytesReceived() uint64

BytesReceived returns the number of bytes received

func (*Association) BytesSent

func (a *Association) BytesSent() uint64

BytesSent returns the number of bytes sent

func (*Association) CWND

func (a *Association) CWND() uint32

CWND returns the association's current congestion window (cwnd)

func (*Association) Close

func (a *Association) Close() error

Close ends the SCTP Association and cleans up any state

func (*Association) MTU

func (a *Association) MTU() uint32

MTU returns the association's current MTU

func (*Association) MaxMessageSize

func (a *Association) MaxMessageSize() uint32

MaxMessageSize returns the maximum message size you can send.

func (*Association) OpenStream

func (a *Association) OpenStream(streamIdentifier uint16, defaultPayloadType PayloadProtocolIdentifier) (*Stream, error)

OpenStream opens a stream

func (*Association) RWND

func (a *Association) RWND() uint32

RWND returns the association's current receiver window (rwnd)

func (*Association) SRTT

func (a *Association) SRTT() float64

SRTT returns the latest smoothed round-trip time (srrt)

func (*Association) SetMaxMessageSize

func (a *Association) SetMaxMessageSize(maxMsgSize uint32)

SetMaxMessageSize sets the maximum message size you can send.

func (*Association) Shutdown

func (a *Association) Shutdown(ctx context.Context) error

Shutdown initiates the shutdown sequence. The method blocks until the shutdown sequence is completed and the connection is closed, or until the passed context is done, in which case the context's error is returned.

type Config

type Config struct {
	Name                 string
	NetConn              net.Conn
	MaxReceiveBufferSize uint32
	MaxMessageSize       uint32
	EnableZeroChecksum   bool
	LoggerFactory        logging.LoggerFactory

	// congestion control configuration
	// RTOMax is the maximum retransmission timeout in milliseconds
	RTOMax float64
	// Minimum congestion window
	MinCwnd uint32
	// Send window for fast retransmit
	FastRtxWnd uint32
	// Step of congestion window increase at Congestion Avoidance
	CwndCAStep uint32
}

Config collects the arguments to createAssociation construction into a single structure

type PayloadProtocolIdentifier

type PayloadProtocolIdentifier uint32

PayloadProtocolIdentifier is an enum for DataChannel payload types

const (
	PayloadTypeUnknown           PayloadProtocolIdentifier = 0
	PayloadTypeWebRTCDCEP        PayloadProtocolIdentifier = 50
	PayloadTypeWebRTCString      PayloadProtocolIdentifier = 51
	PayloadTypeWebRTCBinary      PayloadProtocolIdentifier = 53
	PayloadTypeWebRTCStringEmpty PayloadProtocolIdentifier = 56
	PayloadTypeWebRTCBinaryEmpty PayloadProtocolIdentifier = 57
)

PayloadProtocolIdentifier enums https://www.iana.org/assignments/sctp-parameters/sctp-parameters.xhtml#sctp-parameters-25

func (PayloadProtocolIdentifier) String

func (p PayloadProtocolIdentifier) String() string

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

Stream represents an SCTP stream

func (*Stream) BufferedAmount

func (s *Stream) BufferedAmount() uint64

BufferedAmount returns the number of bytes of data currently queued to be sent over this stream.

func (*Stream) BufferedAmountLowThreshold

func (s *Stream) BufferedAmountLowThreshold() uint64

BufferedAmountLowThreshold returns the number of bytes of buffered outgoing data that is considered "low." Defaults to 0.

func (*Stream) Close

func (s *Stream) Close() error

Close closes the write-direction of the stream. Future calls to Write are not permitted after calling Close.

func (*Stream) OnBufferedAmountLow

func (s *Stream) OnBufferedAmountLow(f func())

OnBufferedAmountLow sets the callback handler which would be called when the number of bytes of outgoing data buffered is lower than the threshold.

func (*Stream) Read

func (s *Stream) Read(p []byte) (int, error)

Read reads a packet of len(p) bytes, dropping the Payload Protocol Identifier. Returns EOF when the stream is reset or an error if the stream is closed otherwise.

func (*Stream) ReadSCTP

func (s *Stream) ReadSCTP(p []byte) (int, PayloadProtocolIdentifier, error)

ReadSCTP reads a packet of len(p) bytes and returns the associated Payload Protocol Identifier. Returns EOF when the stream is reset or an error if the stream is closed otherwise.

func (*Stream) SetBufferedAmountLowThreshold

func (s *Stream) SetBufferedAmountLowThreshold(th uint64)

SetBufferedAmountLowThreshold is used to update the threshold. See BufferedAmountLowThreshold().

func (*Stream) SetDefaultPayloadType

func (s *Stream) SetDefaultPayloadType(defaultPayloadType PayloadProtocolIdentifier)

SetDefaultPayloadType sets the default payload type used by Write.

func (*Stream) SetReadDeadline

func (s *Stream) SetReadDeadline(deadline time.Time) error

SetReadDeadline sets the read deadline in an identical way to net.Conn

func (*Stream) SetReliabilityParams

func (s *Stream) SetReliabilityParams(unordered bool, relType byte, relVal uint32)

SetReliabilityParams sets reliability parameters for this stream.

func (*Stream) State

func (s *Stream) State() StreamState

State return the stream state.

func (*Stream) StreamIdentifier

func (s *Stream) StreamIdentifier() uint16

StreamIdentifier returns the Stream identifier associated to the stream.

func (*Stream) Write

func (s *Stream) Write(p []byte) (n int, err error)

Write writes len(p) bytes from p with the default Payload Protocol Identifier

func (*Stream) WriteSCTP

func (s *Stream) WriteSCTP(p []byte, ppi PayloadProtocolIdentifier) (int, error)

WriteSCTP writes len(p) bytes from p to the DTLS connection

type StreamState

type StreamState int

StreamState is an enum for SCTP Stream state field This field identifies the state of stream.

const (
	StreamStateOpen    StreamState = iota // Stream object starts with StreamStateOpen
	StreamStateClosing                    // Outgoing stream is being reset
	StreamStateClosed                     // Stream has been closed
)

StreamState enums

func (StreamState) String

func (ss StreamState) String() string