Documentation/security/LSM-sctp.rst

   1 SCTP LSM Support
   2 ================
   3
   4 For security module support, three SCTP specific hooks have been implemented::
   5
   6     security_sctp_assoc_request()
   7     security_sctp_bind_connect()
   8     security_sctp_sk_clone()
   9
  10 Also the following security hook has been utilised::
  11
  12     security_inet_conn_established()
  13
  14 The usage of these hooks are described below with the SELinux implementation
  15 described in ``Documentation/security/SELinux-sctp.rst``
  16
  17
  18 security_sctp_assoc_request()
  19 -----------------------------
  20 Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the
  21 security module. Returns 0 on success, error on failure.
  22 ::
  23
  24     @ep - pointer to sctp endpoint structure.
  25     @skb - pointer to skbuff of association packet.
  26
  27
  28 security_sctp_bind_connect()
  29 -----------------------------
  30 Passes one or more ipv4/ipv6 addresses to the security module for validation
  31 based on the ``@optname`` that will result in either a bind or connect
  32 service as shown in the permission check tables below.
  33 Returns 0 on success, error on failure.
  34 ::
  35
  36     @sk      - Pointer to sock structure.
  37     @optname - Name of the option to validate.
  38     @address - One or more ipv4 / ipv6 addresses.
  39     @addrlen - The total length of address(s). This is calculated on each
  40                ipv4 or ipv6 address using sizeof(struct sockaddr_in) or
  41                sizeof(struct sockaddr_in6).
  42
  43   ------------------------------------------------------------------
  44   |                     BIND Type Checks                           |
  45   |       @optname             |         @address contains         |
  46   |----------------------------|-----------------------------------|
  47   | SCTP_SOCKOPT_BINDX_ADD     | One or more ipv4 / ipv6 addresses |
  48   | SCTP_PRIMARY_ADDR          | Single ipv4 or ipv6 address       |
  49   | SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address       |
  50   ------------------------------------------------------------------
  51
  52   ------------------------------------------------------------------
  53   |                   CONNECT Type Checks                          |
  54   |       @optname             |         @address contains         |
  55   |----------------------------|-----------------------------------|
  56   | SCTP_SOCKOPT_CONNECTX      | One or more ipv4 / ipv6 addresses |
  57   | SCTP_PARAM_ADD_IP          | One or more ipv4 / ipv6 addresses |
  58   | SCTP_SENDMSG_CONNECT       | Single ipv4 or ipv6 address       |
  59   | SCTP_PARAM_SET_PRIMARY     | Single ipv4 or ipv6 address       |
  60   ------------------------------------------------------------------
  61
  62 A summary of the ``@optname`` entries is as follows::
  63
  64     SCTP_SOCKOPT_BINDX_ADD - Allows additional bind addresses to be
  65                              associated after (optionally) calling
  66                              bind(3).
  67                              sctp_bindx(3) adds a set of bind
  68                              addresses on a socket.
  69
  70     SCTP_SOCKOPT_CONNECTX - Allows the allocation of multiple
  71                             addresses for reaching a peer
  72                             (multi-homed).
  73                             sctp_connectx(3) initiates a connection
  74                             on an SCTP socket using multiple
  75                             destination addresses.
  76
  77     SCTP_SENDMSG_CONNECT  - Initiate a connection that is generated by a
  78                             sendmsg(2) or sctp_sendmsg(3) on a new asociation.
  79
  80     SCTP_PRIMARY_ADDR     - Set local primary address.
  81
  82     SCTP_SET_PEER_PRIMARY_ADDR - Request peer sets address as
  83                                  association primary.
  84
  85     SCTP_PARAM_ADD_IP          - These are used when Dynamic Address
  86     SCTP_PARAM_SET_PRIMARY     - Reconfiguration is enabled as explained below.
  87
  88
  89 To support Dynamic Address Reconfiguration the following parameters must be
  90 enabled on both endpoints (or use the appropriate **setsockopt**\(2))::
  91
  92     /proc/sys/net/sctp/addip_enable
  93     /proc/sys/net/sctp/addip_noauth_enable
  94
  95 then the following *_PARAM_*'s are sent to the peer in an
  96 ASCONF chunk when the corresponding ``@optname``'s are present::
  97
  98           @optname                      ASCONF Parameter
  99          ----------                    ------------------
 100     SCTP_SOCKOPT_BINDX_ADD     ->   SCTP_PARAM_ADD_IP
 101     SCTP_SET_PEER_PRIMARY_ADDR ->   SCTP_PARAM_SET_PRIMARY
 102
 103
 104 security_sctp_sk_clone()
 105 -------------------------
 106 Called whenever a new socket is created by **accept**\(2)
 107 (i.e. a TCP style socket) or when a socket is 'peeled off' e.g userspace
 108 calls **sctp_peeloff**\(3).
 109 ::
 110
 111     @ep - pointer to current sctp endpoint structure.
 112     @sk - pointer to current sock structure.
 113     @sk - pointer to new sock structure.
 114
 115
 116 security_inet_conn_established()
 117 ---------------------------------
 118 Called when a COOKIE ACK is received::
 119
 120     @sk  - pointer to sock structure.
 121     @skb - pointer to skbuff of the COOKIE ACK packet.
 122
 123
 124 Security Hooks used for Association Establishment
 125 =================================================
 126 The following diagram shows the use of ``security_sctp_bind_connect()``,
 127 ``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when
 128 establishing an association.
 129 ::
 130
 131       SCTP endpoint "A"                                SCTP endpoint "Z"
 132       =================                                =================
 133     sctp_sf_do_prm_asoc()
 134  Association setup can be initiated
 135  by a connect(2), sctp_connectx(3),
 136  sendmsg(2) or sctp_sendmsg(3).
 137  These will result in a call to
 138  security_sctp_bind_connect() to
 139  initiate an association to
 140  SCTP peer endpoint "Z".
 141          INIT --------------------------------------------->
 142                                                    sctp_sf_do_5_1B_init()
 143                                                  Respond to an INIT chunk.
 144                                              SCTP peer endpoint "A" is
 145                                              asking for an association. Call
 146                                              security_sctp_assoc_request()
 147                                              to set the peer label if first
 148                                              association.
 149                                              If not first association, check
 150                                              whether allowed, IF so send:
 151           <----------------------------------------------- INIT ACK
 152           |                                  ELSE audit event and silently
 153           |                                       discard the packet.
 154           |
 155     COOKIE ECHO ------------------------------------------>
 156                                                           |
 157                                                           |
 158                                                           |
 159           <------------------------------------------- COOKIE ACK
 160           |                                               |
 161     sctp_sf_do_5_1E_ca                                    |
 162  Call security_inet_conn_established()                    |
 163  to set the peer label.                                   |
 164           |                                               |
 165           |                               If SCTP_SOCKET_TCP or peeled off
 166           |                               socket security_sctp_sk_clone() is
 167           |                               called to clone the new socket.
 168           |                                               |
 169       ESTABLISHED                                    ESTABLISHED
 170           |                                               |
 171     ------------------------------------------------------------------
 172     |                     Association Established                    |
 173     ------------------------------------------------------------------
 174
 175