1 /** \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 OR GPL-2.0-or-later 9 */ 10 11 #ifndef SSL_HELPERS_H 12 #define SSL_HELPERS_H 13 14 #include "mbedtls/build_info.h" 15 16 #include <string.h> 17 18 #include <test/helpers.h> 19 #include <test/macros.h> 20 #include <test/random.h> 21 #include <test/psa_crypto_helpers.h> 22 23 #if defined(MBEDTLS_SSL_TLS_C) 24 #include <ssl_misc.h> 25 #include <mbedtls/timing.h> 26 #include <mbedtls/debug.h> 27 28 #include "test/certs.h" 29 30 #if defined(MBEDTLS_SSL_CACHE_C) 31 #include "mbedtls/ssl_cache.h" 32 #endif 33 34 #define PSA_TO_MBEDTLS_ERR(status) PSA_TO_MBEDTLS_ERR_LIST(status, \ 35 psa_to_ssl_errors, \ 36 psa_generic_status_to_mbedtls) 37 38 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) 39 #if defined(PSA_WANT_KEY_TYPE_AES) 40 #if defined(PSA_WANT_ALG_GCM) 41 #if defined(PSA_WANT_ALG_SHA_384) 42 #define MBEDTLS_TEST_HAS_TLS1_3_AES_256_GCM_SHA384 43 #endif 44 #if defined(PSA_WANT_ALG_SHA_256) 45 #define MBEDTLS_TEST_HAS_TLS1_3_AES_128_GCM_SHA256 46 #endif 47 #endif /* PSA_WANT_ALG_GCM */ 48 #if defined(PSA_WANT_ALG_CCM) && defined(PSA_WANT_ALG_SHA_256) 49 #define MBEDTLS_TEST_HAS_TLS1_3_AES_128_CCM_SHA256 50 #define MBEDTLS_TEST_HAS_TLS1_3_AES_128_CCM_8_SHA256 51 #endif 52 #endif /* PSA_WANT_KEY_TYPE_AES */ 53 #if defined(PSA_WANT_ALG_CHACHA20_POLY1305) && defined(PSA_WANT_ALG_SHA_256) 54 #define MBEDTLS_TEST_HAS_TLS1_3_CHACHA20_POLY1305_SHA256 55 #endif 56 57 #if defined(MBEDTLS_TEST_HAS_TLS1_3_AES_256_GCM_SHA384) || \ 58 defined(MBEDTLS_TEST_HAS_TLS1_3_AES_128_GCM_SHA256) || \ 59 defined(MBEDTLS_TEST_HAS_TLS1_3_AES_128_CCM_SHA256) || \ 60 defined(MBEDTLS_TEST_HAS_TLS1_3_AES_128_CCM_8_SHA256) || \ 61 defined(MBEDTLS_TEST_HAS_TLS1_3_CHACHA20_POLY1305_SHA256) 62 #define MBEDTLS_TEST_AT_LEAST_ONE_TLS1_3_CIPHERSUITE 63 #endif 64 65 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ 66 67 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) 68 #define MBEDTLS_CAN_HANDLE_RSA_TEST_KEY 69 #endif 70 71 #if defined(PSA_WANT_ALG_GCM) || \ 72 defined(PSA_WANT_ALG_CCM) || \ 73 defined(PSA_WANT_ALG_CHACHA20_POLY1305) 74 #define MBEDTLS_TEST_HAS_AEAD_ALG 75 #endif 76 77 enum { 78 #define MBEDTLS_SSL_TLS1_3_LABEL(name, string) \ 79 tls13_label_ ## name, 80 MBEDTLS_SSL_TLS1_3_LABEL_LIST 81 #undef MBEDTLS_SSL_TLS1_3_LABEL 82 }; 83 84 #if defined(MBEDTLS_SSL_ALPN) 85 #define MBEDTLS_TEST_MAX_ALPN_LIST_SIZE 10 86 #endif 87 88 typedef struct mbedtls_test_ssl_log_pattern { 89 const char *pattern; 90 size_t counter; 91 } mbedtls_test_ssl_log_pattern; 92 93 typedef struct mbedtls_test_handshake_test_options { 94 const char *cipher; 95 uint16_t *group_list; 96 mbedtls_ssl_protocol_version client_min_version; 97 mbedtls_ssl_protocol_version client_max_version; 98 mbedtls_ssl_protocol_version server_min_version; 99 mbedtls_ssl_protocol_version server_max_version; 100 mbedtls_ssl_protocol_version expected_negotiated_version; 101 int expected_handshake_result; 102 int expected_ciphersuite; 103 int pk_alg; 104 int opaque_alg; 105 int opaque_alg2; 106 int opaque_usage; 107 data_t *psk_str; 108 int dtls; 109 int srv_auth_mode; 110 int serialize; 111 int mfl; 112 int cli_msg_len; 113 int srv_msg_len; 114 int expected_cli_fragments; 115 int expected_srv_fragments; 116 int renegotiate; 117 int legacy_renegotiation; 118 void *srv_log_obj; 119 void *cli_log_obj; 120 void (*srv_log_fun)(void *, int, const char *, int, const char *); 121 void (*cli_log_fun)(void *, int, const char *, int, const char *); 122 int resize_buffers; 123 int early_data; 124 int max_early_data_size; 125 #if defined(MBEDTLS_SSL_CACHE_C) 126 mbedtls_ssl_cache_context *cache; 127 #endif 128 #if defined(MBEDTLS_SSL_ALPN) 129 const char *alpn_list[MBEDTLS_TEST_MAX_ALPN_LIST_SIZE]; 130 #endif 131 } mbedtls_test_handshake_test_options; 132 133 /* 134 * Buffer structure for custom I/O callbacks. 135 */ 136 typedef struct mbedtls_test_ssl_buffer { 137 size_t start; 138 size_t content_length; 139 size_t capacity; 140 unsigned char *buffer; 141 } mbedtls_test_ssl_buffer; 142 143 /* 144 * Context for a message metadata queue (fifo) that is on top of the ring buffer. 145 */ 146 typedef struct mbedtls_test_ssl_message_queue { 147 size_t *messages; 148 int pos; 149 int num; 150 int capacity; 151 } mbedtls_test_ssl_message_queue; 152 153 /* 154 * Context for the I/O callbacks simulating network connection. 155 */ 156 157 #define MBEDTLS_MOCK_SOCKET_CONNECTED 1 158 159 typedef struct mbedtls_test_mock_socket { 160 int status; 161 mbedtls_test_ssl_buffer *input; 162 mbedtls_test_ssl_buffer *output; 163 struct mbedtls_test_mock_socket *peer; 164 } mbedtls_test_mock_socket; 165 166 /* Errors used in the message socket mocks */ 167 168 #define MBEDTLS_TEST_ERROR_CONTEXT_ERROR -55 169 #define MBEDTLS_TEST_ERROR_SEND_FAILED -66 170 #define MBEDTLS_TEST_ERROR_RECV_FAILED -77 171 172 /* 173 * Structure used as an addon, or a wrapper, around the mocked sockets. 174 * Contains an input queue, to which the other socket pushes metadata, 175 * and an output queue, to which this one pushes metadata. This context is 176 * considered as an owner of the input queue only, which is initialized and 177 * freed in the respective setup and free calls. 178 */ 179 typedef struct mbedtls_test_message_socket_context { 180 mbedtls_test_ssl_message_queue *queue_input; 181 mbedtls_test_ssl_message_queue *queue_output; 182 mbedtls_test_mock_socket *socket; 183 } mbedtls_test_message_socket_context; 184 185 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED) 186 187 /* 188 * Endpoint structure for SSL communication tests. 189 */ 190 typedef struct mbedtls_test_ssl_endpoint { 191 const char *name; 192 mbedtls_ssl_context ssl; 193 mbedtls_ssl_config conf; 194 mbedtls_test_mock_socket socket; 195 uintptr_t user_data_cookie; /* A unique value associated with this endpoint */ 196 197 /* Objects only used by DTLS. 198 * They should be guarded by MBEDTLS_SSL_PROTO_DTLS, but 199 * currently aren't because some code accesses them without guards. */ 200 mbedtls_test_message_socket_context dtls_context; 201 #if defined(MBEDTLS_TIMING_C) 202 mbedtls_timing_delay_context timer; 203 #endif 204 205 /* Objects owned by the endpoint */ 206 int *ciphersuites; 207 mbedtls_test_ssl_message_queue queue_input; 208 mbedtls_x509_crt *ca_chain; 209 mbedtls_x509_crt *cert; 210 mbedtls_pk_context *pkey; 211 } mbedtls_test_ssl_endpoint; 212 213 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */ 214 215 /* 216 * Random number generator aimed for TLS unitary tests. Its main purpose is to 217 * simplify the set-up of a random number generator for TLS 218 * unitary tests: no need to set up a good entropy source for example. 219 */ 220 int mbedtls_test_random(void *p_rng, unsigned char *output, size_t output_len); 221 222 /* 223 * This function can be passed to mbedtls to receive output logs from it. In 224 * this case, it will count the instances of a mbedtls_test_ssl_log_pattern 225 * in the received logged messages. 226 */ 227 void mbedtls_test_ssl_log_analyzer(void *ctx, int level, 228 const char *file, int line, 229 const char *str); 230 231 void mbedtls_test_init_handshake_options( 232 mbedtls_test_handshake_test_options *opts); 233 234 void mbedtls_test_free_handshake_options( 235 mbedtls_test_handshake_test_options *opts); 236 237 /* 238 * Initialises \p buf. After calling this function it is safe to call 239 * `mbedtls_test_ssl_buffer_free()` on \p buf. 240 */ 241 void mbedtls_test_ssl_buffer_init(mbedtls_test_ssl_buffer *buf); 242 243 /* 244 * Sets up \p buf. After calling this function it is safe to call 245 * `mbedtls_test_ssl_buffer_put()` and `mbedtls_test_ssl_buffer_get()` 246 * on \p buf. 247 */ 248 int mbedtls_test_ssl_buffer_setup(mbedtls_test_ssl_buffer *buf, 249 size_t capacity); 250 251 void mbedtls_test_ssl_buffer_free(mbedtls_test_ssl_buffer *buf); 252 253 /* 254 * Puts \p input_len bytes from the \p input buffer into the ring buffer \p buf. 255 * 256 * \p buf must have been initialized and set up by calling 257 * `mbedtls_test_ssl_buffer_init()` and `mbedtls_test_ssl_buffer_setup()`. 258 * 259 * \retval \p input_len, if the data fits. 260 * \retval 0 <= value < \p input_len, if the data does not fit. 261 * \retval -1, if \p buf is NULL, it hasn't been set up or \p input_len is not 262 * zero and \p input is NULL. 263 */ 264 int mbedtls_test_ssl_buffer_put(mbedtls_test_ssl_buffer *buf, 265 const unsigned char *input, size_t input_len); 266 267 /* 268 * Gets \p output_len bytes from the ring buffer \p buf into the 269 * \p output buffer. The output buffer can be NULL, in this case a part of the 270 * ring buffer will be dropped, if the requested length is available. 271 * 272 * \p buf must have been initialized and set up by calling 273 * `mbedtls_test_ssl_buffer_init()` and `mbedtls_test_ssl_buffer_setup()`. 274 * 275 * \retval \p output_len, if the data is available. 276 * \retval 0 <= value < \p output_len, if the data is not available. 277 * \retval -1, if \buf is NULL or it hasn't been set up. 278 */ 279 int mbedtls_test_ssl_buffer_get(mbedtls_test_ssl_buffer *buf, 280 unsigned char *output, size_t output_len); 281 282 /* 283 * Errors used in the message transport mock tests 284 */ 285 #define MBEDTLS_TEST_ERROR_ARG_NULL -11 286 #define MBEDTLS_TEST_ERROR_MESSAGE_TRUNCATED -44 287 288 /* 289 * Setup and free functions for the message metadata queue. 290 * 291 * \p capacity describes the number of message metadata chunks that can be held 292 * within the queue. 293 * 294 * \retval 0, if a metadata queue of a given length can be allocated. 295 * \retval MBEDTLS_ERR_SSL_ALLOC_FAILED, if allocation failed. 296 */ 297 int mbedtls_test_ssl_message_queue_setup( 298 mbedtls_test_ssl_message_queue *queue, size_t capacity); 299 300 void mbedtls_test_ssl_message_queue_free( 301 mbedtls_test_ssl_message_queue *queue); 302 303 /* 304 * Push message length information onto the message metadata queue. 305 * This will become the last element to leave it (fifo). 306 * 307 * \retval MBEDTLS_TEST_ERROR_ARG_NULL, if the queue is null. 308 * \retval MBEDTLS_ERR_SSL_WANT_WRITE, if the queue is full. 309 * \retval \p len, if the push was successful. 310 */ 311 int mbedtls_test_ssl_message_queue_push_info( 312 mbedtls_test_ssl_message_queue *queue, size_t len); 313 314 /* 315 * Pop information about the next message length from the queue. This will be 316 * the oldest inserted message length(fifo). \p msg_len can be null, in which 317 * case the data will be popped from the queue but not copied anywhere. 318 * 319 * \retval MBEDTLS_TEST_ERROR_ARG_NULL, if the queue is null. 320 * \retval MBEDTLS_ERR_SSL_WANT_READ, if the queue is empty. 321 * \retval message length, if the pop was successful, up to the given 322 \p buf_len. 323 */ 324 int mbedtls_test_ssl_message_queue_pop_info( 325 mbedtls_test_ssl_message_queue *queue, size_t buf_len); 326 327 /* 328 * Setup and teardown functions for mock sockets. 329 */ 330 void mbedtls_test_mock_socket_init(mbedtls_test_mock_socket *socket); 331 332 /* 333 * Closes the socket \p socket. 334 * 335 * \p socket must have been previously initialized by calling 336 * mbedtls_test_mock_socket_init(). 337 * 338 * This function frees all allocated resources and both sockets are aware of the 339 * new connection state. 340 * 341 * That is, this function does not simulate half-open TCP connections and the 342 * phenomenon that when closing a UDP connection the peer is not aware of the 343 * connection having been closed. 344 */ 345 void mbedtls_test_mock_socket_close(mbedtls_test_mock_socket *socket); 346 347 /* 348 * Establishes a connection between \p peer1 and \p peer2. 349 * 350 * \p peer1 and \p peer2 must have been previously initialized by calling 351 * mbedtls_test_mock_socket_init(). 352 * 353 * The capacities of the internal buffers are set to \p bufsize. Setting this to 354 * the correct value allows for simulation of MTU, sanity testing the mock 355 * implementation and mocking TCP connections with lower memory cost. 356 */ 357 int mbedtls_test_mock_socket_connect(mbedtls_test_mock_socket *peer1, 358 mbedtls_test_mock_socket *peer2, 359 size_t bufsize); 360 361 362 /* 363 * Callbacks for simulating blocking I/O over connection-oriented transport. 364 */ 365 int mbedtls_test_mock_tcp_send_b(void *ctx, 366 const unsigned char *buf, size_t len); 367 368 int mbedtls_test_mock_tcp_recv_b(void *ctx, unsigned char *buf, size_t len); 369 370 /* 371 * Callbacks for simulating non-blocking I/O over connection-oriented transport. 372 */ 373 int mbedtls_test_mock_tcp_send_nb(void *ctx, 374 const unsigned char *buf, size_t len); 375 376 int mbedtls_test_mock_tcp_recv_nb(void *ctx, unsigned char *buf, size_t len); 377 378 void mbedtls_test_message_socket_init( 379 mbedtls_test_message_socket_context *ctx); 380 381 /* 382 * Setup a given message socket context including initialization of 383 * input/output queues to a chosen capacity of messages. Also set the 384 * corresponding mock socket. 385 * 386 * \retval 0, if everything succeeds. 387 * \retval MBEDTLS_ERR_SSL_ALLOC_FAILED, if allocation of a message 388 * queue failed. 389 */ 390 int mbedtls_test_message_socket_setup( 391 mbedtls_test_ssl_message_queue *queue_input, 392 mbedtls_test_ssl_message_queue *queue_output, 393 size_t queue_capacity, 394 mbedtls_test_mock_socket *socket, 395 mbedtls_test_message_socket_context *ctx); 396 397 /* 398 * Close a given message socket context, along with the socket itself. Free the 399 * memory allocated by the input queue. 400 */ 401 void mbedtls_test_message_socket_close( 402 mbedtls_test_message_socket_context *ctx); 403 404 /* 405 * Send one message through a given message socket context. 406 * 407 * \retval \p len, if everything succeeds. 408 * \retval MBEDTLS_TEST_ERROR_CONTEXT_ERROR, if any of the needed context 409 * elements or the context itself is null. 410 * \retval MBEDTLS_TEST_ERROR_SEND_FAILED if 411 * mbedtls_test_mock_tcp_send_b failed. 412 * \retval MBEDTLS_ERR_SSL_WANT_WRITE, if the output queue is full. 413 * 414 * This function will also return any error from 415 * mbedtls_test_ssl_message_queue_push_info. 416 */ 417 int mbedtls_test_mock_tcp_send_msg(void *ctx, 418 const unsigned char *buf, size_t len); 419 420 /* 421 * Receive one message from a given message socket context and return message 422 * length or an error. 423 * 424 * \retval message length, if everything succeeds. 425 * \retval MBEDTLS_TEST_ERROR_CONTEXT_ERROR, if any of the needed context 426 * elements or the context itself is null. 427 * \retval MBEDTLS_TEST_ERROR_RECV_FAILED if 428 * mbedtls_test_mock_tcp_recv_b failed. 429 * 430 * This function will also return any error other than 431 * MBEDTLS_TEST_ERROR_MESSAGE_TRUNCATED from test_ssl_message_queue_peek_info. 432 */ 433 int mbedtls_test_mock_tcp_recv_msg(void *ctx, 434 unsigned char *buf, size_t buf_len); 435 436 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED) 437 438 /* 439 * Load default CA certificates and endpoint keys into \p ep. 440 * 441 * \retval 0 on success, otherwise error code. 442 */ 443 int mbedtls_test_ssl_endpoint_certificate_init(mbedtls_test_ssl_endpoint *ep, 444 int pk_alg, 445 int opaque_alg, int opaque_alg2, 446 int opaque_usage); 447 448 /** Initialize the configuration in an SSL endpoint structure. 449 * 450 * \note You must call `mbedtls_test_ssl_endpoint_free()` after 451 * calling this function, even if it fails. This is necessary to 452 * free data that may have been stored in the endpoint structure. 453 * 454 * \param[out] ep The endpoint structure to configure. 455 * \param endpoint_type #MBEDTLS_SSL_IS_SERVER or #MBEDTLS_SSL_IS_CLIENT. 456 * \param[in] options The options to use for configuring the endpoint 457 * structure. 458 * 459 * \retval 0 on success, otherwise error code. 460 */ 461 int mbedtls_test_ssl_endpoint_init_conf( 462 mbedtls_test_ssl_endpoint *ep, int endpoint_type, 463 const mbedtls_test_handshake_test_options *options); 464 465 /** Initialize the session context in an endpoint structure. 466 * 467 * \note The endpoint structure must have been set up with 468 * mbedtls_test_ssl_endpoint_init_conf() with the same \p options. 469 * Between calling mbedtls_test_ssl_endpoint_init_conf() and 470 * mbedtls_test_ssl_endpoint_init_ssl(), you may configure `ep->ssl` 471 * further if you know what you're doing. 472 * 473 * \note You must call `mbedtls_test_ssl_endpoint_free()` after 474 * calling this function, even if it fails. This is necessary to 475 * free data that may have been stored in the endpoint structure. 476 * 477 * \param[out] ep The endpoint structure to set up. 478 * \param[in] options The options used for configuring the endpoint 479 * structure. 480 * 481 * \retval 0 on success, otherwise error code. 482 */ 483 int mbedtls_test_ssl_endpoint_init_ssl( 484 mbedtls_test_ssl_endpoint *ep, 485 const mbedtls_test_handshake_test_options *options); 486 487 /** Initialize the configuration and a context in an SSL endpoint structure. 488 * 489 * This function is equivalent to calling 490 * mbedtls_test_ssl_endpoint_init_conf() followed by 491 * mbedtls_test_ssl_endpoint_init_ssl(). 492 * 493 * \note You must call `mbedtls_test_ssl_endpoint_free()` after 494 * calling this function, even if it fails. This is necessary to 495 * free data that may have been stored in the endpoint structure. 496 * 497 * \param[out] ep The endpoint structure to configure. 498 * \param endpoint_type #MBEDTLS_SSL_IS_SERVER or #MBEDTLS_SSL_IS_CLIENT. 499 * \param[in] options The options to use for configuring the endpoint 500 * structure. 501 * 502 * \retval 0 on success, otherwise error code. 503 */ 504 int mbedtls_test_ssl_endpoint_init( 505 mbedtls_test_ssl_endpoint *ep, int endpoint_type, 506 const mbedtls_test_handshake_test_options *options); 507 508 /* 509 * Deinitializes endpoint represented by \p ep. 510 */ 511 void mbedtls_test_ssl_endpoint_free(mbedtls_test_ssl_endpoint *ep); 512 513 /* Join a DTLS client with a DTLS server. 514 * 515 * You must call this function after setting up the endpoint objects 516 * and before starting a DTLS handshake. 517 * 518 * \param client The client. It must have been set up with 519 * mbedtls_test_ssl_endpoint_init(). 520 * \param server The server. It must have been set up with 521 * mbedtls_test_ssl_endpoint_init(). 522 * 523 * \retval 0 on success, otherwise error code. 524 */ 525 int mbedtls_test_ssl_dtls_join_endpoints(mbedtls_test_ssl_endpoint *client, 526 mbedtls_test_ssl_endpoint *server); 527 528 /* 529 * This function moves ssl handshake from \p ssl to prescribed \p state. 530 * /p second_ssl is used as second endpoint and their sockets have to be 531 * connected before calling this function. 532 * 533 * For example, to perform a full handshake: 534 * ``` 535 * mbedtls_test_move_handshake_to_state( 536 * &server.ssl, &client.ssl, 537 * MBEDTLS_SSL_HANDSHAKE_OVER); 538 * mbedtls_test_move_handshake_to_state( 539 * &client.ssl, &server.ssl, 540 * MBEDTLS_SSL_HANDSHAKE_OVER); 541 * ``` 542 * Note that you need both calls to reach the handshake-over state on 543 * both sides. 544 * 545 * \retval 0 on success, otherwise error code. 546 */ 547 int mbedtls_test_move_handshake_to_state(mbedtls_ssl_context *ssl, 548 mbedtls_ssl_context *second_ssl, 549 int state); 550 551 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */ 552 553 /* 554 * Helper function setting up inverse record transformations 555 * using given cipher, hash, EtM mode, authentication tag length, 556 * and version. 557 */ 558 #define CHK(x) \ 559 do \ 560 { \ 561 if (!(x)) \ 562 { \ 563 ret = -1; \ 564 goto cleanup; \ 565 } \ 566 } while (0) 567 568 #if MBEDTLS_SSL_CID_OUT_LEN_MAX > MBEDTLS_SSL_CID_IN_LEN_MAX 569 #define SSL_CID_LEN_MIN MBEDTLS_SSL_CID_IN_LEN_MAX 570 #else 571 #define SSL_CID_LEN_MIN MBEDTLS_SSL_CID_OUT_LEN_MAX 572 #endif 573 574 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \ 575 defined(PSA_WANT_ALG_CBC_NO_PADDING) && defined(PSA_WANT_KEY_TYPE_AES) 576 int mbedtls_test_psa_cipher_encrypt_helper(mbedtls_ssl_transform *transform, 577 const unsigned char *iv, 578 size_t iv_len, 579 const unsigned char *input, 580 size_t ilen, 581 unsigned char *output, 582 size_t *olen); 583 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 && PSA_WANT_ALG_CBC_NO_PADDING && 584 PSA_WANT_KEY_TYPE_AES */ 585 586 int mbedtls_test_ssl_build_transforms(mbedtls_ssl_transform *t_in, 587 mbedtls_ssl_transform *t_out, 588 int cipher_type, int hash_id, 589 int etm, int tag_mode, 590 mbedtls_ssl_protocol_version tls_version, 591 size_t cid0_len, 592 size_t cid1_len); 593 594 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC) 595 /** 596 * \param[in,out] record The record to prepare. 597 * It must contain the data to MAC at offset 598 * `record->data_offset`, of length 599 * `record->data_length`. 600 * On success, write the MAC immediately 601 * after the data and increment 602 * `record->data_length` accordingly. 603 * \param[in,out] transform_out The out transform, typically prepared by 604 * mbedtls_test_ssl_build_transforms(). 605 * Its HMAC context may be used. Other than that 606 * it is treated as an input parameter. 607 * 608 * \return 0 on success, an `MBEDTLS_ERR_xxx` error code 609 * or -1 on error. 610 */ 611 int mbedtls_test_ssl_prepare_record_mac(mbedtls_record *record, 612 mbedtls_ssl_transform *transform_out); 613 #endif /* MBEDTLS_SSL_SOME_SUITES_USE_MAC */ 614 615 /* 616 * Populate a session structure for serialization tests. 617 * Choose dummy values, mostly non-0 to distinguish from the init default. 618 */ 619 int mbedtls_test_ssl_tls12_populate_session(mbedtls_ssl_session *session, 620 int ticket_len, 621 int endpoint_type, 622 const char *crt_file); 623 624 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) 625 int mbedtls_test_ssl_tls13_populate_session(mbedtls_ssl_session *session, 626 int ticket_len, 627 int endpoint_type); 628 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ 629 630 /* 631 * Perform data exchanging between \p ssl_1 and \p ssl_2 and check if the 632 * message was sent in the correct number of fragments. 633 * 634 * /p ssl_1 and /p ssl_2 Endpoints represented by mbedtls_ssl_context. Both 635 * of them must be initialized and connected 636 * beforehand. 637 * /p msg_len_1 and /p msg_len_2 specify the size of the message to send. 638 * /p expected_fragments_1 and /p expected_fragments_2 determine in how many 639 * fragments the message should be sent. 640 * expected_fragments is 0: can be used for DTLS testing while the message 641 * size is larger than MFL. In that case the message 642 * cannot be fragmented and sent to the second 643 * endpoint. 644 * This value can be used for negative tests. 645 * expected_fragments is 1: can be used for TLS/DTLS testing while the 646 * message size is below MFL 647 * expected_fragments > 1: can be used for TLS testing while the message 648 * size is larger than MFL 649 * 650 * \retval 0 on success, otherwise error code. 651 */ 652 int mbedtls_test_ssl_exchange_data( 653 mbedtls_ssl_context *ssl_1, 654 int msg_len_1, const int expected_fragments_1, 655 mbedtls_ssl_context *ssl_2, 656 int msg_len_2, const int expected_fragments_2); 657 658 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED) 659 int mbedtls_test_ssl_do_handshake_with_endpoints( 660 mbedtls_test_ssl_endpoint *server_ep, 661 mbedtls_test_ssl_endpoint *client_ep, 662 mbedtls_test_handshake_test_options *options, 663 mbedtls_ssl_protocol_version proto); 664 #endif /* defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED) */ 665 666 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED) 667 /** Perform an SSL handshake and exchange data over the connection. 668 * 669 * This function also handles cases where the handshake is expected to fail. 670 * 671 * If the handshake succeeds as expected, this function validates that 672 * connection parameters are as expected, exchanges data over the 673 * connection, and exercises some optional protocol features if they 674 * are enabled. See the code to see what features are validated and exercised. 675 * 676 * The handshake is expected to fail in the following cases: 677 * - If `options->expected_handshake_result != 0`. 678 * - If `options->expected_negotiated_version == MBEDTLS_SSL_VERSION_UNKNOWN`. 679 * 680 * \param[in] options Options for the connection. 681 * \param client The client endpoint. It must have been set up with 682 * mbedtls_test_ssl_endpoint_init() with \p options 683 * and #MBEDTLS_SSL_IS_CLIENT. 684 * \param server The server endpoint. It must have been set up with 685 * mbedtls_test_ssl_endpoint_init() with \p options 686 * and #MBEDTLS_SSL_IS_CLIENT. 687 * 688 * \return 1 on success, 0 on failure. On failure, this function 689 * calls mbedtls_test_fail(), indicating the failure 690 * reason and location. The causes of failure are: 691 * - Inconsistent options or bad endpoint state. 692 * - Operational problem during the handshake. 693 * - The handshake was expected to pass, but failed. 694 * - The handshake was expected to fail, but passed or 695 * failed with a different result. 696 * - The handshake passed as expected, but some connection 697 * parameter (e.g. protocol version, cipher suite, ...) 698 * is not as expected. 699 * - The handshake passed as expected, but something 700 * went wrong when attempting to exchange data. 701 * - The handshake passed as expected, but something 702 * went wrong when exercising other features 703 * (e.g. renegotiation, serialization, ...). 704 */ 705 int mbedtls_test_ssl_perform_connection( 706 const mbedtls_test_handshake_test_options *options, 707 mbedtls_test_ssl_endpoint *client, 708 mbedtls_test_ssl_endpoint *server); 709 710 void mbedtls_test_ssl_perform_handshake( 711 const mbedtls_test_handshake_test_options *options); 712 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */ 713 714 #if defined(MBEDTLS_TEST_HOOKS) 715 /* 716 * Tweak vector lengths in a TLS 1.3 Certificate message 717 * 718 * \param[in] buf Buffer containing the Certificate message to tweak 719 * \param[in]]out] end End of the buffer to parse 720 * \param tweak Tweak identifier (from 1 to the number of tweaks). 721 * \param[out] expected_result Error code expected from the parsing function 722 * \param[out] args Arguments of the MBEDTLS_SSL_CHK_BUF_READ_PTR call that 723 * is expected to fail. All zeroes if no 724 * MBEDTLS_SSL_CHK_BUF_READ_PTR failure is expected. 725 */ 726 int mbedtls_test_tweak_tls13_certificate_msg_vector_len( 727 unsigned char *buf, unsigned char **end, int tweak, 728 int *expected_result, mbedtls_ssl_chk_buf_ptr_args *args); 729 #endif /* MBEDTLS_TEST_HOOKS */ 730 731 #if defined(MBEDTLS_SSL_SESSION_TICKETS) 732 int mbedtls_test_ticket_write( 733 void *p_ticket, const mbedtls_ssl_session *session, 734 unsigned char *start, const unsigned char *end, 735 size_t *tlen, uint32_t *ticket_lifetime); 736 737 int mbedtls_test_ticket_parse(void *p_ticket, mbedtls_ssl_session *session, 738 unsigned char *buf, size_t len); 739 #endif /* MBEDTLS_SSL_SESSION_TICKETS */ 740 741 #if defined(MBEDTLS_SSL_CLI_C) && defined(MBEDTLS_SSL_SRV_C) && \ 742 defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS) && \ 743 defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED) 744 int mbedtls_test_get_tls13_ticket( 745 mbedtls_test_handshake_test_options *client_options, 746 mbedtls_test_handshake_test_options *server_options, 747 mbedtls_ssl_session *session); 748 #endif 749 750 #define ECJPAKE_TEST_PWD "bla" 751 752 #define ECJPAKE_TEST_SET_PASSWORD(exp_ret_val) \ 753 ret = (use_opaque_arg) ? \ 754 mbedtls_ssl_set_hs_ecjpake_password_opaque(&ssl, pwd_slot) : \ 755 mbedtls_ssl_set_hs_ecjpake_password(&ssl, pwd_string, pwd_len); \ 756 TEST_EQUAL(ret, exp_ret_val) 757 758 #define TEST_AVAILABLE_ECC(tls_id_, group_id_, psa_family_, psa_bits_) \ 759 TEST_EQUAL(mbedtls_ssl_get_ecp_group_id_from_tls_id(tls_id_), \ 760 group_id_); \ 761 TEST_EQUAL(mbedtls_ssl_get_tls_id_from_ecp_group_id(group_id_), \ 762 tls_id_); \ 763 TEST_EQUAL(mbedtls_ssl_get_psa_curve_info_from_tls_id(tls_id_, \ 764 &psa_type, &psa_bits), PSA_SUCCESS); \ 765 TEST_EQUAL(psa_family_, PSA_KEY_TYPE_ECC_GET_FAMILY(psa_type)); \ 766 TEST_EQUAL(psa_bits_, psa_bits); 767 768 #define TEST_UNAVAILABLE_ECC(tls_id_, group_id_, psa_family_, psa_bits_) \ 769 TEST_EQUAL(mbedtls_ssl_get_ecp_group_id_from_tls_id(tls_id_), \ 770 MBEDTLS_ECP_DP_NONE); \ 771 TEST_EQUAL(mbedtls_ssl_get_tls_id_from_ecp_group_id(group_id_), \ 772 0); \ 773 TEST_EQUAL(mbedtls_ssl_get_psa_curve_info_from_tls_id(tls_id_, \ 774 &psa_type, &psa_bits), \ 775 PSA_ERROR_NOT_SUPPORTED); 776 777 #endif /* MBEDTLS_SSL_TLS_C */ 778 779 #endif /* SSL_HELPERS_H */ 780