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