Skip to content

Commit e776af3

Browse files
guhetierCopilot
guhetier
and
Copilot
committed
Refine keying material docs and sync API table
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent bf74583 commit e776af3

6 files changed

Lines changed: 93 additions & 31 deletions

File tree

‎docs/api/ConnectionExportKeyingMaterial.md‎

Lines changed: 15 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
ConnectionExportKeyingMaterial function
22
======
33

4-
Exports keying material derived from the connection's TLS session, as described in [RFC 5705](https://www.rfc-editor.org/rfc/rfc5705) and [RFC 8446 Section 7.5](https://www.rfc-editor.org/rfc/rfc8446#section-7.5). The exported material is bound to the TLS session and can be used by the app for its own purposes (for example, to authenticate the peer at the application layer).
4+
Exports keying material derived from the connection's TLS session, as described in [RFC 5705](https://www.rfc-editor.org/rfc/rfc5705) and [RFC 8446 Section 7.5](https://www.rfc-editor.org/rfc/rfc8446#section-7.5).
5+
The exported material is bound to the TLS session and can be used by the app for its own purposes (for example, to authenticate the peer at the application layer).
56

6-
> **Note** - This is a preview API and is only available when the library is built with `QUIC_API_ENABLE_PREVIEW_FEATURES`. It is available from v2.6.
7+
> **Note** - This API is in [preview](../PreviewFeatures.md). It should be considered unstable and can be subject to breaking changes.
78
89
# Syntax
910

@@ -39,38 +40,24 @@ The function returns a [QUIC_STATUS](QUIC_STATUS.md). The app may use `QUIC_FAIL
3940
4041
The following errors are the most likely to be returned:
4142
42-
`QUIC_STATUS_SUCCESS`
43-
44-
The keying material was exported into `Output`.
45-
46-
`QUIC_STATUS_INVALID_PARAMETER`
47-
48-
`Config`, `Config->Label`, or `Output` is NULL; `Config->OutputLength` is 0; `Config->Context` is NULL while `Config->ContextLength` is non-zero; or `Connection` is not a connection handle.
49-
50-
`QUIC_STATUS_INVALID_STATE`
51-
52-
The connection's TLS context is no longer available. This happens if the handshake has not completed yet, or if it has already been released after handshake completion (see Remarks).
53-
54-
`QUIC_STATUS_NOT_SUPPORTED`
55-
56-
The underlying TLS provider does not support exporting keying material. This is the case in kernel mode.
43+
Value | Meaning
44+
--- | ---
45+
**QUIC_STATUS_SUCCESS** | The keying material was exported into `Output`.
46+
**QUIC_STATUS_INVALID_PARAMETER** | `Config`, `Config->Label`, or `Output` is NULL; `Config->OutputLength` is 0; `Config->Context` is NULL while `Config->ContextLength` is non-zero; or `Connection` is not a connection handle.
47+
**QUIC_STATUS_INVALID_STATE** | The connection's TLS context is no longer available. This happens if the handshake has not completed yet, or if it has already been released after handshake completion (see Remarks).
48+
**QUIC_STATUS_NOT_SUPPORTED** | The underlying TLS provider does not support exporting keying material. This is the case in kernel mode.
5749
5850
# Remarks
5951
60-
The keying material can only be exported while the connection's TLS context is alive. The context is created during the handshake and, when session resumption is disabled, is released shortly after the handshake completes (once the handshake `CRYPTO` data is fully acknowledged), mirroring the behavior of `QUIC_PARAM_TLS_HANDSHAKE_INFO`.
61-
62-
The guaranteed-safe window to call this API is inline while handling the `QUIC_CONNECTION_EVENT_CONNECTED` event. Calling it later may return `QUIC_STATUS_INVALID_STATE` if the context has already been released.
63-
64-
The call is blocking. When invoked from the connection's worker thread (for example, inline in a connection event callback) it executes synchronously; otherwise it is queued to the connection's worker and the calling thread blocks until the operation completes.
52+
The keying material can only be exported once the handshake is completed and while the connection's TLS context is alive.
53+
On a server, the TLS context is is released shortly after the handshake completes (unless resumption tickets are used)
6554
66-
Both peers of a connection derive identical keying material for the same `Label` and `Context`. Different labels or contexts produce independent, unrelated material.
55+
This API is best called inline while handling the `QUIC_CONNECTION_EVENT_CONNECTED` event to ensure the TLS context is still alive.
56+
Calling it later may return `QUIC_STATUS_INVALID_STATE` if the context has already been released.
6757
68-
This API is only supported by the user-mode TLS providers (Schannel and OpenSSL/quictls). In kernel mode it returns `QUIC_STATUS_NOT_SUPPORTED`.
58+
This API is not supported for Windows Kernel Mode, where it returns `QUIC_STATUS_NOT_SUPPORTED`.
6959
7060
# See Also
7161
7262
[QUIC_KEYING_MATERIAL_CONFIG](QUIC_KEYING_MATERIAL_CONFIG.md)<br>
73-
[QUIC_CONNECTION_EVENT](QUIC_CONNECTION_EVENT.md)<br>
74-
[ConnectionOpen](ConnectionOpen.md)<br>
75-
[ConnectionStart](ConnectionStart.md)<br>
76-
[ConnectionClose](ConnectionClose.md)<br>
63+
[QUIC_CONNECTION_EVENT](QUIC_CONNECTION_EVENT.md)<br>

‎docs/api/ExecutionCreate.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
ExecutionCreate function
2+
======
3+
4+
TODO
5+
6+
# See Also
7+
8+
[QUIC_API_TABLE](QUIC_API_TABLE.md)<br>

‎docs/api/ExecutionDelete.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
ExecutionDelete function
2+
======
3+
4+
TODO
5+
6+
# See Also
7+
8+
[QUIC_API_TABLE](QUIC_API_TABLE.md)<br>

‎docs/api/ExecutionPoll.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
ExecutionPoll function
2+
======
3+
4+
TODO
5+
6+
# See Also
7+
8+
[QUIC_API_TABLE](QUIC_API_TABLE.md)<br>

‎docs/api/QUIC_API_TABLE.md‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,29 @@ typedef struct QUIC_API_TABLE {
4747

4848
QUIC_DATAGRAM_SEND_FN DatagramSend;
4949

50+
QUIC_CONNECTION_COMP_RESUMPTION_FN ConnectionResumptionTicketValidationComplete; // Available from v2.2
51+
QUIC_CONNECTION_COMP_CERT_FN ConnectionCertificateValidationComplete; // Available from v2.2
52+
53+
QUIC_CONNECTION_OPEN_IN_PARTITION_FN
54+
ConnectionOpenInPartition; // Available from v2.5
55+
5056
#ifdef QUIC_API_ENABLE_PREVIEW_FEATURES
57+
QUIC_STREAM_PROVIDE_RECEIVE_BUFFERS_FN
58+
StreamProvideReceiveBuffers; // Available from v2.5
59+
60+
QUIC_CONN_POOL_CREATE_FN ConnectionPoolCreate; // Available from v2.5
61+
62+
#ifndef _KERNEL_MODE
63+
#define QUIC_API_EXECUTION_CONTEXT
64+
QUIC_EXECUTION_CREATE_FN ExecutionCreate; // Available from v2.5
65+
QUIC_EXECUTION_DELETE_FN ExecutionDelete; // Available from v2.5
66+
QUIC_EXECUTION_POLL_FN ExecutionPoll; // Available from v2.5
67+
#endif // _KERNEL_MODE
68+
QUIC_REGISTRATION_CLOSE2_FN RegistrationClose2; // Available from v2.6
69+
5170
QUIC_CONNECTION_EXPORT_KEYING_MATERIAL_FN
5271
ConnectionExportKeyingMaterial; // Available from v2.6
53-
#endif
72+
#endif // QUIC_API_ENABLE_PREVIEW_FEATURES
5473

5574
} QUIC_API_TABLE;
5675
```
@@ -177,9 +196,41 @@ See [StreamReceiveSetEnabled](StreamReceiveSetEnabled.md)
177196

178197
See [DatagramSend](DatagramSend.md)
179198

199+
`ConnectionResumptionTicketValidationComplete`
200+
201+
See [ConnectionResumptionTicketValidationComplete](ConnectionResumptionTicketValidationComplete.md)
202+
203+
`ConnectionCertificateValidationComplete`
204+
205+
See [ConnectionCertificateValidationComplete](ConnectionCertificateValidationComplete.md)
206+
207+
`ConnectionOpenInPartition`
208+
209+
See [ConnectionOpenInPartition](ConnectionOpenInPartition.md)
210+
211+
`StreamProvideReceiveBuffers`
212+
213+
See (Preview) [StreamProvideReceiveBuffers](StreamProvideReceiveBuffers.md)
214+
215+
`ConnectionPoolCreate`
216+
217+
See (Preview) [ConnectionPoolCreate](ConnectionPoolCreate.md)
218+
219+
`ExecutionCreate`
220+
221+
See (Preview) [ExecutionCreate](ExecutionCreate.md)
222+
223+
`ExecutionDelete`
224+
225+
See (Preview) [ExecutionDelete](ExecutionDelete.md)
226+
227+
`ExecutionPoll`
228+
229+
See (Preview) [ExecutionPoll](ExecutionPoll.md)
230+
180231
`ConnectionExportKeyingMaterial`
181232

182-
See [ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md)
233+
See (Preview) [ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md)
183234

184235
# See Also
185236

‎docs/api/QUIC_KEYING_MATERIAL_CONFIG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ QUIC_KEYING_MATERIAL_CONFIG structure
33

44
The structure used to configure a call to [ConnectionExportKeyingMaterial](ConnectionExportKeyingMaterial.md).
55

6-
> **Note** - This is a preview structure and is only available when the library is built with `QUIC_API_ENABLE_PREVIEW_FEATURES`. It is available from v2.6.
6+
> **Note** - This API is in [preview](../PreviewFeatures.md). It should be considered unstable and can be subject to breaking changes.
77
88
# Syntax
99

0 commit comments

Comments
 (0)