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