common/mbedtls/ssl_tls13_keys.h

   1 /*
   2  *  TLS 1.3 key schedule
   3  *
   4  *  Copyright The Mbed TLS Contributors
   5  *  SPDX-License-Identifier: Apache-2.0
   6  *
   7  *  Licensed under the Apache License, Version 2.0 ( the "License" ); you may
   8  *  not use this file except in compliance with the License.
   9  *  You may obtain a copy of the License at
  10  *
  11  *  http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  *  Unless required by applicable law or agreed to in writing, software
  14  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  15  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  *  See the License for the specific language governing permissions and
  17  *  limitations under the License.
  18  */
  19 #if !defined(MBEDTLS_SSL_TLS1_3_KEYS_H)
  20 #define MBEDTLS_SSL_TLS1_3_KEYS_H
  21
  22 /* This requires MBEDTLS_SSL_TLS1_3_LABEL( idx, name, string ) to be defined at
  23  * the point of use. See e.g. the definition of mbedtls_ssl_tls1_3_labels_union
  24  * below. */
  25 #define MBEDTLS_SSL_TLS1_3_LABEL_LIST                               \
  26     MBEDTLS_SSL_TLS1_3_LABEL( finished    , "finished"     ) \
  27     MBEDTLS_SSL_TLS1_3_LABEL( resumption  , "resumption"   ) \
  28     MBEDTLS_SSL_TLS1_3_LABEL( traffic_upd , "traffic upd"  ) \
  29     MBEDTLS_SSL_TLS1_3_LABEL( exporter    , "exporter"     ) \
  30     MBEDTLS_SSL_TLS1_3_LABEL( key         , "key"          ) \
  31     MBEDTLS_SSL_TLS1_3_LABEL( iv          , "iv"           ) \
  32     MBEDTLS_SSL_TLS1_3_LABEL( c_hs_traffic, "c hs traffic" ) \
  33     MBEDTLS_SSL_TLS1_3_LABEL( c_ap_traffic, "c ap traffic" ) \
  34     MBEDTLS_SSL_TLS1_3_LABEL( c_e_traffic , "c e traffic"  ) \
  35     MBEDTLS_SSL_TLS1_3_LABEL( s_hs_traffic, "s hs traffic" ) \
  36     MBEDTLS_SSL_TLS1_3_LABEL( s_ap_traffic, "s ap traffic" ) \
  37     MBEDTLS_SSL_TLS1_3_LABEL( s_e_traffic , "s e traffic"  ) \
  38     MBEDTLS_SSL_TLS1_3_LABEL( e_exp_master, "e exp master" ) \
  39     MBEDTLS_SSL_TLS1_3_LABEL( res_master  , "res master"   ) \
  40     MBEDTLS_SSL_TLS1_3_LABEL( exp_master  , "exp master"   ) \
  41     MBEDTLS_SSL_TLS1_3_LABEL( ext_binder  , "ext binder"   ) \
  42     MBEDTLS_SSL_TLS1_3_LABEL( res_binder  , "res binder"   ) \
  43     MBEDTLS_SSL_TLS1_3_LABEL( derived     , "derived"      )
  44
  45 #define MBEDTLS_SSL_TLS1_3_LABEL( name, string )       \
  46     const unsigned char name    [ sizeof(string) - 1 ];
  47
  48 union mbedtls_ssl_tls1_3_labels_union {
  49     MBEDTLS_SSL_TLS1_3_LABEL_LIST
  50 };
  51 struct mbedtls_ssl_tls1_3_labels_struct {
  52     MBEDTLS_SSL_TLS1_3_LABEL_LIST
  53 };
  54 #undef MBEDTLS_SSL_TLS1_3_LABEL
  55
  56 extern const struct mbedtls_ssl_tls1_3_labels_struct mbedtls_ssl_tls1_3_labels;
  57
  58 #define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( LABEL )  \
  59     mbedtls_ssl_tls1_3_labels.LABEL,              \
  60     sizeof(mbedtls_ssl_tls1_3_labels.LABEL)
  61
  62 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN  \
  63     sizeof( union mbedtls_ssl_tls1_3_labels_union )
  64
  65 /* The maximum length of HKDF contexts used in the TLS 1.3 standard.
  66  * Since contexts are always hashes of message transcripts, this can
  67  * be approximated from above by the maximum hash size. */
  68 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN  \
  69     MBEDTLS_MD_MAX_SIZE
  70
  71 /* Maximum desired length for expanded key material generated
  72  * by HKDF-Expand-Label.
  73  *
  74  * Warning: If this ever needs to be increased, the implementation
  75  * ssl_tls1_3_hkdf_encode_label() in ssl_tls13_keys.c needs to be
  76  * adjusted since it currently assumes that HKDF key expansion
  77  * is never used with more than 255 Bytes of output. */
  78 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN 255
  79
  80 /**
  81  * \brief           The \c HKDF-Expand-Label function from
  82  *                  the TLS 1.3 standard RFC 8446.
  83  *
  84  * <tt>
  85  *                  HKDF-Expand-Label( Secret, Label, Context, Length ) =
  86  *                       HKDF-Expand( Secret, HkdfLabel, Length )
  87  * </tt>
  88  *
  89  * \param hash_alg  The identifier for the hash algorithm to use.
  90  * \param secret    The \c Secret argument to \c HKDF-Expand-Label.
  91  *                  This must be a readable buffer of length \p slen Bytes.
  92  * \param slen      The length of \p secret in Bytes.
  93  * \param label     The \c Label argument to \c HKDF-Expand-Label.
  94  *                  This must be a readable buffer of length \p llen Bytes.
  95  * \param llen      The length of \p label in Bytes.
  96  * \param ctx       The \c Context argument to \c HKDF-Expand-Label.
  97  *                  This must be a readable buffer of length \p clen Bytes.
  98  * \param clen      The length of \p context in Bytes.
  99  * \param buf       The destination buffer to hold the expanded secret.
 100  *                  This must be a writable buffer of length \p blen Bytes.
 101  * \param blen      The desired size of the expanded secret in Bytes.
 102  *
 103  * \returns         \c 0 on success.
 104  * \return          A negative error code on failure.
 105  */
 106
 107 int mbedtls_ssl_tls1_3_hkdf_expand_label(
 108     mbedtls_md_type_t hash_alg,
 109     const unsigned char *secret, size_t slen,
 110     const unsigned char *label, size_t llen,
 111     const unsigned char *ctx, size_t clen,
 112     unsigned char *buf, size_t blen);
 113
 114 /**
 115  * \brief           This function is part of the TLS 1.3 key schedule.
 116  *                  It extracts key and IV for the actual client/server traffic
 117  *                  from the client/server traffic secrets.
 118  *
 119  * From RFC 8446:
 120  *
 121  * <tt>
 122  *   [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length)
 123  *   [sender]_write_iv  = HKDF-Expand-Label(Secret, "iv", "", iv_length)*
 124  * </tt>
 125  *
 126  * \param hash_alg      The identifier for the hash algorithm to be used
 127  *                      for the HKDF-based expansion of the secret.
 128  * \param client_secret The client traffic secret.
 129  *                      This must be a readable buffer of size \p slen Bytes
 130  * \param server_secret The server traffic secret.
 131  *                      This must be a readable buffer of size \p slen Bytes
 132  * \param slen          Length of the secrets \p client_secret and
 133  *                      \p server_secret in Bytes.
 134  * \param key_len       The desired length of the key to be extracted in Bytes.
 135  * \param iv_len        The desired length of the IV to be extracted in Bytes.
 136  * \param keys          The address of the structure holding the generated
 137  *                      keys and IVs.
 138  *
 139  * \returns             \c 0 on success.
 140  * \returns             A negative error code on failure.
 141  */
 142
 143 int mbedtls_ssl_tls1_3_make_traffic_keys(
 144     mbedtls_md_type_t hash_alg,
 145     const unsigned char *client_secret,
 146     const unsigned char *server_secret,
 147     size_t slen, size_t key_len, size_t iv_len,
 148     mbedtls_ssl_key_set *keys);
 149
 150
 151 #define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED 0
 152 #define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED   1
 153
 154 /**
 155  * \brief The \c Derive-Secret function from the TLS 1.3 standard RFC 8446.
 156  *
 157  * <tt>
 158  *   Derive-Secret( Secret, Label, Messages ) =
 159  *      HKDF-Expand-Label( Secret, Label,
 160  *                         Hash( Messages ),
 161  *                         Hash.Length ) )
 162  * </tt>
 163  *
 164  * \param hash_alg   The identifier for the hash function used for the
 165  *                   applications of HKDF.
 166  * \param secret     The \c Secret argument to the \c Derive-Secret function.
 167  *                   This must be a readable buffer of length \p slen Bytes.
 168  * \param slen       The length of \p secret in Bytes.
 169  * \param label      The \c Label argument to the \c Derive-Secret function.
 170  *                   This must be a readable buffer of length \p llen Bytes.
 171  * \param llen       The length of \p label in Bytes.
 172  * \param ctx        The hash of the \c Messages argument to the
 173  *                   \c Derive-Secret function, or the \c Messages argument
 174  *                   itself, depending on \p context_already_hashed.
 175  * \param clen       The length of \p hash.
 176  * \param ctx_hashed This indicates whether the \p ctx contains the hash of
 177  *                   the \c Messages argument in the application of the
 178  *                   \c Derive-Secret function
 179  *                   (value MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED), or whether
 180  *                   it is the content of \c Messages itself, in which case
 181  *                   the function takes care of the hashing
 182  *                   (value MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED).
 183  * \param dstbuf     The target buffer to write the output of
 184  *                   \c Derive-Secret to. This must be a writable buffer of
 185  *                   size \p buflen Bytes.
 186  * \param buflen     The length of \p dstbuf in Bytes.
 187  *
 188  * \returns        \c 0 on success.
 189  * \returns        A negative error code on failure.
 190  */
 191 int mbedtls_ssl_tls1_3_derive_secret(
 192     mbedtls_md_type_t hash_alg,
 193     const unsigned char *secret, size_t slen,
 194     const unsigned char *label, size_t llen,
 195     const unsigned char *ctx, size_t clen,
 196     int ctx_hashed,
 197     unsigned char *dstbuf, size_t buflen);
 198
 199 /**
 200  * \brief Compute the next secret in the TLS 1.3 key schedule
 201  *
 202  * The TLS 1.3 key schedule proceeds as follows to compute
 203  * the three main secrets during the handshake: The early
 204  * secret for early data, the handshake secret for all
 205  * other encrypted handshake messages, and the master
 206  * secret for all application traffic.
 207  *
 208  * <tt>
 209  *                    0
 210  *                    |
 211  *                    v
 212  *     PSK ->  HKDF-Extract = Early Secret
 213  *                    |
 214  *                    v
 215  *     Derive-Secret( ., "derived", "" )
 216  *                    |
 217  *                    v
 218  *  (EC)DHE -> HKDF-Extract = Handshake Secret
 219  *                    |
 220  *                    v
 221  *     Derive-Secret( ., "derived", "" )
 222  *                    |
 223  *                    v
 224  *     0 -> HKDF-Extract = Master Secret
 225  * </tt>
 226  *
 227  * Each of the three secrets in turn is the basis for further
 228  * key derivations, such as the derivation of traffic keys and IVs;
 229  * see e.g. mbedtls_ssl_tls1_3_make_traffic_keys().
 230  *
 231  * This function implements one step in this evolution of secrets:
 232  *
 233  * <tt>
 234  *                old_secret
 235  *                    |
 236  *                    v
 237  *     Derive-Secret( ., "derived", "" )
 238  *                    |
 239  *                    v
 240  *     input -> HKDF-Extract = new_secret
 241  * </tt>
 242  *
 243  * \param hash_alg    The identifier for the hash function used for the
 244  *                    applications of HKDF.
 245  * \param secret_old  The address of the buffer holding the old secret
 246  *                    on function entry. If not \c NULL, this must be a
 247  *                    readable buffer whose size matches the output size
 248  *                    of the hash function represented by \p hash_alg.
 249  *                    If \c NULL, an all \c 0 array will be used instead.
 250  * \param input       The address of the buffer holding the additional
 251  *                    input for the key derivation (e.g., the PSK or the
 252  *                    ephemeral (EC)DH secret). If not \c NULL, this must be
 253  *                    a readable buffer whose size \p input_len Bytes.
 254  *                    If \c NULL, an all \c 0 array will be used instead.
 255  * \param input_len   The length of \p input in Bytes.
 256  * \param secret_new  The address of the buffer holding the new secret
 257  *                    on function exit. This must be a writable buffer
 258  *                    whose size matches the output size of the hash
 259  *                    function represented by \p hash_alg.
 260  *                    This may be the same as \p secret_old.
 261  *
 262  * \returns           \c 0 on success.
 263  * \returns           A negative error code on failure.
 264  */
 265
 266 int mbedtls_ssl_tls1_3_evolve_secret(
 267     mbedtls_md_type_t hash_alg,
 268     const unsigned char *secret_old,
 269     const unsigned char *input, size_t input_len,
 270     unsigned char *secret_new);
 271
 272 #endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */