mirror of
https://github.com/torvalds/linux
synced 2024-09-20 02:57:25 +00:00
tls: Add receive path documentation
Add documentation on rx path setup and cmsg interface. Signed-off-by: Dave Watson <davejwatson@fb.com> Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
parent
c46234ebb4
commit
b6c535b163
|
@ -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
|
||||||
-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.
|
||||||
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.
|
||||||
|
|
||||||
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
|
||||||
|
|
Loading…
Reference in a new issue