blob: f997c1864ecec169dfd39f0d5f26329fda61b44e [file] [log] [blame]
Yanray Wang5fce1452022-10-24 14:42:01 +08001/** \file ssl_helpers.h
2 *
3 * \brief This file contains helper functions to set up a TLS connection.
4 */
5
6/*
7 * Copyright The Mbed TLS Contributors
8 * SPDX-License-Identifier: Apache-2.0
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
21 */
22
23#ifndef SSL_HELPERS_H
24#define SSL_HELPERS_H
25
Yanray Wang4323e452023-03-14 16:52:06 +080026#include <string.h>
Yanray Wang5fce1452022-10-24 14:42:01 +080027
Yanray Wang4323e452023-03-14 16:52:06 +080028#include <test/helpers.h>
29#include <test/macros.h>
30#include <test/random.h>
31#include <test/psa_crypto_helpers.h>
32
33#if defined(MBEDTLS_SSL_TLS_C)
34#include <mbedtls/ssl_internal.h>
Yanray Wang59ab2762022-10-26 09:57:53 +080035#include <mbedtls/ctr_drbg.h>
36#include <mbedtls/entropy.h>
Yanray Wang4323e452023-03-14 16:52:06 +080037#include <mbedtls/certs.h>
38#include <mbedtls/timing.h>
39#include <mbedtls/debug.h>
40#include <ssl_tls13_keys.h>
41
42#if defined(MBEDTLS_SSL_CACHE_C)
43#include "mbedtls/ssl_cache.h"
44#endif
Yanray Wang59ab2762022-10-26 09:57:53 +080045
Yanray Wange16808c2023-03-14 18:08:56 +080046#if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED) || \
47 defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
48 defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED)
49#define MBEDTLS_CAN_HANDLE_RSA_TEST_KEY
50#endif
51
52enum {
53#define MBEDTLS_SSL_TLS1_3_LABEL(name, string) \
54 tls1_3_label_ ## name,
55 MBEDTLS_SSL_TLS1_3_LABEL_LIST
56#undef MBEDTLS_SSL_TLS1_3_LABEL
57};
58
Yanray Wang59ab2762022-10-26 09:57:53 +080059typedef struct mbedtls_test_ssl_log_pattern {
60 const char *pattern;
61 size_t counter;
62} mbedtls_test_ssl_log_pattern;
63
64/* Invalid minor version used when not specifying a min/max version or expecting a test to fail */
65#define TEST_SSL_MINOR_VERSION_NONE -1
66
67typedef struct mbedtls_test_handshake_test_options {
68 const char *cipher;
69 int client_min_version;
70 int client_max_version;
71 int server_min_version;
72 int server_max_version;
73 int expected_negotiated_version;
74 int pk_alg;
75 data_t *psk_str;
76 int dtls;
77 int srv_auth_mode;
78 int serialize;
79 int mfl;
80 int cli_msg_len;
81 int srv_msg_len;
82 int expected_cli_fragments;
83 int expected_srv_fragments;
84 int renegotiate;
85 int legacy_renegotiation;
86 void *srv_log_obj;
87 void *cli_log_obj;
88 void (*srv_log_fun)(void *, int, const char *, int, const char *);
89 void (*cli_log_fun)(void *, int, const char *, int, const char *);
90 int resize_buffers;
91} mbedtls_test_handshake_test_options;
92
93/*
94 * Buffer structure for custom I/O callbacks.
95 */
96typedef struct mbedtls_test_ssl_buffer {
97 size_t start;
98 size_t content_length;
99 size_t capacity;
100 unsigned char *buffer;
101} mbedtls_test_ssl_buffer;
102
103/*
104 * Context for a message metadata queue (fifo) that is on top of the ring buffer.
105 */
106typedef struct mbedtls_test_ssl_message_queue {
107 size_t *messages;
108 int pos;
109 int num;
110 int capacity;
111} mbedtls_test_ssl_message_queue;
112
113/*
114 * Context for the I/O callbacks simulating network connection.
115 */
116
117#define MBEDTLS_MOCK_SOCKET_CONNECTED 1
118
119typedef struct mbedtls_test_mock_socket {
120 int status;
121 mbedtls_test_ssl_buffer *input;
122 mbedtls_test_ssl_buffer *output;
123 struct mbedtls_test_mock_socket *peer;
124} mbedtls_test_mock_socket;
125
126/* Errors used in the message socket mocks */
127
128#define MBEDTLS_TEST_ERROR_CONTEXT_ERROR -55
129#define MBEDTLS_TEST_ERROR_SEND_FAILED -66
130#define MBEDTLS_TEST_ERROR_RECV_FAILED -77
131
132/*
133 * Structure used as an addon, or a wrapper, around the mocked sockets.
134 * Contains an input queue, to which the other socket pushes metadata,
135 * and an output queue, to which this one pushes metadata. This context is
136 * considered as an owner of the input queue only, which is initialized and
137 * freed in the respective setup and free calls.
138 */
139typedef struct mbedtls_test_message_socket_context {
140 mbedtls_test_ssl_message_queue *queue_input;
141 mbedtls_test_ssl_message_queue *queue_output;
142 mbedtls_test_mock_socket *socket;
143} mbedtls_test_message_socket_context;
144
145#if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) && \
146 defined(MBEDTLS_CERTS_C) && \
147 defined(MBEDTLS_ENTROPY_C) && \
148 defined(MBEDTLS_CTR_DRBG_C)
149
150/*
151 * Structure with endpoint's certificates for SSL communication tests.
152 */
153typedef struct mbedtls_test_ssl_endpoint_certificate {
154 mbedtls_x509_crt *ca_cert;
155 mbedtls_x509_crt *cert;
156 mbedtls_pk_context *pkey;
157} mbedtls_test_ssl_endpoint_certificate;
158
159/*
160 * Endpoint structure for SSL communication tests.
161 */
162typedef struct mbedtls_test_ssl_endpoint {
163 const char *name;
164 mbedtls_ssl_context ssl;
165 mbedtls_ssl_config conf;
166 mbedtls_ctr_drbg_context ctr_drbg;
167 mbedtls_entropy_context entropy;
168 mbedtls_test_mock_socket socket;
169 mbedtls_test_ssl_endpoint_certificate cert;
170} mbedtls_test_ssl_endpoint;
171
172#endif /* MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED && MBEDTLS_CERTS_C &&
173 MBEDTLS_ENTROPY_C && MBEDTLS_CTR_DRBG_C */
174
Yanray Wang4323e452023-03-14 16:52:06 +0800175/*
176 * This function can be passed to mbedtls to receive output logs from it. In
177 * this case, it will count the instances of a mbedtls_test_ssl_log_pattern
178 * in the received logged messages.
179 */
180void mbedtls_test_ssl_log_analyzer(void *ctx, int level,
181 const char *file, int line,
182 const char *str);
183
184void mbedtls_test_init_handshake_options(
185 mbedtls_test_handshake_test_options *opts);
186
187/*
188 * Initialises \p buf. After calling this function it is safe to call
189 * `mbedtls_test_ssl_buffer_free()` on \p buf.
190 */
191void mbedtls_test_ssl_buffer_init(mbedtls_test_ssl_buffer *buf);
192
193/*
194 * Sets up \p buf. After calling this function it is safe to call
195 * `mbedtls_test_ssl_buffer_put()` and `mbedtls_test_ssl_buffer_get()`
196 * on \p buf.
197 */
198int mbedtls_test_ssl_buffer_setup(mbedtls_test_ssl_buffer *buf,
199 size_t capacity);
200
201void mbedtls_test_ssl_buffer_free(mbedtls_test_ssl_buffer *buf);
202
203/*
204 * Puts \p input_len bytes from the \p input buffer into the ring buffer \p buf.
205 *
206 * \p buf must have been initialized and set up by calling
207 * `mbedtls_test_ssl_buffer_init()` and `mbedtls_test_ssl_buffer_setup()`.
208 *
209 * \retval \p input_len, if the data fits.
210 * \retval 0 <= value < \p input_len, if the data does not fit.
211 * \retval -1, if \p buf is NULL, it hasn't been set up or \p input_len is not
212 * zero and \p input is NULL.
213 */
214int mbedtls_test_ssl_buffer_put(mbedtls_test_ssl_buffer *buf,
215 const unsigned char *input, size_t input_len);
216
217/*
218 * Gets \p output_len bytes from the ring buffer \p buf into the
219 * \p output buffer. The output buffer can be NULL, in this case a part of the
220 * ring buffer will be dropped, if the requested length is available.
221 *
222 * \p buf must have been initialized and set up by calling
223 * `mbedtls_test_ssl_buffer_init()` and `mbedtls_test_ssl_buffer_setup()`.
224 *
225 * \retval \p output_len, if the data is available.
226 * \retval 0 <= value < \p output_len, if the data is not available.
227 * \retval -1, if \buf is NULL or it hasn't been set up.
228 */
229int mbedtls_test_ssl_buffer_get(mbedtls_test_ssl_buffer *buf,
230 unsigned char *output, size_t output_len);
231
232/*
233 * Errors used in the message transport mock tests
234 */
235 #define MBEDTLS_TEST_ERROR_ARG_NULL -11
236 #define MBEDTLS_TEST_ERROR_MESSAGE_TRUNCATED -44
237
238/*
239 * Setup and free functions for the message metadata queue.
240 *
241 * \p capacity describes the number of message metadata chunks that can be held
242 * within the queue.
243 *
244 * \retval 0, if a metadata queue of a given length can be allocated.
245 * \retval MBEDTLS_ERR_SSL_ALLOC_FAILED, if allocation failed.
246 */
247int mbedtls_test_ssl_message_queue_setup(
248 mbedtls_test_ssl_message_queue *queue, size_t capacity);
249
250void mbedtls_test_ssl_message_queue_free(
251 mbedtls_test_ssl_message_queue *queue);
252
253/*
254 * Push message length information onto the message metadata queue.
255 * This will become the last element to leave it (fifo).
256 *
257 * \retval MBEDTLS_TEST_ERROR_ARG_NULL, if the queue is null.
258 * \retval MBEDTLS_ERR_SSL_WANT_WRITE, if the queue is full.
259 * \retval \p len, if the push was successful.
260 */
261int mbedtls_test_ssl_message_queue_push_info(
262 mbedtls_test_ssl_message_queue *queue, size_t len);
263
264/*
265 * Pop information about the next message length from the queue. This will be
266 * the oldest inserted message length(fifo). \p msg_len can be null, in which
267 * case the data will be popped from the queue but not copied anywhere.
268 *
269 * \retval MBEDTLS_TEST_ERROR_ARG_NULL, if the queue is null.
270 * \retval MBEDTLS_ERR_SSL_WANT_READ, if the queue is empty.
271 * \retval message length, if the pop was successful, up to the given
272 \p buf_len.
273 */
274int mbedtls_test_ssl_message_queue_pop_info(
275 mbedtls_test_ssl_message_queue *queue, size_t buf_len);
276
277/*
278 * Setup and teardown functions for mock sockets.
279 */
280void mbedtls_mock_socket_init(mbedtls_test_mock_socket *socket);
281
282/*
283 * Closes the socket \p socket.
284 *
285 * \p socket must have been previously initialized by calling
286 * mbedtls_mock_socket_init().
287 *
288 * This function frees all allocated resources and both sockets are aware of the
289 * new connection state.
290 *
291 * That is, this function does not simulate half-open TCP connections and the
292 * phenomenon that when closing a UDP connection the peer is not aware of the
293 * connection having been closed.
294 */
295void mbedtls_test_mock_socket_close(mbedtls_test_mock_socket *socket);
296
297/*
298 * Establishes a connection between \p peer1 and \p peer2.
299 *
300 * \p peer1 and \p peer2 must have been previously initialized by calling
301 * mbedtls_mock_socket_init().
302 *
303 * The capacities of the internal buffers are set to \p bufsize. Setting this to
304 * the correct value allows for simulation of MTU, sanity testing the mock
305 * implementation and mocking TCP connections with lower memory cost.
306 */
307int mbedtls_test_mock_socket_connect(mbedtls_test_mock_socket *peer1,
308 mbedtls_test_mock_socket *peer2,
309 size_t bufsize);
310
311/*
312 * Callbacks for simulating blocking I/O over connection-oriented transport.
313 */
314int mbedtls_test_mock_tcp_send_b(void *ctx,
315 const unsigned char *buf, size_t len);
316
317int mbedtls_test_mock_tcp_recv_b(void *ctx, unsigned char *buf, size_t len);
318
319/*
320 * Callbacks for simulating non-blocking I/O over connection-oriented transport.
321 */
322int mbedtls_test_mock_tcp_send_nb(void *ctx,
323 const unsigned char *buf, size_t len);
324
325int mbedtls_test_mock_tcp_recv_nb(void *ctx, unsigned char *buf, size_t len);
326
327void mbedtls_test_message_socket_init(
328 mbedtls_test_message_socket_context *ctx);
329
330/*
331 * Setup a given message socket context including initialization of
332 * input/output queues to a chosen capacity of messages. Also set the
333 * corresponding mock socket.
334 *
335 * \retval 0, if everything succeeds.
336 * \retval MBEDTLS_ERR_SSL_ALLOC_FAILED, if allocation of a message
337 * queue failed.
338 */
339int mbedtls_test_message_socket_setup(
340 mbedtls_test_ssl_message_queue *queue_input,
341 mbedtls_test_ssl_message_queue *queue_output,
342 size_t queue_capacity,
343 mbedtls_test_mock_socket *socket,
344 mbedtls_test_message_socket_context *ctx);
345
346/*
347 * Close a given message socket context, along with the socket itself. Free the
348 * memory allocated by the input queue.
349 */
350void mbedtls_test_message_socket_close(
351 mbedtls_test_message_socket_context *ctx);
352
353/*
354 * Send one message through a given message socket context.
355 *
356 * \retval \p len, if everything succeeds.
357 * \retval MBEDTLS_TEST_ERROR_CONTEXT_ERROR, if any of the needed context
358 * elements or the context itself is null.
359 * \retval MBEDTLS_TEST_ERROR_SEND_FAILED if
360 * mbedtls_test_mock_tcp_send_b failed.
361 * \retval MBEDTLS_ERR_SSL_WANT_WRITE, if the output queue is full.
362 *
363 * This function will also return any error from
364 * mbedtls_test_ssl_message_queue_push_info.
365 */
366int mbedtls_test_mock_tcp_send_msg(void *ctx,
367 const unsigned char *buf, size_t len);
368
369/*
370 * Receive one message from a given message socket context and return message
371 * length or an error.
372 *
373 * \retval message length, if everything succeeds.
374 * \retval MBEDTLS_TEST_ERROR_CONTEXT_ERROR, if any of the needed context
375 * elements or the context itself is null.
376 * \retval MBEDTLS_TEST_ERROR_RECV_FAILED if
377 * mbedtls_test_mock_tcp_recv_b failed.
378 *
379 * This function will also return any error other than
380 * MBEDTLS_TEST_ERROR_MESSAGE_TRUNCATED from
381 * mbedtls_test_message_queue_peek_info.
382 */
383int mbedtls_test_mock_tcp_recv_msg(void *ctx,
384 unsigned char *buf, size_t buf_len);
385
386#if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) && \
387 defined(MBEDTLS_CERTS_C) && \
388 defined(MBEDTLS_ENTROPY_C) && \
389 defined(MBEDTLS_CTR_DRBG_C)
390
391/*
392 * Initializes \p ep_cert structure and assigns it to endpoint
393 * represented by \p ep.
394 *
395 * \retval 0 on success, otherwise error code.
396 */
397int mbedtls_test_ssl_endpoint_certificate_init(mbedtls_test_ssl_endpoint *ep,
398 int pk_alg);
399
400/*
401 * Initializes \p ep structure. It is important to call
402 * `mbedtls_test_ssl_endpoint_free()` after calling this function
403 * even if it fails.
404 *
405 * \p endpoint_type must be set as MBEDTLS_SSL_IS_SERVER or
406 * MBEDTLS_SSL_IS_CLIENT.
407 * \p pk_alg the algorithm to use, currently only MBEDTLS_PK_RSA and
408 * MBEDTLS_PK_ECDSA are supported.
409 * \p dtls_context - in case of DTLS - this is the context handling metadata.
410 * \p input_queue - used only in case of DTLS.
411 * \p output_queue - used only in case of DTLS.
412 *
413 * \retval 0 on success, otherwise error code.
414 */
415int mbedtls_test_ssl_endpoint_init(
416 mbedtls_test_ssl_endpoint *ep, int endpoint_type, int pk_alg,
417 mbedtls_test_message_socket_context *dtls_context,
418 mbedtls_test_ssl_message_queue *input_queue,
419 mbedtls_test_ssl_message_queue *output_queue,
420 const mbedtls_ecp_group_id *curves);
421
422/*
423 * Deinitializes endpoint represented by \p ep.
424 */
425void mbedtls_test_ssl_endpoint_free(
426 mbedtls_test_ssl_endpoint *ep,
427 mbedtls_test_message_socket_context *context);
428
429/*
430 * This function moves ssl handshake from \p ssl to prescribed \p state.
431 * /p second_ssl is used as second endpoint and their sockets have to be
432 * connected before calling this function.
433 *
434 * \retval 0 on success, otherwise error code.
435 */
436int mbedtls_test_move_handshake_to_state(mbedtls_ssl_context *ssl,
437 mbedtls_ssl_context *second_ssl,
438 int state);
439
Yanray Wang1ef77c02023-03-14 16:59:00 +0800440#endif /* MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED && MBEDTLS_CERTS_C &&
441 MBEDTLS_ENTROPY_C && MBEDTLS_CTR_DRBG_C */
442
443/*
444 * Helper function setting up inverse record transformations
445 * using given cipher, hash, EtM mode, authentication tag length,
446 * and version.
447 */
448
449#define CHK(x) \
450 do \
451 { \
452 if (!(x)) \
453 { \
454 ret = -1; \
455 goto cleanup; \
456 } \
457 } while (0)
Yanray Wang4323e452023-03-14 16:52:06 +0800458
Yanray Wange62e8a12023-03-15 16:39:05 +0800459#if MBEDTLS_SSL_CID_OUT_LEN_MAX > MBEDTLS_SSL_CID_IN_LEN_MAX
460#define SSL_CID_LEN_MIN MBEDTLS_SSL_CID_IN_LEN_MAX
461#else
462#define SSL_CID_LEN_MIN MBEDTLS_SSL_CID_OUT_LEN_MAX
463#endif
464
Yanray Wang4323e452023-03-14 16:52:06 +0800465int mbedtls_test_ssl_build_transforms(mbedtls_ssl_transform *t_in,
466 mbedtls_ssl_transform *t_out,
467 int cipher_type, int hash_id,
468 int etm, int tag_mode, int ver,
469 size_t cid0_len,
470 size_t cid1_len);
471
472/*
473 * Populate a session structure for serialization tests.
474 * Choose dummy values, mostly non-0 to distinguish from the init default.
475 */
476int mbedtls_test_ssl_populate_session(mbedtls_ssl_session *session,
477 int ticket_len,
478 const char *crt_file);
479
480/*
481 * Perform data exchanging between \p ssl_1 and \p ssl_2 and check if the
482 * message was sent in the correct number of fragments.
483 *
484 * /p ssl_1 and /p ssl_2 Endpoints represented by mbedtls_ssl_context. Both
485 * of them must be initialized and connected
486 * beforehand.
487 * /p msg_len_1 and /p msg_len_2 specify the size of the message to send.
488 * /p expected_fragments_1 and /p expected_fragments_2 determine in how many
489 * fragments the message should be sent.
490 * expected_fragments is 0: can be used for DTLS testing while the message
491 * size is larger than MFL. In that case the message
492 * cannot be fragmented and sent to the second
493 * endpoint.
494 * This value can be used for negative tests.
495 * expected_fragments is 1: can be used for TLS/DTLS testing while the
496 * message size is below MFL
497 * expected_fragments > 1: can be used for TLS testing while the message
498 * size is larger than MFL
499 *
500 * \retval 0 on success, otherwise error code.
501 */
502int mbedtls_exchange_data(mbedtls_ssl_context *ssl_1,
503 int msg_len_1, const int expected_fragments_1,
504 mbedtls_ssl_context *ssl_2,
505 int msg_len_2, const int expected_fragments_2);
506
507#if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) && \
508 defined(MBEDTLS_CERTS_C) && \
509 defined(MBEDTLS_ENTROPY_C) && \
510 defined(MBEDTLS_CTR_DRBG_C)
511void mbedtls_test_ssl_perform_handshake(
512 mbedtls_test_handshake_test_options *options);
Yanray Wang1ef77c02023-03-14 16:59:00 +0800513#endif /* MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED && MBEDTLS_CERTS_C &&
514 MBEDTLS_ENTROPY_C && MBEDTLS_CTR_DRBG_C */
Yanray Wang4323e452023-03-14 16:52:06 +0800515#endif /* MBEDTLS_SSL_TLS_C */
516
Yanray Wang5fce1452022-10-24 14:42:01 +0800517#endif /* SSL_HELPERS_H */