src/libtls/tls_hkdf.h

   1 /*
   2  * Copyright (C) 2020 Pascal Knecht
   3  * Copyright (C) 2020 Méline Sieber
   4  * HSR Hochschule fuer Technik Rapperswil
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup tls_hkdf tls_hkdf
  19  * @{ @ingroup libtls
  20  */
  21
  22 #ifndef TLS_HKDF_H_
  23 #define TLS_HKDF_H_
  24
  25 #include <library.h>
  26 #include <crypto/hashers/hasher.h>
  27
  28 typedef enum tls_hkdf_label_t tls_hkdf_label_t;
  29 typedef struct tls_hkdf_t tls_hkdf_t;
  30
  31 /**
  32  * TLS HKDF labels
  33  */
  34 enum tls_hkdf_label_t {
  35         TLS_HKDF_EXT_BINDER,
  36         TLS_HKDF_RES_BINDER,
  37         TLS_HKDF_C_E_TRAFFIC,
  38         TLS_HKDF_E_EXP_MASTER,
  39         TLS_HKDF_C_HS_TRAFFIC,
  40         TLS_HKDF_S_HS_TRAFFIC,
  41         TLS_HKDF_C_AP_TRAFFIC,
  42         TLS_HKDF_S_AP_TRAFFIC,
  43         TLS_HKDF_EXP_MASTER,
  44         TLS_HKDF_RES_MASTER,
  45         TLS_HKDF_UPD_C_TRAFFIC,
  46         TLS_HKDF_UPD_S_TRAFFIC,
  47 };
  48
  49 /**
  50  * TLS HKDF helper functions.
  51  */
  52 struct tls_hkdf_t {
  53
  54         /**
  55          * Set the (EC)DHE shared secret of this connection.
  56          *
  57          * @param shared_secret         input key material to use
  58          */
  59         void (*set_shared_secret)(tls_hkdf_t *this, chunk_t shared_secret);
  60
  61         /**
  62          * Allocate secret of the requested label.
  63          *
  64          * Space for returned secret is allocated and must be freed by the caller.
  65          *
  66          * @param label                         HKDF label of requested secret
  67          * @param messages                      handshake messages
  68          * @param secret                        secret will be written into this chunk, if used
  69          * @return                                      TRUE if secrets derived successfully
  70          */
  71         bool (*generate_secret)(tls_hkdf_t *this, tls_hkdf_label_t label,
  72                                                         chunk_t messages, chunk_t *secret);
  73
  74         /**
  75          * Allocate traffic encryption key bytes.
  76          *
  77          * Key used to encrypt traffic data as defined in RFC 8446, section 7.3.
  78          * Space for returned secret is allocated and must be freed by the caller.
  79          *
  80          * @param is_server                     TRUE if server, FALSE if client derives secret
  81          * @param length                        key length, in bytes
  82          * @param key                           key will be written into this chunk
  83          * @return                                      TRUE if secrets derived successfully
  84          */
  85         bool (*derive_key)(tls_hkdf_t *this, bool is_server, size_t length,
  86                                            chunk_t *key);
  87
  88         /**
  89          * Allocate traffic IV bytes.
  90          *
  91          * IV used to encrypt traffic data as defined in RFC 8446, section 7.3.
  92          * Space for returned secret is allocated and must be freed by the caller.
  93          *
  94          * @param is_server                     TRUE if server, FALSE if client derives secret
  95          * @param length                        key length, in bytes
  96          * @param iv                            IV will be written into this chunk
  97          * @return                                      TRUE if secrets derived successfully
  98          */
  99         bool (*derive_iv)(tls_hkdf_t *this, bool is_server, size_t length,
 100                                           chunk_t *iv);
 101
 102         /**
 103          * Allocate finished key bytes.
 104          *
 105          * Key used to compute Finished messages as defined in RFC 8446,
 106          * section 4.4.4. Space for returned secret is allocated and must be freed
 107          * by the caller.
 108          *
 109          * @param server                        Whether the client or server finish key is derived
 110          * @param finished                      key will be written into this chunk
 111          * @return                                      TRUE if secrets derived successfully
 112          */
 113         bool (*derive_finished)(tls_hkdf_t *this, bool server,
 114                                                         chunk_t *finished);
 115
 116         /**
 117          * Export key material.
 118          *
 119          * @param label                         exporter label
 120          * @param context                       optional context
 121          * @param messages                      handshake messages
 122          * @param length                        key length, in bytes
 123          * @param key                           exported key material
 124          * @return                                      TRUE if key material successfully exported
 125          */
 126         bool (*export)(tls_hkdf_t *this, char *label, chunk_t context,
 127                                    chunk_t messages, size_t length, chunk_t *key);
 128
 129         /**
 130          * Generate resumption PSKs.
 131          *
 132          * @param messages                      handshake messages
 133          * @param nonce                         nonce to use for this PSK
 134          * @param psk                           generated PSK
 135          * @return                                      TRUE if PSK successfully generated
 136          */
 137         bool (*resume)(tls_hkdf_t *this, chunk_t messages, chunk_t nonce,
 138                                    chunk_t *psk);
 139
 140         /**
 141          * Generate a PSK binder.
 142          *
 143          * @note The transcript hash is built of the partial ClientHello message up
 144          * to and including the PreSharedKey extension's identities field, excluding
 145          * the actual binders (their length is included in that of the extension(s)
 146          * and message, though), as per RFC 8446, section 4.2.11.2.
 147          *
 148          * @param seed                          transcript-hash of client_hello to seed the PRF
 149          * @param psk_binder            generated psk binder
 150          * @return                                      TRUE if output was generated
 151          */
 152         bool (*binder)(tls_hkdf_t *this, chunk_t seed, chunk_t *psk_binder);
 153
 154         /**
 155          * Use the internal PRF to allocate data (mainly for the finished message
 156          * where the key is from derive_finished() and the seed is the transcript
 157          * hash).
 158          *
 159          * @param key                           key to use with the PRF
 160          * @param seed                          seed to use with the PRF
 161          * @param out                           output from the PRF (allocated)
 162          * @return                                      TRUE if output was generated
 163          */
 164         bool (*allocate_bytes)(tls_hkdf_t *this, chunk_t key, chunk_t seed,
 165                                                    chunk_t *out);
 166
 167         /**
 168          * Destroy a tls_hkdf_t
 169          */
 170         void (*destroy)(tls_hkdf_t *this);
 171 };
 172
 173 /**
 174  * Create a tls_hkdf instance.
 175  *
 176  * @param hash_algorithm        hash algorithm to use
 177  * @param psk                           Pre shared key if available otherwise NULL
 178  * @return                                      TLS HKDF helper
 179  */
 180 tls_hkdf_t *tls_hkdf_create(hash_algorithm_t hash_algorithm, chunk_t psk);
 181
 182 #endif /** TLS_HKDF_H_ @}*/