1.. _kernel_tls:
2
3==========
4Kernel TLS
5==========
6
7Overview
8========
9
10Transport Layer Security (TLS) is a Upper Layer Protocol (ULP) that runs over
11TCP. TLS provides end-to-end data integrity and confidentiality.
12
13User interface
14==============
15
16Creating a TLS connection
17-------------------------
18
19First create a new TCP socket and set the TLS ULP.
20
21.. code-block:: c
22
23  sock = socket(AF_INET, SOCK_STREAM, 0);
24  setsockopt(sock, SOL_TCP, TCP_ULP, "tls", sizeof("tls"));
25
26Setting the TLS ULP allows us to set/get TLS socket options. Currently
27only the symmetric encryption is handled in the kernel.  After the TLS
28handshake is complete, we have all the parameters required to move the
29data-path to the kernel. There is a separate socket option for moving
30the transmit and the receive into the kernel.
31
32.. code-block:: c
33
34  /* From linux/tls.h */
35  struct tls_crypto_info {
36          unsigned short version;
37          unsigned short cipher_type;
38  };
39
40  struct tls12_crypto_info_aes_gcm_128 {
41          struct tls_crypto_info info;
42          unsigned char iv[TLS_CIPHER_AES_GCM_128_IV_SIZE];
43          unsigned char key[TLS_CIPHER_AES_GCM_128_KEY_SIZE];
44          unsigned char salt[TLS_CIPHER_AES_GCM_128_SALT_SIZE];
45          unsigned char rec_seq[TLS_CIPHER_AES_GCM_128_REC_SEQ_SIZE];
46  };
47
48
49  struct tls12_crypto_info_aes_gcm_128 crypto_info;
50
51  crypto_info.info.version = TLS_1_2_VERSION;
52  crypto_info.info.cipher_type = TLS_CIPHER_AES_GCM_128;
53  memcpy(crypto_info.iv, iv_write, TLS_CIPHER_AES_GCM_128_IV_SIZE);
54  memcpy(crypto_info.rec_seq, seq_number_write,
55					TLS_CIPHER_AES_GCM_128_REC_SEQ_SIZE);
56  memcpy(crypto_info.key, cipher_key_write, TLS_CIPHER_AES_GCM_128_KEY_SIZE);
57  memcpy(crypto_info.salt, implicit_iv_write, TLS_CIPHER_AES_GCM_128_SALT_SIZE);
58
59  setsockopt(sock, SOL_TLS, TLS_TX, &crypto_info, sizeof(crypto_info));
60
61Transmit and receive are set separately, but the setup is the same, using either
62TLS_TX or TLS_RX.
63
64Sending TLS application data
65----------------------------
66
67After setting the TLS_TX socket option all application data sent over this
68socket is encrypted using TLS and the parameters provided in the socket option.
69For example, we can send an encrypted hello world record as follows:
70
71.. code-block:: c
72
73  const char *msg = "hello world\n";
74  send(sock, msg, strlen(msg));
75
76send() data is directly encrypted from the userspace buffer provided
77to the encrypted kernel send buffer if possible.
78
79The sendfile system call will send the file's data over TLS records of maximum
80length (2^14).
81
82.. code-block:: c
83
84  file = open(filename, O_RDONLY);
85  fstat(file, &stat);
86  sendfile(sock, file, &offset, stat.st_size);
87
88TLS records are created and sent after each send() call, unless
89MSG_MORE is passed.  MSG_MORE will delay creation of a record until
90MSG_MORE is not passed, or the maximum record size is reached.
91
92The kernel will need to allocate a buffer for the encrypted data.
93This buffer is allocated at the time send() is called, such that
94either the entire send() call will return -ENOMEM (or block waiting
95for memory), or the encryption will always succeed.  If send() returns
96-ENOMEM and some data was left on the socket buffer from a previous
97call using MSG_MORE, the MSG_MORE data is left on the socket buffer.
98
99Receiving TLS application data
100------------------------------
101
102After setting the TLS_RX socket option, all recv family socket calls
103are decrypted using TLS parameters provided.  A full TLS record must
104be received before decryption can happen.
105
106.. code-block:: c
107
108  char buffer[16384];
109  recv(sock, buffer, 16384);
110
111Received data is decrypted directly in to the user buffer if it is
112large enough, and no additional allocations occur.  If the userspace
113buffer is too small, data is decrypted in the kernel and copied to
114userspace.
115
116``EINVAL`` is returned if the TLS version in the received message does not
117match the version passed in setsockopt.
118
119``EMSGSIZE`` is returned if the received message is too big.
120
121``EBADMSG`` is returned if decryption failed for any other reason.
122
123Send TLS control messages
124-------------------------
125
126Other than application data, TLS has control messages such as alert
127messages (record type 21) and handshake messages (record type 22), etc.
128These messages can be sent over the socket by providing the TLS record type
129via a CMSG. For example the following function sends @data of @length bytes
130using a record of type @record_type.
131
132.. code-block:: c
133
134  /* send TLS control message using record_type */
135  static int klts_send_ctrl_message(int sock, unsigned char record_type,
136                                    void *data, size_t length)
137  {
138        struct msghdr msg = {0};
139        int cmsg_len = sizeof(record_type);
140        struct cmsghdr *cmsg;
141        char buf[CMSG_SPACE(cmsg_len)];
142        struct iovec msg_iov;   /* Vector of data to send/receive into.  */
143
144        msg.msg_control = buf;
145        msg.msg_controllen = sizeof(buf);
146        cmsg = CMSG_FIRSTHDR(&msg);
147        cmsg->cmsg_level = SOL_TLS;
148        cmsg->cmsg_type = TLS_SET_RECORD_TYPE;
149        cmsg->cmsg_len = CMSG_LEN(cmsg_len);
150        *CMSG_DATA(cmsg) = record_type;
151        msg.msg_controllen = cmsg->cmsg_len;
152
153        msg_iov.iov_base = data;
154        msg_iov.iov_len = length;
155        msg.msg_iov = &msg_iov;
156        msg.msg_iovlen = 1;
157
158        return sendmsg(sock, &msg, 0);
159  }
160
161Control message data should be provided unencrypted, and will be
162encrypted by the kernel.
163
164Receiving TLS control messages
165------------------------------
166
167TLS control messages are passed in the userspace buffer, with message
168type passed via cmsg.  If no cmsg buffer is provided, an error is
169returned if a control message is received.  Data messages may be
170received without a cmsg buffer set.
171
172.. code-block:: c
173
174  char buffer[16384];
175  char cmsg[CMSG_SPACE(sizeof(unsigned char))];
176  struct msghdr msg = {0};
177  msg.msg_control = cmsg;
178  msg.msg_controllen = sizeof(cmsg);
179
180  struct iovec msg_iov;
181  msg_iov.iov_base = buffer;
182  msg_iov.iov_len = 16384;
183
184  msg.msg_iov = &msg_iov;
185  msg.msg_iovlen = 1;
186
187  int ret = recvmsg(sock, &msg, 0 /* flags */);
188
189  struct cmsghdr *cmsg = CMSG_FIRSTHDR(&msg);
190  if (cmsg->cmsg_level == SOL_TLS &&
191      cmsg->cmsg_type == TLS_GET_RECORD_TYPE) {
192      int record_type = *((unsigned char *)CMSG_DATA(cmsg));
193      // Do something with record_type, and control message data in
194      // buffer.
195      //
196      // Note that record_type may be == to application data (23).
197  } else {
198      // Buffer contains application data.
199  }
200
201recv will never return data from mixed types of TLS records.
202
203Integrating in to userspace TLS library
204---------------------------------------
205
206At a high level, the kernel TLS ULP is a replacement for the record
207layer of a userspace TLS library.
208
209A patchset to OpenSSL to use ktls as the record layer is
210`here <https://github.com/Mellanox/openssl/commits/tls_rx2>`_.
211
212`An example <https://github.com/ktls/af_ktls-tool/commits/RX>`_
213of calling send directly after a handshake using gnutls.
214Since it doesn't implement a full record layer, control
215messages are not supported.
216
217Optional optimizations
218----------------------
219
220There are certain condition-specific optimizations the TLS ULP can make,
221if requested. Those optimizations are either not universally beneficial
222or may impact correctness, hence they require an opt-in.
223All options are set per-socket using setsockopt(), and their
224state can be checked using getsockopt() and via socket diag (``ss``).
225
226TLS_TX_ZEROCOPY_RO
227~~~~~~~~~~~~~~~~~~
228
229For device offload only. Allow sendfile() data to be transmitted directly
230to the NIC without making an in-kernel copy. This allows true zero-copy
231behavior when device offload is enabled.
232
233The application must make sure that the data is not modified between being
234submitted and transmission completing. In other words this is mostly
235applicable if the data sent on a socket via sendfile() is read-only.
236
237Modifying the data may result in different versions of the data being used
238for the original TCP transmission and TCP retransmissions. To the receiver
239this will look like TLS records had been tampered with and will result
240in record authentication failures.
241
242TLS_RX_EXPECT_NO_PAD
243~~~~~~~~~~~~~~~~~~~~
244
245TLS 1.3 only. Expect the sender to not pad records. This allows the data
246to be decrypted directly into user space buffers with TLS 1.3.
247
248This optimization is safe to enable only if the remote end is trusted,
249otherwise it is an attack vector to doubling the TLS processing cost.
250
251If the record decrypted turns out to had been padded or is not a data
252record it will be decrypted again into a kernel buffer without zero copy.
253Such events are counted in the ``TlsDecryptRetry`` statistic.
254
255Statistics
256==========
257
258TLS implementation exposes the following per-namespace statistics
259(``/proc/net/tls_stat``):
260
261- ``TlsCurrTxSw``, ``TlsCurrRxSw`` -
262  number of TX and RX sessions currently installed where host handles
263  cryptography
264
265- ``TlsCurrTxDevice``, ``TlsCurrRxDevice`` -
266  number of TX and RX sessions currently installed where NIC handles
267  cryptography
268
269- ``TlsTxSw``, ``TlsRxSw`` -
270  number of TX and RX sessions opened with host cryptography
271
272- ``TlsTxDevice``, ``TlsRxDevice`` -
273  number of TX and RX sessions opened with NIC cryptography
274
275- ``TlsDecryptError`` -
276  record decryption failed (e.g. due to incorrect authentication tag)
277
278- ``TlsDeviceRxResync`` -
279  number of RX resyncs sent to NICs handling cryptography
280
281- ``TlsDecryptRetry`` -
282  number of RX records which had to be re-decrypted due to
283  ``TLS_RX_EXPECT_NO_PAD`` mis-prediction. Note that this counter will
284  also increment for non-data records.
285