2
0

quic_record_shared.h 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  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. #ifndef OSSL_QUIC_RECORD_SHARED_H
  10. # define OSSL_QUIC_RECORD_SHARED_H
  11. # include <openssl/ssl.h>
  12. # include "internal/quic_types.h"
  13. # include "internal/quic_wire_pkt.h"
  14. /*
  15. * QUIC Record Layer EL Management Utilities
  16. * =========================================
  17. *
  18. * This defines a structure for managing the cryptographic state at a given
  19. * encryption level, as this functionality is shared between QRX and QTX. For
  20. * QRL use only.
  21. */
  22. /*
  23. * States an EL can be in. The Updating and Cooldown states are used by RX only;
  24. * a TX EL in the Provisioned state is always in the Normal substate.
  25. *
  26. * Key material is available if in the Provisioned state.
  27. */
  28. #define QRL_EL_STATE_UNPROV 0 /* Unprovisioned (initial state) */
  29. #define QRL_EL_STATE_PROV_NORMAL 1 /* Provisioned - Normal */
  30. #define QRL_EL_STATE_PROV_UPDATING 2 /* Provisioned - Updating */
  31. #define QRL_EL_STATE_PROV_COOLDOWN 3 /* Provisioned - Cooldown */
  32. #define QRL_EL_STATE_DISCARDED 4 /* Discarded (terminal state) */
  33. typedef struct ossl_qrl_enc_level_st {
  34. /*
  35. * Cryptographic context used to apply and remove header protection from
  36. * packet headers.
  37. */
  38. QUIC_HDR_PROTECTOR hpr;
  39. /* Hash function used for key derivation. */
  40. EVP_MD *md;
  41. /* Context used for packet body ciphering. One for each keyslot. */
  42. EVP_CIPHER_CTX *cctx[2];
  43. OSSL_LIB_CTX *libctx;
  44. const char *propq;
  45. /*
  46. * Key epoch, essentially the number of times we have done a key update.
  47. *
  48. * The least significant bit of this is therefore by definition the current
  49. * Key Phase bit value.
  50. */
  51. uint64_t key_epoch;
  52. /* Usage counter. The caller maintains this. Used by TX side only. */
  53. uint64_t op_count;
  54. /* QRL_SUITE_* value. */
  55. uint32_t suite_id;
  56. /* Length of authentication tag. */
  57. uint32_t tag_len;
  58. /* Current EL state. */
  59. unsigned char state; /* QRL_EL_STATE_* */
  60. /* 1 if for TX, else RX. Initialised when secret provided. */
  61. unsigned char is_tx;
  62. /* IV used to construct nonces used for AEAD packet body ciphering. */
  63. unsigned char iv[2][EVP_MAX_IV_LENGTH];
  64. /*
  65. * Secret for next key epoch.
  66. */
  67. unsigned char ku[EVP_MAX_KEY_LENGTH];
  68. } OSSL_QRL_ENC_LEVEL;
  69. typedef struct ossl_qrl_enc_level_set_st {
  70. OSSL_QRL_ENC_LEVEL el[QUIC_ENC_LEVEL_NUM];
  71. } OSSL_QRL_ENC_LEVEL_SET;
  72. /*
  73. * Returns 1 if we have key material for a given encryption level (that is, if
  74. * we are in the PROVISIONED state), 0 if we do not yet have material (we are in
  75. * the UNPROVISIONED state) and -1 if the EL is discarded (we are in the
  76. * DISCARDED state).
  77. */
  78. int ossl_qrl_enc_level_set_have_el(OSSL_QRL_ENC_LEVEL_SET *els,
  79. uint32_t enc_level);
  80. /*
  81. * Returns EL in a set. If enc_level is not a valid QUIC_ENC_LEVEL_* value,
  82. * returns NULL. If require_prov is 1, returns NULL if the EL is not in
  83. * the PROVISIONED state; otherwise, the returned EL may be in any state.
  84. */
  85. OSSL_QRL_ENC_LEVEL *ossl_qrl_enc_level_set_get(OSSL_QRL_ENC_LEVEL_SET *els,
  86. uint32_t enc_level,
  87. int require_prov);
  88. /* Provide secret to an EL. md may be NULL. */
  89. int ossl_qrl_enc_level_set_provide_secret(OSSL_QRL_ENC_LEVEL_SET *els,
  90. OSSL_LIB_CTX *libctx,
  91. const char *propq,
  92. uint32_t enc_level,
  93. uint32_t suite_id,
  94. EVP_MD *md,
  95. const unsigned char *secret,
  96. size_t secret_len,
  97. unsigned char init_key_phase_bit,
  98. int is_tx);
  99. /*
  100. * Returns 1 if the given keyslot index is currently valid for a given EL and EL
  101. * state.
  102. */
  103. int ossl_qrl_enc_level_set_has_keyslot(OSSL_QRL_ENC_LEVEL_SET *els,
  104. uint32_t enc_level,
  105. unsigned char tgt_state,
  106. size_t keyslot);
  107. /* Perform a key update. Transitions from PROV_NORMAL to PROV_UPDATING. */
  108. int ossl_qrl_enc_level_set_key_update(OSSL_QRL_ENC_LEVEL_SET *els,
  109. uint32_t enc_level);
  110. /* Transitions from PROV_UPDATING to PROV_COOLDOWN. */
  111. int ossl_qrl_enc_level_set_key_update_done(OSSL_QRL_ENC_LEVEL_SET *els,
  112. uint32_t enc_level);
  113. /*
  114. * Transitions from PROV_COOLDOWN to PROV_NORMAL. (If in PROV_UPDATING,
  115. * auto-transitions to PROV_COOLDOWN first.)
  116. */
  117. int ossl_qrl_enc_level_set_key_cooldown_done(OSSL_QRL_ENC_LEVEL_SET *els,
  118. uint32_t enc_level);
  119. /*
  120. * Discard an EL. No secret can be provided for the EL ever again.
  121. */
  122. void ossl_qrl_enc_level_set_discard(OSSL_QRL_ENC_LEVEL_SET *els,
  123. uint32_t enc_level);
  124. #endif