]>
Commit | Line | Data |
---|---|---|
ec279ac2 HL |
1 | /* |
2 | * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved. | |
3 | * | |
4 | * Licensed under the Apache License 2.0 (the "License"). You may not use | |
5 | * this file except in compliance with the License. You can obtain a copy | |
6 | * in the file LICENSE in the source distribution or at | |
7 | * https://www.openssl.org/source/license.html | |
8 | */ | |
9 | ||
10 | #ifndef OSSL_QUIC_RECORD_UTIL_H | |
11 | # define OSSL_QUIC_RECORD_UTIL_H | |
12 | ||
13 | # include <openssl/ssl.h> | |
19571483 HL |
14 | # include "internal/quic_types.h" |
15 | ||
16 | struct ossl_qrx_st; | |
17 | struct ossl_qtx_st; | |
ec279ac2 HL |
18 | |
19 | /* | |
20 | * QUIC Key Derivation Utilities | |
21 | * ============================= | |
22 | */ | |
23 | ||
24 | /* HKDF-Extract(salt, IKM) (RFC 5869) */ | |
25 | int ossl_quic_hkdf_extract(OSSL_LIB_CTX *libctx, | |
26 | const char *propq, | |
27 | const EVP_MD *md, | |
28 | const unsigned char *salt, size_t salt_len, | |
29 | const unsigned char *ikm, size_t ikm_len, | |
30 | unsigned char *out, size_t out_len); | |
31 | ||
19571483 HL |
32 | /* |
33 | * A QUIC client sends its first INITIAL packet with a random DCID, which | |
34 | * is used to compute the secrets used for INITIAL packet encryption in both | |
35 | * directions (both client-to-server and server-to-client). | |
36 | * | |
37 | * This function performs the necessary DCID-based key derivation, and then | |
38 | * provides the derived key material for the INITIAL encryption level to a QRX | |
39 | * instance, a QTX instance, or both. | |
40 | * | |
41 | * This function derives the necessary key material and then: | |
42 | * - if qrx is non-NULL, provides the appropriate secret to it; | |
43 | * - if qtx is non-NULL, provides the appropriate secret to it. | |
44 | * | |
45 | * If both qrx and qtx are NULL, this is a no-op. This function is equivalent to | |
46 | * making the appropriate calls to ossl_qrx_provide_secret() and | |
47 | * ossl_qtx_provide_secret(). | |
48 | * | |
49 | * It is possible to use a QRX or QTX without ever calling this, for example if | |
50 | * there is no desire to handle INITIAL packets (e.g. if a QRX/QTX is | |
51 | * instantiated to succeed a previous QRX/QTX and handle a connection which is | |
52 | * already established). However in this case you should make sure you call | |
53 | * ossl_qrx_discard_enc_level(); see the header for that function for more | |
54 | * details. Calling ossl_qtx_discard_enc_level() is not essential but could | |
55 | * protect against programming errors. | |
56 | * | |
57 | * Returns 1 on success or 0 on error. | |
58 | */ | |
59 | int ossl_quic_provide_initial_secret(OSSL_LIB_CTX *libctx, | |
60 | const char *propq, | |
61 | const QUIC_CONN_ID *dst_conn_id, | |
62 | int is_server, | |
63 | struct ossl_qrx_st *qrx, | |
64 | struct ossl_qtx_st *qtx); | |
65 | ||
ec279ac2 HL |
66 | /* |
67 | * QUIC Record Layer Ciphersuite Info | |
68 | * ================================== | |
69 | */ | |
70 | ||
71 | /* Available QUIC Record Layer (QRL) ciphersuites. */ | |
72 | # define QRL_SUITE_AES128GCM 1 /* SHA256 */ | |
73 | # define QRL_SUITE_AES256GCM 2 /* SHA384 */ | |
74 | # define QRL_SUITE_CHACHA20POLY1305 3 /* SHA256 */ | |
75 | ||
76 | /* Returns cipher name in bytes or NULL if suite ID is invalid. */ | |
77 | const char *ossl_qrl_get_suite_cipher_name(uint32_t suite_id); | |
78 | ||
79 | /* Returns hash function name in bytes or NULL if suite ID is invalid. */ | |
80 | const char *ossl_qrl_get_suite_md_name(uint32_t suite_id); | |
81 | ||
82 | /* Returns secret length in bytes or 0 if suite ID is invalid. */ | |
83 | uint32_t ossl_qrl_get_suite_secret_len(uint32_t suite_id); | |
84 | ||
85 | /* Returns key length in bytes or 0 if suite ID is invalid. */ | |
86 | uint32_t ossl_qrl_get_suite_cipher_key_len(uint32_t suite_id); | |
87 | ||
88 | /* Returns IV length in bytes or 0 if suite ID is invalid. */ | |
89 | uint32_t ossl_qrl_get_suite_cipher_iv_len(uint32_t suite_id); | |
90 | ||
91 | /* Returns AEAD auth tag length in bytes or 0 if suite ID is invalid. */ | |
92 | uint32_t ossl_qrl_get_suite_cipher_tag_len(uint32_t suite_id); | |
93 | ||
94 | /* Returns a QUIC_HDR_PROT_CIPHER_* value or 0 if suite ID is invalid. */ | |
95 | uint32_t ossl_qrl_get_suite_hdr_prot_cipher_id(uint32_t suite_id); | |
96 | ||
97 | /* Returns header protection key length in bytes or 0 if suite ID is invalid. */ | |
98 | uint32_t ossl_qrl_get_suite_hdr_prot_key_len(uint32_t suite_id); | |
99 | ||
19571483 HL |
100 | /* |
101 | * Returns maximum number of packets which may be safely encrypted with a suite | |
102 | * or 0 if suite ID is invalid. | |
103 | */ | |
104 | uint64_t ossl_qrl_get_suite_max_pkt(uint32_t suite_id); | |
105 | ||
106 | /* | |
107 | * Returns maximum number of RX'd packets which may safely fail AEAD decryption | |
108 | * for a given suite or 0 if suite ID is invalid. | |
109 | */ | |
110 | uint64_t ossl_qrl_get_suite_max_forged_pkt(uint32_t suite_id); | |
111 | ||
ec279ac2 | 112 | #endif |