Home | History | Annotate | Line # | Download | only in internal 
      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