Home | History | Annotate | Line # | Download | only in quic 
      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 
     26 /*
     27  * States an EL can be in. The Updating and Cooldown states are used by RX only;
     28  * a TX EL in the Provisioned state is always in the Normal substate.
     29  *
     30  * Key material is available if in the Provisioned state.
     31  */
     32 #define QRL_EL_STATE_UNPROV 0 /* Unprovisioned (initial state) */
     33 #define QRL_EL_STATE_PROV_NORMAL 1 /* Provisioned - Normal */
     34 #define QRL_EL_STATE_PROV_UPDATING 2 /* Provisioned - Updating */
     35 #define QRL_EL_STATE_PROV_COOLDOWN 3 /* Provisioned - Cooldown */
     36 #define QRL_EL_STATE_DISCARDED 4 /* Discarded (terminal state) */
     37 
     38 typedef struct ossl_qrl_enc_level_st {
     39     /*
     40      * Cryptographic context used to apply and remove header protection from
     41      * packet headers.
     42      */
     43     QUIC_HDR_PROTECTOR hpr;
     44 
     45     /* Hash function used for key derivation. */
     46     EVP_MD *md;
     47 
     48     /* Context used for packet body ciphering. One for each keyslot. */
     49     EVP_CIPHER_CTX *cctx[2];
     50 
     51     OSSL_LIB_CTX *libctx;
     52     const char *propq;
     53 
     54     /*
     55      * Key epoch, essentially the number of times we have done a key update.
     56      *
     57      * The least significant bit of this is therefore by definition the current
     58      * Key Phase bit value.
     59      */
     60     uint64_t key_epoch;
     61 
     62     /* Usage counter. The caller maintains this. Used by TX side only. */
     63     uint64_t op_count;
     64 
     65     /* QRL_SUITE_* value. */
     66     uint32_t suite_id;
     67 
     68     /* Length of authentication tag. */
     69     uint32_t tag_len;
     70 
     71     /* Current EL state. */
     72     unsigned char state; /* QRL_EL_STATE_* */
     73 
     74     /* 1 if for TX, else RX. Initialised when secret provided. */
     75     unsigned char is_tx;
     76 
     77     /* IV used to construct nonces used for AEAD packet body ciphering. */
     78     unsigned char iv[2][EVP_MAX_IV_LENGTH];
     79 
     80     /*
     81      * Secret for next key epoch.
     82      */
     83     unsigned char ku[EVP_MAX_KEY_LENGTH];
     84 } OSSL_QRL_ENC_LEVEL;
     85 
     86 typedef struct ossl_qrl_enc_level_set_st {
     87     OSSL_QRL_ENC_LEVEL el[QUIC_ENC_LEVEL_NUM];
     88 } OSSL_QRL_ENC_LEVEL_SET;
     89 
     90 /*
     91  * Returns 1 if we have key material for a given encryption level (that is, if
     92  * we are in the PROVISIONED state), 0 if we do not yet have material (we are in
     93  * the UNPROVISIONED state) and -1 if the EL is discarded (we are in the
     94  * DISCARDED state).
     95  */
     96 int ossl_qrl_enc_level_set_have_el(OSSL_QRL_ENC_LEVEL_SET *els,
     97     uint32_t enc_level);
     98 
     99 /*
    100  * Returns EL in a set. If enc_level is not a valid QUIC_ENC_LEVEL_* value,
    101  * returns NULL. If require_prov is 1, returns NULL if the EL is not in
    102  * the PROVISIONED state; otherwise, the returned EL may be in any state.
    103  */
    104 OSSL_QRL_ENC_LEVEL *ossl_qrl_enc_level_set_get(OSSL_QRL_ENC_LEVEL_SET *els,
    105     uint32_t enc_level,
    106     int require_prov);
    107 
    108 /* Provide secret to an EL. md may be NULL. */
    109 int ossl_qrl_enc_level_set_provide_secret(OSSL_QRL_ENC_LEVEL_SET *els,
    110     OSSL_LIB_CTX *libctx,
    111     const char *propq,
    112     uint32_t enc_level,
    113     uint32_t suite_id,
    114     EVP_MD *md,
    115     const unsigned char *secret,
    116     size_t secret_len,
    117     unsigned char init_key_phase_bit,
    118     int is_tx);
    119 
    120 /*
    121  * Returns 1 if the given keyslot index is currently valid for a given EL and EL
    122  * state.
    123  */
    124 int ossl_qrl_enc_level_set_has_keyslot(OSSL_QRL_ENC_LEVEL_SET *els,
    125     uint32_t enc_level,
    126     unsigned char tgt_state,
    127     size_t keyslot);
    128 
    129 /* Perform a key update. Transitions from PROV_NORMAL to PROV_UPDATING. */
    130 int ossl_qrl_enc_level_set_key_update(OSSL_QRL_ENC_LEVEL_SET *els,
    131     uint32_t enc_level);
    132 
    133 /* Transitions from PROV_UPDATING to PROV_COOLDOWN. */
    134 int ossl_qrl_enc_level_set_key_update_done(OSSL_QRL_ENC_LEVEL_SET *els,
    135     uint32_t enc_level);
    136 
    137 /*
    138  * Transitions from PROV_COOLDOWN to PROV_NORMAL. (If in PROV_UPDATING,
    139  * auto-transitions to PROV_COOLDOWN first.)
    140  */
    141 int ossl_qrl_enc_level_set_key_cooldown_done(OSSL_QRL_ENC_LEVEL_SET *els,
    142     uint32_t enc_level);
    143 
    144 /*
    145  * Discard an EL. No secret can be provided for the EL ever again.
    146  */
    147 void ossl_qrl_enc_level_set_discard(OSSL_QRL_ENC_LEVEL_SET *els,
    148     uint32_t enc_level);
    149 
    150 #endif
    151