My working unpac space for OCaml projects in development
Refactor tls-ktls to use protocol-standard terminology
Rename kTLS-specific types and functions to generic protocol terminology:
- ktls_keys -> traffic_key_material
- ktls_version/ktls_cipher -> version/cipher
- client_key/iv -> client_write_key/client_write_iv
- server_key/iv -> server_write_key/server_write_iv
- client_seq/server_seq -> client_sequence/server_sequence
- ktls_keys_error -> key_material_error
This makes the TLS library's key export feature useful for any purpose
requiring access to traffic keys (kTLS, debugging, testing) rather than
being specific to kernel TLS offload.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+75
-132
+13
-13
lib/ktls/ktls.ml
+13
-13
lib/ktls/ktls.ml
···
50
50
51
51
let available () = ktls_available ()
52
52
53
-
let of_tls_state_keys (keys : Tls_ktls.Core.ktls_keys) =
54
-
let version = match keys.Tls_ktls.Core.ktls_version with
53
+
let of_traffic_key_material (keys : Tls_ktls.Core.traffic_key_material) =
54
+
let version = match keys.Tls_ktls.Core.version with
55
55
| `TLS_1_3 -> TLS_1_3
56
56
| `TLS_1_2 -> TLS_1_2
57
57
| _ -> TLS_1_2 (* Fallback, shouldn't happen with current code *)
58
58
in
59
-
let cipher = match keys.Tls_ktls.Core.ktls_cipher with
59
+
let cipher = match keys.Tls_ktls.Core.cipher with
60
60
| Tls_ktls.Ciphersuite.AES_128_GCM -> AES_GCM_128
61
61
| Tls_ktls.Ciphersuite.AES_256_GCM -> AES_GCM_256
62
62
| Tls_ktls.Ciphersuite.CHACHA20_POLY1305 -> CHACHA20_POLY1305
···
67
67
Ok {
68
68
version ;
69
69
cipher ;
70
-
client_key = keys.Tls_ktls.Core.client_key ;
71
-
client_iv = keys.Tls_ktls.Core.client_iv ;
72
-
client_seq = keys.Tls_ktls.Core.client_seq ;
73
-
server_key = keys.Tls_ktls.Core.server_key ;
74
-
server_iv = keys.Tls_ktls.Core.server_iv ;
75
-
server_seq = keys.Tls_ktls.Core.server_seq ;
70
+
client_key = keys.Tls_ktls.Core.client_write_key ;
71
+
client_iv = keys.Tls_ktls.Core.client_write_iv ;
72
+
client_seq = keys.Tls_ktls.Core.client_sequence ;
73
+
server_key = keys.Tls_ktls.Core.server_write_key ;
74
+
server_iv = keys.Tls_ktls.Core.server_write_iv ;
75
+
server_seq = keys.Tls_ktls.Core.server_sequence ;
76
76
}
77
77
78
78
let of_tls_state state =
79
-
match Tls_ktls.Engine.ktls_keys state with
79
+
match Tls_ktls.Engine.traffic_key_material state with
80
80
| Error `Not_established -> Error `Not_established
81
-
| Error `Not_aead -> Error `Not_aead
82
-
| Error `Unsupported_cipher -> Error `Unsupported_cipher
83
-
| Ok keys -> of_tls_state_keys keys
81
+
| Error `Tls12_no_support -> Error `Not_aead
82
+
| Error `No_aead -> Error `Not_aead
83
+
| Ok keys -> of_traffic_key_material keys
84
84
85
85
(* Get the raw file descriptor integer from Unix.file_descr *)
86
86
external fd_to_int : Unix.file_descr -> int = "%identity"
+4
-4
lib/ktls/ktls.mli
+4
-4
lib/ktls/ktls.mli
···
66
66
val of_tls_state : Tls_ktls.Engine.state ->
67
67
(t, [> `Not_established | `Not_aead | `Unsupported_cipher ]) result
68
68
69
-
(** [of_tls_state_keys keys] converts pre-extracted kTLS keys to the
70
-
kTLS configuration type. This is useful when you already have the
71
-
keys from {!Tls_ktls.Engine.ktls_keys}. *)
72
-
val of_tls_state_keys : Tls_ktls.Core.ktls_keys -> (t, error) result
69
+
(** [of_traffic_key_material keys] converts pre-extracted traffic key material
70
+
to the kTLS configuration type. This is useful when you already have the
71
+
keys from {!Tls_ktls.Engine.traffic_key_material}. *)
72
+
val of_traffic_key_material : Tls_ktls.Core.traffic_key_material -> (t, error) result
73
73
74
74
(** {1 Configuration} *)
75
75
-60
lib/ktls/ktls_stubs.c
-60
lib/ktls/ktls_stubs.c
···
16
16
#include <netinet/in.h>
17
17
#include <netinet/tcp.h>
18
18
19
-
/* Linux kTLS headers */
20
-
#ifdef __linux__
21
19
#include <linux/tls.h>
22
-
#else
23
-
/* Stub definitions for non-Linux platforms */
24
-
#define SOL_TLS 282
25
-
#define TCP_ULP 31
26
-
#define TLS_TX 1
27
-
#define TLS_RX 2
28
-
#define TLS_1_2_VERSION 0x0303
29
-
#define TLS_1_3_VERSION 0x0304
30
-
#define TLS_CIPHER_AES_GCM_128 51
31
-
#define TLS_CIPHER_AES_GCM_256 52
32
-
#define TLS_CIPHER_CHACHA20_POLY1305 54
33
-
34
-
#define TLS_CIPHER_AES_GCM_128_IV_SIZE 8
35
-
#define TLS_CIPHER_AES_GCM_128_KEY_SIZE 16
36
-
#define TLS_CIPHER_AES_GCM_128_SALT_SIZE 4
37
-
#define TLS_CIPHER_AES_GCM_128_TAG_SIZE 16
38
-
#define TLS_CIPHER_AES_GCM_128_REC_SEQ_SIZE 8
39
-
40
-
#define TLS_CIPHER_AES_GCM_256_IV_SIZE 8
41
-
#define TLS_CIPHER_AES_GCM_256_KEY_SIZE 32
42
-
#define TLS_CIPHER_AES_GCM_256_SALT_SIZE 4
43
-
#define TLS_CIPHER_AES_GCM_256_TAG_SIZE 16
44
-
#define TLS_CIPHER_AES_GCM_256_REC_SEQ_SIZE 8
45
-
46
-
#define TLS_CIPHER_CHACHA20_POLY1305_IV_SIZE 12
47
-
#define TLS_CIPHER_CHACHA20_POLY1305_KEY_SIZE 32
48
-
#define TLS_CIPHER_CHACHA20_POLY1305_SALT_SIZE 0
49
-
#define TLS_CIPHER_CHACHA20_POLY1305_TAG_SIZE 16
50
-
#define TLS_CIPHER_CHACHA20_POLY1305_REC_SEQ_SIZE 8
51
-
52
-
struct tls_crypto_info {
53
-
unsigned short version;
54
-
unsigned short cipher_type;
55
-
};
56
-
57
-
struct tls12_crypto_info_aes_gcm_128 {
58
-
struct tls_crypto_info info;
59
-
unsigned char iv[TLS_CIPHER_AES_GCM_128_IV_SIZE];
60
-
unsigned char key[TLS_CIPHER_AES_GCM_128_KEY_SIZE];
61
-
unsigned char salt[TLS_CIPHER_AES_GCM_128_SALT_SIZE];
62
-
unsigned char rec_seq[TLS_CIPHER_AES_GCM_128_REC_SEQ_SIZE];
63
-
};
64
-
65
-
struct tls12_crypto_info_aes_gcm_256 {
66
-
struct tls_crypto_info info;
67
-
unsigned char iv[TLS_CIPHER_AES_GCM_256_IV_SIZE];
68
-
unsigned char key[TLS_CIPHER_AES_GCM_256_KEY_SIZE];
69
-
unsigned char salt[TLS_CIPHER_AES_GCM_256_SALT_SIZE];
70
-
unsigned char rec_seq[TLS_CIPHER_AES_GCM_256_REC_SEQ_SIZE];
71
-
};
72
-
73
-
struct tls12_crypto_info_chacha20_poly1305 {
74
-
struct tls_crypto_info info;
75
-
unsigned char iv[TLS_CIPHER_CHACHA20_POLY1305_IV_SIZE];
76
-
unsigned char key[TLS_CIPHER_CHACHA20_POLY1305_KEY_SIZE];
77
-
unsigned char rec_seq[TLS_CIPHER_CHACHA20_POLY1305_REC_SEQ_SIZE];
78
-
};
79
-
#endif
80
20
81
21
/* Check if kTLS is available on this system */
82
22
CAMLprim value caml_ktls_available(value unit)
+2
-2
lib/ktls_eio/ktls_eio.ml
+2
-2
lib/ktls_eio/ktls_eio.ml
···
20
20
Eio_unix.Resource.fd_opt flow
21
21
22
22
let enable_ktls ~role tls_flow =
23
-
match Tls_eio.ktls_keys tls_flow with
23
+
match Tls_eio.traffic_key_material tls_flow with
24
24
| Error _ -> None
25
25
| Ok keys ->
26
-
match Ktls.of_tls_state_keys keys with
26
+
match Ktls.of_traffic_key_material keys with
27
27
| Error _ -> None
28
28
| Ok ktls_cfg ->
29
29
let underlying = Tls_eio.underlying_flow tls_flow in
+3
-3
vendor/opam/tls-ktls/eio/tls_eio.ml
+3
-3
vendor/opam/tls-ktls/eio/tls_eio.ml
···
241
241
let key_update ?request (t:t) = Raw.key_update ?request (raw t)
242
242
let epoch (t:t) = Raw.epoch (raw t)
243
243
244
-
(* kTLS support *)
245
-
let ktls_keys (t:t) =
244
+
(* Traffic key material extraction *)
245
+
let traffic_key_material (t:t) =
246
246
let r = raw t in
247
247
match r.Raw.state with
248
-
| `Active tls | `Read_closed tls | `Write_closed tls -> Tls_ktls.Engine.ktls_keys tls
248
+
| `Active tls | `Read_closed tls | `Write_closed tls -> Tls_ktls.Engine.traffic_key_material tls
249
249
| `Closed | `Error _ -> Error `Not_established
250
250
251
251
let underlying_flow (t:t) = (raw t).Raw.flow
+5
-3
vendor/opam/tls-ktls/eio/tls_eio.mli
+5
-3
vendor/opam/tls-ktls/eio/tls_eio.mli
···
58
58
active session. *)
59
59
val epoch : t -> (Tls_ktls.Core.epoch_data, unit) result
60
60
61
-
(** {2 kTLS support} *)
61
+
(** {2 Traffic key material} *)
62
62
63
-
(** [ktls_keys t] extracts the raw traffic keys needed for kernel TLS offload.
63
+
(** [traffic_key_material t] extracts the derived traffic keys, IVs, and current
64
+
sequence numbers for the TLS 1.3 connection. Useful for kernel TLS offload,
65
+
debugging, or other scenarios requiring access to the symmetric key material.
64
66
Returns [Error `Not_established] if the handshake is not complete. *)
65
-
val ktls_keys : t -> (Tls_ktls.Core.ktls_keys, Tls_ktls.Engine.ktls_keys_error) result
67
+
val traffic_key_material : t -> (Tls_ktls.Core.traffic_key_material, Tls_ktls.Engine.key_material_error) result
66
68
67
69
(** [underlying_flow t] returns the underlying Eio flow (socket) that this TLS
68
70
session wraps. This is useful for enabling kTLS on the socket. *)
+13
-12
vendor/opam/tls-ktls/lib/core.ml
+13
-12
vendor/opam/tls-ktls/lib/core.ml
···
490
490
tls_unique : string option ;
491
491
}
492
492
493
-
(** Key material for kernel TLS (kTLS) offload.
494
-
Contains the symmetric keys, IVs, and sequence numbers needed
495
-
to configure kernel TLS after userspace handshake completion. *)
496
-
type ktls_keys = {
497
-
ktls_version : tls_version ;
498
-
ktls_cipher : Ciphersuite.aead_cipher ;
499
-
client_key : string ;
500
-
client_iv : string ;
501
-
client_seq : int64 ;
502
-
server_key : string ;
503
-
server_iv : string ;
504
-
server_seq : int64 ;
493
+
(** Traffic key material for TLS 1.3 connections.
494
+
Contains the derived write keys, IVs, and current sequence numbers
495
+
for both client and server directions. Useful for kernel offload
496
+
(kTLS), debugging, or other scenarios requiring access to traffic keys. *)
497
+
type traffic_key_material = {
498
+
version : tls_version ;
499
+
cipher : Ciphersuite.aead_cipher ;
500
+
client_write_key : string ;
501
+
client_write_iv : string ;
502
+
client_sequence : int64 ;
503
+
server_write_key : string ;
504
+
server_write_iv : string ;
505
+
server_sequence : int64 ;
505
506
}
506
507
507
508
let supports_key_usage ?(not_present = false) usage cert =
+13
-13
vendor/opam/tls-ktls/lib/engine.ml
+13
-13
vendor/opam/tls-ktls/lib/engine.ml
···
760
760
| _, None -> Error (`Msg "couldn't find a tls-unique in the session data")
761
761
| _, Some data -> Ok data
762
762
763
-
type ktls_keys_error = [ `Not_established | `Not_aead | `Unsupported_cipher ]
763
+
type key_material_error = [ `Not_established | `Tls12_no_support | `No_aead ]
764
764
765
-
let ktls_keys state =
765
+
let traffic_key_material state =
766
766
match state.handshake.session with
767
767
| `TLS13 session :: _ ->
768
768
let cipher = session.ciphersuite13 in
···
783
783
in
784
784
(* For server: encryptor uses server keys, decryptor uses client keys
785
785
For client: encryptor uses client keys, decryptor uses server keys *)
786
-
let client_seq, server_seq =
786
+
let client_sequence, server_sequence =
787
787
if is_server then (dec_seq, enc_seq) else (enc_seq, dec_seq)
788
788
in
789
789
Ok {
790
-
ktls_version = `TLS_1_3 ;
791
-
ktls_cipher = aead ;
792
-
client_key = session.client_traffic_key ;
793
-
client_iv = session.client_traffic_iv ;
794
-
client_seq ;
795
-
server_key = session.server_traffic_key ;
796
-
server_iv = session.server_traffic_iv ;
797
-
server_seq ;
790
+
Core.version = `TLS_1_3 ;
791
+
cipher = aead ;
792
+
client_write_key = session.client_write_key ;
793
+
client_write_iv = session.client_write_iv ;
794
+
client_sequence ;
795
+
server_write_key = session.server_write_key ;
796
+
server_write_iv = session.server_write_iv ;
797
+
server_sequence ;
798
798
}
799
799
| `TLS _session :: _ ->
800
-
(* TLS 1.2 with AEAD - would need additional work to extract keys *)
801
-
Error `Not_aead
800
+
(* TLS 1.2 - would need additional work to extract keys *)
801
+
Error `Tls12_no_support
802
802
| [] ->
803
803
Error `Not_established
+9
-9
vendor/opam/tls-ktls/lib/engine.mli
+9
-9
vendor/opam/tls-ktls/lib/engine.mli
···
171
171
[ `Tls_exporter | `Tls_unique | `Tls_server_endpoint ] ->
172
172
(string, [ `Msg of string ]) result
173
173
174
-
(** {1 Kernel TLS offload} *)
174
+
(** {1 Traffic Key Material} *)
175
175
176
-
(** Errors that can occur when extracting kTLS keys *)
177
-
type ktls_keys_error = [ `Not_established | `Not_aead | `Unsupported_cipher ]
176
+
(** Errors that can occur when extracting traffic key material *)
177
+
type key_material_error = [ `Not_established | `Tls12_no_support | `No_aead ]
178
178
179
-
(** [ktls_keys state] extracts the raw traffic keys, IVs, and sequence numbers
180
-
needed for Linux kernel TLS (kTLS) offload. This allows the kernel to handle
181
-
TLS record-layer encryption/decryption after the handshake is complete.
179
+
(** [traffic_key_material state] extracts the derived traffic keys, IVs, and
180
+
current sequence numbers for an established TLS 1.3 connection. This is
181
+
useful for kernel TLS offload (kTLS), debugging, or other scenarios
182
+
requiring access to the symmetric key material.
182
183
183
184
Returns [Error `Not_established] if the handshake is not complete.
184
-
Returns [Error `Not_aead] if the cipher is not AEAD (only TLS 1.3 ciphers
185
-
are currently supported). *)
186
-
val ktls_keys : state -> (Core.ktls_keys, ktls_keys_error) result
185
+
Returns [Error `Tls12_no_support] for TLS 1.2 connections (not yet supported). *)
186
+
val traffic_key_material : state -> (Core.traffic_key_material, key_material_error) result
+2
-2
vendor/opam/tls-ktls/lib/handshake_client13.ml
+2
-2
vendor/opam/tls-ktls/lib/handshake_client13.ml
···
164
164
let* () = guard (String.length state.hs_fragment = 0) (`Fatal (`Handshake `Fragments)) in
165
165
let log = log ^ raw in
166
166
let server_app_secret, server_app_ctx, client_app_secret, client_app_ctx,
167
-
(client_traffic_key, client_traffic_iv, server_traffic_key, server_traffic_iv) =
167
+
(client_write_key, client_write_iv, server_write_key, server_write_iv) =
168
168
Handshake_crypto13.app_ctx_with_keys session.master_secret log
169
169
in
170
170
let exporter_master_secret = Handshake_crypto13.exporter session.master_secret log in
···
209
209
let resumption_secret = Handshake_crypto13.resumption session.master_secret (log ^ mfin) in
210
210
let session = { session with
211
211
resumption_secret ; exporter_master_secret ; client_app_secret ; server_app_secret ;
212
-
client_traffic_key ; client_traffic_iv ; server_traffic_key ; server_traffic_iv
212
+
client_write_key ; client_write_iv ; server_write_key ; server_write_iv
213
213
} in
214
214
let machina = Client13 Established13 in
215
215
+4
-4
vendor/opam/tls-ktls/lib/handshake_common.ml
+4
-4
vendor/opam/tls-ktls/lib/handshake_common.ml
···
137
137
resumed = false ;
138
138
client_app_secret = "" ;
139
139
server_app_secret = "" ;
140
-
client_traffic_key = "" ;
141
-
client_traffic_iv = "" ;
142
-
server_traffic_key = "" ;
143
-
server_traffic_iv = "" ;
140
+
client_write_key = "" ;
141
+
client_write_iv = "" ;
142
+
server_write_key = "" ;
143
+
server_write_iv = "" ;
144
144
}
145
145
146
146
let common_session_data_of_epoch (epoch : epoch_data) common_session_data =
+2
-2
vendor/opam/tls-ktls/lib/handshake_server13.ml
+2
-2
vendor/opam/tls-ktls/lib/handshake_server13.ml
···
315
315
316
316
let log = log ^ fin_raw in
317
317
let server_app_secret, server_app_ctx, client_app_secret, client_app_ctx,
318
-
(client_traffic_key, client_traffic_iv, server_traffic_key, server_traffic_iv) =
318
+
(client_write_key, client_write_iv, server_write_key, server_write_iv) =
319
319
app_ctx_with_keys master_secret log
320
320
in
321
321
let exporter_master_secret = Handshake_crypto13.exporter master_secret log in
322
322
let session' = { session' with
323
323
server_app_secret ; client_app_secret ; exporter_master_secret ;
324
-
client_traffic_key ; client_traffic_iv ; server_traffic_key ; server_traffic_iv
324
+
client_write_key ; client_write_iv ; server_write_key ; server_write_iv
325
325
} in
326
326
327
327
let* () =
+5
-5
vendor/opam/tls-ktls/lib/state.ml
+5
-5
vendor/opam/tls-ktls/lib/state.ml
···
130
130
resumed : bool ;
131
131
client_app_secret : string ;
132
132
server_app_secret : string ;
133
-
(* Raw traffic keys for kTLS offload *)
134
-
client_traffic_key : string ;
135
-
client_traffic_iv : string ;
136
-
server_traffic_key : string ;
137
-
server_traffic_iv : string ;
133
+
(* Derived traffic keys (from HKDF-Expand-Label) *)
134
+
client_write_key : string ;
135
+
client_write_iv : string ;
136
+
server_write_key : string ;
137
+
server_write_iv : string ;
138
138
}
139
139
140
140
type client13_handshake_state =