Date:   Wed, 15 May 2019 13:41:22 -0700
From:   Jakub Kicinski <jakub.kicinski@...ronome.com>
To:     davem@...emloft.net
Cc:     netdev@...r.kernel.org, oss-drivers@...ronome.com,
        alexei.starovoitov@...il.com, davejwatson@...com,
        john.fastabend@...il.com, vakul.garg@....com, borisp@...lanox.com,
        Jakub Kicinski <jakub.kicinski@...ronome.com>,
        Alexei Starovoitov <ast@...nel.org>
Subject: [PATCH net 2/3] 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@...ronome.com>
Acked-by: Dave Watson <davejwatson@...com>
Acked-by: Alexei Starovoitov <ast@...nel.org>
---
 Documentation/networking/index.rst            |  1 +
 Documentation/networking/{tls.txt => tls.rst} | 42 +++++++++++++------
 2 files changed, 30 insertions(+), 13 deletions(-)
 rename Documentation/networking/{tls.txt => tls.rst} (88%)

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 @@ Linux Networking Documentation
    checksum-offloads
    segmentation-offloads
    scaling
+   tls
 
 .. only::  subproject
 
diff --git a/Documentation/networking/tls.txt b/Documentation/networking/tls.rst
similarity index 88%
rename from Documentation/networking/tls.txt
rename to 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.
-- 
2.21.0

Powered by blists - more mailing lists