Annotation of embedaddon/strongswan/src/libtls/tls_hkdf.h, revision 1.1.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