1SCTP LSM Support
2================
3
4For 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
10Also the following security hook has been utilised::
11
12    security_inet_conn_established()
13
14The usage of these hooks are described below with the SELinux implementation
15described in ``Documentation/security/SELinux-sctp.rst``
16
17
18security_sctp_assoc_request()
19-----------------------------
20Passes the ``@ep`` and ``@chunk->skb`` of the association INIT packet to the
21security 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
28security_sctp_bind_connect()
29-----------------------------
30Passes one or more ipv4/ipv6 addresses to the security module for validation
31based on the ``@optname`` that will result in either a bind or connect
32service as shown in the permission check tables below.
33Returns 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
62A 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
89To support Dynamic Address Reconfiguration the following parameters must be
90enabled 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
95then the following *_PARAM_*'s are sent to the peer in an
96ASCONF 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
104security_sctp_sk_clone()
105-------------------------
106Called 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
108calls **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
116security_inet_conn_established()
117---------------------------------
118Called 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
124Security Hooks used for Association Establishment
125=================================================
126The following diagram shows the use of ``security_sctp_bind_connect()``,
127``security_sctp_assoc_request()``, ``security_inet_conn_established()`` when
128establishing 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
176