1.. SPDX-License-Identifier: GPL-2.0
2
3====
4SCTP
5====
6
7SCTP LSM Support
8================
9
10Security Hooks
11--------------
12
13For security module support, three SCTP specific hooks have been implemented::
14
15    security_sctp_assoc_request()
16    security_sctp_bind_connect()
17    security_sctp_sk_clone()
18
19Also the following security hook has been utilised::
20
21    security_inet_conn_established()
22
23The usage of these hooks are described below with the SELinux implementation
24described in the `SCTP SELinux Support`_ chapter.
25
26
27security_sctp_assoc_request()
28~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
29Passes the ``@asoc`` and ``@chunk->skb`` of the association INIT packet to the
30security module. Returns 0 on success, error on failure.
31::
32
33    @asoc - pointer to sctp association structure.
34    @skb - pointer to skbuff of association packet.
35
36
37security_sctp_bind_connect()
38~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39Passes one or more ipv4/ipv6 addresses to the security module for validation
40based on the ``@optname`` that will result in either a bind or connect
41service as shown in the permission check tables below.
42Returns 0 on success, error on failure.
43::
44
45    @sk      - Pointer to sock structure.
46    @optname - Name of the option to validate.
47    @address - One or more ipv4 / ipv6 addresses.
48    @addrlen - The total length of address(s). This is calculated on each
49               ipv4 or ipv6 address using sizeof(struct sockaddr_in) or
50               sizeof(struct sockaddr_in6).
51
52  ------------------------------------------------------------------
53  |                     BIND Type Checks                           |
54  |       @optname             |         @address contains         |
55  |----------------------------|-----------------------------------|
56  | SCTP_SOCKOPT_BINDX_ADD     | One or more ipv4 / ipv6 addresses |
57  | SCTP_PRIMARY_ADDR          | Single ipv4 or ipv6 address       |
58  | SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address       |
59  ------------------------------------------------------------------
60
61  ------------------------------------------------------------------
62  |                   CONNECT Type Checks                          |
63  |       @optname             |         @address contains         |
64  |----------------------------|-----------------------------------|
65  | SCTP_SOCKOPT_CONNECTX      | One or more ipv4 / ipv6 addresses |
66  | SCTP_PARAM_ADD_IP          | One or more ipv4 / ipv6 addresses |
67  | SCTP_SENDMSG_CONNECT       | Single ipv4 or ipv6 address       |
68  | SCTP_PARAM_SET_PRIMARY     | Single ipv4 or ipv6 address       |
69  ------------------------------------------------------------------
70
71A summary of the ``@optname`` entries is as follows::
72
73    SCTP_SOCKOPT_BINDX_ADD - Allows additional bind addresses to be
74                             associated after (optionally) calling
75                             bind(3).
76                             sctp_bindx(3) adds a set of bind
77                             addresses on a socket.
78
79    SCTP_SOCKOPT_CONNECTX - Allows the allocation of multiple
80                            addresses for reaching a peer
81                            (multi-homed).
82                            sctp_connectx(3) initiates a connection
83                            on an SCTP socket using multiple
84                            destination addresses.
85
86    SCTP_SENDMSG_CONNECT  - Initiate a connection that is generated by a
87                            sendmsg(2) or sctp_sendmsg(3) on a new asociation.
88
89    SCTP_PRIMARY_ADDR     - Set local primary address.
90
91    SCTP_SET_PEER_PRIMARY_ADDR - Request peer sets address as
92                                 association primary.
93
94    SCTP_PARAM_ADD_IP          - These are used when Dynamic Address
95    SCTP_PARAM_SET_PRIMARY     - Reconfiguration is enabled as explained below.
96
97
98To support Dynamic Address Reconfiguration the following parameters must be
99enabled on both endpoints (or use the appropriate **setsockopt**\(2))::
100
101    /proc/sys/net/sctp/addip_enable
102    /proc/sys/net/sctp/addip_noauth_enable
103
104then the following *_PARAM_*'s are sent to the peer in an
105ASCONF chunk when the corresponding ``@optname``'s are present::
106
107          @optname                      ASCONF Parameter
108         ----------                    ------------------
109    SCTP_SOCKOPT_BINDX_ADD     ->   SCTP_PARAM_ADD_IP
110    SCTP_SET_PEER_PRIMARY_ADDR ->   SCTP_PARAM_SET_PRIMARY
111
112
113security_sctp_sk_clone()
114~~~~~~~~~~~~~~~~~~~~~~~~
115Called whenever a new socket is created by **accept**\(2)
116(i.e. a TCP style socket) or when a socket is 'peeled off' e.g userspace
117calls **sctp_peeloff**\(3).
118::
119
120    @asoc - pointer to current sctp association structure.
121    @sk - pointer to current sock structure.
122    @newsk - pointer to new sock structure.
123
124
125security_inet_conn_established()
126~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127Called when a COOKIE ACK is received::
128
129    @sk  - pointer to sock structure.
130    @skb - pointer to skbuff of the COOKIE ACK packet.
131
132
133Security Hooks used for Association Establishment
134-------------------------------------------------
135
136The following diagram shows the use of ``security_sctp_bind_connect()``,
137``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when
138establishing an association.
139::
140
141      SCTP endpoint "A"                                SCTP endpoint "Z"
142      =================                                =================
143    sctp_sf_do_prm_asoc()
144 Association setup can be initiated
145 by a connect(2), sctp_connectx(3),
146 sendmsg(2) or sctp_sendmsg(3).
147 These will result in a call to
148 security_sctp_bind_connect() to
149 initiate an association to
150 SCTP peer endpoint "Z".
151         INIT --------------------------------------------->
152                                                   sctp_sf_do_5_1B_init()
153                                                 Respond to an INIT chunk.
154                                             SCTP peer endpoint "A" is asking
155                                             for a temporary association.
156                                             Call security_sctp_assoc_request()
157                                             to set the peer label if first
158                                             association.
159                                             If not first association, check
160                                             whether allowed, IF so send:
161          <----------------------------------------------- INIT ACK
162          |                                  ELSE audit event and silently
163          |                                       discard the packet.
164          |
165    COOKIE ECHO ------------------------------------------>
166                                                  sctp_sf_do_5_1D_ce()
167                                             Respond to an COOKIE ECHO chunk.
168                                             Confirm the cookie and create a
169                                             permanent association.
170                                             Call security_sctp_assoc_request() to
171                                             do the same as for INIT chunk Response.
172          <------------------------------------------- COOKIE ACK
173          |                                               |
174    sctp_sf_do_5_1E_ca                                    |
175 Call security_inet_conn_established()                    |
176 to set the peer label.                                   |
177          |                                               |
178          |                               If SCTP_SOCKET_TCP or peeled off
179          |                               socket security_sctp_sk_clone() is
180          |                               called to clone the new socket.
181          |                                               |
182      ESTABLISHED                                    ESTABLISHED
183          |                                               |
184    ------------------------------------------------------------------
185    |                     Association Established                    |
186    ------------------------------------------------------------------
187
188
189SCTP SELinux Support
190====================
191
192Security Hooks
193--------------
194
195The `SCTP LSM Support`_ chapter above describes the following SCTP security
196hooks with the SELinux specifics expanded below::
197
198    security_sctp_assoc_request()
199    security_sctp_bind_connect()
200    security_sctp_sk_clone()
201    security_inet_conn_established()
202
203
204security_sctp_assoc_request()
205~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206Passes the ``@asoc`` and ``@chunk->skb`` of the association INIT packet to the
207security module. Returns 0 on success, error on failure.
208::
209
210    @asoc - pointer to sctp association structure.
211    @skb - pointer to skbuff of association packet.
212
213The security module performs the following operations:
214     IF this is the first association on ``@asoc->base.sk``, then set the peer
215     sid to that in ``@skb``. This will ensure there is only one peer sid
216     assigned to ``@asoc->base.sk`` that may support multiple associations.
217
218     ELSE validate the ``@asoc->base.sk peer_sid`` against the ``@skb peer sid``
219     to determine whether the association should be allowed or denied.
220
221     Set the sctp ``@asoc sid`` to socket's sid (from ``asoc->base.sk``) with
222     MLS portion taken from ``@skb peer sid``. This will be used by SCTP
223     TCP style sockets and peeled off connections as they cause a new socket
224     to be generated.
225
226     If IP security options are configured (CIPSO/CALIPSO), then the ip
227     options are set on the socket.
228
229
230security_sctp_bind_connect()
231~~~~~~~~~~~~~~~~~~~~~~~~~~~~
232Checks permissions required for ipv4/ipv6 addresses based on the ``@optname``
233as follows::
234
235  ------------------------------------------------------------------
236  |                   BIND Permission Checks                       |
237  |       @optname             |         @address contains         |
238  |----------------------------|-----------------------------------|
239  | SCTP_SOCKOPT_BINDX_ADD     | One or more ipv4 / ipv6 addresses |
240  | SCTP_PRIMARY_ADDR          | Single ipv4 or ipv6 address       |
241  | SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address       |
242  ------------------------------------------------------------------
243
244  ------------------------------------------------------------------
245  |                 CONNECT Permission Checks                      |
246  |       @optname             |         @address contains         |
247  |----------------------------|-----------------------------------|
248  | SCTP_SOCKOPT_CONNECTX      | One or more ipv4 / ipv6 addresses |
249  | SCTP_PARAM_ADD_IP          | One or more ipv4 / ipv6 addresses |
250  | SCTP_SENDMSG_CONNECT       | Single ipv4 or ipv6 address       |
251  | SCTP_PARAM_SET_PRIMARY     | Single ipv4 or ipv6 address       |
252  ------------------------------------------------------------------
253
254
255`SCTP LSM Support`_ gives a summary of the ``@optname``
256entries and also describes ASCONF chunk processing when Dynamic Address
257Reconfiguration is enabled.
258
259
260security_sctp_sk_clone()
261~~~~~~~~~~~~~~~~~~~~~~~~
262Called whenever a new socket is created by **accept**\(2) (i.e. a TCP style
263socket) or when a socket is 'peeled off' e.g userspace calls
264**sctp_peeloff**\(3). ``security_sctp_sk_clone()`` will set the new
265sockets sid and peer sid to that contained in the ``@asoc sid`` and
266``@asoc peer sid`` respectively.
267::
268
269    @asoc - pointer to current sctp association structure.
270    @sk - pointer to current sock structure.
271    @newsk - pointer to new sock structure.
272
273
274security_inet_conn_established()
275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276Called when a COOKIE ACK is received where it sets the connection's peer sid
277to that in ``@skb``::
278
279    @sk  - pointer to sock structure.
280    @skb - pointer to skbuff of the COOKIE ACK packet.
281
282
283Policy Statements
284-----------------
285The following class and permissions to support SCTP are available within the
286kernel::
287
288    class sctp_socket inherits socket { node_bind }
289
290whenever the following policy capability is enabled::
291
292    policycap extended_socket_class;
293
294SELinux SCTP support adds the ``name_connect`` permission for connecting
295to a specific port type and the ``association`` permission that is explained
296in the section below.
297
298If userspace tools have been updated, SCTP will support the ``portcon``
299statement as shown in the following example::
300
301    portcon sctp 1024-1036 system_u:object_r:sctp_ports_t:s0
302
303
304SCTP Peer Labeling
305------------------
306An SCTP socket will only have one peer label assigned to it. This will be
307assigned during the establishment of the first association. Any further
308associations on this socket will have their packet peer label compared to
309the sockets peer label, and only if they are different will the
310``association`` permission be validated. This is validated by checking the
311socket peer sid against the received packets peer sid to determine whether
312the association should be allowed or denied.
313
314NOTES:
315   1) If peer labeling is not enabled, then the peer context will always be
316      ``SECINITSID_UNLABELED`` (``unlabeled_t`` in Reference Policy).
317
318   2) As SCTP can support more than one transport address per endpoint
319      (multi-homing) on a single socket, it is possible to configure policy
320      and NetLabel to provide different peer labels for each of these. As the
321      socket peer label is determined by the first associations transport
322      address, it is recommended that all peer labels are consistent.
323
324   3) **getpeercon**\(3) may be used by userspace to retrieve the sockets peer
325      context.
326
327   4) While not SCTP specific, be aware when using NetLabel that if a label
328      is assigned to a specific interface, and that interface 'goes down',
329      then the NetLabel service will remove the entry. Therefore ensure that
330      the network startup scripts call **netlabelctl**\(8) to set the required
331      label (see **netlabel-config**\(8) helper script for details).
332
333   5) The NetLabel SCTP peer labeling rules apply as discussed in the following
334      set of posts tagged "netlabel" at: https://www.paul-moore.com/blog/t.
335
336   6) CIPSO is only supported for IPv4 addressing: ``socket(AF_INET, ...)``
337      CALIPSO is only supported for IPv6 addressing: ``socket(AF_INET6, ...)``
338
339      Note the following when testing CIPSO/CALIPSO:
340         a) CIPSO will send an ICMP packet if an SCTP packet cannot be
341            delivered because of an invalid label.
342         b) CALIPSO does not send an ICMP packet, just silently discards it.
343
344   7) IPSEC is not supported as RFC 3554 - sctp/ipsec support has not been
345      implemented in userspace (**racoon**\(8) or **ipsec_pluto**\(8)),
346      although the kernel supports SCTP/IPSEC.
347