tls-hkdf: Cleanups and refactorings
[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 };
46
47 /**
48 * TLS HKDF helper functions.
49 */
50 struct tls_hkdf_t {
51
52 /**
53 * Set the (EC)DHE shared secret of this connection.
54 *
55 * @param shared_secret input key material to use
56 */
57 void (*set_shared_secret)(tls_hkdf_t *this, chunk_t shared_secret);
58
59 /**
60 * Allocate secret of the requested label.
61 *
62 * Space for returned secret is allocated and must be freed by the caller.
63 *
64 * @param label HKDF label of requested secret
65 * @param messages handshake messages
66 * @param secret secret will be written into this chunk, if used
67 * @return TRUE if secrets derived successfully
68 */
69 bool (*generate_secret)(tls_hkdf_t *this, tls_hkdf_label_t label,
70 chunk_t messages, chunk_t *secret);
71
72 /**
73 * Allocate traffic encryption key bytes.
74 *
75 * Key used to encrypt traffic data as defined in RFC 8446, section 7.3.
76 * Space for returned secret is allocated and must be freed by the caller.
77 *
78 * @param is_server TRUE if server, FALSE if client derives secret
79 * @param length key length, in bytes
80 * @param key key will be written into this chunk
81 * @return TRUE if secrets derived successfully
82 */
83 bool (*derive_key)(tls_hkdf_t *this, bool is_server, size_t length,
84 chunk_t *key);
85
86 /**
87 * Allocate traffic IV bytes.
88 *
89 * IV used to encrypt traffic data as defined in RFC 8446, section 7.3.
90 * Space for returned secret is allocated and must be freed by the caller.
91 *
92 * @param is_server TRUE if server, FALSE if client derives secret
93 * @param length key length, in bytes
94 * @param iv IV will be written into this chunk
95 * @return TRUE if secrets derived successfully
96 */
97 bool (*derive_iv)(tls_hkdf_t *this, bool is_server, size_t length,
98 chunk_t *iv);
99
100 /**
101 * Allocate finished key bytes.
102 *
103 * Key used to compute Finished messages as defined in RFC 8446,
104 * section 4.4.4. Space for returned secret is allocated and must be freed
105 * by the caller.
106 *
107 * @param is_server TRUE if server, FALSE if client derives secret
108 * @param finished key will be written into this chunk
109 * @return TRUE if secrets derived successfully
110 */
111 bool (*derive_finished)(tls_hkdf_t *this, bool is_server,
112 chunk_t *finished);
113
114 /**
115 * Destroy a tls_hkdf_t
116 */
117 void (*destroy)(tls_hkdf_t *this);
118 };
119
120 /**
121 * Create a tls_hkdf instance.
122 *
123 * @param hash_algorithm hash algorithm to use
124 * @param psk Pre shared key if available otherwise NULL
125 * @return TLS HKDF helper
126 */
127 tls_hkdf_t *tls_hkdf_create(hash_algorithm_t hash_algorithm, chunk_t psk);
128
129 #endif /** TLS_HKDF_H_ @}*/