tls-hkdf: Implement binder PSK generation
[strongswan.git] / 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_ @}*/