2ce3d038a734b74eca718da7d24e4be6fefb3e31
[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 * Use the internal PRF to allocate data (mainly for the finished message
131 * where the key is from derive_finished() and the seed is the transcript
132 * hash).
133 *
134 * @param key key to use with the PRF
135 * @param seed seed to use with the PRF
136 * @param out output from the PRF (allocated)
137 * @return TRUE if output was generated
138 */
139 bool (*allocate_bytes)(tls_hkdf_t *this, chunk_t key, chunk_t seed,
140 chunk_t *out);
141
142 /**
143 * Destroy a tls_hkdf_t
144 */
145 void (*destroy)(tls_hkdf_t *this);
146 };
147
148 /**
149 * Create a tls_hkdf instance.
150 *
151 * @param hash_algorithm hash algorithm to use
152 * @param psk Pre shared key if available otherwise NULL
153 * @return TLS HKDF helper
154 */
155 tls_hkdf_t *tls_hkdf_create(hash_algorithm_t hash_algorithm, chunk_t psk);
156
157 #endif /** TLS_HKDF_H_ @}*/