Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0 |
| 2 | |
| 3 | ==== |
| 4 | SCTP |
| 5 | ==== |
| 6 | |
| 7 | SCTP LSM Support |
| 8 | ================ |
| 9 | |
| 10 | Security Hooks |
| 11 | -------------- |
| 12 | |
| 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() |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 18 | security_sctp_assoc_established() |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 19 | |
| 20 | The usage of these hooks are described below with the SELinux implementation |
| 21 | described in the `SCTP SELinux Support`_ chapter. |
| 22 | |
| 23 | |
| 24 | security_sctp_assoc_request() |
| 25 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 26 | Passes the ``@asoc`` and ``@chunk->skb`` of the association INIT packet to the |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 27 | security module. Returns 0 on success, error on failure. |
| 28 | :: |
| 29 | |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 30 | @asoc - pointer to sctp association structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 31 | @skb - pointer to skbuff of association packet. |
| 32 | |
| 33 | |
| 34 | security_sctp_bind_connect() |
| 35 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 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 |
Remington Brasga | da51bbc | 2024-04-29 22:55:27 +0000 | [diff] [blame] | 84 | sendmsg(2) or sctp_sendmsg(3) on a new association. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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() |
| 111 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 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 | |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 117 | @asoc - pointer to current sctp association structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 118 | @sk - pointer to current sock structure. |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 119 | @newsk - pointer to new sock structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 120 | |
| 121 | |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 122 | security_sctp_assoc_established() |
Wan Jiabing | 70868c6 | 2022-02-28 10:56:41 +0800 | [diff] [blame] | 123 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 124 | Called when a COOKIE ACK is received, and the peer secid will be |
| 125 | saved into ``@asoc->peer_secid`` for client:: |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 126 | |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 127 | @asoc - pointer to sctp association structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 128 | @skb - pointer to skbuff of the COOKIE ACK packet. |
| 129 | |
| 130 | |
| 131 | Security Hooks used for Association Establishment |
| 132 | ------------------------------------------------- |
| 133 | |
| 134 | The following diagram shows the use of ``security_sctp_bind_connect()``, |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 135 | ``security_sctp_assoc_request()``, ``security_sctp_assoc_established()`` when |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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. |
Xin Long | e215dab | 2021-11-02 08:02:48 -0400 | [diff] [blame] | 152 | SCTP peer endpoint "A" is asking |
| 153 | for a temporary association. |
| 154 | Call security_sctp_assoc_request() |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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 ------------------------------------------> |
Xin Long | e215dab | 2021-11-02 08:02:48 -0400 | [diff] [blame] | 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. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 170 | <------------------------------------------- COOKIE ACK |
| 171 | | | |
| 172 | sctp_sf_do_5_1E_ca | |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 173 | Call security_sctp_assoc_established() | |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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 | |
| 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() |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 199 | security_sctp_assoc_established() |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 200 | |
| 201 | |
| 202 | security_sctp_assoc_request() |
| 203 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 204 | Passes the ``@asoc`` and ``@chunk->skb`` of the association INIT packet to the |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 205 | security module. Returns 0 on success, error on failure. |
| 206 | :: |
| 207 | |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 208 | @asoc - pointer to sctp association structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 209 | @skb - pointer to skbuff of association packet. |
| 210 | |
| 211 | The security module performs the following operations: |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 212 | IF this is the first association on ``@asoc->base.sk``, then set the peer |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 213 | sid to that in ``@skb``. This will ensure there is only one peer sid |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 214 | assigned to ``@asoc->base.sk`` that may support multiple associations. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 215 | |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 216 | ELSE validate the ``@asoc->base.sk peer_sid`` against the ``@skb peer sid`` |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 217 | to determine whether the association should be allowed or denied. |
| 218 | |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 219 | Set the sctp ``@asoc sid`` to socket's sid (from ``asoc->base.sk``) with |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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 |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 263 | sockets sid and peer sid to that contained in the ``@asoc sid`` and |
| 264 | ``@asoc peer sid`` respectively. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 265 | :: |
| 266 | |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 267 | @asoc - pointer to current sctp association structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 268 | @sk - pointer to current sock structure. |
Xin Long | c081d53 | 2021-11-02 08:02:47 -0400 | [diff] [blame] | 269 | @newsk - pointer to new sock structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 270 | |
| 271 | |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 272 | security_sctp_assoc_established() |
Wan Jiabing | 70868c6 | 2022-02-28 10:56:41 +0800 | [diff] [blame] | 273 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 274 | Called when a COOKIE ACK is received where it sets the connection's peer sid |
| 275 | to that in ``@skb``:: |
| 276 | |
Ondrej Mosnacek | 5e50f5d | 2022-02-12 18:59:21 +0100 | [diff] [blame] | 277 | @asoc - pointer to sctp association structure. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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 |
Alexander A. Klimov | 93431e0 | 2020-05-26 08:05:44 +0200 | [diff] [blame] | 332 | set of posts tagged "netlabel" at: https://www.paul-moore.com/blog/t. |
Kees Cook | d61330c | 2019-02-17 14:08:36 -0800 | [diff] [blame] | 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. |