Commit b6c535b1 authored by Dave Watson's avatar Dave Watson Committed by David S. Miller

tls: Add receive path documentation

Add documentation on rx path setup and cmsg interface.
Signed-off-by: default avatarDave Watson <davejwatson@fb.com>
Signed-off-by: default avatarDavid S. Miller <davem@davemloft.net>
parent c46234eb
...@@ -48,6 +48,9 @@ the transmit and the receive into the kernel. ...@@ -48,6 +48,9 @@ the transmit and the receive into the kernel.
setsockopt(sock, SOL_TLS, TLS_TX, &crypto_info, sizeof(crypto_info)); setsockopt(sock, SOL_TLS, TLS_TX, &crypto_info, sizeof(crypto_info));
Transmit and receive are set separately, but the setup is the same, using either
TLS_TX or TLS_RX.
Sending TLS application data Sending TLS application data
---------------------------- ----------------------------
...@@ -79,6 +82,28 @@ for memory), or the encryption will always succeed. If send() returns ...@@ -79,6 +82,28 @@ for memory), or the encryption will always succeed. If send() returns
-ENOMEM and some data was left on the socket buffer from a previous -ENOMEM and some data was left on the socket buffer from a previous
call using MSG_MORE, the MSG_MORE data is left on the socket buffer. call using MSG_MORE, the MSG_MORE data is left on the socket buffer.
Receiving TLS application data
------------------------------
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.
char buffer[16384];
recv(sock, buffer, 16384);
Received data is decrypted directly in to the user buffer if it is
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
match the version passed in setsockopt.
EMSGSIZE is returned if the received message is too big.
EBADMSG is returned if decryption failed for any other reason.
Send TLS control messages Send TLS control messages
------------------------- -------------------------
...@@ -118,6 +143,43 @@ using a record of type @record_type. ...@@ -118,6 +143,43 @@ using a record of type @record_type.
Control message data should be provided unencrypted, and will be Control message data should be provided unencrypted, and will be
encrypted by the kernel. encrypted by the kernel.
Receiving TLS control messages
------------------------------
TLS control messages are passed in the userspace buffer, with message
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.
char buffer[16384];
char cmsg[CMSG_SPACE(sizeof(unsigned char))];
struct msghdr msg = {0};
msg.msg_control = cmsg;
msg.msg_controllen = sizeof(cmsg);
struct iovec msg_iov;
msg_iov.iov_base = buffer;
msg_iov.iov_len = 16384;
msg.msg_iov = &msg_iov;
msg.msg_iovlen = 1;
int ret = recvmsg(sock, &msg, 0 /* flags */);
struct cmsghdr *cmsg = CMSG_FIRSTHDR(&msg);
if (cmsg->cmsg_level == SOL_TLS &&
cmsg->cmsg_type == TLS_GET_RECORD_TYPE) {
int record_type = *((unsigned char *)CMSG_DATA(cmsg));
// Do something with record_type, and control message data in
// buffer.
//
// Note that record_type may be == to application data (23).
} else {
// Buffer contains application data.
}
recv will never return data from mixed types of TLS records.
Integrating in to userspace TLS library Integrating in to userspace TLS library
--------------------------------------- ---------------------------------------
...@@ -126,10 +188,10 @@ layer of a userspace TLS library. ...@@ -126,10 +188,10 @@ 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/tls-openssl https://github.com/Mellanox/openssl/commits/tls_rx2
An example of calling send directly after a handshake using An example of calling send directly after a handshake using
gnutls. Since it doesn't implement a full record layer, control gnutls. Since it doesn't implement a full record layer, control
messages are not supported: messages are not supported:
https://github.com/Mellanox/tls-af_ktls_tool https://github.com/ktls/af_ktls-tool/commits/RX
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment