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