mirror of
https://mirrors.bfsu.edu.cn/git/linux.git
synced 2024-12-09 20:14:09 +08:00
Documentation: tls: RSTify the ktls documentation
Convert the TLS doc to RST. Use C code blocks for the code samples, and mark hyperlinks. Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com> Acked-by: Dave Watson <davejwatson@fb.com> Acked-by: Alexei Starovoitov <ast@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
parent
b0d8d4363e
commit
f3c0f3c6c2
@ -28,6 +28,7 @@ Contents:
|
||||
checksum-offloads
|
||||
segmentation-offloads
|
||||
scaling
|
||||
tls
|
||||
|
||||
.. only:: subproject
|
||||
|
||||
|
@ -1,3 +1,7 @@
|
||||
==========
|
||||
Kernel TLS
|
||||
==========
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
@ -12,6 +16,8 @@ Creating a TLS connection
|
||||
|
||||
First create a new TCP socket and set the TLS ULP.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
sock = socket(AF_INET, SOCK_STREAM, 0);
|
||||
setsockopt(sock, SOL_TCP, TCP_ULP, "tls", sizeof("tls"));
|
||||
|
||||
@ -21,6 +27,8 @@ handshake is complete, we have all the parameters required to move the
|
||||
data-path to the kernel. There is a separate socket option for moving
|
||||
the transmit and the receive into the kernel.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* From linux/tls.h */
|
||||
struct tls_crypto_info {
|
||||
unsigned short version;
|
||||
@ -58,6 +66,8 @@ After setting the TLS_TX socket option all application data sent over this
|
||||
socket is encrypted using TLS and the parameters provided in the socket option.
|
||||
For example, we can send an encrypted hello world record as follows:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
const char *msg = "hello world\n";
|
||||
send(sock, msg, strlen(msg));
|
||||
|
||||
@ -67,6 +77,8 @@ to the encrypted kernel send buffer if possible.
|
||||
The sendfile system call will send the file's data over TLS records of maximum
|
||||
length (2^14).
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
file = open(filename, O_RDONLY);
|
||||
fstat(file, &stat);
|
||||
sendfile(sock, file, &offset, stat.st_size);
|
||||
@ -89,6 +101,8 @@ After setting the TLS_RX socket option, all recv family socket calls
|
||||
are decrypted using TLS parameters provided. A full TLS record must
|
||||
be received before decryption can happen.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
char buffer[16384];
|
||||
recv(sock, buffer, 16384);
|
||||
|
||||
@ -97,12 +111,12 @@ large enough, and no additional allocations occur. If the userspace
|
||||
buffer is too small, data is decrypted in the kernel and copied to
|
||||
userspace.
|
||||
|
||||
EINVAL is returned if the TLS version in the received message does not
|
||||
``EINVAL`` is returned if the TLS version in the received message does not
|
||||
match the version passed in setsockopt.
|
||||
|
||||
EMSGSIZE is returned if the received message is too big.
|
||||
``EMSGSIZE`` is returned if the received message is too big.
|
||||
|
||||
EBADMSG is returned if decryption failed for any other reason.
|
||||
``EBADMSG`` is returned if decryption failed for any other reason.
|
||||
|
||||
Send TLS control messages
|
||||
-------------------------
|
||||
@ -113,9 +127,11 @@ These messages can be sent over the socket by providing the TLS record type
|
||||
via a CMSG. For example the following function sends @data of @length bytes
|
||||
using a record of type @record_type.
|
||||
|
||||
/* send TLS control message using record_type */
|
||||
.. code-block:: c
|
||||
|
||||
/* send TLS control message using record_type */
|
||||
static int klts_send_ctrl_message(int sock, unsigned char record_type,
|
||||
void *data, size_t length)
|
||||
void *data, size_t length)
|
||||
{
|
||||
struct msghdr msg = {0};
|
||||
int cmsg_len = sizeof(record_type);
|
||||
@ -151,6 +167,8 @@ type passed via cmsg. If no cmsg buffer is provided, an error is
|
||||
returned if a control message is received. Data messages may be
|
||||
received without a cmsg buffer set.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
char buffer[16384];
|
||||
char cmsg[CMSG_SPACE(sizeof(unsigned char))];
|
||||
struct msghdr msg = {0};
|
||||
@ -186,12 +204,10 @@ Integrating in to userspace TLS library
|
||||
At a high level, the kernel TLS ULP is a replacement for the record
|
||||
layer of a userspace TLS library.
|
||||
|
||||
A patchset to OpenSSL to use ktls as the record layer is here:
|
||||
A patchset to OpenSSL to use ktls as the record layer is
|
||||
`here <https://github.com/Mellanox/openssl/commits/tls_rx2>`_.
|
||||
|
||||
https://github.com/Mellanox/openssl/commits/tls_rx2
|
||||
|
||||
An example of calling send directly after a handshake using
|
||||
gnutls. Since it doesn't implement a full record layer, control
|
||||
messages are not supported:
|
||||
|
||||
https://github.com/ktls/af_ktls-tool/commits/RX
|
||||
`An example <https://github.com/ktls/af_ktls-tool/commits/RX>`_
|
||||
of calling send directly after a handshake using gnutls.
|
||||
Since it doesn't implement a full record layer, control
|
||||
messages are not supported.
|
Loading…
Reference in New Issue
Block a user