Return to tls_hkdf.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libtls

strongswan 5.9.2

    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_ @}*/