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