Annotation of embedaddon/strongswan/src/libtls/tls_hkdf.h, revision 1.1
1.1 ! misho 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_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to tls_hkdf.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / strongswan / src / libtls