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