ssl/quic/quic_record_shared.h

   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_SHARED_H
  11 # define OSSL_QUIC_RECORD_SHARED_H
  12
  13 # include <openssl/ssl.h>
  14 # include "internal/quic_types.h"
  15 # include "internal/quic_wire_pkt.h"
  16
  17 /*
  18  * QUIC Record Layer EL Management Utilities
  19  * =========================================
  20  *
  21  * This defines a structure for managing the cryptographic state at a given
  22  * encryption level, as this functionality is shared between QRX and QTX. For
  23  * QRL use only.
  24  */
  25 typedef struct ossl_qrl_enc_level_st {
  26     /* Hash function used for key derivation. */
  27     EVP_MD                     *md;
  28     /* Context used for packet body ciphering. */
  29     EVP_CIPHER_CTX             *cctx;
  30     /* IV used to construct nonces used for AEAD packet body ciphering. */
  31     unsigned char               iv[EVP_MAX_IV_LENGTH];
  32     /* Have we permanently discarded this encryption level? */
  33     unsigned char               discarded;
  34     /* QRL_SUITE_* value. */
  35     uint32_t                    suite_id;
  36     /* Length of authentication tag. */
  37     uint32_t                    tag_len;
  38     /*
  39      * Cryptographic context used to apply and remove header protection from
  40      * packet headers.
  41      */
  42     QUIC_HDR_PROTECTOR          hpr;
  43     /* Usage counter. The caller maintains this. */
  44     uint64_t                    op_count;
  45 } OSSL_QRL_ENC_LEVEL;
  46
  47 typedef struct ossl_qrl_enc_level_set_st {
  48     OSSL_QRL_ENC_LEVEL el[QUIC_ENC_LEVEL_NUM];
  49 } OSSL_QRL_ENC_LEVEL_SET;
  50
  51 /*
  52  * Returns 1 if we have key material for a given encryption level, 0 if we do
  53  * not yet have material and -1 if the EL is discarded.
  54  */
  55 int ossl_qrl_enc_level_set_have_el(OSSL_QRL_ENC_LEVEL_SET *els,
  56                                    uint32_t enc_level);
  57
  58 /*
  59  * Returns EL in a set. If enc_level is not a valid QUIC_ENC_LEVEL_* value,
  60  * returns NULL. If require_valid is 1, returns NULL if the EL is not
  61  * provisioned or has been discarded; otherwise, the returned EL may be
  62  * unprovisioned or discarded.
  63  */
  64 OSSL_QRL_ENC_LEVEL *ossl_qrl_enc_level_set_get(OSSL_QRL_ENC_LEVEL_SET *els,
  65                                                uint32_t enc_level,
  66                                                int require_valid);
  67
  68 /* Provide secret to an EL. md may be NULL. */
  69 int ossl_qrl_enc_level_set_provide_secret(OSSL_QRL_ENC_LEVEL_SET *els,
  70                                           OSSL_LIB_CTX *libctx,
  71                                           const char *propq,
  72                                           uint32_t enc_level,
  73                                           uint32_t suite_id,
  74                                           EVP_MD *md,
  75                                           const unsigned char *secret,
  76                                           size_t secret_len);
  77
  78 /*
  79  * Discard an EL. If is_final is non-zero, no secret can be provided for the EL
  80  * ever again.
  81  */
  82 void ossl_qrl_enc_level_set_discard(OSSL_QRL_ENC_LEVEL_SET *els,
  83                                     uint32_t enc_level,
  84                                     int is_final);
  85
  86 #endif