Documentation/security/SELinux-sctp.rst

   1 SCTP SELinux Support
   2 =====================
   3
   4 Security Hooks
   5 ===============
   6
   7 ``Documentation/security/LSM-sctp.rst`` describes the following SCTP security
   8 hooks with the SELinux specifics expanded below::
   9
  10     security_sctp_assoc_request()
  11     security_sctp_bind_connect()
  12     security_sctp_sk_clone()
  13     security_inet_conn_established()
  14
  15
  16 security_sctp_assoc_request()
  17 -----------------------------
  18 Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the
  19 security module. Returns 0 on success, error on failure.
  20 ::
  21
  22     @ep - pointer to sctp endpoint structure.
  23     @skb - pointer to skbuff of association packet.
  24
  25 The security module performs the following operations:
  26      IF this is the first association on ``@ep->base.sk``, then set the peer
  27      sid to that in ``@skb``. This will ensure there is only one peer sid
  28      assigned to ``@ep->base.sk`` that may support multiple associations.
  29
  30      ELSE validate the ``@ep->base.sk peer_sid`` against the ``@skb peer sid``
  31      to determine whether the association should be allowed or denied.
  32
  33      Set the sctp ``@ep sid`` to socket's sid (from ``ep->base.sk``) with
  34      MLS portion taken from ``@skb peer sid``. This will be used by SCTP
  35      TCP style sockets and peeled off connections as they cause a new socket
  36      to be generated.
  37
  38      If IP security options are configured (CIPSO/CALIPSO), then the ip
  39      options are set on the socket.
  40
  41
  42 security_sctp_bind_connect()
  43 -----------------------------
  44 Checks permissions required for ipv4/ipv6 addresses based on the ``@optname``
  45 as follows::
  46
  47   ------------------------------------------------------------------
  48   |                   BIND Permission Checks                       |
  49   |       @optname             |         @address contains         |
  50   |----------------------------|-----------------------------------|
  51   | SCTP_SOCKOPT_BINDX_ADD     | One or more ipv4 / ipv6 addresses |
  52   | SCTP_PRIMARY_ADDR          | Single ipv4 or ipv6 address       |
  53   | SCTP_SET_PEER_PRIMARY_ADDR | Single ipv4 or ipv6 address       |
  54   ------------------------------------------------------------------
  55
  56   ------------------------------------------------------------------
  57   |                 CONNECT Permission Checks                      |
  58   |       @optname             |         @address contains         |
  59   |----------------------------|-----------------------------------|
  60   | SCTP_SOCKOPT_CONNECTX      | One or more ipv4 / ipv6 addresses |
  61   | SCTP_PARAM_ADD_IP          | One or more ipv4 / ipv6 addresses |
  62   | SCTP_SENDMSG_CONNECT       | Single ipv4 or ipv6 address       |
  63   | SCTP_PARAM_SET_PRIMARY     | Single ipv4 or ipv6 address       |
  64   ------------------------------------------------------------------
  65
  66
  67 ``Documentation/security/LSM-sctp.rst`` gives a summary of the ``@optname``
  68 entries and also describes ASCONF chunk processing when Dynamic Address
  69 Reconfiguration is enabled.
  70
  71
  72 security_sctp_sk_clone()
  73 -------------------------
  74 Called whenever a new socket is created by **accept**\(2) (i.e. a TCP style
  75 socket) or when a socket is 'peeled off' e.g userspace calls
  76 **sctp_peeloff**\(3). ``security_sctp_sk_clone()`` will set the new
  77 sockets sid and peer sid to that contained in the ``@ep sid`` and
  78 ``@ep peer sid`` respectively.
  79 ::
  80
  81     @ep - pointer to current sctp endpoint structure.
  82     @sk - pointer to current sock structure.
  83     @sk - pointer to new sock structure.
  84
  85
  86 security_inet_conn_established()
  87 ---------------------------------
  88 Called when a COOKIE ACK is received where it sets the connection's peer sid
  89 to that in ``@skb``::
  90
  91     @sk  - pointer to sock structure.
  92     @skb - pointer to skbuff of the COOKIE ACK packet.
  93
  94
  95 Policy Statements
  96 ==================
  97 The following class and permissions to support SCTP are available within the
  98 kernel::
  99
 100     class sctp_socket inherits socket { node_bind }
 101
 102 whenever the following policy capability is enabled::
 103
 104     policycap extended_socket_class;
 105
 106 SELinux SCTP support adds the ``name_connect`` permission for connecting
 107 to a specific port type and the ``association`` permission that is explained
 108 in the section below.
 109
 110 If userspace tools have been updated, SCTP will support the ``portcon``
 111 statement as shown in the following example::
 112
 113     portcon sctp 1024-1036 system_u:object_r:sctp_ports_t:s0
 114
 115
 116 SCTP Peer Labeling
 117 ===================
 118 An SCTP socket will only have one peer label assigned to it. This will be
 119 assigned during the establishment of the first association. Any further
 120 associations on this socket will have their packet peer label compared to
 121 the sockets peer label, and only if they are different will the
 122 ``association`` permission be validated. This is validated by checking the
 123 socket peer sid against the received packets peer sid to determine whether
 124 the association should be allowed or denied.
 125
 126 NOTES:
 127    1) If peer labeling is not enabled, then the peer context will always be
 128       ``SECINITSID_UNLABELED`` (``unlabeled_t`` in Reference Policy).
 129
 130    2) As SCTP can support more than one transport address per endpoint
 131       (multi-homing) on a single socket, it is possible to configure policy
 132       and NetLabel to provide different peer labels for each of these. As the
 133       socket peer label is determined by the first associations transport
 134       address, it is recommended that all peer labels are consistent.
 135
 136    3) **getpeercon**\(3) may be used by userspace to retrieve the sockets peer
 137       context.
 138
 139    4) While not SCTP specific, be aware when using NetLabel that if a label
 140       is assigned to a specific interface, and that interface 'goes down',
 141       then the NetLabel service will remove the entry. Therefore ensure that
 142       the network startup scripts call **netlabelctl**\(8) to set the required
 143       label (see **netlabel-config**\(8) helper script for details).
 144
 145    5) The NetLabel SCTP peer labeling rules apply as discussed in the following
 146       set of posts tagged "netlabel" at: http://www.paul-moore.com/blog/t.
 147
 148    6) CIPSO is only supported for IPv4 addressing: ``socket(AF_INET, ...)``
 149       CALIPSO is only supported for IPv6 addressing: ``socket(AF_INET6, ...)``
 150
 151       Note the following when testing CIPSO/CALIPSO:
 152          a) CIPSO will send an ICMP packet if an SCTP packet cannot be
 153             delivered because of an invalid label.
 154          b) CALIPSO does not send an ICMP packet, just silently discards it.
 155
 156    7) IPSEC is not supported as RFC 3554 - sctp/ipsec support has not been
 157       implemented in userspace (**racoon**\(8) or **ipsec_pluto**\(8)),
 158       although the kernel supports SCTP/IPSEC.