summaryrefslogtreecommitdiff
path: root/lib/prf.c
blob: b7e926febfccab97282d909bec15d0f9c297fc84 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
/*
 * Copyright (C) 2002-2015 Free Software Foundation, Inc.
 * Copyright (C) 2014-2015 Nikos Mavrogiannopoulos
 * Copyright (C) 2016-2017 Red Hat, Inc.
 *
 * Author: Nikos Mavrogiannopoulos
 *
 * This file is part of GnuTLS.
 *
 * The GnuTLS is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>
 *
 */

/* Functions for the TLS PRF handling.
 */

#include "gnutls_int.h"
#include "errors.h"
#include "secrets.h"
#include <num.h>
#include <state.h>
#include <algorithms.h>

#define EXPORTER_LABEL "exporter"

/**
 * gnutls_prf_raw:
 * @session: is a #gnutls_session_t type.
 * @label_size: length of the @label variable.
 * @label: label used in PRF computation, typically a short string.
 * @seed_size: length of the @seed variable.
 * @seed: optional extra data to seed the PRF with.
 * @outsize: size of pre-allocated output buffer to hold the output.
 * @out: pre-allocated buffer to hold the generated data.
 *
 * Apply the TLS Pseudo-Random-Function (PRF) on the master secret
 * and the provided data.
 *
 * The @label variable usually contains a string denoting the purpose
 * for the generated data.  The @seed usually contains data such as the
 * client and server random, perhaps together with some additional
 * data that is added to guarantee uniqueness of the output for a
 * particular purpose.
 *
 * Because the output is not guaranteed to be unique for a particular
 * session unless @seed includes the client random and server random
 * fields (the PRF would output the same data on another connection
 * resumed from the first one), it is not recommended to use this
 * function directly.  The gnutls_prf() function seeds the PRF with the
 * client and server random fields directly, and is recommended if you
 * want to generate pseudo random data unique for each session.
 *
 * Note: This function will only operate under TLS versions prior to 1.3.
 * In TLS1.3 the use of PRF is replaced with HKDF and the generic
 * exporters like gnutls_prf_rfc5705() should be used instead. Under
 * TLS1.3 this function returns %GNUTLS_E_INVALID_REQUEST.
 *
 * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
 **/
int
gnutls_prf_raw(gnutls_session_t session,
	       size_t label_size,
	       const char *label,
	       size_t seed_size, const char *seed, size_t outsize,
	       char *out)
{
	int ret;
	const version_entry_st *vers = get_version(session);

	if (vers && vers->tls13_sem)
		return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);

	ret = _gnutls_prf_raw(session->security_parameters.prf->id,
			  GNUTLS_MASTER_SIZE, session->security_parameters.master_secret,
			  label_size, label,
			  seed_size, (uint8_t *) seed,
			  outsize, out);

	return ret;
}

/**
 * gnutls_prf_rfc5705:
 * @session: is a #gnutls_session_t type.
 * @label_size: length of the @label variable.
 * @label: label used in PRF computation, typically a short string.
 * @context_size: length of the @extra variable.
 * @context: optional extra data to seed the PRF with.
 * @outsize: size of pre-allocated output buffer to hold the output.
 * @out: pre-allocated buffer to hold the generated data.
 *
 * Exports keyring material from TLS/DTLS session to an application,
 * as specified in RFC5705.
 *
 * In the TLS versions prior to 1.3, it applies the TLS
 * Pseudo-Random-Function (PRF) on the master secret and the provided
 * data, seeded with the client and server random fields.
 *
 * In TLS 1.3, it applies HKDF on the exporter master secret derived
 * from the master secret.
 *
 * The @label variable usually contains a string denoting the purpose
 * for the generated data.
 *
 * The @context variable can be used to add more data to the seed, after
 * the random variables.  It can be used to make sure the
 * generated output is strongly connected to some additional data
 * (e.g., a string used in user authentication). 
 *
 * The output is placed in @out, which must be pre-allocated.
 *
 * Note that, to provide the RFC5705 context, the @context variable
 * must be non-null.
 *
 * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
 *
 * Since: 3.4.4
 **/
int
gnutls_prf_rfc5705(gnutls_session_t session,
		   size_t label_size, const char *label,
		   size_t context_size, const char *context,
		   size_t outsize, char *out)
{
	const version_entry_st *vers = get_version(session);
	int ret;

	if (vers && vers->tls13_sem) {
		uint8_t secret[MAX_HASH_SIZE];
		uint8_t digest[MAX_HASH_SIZE];
		unsigned digest_size = session->security_parameters.prf->output_size;

		/* exporter_master_secret might not be set, when
		 * handshake is in progress */
		if (session->internals.handshake_in_progress) {
			gnutls_assert();
			return GNUTLS_E_INVALID_REQUEST;
		}

		ret = _tls13_derive_secret(session, label, label_size, NULL, 0,
					   session->key.proto.tls13.ap_expkey, secret);
		if (ret < 0)
			return gnutls_assert_val(ret);

		ret = gnutls_hash_fast((gnutls_digest_algorithm_t)session->security_parameters.prf->id,
				       context, context_size, digest);
		if (ret < 0)
			return gnutls_assert_val(ret);

		ret = _tls13_expand_secret(session, EXPORTER_LABEL, sizeof(EXPORTER_LABEL)-1,
					   digest, digest_size,
					   secret, outsize, out);
	} else {
		char *pctx = NULL;

		if (context != NULL && context_size > 65535)  {
			gnutls_assert();
			return GNUTLS_E_INVALID_REQUEST;
		}

		if (context != NULL) {
			pctx = gnutls_malloc(context_size+2);
			if (!pctx) {
				gnutls_assert();
				return GNUTLS_E_MEMORY_ERROR;
			}

			memcpy(pctx+2, context, context_size);
			_gnutls_write_uint16(context_size, (void*)pctx);
			context_size += 2;
		}

		ret = gnutls_prf(session, label_size, label, 0,
				 context_size, pctx, outsize, out);

		gnutls_free(pctx);
	}

	return ret;
}

/**
 * gnutls_prf:
 * @session: is a #gnutls_session_t type.
 * @label_size: length of the @label variable.
 * @label: label used in PRF computation, typically a short string.
 * @server_random_first: non-zero if server random field should be first in seed
 * @extra_size: length of the @extra variable.
 * @extra: optional extra data to seed the PRF with.
 * @outsize: size of pre-allocated output buffer to hold the output.
 * @out: pre-allocated buffer to hold the generated data.
 *
 * Applies the TLS Pseudo-Random-Function (PRF) on the master secret
 * and the provided data, seeded with the client and server random fields.
 * For the key expansion specified in RFC5705 see gnutls_prf_rfc5705().
 *
 * The @label variable usually contains a string denoting the purpose
 * for the generated data.  The @server_random_first indicates whether
 * the client random field or the server random field should be first
 * in the seed.  Non-zero indicates that the server random field is first,
 * 0 that the client random field is first.
 *
 * The @extra variable can be used to add more data to the seed, after
 * the random variables.  It can be used to make sure the
 * generated output is strongly connected to some additional data
 * (e.g., a string used in user authentication).
 *
 * The output is placed in @out, which must be pre-allocated.
 *
 * Note: This function produces identical output with gnutls_prf_rfc5705()
 * when @server_random_first is set to 0 and @extra is %NULL. Under TLS1.3
 * this function will only operate when these conditions are true, or otherwise
 * return %GNUTLS_E_INVALID_REQUEST.
 *
 * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
 **/
int
gnutls_prf(gnutls_session_t session,
	   size_t label_size,
	   const char *label,
	   int server_random_first,
	   size_t extra_size, const char *extra,
	   size_t outsize, char *out)
{
	int ret;
	uint8_t *seed;
	const version_entry_st *vers = get_version(session);
	size_t seedsize = 2 * GNUTLS_RANDOM_SIZE + extra_size;

	if (vers && vers->tls13_sem) {
		if (extra == NULL && server_random_first == 0)
			return gnutls_prf_rfc5705(session, label_size, label,
						  extra_size, extra, outsize, out);
		else
			return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);
	}

	seed = gnutls_malloc(seedsize);
	if (!seed) {
		gnutls_assert();
		return GNUTLS_E_MEMORY_ERROR;
	}

	memcpy(seed, server_random_first ?
	       session->security_parameters.server_random :
	       session->security_parameters.client_random,
	       GNUTLS_RANDOM_SIZE);
	memcpy(seed + GNUTLS_RANDOM_SIZE,
	       server_random_first ? session->security_parameters.
	       client_random : session->security_parameters.server_random,
	       GNUTLS_RANDOM_SIZE);

	if (extra && extra_size) {
		memcpy(seed + 2 * GNUTLS_RANDOM_SIZE, extra, extra_size);
	}

	ret =
	    _gnutls_prf_raw(session->security_parameters.prf->id,
			GNUTLS_MASTER_SIZE, session->security_parameters.master_secret,
			label_size, label,
			seedsize, seed,
			outsize, out);

	gnutls_free(seed);

	return ret;
}