summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJakub Kicinski <jakub.kicinski@netronome.com>2019-05-22 03:57:13 +0200
committerDavid S. Miller <davem@davemloft.net>2019-05-22 21:18:20 +0200
commitf3c0f3c6c2013e6caa7ab9c3c6a9fb12f6832c43 (patch)
tree804dd86acd8f11cd35e086b326e5c722331369a5
parentDocumentation: net: move device drivers docs to a submenu (diff)
downloadlinux-f3c0f3c6c2013e6caa7ab9c3c6a9fb12f6832c43.tar.xz
linux-f3c0f3c6c2013e6caa7ab9c3c6a9fb12f6832c43.zip
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>
-rw-r--r--Documentation/networking/index.rst1
-rw-r--r--Documentation/networking/tls.rst (renamed from Documentation/networking/tls.txt)42
2 files changed, 30 insertions, 13 deletions
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 7a2bfad6a762..f0f97eef091c 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -28,6 +28,7 @@ Contents:
checksum-offloads
segmentation-offloads
scaling
+ tls
.. only:: subproject
diff --git a/Documentation/networking/tls.txt b/Documentation/networking/tls.rst
index 58b5ef75f1b7..482bd73f18a2 100644
--- a/Documentation/networking/tls.txt
+++ b/Documentation/networking/tls.rst
@@ -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:
-
-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:
+A patchset to OpenSSL to use ktls as the record layer is
+`here <https://github.com/Mellanox/openssl/commits/tls_rx2>`_.
-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.