From Fedora Project Wiki
(Add trackers)
(deferred to F41 per https://bugzilla.redhat.com/show_bug.cgi?id=2130000#c8)
 
(4 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= KTLS implementation for GnuTLS <!-- The name of your change proposal --> =
= KTLS implementation for GnuTLS <!-- The name of your change proposal --> =
{{admon/important|kTLS now disabled by default| see the rationale for this decision [https://pagure.io/fesco/issue/2871#comment-824428 here].}}


== Summary ==
== Summary ==
Line 12: Line 13:


== Current status ==
== Current status ==
[[Category:ChangeAcceptedF38]]
[[Category:ChangeAcceptedF41]]
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
Line 21: Line 22:
[[Category:SystemWideChange]]
[[Category:SystemWideChange]]


* Targeted release: [[Releases/38 | Fedora Linux 38 ]]  
* Targeted release: [[Releases/41 | Fedora Linux 41 ]]  
* Last updated: <!-- this is an automatic macro — you don't need to change this line -->  {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}  
* Last updated: <!-- this is an automatic macro — you don't need to change this line -->  {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}  
<!-- After the change proposal is accepted by FESCo, tracking bug is created in Bugzilla and linked to this page  
<!-- After the change proposal is accepted by FESCo, tracking bug is created in Bugzilla and linked to this page  
Line 37: Line 38:
The goal of this change is to provide GnuTLS users with a high throughput data transfer mechanism on encrypted channels, with emphasis on ''network block devices'' (NBD).
The goal of this change is to provide GnuTLS users with a high throughput data transfer mechanism on encrypted channels, with emphasis on ''network block devices'' (NBD).


We accomplish this with KTLS which offloads enc/decryption (TLS record) to the kernel, while GnuTLS handles initial connection (TLS handshake).
We accomplish this with kTLS which offloads enc/decryption (TLS record) to the kernel, while GnuTLS handles initial connection (TLS handshake).


GNUTLS will detect whether the kernel supports kTLS and will automatically enable its usage when compatible. Any package built against GNUTLS, is likely to see some performance benefit from kTLS, provided it has not installed custom push/pull I/O function callbacks.
<strike>GNUTLS will detect whether the kernel supports kTLS and will automatically enable its usage when compatible</strike>
</br>kTLS will be disabled by default and enabled with the following [https://fedoraproject.org/wiki/Changes/KTLSSupportForGnuTLS#How_To_Test steps]. Any package built against GNUTLS with kTLS enabled, is likely to see some performance benefit from kTLS, provided it has not installed custom push/pull I/O function callbacks.


kTLS enables a reduction in context switching and reduced data copies when using send_file(). With suitable NIC hardware the encryption operations can be offloaded, freeing time on the main CPUs for application usage. Without offload hardware, kTLS may still improve parallelism for applications as the kernel can perform encryption operations on a differen host CPU to that running the application threads
kTLS enables a reduction in context switching and reduced data copies when using send_file(). With suitable NIC hardware the encryption operations can be offloaded, freeing time on the main CPUs for application usage. Without offload hardware, kTLS may still improve parallelism for applications as the kernel can perform encryption operations on a differen host CPU to that running the application threads
Line 47: Line 49:


== Benefit to Fedora ==
== Benefit to Fedora ==
The improvement lies in acceleration of large data transfers trough encrypted channels.
The improvement lies in acceleration of large data transfers through encrypted channels.
The send_file function enables us to send data directly trough socket without entering user space, saving us from 2 context switches and 2 additional user space buffers. This is especially useful for NBD  
The send_file function enables us to send data directly through socket without entering user space, saving us from 2 context switches and 2 additional user space buffers. This is especially useful for NBD  


'''Benefits'''
'''Benefits'''
Line 58: Line 60:


== Scope ==
== Scope ==
* Proposal owners: Support for KTLS key update in GnuTLS ''track'': [https://gitlab.com/gnutls/gnutls/-/merge_requests/1625 gitlab]
* Proposal owners: Support for kTLS key update in GnuTLS ''track'': [https://gitlab.com/gnutls/gnutls/-/merge_requests/1625 gitlab]
* Other developers: Support for TLS1.3 key update in KTLS (tls kernel module)
* Other developers: Support for TLS1.3 key update in kTLS (tls kernel module)
* Release engineering: https://pagure.io/releng/issue/11016
* Release engineering: https://pagure.io/releng/issue/11016
* Policies and guidelines: not needed for this Change
* Policies and guidelines: not needed for this Change
Line 66: Line 68:


== Upgrade/compatibility impact ==
== Upgrade/compatibility impact ==
Although this feature will be enabled by default, users will not notice any change, as in case of failure to initialize KTLS, GnuTLS will fallback to the currently used mode of operation.
<strike>Although this feature will be enabled by default, users will not notice any change, as in case of failure to initialize kTLS, GnuTLS will fallback to the currently used mode of operation.</strike>
 
kTLS will be disabled by default so users will not notice any changes.
Users will be also provided with means to disable this feature trough crypto-policies


== How To Test ==
== How To Test ==
Line 74: Line 75:
# load TLS kernel module (`modprobe tls`)
# load TLS kernel module (`modprobe tls`)
# enable ktls with crypto policies  
# enable ktls with crypto policies  
{{admon/note|Once proposal accepted|KTLS will be enabled by default and this step will not be needed.}}
<pre>$ cat > /etc/crypto-policies/local.d/gnutls-ktls.config <<EOF
<pre>$ cat > /etc/crypto-policies/local.d/gnutls-ktls.config <<EOF
[global]
[global]
Line 81: Line 81:
</pre>
</pre>
<pre>$ update-crypto-policies</pre>
<pre>$ update-crypto-policies</pre>
{{admon/important||KTLS will not initialize if app uses custom push/pull callback for GnuTLS.}}
{{admon/important||kTLS will not initialize if app uses custom push/pull callback for GnuTLS.}}


== User Experience ==
== User Experience ==
Line 89: Line 89:
== Dependencies ==
== Dependencies ==


Currently '''KTLS doesn't support key_update''' (The keys delivered to the kernel can’t be set more than once per session) so a kernel module patch would be needed for this functionality.
Currently '''kTLS doesn't support key_update''' (The keys delivered to the kernel can’t be set more than once per session) so a kernel module patch would be needed for this functionality.
This not only impacts key_update invokation by user of either side, but also by [https://datatracker.ietf.org/doc/html/rfc8446#section-5.5 AES-GCM key usage limit]. As this could weaken the security of TLS protocol, GnuTLS will disable KTLS for rest of the session and fallback to default mode of operation i.e. move encryption and decryption back to usersace after the key_update is called.
This not only impacts key_update invokation by user of either side, but also by [https://datatracker.ietf.org/doc/html/rfc8446#section-5.5 AES-GCM key usage limit]. As this could weaken the security of TLS protocol, <strike> GnuTLS will disable kTLS for rest of the session and fallback to default mode of operation i.e. move encryption and decryption back to usersace </strike> GnuTLS will invalidate the session and return a error after the key_update is called.


{{admon/note|GnuTLS supports KTLS key_update| This feature is supported if apropriate kernel patch is applied}}
{{admon/note|GnuTLS supports kTLS key_update| This feature is supported if apropriate kernel patch is applied}}


== Contingency Plan ==
== Contingency Plan ==
Line 103: Line 103:
=== API ===
=== API ===
'''[https://gnutls.org/manual/gnutls.html#index-gnutls_005ftransport_005fis_005fktls_005fenabled gnutls_transport_is_ktls_enabled()]'''
'''[https://gnutls.org/manual/gnutls.html#index-gnutls_005ftransport_005fis_005fktls_005fenabled gnutls_transport_is_ktls_enabled()]'''
To check if KTLS was properly initialized on the interfaces:  
To check if kTLS was properly initialized on the interfaces:  
{{admon/important||it has to be invoked no earlier that after a TLS-handshake}}
{{admon/important||it has to be invoked no earlier that after a TLS-handshake}}
<pre> gnutls_transport_ktls_enable_flags_t gnutls_transport_is_ktls_enabled(gnutls_session_t session);</pre>
<pre> gnutls_transport_ktls_enable_flags_t gnutls_transport_is_ktls_enabled(gnutls_session_t session);</pre>
Line 109: Line 109:


'''[https://gnutls.org/manual/gnutls.html#index-gnutls_005frecord_005fsend_005ffile gnutls_record_send_file()]'''
'''[https://gnutls.org/manual/gnutls.html#index-gnutls_005frecord_005fsend_005ffile gnutls_record_send_file()]'''
To send data directly from a file descriptor in a zero-copy manner if KTLS is enabled; otherwise it will just iteratively read from the file descriptor:
To send data directly from a file descriptor in a zero-copy manner if kTLS is enabled; otherwise it will just iteratively read from the file descriptor:
<pre> ssize_t gnutls_record_send_file(gnutls_session_t session, int fd, off_t *offset, size_t count);</pre>
<pre> ssize_t gnutls_record_send_file(gnutls_session_t session, int fd, off_t *offset, size_t count);</pre>



Latest revision as of 02:49, 21 February 2024

KTLS implementation for GnuTLS

Important.png
kTLS now disabled by default
see the rationale for this decision here.

Summary

Acceleration of GnuTLS with software Kernel TLS (KTLS)

Owner

Current status

Detailed Description

The goal of this change is to provide GnuTLS users with a high throughput data transfer mechanism on encrypted channels, with emphasis on network block devices (NBD).

We accomplish this with kTLS which offloads enc/decryption (TLS record) to the kernel, while GnuTLS handles initial connection (TLS handshake).

GNUTLS will detect whether the kernel supports kTLS and will automatically enable its usage when compatible
kTLS will be disabled by default and enabled with the following steps. Any package built against GNUTLS with kTLS enabled, is likely to see some performance benefit from kTLS, provided it has not installed custom push/pull I/O function callbacks.

kTLS enables a reduction in context switching and reduced data copies when using send_file(). With suitable NIC hardware the encryption operations can be offloaded, freeing time on the main CPUs for application usage. Without offload hardware, kTLS may still improve parallelism for applications as the kernel can perform encryption operations on a differen host CPU to that running the application threads

Feedback

Benefit to Fedora

The improvement lies in acceleration of large data transfers through encrypted channels. The send_file function enables us to send data directly through socket without entering user space, saving us from 2 context switches and 2 additional user space buffers. This is especially useful for NBD

Benefits

  • Acceleration of live VM migration, which should mitigate the downtime for various services used by both the users and the developers.
  • Increased speed at which files can be retrieved from NBD via encrypted channel and less CPU and memory strain on NBD server.

packages that might benefit: Package-x-generic-16.pngnbd Package-x-generic-16.pngnbdkit Package-x-generic-16.pngqemu

Scope

  • Proposal owners: Support for kTLS key update in GnuTLS track: gitlab
  • Other developers: Support for TLS1.3 key update in kTLS (tls kernel module)
  • Release engineering: https://pagure.io/releng/issue/11016
  • Policies and guidelines: not needed for this Change
  • Trademark approval: not needed for this Change
  • Alignment with Objectives: None

Upgrade/compatibility impact

Although this feature will be enabled by default, users will not notice any change, as in case of failure to initialize kTLS, GnuTLS will fallback to the currently used mode of operation. kTLS will be disabled by default so users will not notice any changes.

How To Test

To enable this feature user has to:

  1. load TLS kernel module (modprobe tls)
  2. enable ktls with crypto policies
$ cat > /etc/crypto-policies/local.d/gnutls-ktls.config <<EOF
[global]
ktls = true
EOF
$ update-crypto-policies
Important.png
kTLS will not initialize if app uses custom push/pull callback for GnuTLS.

User Experience

This change should accelerate large data transfers especially that of files. This will affect users that use applications which utilize GnuTLS for encrypting communication channels.

Dependencies

Currently kTLS doesn't support key_update (The keys delivered to the kernel can’t be set more than once per session) so a kernel module patch would be needed for this functionality. This not only impacts key_update invokation by user of either side, but also by AES-GCM key usage limit. As this could weaken the security of TLS protocol, GnuTLS will disable kTLS for rest of the session and fallback to default mode of operation i.e. move encryption and decryption back to usersace GnuTLS will invalidate the session and return a error after the key_update is called.

Note.png
GnuTLS supports kTLS key_update
This feature is supported if apropriate kernel patch is applied

Contingency Plan

  • Contingency mechanism: Feature will be disabled by default in crypto-policies.
  • Contingency deadline: 2023-02-21
  • Blocks release? No


Documentation

API

gnutls_transport_is_ktls_enabled() To check if kTLS was properly initialized on the interfaces:

Important.png
it has to be invoked no earlier that after a TLS-handshake
 gnutls_transport_ktls_enable_flags_t gnutls_transport_is_ktls_enabled(gnutls_session_t session);


gnutls_record_send_file() To send data directly from a file descriptor in a zero-copy manner if kTLS is enabled; otherwise it will just iteratively read from the file descriptor:

 ssize_t gnutls_record_send_file(gnutls_session_t session, int fd, off_t *offset, size_t count);

Release Notes