Module sctp

Objects

class sctp.sctp_generic(**kwds)
Bases:

dict

__fields__
Type:

dict

Value:

{}

Valid dictionary keys with value formats and default values.

__c_size__
Type:

int

Value:

0

The size in bytes of the corresponding C-structure (sizeof()). See note in _sctp.sctp about alignment of C-structures.

__optname__
Type:

int

Value:

0

Socket option name (e.g., SCTP_RTOINFO)

property fmt
Classmethod:

Type:

str

The format used by struct.pack() in property to_bytes. It takes into account any possible padding (see note in _sctp.sctp about padding).

property size
Classmethod:

Type:

int

A shortcut for struct.calcsize(fmt).

property to_bytes
Type:

str

Converts the dictionary into a bytes object (using struct.pack() with format fmt).

set_value(field, value)
Parameters:
Returns:

value, if check succeeded

Raises:

TypeError – if check failed

Warning

This class cannot be instanciated.

class sctp.sctp_initmsg(*, sinit_num_ostreams=0, sinit_max_instreams=0, sinit_max_attempts=0, sinit_max_init_timeo=0)
Bases:

sctp_generic

See SCTP_INITMSG socket option.

class sctp.sctp_paddrparams(*, spp_assoc_id=0, spp_address=bytes(SOCKADDR_STORAGE_CSIZE), spp_hbinterval=0, spp_pathmaxrxt=0, spp_pathmtu=0, spp_flags=0, spp_ipv6_flowlabel=0, spp_dscp=0)
Bases:

sctp_generic

See SCTP_PEER_ADDR_PARAMS socket option.

class sctp.sctp_paddrinfo(*, spinfo_assoc_id=0, spinfo_address=bytes(SOCKADDR_STORAGE_CSIZE), spinfo_state=0, spinfo_cwnd=0, spinfo_srtt=0, spinfo_rto=0, spinfo_mtu=0)
Bases:

sctp_generic

See SCTP_GET_PEER_ADDR_INFO socket option.

class sctp.sctp_rtoinfo(*, srto_assoc_id=0, srto_initial=0, srto_max=0, srto_min=0)
Bases:

sctp_generic

See SCTP_RTOINFO socket option.

class sctp.sctp_assocparams(*, sasoc_assoc_id=0, sasoc_asocmaxrxt=0, sasoc_number_peer_destinations=0, sasoc_peer_rwnd=0, sasoc_local_rwnd=0, sasoc_cookie_life=0)
Bases:

sctp_generic

See SCTP_ASSOCINFO socket option.

class sctp.sctp_setprim(*, ssp_assoc_id=0, ssp_addr=bytes(SOCKADDR_STORAGE_CSIZE))
Bases:

sctp_generic

See SCTP_PRIMARY_ADDR socket option.

class sctp.sctp_setadaptation(*, ssb_adaptation_ind=0)
Bases:

sctp_generic

See SCTP_ADAPTATION_LAYER socket option.

class sctp.sctp_assoc_value(*, assoc_id=0, assoc_value=0)
Bases:

sctp_generic

See SCTP_MAXSEG, SCTP_MAX_BURST, SCTP_CONTEXT socket options.

class sctp.sctp_sack_info(*, sack_assoc_id=0, sack_delay=0, sack_freq=0)
Bases:

sctp_generic

See SCTP_DELAYED_SACK socket option.

class sctp.sctp_authkeyid(*, scact_assoc_id=0, scact_keynumber)
Bases:

sctp_generic

See :py:data: SCTP_AUTH_ACTIVE_KEY socket option.

class sctp.sctp_default_prinfo(*, pr_policy=SCTP_PR_SCTP_NONE, pr_value=0, pr_assoc_id=0)
Bases:

sctp_generic

See SCTP_DEFAULT_PRINFO socket option.

class sctp.sctp_status(*, sstat_assoc_id=0, sstat_state=0, sstat_rwnd=0, sstat_unackdata=0, sstat_penddata=0, sstat_instrms=0, sstat_outstrms=0, sstat_fragmentation_point=0, sstat_primary=bytes(sctp_paddrinfo.size))
Bases:

sctp_generic

See SCTP_STATUS socket option.

class sctp.sctp_setpeerprim(*, sspp_assoc_id=0, sspp_addr=bytes(SOCKADDR_STORAGE_CSIZE))
Bases:

sctp_generic

See SCTP_SET_PEER_PRIMARY_ADDR socket option.

class sctp.sctp_authchunk(*, sauth_chunk=ChunkTypes.DATA.value)
Bases:

sctp_generic

See SCTP_AUTH_CHUNK socket option.

class sctp.sctp_authkey(*, sca_assoc_id=0, sca_keynumber=0, sca_key=None)
Bases:

dict

See SCTP_AUTH_KEY socket option.

class sctp.sctp_event(*, se_assoc_id=0, se_type=0, se_on=0)
Bases:

sctp_generic

See SCTP_EVENT socket option.

class sctp.sctp_socket(family, type, proto=IPPROTO_SCTP)
Bases:

_sctp.sctp.sctp_socket

getsockopt(level, optname, optval=None)
Parameters:
Returns:

a int object, a bytes object, a tuple object or an object inherited from sctp_generic

Raises:

TypeError, OSError –

Note

When optname is not IPPROTO_SCTP, getsockopt() behaves exactly like method getsockopt() of the standard Python object socket.

Some examples when level is IPPROTO_SCTP:

>>> sock = sctp_socket(AF_INET, SOCK_SEQPACKET)
>>> sock.connect(('localhost', 2000))
>>> spinfo = sctp_paddrinfo(spinfo_address=(('localhost', 20000)))
>>> print(s.getsockopt(IPPROTO_SCTP, SCTP_GET_PEER_ADDR_INFO, spinfo))
{'spinfo_assoc_id': 29, 'spinfo_address': ('127.0.0.1', 20000),
 'spinfo_state': 2, 'spinfo_cwnd': 131064, 'spinfo_srtt': 0,
 'spinfo_rto': 3000, 'spinfo_mtu': 65532}

>>> sock = sctp_socket(AF_INET, SOCK_STREAM)
>>> print(sock.getsockopt(IPPROTO_SCTP, SCTP_INITMSG))
{'sinit_num_ostreams': 10, 'sinit_max_instreams': 65535,
 'sinit_max_attempts': 8, 'sinit_max_init_timeo': 60000}

>>> sock = sctp_socket(AF_INET, SOCK_STREAM)
>>> id = sock.sctp_connectx((('localhost', 20000),), assoc_id=True)
>>> print(sock.getsockopt(IPPROTO_SCTP, SCTP_PEER_AUTH_CHUNKS, id))
{'gauth_assoc_id': 3, 'gauth_chunks': (128, 193)}
setsockopt(level, optname, *values)
Parameters:
Returns:

None

Raises:

TypeError, OSError –

Note

When optname is not IPPROTO_SCTP, setsockopt() behaves exactly like method setsockopt() of the standard Python object socket.

An example showing how to change the number of output streams during initialization:

>>> sock = sctp_socket(AF_INET, SOCK_STREAM)
>>> sinit = sock.getsockopt(IPPROTO_SCTP, SCTP_INITMSG)
>>> print(sinit['sinit_num_ostreams'])
10
>>> sinit['sinit_num_ostreams'] = 100
>>> sock.setsockopt(IPPROTO_SCTP, SCTP_INITMSG, sinit)

Some specific socket options

  • SCTP_FRAGMENT_INTERLEAVE

    Last argument of setsockopt() must be 0, 1 or 2.

  • SCTP_HMAC_IDENT

    To set this option: setsockopt(IPPROTO_SCTP, SCTP_HMAC_IDENT, ids) where ids is a tuple of HMAC identifiers. For example:

    >>> setsockopt(IPPROTO_SCTP, SCTP_HMAC_IDENT,
               (SCTP_AUTH_HMAC_ID_SHA256, SCTP_AUTH_HMAC_ID_SHA1))

    Warning

    Algorithm SCTP_AUTH_HMAC_ID_SHA1 is mandatory, otherwise ValueError is raised.

    To get the list of supported HMAC identifiers:

    >>> print(getsockopt(IPPROTO_SCTP, SCTP_HMAC_IDENT))
(3, 1)

  • SCTP_PEER_AUTH_CHUNKS, SCTP_LOCAL_AUTH_CHUNKS

    Both options can take an association identifier as an optional parameter:

    >>> sock = sctp_socket(AF_INET, SOCK_STREAM, IPPROTO_SCTP)
>>> id = sock.sctp_connectx((('localhost', 20000),), assoc_id=True)
>>> print(sock.getsockopt(IPPROTO_SCTP, SCTP_PEER_AUTH_CHUNKS, id))
{'gauth_assoc_id': 3, 'gauth_chunks': (128, 193)}

  • SCTP_AUTH_CHUNK

    This (write-only) option takes a member of ChunkTypes as argument:

    >>> sauth = sctp_authchunk(sauth_chunk=ChunkTypes.COOKIE_ACK)
>>> sock.setsockopt(IPPROTO_SCTP, SCTP_AUTH_CHUNK, sauth)

    Warning

    Chunk types INIT, INIT_ACK, SHUTDOWN_COMPLETE and AUTH, are not allowed, otherwise ValueError is raised.

  • SCTP_AUTH_KEY

    This option will set a shared secret key as follows:

    >>> sca = sctp_authkey(sca_keynumber=13, sca_key=b'some secret')
>>> sock.setsockopt(IPPROTO_SCTP, SCTP_AUTH_KEY, sca)

    To disable and then remove this shared secret key:

    >>> scact = sctp_authkeyid(scact_keynumber=13)
>>> sock.setsockopt(IPPROTO_SCTP, SCTP_AUTH_DEACTIVATE_KEY, scact)
>>> sock.setsockopt(IPPROTO_SCTP, SCTP_AUTH_DELETE_KEY, scact)
sctp_opt_info([id, ]optname, optval)
Parameters:
Returns:

a int object, a bytes object, a tuple object or an object inherited from sctp_generic

Raises:

TypeError, ValueError, OSError –

The optval parameter must have a field whose name ends with 'assoc_id', such as 'srto_assoc_id', otherwise ValueError is raised. The value of id is then assigned to this field before calling getsockopt(IPPROTO_SCTP, optname, optval).

An example with one-to-one socket:

>>> sock = sctp_socket(AF_INET, SOCK_STREAM)
>>> sock.sctp_connectx((('localhost', 20000),))
>>> optval = sctp_assoc_value()
>>> opt = sctp_opt_info(SCTP_MAXSEG, optval)
>>> print(opt)
{'assoc_id': 0, 'assoc_value': 65484}

Another one with one-to-many socket:

>>> sock = sctp_socket(AF_INET, SOCK_SEQPACKET)
>>> sock.sctp_connectx((('localhost', 20000),))
>>> optval = sctp_status()
>>> opt = sctp_opt_info(SCTP_STATUS, optval)
...
OSError: sctp_socket._getsockopt(): [22, Invalid argument]
# parameter `id' is required for one-to-many sockets

>>> id = sock.sctp_connectx((('localhost', 20000),), assoc_id=True)
>>> optval = sctp_status()
>>> opt = sctp_opt_info(id, SCTP_STATUS, optval)
    #                   ^^
    #          required parameter id
>>> print(opt)
{'sstat_assoc_id': 321, 'sstat_state': 4, 'sstat_rwnd': 106496,
 'sstat_unackdata': 0, 'sstat_penddata': 0, 'sstat_instrms': 2,
 'sstat_outstrms': 10, 'sstat_fragmentation_point': 65484,
 'sstat_primary': {'spinfo_assoc_id': 321, 'spinfo_address':
                   ('127.0.0.1', 20000), 'spinfo_state': 2,
                   'spinfo_cwnd': 131064, 'spinfo_srtt': 0,
                   'spinfo_rto': 3000, 'spinfo_mtu': 65532}}

Note

In fact, if the 'assoc_id' field of optval is named 'field_assoc_id' for example, sctp_opt_info(id, optname, optval) is equivalent to: optval['field_assoc_id'] = id; getsockopt(IPPROTO_SCTP, optname, optval).

Some useful objects

class sctp.ChunkTypes
Bases:

enum.IntEnum

DATA, INIT, INIT_ACK, SACK, HEARTBEAT, HEARTBEAT_ACK,
ABORT, SHUTDOWN, SHUTDOWN_ACK, ERROR, COOKIE_ECHO, COOKIE_ACK,
SHUTDOWN_COMPLETE, AUTH
name(type)
Classmethod:

Parameters:

type (int) – chunk type as an integer in range [0-255] (see RFC 4960 – section-3.2)

Returns:

the plain name of the chunk type (e.g., ChunkTypes.name(11) returns 'COOKIE_ACK')

Raises:

TypeError – if type is not an integer in range [0-255]