Branch data Line data Source code
1 : : /*
2 : : * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 : : *
4 : : * Licensed under the Apache License, Version 2.0 (the "License").
5 : : * You may not use this file except in compliance with the License.
6 : : * A copy of the License is located at
7 : : *
8 : : * http://aws.amazon.com/apache2.0
9 : : *
10 : : * or in the "license" file accompanying this file. This file is distributed
11 : : * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12 : : * express or implied. See the License for the specific language governing
13 : : * permissions and limitations under the License.
14 : : */
15 : :
16 : : /**
17 : : * @file s2n.h
18 : : * s2n-tls is a C99 implementation of the TLS/SSL protocols that is designed to
19 : : * be simple, small, fast, and with security as a priority. <br> It is released and
20 : : * licensed under the Apache License 2.0.
21 : : */
22 : :
23 : : #pragma once
24 : :
25 : : #ifndef S2N_API
26 : : /**
27 : : * Marks a function as belonging to the public s2n API.
28 : : */
29 : : #define S2N_API
30 : : #endif
31 : :
32 : : #ifdef __cplusplus
33 : : extern "C" {
34 : : #endif
35 : :
36 : : #include <stdbool.h>
37 : : #include <stdint.h>
38 : : #include <stdio.h>
39 : : #include <sys/types.h>
40 : : #include <sys/uio.h>
41 : :
42 : : /**
43 : : * Function return code
44 : : */
45 : 6644564987 : #define S2N_SUCCESS 0
46 : : /**
47 : : * Function return code
48 : : */
49 : 104 : #define S2N_FAILURE -1
50 : :
51 : : /**
52 : : * Callback return code
53 : : */
54 : 13 : #define S2N_CALLBACK_BLOCKED -2
55 : :
56 : : /**
57 : : * s2n minimum supported TLS record major version
58 : : */
59 : : #define S2N_MINIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION 2
60 : :
61 : : /**
62 : : * s2n maximum supported TLS record major version
63 : : */
64 : : #define S2N_MAXIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION 3
65 : :
66 : : /**
67 : : * s2n SSL 2.0 Version Constant
68 : : */
69 : 2 : #define S2N_SSLv2 20
70 : :
71 : : /**
72 : : * s2n SSL 3.0 Version Constant
73 : : */
74 : 249229 : #define S2N_SSLv3 30
75 : :
76 : : /**
77 : : * s2n TLS 1.0 Version Constant
78 : : */
79 : 982667 : #define S2N_TLS10 31
80 : :
81 : : /**
82 : : * s2n TLS 1.1 Version Constant
83 : : */
84 : 424560 : #define S2N_TLS11 32
85 : :
86 : : /**
87 : : * s2n TLS 1.2 Version Constant
88 : : */
89 : 263672 : #define S2N_TLS12 33
90 : :
91 : : /**
92 : : * s2n TLS 1.3 Version Constant
93 : : */
94 : 34147094 : #define S2N_TLS13 34
95 : :
96 : : /**
97 : : * s2n Unknown TLS Version
98 : : */
99 : 1711168 : #define S2N_UNKNOWN_PROTOCOL_VERSION 0
100 : :
101 : : /**
102 : : * s2n-tls functions that return 'int' return 0 to indicate success and -1 to indicate
103 : : * failure.
104 : : *
105 : : * s2n-tls functions that return pointer types return NULL in the case of
106 : : * failure.
107 : : *
108 : : * When an s2n-tls function returns a failure, s2n_errno will be set to a value
109 : : * corresponding to the error. This error value can be translated into a string
110 : : * explaining the error in English by calling s2n_strerror(s2n_errno, "EN").
111 : : * A string containing human readable error name; can be generated with `s2n_strerror_name`.
112 : : * A string containing internal debug information, including filename and line number, can be generated with `s2n_strerror_debug`.
113 : : * A string containing only the filename and line number can be generated with `s2n_strerror_source`.
114 : : * This string is useful to include when reporting issues to the s2n-tls development team.
115 : : *
116 : : * @warning To avoid possible confusion, s2n_errno should be cleared after processing an error: `s2n_errno = S2N_ERR_T_OK`
117 : : */
118 : : S2N_API extern __thread int s2n_errno;
119 : :
120 : : /**
121 : : * This function can be used instead of trying to resolve `s2n_errno` directly
122 : : * in runtimes where thread-local variables may not be easily accessible.
123 : : *
124 : : * @returns The address of the thread-local `s2n_errno` variable
125 : : */
126 : : S2N_API extern int *s2n_errno_location(void);
127 : :
128 : : /**
129 : : * Used to help applications determine why an s2n-tls function failed.
130 : : *
131 : : * This enum is optimized for use in C switch statements. Each value in the enum represents
132 : : * an error "category".
133 : : *
134 : : * s2n-tls organizes errors into different "types" to allow applications to handle error
135 : : * values without catching all possibilities. Applications using non-blocking I/O should check
136 : : * the error type to determine if the I/O operation failed because it would block or for some other
137 : : * error. To retrieve the type for a given error use `s2n_error_get_type()`. Applications should
138 : : * perform any error handling logic using these high level types.
139 : : *
140 : : * See the [Error Handling](https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch03-error-handling.md) section for how the errors should be interpreted.
141 : : */
142 : : typedef enum {
143 : : /** No error */
144 : : S2N_ERR_T_OK = 0,
145 : : /** Underlying I/O operation failed, check system errno */
146 : : S2N_ERR_T_IO,
147 : : /** EOF */
148 : : S2N_ERR_T_CLOSED,
149 : : /** Underlying I/O operation would block */
150 : : S2N_ERR_T_BLOCKED,
151 : : /** Incoming Alert */
152 : : S2N_ERR_T_ALERT,
153 : : /** Failure in some part of the TLS protocol. Ex: CBC verification failure */
154 : : S2N_ERR_T_PROTO,
155 : : /** Error internal to s2n-tls. A precondition could have failed. */
156 : : S2N_ERR_T_INTERNAL,
157 : : /** User input error. Ex: Providing an invalid cipher preference version */
158 : : S2N_ERR_T_USAGE
159 : : } s2n_error_type;
160 : :
161 : : /**
162 : : * Gets the category of error from an error.
163 : : *
164 : : * s2n-tls organizes errors into different "types" to allow applications to do logic on error values without catching all possibilities.
165 : : * Applications using non-blocking I/O should check error type to determine if the I/O operation failed because
166 : : * it would block or for some other error.
167 : : *
168 : : * @param error The error from s2n. Usually this is `s2n_errno`.
169 : : * @returns An s2n_error_type
170 : : */
171 : : S2N_API extern int s2n_error_get_type(int error);
172 : :
173 : : /**
174 : : * An opaque configuration object, used by clients and servers for holding cryptographic certificates, keys and preferences.
175 : : */
176 : : struct s2n_config;
177 : :
178 : : /**
179 : : * An opaque connection. Used to track each s2n connection.
180 : : */
181 : : struct s2n_connection;
182 : :
183 : : /**
184 : : * Prevents S2N from calling `OPENSSL_init_crypto`/`OPENSSL_cleanup`/`EVP_cleanup` on OpenSSL versions
185 : : * prior to 1.1.x. This allows applications or languages that also init OpenSSL to interoperate
186 : : * with S2N.
187 : : *
188 : : * @warning This function must be called BEFORE s2n_init() to have any effect. It will return an error
189 : : * if s2n is already initialized.
190 : : *
191 : : * @note If you disable this and are using a version of OpenSSL/libcrypto < 1.1.x, you will
192 : : * be responsible for library init and cleanup (specifically `OPENSSL_add_all_algorithms()`
193 : : * or `OPENSSL_init_crypto()`, and EVP_* APIs will not be usable unless the library is initialized.
194 : : *
195 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
196 : : */
197 : : S2N_API extern int s2n_crypto_disable_init(void);
198 : :
199 : : /**
200 : : * Prevents S2N from installing an atexit handler, which allows safe shutdown of S2N from within a
201 : : * re-entrant shared library
202 : : *
203 : : * @warning This function must be called BEFORE s2n_init() to have any effect. It will return an error
204 : : * if s2n is already initialized.
205 : : *
206 : : * @note This will cause `s2n_cleanup` to do complete cleanup of s2n-tls when called from the main
207 : : * thread (the thread `s2n_init` was called from).
208 : : *
209 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
210 : : */
211 : : S2N_API extern int s2n_disable_atexit(void);
212 : :
213 : : /**
214 : : * Fetches the OpenSSL version s2n-tls was compiled with. This can be used by applications to validate at runtime
215 : : * that the versions of s2n-tls and Openssl that they have loaded are correct.
216 : : *
217 : : * @returns the version number of OpenSSL that s2n-tls was compiled with
218 : : */
219 : : S2N_API extern unsigned long s2n_get_openssl_version(void);
220 : :
221 : : /**
222 : : * Initializes the s2n-tls library and should be called once in your application, before any other s2n-tls
223 : : * functions are called. Failure to call s2n_init() will result in errors from other s2n-tls functions.
224 : : *
225 : : * @warning This function is not thread safe and should only be called once.
226 : : *
227 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
228 : : */
229 : : S2N_API extern int s2n_init(void);
230 : :
231 : : /**
232 : : * Cleans up thread-local resources used by s2n-tls. Does not perform a full library cleanup. To fully
233 : : * clean up the library use s2n_cleanup_final().
234 : : *
235 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
236 : : */
237 : : S2N_API extern int s2n_cleanup(void);
238 : :
239 : : /*
240 : : * Performs a complete deinitialization and cleanup of the s2n-tls library.
241 : : *
242 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
243 : : */
244 : : S2N_API extern int s2n_cleanup_final(void);
245 : :
246 : : typedef enum {
247 : : S2N_FIPS_MODE_DISABLED = 0,
248 : : S2N_FIPS_MODE_ENABLED,
249 : : } s2n_fips_mode;
250 : :
251 : : /**
252 : : * Determines whether s2n-tls is operating in FIPS mode.
253 : : *
254 : : * s2n-tls enters FIPS mode on initialization when built with a version of AWS-LC that supports
255 : : * FIPS (https://github.com/aws/aws-lc/blob/main/crypto/fipsmodule/FIPS.md). FIPS mode controls
256 : : * some internal configuration related to FIPS support, like which random number generator is used.
257 : : *
258 : : * FIPS mode does not enforce the use of FIPS-approved cryptography. Applications attempting to use
259 : : * only FIPS-approved cryptography should also ensure that s2n-tls is configured to use a security
260 : : * policy that only supports FIPS-approved cryptography.
261 : : *
262 : : * @param fips_mode Set to the FIPS mode of s2n-tls.
263 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
264 : : */
265 : : S2N_API extern int s2n_get_fips_mode(s2n_fips_mode *fips_mode);
266 : :
267 : : /**
268 : : * Creates a new s2n_config object. This object can (and should) be associated with many connection
269 : : * objects.
270 : : *
271 : : * The returned config will be initialized with default system certificates in its trust store.
272 : : *
273 : : * The returned config should be freed with `s2n_config_free()` after it's no longer in use by any
274 : : * connection.
275 : : *
276 : : * @returns A new configuration object suitable for configuring connections and associating certs
277 : : * and keys.
278 : : */
279 : : S2N_API extern struct s2n_config *s2n_config_new(void);
280 : :
281 : : /**
282 : : * Creates a new s2n_config object with minimal default options.
283 : : *
284 : : * This function has better performance than `s2n_config_new()` because it does not load default
285 : : * system certificates into the trust store by default. To add system certificates to this config,
286 : : * call `s2n_config_load_system_certs()`.
287 : : *
288 : : * The returned config should be freed with `s2n_config_free()` after it's no longer in use by any
289 : : * connection.
290 : : *
291 : : * @returns A new configuration object suitable for configuring connections and associating certs
292 : : * and keys.
293 : : */
294 : : S2N_API extern struct s2n_config *s2n_config_new_minimal(void);
295 : :
296 : : /**
297 : : * Frees the memory associated with an `s2n_config` object.
298 : : *
299 : : * @param config The configuration object being freed
300 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
301 : : */
302 : : S2N_API extern int s2n_config_free(struct s2n_config *config);
303 : :
304 : : /**
305 : : * Frees the DH params associated with an `s2n_config` object.
306 : : *
307 : : * @param config The configuration object with DH params being freed
308 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
309 : : */
310 : : S2N_API extern int s2n_config_free_dhparams(struct s2n_config *config);
311 : :
312 : : /**
313 : : * Frees the certificate chain and key associated with an `s2n_config` object.
314 : : *
315 : : * @param config The configuration object with DH params being freed
316 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
317 : : */
318 : : S2N_API extern int s2n_config_free_cert_chain_and_key(struct s2n_config *config);
319 : :
320 : : /**
321 : : * Callback function type used to get the system time.
322 : : *
323 : : * @param void* A pointer to arbitrary data for use within the callback
324 : : * @param uint64_t* A pointer that the callback will set to the time in nanoseconds
325 : : * The function should return 0 on success and -1 on failure.
326 : : */
327 : : typedef int (*s2n_clock_time_nanoseconds)(void *, uint64_t *);
328 : :
329 : : /**
330 : : * Cache callback function that allows the caller to retrieve SSL session data
331 : : * from a cache.
332 : : *
333 : : * The callback function takes six arguments:
334 : : * a pointer to the s2n_connection object,
335 : : * a pointer to arbitrary data for use within the callback,
336 : : * a pointer to a key which can be used to retrieve the cached entry,
337 : : * a 64 bit unsigned integer specifying the size of this key,
338 : : * a pointer to a memory location where the value should be stored,
339 : : * and a pointer to a 64 bit unsigned integer specifying the size of this value.
340 : : *
341 : : * Initially *value_size will be set to the amount of space allocated for the value,
342 : : * the callback should set *value_size to the actual size of the data returned.
343 : : * If there is insufficient space, -1 should be returned.
344 : : * If the cache is not ready to provide data for the request,
345 : : * S2N_CALLBACK_BLOCKED should be returned.
346 : : *
347 : : * This will cause s2n_negotiate() to return S2N_BLOCKED_ON_APPLICATION_INPUT.
348 : : */
349 : : typedef int (*s2n_cache_retrieve_callback)(struct s2n_connection *conn, void *, const void *key, uint64_t key_size, void *value, uint64_t *value_size);
350 : :
351 : : /**
352 : : * Cache callback function that allows the caller to store SSL session data in a
353 : : * cache.
354 : : *
355 : : * The callback function takes seven arguments:
356 : : * a pointer to the s2n_connection object,
357 : : * a pointer to arbitrary data for use within the callback,
358 : : * a 64-bit unsigned integer specifying the number of seconds the session data may be stored for,
359 : : * a pointer to a key which can be used to retrieve the cached entry,
360 : : * a 64 bit unsigned integer specifying the size of this key,
361 : : * a pointer to a value which should be stored,
362 : : * and a 64 bit unsigned integer specified the size of this value.
363 : : */
364 : : typedef int (*s2n_cache_store_callback)(struct s2n_connection *conn, void *, uint64_t ttl_in_seconds, const void *key, uint64_t key_size, const void *value, uint64_t value_size);
365 : :
366 : : /**
367 : : * Cache callback function that allows the caller to set a callback function
368 : : * that will be used to delete SSL session data from a cache.
369 : : *
370 : : * The callback function takes four arguments:
371 : : * a pointer to s2n_connection object,
372 : : * a pointer to arbitrary data for use within the callback,
373 : : * a pointer to a key which can be used to delete the cached entry,
374 : : * and a 64 bit unsigned integer specifying the size of this key.
375 : : */
376 : : typedef int (*s2n_cache_delete_callback)(struct s2n_connection *conn, void *, const void *key, uint64_t key_size);
377 : :
378 : : /**
379 : : * Allows the caller to set a callback function that will be used to get the
380 : : * system time. The time returned should be the number of nanoseconds since the
381 : : * Unix epoch (Midnight, January 1st, 1970).
382 : : *
383 : : * s2n-tls uses this clock for timestamps.
384 : : *
385 : : * @param config The configuration object being updated
386 : : * @param clock_fn The wall clock time callback function
387 : : * @param ctx An opaque pointer that the callback will be invoked with
388 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
389 : : */
390 : : S2N_API extern int s2n_config_set_wall_clock(struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx);
391 : :
392 : : /**
393 : : * Allows the caller to set a callback function that will be used to get
394 : : * monotonic time. The monotonic time is the time since an arbitrary, unspecified
395 : : * point. Unlike wall clock time, it MUST never move backwards.
396 : : *
397 : : * s2n-tls uses this clock for timers.
398 : : *
399 : : * @param config The configuration object being updated
400 : : * @param clock_fn The monotonic time callback function
401 : : * @param ctx An opaque pointer that the callback will be invoked with
402 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
403 : : */
404 : : S2N_API extern int s2n_config_set_monotonic_clock(struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx);
405 : :
406 : : /**
407 : : * Translates an s2n_error code to a human readable string explaining the error.
408 : : *
409 : : * @param error The error code to explain. Usually this is s2n_errno
410 : : * @param lang The language to explain the error code. Pass "EN" or NULL for English.
411 : : * @returns The error string
412 : : */
413 : : S2N_API extern const char *s2n_strerror(int error, const char *lang);
414 : :
415 : : /**
416 : : * Translates an s2n_error code to a human readable string containing internal debug
417 : : * information, including file name and line number. This function is useful when
418 : : * reporting issues to the s2n-tls development team.
419 : : *
420 : : * @param error The error code to explain. Usually this is s2n_errno
421 : : * @param lang The language to explain the error code. Pass "EN" or NULL for English.
422 : : * @returns The error string
423 : : */
424 : : S2N_API extern const char *s2n_strerror_debug(int error, const char *lang);
425 : :
426 : : /**
427 : : * Translates an s2n_error code to a human readable string.
428 : : *
429 : : * @param error The error code to explain. Usually this is s2n_errno
430 : : * @returns The error string
431 : : */
432 : : S2N_API extern const char *s2n_strerror_name(int error);
433 : :
434 : : /**
435 : : * Translates an s2n_error code to a filename and line number.
436 : : *
437 : : * @param error The error code to explain. Usually this is s2n_errno.
438 : : * @returns The error string.
439 : : */
440 : : S2N_API extern const char *s2n_strerror_source(int error);
441 : :
442 : : /**
443 : : * Opaque stack trace structure.
444 : : */
445 : : struct s2n_stacktrace;
446 : :
447 : : /**
448 : : * Checks if s2n stack trace captures are enabled.
449 : : *
450 : : * @returns True if stack traces are enabled. False if they are disabled.
451 : : */
452 : : S2N_API extern bool s2n_stack_traces_enabled(void);
453 : :
454 : : /**
455 : : * Configures the s2n stack trace captures option.
456 : : *
457 : : * @param newval Boolean to determine if stack traces should be enabled. True to enable them. False to disable them.
458 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
459 : : */
460 : : S2N_API extern int s2n_stack_traces_enabled_set(bool newval);
461 : :
462 : : /**
463 : : * Calculates the s2n stack trace.
464 : : *
465 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
466 : : */
467 : : S2N_API extern int s2n_calculate_stacktrace(void);
468 : :
469 : : /**
470 : : * Prints the s2n stack trace to a file. The file descriptor is expected to be
471 : : * open and ready for writing.
472 : : *
473 : : * @param fptr A pointer to the file s2n-tls should write the stack trace to.
474 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
475 : : */
476 : : S2N_API extern int s2n_print_stacktrace(FILE *fptr);
477 : :
478 : : /**
479 : : * Clean up the memory used to contain the stack trace.
480 : : *
481 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
482 : : */
483 : : S2N_API extern int s2n_free_stacktrace(void);
484 : :
485 : : /**
486 : : * Export the s2n_stacktrace.
487 : : *
488 : : * @param trace A pointer to the s2n_stacktrace to fill.
489 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
490 : : */
491 : : S2N_API extern int s2n_get_stacktrace(struct s2n_stacktrace *trace);
492 : :
493 : : /**
494 : : * Allows the caller to set a callback function that will be used to store SSL
495 : : * session data in a cache.
496 : : *
497 : : * @param config The configuration object being updated
498 : : * @param cache_store_callback The cache store callback function.
499 : : * @param data An opaque context pointer that the callback will be invoked with.
500 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
501 : : */
502 : : S2N_API extern int s2n_config_set_cache_store_callback(struct s2n_config *config, s2n_cache_store_callback cache_store_callback, void *data);
503 : :
504 : : /**
505 : : * Allows the caller to set a callback function that will be used to retrieve SSL
506 : : * session data from a cache.
507 : : *
508 : : * @param config The configuration object being updated
509 : : * @param cache_retrieve_callback The cache retrieve callback function.
510 : : * @param data An opaque context pointer that the callback will be invoked with.
511 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
512 : : */
513 : : S2N_API extern int s2n_config_set_cache_retrieve_callback(struct s2n_config *config, s2n_cache_retrieve_callback cache_retrieve_callback, void *data);
514 : :
515 : : /**
516 : : * Allows the caller to set a callback function that will be used to delete SSL
517 : : * session data from a cache.
518 : : *
519 : : * @param config The configuration object being updated
520 : : * @param cache_delete_callback The cache delete callback function.
521 : : * @param data An opaque context pointer that the callback will be invoked with.
522 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
523 : : */
524 : : S2N_API extern int s2n_config_set_cache_delete_callback(struct s2n_config *config, s2n_cache_delete_callback cache_delete_callback, void *data);
525 : :
526 : : /**
527 : : * Called when `s2n_init` is executed.
528 : : */
529 : : typedef int (*s2n_mem_init_callback)(void);
530 : :
531 : : /**
532 : : * Will be called when `s2n_cleanup` is executed.
533 : : */
534 : : typedef int (*s2n_mem_cleanup_callback)(void);
535 : :
536 : : /**
537 : : * A function that can allocate at least `requested` bytes of memory.
538 : : *
539 : : * It stores the location of that memory in **\*ptr** and the size of the allocated
540 : : * data in **\*allocated**. The function may choose to allocate more memory
541 : : * than was requested. s2n-tls will consider all allocated memory available for
542 : : * use, and will attempt to free all allocated memory when able.
543 : : */
544 : : typedef int (*s2n_mem_malloc_callback)(void **ptr, uint32_t requested, uint32_t *allocated);
545 : :
546 : : /**
547 : : * Frees memory allocated by s2n_mem_malloc_callback.
548 : : */
549 : : typedef int (*s2n_mem_free_callback)(void *ptr, uint32_t size);
550 : :
551 : : /**
552 : : * Allows the caller to override s2n-tls's internal memory handling functions.
553 : : *
554 : : * @warning This function must be called before s2n_init().
555 : : *
556 : : * @param mem_init_callback The s2n_mem_init_callback
557 : : * @param mem_cleanup_callback The s2n_mem_cleanup_callback
558 : : * @param mem_malloc_callback The s2n_mem_malloc_callback
559 : : * @param mem_free_callback The s2n_mem_free_callback
560 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
561 : : */
562 : : S2N_API extern int s2n_mem_set_callbacks(s2n_mem_init_callback mem_init_callback, s2n_mem_cleanup_callback mem_cleanup_callback,
563 : : s2n_mem_malloc_callback mem_malloc_callback, s2n_mem_free_callback mem_free_callback);
564 : :
565 : : /**
566 : : * A callback function that will be called when s2n-tls is initialized.
567 : : */
568 : : typedef int (*s2n_rand_init_callback)(void);
569 : :
570 : : /**
571 : : * A callback function that will be called when `s2n_cleanup` is executed.
572 : : */
573 : : typedef int (*s2n_rand_cleanup_callback)(void);
574 : :
575 : : /**
576 : : * A callback function that will be used to provide entropy to the s2n-tls
577 : : * random number generators.
578 : : */
579 : : typedef int (*s2n_rand_seed_callback)(void *data, uint32_t size);
580 : :
581 : : /**
582 : : * A callback function that will be used to mix in entropy every time the RNG
583 : : * is invoked.
584 : : */
585 : : typedef int (*s2n_rand_mix_callback)(void *data, uint32_t size);
586 : :
587 : : /**
588 : : * Allows the caller to override s2n-tls's entropy functions.
589 : : *
590 : : * @warning This function must be called before s2n_init().
591 : : *
592 : : * @note The overriden random callbacks will not be used when s2n-tls is operating in FIPS mode.
593 : : *
594 : : * @param rand_init_callback The s2n_rand_init_callback
595 : : * @param rand_cleanup_callback The s2n_rand_cleanup_callback
596 : : * @param rand_seed_callback The s2n_rand_seed_callback
597 : : * @param rand_mix_callback The s2n_rand_mix_callback
598 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
599 : : */
600 : : S2N_API extern int s2n_rand_set_callbacks(s2n_rand_init_callback rand_init_callback, s2n_rand_cleanup_callback rand_cleanup_callback,
601 : : s2n_rand_seed_callback rand_seed_callback, s2n_rand_mix_callback rand_mix_callback);
602 : :
603 : : /**
604 : : * TLS extensions supported by s2n-tls
605 : : */
606 : : typedef enum {
607 : : S2N_EXTENSION_SERVER_NAME = 0,
608 : : S2N_EXTENSION_MAX_FRAG_LEN = 1,
609 : : S2N_EXTENSION_OCSP_STAPLING = 5,
610 : : S2N_EXTENSION_SUPPORTED_GROUPS = 10,
611 : : S2N_EXTENSION_EC_POINT_FORMATS = 11,
612 : : S2N_EXTENSION_SIGNATURE_ALGORITHMS = 13,
613 : : S2N_EXTENSION_ALPN = 16,
614 : : S2N_EXTENSION_CERTIFICATE_TRANSPARENCY = 18,
615 : : S2N_EXTENSION_SUPPORTED_VERSIONS = 43,
616 : : S2N_EXTENSION_RENEGOTIATION_INFO = 65281,
617 : : } s2n_tls_extension_type;
618 : :
619 : : /**
620 : : * MFL configurations from https://datatracker.ietf.org/doc/html/rfc6066#section-4.
621 : : */
622 : : typedef enum {
623 : : S2N_TLS_MAX_FRAG_LEN_512 = 1,
624 : : S2N_TLS_MAX_FRAG_LEN_1024 = 2,
625 : : S2N_TLS_MAX_FRAG_LEN_2048 = 3,
626 : : S2N_TLS_MAX_FRAG_LEN_4096 = 4,
627 : : } s2n_max_frag_len;
628 : :
629 : : /**
630 : : * Opaque certificate type.
631 : : */
632 : : struct s2n_cert;
633 : :
634 : : /**
635 : : * Opaque certificate chain and key type.
636 : : */
637 : : struct s2n_cert_chain_and_key;
638 : :
639 : : /**
640 : : * Opaque key type.
641 : : */
642 : : struct s2n_pkey;
643 : :
644 : : /**
645 : : * Opaque public key type.
646 : : */
647 : : typedef struct s2n_pkey s2n_cert_public_key;
648 : :
649 : : /**
650 : : * Opaque private key type.
651 : : */
652 : : typedef struct s2n_pkey s2n_cert_private_key;
653 : :
654 : : /**
655 : : * Creates a new s2n_cert_chain_and_key object. This object can be associated
656 : : * with many config objects. It is used to represent a certificate and key pair.
657 : : *
658 : : * @returns A new object used to represent a certificate-chain/key pair
659 : : */
660 : : S2N_API extern struct s2n_cert_chain_and_key *s2n_cert_chain_and_key_new(void);
661 : :
662 : : /**
663 : : * Associates a certificate chain and private key with an `s2n_cert_chain_and_key` object.
664 : : *
665 : : * `cert_chain_pem` should be a PEM encoded certificate chain, with the first
666 : : * certificate in the chain being your leaf certificate. `private_key_pem`
667 : : * should be a PEM encoded private key corresponding to the leaf certificate.
668 : : *
669 : : * @note Prefer using s2n_cert_chain_and_key_load_pem_bytes.
670 : : *
671 : : * @param chain_and_key The certificate chain and private key handle
672 : : * @param chain_pem A byte array of a PEM encoded certificate chain.
673 : : * @param private_key_pem A byte array of a PEM encoded key.
674 : : *
675 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
676 : : */
677 : : S2N_API extern int s2n_cert_chain_and_key_load_pem(struct s2n_cert_chain_and_key *chain_and_key, const char *chain_pem, const char *private_key_pem);
678 : :
679 : : /**
680 : : * Associates a certificate chain and private key with an `s2n_cert_chain_and_key` object.
681 : : *
682 : : * `cert_chain_pem` should be a PEM encoded certificate chain, with the first
683 : : * certificate in the chain being your leaf certificate. `private_key_pem`
684 : : * should be a PEM encoded private key corresponding to the leaf certificate.
685 : : *
686 : : * @param chain_and_key The certificate chain and private key handle
687 : : * @param chain_pem A byte array of a PEM encoded certificate chain.
688 : : * @param chain_pem_len Size of `chain_pem`
689 : : * @param private_key_pem A byte array of a PEM encoded key.
690 : : * @param private_key_pem_len Size of `private_key_pem`
691 : : *
692 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
693 : : */
694 : : S2N_API extern int s2n_cert_chain_and_key_load_pem_bytes(struct s2n_cert_chain_and_key *chain_and_key, uint8_t *chain_pem, uint32_t chain_pem_len, uint8_t *private_key_pem, uint32_t private_key_pem_len);
695 : :
696 : : /**
697 : : * Associates a public certificate chain with a `s2n_cert_chain_and_key` object. It does
698 : : * NOT set a private key, so the connection will need to be configured to
699 : : * [offload private key operations](https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch12-private-key-ops.md).
700 : : *
701 : : * @param chain_and_key The certificate chain and private key handle
702 : : * @param chain_pem A byte array of a PEM encoded certificate chain.
703 : : * @param chain_pem_len Size of `chain_pem`
704 : : *
705 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
706 : : */
707 : : S2N_API extern int s2n_cert_chain_and_key_load_public_pem_bytes(struct s2n_cert_chain_and_key *chain_and_key, uint8_t *chain_pem, uint32_t chain_pem_len);
708 : :
709 : : /**
710 : : * Frees the memory associated with an `s2n_cert_chain_and_key` object.
711 : : *
712 : : * @param cert_and_key The certificate chain and private key handle
713 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
714 : : */
715 : : S2N_API extern int s2n_cert_chain_and_key_free(struct s2n_cert_chain_and_key *cert_and_key);
716 : :
717 : : /**
718 : : * Adds a context to the `s2n_cert_chain_and_key` object.
719 : : *
720 : : * @param cert_and_key The certificate chain and private key handle
721 : : * @param ctx An opaque pointer to user supplied data.
722 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
723 : : */
724 : : S2N_API extern int s2n_cert_chain_and_key_set_ctx(struct s2n_cert_chain_and_key *cert_and_key, void *ctx);
725 : :
726 : : /**
727 : : * Get the user supplied context from the `s2n_cert_chain_and_key` object.
728 : : *
729 : : * @param cert_and_key The certificate chain and private key handle
730 : : * @returns The user supplied pointer from s2n_cert_chain_and_key_set_ctx()
731 : : */
732 : : S2N_API extern void *s2n_cert_chain_and_key_get_ctx(struct s2n_cert_chain_and_key *cert_and_key);
733 : :
734 : : /**
735 : : * Get the private key from the `s2n_cert_chain_and_key` object.
736 : : *
737 : : * @param cert_and_key The certificate chain and private key handle
738 : : * @returns A pointer to the `s2n_cert_private_key`
739 : : */
740 : : S2N_API extern s2n_cert_private_key *s2n_cert_chain_and_key_get_private_key(struct s2n_cert_chain_and_key *cert_and_key);
741 : :
742 : : /**
743 : : * Set the raw OCSP stapling data for a certificate chain.
744 : : *
745 : : * @param chain_and_key The certificate chain handle
746 : : * @param data A pointer to the raw OCSP stapling data bytes. The data will be copied.
747 : : * @param length The length of the data bytes.
748 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
749 : : */
750 : : S2N_API extern int s2n_cert_chain_and_key_set_ocsp_data(struct s2n_cert_chain_and_key *chain_and_key, const uint8_t *data, uint32_t length);
751 : :
752 : : /**
753 : : * Set the signed certificate timestamp (SCT) for a certificate chain.
754 : : * This is used for Certificate Transparency.
755 : : *
756 : : * @param chain_and_key The certificate chain handle
757 : : * @param data A pointer to the SCT data. The data will be copied.
758 : : * @param length The length of the data bytes.
759 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
760 : : */
761 : : S2N_API extern int s2n_cert_chain_and_key_set_sct_list(struct s2n_cert_chain_and_key *chain_and_key, const uint8_t *data, uint32_t length);
762 : :
763 : : /**
764 : : * A callback function that is invoked if s2n-tls cannot resolve a conflict between
765 : : * two certificates with the same domain name. This function is invoked while certificates
766 : : * are added to an `s2n_config`.
767 : : *
768 : : * Currently, the only builtin resolution for domain name conflicts is certificate type(RSA,
769 : : * ECDSA, etc). The callback should return a pointer to the `s2n_cert_chain_and_key` that
770 : : * should be used for dns name `name`.
771 : : *
772 : : * If NULL is returned, the first certificate will be used. Typically an application
773 : : * will use properties like trust and expiry to implement tiebreaking.
774 : : */
775 : : typedef struct s2n_cert_chain_and_key *(*s2n_cert_tiebreak_callback)(struct s2n_cert_chain_and_key *cert1, struct s2n_cert_chain_and_key *cert2, uint8_t *name, uint32_t name_len);
776 : :
777 : : /**
778 : : * Sets the `s2n_cert_tiebreak_callback` for resolving domain name conflicts.
779 : : * If no callback is set, the first certificate added for a domain name will always be preferred.
780 : : *
781 : : * @param config The configuration object being updated
782 : : * @param cert_tiebreak_cb The pointer to the certificate tiebreak function
783 : : *
784 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
785 : : */
786 : : S2N_API extern int s2n_config_set_cert_tiebreak_callback(struct s2n_config *config, s2n_cert_tiebreak_callback cert_tiebreak_cb);
787 : :
788 : : /**
789 : : * Associates a certificate chain and private key with an `s2n_config` object.
790 : : * Using this API, only one cert chain of each type (like ECDSA or RSA) may be associated with a config.
791 : : * `cert_chain_pem` should be a PEM encoded certificate chain, with the first certificate
792 : : * in the chain being your server's certificate. `private_key_pem` should be a
793 : : * PEM encoded private key corresponding to the server certificate.
794 : : *
795 : : * @deprecated Use s2n_config_add_cert_chain_and_key_to_store instead.
796 : : *
797 : : * @param config The configuration object being updated
798 : : * @param cert_chain_pem A byte array of a PEM encoded certificate chain.
799 : : * @param private_key_pem A byte array of a PEM encoded key.
800 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
801 : : */
802 : : S2N_API extern int s2n_config_add_cert_chain_and_key(struct s2n_config *config, const char *cert_chain_pem, const char *private_key_pem);
803 : :
804 : : /**
805 : : * The preferred method of associating a certificate chain and private key pair with an `s2n_config` object.
806 : : * This method may be called multiple times to support multiple key types (RSA, RSA-PSS, ECDSA) and multiple
807 : : * domains. On the server side, the certificate selected will be based on the incoming SNI value and the
808 : : * client's capabilities (supported ciphers).
809 : : *
810 : : * In the case of no certificate matching the client's SNI extension or if no SNI extension was sent by
811 : : * the client, the certificate from the `first` call to `s2n_config_add_cert_chain_and_key_to_store()`
812 : : * will be selected. Use `s2n_config_set_cert_chain_and_key_defaults()` to set different defaults.
813 : : *
814 : : * @warning It is not recommended to free or modify the `cert_key_pair` as any subsequent changes will be
815 : : * reflected in the config.
816 : : *
817 : : * @param config The configuration object being updated
818 : : * @param cert_key_pair The certificate chain and private key handle
819 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
820 : : */
821 : : S2N_API extern int s2n_config_add_cert_chain_and_key_to_store(struct s2n_config *config, struct s2n_cert_chain_and_key *cert_key_pair);
822 : :
823 : : /**
824 : : * Explicitly sets certificate chain and private key pairs to be used as defaults for each auth
825 : : * method (key type). A "default" certificate is used when there is not an SNI match with any other
826 : : * configured certificate.
827 : : *
828 : : * Only one certificate can be set as the default per auth method (one RSA default, one ECDSA default,
829 : : * etc.). All previous default certificates will be cleared and re-set when this API is called.
830 : : *
831 : : * This API is called for a specific `s2n_config` object. s2n-tls will attempt to automatically choose
832 : : * default certificates for each auth method (key type) based on the order that `s2n_cert_chain_and_key`
833 : : * are added to the `s2n_config` using one of the APIs listed above.
834 : : * `s2n_config_set_cert_chain_and_key_defaults` can be called at any time; s2n-tls will clear defaults
835 : : * and no longer attempt to automatically choose any default certificates.
836 : : *
837 : : * @param config The configuration object being updated
838 : : * @param cert_key_pairs An array of certificate chain and private key handles
839 : : * @param num_cert_key_pairs The amount of handles in cert_key_pairs
840 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
841 : : */
842 : : S2N_API extern int s2n_config_set_cert_chain_and_key_defaults(struct s2n_config *config,
843 : : struct s2n_cert_chain_and_key **cert_key_pairs, uint32_t num_cert_key_pairs);
844 : :
845 : : /**
846 : : * Adds to the trust store from a CA file or directory containing trusted certificates.
847 : : *
848 : : * When configs are created with `s2n_config_new()`, the trust store is initialized with default
849 : : * system certificates. To completely override these certificates, call
850 : : * `s2n_config_wipe_trust_store()` before calling this function.
851 : : *
852 : : * @note The trust store will be initialized with the common locations for the host
853 : : * operating system by default.
854 : : *
855 : : * @warning This API uses the PEM parsing implementation from the linked libcrypto. This
856 : : * implementation will typically make a best-effort attempt to parse all of the certificates in the
857 : : * provided file or directory. This permissive approach may silently ignore malformed certificates,
858 : : * leading to possible connection failures if a certificate was expected to exist in the trust
859 : : * store but was skipped while parsing. As such, this API should only be used on PEMs that are
860 : : * known to be well-formed and parsable with the linked libcrypto, such as the system trust store.
861 : : * For all other PEMs, `s2n_config_add_pem_to_trust_store()` should be used instead, which parses
862 : : * more strictly.
863 : : *
864 : : * @param config The configuration object being updated
865 : : * @param ca_pem_filename A string for the file path of the CA PEM file.
866 : : * @param ca_dir A string for the directory of the CA PEM files.
867 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
868 : : */
869 : : S2N_API extern int s2n_config_set_verification_ca_location(struct s2n_config *config, const char *ca_pem_filename, const char *ca_dir);
870 : :
871 : : /**
872 : : * Adds a PEM to the trust store. This will allocate memory, and load `pem` into the trust store.
873 : : *
874 : : * When configs are created with `s2n_config_new()`, the trust store is initialized with default
875 : : * system certificates. To completely override these certificates, call
876 : : * `s2n_config_wipe_trust_store()` before calling this function.
877 : : *
878 : : * @note This API uses the s2n-tls PEM parsing implementation, which is more strict than typical
879 : : * libcrypto implementations such as OpenSSL. An error is returned if any unexpected data is
880 : : * encountered while parsing `pem`. This allows applications to be made aware of any malformed
881 : : * certificates rather than attempt to negotiate with a partial trust store. However, some PEMs may
882 : : * need to be loaded that are not under control of the application, such as system trust stores. In
883 : : * this case, `s2n_config_set_verification_ca_location()` may be used, which performs more widely
884 : : * compatible and permissive parsing from the linked libcrypto.
885 : : *
886 : : * @param config The configuration object being updated
887 : : * @param pem The string value of the PEM certificate.
888 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
889 : : */
890 : : S2N_API extern int s2n_config_add_pem_to_trust_store(struct s2n_config *config, const char *pem);
891 : :
892 : : /**
893 : : * Clears the trust store of all certificates.
894 : : *
895 : : * When configs are created with `s2n_config_new()`, the trust store is initialized with default
896 : : * system certificates. To completely override these certificates, call this function before
897 : : * functions like `s2n_config_set_verification_ca_location()` or
898 : : * `s2n_config_add_pem_to_trust_store()`.
899 : : *
900 : : * @param config The configuration object being updated
901 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
902 : : */
903 : : S2N_API extern int s2n_config_wipe_trust_store(struct s2n_config *config);
904 : :
905 : : /**
906 : : * Loads default system certificates into the trust store.
907 : : *
908 : : * `s2n_config_new_minimal()` doesn't load default system certificates into the config's trust
909 : : * store by default. If `config` was created with `s2n_config_new_minimal`, this function can be
910 : : * used to load system certificates into the trust store.
911 : : *
912 : : * @note This API will error if called on a config that has already loaded system certificates
913 : : * into its trust store, which includes all configs created with `s2n_config_new()`.
914 : : *
915 : : * @param config The configuration object being updated
916 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
917 : : */
918 : : S2N_API extern int s2n_config_load_system_certs(struct s2n_config *config);
919 : :
920 : : typedef enum {
921 : : S2N_VERIFY_AFTER_SIGN_DISABLED,
922 : : S2N_VERIFY_AFTER_SIGN_ENABLED
923 : : } s2n_verify_after_sign;
924 : :
925 : : /**
926 : : * Toggle whether generated signatures are verified before being sent.
927 : : *
928 : : * Although signatures produced by the underlying libcrypto should always be valid,
929 : : * hardware faults, bugs in the signing implementation, or other uncommon factors
930 : : * can cause unexpected mistakes in the final signatures. Because these mistakes
931 : : * can leak information about the private key, applications with low trust in their
932 : : * hardware or libcrypto may want to verify signatures before sending them.
933 : : *
934 : : * However, this feature will significantly impact handshake latency.
935 : : * Additionally, most libcrypto implementations already check for common errors in signatures.
936 : : */
937 : : S2N_API extern int s2n_config_set_verify_after_sign(struct s2n_config *config, s2n_verify_after_sign mode);
938 : :
939 : : /**
940 : : * Set a custom send buffer size.
941 : : *
942 : : * This buffer is used to stage records for sending. By default,
943 : : * enough memory is allocated to hold a single record of the maximum
944 : : * size configured for the connection. With the default fragment size,
945 : : * that is about 8K bytes.
946 : : *
947 : : * Less memory can be allocated for the send buffer, but this will result in
948 : : * smaller, more fragmented records and increased overhead. While the absolute
949 : : * minimum size required is 1034 bytes, at least 2K bytes is recommended for
950 : : * reasonable record sizes.
951 : : *
952 : : * More memory can be allocated for the send buffer. This will result in s2n-tls
953 : : * buffering multiple records before sending them, reducing system write calls.
954 : : * At least 17K bytes is recommended for this use case, or at least 35K bytes
955 : : * if larger fragment sizes are used via `s2n_connection_prefer_throughput()`.
956 : : *
957 : : * @param config The configuration object being updated
958 : : * @param size The desired custom buffer size.
959 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
960 : : */
961 : : S2N_API extern int s2n_config_set_send_buffer_size(struct s2n_config *config, uint32_t size);
962 : :
963 : : /**
964 : : * Enable or disable receiving of multiple TLS records in a single s2n_recv call
965 : : *
966 : : * By default, s2n-tls returns from s2n_recv() after reading a single TLS record.
967 : : * Enabling receiving of multiple records will instead cause s2n_recv() to attempt
968 : : * to read until the application-provided output buffer is full. This may be more
969 : : * efficient, especially if larger receive buffers are used.
970 : : *
971 : : * @note If this option is enabled with blocking IO, the call to s2n_recv() will
972 : : * not return until either the application-provided output buffer is full or the
973 : : * peer closes the connection. This may lead to unintentionally long waits if the
974 : : * peer does not send enough data.
975 : : *
976 : : * @param config The configuration object being updated
977 : : * @param enabled Set to `true` if multiple record receive is to be enabled; `false` to disable.
978 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
979 : : */
980 : : S2N_API extern int s2n_config_set_recv_multi_record(struct s2n_config *config, bool enabled);
981 : :
982 : : /**
983 : : * A callback function invoked (usually multiple times) during X.509 validation for each
984 : : * name encountered in the leaf certificate.
985 : : *
986 : : * Return 1 to trust that hostname or 0 to not trust the hostname.
987 : : *
988 : : * If this function returns 1, then the certificate is considered trusted and that portion
989 : : * of the X.509 validation will succeed.
990 : : *
991 : : * If no hostname results in a 1 being returned, the certificate will be untrusted and the
992 : : * validation will terminate immediately.
993 : : *
994 : : * Data is a opaque user context set in s2n_config_set_verify_host_callback() or s2n_connection_set_verify_host_callback().
995 : : */
996 : : typedef uint8_t (*s2n_verify_host_fn)(const char *host_name, size_t host_name_len, void *data);
997 : :
998 : : /**
999 : : * Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.
1000 : : *
1001 : : * The default behavior is to require that the hostname match the server name set with s2n_set_server_name().
1002 : : * This will likely lead to all client certificates being rejected, so the callback will need to be overriden when using
1003 : : * client authentication.
1004 : : *
1005 : : * This change will be inherited by s2n_connections using this config. If a separate callback for different connections
1006 : : * using the same config is desired, see s2n_connection_set_verify_host_callback().
1007 : : *
1008 : : * @param config The configuration object being updated
1009 : : * @param data A user supplied opaque context to pass back to the callback
1010 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1011 : : */
1012 : : S2N_API extern int s2n_config_set_verify_host_callback(struct s2n_config *config, s2n_verify_host_fn, void *data);
1013 : :
1014 : : /**
1015 : : * Toggles whether or not to validate stapled OCSP responses.
1016 : : *
1017 : : * 1 means OCSP responses will be validated when they are encountered, while 0 means this step will
1018 : : * be skipped.
1019 : : *
1020 : : * The default value is 1 if the underlying libCrypto implementation supports OCSP.
1021 : : *
1022 : : * @param config The configuration object being updated
1023 : : * @param check_ocsp The desired OCSP response check configuration
1024 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1025 : : */
1026 : : S2N_API extern int s2n_config_set_check_stapled_ocsp_response(struct s2n_config *config, uint8_t check_ocsp);
1027 : :
1028 : : /**
1029 : : * Disables timestamp validation for received certificates.
1030 : : *
1031 : : * By default, s2n-tls checks the notBefore and notAfter fields on the certificates it receives
1032 : : * during the handshake. If the current date is not within the range of these fields for any
1033 : : * certificate in the chain of trust, `s2n_negotiate()` will error. This validation is in
1034 : : * accordance with RFC 5280, section 6.1.3 a.2:
1035 : : * https://datatracker.ietf.org/doc/html/rfc5280#section-6.1.3.
1036 : : *
1037 : : * This API will disable this timestamp validation, permitting negotiation with peers that send
1038 : : * expired certificates, or certificates that are not yet considered valid.
1039 : : *
1040 : : * @warning Applications calling this API should seriously consider the security implications of
1041 : : * disabling this validation. The validity period of a certificate corresponds to the range of time
1042 : : * in which the CA is guaranteed to maintain information regarding the certificate's revocation
1043 : : * status. As such, it may not be possible to obtain accurate revocation information for
1044 : : * certificates with invalid timestamps. Applications disabling this validation MUST implement
1045 : : * some external method for limiting certificate lifetime.
1046 : : *
1047 : : * @param config The associated connection config.
1048 : : * @returns S2N_SUCCESS on success, S2N_FAILURE on failure.
1049 : : */
1050 : : S2N_API extern int s2n_config_disable_x509_time_verification(struct s2n_config *config);
1051 : :
1052 : : /**
1053 : : * Turns off all X.509 validation during the negotiation phase of the connection. This should only
1054 : : * be used for testing or debugging purposes.
1055 : : *
1056 : : * @param config The configuration object being updated
1057 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1058 : : */
1059 : : S2N_API extern int s2n_config_disable_x509_verification(struct s2n_config *config);
1060 : :
1061 : : /**
1062 : : * Sets the maximum allowed depth of a cert chain used for X509 validation. The default value is
1063 : : * 7. If this limit is exceeded, validation will fail if s2n_config_disable_x509_verification()
1064 : : * has not been called. 0 is an illegal value and will return an error.
1065 : : * 1 means only a root certificate will be used.
1066 : : *
1067 : : * @param config The configuration object being updated
1068 : : * @param max_depth The number of allowed certificates in the certificate chain
1069 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1070 : : */
1071 : : S2N_API extern int s2n_config_set_max_cert_chain_depth(struct s2n_config *config, uint16_t max_depth);
1072 : :
1073 : : /**
1074 : : * Associates a set of Diffie-Hellman parameters with an `s2n_config` object.
1075 : : * @note `dhparams_pem` should be PEM encoded DH parameters.
1076 : : *
1077 : : * @param config The configuration object being updated
1078 : : * @param dhparams_pem A string containing the PEM encoded DH parameters.
1079 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1080 : : */
1081 : : S2N_API extern int s2n_config_add_dhparams(struct s2n_config *config, const char *dhparams_pem);
1082 : :
1083 : : /**
1084 : : * Sets the security policy that includes the cipher/kem/signature/ecc preferences and
1085 : : * protocol version.
1086 : : *
1087 : : * See the [USAGE-GUIDE.md](https://github.com/aws/s2n-tls/blob/main/docs/usage-guide) for how to use security policies.
1088 : : */
1089 : : S2N_API extern int s2n_config_set_cipher_preferences(struct s2n_config *config, const char *version);
1090 : :
1091 : : /**
1092 : : * Appends the provided application protocol to the preference list
1093 : : *
1094 : : * The data provided in `protocol` parameter will be copied into an internal buffer
1095 : : *
1096 : : * @param config The configuration object being updated
1097 : : * @param protocol A pointer to a byte array value
1098 : : * @param protocol_len The length of bytes that should be read from `protocol`. Note: this value cannot be 0, otherwise an error will be returned.
1099 : : */
1100 : : S2N_API extern int s2n_config_append_protocol_preference(struct s2n_config *config, const uint8_t *protocol, uint8_t protocol_len);
1101 : :
1102 : : /**
1103 : : * Sets the application protocol preferences on an `s2n_config` object.
1104 : : * `protocols` is a list in order of preference, with most preferred protocol first, and of
1105 : : * length `protocol_count`.
1106 : : *
1107 : : * When acting as an `S2N_CLIENT` the protocol list is included in the Client Hello message
1108 : : * as the ALPN extension.
1109 : : *
1110 : : * As an `S2N_SERVER`, the list is used to negotiate a mutual application protocol with the
1111 : : * client. After the negotiation for the connection has completed, the agreed upon protocol
1112 : : * can be retrieved with s2n_get_application_protocol()
1113 : : *
1114 : : * @param config The configuration object being updated
1115 : : * @param protocols The list of preferred protocols, in order of preference
1116 : : * @param protocol_count The size of the protocols list
1117 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1118 : : */
1119 : : S2N_API extern int s2n_config_set_protocol_preferences(struct s2n_config *config, const char *const *protocols, int protocol_count);
1120 : :
1121 : : /**
1122 : : * Enum used to define the type, if any, of certificate status request
1123 : : * a connection should make during the handshake. The only supported status request type is
1124 : : * OCSP, `S2N_STATUS_REQUEST_OCSP`.
1125 : : */
1126 : : typedef enum {
1127 : : S2N_STATUS_REQUEST_NONE = 0,
1128 : : S2N_STATUS_REQUEST_OCSP = 1
1129 : : } s2n_status_request_type;
1130 : :
1131 : : /**
1132 : : * Sets up a connection to request the certificate status of a peer during an SSL handshake. If set
1133 : : * to S2N_STATUS_REQUEST_NONE, no status request is made.
1134 : : *
1135 : : * @note SHA-1 is the only supported hash algorithm for the `certID` field. This is different
1136 : : * from the hash algorithm used for the OCSP signature. See
1137 : : * [RFC 6960](https://datatracker.ietf.org/doc/html/rfc6960#section-4.1.1) for more information.
1138 : : * While unlikely to be the case, if support for a different hash algorithm is required, the
1139 : : * s2n-tls validation can be disabled with `s2n_config_set_check_stapled_ocsp_response()` and the
1140 : : * response can be retrieved for manual validation with `s2n_connection_get_ocsp_response()`.
1141 : : *
1142 : : * @param config The configuration object being updated
1143 : : * @param type The desired request status type
1144 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1145 : : */
1146 : : S2N_API extern int s2n_config_set_status_request_type(struct s2n_config *config, s2n_status_request_type type);
1147 : :
1148 : : /**
1149 : : * Enum to set Certificate Transparency Support level.
1150 : : */
1151 : : typedef enum {
1152 : : S2N_CT_SUPPORT_NONE = 0,
1153 : : S2N_CT_SUPPORT_REQUEST = 1
1154 : : } s2n_ct_support_level;
1155 : :
1156 : : /**
1157 : : * Set the Certificate Transparency Support level.
1158 : : *
1159 : : * @param config The configuration object being updated
1160 : : * @param level The desired Certificate Transparency Support configuration
1161 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1162 : : */
1163 : : S2N_API extern int s2n_config_set_ct_support_level(struct s2n_config *config, s2n_ct_support_level level);
1164 : :
1165 : : /**
1166 : : * Sets whether or not a connection should terminate on receiving a WARNING alert from its peer.
1167 : : *
1168 : : * `alert_behavior` can take the following values:
1169 : : * - `S2N_ALERT_FAIL_ON_WARNINGS` default behavior: s2n-tls will terminate the connection if its peer sends a WARNING alert.
1170 : : * - `S2N_ALERT_IGNORE_WARNINGS` - with the exception of `close_notify` s2n-tls will ignore all WARNING alerts and keep communicating with its peer. This setting is ignored in TLS1.3
1171 : : *
1172 : : * @note TLS1.3 terminates a connection for all alerts except user_canceled.
1173 : : * @warning S2N_ALERT_FAIL_ON_WARNINGS is the recommended behavior. Past TLS protocol vulnerabilities have involved downgrading alerts to warnings.
1174 : : */
1175 : : typedef enum {
1176 : : S2N_ALERT_FAIL_ON_WARNINGS = 0,
1177 : : S2N_ALERT_IGNORE_WARNINGS = 1
1178 : : } s2n_alert_behavior;
1179 : :
1180 : : /**
1181 : : * Sets the config's alert behavior based on the `s2n_alert_behavior` enum.
1182 : : *
1183 : : * @param config The configuration object being updated
1184 : : * @param alert_behavior The desired alert behavior.
1185 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1186 : : */
1187 : : S2N_API extern int s2n_config_set_alert_behavior(struct s2n_config *config, s2n_alert_behavior alert_behavior);
1188 : :
1189 : : /**
1190 : : * Sets the extension data in the `s2n_config` object for the specified extension.
1191 : : * This method will clear any existing data that is set. If the data and length
1192 : : * parameters are set to NULL, no new data is set in the `s2n_config` object,
1193 : : * effectively clearing existing data.
1194 : : *
1195 : : * @deprecated Use s2n_cert_chain_and_key_set_ocsp_data and s2n_cert_chain_and_key_set_sct_list instead.
1196 : : *
1197 : : * @param config The configuration object being updated
1198 : : * @param type The extension type
1199 : : * @param data Data for the extension
1200 : : * @param length Length of the `data` buffer
1201 : : */
1202 : : S2N_API extern int s2n_config_set_extension_data(struct s2n_config *config, s2n_tls_extension_type type, const uint8_t *data, uint32_t length);
1203 : :
1204 : : /**
1205 : : * Allows the caller to set a TLS Maximum Fragment Length extension that will be used
1206 : : * to fragment outgoing messages. s2n-tls currently does not reject fragments larger
1207 : : * than the configured maximum when in server mode. The TLS negotiated maximum fragment
1208 : : * length overrides the preference set by the `s2n_connection_prefer_throughput` and
1209 : : * `s2n_connection_prefer_low_latency`.
1210 : : *
1211 : : * @note Some TLS implementations do not respect their peer's max fragment length extension.
1212 : : *
1213 : : * @param config The configuration object being updated
1214 : : * @param mfl_code The selected MFL size
1215 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1216 : : */
1217 : : S2N_API extern int s2n_config_send_max_fragment_length(struct s2n_config *config, s2n_max_frag_len mfl_code);
1218 : :
1219 : : /**
1220 : : * Allows the server to opt-in to accept client's TLS maximum fragment length extension
1221 : : * requests. If this API is not called, and client requests the extension, server will ignore
1222 : : * the request and continue TLS handshake with default maximum fragment length of 8k bytes
1223 : : *
1224 : : * @note Some TLS implementations do not respect their peer's max fragment length extension.
1225 : : *
1226 : : * @param config The configuration object being updated
1227 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1228 : : */
1229 : : S2N_API extern int s2n_config_accept_max_fragment_length(struct s2n_config *config);
1230 : :
1231 : : /**
1232 : : * Sets the lifetime of the cached session state. The default value is 15 hours.
1233 : : *
1234 : : * @param config The configuration object being updated
1235 : : * @param lifetime_in_secs The desired lifetime of the session state in seconds
1236 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1237 : : */
1238 : : S2N_API extern int s2n_config_set_session_state_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
1239 : :
1240 : : /**
1241 : : * Enable or disable session resumption using session ticket.
1242 : : *
1243 : : * @param config The configuration object being updated
1244 : : * @param enabled The configuration object being updated. Set to 1 to enable. Set to 0 to disable.
1245 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1246 : : */
1247 : : S2N_API extern int s2n_config_set_session_tickets_onoff(struct s2n_config *config, uint8_t enabled);
1248 : :
1249 : : /**
1250 : : * Enable or disable session caching.
1251 : : *
1252 : : * @note Session caching will not be turned on unless all three session cache callbacks are set
1253 : : * prior to calling this function.
1254 : : *
1255 : : * @param config The configuration object being updated
1256 : : * @param enabled The configuration object being updated. Set to 1 to enable. Set to 0 to disable.
1257 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1258 : : */
1259 : : S2N_API extern int s2n_config_set_session_cache_onoff(struct s2n_config *config, uint8_t enabled);
1260 : :
1261 : : /**
1262 : : * Sets how long a session ticket key will be in a state where it can be used for both encryption
1263 : : * and decryption of tickets on the server side.
1264 : : *
1265 : : * @note The default value is 2 hours.
1266 : : * @param config The configuration object being updated
1267 : : * @param lifetime_in_secs The desired lifetime of decrypting and encrypting tickets in seconds
1268 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1269 : : */
1270 : : S2N_API extern int s2n_config_set_ticket_encrypt_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
1271 : :
1272 : : /**
1273 : : * Sets how long a session ticket key will be in a state where it can used just for decryption of
1274 : : * already assigned tickets on the server side. Once decrypted, the session will resume and the
1275 : : * server will issue a new session ticket encrypted using a key in encrypt-decrypt state.
1276 : : *
1277 : : * @note The default value is 13 hours.
1278 : : * @param config The configuration object being updated
1279 : : * @param lifetime_in_secs The desired lifetime of decrypting and encrypting tickets in seconds
1280 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1281 : : */
1282 : : S2N_API extern int s2n_config_set_ticket_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
1283 : :
1284 : : /**
1285 : : * Adds session ticket key on the server side. It would be ideal to add new keys after every
1286 : : * (encrypt_decrypt_key_lifetime_in_nanos/2) nanos because this will allow for gradual and
1287 : : * linear transition of a key from encrypt-decrypt state to decrypt-only state.
1288 : : *
1289 : : * @param config The configuration object being updated
1290 : : * @param name Name of the session ticket key that should be randomly generated to avoid collisions
1291 : : * @param name_len Length of session ticket key name
1292 : : * @param key Key used to perform encryption/decryption of session ticket
1293 : : * @param key_len Length of the session ticket key
1294 : : * @param intro_time_in_seconds_from_epoch Time at which the session ticket key is introduced. If this is 0, then intro_time_in_seconds_from_epoch is set to now.
1295 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1296 : : */
1297 : : S2N_API extern int s2n_config_add_ticket_crypto_key(struct s2n_config *config, const uint8_t *name, uint32_t name_len,
1298 : : uint8_t *key, uint32_t key_len, uint64_t intro_time_in_seconds_from_epoch);
1299 : :
1300 : : /**
1301 : : * Requires that session tickets are only used when forward secrecy is possible.
1302 : : *
1303 : : * Restricts session resumption to TLS1.3, as the tickets used in TLS1.2 resumption are
1304 : : * not forward secret. Clients should not expect to receive new session tickets and servers
1305 : : * will not send new session tickets when TLS1.2 is negotiated and ticket forward secrecy is required.
1306 : : *
1307 : : * @note The default behavior is that forward secrecy is not required.
1308 : : *
1309 : : * @param config The config object being updated
1310 : : * @param enabled Indicates if forward secrecy is required or not on tickets
1311 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1312 : : */
1313 : : S2N_API extern int s2n_config_require_ticket_forward_secrecy(struct s2n_config *config, bool enabled);
1314 : :
1315 : : /**
1316 : : * Sets user defined context on the `s2n_config` object.
1317 : : *
1318 : : * @param config The configuration object being updated
1319 : : * @param ctx A pointer to the user defined ctx.
1320 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1321 : : */
1322 : : S2N_API extern int s2n_config_set_ctx(struct s2n_config *config, void *ctx);
1323 : :
1324 : : /**
1325 : : * Gets the user defined context from the `s2n_config` object.
1326 : : * The context is set by calling s2n_config_set_ctx()
1327 : : *
1328 : : * @param config The configuration object being accessed
1329 : : * @param ctx A pointer to the user defined ctx.
1330 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1331 : : */
1332 : : S2N_API extern int s2n_config_get_ctx(struct s2n_config *config, void **ctx);
1333 : :
1334 : : /**
1335 : : * Used to declare connections as server or client type, respectively.
1336 : : */
1337 : : typedef enum {
1338 : : S2N_SERVER,
1339 : : S2N_CLIENT
1340 : : } s2n_mode;
1341 : :
1342 : : /**
1343 : : * Creates a new connection object. Each s2n-tls SSL/TLS connection uses
1344 : : * one of these objects. These connection objects can be operated on by up
1345 : : * to two threads at a time, one sender and one receiver, but neither sending
1346 : : * nor receiving are atomic, so if these objects are being called by multiple
1347 : : * sender or receiver threads, you must perform your own locking to ensure
1348 : : * that only one sender or receiver is active at a time.
1349 : : *
1350 : : * The `mode` parameters specifies if the caller is a server, or is a client.
1351 : : * Connections objects are re-usable across many connections, and should be
1352 : : * re-used (to avoid deallocating and allocating memory). You should wipe
1353 : : * connections immediately after use.
1354 : : *
1355 : : * @param mode The desired connection type
1356 : : * @returns A s2n_connection handle
1357 : : */
1358 : : S2N_API extern struct s2n_connection *s2n_connection_new(s2n_mode mode);
1359 : :
1360 : : /**
1361 : : * Associates a configuration object with a connection.
1362 : : *
1363 : : * @param conn The connection object being associated
1364 : : * @param config The configuration object being associated
1365 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1366 : : */
1367 : : S2N_API extern int s2n_connection_set_config(struct s2n_connection *conn, struct s2n_config *config);
1368 : :
1369 : : /**
1370 : : * Sets user defined context in `s2n_connection` object.
1371 : : *
1372 : : * @param conn The connection object being updated
1373 : : * @param ctx A pointer to the user defined context
1374 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1375 : : */
1376 : : S2N_API extern int s2n_connection_set_ctx(struct s2n_connection *conn, void *ctx);
1377 : :
1378 : : /**
1379 : : * Gets user defined context from a `s2n_connection` object.
1380 : : *
1381 : : * @param conn The connection object that contains the desired context
1382 : : */
1383 : : S2N_API extern void *s2n_connection_get_ctx(struct s2n_connection *conn);
1384 : :
1385 : : /**
1386 : : * The callback function takes a s2n-tls connection as input, which receives the ClientHello
1387 : : * and the context previously provided in `s2n_config_set_client_hello_cb`. The callback can
1388 : : * access any ClientHello information from the connection and use the `s2n_connection_set_config`
1389 : : * call to change the config of the connection.
1390 : : */
1391 : : typedef int s2n_client_hello_fn(struct s2n_connection *conn, void *ctx);
1392 : :
1393 : : /**
1394 : : * Client Hello callback modes
1395 : : * - `S2N_CLIENT_HELLO_CB_BLOCKING` (default):
1396 : : * - In this mode s2n-tls expects the callback to complete its work and return the appropriate response code before the handshake continues. If any of the connection properties were changed based on the server_name extension the callback must either return a value greater than 0 or invoke `s2n_connection_server_name_extension_used`, otherwise the callback returns 0 to continue the handshake.
1397 : : * - `S2N_CLIENT_HELLO_CB_NONBLOCKING`:
1398 : : * - In non-blocking mode, s2n-tls expects the callback to not complete its work. If the callback returns a response code of 0, s2n-tls will return `S2N_FAILURE` with `S2N_ERR_T_BLOCKED` error type and `s2n_blocked_status` set to `S2N_BLOCKED_ON_APPLICATION_INPUT`. The handshake is paused and further calls to `s2n_negotiate` will continue to return the same error until `s2n_client_hello_cb_done` is invoked for the `s2n_connection` to resume the handshake. If any of the connection properties were changed on the basis of the server_name extension then `s2n_connection_server_name_extension_used` must be invoked before marking the callback done.
1399 : : */
1400 : : typedef enum {
1401 : : S2N_CLIENT_HELLO_CB_BLOCKING,
1402 : : S2N_CLIENT_HELLO_CB_NONBLOCKING
1403 : : } s2n_client_hello_cb_mode;
1404 : :
1405 : : /**
1406 : : * Allows the caller to set a callback function that will be called after ClientHello was parsed.
1407 : : *
1408 : : * @param config The configuration object being updated
1409 : : * @param client_hello_callback The client hello callback function
1410 : : * @param ctx A pointer to a user defined context that the Client Hello callback will be invoked with.
1411 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1412 : : */
1413 : : S2N_API extern int s2n_config_set_client_hello_cb(struct s2n_config *config, s2n_client_hello_fn client_hello_callback, void *ctx);
1414 : :
1415 : : /**
1416 : : * Sets the callback execution mode.
1417 : : *
1418 : : * See s2n_client_hello_cb_mode for each mode's behavior.
1419 : : *
1420 : : * @param config The configuration object being updated
1421 : : * @param cb_mode The desired callback mode
1422 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1423 : : */
1424 : : S2N_API extern int s2n_config_set_client_hello_cb_mode(struct s2n_config *config, s2n_client_hello_cb_mode cb_mode);
1425 : :
1426 : : /**
1427 : : * Marks the non-blocking callback as complete. Can be invoked from within the callback when
1428 : : * operating in non-blocking mode to continue the handshake.
1429 : : *
1430 : : * @param conn The connection object being updated
1431 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1432 : : */
1433 : : S2N_API extern int s2n_client_hello_cb_done(struct s2n_connection *conn);
1434 : :
1435 : : /**
1436 : : * Must be invoked if any of the connection properties were changed on the basis of the server_name
1437 : : * extension. This must be invoked before marking the Client Hello callback done.
1438 : : *
1439 : : * @param conn The connection object being updated
1440 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1441 : : */
1442 : : S2N_API extern int s2n_connection_server_name_extension_used(struct s2n_connection *conn);
1443 : :
1444 : : /**
1445 : : * Opaque client hello handle
1446 : : */
1447 : : struct s2n_client_hello;
1448 : :
1449 : : /**
1450 : : * Get the Client Hello from a s2n_connection.
1451 : : *
1452 : : * Earliest point during the handshake when this structure is available for use is in the
1453 : : * client_hello_callback (see s2n_config_set_client_hello_cb()).
1454 : : *
1455 : : * @param conn The connection object containing the client hello
1456 : : * @returns A handle to the s2n_client_hello structure holding the client hello message sent by the client during the handshake. NULL is returned if a Client Hello has not yet been received and parsed.
1457 : : */
1458 : : S2N_API extern struct s2n_client_hello *s2n_connection_get_client_hello(struct s2n_connection *conn);
1459 : :
1460 : : /**
1461 : : * Creates an s2n_client_hello from bytes representing a ClientHello message.
1462 : : *
1463 : : * The input bytes should include the message header (message type and length),
1464 : : * but not the record header.
1465 : : *
1466 : : * Unlike s2n_connection_get_client_hello, the s2n_client_hello returned by this
1467 : : * method is owned by the application and must be freed with s2n_client_hello_free.
1468 : : *
1469 : : * This method does not support SSLv2 ClientHellos.
1470 : : *
1471 : : * @param bytes The raw bytes representing the ClientHello.
1472 : : * @param size The size of raw_message.
1473 : : * @returns A new s2n_client_hello on success, or NULL on failure.
1474 : : */
1475 : : S2N_API extern struct s2n_client_hello *s2n_client_hello_parse_message(const uint8_t *bytes, uint32_t size);
1476 : :
1477 : : /**
1478 : : * Frees an s2n_client_hello structure.
1479 : : *
1480 : : * This method should be called to free s2n_client_hellos returned by
1481 : : * s2n_client_hello_parse_message. It will error if passed an s2n_client_hello
1482 : : * returned by s2n_connection_get_client_hello and owned by the connection.
1483 : : *
1484 : : * @param ch The structure to be freed.
1485 : : * @returns S2N_SUCCESS on success, S2N_FAILURE on failure.
1486 : : */
1487 : : S2N_API extern int s2n_client_hello_free(struct s2n_client_hello **ch);
1488 : :
1489 : : /**
1490 : : * Function to determine the size of the raw Client Hello buffer.
1491 : : *
1492 : : * Can be used to determine the necessary size of the `out` buffer for
1493 : : * s2n_client_hello_get_raw_message()
1494 : : *
1495 : : * @param ch The Client Hello handle
1496 : : * @returns The size of the ClientHello message received by the server
1497 : : */
1498 : : S2N_API extern ssize_t s2n_client_hello_get_raw_message_length(struct s2n_client_hello *ch);
1499 : :
1500 : : /**
1501 : : * Copies `max_length` bytes of the ClientHello message into the `out` buffer.
1502 : : * The ClientHello instrumented using this function will have the Random bytes
1503 : : * zero-ed out.
1504 : : *
1505 : : * Note: SSLv2 ClientHello messages follow a different structure than more modern
1506 : : * ClientHello messages. See [RFC5246](https://tools.ietf.org/html/rfc5246#appendix-E.2).
1507 : : * In addition, due to how s2n-tls parses SSLv2 ClientHellos, the raw message is
1508 : : * missing the first three bytes (the msg_type and version) and instead begins with
1509 : : * the cipher_specs. To determine whether a ClientHello is an SSLv2 ClientHello,
1510 : : * you will need to use s2n_connection_get_client_hello_version(). To get the
1511 : : * protocol version advertised in the SSLv2 ClientHello (which may be higher
1512 : : * than SSLv2), you will need to use s2n_connection_get_client_protocol_version().
1513 : : *
1514 : : * @param ch The Client Hello handle
1515 : : * @param out The destination buffer for the raw Client Hello
1516 : : * @param max_length The size of out in bytes
1517 : : * @returns The number of copied bytes
1518 : : */
1519 : : S2N_API extern ssize_t s2n_client_hello_get_raw_message(struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length);
1520 : :
1521 : : /**
1522 : : * Function to determine the size of the Client Hello cipher suites.
1523 : : * This can be used to allocate the `out` buffer for s2n_client_hello_get_cipher_suites().
1524 : : *
1525 : : * @param ch The Client Hello handle
1526 : : * @returns the number of bytes the cipher_suites takes on the ClientHello message received by the server
1527 : : */
1528 : : S2N_API extern ssize_t s2n_client_hello_get_cipher_suites_length(struct s2n_client_hello *ch);
1529 : :
1530 : : /**
1531 : : * Copies into the `out` buffer `max_length` bytes of the cipher_suites on the ClientHello.
1532 : : *
1533 : : * Note: SSLv2 ClientHello cipher suites follow a different structure than modern
1534 : : * ClientHello messages. See [RFC5246](https://tools.ietf.org/html/rfc5246#appendix-E.2).
1535 : : * To determine whether a ClientHello is an SSLv2 ClientHello,
1536 : : * you will need to use s2n_connection_get_client_hello_version().
1537 : : *
1538 : : * @param ch The Client Hello handle
1539 : : * @param out The destination buffer for the raw Client Hello cipher suites
1540 : : * @param max_length The size of out in bytes
1541 : : * @returns The number of copied bytes
1542 : : */
1543 : : S2N_API extern ssize_t s2n_client_hello_get_cipher_suites(struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length);
1544 : :
1545 : : /**
1546 : : * Function to determine the size of the Client Hello extensions.
1547 : : * This can be used to allocate the `out` buffer for s2n_client_hello_get_extensions().
1548 : : *
1549 : : * @param ch The Client Hello handle
1550 : : * @returns the number of bytes the extensions take in the ClientHello message received by the server
1551 : : */
1552 : : S2N_API extern ssize_t s2n_client_hello_get_extensions_length(struct s2n_client_hello *ch);
1553 : :
1554 : : /**
1555 : : * Copies into the `out` buffer `max_length` bytes of the extensions in the ClientHello.
1556 : : *
1557 : : * @param ch The Client Hello handle
1558 : : * @param out The destination buffer for the raw Client Hello extensions
1559 : : * @param max_length The size of out in bytes
1560 : : * @returns The number of copied bytes
1561 : : */
1562 : : S2N_API extern ssize_t s2n_client_hello_get_extensions(struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length);
1563 : :
1564 : : /**
1565 : : * Query the ClientHello message received by the server. Use this function to allocate the `out` buffer for
1566 : : * other client hello extension functions.
1567 : : *
1568 : : * @param ch A pointer to the Client Hello
1569 : : * @param extension_type Indicates the desired extension
1570 : : * @returns The number of bytes the given extension type takes
1571 : : */
1572 : : S2N_API extern ssize_t s2n_client_hello_get_extension_length(struct s2n_client_hello *ch, s2n_tls_extension_type extension_type);
1573 : :
1574 : : /**
1575 : : * Copies into the `out` buffer `max_length` bytes of a given extension type on the ClientHello
1576 : : *
1577 : : * `ch` is a pointer to the `s2n_client_hello` of the `s2n_connection` which can be obtained using s2n_connection_get_client_hello().
1578 : : *
1579 : : * @param ch A pointer to the Client Hello
1580 : : * @param extension_type Indicates the desired extension
1581 : : * @param out A pointer to the buffer that s2n will write the client session id to. This buffer MUST be the size of `max_length`
1582 : : * @param max_length The size of `out`.
1583 : : * @returns The number of copied bytes
1584 : : */
1585 : : S2N_API extern ssize_t s2n_client_hello_get_extension_by_id(struct s2n_client_hello *ch, s2n_tls_extension_type extension_type, uint8_t *out, uint32_t max_length);
1586 : :
1587 : : /**
1588 : : * Used to check if a particular extension exists in the client hello.
1589 : : *
1590 : : * `ch` is a pointer to the `s2n_client_hello` of the `s2n_connection` which can be obtained using s2n_connection_get_client_hello().
1591 : : *
1592 : : * @param ch A pointer to the client hello object
1593 : : * @param extension_iana The iana value of the extension
1594 : : * @param exists A pointer that will be set to whether or not the extension exists
1595 : : */
1596 : : S2N_API extern int s2n_client_hello_has_extension(struct s2n_client_hello *ch, uint16_t extension_iana, bool *exists);
1597 : :
1598 : : /**
1599 : : * Get the the ClientHello session id length in bytes
1600 : : *
1601 : : * `ch` is a pointer to the `s2n_client_hello` of the `s2n_connection` which can be obtained using s2n_connection_get_client_hello().
1602 : : *
1603 : : * @param ch A pointer to the Client Hello
1604 : : * @param out_length An out pointer. s2n will set it's value to the size of the session_id in bytes.
1605 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1606 : : */
1607 : : S2N_API extern int s2n_client_hello_get_session_id_length(struct s2n_client_hello *ch, uint32_t *out_length);
1608 : :
1609 : : /**
1610 : : * Copies up to `max_length` bytes of the ClientHello session_id into the `out` buffer and stores the number of copied bytes in `out_length`.
1611 : : *
1612 : : * Retrieve the session id as sent by the client in the ClientHello message. The session id on the `s2n_connection` may change later
1613 : : * when the server sends the ServerHello; see `s2n_connection_get_session_id` for how to get the final session id used for future session resumption.
1614 : : *
1615 : : * Use s2n_client_hello_get_session_id_length() to get the the ClientHello session id length in bytes. `ch` is a pointer to the `s2n_client_hello`
1616 : : * of the `s2n_connection` which can be obtained using s2n_connection_get_client_hello().
1617 : : *
1618 : : * @param ch A pointer to the Client Hello
1619 : : * @param out A pointer to the buffer that s2n will write the client session id to. This buffer MUST be the size of `max_length`
1620 : : * @param out_length An out pointer. s2n will set it's value to the size of the session_id in bytes.
1621 : : * @param max_length The size of `out`.
1622 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1623 : : */
1624 : : S2N_API extern int s2n_client_hello_get_session_id(struct s2n_client_hello *ch, uint8_t *out, uint32_t *out_length, uint32_t max_length);
1625 : :
1626 : : /**
1627 : : * Get the length of the compression methods list sent in the Client Hello.
1628 : : *
1629 : : * @param ch A pointer to the Client Hello
1630 : : * @param out_length An out pointer. Will be set to the length of the compression methods list in bytes.
1631 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1632 : : */
1633 : : S2N_API extern int s2n_client_hello_get_compression_methods_length(struct s2n_client_hello *ch, uint32_t *out_length);
1634 : :
1635 : : /**
1636 : : * Retrieves the list of compression methods sent in the Client Hello.
1637 : : *
1638 : : * Use `s2n_client_hello_get_compression_methods_length()`
1639 : : * to retrieve how much memory should be allocated for the buffer in advance.
1640 : : *
1641 : : * @note Compression methods were removed in TLS1.3 and therefore the only valid value in this list is the
1642 : : * "null" compression method when TLS1.3 is negotiated.
1643 : : *
1644 : : * @note s2n-tls has never supported compression methods in any TLS version and therefore a
1645 : : * compression method will never be negotiated or used.
1646 : : *
1647 : : * @param ch A pointer to the Client Hello
1648 : : * @param list A pointer to some memory that s2n will write the compression methods to. This memory MUST be the size of `list_length`
1649 : : * @param list_length The size of `list`.
1650 : : * @param out_length An out pointer. s2n will set its value to the size of the compression methods list in bytes.
1651 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1652 : : */
1653 : : S2N_API extern int s2n_client_hello_get_compression_methods(struct s2n_client_hello *ch, uint8_t *list, uint32_t list_length, uint32_t *out_length);
1654 : :
1655 : : /**
1656 : : * Access the Client Hello protocol version
1657 : : *
1658 : : * @note This field is a legacy field in TLS1.3 and is no longer used to negotiate the
1659 : : * protocol version of the connection. It will be set to TLS1.2 even if TLS1.3 is negotiated.
1660 : : * Therefore this method should only be used for logging or fingerprinting.
1661 : : *
1662 : : * @param ch A pointer to the client hello struct
1663 : : * @param out The protocol version in the client hello.
1664 : : */
1665 : : S2N_API extern int s2n_client_hello_get_legacy_protocol_version(struct s2n_client_hello *ch, uint8_t *out);
1666 : :
1667 : : /**
1668 : : * Retrieves the supported groups received from the client in the supported groups extension.
1669 : : *
1670 : : * IANA values for each of the received supported groups are written to the provided `groups`
1671 : : * array, and `groups_count` is set to the number of received supported groups.
1672 : : *
1673 : : * `groups_count_max` should be set to the maximum capacity of the `groups` array. If
1674 : : * `groups_count_max` is less than the number of received supported groups, this function will
1675 : : * error. To determine how large `groups` should be in advance, use
1676 : : * `s2n_client_hello_get_extension_length()` with the S2N_EXTENSION_SUPPORTED_GROUPS extension
1677 : : * type, and divide the value by 2.
1678 : : *
1679 : : * If no supported groups extension was received from the peer, or the received supported groups
1680 : : * extension is malformed, this function will error.
1681 : : *
1682 : : * @param ch A pointer to the ClientHello. Can be retrieved from a connection via
1683 : : * `s2n_connection_get_client_hello()`.
1684 : : * @param groups The array to populate with the received supported groups.
1685 : : * @param groups_count_max The maximum number of supported groups that can fit in the `groups` array.
1686 : : * @param groups_count Returns the number of received supported groups.
1687 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
1688 : : */
1689 : : S2N_API extern int s2n_client_hello_get_supported_groups(struct s2n_client_hello *ch, uint16_t *groups,
1690 : : uint16_t groups_count_max, uint16_t *groups_count);
1691 : :
1692 : : /**
1693 : : * Gets the length of the first server name in a Client Hello.
1694 : : *
1695 : : * @param ch A pointer to the ClientHello
1696 : : * @param length A pointer which will be populated with the length of the server name
1697 : : */
1698 : : S2N_API extern int s2n_client_hello_get_server_name_length(struct s2n_client_hello *ch, uint16_t *length);
1699 : :
1700 : : /**
1701 : : * Gets the first server name in a Client Hello.
1702 : : *
1703 : : * Use `s2n_client_hello_get_server_name_length()` to get the amount of memory needed for the buffer.
1704 : : *
1705 : : * @param ch A pointer to the ClientHello
1706 : : * @param server_name A pointer to the memory which will be populated with the server name
1707 : : * @param length The maximum amount of data that can be written to `server_name`
1708 : : * @param out_length A pointer which will be populated with the size of the server name
1709 : : */
1710 : : S2N_API extern int s2n_client_hello_get_server_name(struct s2n_client_hello *ch, uint8_t *server_name, uint16_t length, uint16_t *out_length);
1711 : :
1712 : : /**
1713 : : * Sets the file descriptor for a s2n connection.
1714 : : *
1715 : : * @warning If the read end of the pipe is closed unexpectedly, writing to the pipe will raise a SIGPIPE signal.
1716 : : * **s2n-tls does NOT handle SIGPIPE.** A SIGPIPE signal will cause the process to terminate unless it is handled
1717 : : * or ignored by the application.
1718 : : * @note This file-descriptor should be active and connected
1719 : : * @param conn A pointer to the s2n connection
1720 : : * @param fd The new file descriptor
1721 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1722 : : */
1723 : : S2N_API extern int s2n_connection_set_fd(struct s2n_connection *conn, int fd);
1724 : :
1725 : : /**
1726 : : * Sets the file descriptor for the read channel of an s2n connection.
1727 : : *
1728 : : * @warning If the read end of the pipe is closed unexpectedly, writing to the pipe will raise a SIGPIPE signal.
1729 : : * **s2n-tls does NOT handle SIGPIPE.** A SIGPIPE signal will cause the process to terminate unless it is handled
1730 : : * or ignored by the application.
1731 : : * @note This file-descriptor should be active and connected
1732 : : * @param conn A pointer to the s2n connection
1733 : : * @param readfd The new read file descriptor
1734 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1735 : : */
1736 : : S2N_API extern int s2n_connection_set_read_fd(struct s2n_connection *conn, int readfd);
1737 : :
1738 : : /**
1739 : : * Sets the assigned file descriptor for the write channel of an s2n connection.
1740 : : *
1741 : : * @note This file-descriptor should be active and connected
1742 : : * @param conn A pointer to the s2n connection
1743 : : * @param writefd The new write file descriptor
1744 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1745 : : */
1746 : : S2N_API extern int s2n_connection_set_write_fd(struct s2n_connection *conn, int writefd);
1747 : :
1748 : : /**
1749 : : * Gets the assigned file descriptor for the read channel of an s2n connection.
1750 : : *
1751 : : * @param conn A pointer to the s2n connection
1752 : : * @param readfd pointer to place the used file descriptor.
1753 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1754 : : */
1755 : : S2N_API extern int s2n_connection_get_read_fd(struct s2n_connection *conn, int *readfd);
1756 : :
1757 : : /**
1758 : : * Gets the assigned file descriptor for the write channel of an s2n connection.
1759 : : *
1760 : : * @param conn A pointer to the s2n connection
1761 : : * @param writefd pointer to place the used file descriptor.
1762 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1763 : : */
1764 : : S2N_API extern int s2n_connection_get_write_fd(struct s2n_connection *conn, int *writefd);
1765 : :
1766 : : /**
1767 : : * Indicates to s2n that the connection is using corked IO.
1768 : : *
1769 : : * @warning This API should only be used when using managed send IO.
1770 : : *
1771 : : * @param conn The connection object being updated
1772 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1773 : : */
1774 : : S2N_API extern int s2n_connection_use_corked_io(struct s2n_connection *conn);
1775 : :
1776 : : /**
1777 : : * Function pointer for a user provided recv callback.
1778 : : */
1779 : : typedef int s2n_recv_fn(void *io_context, uint8_t *buf, uint32_t len);
1780 : :
1781 : : /**
1782 : : * Function pointer for a user provided send callback.
1783 : : */
1784 : : typedef int s2n_send_fn(void *io_context, const uint8_t *buf, uint32_t len);
1785 : :
1786 : : /**
1787 : : * Set a context containing anything needed in the recv callback function (for example,
1788 : : * a file descriptor), the buffer holding data to be sent or received, and the length of the buffer.
1789 : : *
1790 : : * @note The `io_context` passed to the callbacks may be set separately using `s2n_connection_set_recv_ctx` and `s2n_connection_set_send_ctx`.
1791 : : *
1792 : : * @param conn The connection object being updated
1793 : : * @param ctx A user provided context that the callback will be invoked with
1794 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1795 : : */
1796 : : S2N_API extern int s2n_connection_set_recv_ctx(struct s2n_connection *conn, void *ctx);
1797 : :
1798 : : /**
1799 : : * Set a context containing anything needed in the send callback function (for example,
1800 : : * a file descriptor), the buffer holding data to be sent or received, and the length of the buffer.
1801 : : *
1802 : : * @note The `io_context` passed to the callbacks may be set separately using `s2n_connection_set_recv_ctx` and `s2n_connection_set_send_ctx`.
1803 : : *
1804 : : * @param conn The connection object being updated
1805 : : * @param ctx A user provided context that the callback will be invoked with
1806 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1807 : : */
1808 : : S2N_API extern int s2n_connection_set_send_ctx(struct s2n_connection *conn, void *ctx);
1809 : :
1810 : : /**
1811 : : * Configure a connection to use a recv callback to receive data.
1812 : : *
1813 : : * @note This callback may be blocking or nonblocking.
1814 : : * @note The callback may receive less than the requested length. The function should return the number
1815 : : * of bytes received, or set errno and return an error code < 0.
1816 : : *
1817 : : * @param conn The connection object being updated
1818 : : * @param recv A recv callback function pointer
1819 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1820 : : */
1821 : : S2N_API extern int s2n_connection_set_recv_cb(struct s2n_connection *conn, s2n_recv_fn recv);
1822 : :
1823 : : /**
1824 : : * Configure a connection to use a send callback to send data.
1825 : : *
1826 : : * @note This callback may be blocking or nonblocking.
1827 : : * @note The callback may send less than the requested length. The function should return the
1828 : : * number of bytes sent or set errno and return an error code < 0.
1829 : : *
1830 : : * @param conn The connection object being updated
1831 : : * @param send A send callback function pointer
1832 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1833 : : */
1834 : : S2N_API extern int s2n_connection_set_send_cb(struct s2n_connection *conn, s2n_send_fn send);
1835 : :
1836 : : /**
1837 : : * Change the behavior of s2n-tls when sending data to prefer high throughput.
1838 : : *
1839 : : * Connections preferring throughput will use
1840 : : * large record sizes that minimize overhead.
1841 : : *
1842 : : * @param conn The connection object being updated
1843 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1844 : : */
1845 : : S2N_API extern int s2n_connection_prefer_throughput(struct s2n_connection *conn);
1846 : :
1847 : : /**
1848 : : * Change the behavior of s2n-tls when sending data to prefer low latency.
1849 : : *
1850 : : * Connections preferring low latency will be encrypted
1851 : : * using small record sizes that can be decrypted sooner by the recipient.
1852 : : *
1853 : : * @param conn The connection object being updated
1854 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1855 : : */
1856 : : S2N_API extern int s2n_connection_prefer_low_latency(struct s2n_connection *conn);
1857 : :
1858 : : /**
1859 : : * Configure the connection to reduce potentially expensive calls to recv.
1860 : : *
1861 : : * If this setting is disabled, s2n-tls will call read twice for every TLS record,
1862 : : * which can be expensive but ensures that s2n-tls will always attempt to read the
1863 : : * exact number of bytes it requires. If this setting is enabled, s2n-tls will
1864 : : * instead reduce the number of calls to read by attempting to read as much data
1865 : : * as possible in each read call, storing the extra in the existing IO buffers.
1866 : : * This may cause it to request more data than will ever actually be available.
1867 : : *
1868 : : * There is no additional memory cost of enabling this setting. It reuses the
1869 : : * existing IO buffers.
1870 : : *
1871 : : * This setting is disabled by default. Depending on how your application detects
1872 : : * data available for reading, buffering reads may break your event loop.
1873 : : * In particular, note that:
1874 : : *
1875 : : * 1. File descriptor reads or calls to your custom s2n_recv_cb may request more
1876 : : * data than is available. Reads must return partial data when available rather
1877 : : * than blocking until all requested data is available.
1878 : : *
1879 : : * 2. s2n_negotiate may read and buffer application data records.
1880 : : * You must call s2n_recv at least once after negotiation to ensure that you
1881 : : * handle any buffered data.
1882 : : *
1883 : : * 3. s2n_recv may read and buffer more records than it parses and decrypts.
1884 : : * You must call s2n_recv until it reports S2N_ERR_T_BLOCKED, rather than just
1885 : : * until it reports S2N_SUCCESS.
1886 : : *
1887 : : * 4. s2n_peek reports available decrypted data. It does not report any data
1888 : : * buffered by this feature. However, s2n_peek_buffered does report data
1889 : : * buffered by this feature.
1890 : : *
1891 : : * 5. s2n_connection_release_buffers will not release the input buffer if it
1892 : : * contains buffered data.
1893 : : *
1894 : : * For example: if your event loop uses `poll`, you will receive a POLLIN event
1895 : : * for your read file descriptor when new data is available. When you call s2n_recv
1896 : : * to read that data, s2n-tls reads one or more TLS records from the file descriptor.
1897 : : * If you stop calling s2n_recv before it reports S2N_ERR_T_BLOCKED, some of those
1898 : : * records may remain in s2n-tls's read buffer. If you read part of a record,
1899 : : * s2n_peek will report the remainder of that record as available. But if you don't
1900 : : * read any of a record, it remains encrypted and is not reported by s2n_peek, but
1901 : : * is still reported by s2n_peek_buffered. And because the data is buffered in s2n-tls
1902 : : * instead of in the file descriptor, another call to `poll` will NOT report any
1903 : : * more data available. Your application may hang waiting for more data.
1904 : : *
1905 : : * @warning This feature cannot be enabled for a connection that will enable kTLS for receiving.
1906 : : *
1907 : : * @warning This feature may work with blocking IO, if used carefully. Your blocking
1908 : : * IO must support partial reads (so MSG_WAITALL cannot be used). You will either
1909 : : * need to know exactly how much data your peer is sending, or will need to use
1910 : : * `s2n_peek` and `s2n_peek_buffered` rather than relying on S2N_ERR_T_BLOCKED
1911 : : * as noted in #3 above.
1912 : : *
1913 : : * @param conn The connection object being updated
1914 : : * @param enabled Set to `true` to enable, `false` to disable.
1915 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1916 : : */
1917 : : S2N_API extern int s2n_connection_set_recv_buffering(struct s2n_connection *conn, bool enabled);
1918 : :
1919 : : /**
1920 : : * Reports how many bytes of unprocessed TLS records are buffered due to the optimization
1921 : : * enabled by `s2n_connection_set_recv_buffering`.
1922 : : *
1923 : : * `s2n_peek_buffered` is not a replacement for `s2n_peek`.
1924 : : * While `s2n_peek` reports application data that is ready for the application
1925 : : * to read with no additional processing, `s2n_peek_buffered` reports raw TLS
1926 : : * records that still need to be parsed and likely decrypted. Those records may
1927 : : * contain application data, but they may also only contain TLS control messages.
1928 : : *
1929 : : * If an application needs to determine whether there is any data left to handle
1930 : : * (for example, before calling `poll` to wait on the read file descriptor) then
1931 : : * that application must check both `s2n_peek` and `s2n_peek_buffered`.
1932 : : *
1933 : : * @param conn A pointer to the s2n_connection object
1934 : : * @returns The number of buffered encrypted bytes
1935 : : */
1936 : : S2N_API extern uint32_t s2n_peek_buffered(struct s2n_connection *conn);
1937 : :
1938 : : /**
1939 : : * Configure the connection to free IO buffers when they are not currently in use.
1940 : : *
1941 : : * This configuration can be used to minimize connection memory footprint size, at the cost
1942 : : * of more calls to alloc and free. Some of these costs can be mitigated by configuring s2n-tls
1943 : : * to use an allocator that includes thread-local caches or lock-free allocation patterns.
1944 : : *
1945 : : * @param conn The connection object being update
1946 : : * @param enabled Set to `true` if dynamic buffers are enabled; `false` if disabled
1947 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1948 : : */
1949 : : S2N_API extern int s2n_connection_set_dynamic_buffers(struct s2n_connection *conn, bool enabled);
1950 : :
1951 : : /**
1952 : : * Changes the behavior of s2n-tls when sending data to initially prefer records
1953 : : * small enough to fit in single ethernet frames.
1954 : : *
1955 : : * When dynamic record sizing is active, the connection sends records small enough
1956 : : * to fit in a single standard 1500 byte ethernet frame. Otherwise, the connection
1957 : : * chooses record sizes according to the configured maximum fragment length.
1958 : : *
1959 : : * Dynamic record sizing is active for the first resize_threshold bytes of a connection,
1960 : : * and is reactivated whenever timeout_threshold seconds pass without sending data.
1961 : : *
1962 : : * @param conn The connection object being updated
1963 : : * @param resize_threshold The number of bytes to send before changing the record size. Maximum 8MiB.
1964 : : * @param timeout_threshold Reset record size back to a single segment after threshold seconds of inactivity
1965 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1966 : : */
1967 : : S2N_API extern int s2n_connection_set_dynamic_record_threshold(struct s2n_connection *conn, uint32_t resize_threshold, uint16_t timeout_threshold);
1968 : :
1969 : : /**
1970 : : * Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.
1971 : : *
1972 : : * The default behavior is to require that the hostname match the server name set with s2n_set_server_name(). This will
1973 : : * likely lead to all client certificates being rejected, so the callback will need to be overriden when using client authentication.
1974 : : *
1975 : : * If a single callback for different connections using the same config is desired, see s2n_config_set_verify_host_callback().
1976 : : *
1977 : : * @param conn A pointer to a s2n_connection object
1978 : : * @param host_fn A pointer to a callback function that s2n will invoke in order to verify the hostname of an X.509 certificate
1979 : : * @param data Opaque pointer to data that the verify host function will be invoked with
1980 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
1981 : : */
1982 : : S2N_API extern int s2n_connection_set_verify_host_callback(struct s2n_connection *conn, s2n_verify_host_fn host_fn, void *data);
1983 : :
1984 : : /**
1985 : : * Used to opt-out of s2n-tls's built-in blinding. Blinding is a
1986 : : * mitigation against timing side-channels which in some cases can leak information
1987 : : * about encrypted data. By default s2n-tls will cause a thread to sleep between 10 and
1988 : : * 30 seconds whenever tampering is detected.
1989 : : *
1990 : : * Setting the S2N_SELF_SERVICE_BLINDING option with s2n_connection_set_blinding()
1991 : : * turns off this behavior. This is useful for applications that are handling many connections
1992 : : * in a single thread. In that case, if s2n_recv() or s2n_negotiate() return an error,
1993 : : * self-service applications should call s2n_connection_get_delay() and pause
1994 : : * activity on the connection for the specified number of nanoseconds before calling
1995 : : * close() or shutdown().
1996 : : */
1997 : : typedef enum {
1998 : : S2N_BUILT_IN_BLINDING,
1999 : : S2N_SELF_SERVICE_BLINDING
2000 : : } s2n_blinding;
2001 : :
2002 : : /**
2003 : : * Used to configure s2n-tls to either use built-in blinding (set blinding to S2N_BUILT_IN_BLINDING) or
2004 : : * self-service blinding (set blinding to S2N_SELF_SERVICE_BLINDING).
2005 : : *
2006 : : * @param conn The connection object being updated
2007 : : * @param blinding The desired blinding mode for the connection
2008 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2009 : : */
2010 : : S2N_API extern int s2n_connection_set_blinding(struct s2n_connection *conn, s2n_blinding blinding);
2011 : :
2012 : : /**
2013 : : * Query the connection object for the configured blinding delay.
2014 : : * @param conn The connection object being updated
2015 : : * @returns the number of nanoseconds an application using self-service blinding should pause before calling close() or shutdown().
2016 : : */
2017 : : S2N_API extern uint64_t s2n_connection_get_delay(struct s2n_connection *conn);
2018 : :
2019 : : /**
2020 : : * Configures the maximum blinding delay enforced after errors.
2021 : : *
2022 : : * Blinding protects your application from timing side channel attacks like Lucky13. While s2n-tls
2023 : : * implements other, more specific mitigations for known timing side channels, blinding is important
2024 : : * as a defense against currently unknown or unreported timing attacks.
2025 : : *
2026 : : * Setting a maximum delay lower than the recommended default (30s) will make timing attacks against
2027 : : * your application easier. The lower you set the delay, the fewer requests and less total time an
2028 : : * attacker will require to execute an attack. If you must lower the delay for reasons such as client
2029 : : * timeouts, then you should choose the highest value practically possible to limit your risk.
2030 : : *
2031 : : * If you lower the blinding delay, you should also consider implementing monitoring and filtering
2032 : : * to detect and reject suspicious traffic that could be gathering timing information from a potential
2033 : : * side channel. Timing attacks usually involve repeatedly triggering TLS errors.
2034 : : *
2035 : : * @warning Do NOT set a lower blinding delay unless you understand the risks and have other
2036 : : * mitigations for timing side channels in place.
2037 : : *
2038 : : * @note This delay needs to be set lower than any timeouts, such as your TCP socket timeout.
2039 : : *
2040 : : * @param config The config object being updated.
2041 : : * @param seconds The maximum number of seconds that s2n-tls will delay for in the event of a
2042 : : * sensitive error.
2043 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
2044 : : */
2045 : : S2N_API extern int s2n_config_set_max_blinding_delay(struct s2n_config *config, uint32_t seconds);
2046 : :
2047 : : /**
2048 : : * Sets the cipher preference override for the s2n_connection. Calling this function is not necessary
2049 : : * unless you want to set the cipher preferences on the connection to something different than what is in the s2n_config.
2050 : : *
2051 : : * @param conn The connection object being updated
2052 : : * @param version The human readable string representation of the security policy version.
2053 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2054 : : */
2055 : : S2N_API extern int s2n_connection_set_cipher_preferences(struct s2n_connection *conn, const char *version);
2056 : :
2057 : : /**
2058 : : * Used to indicate the type of key update that is being requested. For further
2059 : : * information refer to `s2n_connection_request_key_update`.
2060 : : */
2061 : : typedef enum {
2062 : : S2N_KEY_UPDATE_NOT_REQUESTED = 0,
2063 : : S2N_KEY_UPDATE_REQUESTED
2064 : : } s2n_peer_key_update;
2065 : :
2066 : : /**
2067 : : * Signals the connection to do a key_update at the next possible opportunity. Note that the resulting key update message
2068 : : * will not be sent until `s2n_send` is called.
2069 : : *
2070 : : * @param conn The connection object to trigger the key update on.
2071 : : * @param peer_request Indicates if a key update should also be requested
2072 : : * of the peer. When set to `S2N_KEY_UPDATE_NOT_REQUESTED`, then only the sending
2073 : : * key of `conn` will be updated. If set to `S2N_KEY_UPDATE_REQUESTED`, then
2074 : : * the sending key of conn will be updated AND the peer will be requested to
2075 : : * update their sending key. Note that s2n-tls currently only supports
2076 : : * `peer_request` being set to `S2N_KEY_UPDATE_NOT_REQUESTED` and will return
2077 : : * S2N_FAILURE if any other value is used.
2078 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2079 : : */
2080 : : S2N_API extern int s2n_connection_request_key_update(struct s2n_connection *conn, s2n_peer_key_update peer_request);
2081 : : /**
2082 : : * Appends the provided application protocol to the preference list
2083 : : *
2084 : : * The data provided in `protocol` parameter will be copied into an internal buffer
2085 : : *
2086 : : * @param conn The connection object being updated
2087 : : * @param protocol A pointer to a slice of bytes
2088 : : * @param protocol_len The length of bytes that should be read from `protocol`. Note: this value cannot be 0, otherwise an error will be returned.
2089 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2090 : : */
2091 : : S2N_API extern int s2n_connection_append_protocol_preference(struct s2n_connection *conn, const uint8_t *protocol, uint8_t protocol_len);
2092 : :
2093 : : /**
2094 : : * Sets the protocol preference override for the s2n_connection. Calling this function is not necessary unless you want
2095 : : * to set the protocol preferences on the connection to something different than what is in the s2n_config.
2096 : : *
2097 : : * @param conn The connection object being updated
2098 : : * @param protocols A pointer to an array of protocol strings
2099 : : * @param protocol_count The number of protocols contained in protocols
2100 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2101 : : */
2102 : : S2N_API extern int s2n_connection_set_protocol_preferences(struct s2n_connection *conn, const char *const *protocols, int protocol_count);
2103 : :
2104 : : /**
2105 : : * Sets the server name for the connection.
2106 : : *
2107 : : * The provided server name will be sent by the client to the server in the
2108 : : * server_name ClientHello extension. It may be desirable for clients
2109 : : * to provide this information to facilitate secure connections to
2110 : : * servers that host multiple 'virtual' servers at a single underlying
2111 : : * network address.
2112 : : *
2113 : : * s2n-tls does not place any restrictions on the provided server name. However,
2114 : : * other TLS implementations might. Specifically, the TLS specification for the
2115 : : * server_name extension requires that it be an ASCII-encoded DNS name without a
2116 : : * trailing dot, and explicitly forbids literal IPv4 or IPv6 addresses.
2117 : : *
2118 : : * @param conn The connection object being queried
2119 : : * @param server_name A pointer to a string containing the desired server name
2120 : : * @warning `server_name` must be a NULL terminated string.
2121 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2122 : : */
2123 : : S2N_API extern int s2n_set_server_name(struct s2n_connection *conn, const char *server_name);
2124 : :
2125 : : /**
2126 : : * Query the connection for the selected server name.
2127 : : *
2128 : : * This can be used by a server to determine which server name the client is using. This function returns the first ServerName entry
2129 : : * in the ServerNameList sent by the client. Subsequent entries are not returned.
2130 : : *
2131 : : * @param conn The connection object being queried
2132 : : * @returns The server name associated with a connection, or NULL if none is found.
2133 : : */
2134 : : S2N_API extern const char *s2n_get_server_name(struct s2n_connection *conn);
2135 : :
2136 : : /**
2137 : : * Query the connection for the selected application protocol.
2138 : : *
2139 : : * @param conn The connection object being queried
2140 : : * @returns The negotiated application protocol for a `s2n_connection`. In the event of no protocol being negotiated, NULL is returned.
2141 : : */
2142 : : S2N_API extern const char *s2n_get_application_protocol(struct s2n_connection *conn);
2143 : :
2144 : : /**
2145 : : * Query the connection for a buffer containing the OCSP response.
2146 : : *
2147 : : * @param conn The connection object being queried
2148 : : * @param length A pointer that is set to the certificate transparency response buffer's size
2149 : : * @returns A pointer to the OCSP response sent by a server during the handshake. If no status response is received, NULL is returned.
2150 : : */
2151 : : S2N_API extern const uint8_t *s2n_connection_get_ocsp_response(struct s2n_connection *conn, uint32_t *length);
2152 : :
2153 : : /**
2154 : : * Query the connection for a buffer containing the Certificate Transparency response.
2155 : : *
2156 : : * @param conn The connection object being queried
2157 : : * @param length A pointer that is set to the certificate transparency response buffer's size
2158 : : * @returns A pointer to the certificate transparency response buffer.
2159 : : */
2160 : : S2N_API extern const uint8_t *s2n_connection_get_sct_list(struct s2n_connection *conn, uint32_t *length);
2161 : :
2162 : : /**
2163 : : * Used in non-blocking mode to indicate in which direction s2n-tls became blocked on I/O before it
2164 : : * returned control to the caller. This allows an application to avoid retrying s2n-tls operations
2165 : : * until I/O is possible in that direction.
2166 : : */
2167 : : typedef enum {
2168 : : S2N_NOT_BLOCKED = 0,
2169 : : S2N_BLOCKED_ON_READ,
2170 : : S2N_BLOCKED_ON_WRITE,
2171 : : S2N_BLOCKED_ON_APPLICATION_INPUT,
2172 : : S2N_BLOCKED_ON_EARLY_DATA,
2173 : : } s2n_blocked_status;
2174 : :
2175 : : /**
2176 : : * Performs the initial "handshake" phase of a TLS connection and must be called before any s2n_recv() or s2n_send() calls.
2177 : : *
2178 : : * @note When using client authentication with TLS1.3, s2n_negotiate() will report a successful
2179 : : * handshake to clients before the server validates the client certificate. If the server then
2180 : : * rejects the client certificate, the client may later receive an alert while calling s2n_recv,
2181 : : * potentially after already having sent application data with s2n_send.
2182 : : *
2183 : : * See the following example for guidance on calling `s2n_negotiate()`:
2184 : : * https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_negotiate.c
2185 : : *
2186 : : * @param conn A pointer to the s2n_connection object
2187 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2188 : : * @returns S2N_SUCCESS if the handshake completed. S2N_FAILURE if the handshake encountered an error or is blocked.
2189 : : */
2190 : : S2N_API extern int s2n_negotiate(struct s2n_connection *conn, s2n_blocked_status *blocked);
2191 : :
2192 : : /**
2193 : : * Writes and encrypts `size` of `buf` data to the associated connection. s2n_send() will return the number of bytes
2194 : : * written, and may indicate a partial write.
2195 : : *
2196 : : * @note Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active.
2197 : : * @note Unlike OpenSSL, repeated calls to s2n_send() should not duplicate the original parameters, but should
2198 : : * update `buf` and `size` per the indication of size written.
2199 : : *
2200 : : * See the following example for guidance on calling `s2n_send()`:
2201 : : * https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_send.c
2202 : : *
2203 : : * @param conn A pointer to the s2n_connection object
2204 : : * @param buf A pointer to a buffer that s2n will write data from
2205 : : * @param size The size of buf
2206 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2207 : : * @returns The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.
2208 : : */
2209 : : S2N_API extern ssize_t s2n_send(struct s2n_connection *conn, const void *buf, ssize_t size, s2n_blocked_status *blocked);
2210 : :
2211 : : /**
2212 : : * Works in the same way as s2n_sendv_with_offset() but with the `offs` parameter implicitly assumed to be 0.
2213 : : * Therefore in the partial write case, the caller would have to make sure that the `bufs` and `count` fields are modified in a way that takes
2214 : : * the partial writes into account.
2215 : : *
2216 : : * @param conn A pointer to the s2n_connection object
2217 : : * @param bufs A pointer to a vector of buffers that s2n will write data from.
2218 : : * @param count The number of buffers in `bufs`
2219 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2220 : : * @returns The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.
2221 : : */
2222 : : S2N_API extern ssize_t s2n_sendv(struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, s2n_blocked_status *blocked);
2223 : :
2224 : : /**
2225 : : * Works in the same way as s2n_send() except that it accepts vectorized buffers. Will return the number of bytes written, and may indicate a partial write. Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active.
2226 : : *
2227 : : * @note Partial writes are possible not just for non-blocking I/O, but also for connections aborted while active.
2228 : : *
2229 : : * @note Unlike OpenSSL, repeated calls to s2n_sendv_with_offset() should not duplicate the original parameters, but should update `bufs` and `count` per the indication of size written.
2230 : : *
2231 : : * See the following example for guidance on calling `s2n_sendv_with_offset()`:
2232 : : * https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_send.c
2233 : : *
2234 : : * @param conn A pointer to the s2n_connection object
2235 : : * @param bufs A pointer to a vector of buffers that s2n will write data from.
2236 : : * @param count The number of buffers in `bufs`
2237 : : * @param offs The write cursor offset. This should be updated as data is written. See the example code.
2238 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2239 : : * @returns The number of bytes written on success, which may indicate a partial write. S2N_FAILURE on failure.
2240 : : */
2241 : : S2N_API extern ssize_t s2n_sendv_with_offset(struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, ssize_t offs, s2n_blocked_status *blocked);
2242 : :
2243 : : /**
2244 : : * Decrypts and reads **size* to `buf` data from the associated
2245 : : * connection.
2246 : : *
2247 : : * @note Unlike OpenSSL, repeated calls to `s2n_recv` should not duplicate the original parameters, but should update `buf` and `size` per the indication of size read.
2248 : : *
2249 : : * See the following example for guidance on calling `s2n_recv()`:
2250 : : * https://github.com/aws/s2n-tls/blob/main/docs/examples/s2n_recv.c
2251 : : *
2252 : : * @param conn A pointer to the s2n_connection object
2253 : : * @param buf A pointer to a buffer that s2n will place read data into.
2254 : : * @param size Size of `buf`
2255 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2256 : : * @returns The number of bytes read on success. 0 if the connection was shutdown by the peer. S2N_FAILURE on failure.
2257 : : */
2258 : : S2N_API extern ssize_t s2n_recv(struct s2n_connection *conn, void *buf, ssize_t size, s2n_blocked_status *blocked);
2259 : :
2260 : : /**
2261 : : * Allows users of s2n-tls to peek inside the data buffer of an s2n-tls connection to see if there more data to be read without actually reading it.
2262 : : *
2263 : : * This is useful when using select() on the underlying s2n-tls file descriptor with a message based application layer protocol. As a single call
2264 : : * to s2n_recv may read all data off the underlying file descriptor, select() will be unable to tell you there if there is more application data
2265 : : * ready for processing already loaded into the s2n-tls buffer.
2266 : : *
2267 : : * @note can then be used to determine if s2n_recv() needs to be called before more data comes in on the raw fd
2268 : : * @param conn A pointer to the s2n_connection object
2269 : : * @returns The number of bytes that can be read from the connection
2270 : : */
2271 : : S2N_API extern uint32_t s2n_peek(struct s2n_connection *conn);
2272 : :
2273 : : /**
2274 : : * Wipes and releases buffers and memory allocated during the TLS handshake.
2275 : : *
2276 : : * @note This function should be called after the handshake is successfully negotiated and logging or recording of handshake data is complete.
2277 : : *
2278 : : * @param conn A pointer to the s2n_connection object
2279 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2280 : : */
2281 : : S2N_API extern int s2n_connection_free_handshake(struct s2n_connection *conn);
2282 : :
2283 : : /**
2284 : : * Wipes and free the `in` and `out` buffers associated with a connection.
2285 : : *
2286 : : * @note This function may be called when a connection is
2287 : : * in keep-alive or idle state to reduce memory overhead of long lived connections.
2288 : : *
2289 : : * @param conn A pointer to the s2n_connection object
2290 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2291 : : */
2292 : : S2N_API extern int s2n_connection_release_buffers(struct s2n_connection *conn);
2293 : :
2294 : : /**
2295 : : * Wipes an existing connection and allows it to be reused. Erases all data associated with a connection including
2296 : : * pending reads.
2297 : : *
2298 : : * @note This function should be called after all I/O is completed and s2n_shutdown has been called.
2299 : : * @note Reusing the same connection handle(s) is more performant than repeatedly calling s2n_connection_new() and s2n_connection_free().
2300 : : *
2301 : : * @param conn A pointer to the s2n_connection object
2302 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2303 : : */
2304 : : S2N_API extern int s2n_connection_wipe(struct s2n_connection *conn);
2305 : :
2306 : : /**
2307 : : * Frees the memory associated with an s2n_connection
2308 : : * handle. The handle is considered invalid after `s2n_connection_free` is used.
2309 : : * s2n_connection_wipe() does not need to be called prior to this function. `s2n_connection_free` performs its own wipe
2310 : : * of sensitive data.
2311 : : *
2312 : : * @param conn A pointer to the s2n_connection object
2313 : : * @returns 0 on success. -1 on failure
2314 : : */
2315 : : S2N_API extern int s2n_connection_free(struct s2n_connection *conn);
2316 : :
2317 : : /**
2318 : : * Attempts a closure at the TLS layer. Does not close the underlying transport. This call may block in either direction.
2319 : : *
2320 : : * Unlike other TLS implementations, `s2n_shutdown` attempts a graceful shutdown by default. It will not return with success unless a close_notify alert is successfully
2321 : : * sent and received. As a result, `s2n_shutdown` may fail when interacting with a non-conformant TLS implementation.
2322 : : *
2323 : : * Once `s2n_shutdown` is complete:
2324 : : * * The s2n_connection handle cannot be used for reading for writing.
2325 : : * * The underlying transport can be closed. Most likely via `shutdown()` or `close()`.
2326 : : * * The s2n_connection handle can be freed via s2n_connection_free() or reused via s2n_connection_wipe()
2327 : : *
2328 : : * @param conn A pointer to the s2n_connection object
2329 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2330 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2331 : : */
2332 : : S2N_API extern int s2n_shutdown(struct s2n_connection *conn, s2n_blocked_status *blocked);
2333 : :
2334 : : /**
2335 : : * Attempts to close the write side of the TLS connection.
2336 : : *
2337 : : * TLS1.3 supports closing the write side of a TLS connection while leaving the read
2338 : : * side unaffected. This feature is usually referred to as "half-close". We send
2339 : : * a close_notify alert, but do not wait for the peer to respond.
2340 : : *
2341 : : * Like `s2n_shutdown()`, this method does not affect the underlying transport.
2342 : : *
2343 : : * `s2n_shutdown_send()` may still be called for earlier TLS versions, but most
2344 : : * TLS implementations will react by immediately discarding any pending writes and
2345 : : * closing the connection.
2346 : : *
2347 : : * Once `s2n_shutdown_send()` is complete:
2348 : : * * The s2n_connection handle CANNOT be used for writing.
2349 : : * * The s2n_connection handle CAN be used for reading.
2350 : : * * The write side of the underlying transport can be closed. Most likely via `shutdown()`.
2351 : : *
2352 : : * The application should still call `s2n_shutdown()` or wait for `s2n_recv()` to
2353 : : * return 0 to indicate end-of-data before cleaning up the connection or closing
2354 : : * the read side of the underlying transport.
2355 : : *
2356 : : * @param conn A pointer to the s2n_connection object
2357 : : * @param blocked A pointer which will be set to the blocked status if an `S2N_ERR_T_BLOCKED` error is returned.
2358 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2359 : : */
2360 : : S2N_API extern int s2n_shutdown_send(struct s2n_connection *conn, s2n_blocked_status *blocked);
2361 : :
2362 : : /**
2363 : : * Used to declare what type of client certificate authentication to use.
2364 : : *
2365 : : * A s2n_connection will enforce client certificate authentication (mTLS) differently based on
2366 : : * the `s2n_cert_auth_type` and `s2n_mode` (client/server) of the connection, as described below.
2367 : : *
2368 : : * Server behavior:
2369 : : * - None (default): Will not request client authentication.
2370 : : * - Optional: Request the client's certificate and validate it. If no certificate is received then
2371 : : * no validation is performed.
2372 : : * - Required: Request the client's certificate and validate it. Abort the handshake if a client
2373 : : * certificate is not received.
2374 : : *
2375 : : * Client behavior:
2376 : : * - None: Abort the handshake if the server requests client authentication.
2377 : : * - Optional (default): Sends the client certificate if the server requests client
2378 : : * authentication. No certificate is sent if the application hasn't provided a certificate.
2379 : : * - Required: Send the client certificate. Abort the handshake if the server doesn't request
2380 : : * client authentication or if the application hasn't provided a certificate.
2381 : : */
2382 : : typedef enum {
2383 : : S2N_CERT_AUTH_NONE,
2384 : : S2N_CERT_AUTH_REQUIRED,
2385 : : S2N_CERT_AUTH_OPTIONAL
2386 : : } s2n_cert_auth_type;
2387 : :
2388 : : /**
2389 : : * Gets Client Certificate authentication method the s2n_config object is using.
2390 : : *
2391 : : * @param config A pointer to a s2n_config object
2392 : : * @param client_auth_type A pointer to a client auth policy. This will be updated to the s2n_config value.
2393 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2394 : : */
2395 : : S2N_API extern int s2n_config_get_client_auth_type(struct s2n_config *config, s2n_cert_auth_type *client_auth_type);
2396 : :
2397 : : /**
2398 : : * Sets whether or not a Client Certificate should be required to complete the TLS Connection.
2399 : : *
2400 : : * If this is set to `S2N_CERT_AUTH_OPTIONAL` the server will request a client certificate but allow the client to not provide one.
2401 : : * Rejecting a client certificate when using `S2N_CERT_AUTH_OPTIONAL` will terminate the handshake.
2402 : : *
2403 : : * @param config A pointer to a s2n_config object
2404 : : * @param client_auth_type The client auth policy for the connection
2405 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2406 : : */
2407 : : S2N_API extern int s2n_config_set_client_auth_type(struct s2n_config *config, s2n_cert_auth_type client_auth_type);
2408 : :
2409 : : /**
2410 : : * Gets Client Certificate authentication method the s2n_connection object is using.
2411 : : *
2412 : : * @param conn A pointer to the s2n_connection object
2413 : : * @param client_auth_type A pointer to a client auth policy. This will be updated to the s2n_connection value.
2414 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2415 : : */
2416 : : S2N_API extern int s2n_connection_get_client_auth_type(struct s2n_connection *conn, s2n_cert_auth_type *client_auth_type);
2417 : :
2418 : : /**
2419 : : * Sets whether or not a Client Certificate should be required to complete the TLS Connection.
2420 : : *
2421 : : * If this is set to `S2N_CERT_AUTH_OPTIONAL` the server will request a client certificate but allow the client to not provide one.
2422 : : * Rejecting a client certificate when using `S2N_CERT_AUTH_OPTIONAL` will terminate the handshake.
2423 : : *
2424 : : * @param conn A pointer to the s2n_connection object
2425 : : * @param client_auth_type The client auth policy for the connection
2426 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2427 : : */
2428 : : S2N_API extern int s2n_connection_set_client_auth_type(struct s2n_connection *conn, s2n_cert_auth_type client_auth_type);
2429 : :
2430 : : /**
2431 : : * Gets the raw certificate chain received from the client.
2432 : : *
2433 : : * The retrieved certificate chain has the format described by the TLS 1.2 RFC:
2434 : : * https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.2. Each certificate is a DER-encoded ASN.1 X.509,
2435 : : * prepended by a 3 byte network-endian length value. Note that this format is used regardless of the connection's
2436 : : * protocol version.
2437 : : *
2438 : : * @warning The buffer pointed to by `cert_chain_out` shares its lifetime with the s2n_connection object.
2439 : : *
2440 : : * @param conn A pointer to the s2n_connection object
2441 : : * @param cert_chain_out A pointer that's set to the client certificate chain.
2442 : : * @param cert_chain_len A pointer that's set to the size of the `cert_chain_out` buffer.
2443 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2444 : : */
2445 : : S2N_API extern int s2n_connection_get_client_cert_chain(struct s2n_connection *conn, uint8_t **der_cert_chain_out, uint32_t *cert_chain_len);
2446 : :
2447 : : /**
2448 : : * Sets the initial number of session tickets to send after a >=TLS1.3 handshake. The default value is one ticket.
2449 : : *
2450 : : * @param config A pointer to the config object.
2451 : : * @param num The number of session tickets that will be sent.
2452 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2453 : : */
2454 : : S2N_API extern int s2n_config_set_initial_ticket_count(struct s2n_config *config, uint8_t num);
2455 : :
2456 : : /**
2457 : : * Increases the number of session tickets to send after a >=TLS1.3 handshake.
2458 : : *
2459 : : * @param conn A pointer to the connection object.
2460 : : * @param num The number of additional session tickets to send.
2461 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2462 : : */
2463 : : S2N_API extern int s2n_connection_add_new_tickets_to_send(struct s2n_connection *conn, uint8_t num);
2464 : :
2465 : : /**
2466 : : * Returns the number of session tickets issued by the server.
2467 : : *
2468 : : * In TLS1.3, this number can be up to the limit configured by s2n_config_set_initial_ticket_count
2469 : : * and s2n_connection_add_new_tickets_to_send. In earlier versions of TLS, this number will be either 0 or 1.
2470 : : *
2471 : : * This method only works for server connections.
2472 : : *
2473 : : * @param conn A pointer to the connection object.
2474 : : * @param num The number of additional session tickets sent.
2475 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2476 : : */
2477 : : S2N_API extern int s2n_connection_get_tickets_sent(struct s2n_connection *conn, uint16_t *num);
2478 : :
2479 : : /**
2480 : : * Sets the keying material lifetime for >=TLS1.3 session tickets so that one session doesn't get re-used ad infinitum.
2481 : : * The default value is one week.
2482 : : *
2483 : : * @param conn A pointer to the connection object.
2484 : : * @param lifetime_in_secs Lifetime of keying material in seconds.
2485 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
2486 : : */
2487 : : S2N_API extern int s2n_connection_set_server_keying_material_lifetime(struct s2n_connection *conn, uint32_t lifetime_in_secs);
2488 : :
2489 : : struct s2n_session_ticket;
2490 : :
2491 : : /**
2492 : : * Callback function for receiving a session ticket.
2493 : : *
2494 : : * This function will be called each time a session ticket is received, which may be multiple times for TLS1.3.
2495 : : *
2496 : : * # Safety
2497 : : *
2498 : : * `ctx` is a void pointer and the caller is responsible for ensuring it is cast to the correct type.
2499 : : * `ticket` is valid only within the scope of this callback.
2500 : : *
2501 : : * @param conn A pointer to the connection object.
2502 : : * @param ctx Context for the session ticket callback function.
2503 : : * @param ticket Pointer to the received session ticket object.
2504 : : */
2505 : : typedef int (*s2n_session_ticket_fn)(struct s2n_connection *conn, void *ctx, struct s2n_session_ticket *ticket);
2506 : :
2507 : : /**
2508 : : * Sets a session ticket callback to be called when a client receives a new session ticket.
2509 : : *
2510 : : * # Safety
2511 : : *
2512 : : * `callback` MUST cast `ctx` into the same type of pointer that was originally created.
2513 : : * `ctx` MUST be valid for the lifetime of the config, or until a different context is set.
2514 : : *
2515 : : * @param config A pointer to the config object.
2516 : : * @param callback The function that should be called when the callback is triggered.
2517 : : * @param ctx The context to be passed when the callback is called.
2518 : : */
2519 : : S2N_API extern int s2n_config_set_session_ticket_cb(struct s2n_config *config, s2n_session_ticket_fn callback, void *ctx);
2520 : :
2521 : : /**
2522 : : * Gets the length of the session ticket from a session ticket object.
2523 : : *
2524 : : * @param ticket Pointer to the session ticket object.
2525 : : * @param data_len Pointer to be set to the length of the session ticket on success.
2526 : : */
2527 : : S2N_API extern int s2n_session_ticket_get_data_len(struct s2n_session_ticket *ticket, size_t *data_len);
2528 : :
2529 : : /**
2530 : : * Gets the session ticket data from a session ticket object.
2531 : : *
2532 : : * # Safety
2533 : : * The entire session ticket will be copied into `data` on success. Therefore, `data` MUST have enough
2534 : : * memory to store the session ticket data.
2535 : : *
2536 : : * @param ticket Pointer to the session ticket object.
2537 : : * @param max_data_len Maximum length of data that can be written to the 'data' pointer.
2538 : : * @param data Pointer to where the session ticket data will be stored.
2539 : : */
2540 : : S2N_API extern int s2n_session_ticket_get_data(struct s2n_session_ticket *ticket, size_t max_data_len, uint8_t *data);
2541 : :
2542 : : /**
2543 : : * Gets the lifetime in seconds of the session ticket from a session ticket object.
2544 : : *
2545 : : * @param ticket Pointer to the session ticket object.
2546 : : * @param session_lifetime Pointer to a variable where the lifetime of the session ticket will be stored.
2547 : : */
2548 : : S2N_API extern int s2n_session_ticket_get_lifetime(struct s2n_session_ticket *ticket, uint32_t *session_lifetime);
2549 : :
2550 : : /**
2551 : : * De-serializes the session state and updates the connection accordingly.
2552 : : *
2553 : : * If this method fails, the connection should not be affected: calling s2n_negotiate
2554 : : * with the connection should simply result in a full handshake.
2555 : : *
2556 : : * @param conn A pointer to the s2n_connection object
2557 : : * @param session A pointer to a buffer of size `length`
2558 : : * @param length The size of the `session` buffer
2559 : : *
2560 : : * @returns The number of copied bytes
2561 : : */
2562 : : S2N_API extern int s2n_connection_set_session(struct s2n_connection *conn, const uint8_t *session, size_t length);
2563 : :
2564 : : /**
2565 : : * Serializes the session state from connection and copies into the `session` buffer and returns the number of copied bytes
2566 : : *
2567 : : * @note This function is not recommended for > TLS 1.2 because in TLS1.3
2568 : : * servers can send multiple session tickets and this function will only
2569 : : * return the most recently received ticket.
2570 : : *
2571 : : * @param conn A pointer to the s2n_connection object
2572 : : * @param session A pointer to a buffer of size `max_length`
2573 : : * @param max_length The size of the `session` buffer
2574 : : *
2575 : : * @returns The number of copied bytes
2576 : : */
2577 : : S2N_API extern int s2n_connection_get_session(struct s2n_connection *conn, uint8_t *session, size_t max_length);
2578 : :
2579 : : /**
2580 : : * Retrieves a hint from the server indicating how long this ticket's lifetime is.
2581 : : *
2582 : : * @note This function is not recommended for > TLS 1.2 because in TLS1.3
2583 : : * servers can send multiple session tickets and this function will only
2584 : : * return the most recently received ticket lifetime hint.
2585 : : *
2586 : : * @param conn A pointer to the s2n_connection object
2587 : : *
2588 : : * @returns The session ticket lifetime hint in seconds from the server or -1 when session ticket was not used for resumption.
2589 : : */
2590 : : S2N_API extern int s2n_connection_get_session_ticket_lifetime_hint(struct s2n_connection *conn);
2591 : :
2592 : : /**
2593 : : * Use this to query the serialized session state size before copying it into a buffer.
2594 : : *
2595 : : * @param conn A pointer to the s2n_connection object
2596 : : *
2597 : : * @returns number of bytes needed to store serialized session state
2598 : : */
2599 : : S2N_API extern int s2n_connection_get_session_length(struct s2n_connection *conn);
2600 : :
2601 : : /**
2602 : : * Gets the latest session id's length from the connection.
2603 : : *
2604 : : * Use this to query the session id size before copying it into a buffer.
2605 : : *
2606 : : * @param conn A pointer to the s2n_connection object
2607 : : *
2608 : : * @returns The latest session id length from the connection. Session id length will be 0 for TLS versions >= TLS1.3 as stateful session resumption has not yet been implemented in TLS1.3.
2609 : : */
2610 : : S2N_API extern int s2n_connection_get_session_id_length(struct s2n_connection *conn);
2611 : :
2612 : : /**
2613 : : * Gets the latest session id from the connection, copies it into the `session_id` buffer, and returns the number of copied bytes.
2614 : : *
2615 : : * The session id may change between s2n receiving the ClientHello and sending the ServerHello, but this function will always describe the latest session id.
2616 : : *
2617 : : * See s2n_client_hello_get_session_id() to get the session id as it was sent by the client in the ClientHello message.
2618 : : *
2619 : : * @param conn A pointer to the s2n_connection object
2620 : : * @param session_id A pointer to a buffer of size `max_length`
2621 : : * @param max_length The size of the `session_id` buffer
2622 : : *
2623 : : * @returns The number of copied bytes.
2624 : : */
2625 : : S2N_API extern int s2n_connection_get_session_id(struct s2n_connection *conn, uint8_t *session_id, size_t max_length);
2626 : :
2627 : : /**
2628 : : * Check if the connection was resumed from an earlier handshake.
2629 : : *
2630 : : * @param conn A pointer to the s2n_connection object
2631 : : *
2632 : : * @returns returns 1 if the handshake was abbreviated, otherwise returns 0
2633 : : */
2634 : : S2N_API extern int s2n_connection_is_session_resumed(struct s2n_connection *conn);
2635 : :
2636 : : /**
2637 : : * Check if the connection is OCSP stapled.
2638 : : *
2639 : : * @param conn A pointer to the s2n_connection object
2640 : : *
2641 : : * @returns 1 if OCSP response was sent (if connection is in S2N_SERVER mode) or received (if connection is in S2N_CLIENT mode) during handshake, otherwise it returns 0.
2642 : : */
2643 : : S2N_API extern int s2n_connection_is_ocsp_stapled(struct s2n_connection *conn);
2644 : :
2645 : : /**
2646 : : * TLS Signature Algorithms - RFC 5246 7.4.1.4.1
2647 : : * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16
2648 : : */
2649 : : typedef enum {
2650 : : S2N_TLS_SIGNATURE_ANONYMOUS = 0,
2651 : : S2N_TLS_SIGNATURE_RSA = 1,
2652 : : S2N_TLS_SIGNATURE_ECDSA = 3,
2653 : : S2N_TLS_SIGNATURE_MLDSA = 9,
2654 : :
2655 : : /* Use Private Range for RSA PSS since it's not defined there */
2656 : : S2N_TLS_SIGNATURE_RSA_PSS_RSAE = 224,
2657 : : S2N_TLS_SIGNATURE_RSA_PSS_PSS
2658 : : } s2n_tls_signature_algorithm;
2659 : :
2660 : : /** TLS Hash Algorithms - https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1
2661 : : * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18
2662 : : */
2663 : : typedef enum {
2664 : : S2N_TLS_HASH_NONE = 0,
2665 : : S2N_TLS_HASH_MD5 = 1,
2666 : : S2N_TLS_HASH_SHA1 = 2,
2667 : : S2N_TLS_HASH_SHA224 = 3,
2668 : : S2N_TLS_HASH_SHA256 = 4,
2669 : : S2N_TLS_HASH_SHA384 = 5,
2670 : : S2N_TLS_HASH_SHA512 = 6,
2671 : :
2672 : : /* Use Private Range for MD5_SHA1 */
2673 : : S2N_TLS_HASH_MD5_SHA1 = 224
2674 : : } s2n_tls_hash_algorithm;
2675 : :
2676 : : /**
2677 : : * Get the connection's selected signature algorithm.
2678 : : *
2679 : : * @param conn A pointer to the s2n_connection object
2680 : : * @param chosen_alg A pointer to a s2n_tls_signature_algorithm object. This is an output parameter.
2681 : : *
2682 : : * @returns S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.
2683 : : */
2684 : : S2N_API extern int s2n_connection_get_selected_signature_algorithm(struct s2n_connection *conn, s2n_tls_signature_algorithm *chosen_alg);
2685 : :
2686 : : /**
2687 : : * Get the connection's selected digest algorithm.
2688 : : *
2689 : : * @param conn A pointer to the s2n_connection object
2690 : : * @param chosen_alg A pointer to a s2n_tls_hash_algorithm object. This is an output parameter.
2691 : : *
2692 : : * @returns S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.
2693 : : */
2694 : : S2N_API extern int s2n_connection_get_selected_digest_algorithm(struct s2n_connection *conn, s2n_tls_hash_algorithm *chosen_alg);
2695 : :
2696 : : /**
2697 : : * Get the client certificate's signature algorithm.
2698 : : *
2699 : : * @param conn A pointer to the s2n_connection object
2700 : : * @param chosen_alg A pointer to a s2n_tls_signature_algorithm object. This is an output parameter.
2701 : : *
2702 : : * @returns S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.
2703 : : */
2704 : : S2N_API extern int s2n_connection_get_selected_client_cert_signature_algorithm(struct s2n_connection *conn, s2n_tls_signature_algorithm *chosen_alg);
2705 : :
2706 : : /**
2707 : : * Get the client certificate's digest algorithm.
2708 : : *
2709 : : * @param conn A pointer to the s2n_connection object
2710 : : * @param chosen_alg A pointer to a s2n_tls_hash_algorithm object. This is an output parameter.
2711 : : *
2712 : : * @returns S2N_SUCCESS on success. S2N_FAILURE if bad parameters are received.
2713 : : */
2714 : : S2N_API extern int s2n_connection_get_selected_client_cert_digest_algorithm(struct s2n_connection *conn, s2n_tls_hash_algorithm *chosen_alg);
2715 : :
2716 : : /**
2717 : : * Get the certificate used during the TLS handshake
2718 : : *
2719 : : * - If `conn` is a server connection, the certificate selected will depend on the
2720 : : * ServerName sent by the client and supported ciphers.
2721 : : * - If `conn` is a client connection, the certificate sent in response to a CertificateRequest
2722 : : * message is returned. Currently s2n-tls supports loading only one certificate in client mode. Note that
2723 : : * not all TLS endpoints will request a certificate.
2724 : : *
2725 : : * @param conn A pointer to the s2n_connection object
2726 : : *
2727 : : * @returns NULL if the certificate selection phase of the handshake has not completed or if a certificate was not requested by the peer
2728 : : */
2729 : : S2N_API extern struct s2n_cert_chain_and_key *s2n_connection_get_selected_cert(struct s2n_connection *conn);
2730 : :
2731 : : /**
2732 : : * @param chain_and_key A pointer to the s2n_cert_chain_and_key object being read.
2733 : : * @param cert_length This return value represents the length of the s2n certificate chain `chain_and_key`.
2734 : : * @returns the length of the s2n certificate chain `chain_and_key`.
2735 : : */
2736 : : S2N_API extern int s2n_cert_chain_get_length(const struct s2n_cert_chain_and_key *chain_and_key, uint32_t *cert_length);
2737 : :
2738 : : /**
2739 : : * Returns the certificate `out_cert` present at the index `cert_idx` of the certificate chain `chain_and_key`.
2740 : : *
2741 : : * Note that the index of the leaf certificate is zero. If the certificate chain `chain_and_key` is NULL or the
2742 : : * certificate index value is not in the acceptable range for the input certificate chain, an error is returned.
2743 : : *
2744 : : * # Safety
2745 : : *
2746 : : * There is no memory allocation required for `out_cert` buffer prior to calling the `s2n_cert_chain_get_cert` API.
2747 : : * The `out_cert` will contain the pointer to the s2n_cert initialized within the input s2n_cert_chain_and_key `chain_and_key`.
2748 : : * The pointer to the output s2n certificate `out_cert` is valid until `chain_and_key` is freed up.
2749 : : * If a caller wishes to persist the `out_cert` beyond the lifetime of `chain_and_key`, the contents would need to be
2750 : : * copied prior to freeing `chain_and_key`.
2751 : : *
2752 : : * @param chain_and_key A pointer to the s2n_cert_chain_and_key object being read.
2753 : : * @param out_cert A pointer to the output s2n_cert `out_cert` present at the index `cert_idx` of the certificate chain `chain_and_key`.
2754 : : * @param cert_idx The certificate index for the requested certificate within the s2n certificate chain.
2755 : : */
2756 : : S2N_API extern int s2n_cert_chain_get_cert(const struct s2n_cert_chain_and_key *chain_and_key, struct s2n_cert **out_cert, const uint32_t cert_idx);
2757 : :
2758 : : /**
2759 : : * Returns the s2n certificate in DER format along with its length.
2760 : : *
2761 : : * The API gets the s2n certificate `cert` in DER format. The certificate is returned in the `out_cert_der` buffer.
2762 : : * Here, `cert_len` represents the length of the certificate.
2763 : : *
2764 : : * A caller can use certificate parsing tools such as the ones provided by OpenSSL to parse the DER encoded certificate chain returned.
2765 : : *
2766 : : * # Safety
2767 : : *
2768 : : * The memory for the `out_cert_der` buffer is allocated and owned by s2n-tls.
2769 : : * Since the size of the certificate can potentially be very large, a pointer to internal connection data is returned instead of
2770 : : * copying the contents into a caller-provided buffer.
2771 : : *
2772 : : * The pointer to the output buffer `out_cert_der` is valid only while the connection exists.
2773 : : * The `s2n_connection_free` API frees the memory associated with the out_cert_der buffer and after the `s2n_connection_wipe` API is
2774 : : * called the memory pointed by out_cert_der is invalid.
2775 : : *
2776 : : * If a caller wishes to persist the `out_cert_der` beyond the lifetime of the connection, the contents would need to be
2777 : : * copied prior to the connection termination.
2778 : : *
2779 : : * @param cert A pointer to the s2n_cert object being read.
2780 : : * @param out_cert_der A pointer to the output buffer which will hold the s2n certificate `cert` in DER format.
2781 : : * @param cert_length This return value represents the length of the certificate.
2782 : : */
2783 : : S2N_API extern int s2n_cert_get_der(const struct s2n_cert *cert, const uint8_t **out_cert_der, uint32_t *cert_length);
2784 : :
2785 : : /**
2786 : : * Returns the validated peer certificate chain as a `s2n_cert_chain_and_key` opaque object.
2787 : : *
2788 : : * The `s2n_cert_chain_and_key` parameter must be allocated by the caller using the `s2n_cert_chain_and_key_new` API
2789 : : * prior to this function call and must be empty. To free the memory associated with the `s2n_cert_chain_and_key` object use the
2790 : : * `s2n_cert_chain_and_key_free` API.
2791 : : *
2792 : : * @param conn A pointer to the s2n_connection object being read.
2793 : : * @param cert_chain The returned validated peer certificate chain `cert_chain` retrieved from the s2n connection.
2794 : : */
2795 : : S2N_API extern int s2n_connection_get_peer_cert_chain(const struct s2n_connection *conn, struct s2n_cert_chain_and_key *cert_chain);
2796 : :
2797 : : /**
2798 : : * Returns the length of the DER encoded extension value of the ASN.1 X.509 certificate extension.
2799 : : *
2800 : : * @param cert A pointer to the s2n_cert object being read.
2801 : : * @param oid A null-terminated cstring that contains the OID of the X.509 certificate extension to be read.
2802 : : * @param ext_value_len This return value contains the length of DER encoded extension value of the ASN.1 X.509 certificate extension.
2803 : : */
2804 : : S2N_API extern int s2n_cert_get_x509_extension_value_length(struct s2n_cert *cert, const uint8_t *oid, uint32_t *ext_value_len);
2805 : :
2806 : : /**
2807 : : * Returns the DER encoding of an ASN.1 X.509 certificate extension value, it's length and a boolean critical.
2808 : : *
2809 : : * @param cert A pointer to the s2n_cert object being read.
2810 : : * @param oid A null-terminated cstring that contains the OID of the X.509 certificate extension to be read.
2811 : : * @param ext_value A pointer to the output buffer which will hold the DER encoding of an ASN.1 X.509 certificate extension value returned.
2812 : : * @param ext_value_len This value is both an input and output parameter and represents the length of the output buffer `ext_value`.
2813 : : * When used as an input parameter, the caller must use this parameter to convey the maximum length of `ext_value`.
2814 : : * When used as an output parameter, `ext_value_len` holds the actual length of the DER encoding of the ASN.1 X.509 certificate extension value returned.
2815 : : * @param critical This return value contains the boolean value for `critical`.
2816 : : */
2817 : : S2N_API extern int s2n_cert_get_x509_extension_value(struct s2n_cert *cert, const uint8_t *oid, uint8_t *ext_value, uint32_t *ext_value_len, bool *critical);
2818 : :
2819 : : /**
2820 : : * Returns the UTF8 String length of the ASN.1 X.509 certificate extension data.
2821 : : *
2822 : : * @param extension_data A pointer to the DER encoded ASN.1 X.509 certificate extension value being read.
2823 : : * @param extension_len represents the length of the input buffer `extension_data`.
2824 : : * @param utf8_str_len This return value contains the UTF8 String length of the ASN.1 X.509 certificate extension data.
2825 : : */
2826 : : S2N_API extern int s2n_cert_get_utf8_string_from_extension_data_length(const uint8_t *extension_data, uint32_t extension_len, uint32_t *utf8_str_len);
2827 : :
2828 : : /**
2829 : : * Returns the UTF8 String representation of the DER encoded ASN.1 X.509 certificate extension data.
2830 : : *
2831 : : * @param extension_data A pointer to the DER encoded ASN.1 X.509 certificate extension value being read.
2832 : : * @param extension_len represents the length of the input buffer `extension_data`.
2833 : : * @param out_data A pointer to the output buffer which will hold the UTF8 String representation of the DER encoded ASN.1 X.509
2834 : : * certificate extension data returned.
2835 : : * @param out_len This value is both an input and output parameter and represents the length of the output buffer `out_data`.
2836 : : * When used as an input parameter, the caller must use this parameter to convey the maximum length of `out_data`.
2837 : : * When used as an output parameter, `out_len` holds the actual length of UTF8 String returned.
2838 : : */
2839 : : S2N_API extern int s2n_cert_get_utf8_string_from_extension_data(const uint8_t *extension_data, uint32_t extension_len, uint8_t *out_data, uint32_t *out_len);
2840 : :
2841 : : /**
2842 : : * Pre-shared key (PSK) Hash Algorithm - RFC 8446 Section-2.2
2843 : : */
2844 : : typedef enum {
2845 : : S2N_PSK_HMAC_SHA256,
2846 : : S2N_PSK_HMAC_SHA384,
2847 : : } s2n_psk_hmac;
2848 : :
2849 : : /**
2850 : : * Opaque pre shared key handle
2851 : : */
2852 : : struct s2n_psk;
2853 : :
2854 : : /**
2855 : : * Creates a new s2n external pre-shared key (PSK) object with `S2N_PSK_HMAC_SHA256` as the default
2856 : : * PSK hash algorithm. An external PSK is a key established outside of TLS using a secure mutually agreed upon mechanism.
2857 : : *
2858 : : * Use `s2n_psk_free` to free the memory allocated to the s2n external PSK object created by this API.
2859 : : *
2860 : : * @returns struct s2n_psk* Returns a pointer to the newly created external PSK object.
2861 : : */
2862 : : S2N_API struct s2n_psk *s2n_external_psk_new(void);
2863 : :
2864 : : /**
2865 : : * Frees the memory associated with the external PSK object.
2866 : : *
2867 : : * @param psk Pointer to the PSK object to be freed.
2868 : : */
2869 : : S2N_API int s2n_psk_free(struct s2n_psk **psk);
2870 : :
2871 : : /**
2872 : : * Sets the identity for a given external PSK object.
2873 : : * The identity is a unique identifier for the pre-shared secret.
2874 : : * It is a non-secret value represented by raw bytes.
2875 : : *
2876 : : * # Safety
2877 : : *
2878 : : * The identity is transmitted over the network unencrypted and is a non-secret value.
2879 : : * Do not include confidential information in the identity.
2880 : : *
2881 : : * Note that the identity is copied into s2n-tls memory and the caller is responsible for
2882 : : * freeing the memory associated with the identity input.
2883 : : *
2884 : : * @param psk A pointer to a PSK object to be updated with the identity.
2885 : : * @param identity The identity in raw bytes format to be copied.
2886 : : * @param identity_size The length of the PSK identity being set.
2887 : : */
2888 : : S2N_API int s2n_psk_set_identity(struct s2n_psk *psk, const uint8_t *identity, uint16_t identity_size);
2889 : :
2890 : : /**
2891 : : * Sets the out-of-band/externally provisioned secret for a given external PSK object.
2892 : : *
2893 : : * # Safety
2894 : : *
2895 : : * Note that the secret is copied into s2n-tls memory and the caller is responsible for
2896 : : * freeing the memory associated with the `secret` input.
2897 : : *
2898 : : * Deriving a shared secret from a password or other low-entropy source
2899 : : * is not secure and is subject to dictionary attacks.
2900 : : * See https://tools.ietf.org/rfc/rfc8446#section-2.2 for more information.
2901 : : *
2902 : : * @param psk A pointer to a PSK object to be updated with the secret.
2903 : : * @param secret The secret in raw bytes format to be copied.
2904 : : * @param secret_size The length of the pre-shared secret being set.
2905 : : */
2906 : : S2N_API int s2n_psk_set_secret(struct s2n_psk *psk, const uint8_t *secret, uint16_t secret_size);
2907 : :
2908 : : /**
2909 : : * Sets the hash algorithm for a given external PSK object. The supported PSK hash
2910 : : * algorithms are as listed in the enum `s2n_psk_hmac` above.
2911 : : *
2912 : : * @param psk A pointer to the external PSK object to be updated with the PSK hash algorithm.
2913 : : * @param hmac The PSK hash algorithm being set.
2914 : : */
2915 : : S2N_API int s2n_psk_set_hmac(struct s2n_psk *psk, s2n_psk_hmac hmac);
2916 : :
2917 : : /**
2918 : : * Appends a PSK object to the list of PSKs supported by the s2n connection.
2919 : : * If a PSK with a duplicate identity is found, an error is returned and the PSK is not added to the list.
2920 : : * Note that a copy of `psk` is stored on the connection. The user is still responsible for freeing the
2921 : : * memory associated with `psk`.
2922 : : *
2923 : : * @param conn A pointer to the s2n_connection object that contains the list of PSKs supported.
2924 : : * @param psk A pointer to the `s2n_psk` object to be appended to the list of PSKs on the s2n connection.
2925 : : */
2926 : : S2N_API int s2n_connection_append_psk(struct s2n_connection *conn, struct s2n_psk *psk);
2927 : :
2928 : : /**
2929 : : * The list of PSK modes supported by s2n-tls for TLS versions >= TLS1.3.
2930 : : * Currently s2n-tls supports two modes - `S2N_PSK_MODE_RESUMPTION`, which represents the PSKs established
2931 : : * using the previous connection via session resumption, and `S2N_PSK_MODE_EXTERNAL`, which represents PSKs
2932 : : * established out-of-band/externally using a secure mutually agreed upon mechanism.
2933 : : */
2934 : : typedef enum {
2935 : : S2N_PSK_MODE_RESUMPTION,
2936 : : S2N_PSK_MODE_EXTERNAL
2937 : : } s2n_psk_mode;
2938 : :
2939 : : /**
2940 : : * Sets the PSK mode on the s2n config object.
2941 : : * The supported PSK modes are listed in the enum `s2n_psk_mode` above.
2942 : : *
2943 : : * @param config A pointer to the s2n_config object being updated.
2944 : : * @param mode The PSK mode to be set.
2945 : : */
2946 : : S2N_API int s2n_config_set_psk_mode(struct s2n_config *config, s2n_psk_mode mode);
2947 : :
2948 : : /**
2949 : : * Sets the PSK mode on the s2n connection object.
2950 : : * The supported PSK modes are listed in the enum `s2n_psk_mode` above.
2951 : : * This API overrides the PSK mode set on config for this connection.
2952 : : *
2953 : : * @param conn A pointer to the s2n_connection object being updated.
2954 : : * @param mode The PSK mode to be set.
2955 : : */
2956 : : S2N_API int s2n_connection_set_psk_mode(struct s2n_connection *conn, s2n_psk_mode mode);
2957 : :
2958 : : /**
2959 : : * Gets the negotiated PSK identity length from the s2n connection object. The negotiated PSK
2960 : : * refers to the chosen PSK by the server to be used for the connection.
2961 : : *
2962 : : * This API can be used to determine if the negotiated PSK exists. If negotiated PSK exists a
2963 : : * call to this API returns a value greater than zero. If the negotiated PSK does not exist, the
2964 : : * value `0` is returned.
2965 : : *
2966 : : * @param conn A pointer to the s2n_connection object that successfully negotiated a PSK connection.
2967 : : * @param identity_length The length of the negotiated PSK identity.
2968 : : */
2969 : : S2N_API int s2n_connection_get_negotiated_psk_identity_length(struct s2n_connection *conn, uint16_t *identity_length);
2970 : :
2971 : : /**
2972 : : * Gets the negotiated PSK identity from the s2n connection object.
2973 : : * If the negotiated PSK does not exist, the PSK identity will not be obtained and no error will be returned.
2974 : : * Prior to this API call, use `s2n_connection_get_negotiated_psk_identity_length` to determine if a
2975 : : * negotiated PSK exists or not.
2976 : : *
2977 : : * # Safety
2978 : : *
2979 : : * The negotiated PSK identity will be copied into the identity buffer on success.
2980 : : * Therefore, the identity buffer must have enough memory to fit the identity length.
2981 : : *
2982 : : * @param conn A pointer to the s2n_connection object.
2983 : : * @param identity The negotiated PSK identity obtained from the s2n_connection object.
2984 : : * @param max_identity_length The maximum length for the PSK identity. If the negotiated psk_identity length is
2985 : : * greater than this `max_identity_length` value an error will be returned.
2986 : : */
2987 : : S2N_API int s2n_connection_get_negotiated_psk_identity(struct s2n_connection *conn, uint8_t *identity, uint16_t max_identity_length);
2988 : :
2989 : : struct s2n_offered_psk;
2990 : :
2991 : : /**
2992 : : * Creates a new s2n offered PSK object.
2993 : : * An offered PSK object represents a single PSK sent by the client.
2994 : : *
2995 : : * # Safety
2996 : : *
2997 : : * Use `s2n_offered_psk_free` to free the memory allocated to the s2n offered PSK object created by this API.
2998 : : *
2999 : : * @returns struct s2n_offered_psk* Returns a pointer to the newly created offered PSK object.
3000 : : */
3001 : : S2N_API struct s2n_offered_psk *s2n_offered_psk_new(void);
3002 : :
3003 : : /**
3004 : : * Frees the memory associated with the `s2n_offered_psk` object.
3005 : : *
3006 : : * @param psk A pointer to the `s2n_offered_psk` object to be freed.
3007 : : */
3008 : : S2N_API int s2n_offered_psk_free(struct s2n_offered_psk **psk);
3009 : :
3010 : : /**
3011 : : * Gets the PSK identity and PSK identity length for a given offered PSK object.
3012 : : *
3013 : : * @param psk A pointer to the offered PSK object being read.
3014 : : * @param identity The PSK identity being obtained.
3015 : : * @param size The length of the PSK identity being obtained.
3016 : : */
3017 : : S2N_API int s2n_offered_psk_get_identity(struct s2n_offered_psk *psk, uint8_t **identity, uint16_t *size);
3018 : :
3019 : : struct s2n_offered_psk_list;
3020 : :
3021 : : /**
3022 : : * Checks whether the offered PSK list has an offered psk object next in line in the list.
3023 : : * An offered PSK list contains all the PSKs offered by the client for the server to select.
3024 : : *
3025 : : * # Safety
3026 : : *
3027 : : * This API returns a pointer to the s2n-tls internal memory with limited lifetime.
3028 : : * After the completion of `s2n_psk_selection_callback` this pointer is invalid.
3029 : : *
3030 : : * @param psk_list A pointer to the offered PSK list being read.
3031 : : * @returns bool A boolean value representing whether an offered psk object is present next in line in the offered PSK list.
3032 : : */
3033 : : S2N_API bool s2n_offered_psk_list_has_next(struct s2n_offered_psk_list *psk_list);
3034 : :
3035 : : /**
3036 : : * Obtains the next offered PSK object from the list of offered PSKs. Use `s2n_offered_psk_list_has_next`
3037 : : * prior to this API call to ensure we have not reached the end of the list.
3038 : : *
3039 : : * @param psk_list A pointer to the offered PSK list being read.
3040 : : * @param psk A pointer to the next offered PSK object being obtained.
3041 : : */
3042 : : S2N_API int s2n_offered_psk_list_next(struct s2n_offered_psk_list *psk_list, struct s2n_offered_psk *psk);
3043 : :
3044 : : /**
3045 : : * Returns the offered PSK list to its original read state.
3046 : : *
3047 : : * When `s2n_offered_psk_list_reread` is called, `s2n_offered_psk_list_next` will return the first PSK
3048 : : * in the offered PSK list.
3049 : : *
3050 : : * @param psk_list A pointer to the offered PSK list being reread.
3051 : : */
3052 : : S2N_API int s2n_offered_psk_list_reread(struct s2n_offered_psk_list *psk_list);
3053 : :
3054 : : /**
3055 : : * Chooses a PSK from the offered PSK list to be used for the connection.
3056 : : * This API matches the PSK identity received from the client against the server's known PSK identities
3057 : : * list, in order to choose the PSK to be used for the connection. If the PSK identity sent from the client
3058 : : * is NULL, no PSK is chosen for the connection. If the client offered PSK identity has no matching PSK identity
3059 : : * with the server, an error will be returned. Use this API along with the `s2n_psk_selection_callback` callback
3060 : : * to select a PSK identity.
3061 : : *
3062 : : * @param psk_list A pointer to the server's known PSK list used to compare for a matching PSK with the client.
3063 : : * @param psk A pointer to the client's PSK object used to compare with the server's known PSK identities.
3064 : : */
3065 : : S2N_API int s2n_offered_psk_list_choose_psk(struct s2n_offered_psk_list *psk_list, struct s2n_offered_psk *psk);
3066 : :
3067 : : /**
3068 : : * Callback function to select a PSK from a list of offered PSKs.
3069 : : * Use this callback to implement custom PSK selection logic. The s2n-tls default PSK selection logic
3070 : : * chooses the first matching PSK from the list of offered PSKs sent by the client.
3071 : : *
3072 : : * # Safety
3073 : : *
3074 : : * `context` is a void pointer and the caller is responsible for ensuring it is cast to the correct type.
3075 : : * After the completion of this callback, the pointer to `psk_list` is invalid.
3076 : : *
3077 : : * @param conn A pointer to the s2n_connection object.
3078 : : * @param context A pointer to a context for the caller to pass state to the callback, if needed.
3079 : : * @param psk_list A pointer to the offered PSK list being read.
3080 : : */
3081 : : typedef int (*s2n_psk_selection_callback)(struct s2n_connection *conn, void *context,
3082 : : struct s2n_offered_psk_list *psk_list);
3083 : :
3084 : : /**
3085 : : * Sets the callback to select the matching PSK.
3086 : : * If this callback is not set s2n-tls uses a default PSK selection logic that selects the first matching
3087 : : * server PSK.
3088 : : *
3089 : : * @param config A pointer to the s2n_config object.
3090 : : * @param cb The function that should be called when the callback is triggered.
3091 : : * @param context A pointer to a context for the caller to pass state to the callback, if needed.
3092 : : */
3093 : : S2N_API int s2n_config_set_psk_selection_callback(struct s2n_config *config, s2n_psk_selection_callback cb, void *context);
3094 : :
3095 : : /**
3096 : : * Get the number of bytes the connection has received.
3097 : : *
3098 : : * @param conn A pointer to the connection
3099 : : * @returns return the number of bytes received by s2n-tls "on the wire"
3100 : : */
3101 : : S2N_API extern uint64_t s2n_connection_get_wire_bytes_in(struct s2n_connection *conn);
3102 : :
3103 : : /**
3104 : : * Get the number of bytes the connection has transmitted out.
3105 : : *
3106 : : * @param conn A pointer to the connection
3107 : : * @returns return the number of bytes transmitted out by s2n-tls "on the wire"
3108 : : */
3109 : : S2N_API extern uint64_t s2n_connection_get_wire_bytes_out(struct s2n_connection *conn);
3110 : :
3111 : : /**
3112 : : * Access the protocol version supported by the client.
3113 : : *
3114 : : * @note The return value corresponds to the macros defined as S2N_SSLv2,
3115 : : * S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
3116 : : *
3117 : : * @param conn A pointer to the connection
3118 : : * @returns returns the highest protocol version supported by the client
3119 : : */
3120 : : S2N_API extern int s2n_connection_get_client_protocol_version(struct s2n_connection *conn);
3121 : :
3122 : : /**
3123 : : * Access the protocol version supported by the server.
3124 : : *
3125 : : * @note The return value corresponds to the macros defined as S2N_SSLv2,
3126 : : * S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
3127 : : *
3128 : : * @param conn A pointer to the connection
3129 : : * @returns Returns the highest protocol version supported by the server
3130 : : */
3131 : : S2N_API extern int s2n_connection_get_server_protocol_version(struct s2n_connection *conn);
3132 : :
3133 : : /**
3134 : : * Access the protocol version selected for the connection.
3135 : : *
3136 : : * @note The return value corresponds to the macros defined as S2N_SSLv2,
3137 : : * S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
3138 : : *
3139 : : * @param conn A pointer to the connection
3140 : : * @returns The protocol version actually negotiated by the handshake
3141 : : */
3142 : : S2N_API extern int s2n_connection_get_actual_protocol_version(struct s2n_connection *conn);
3143 : :
3144 : : /**
3145 : : * Access the client hello protocol version for the connection.
3146 : : *
3147 : : * @note The return value corresponds to the macros defined as S2N_SSLv2,
3148 : : * S2N_SSLv3, S2N_TLS10, S2N_TLS11, S2N_TLS12, and S2N_TLS13.
3149 : : *
3150 : : * @param conn A pointer to the connection
3151 : : * @returns The protocol version used to send the initial client hello message.
3152 : : */
3153 : : S2N_API extern int s2n_connection_get_client_hello_version(struct s2n_connection *conn);
3154 : :
3155 : : /**
3156 : : * Access the protocol version from the header of the first record that contained the ClientHello message.
3157 : : *
3158 : : * @note This field has been deprecated and should not be confused with the client hello
3159 : : * version. It is often set very low, usually to TLS1.0 for compatibility reasons,
3160 : : * and should never be set higher than TLS1.2. Therefore this method should only be used
3161 : : * for logging or fingerprinting.
3162 : : *
3163 : : * @param conn A pointer to the client hello struct
3164 : : * @param out The protocol version in the record header containing the Client Hello.
3165 : : */
3166 : : S2N_API extern int s2n_client_hello_get_legacy_record_version(struct s2n_client_hello *ch, uint8_t *out);
3167 : :
3168 : : /**
3169 : : * Check if Client Auth was used for a connection.
3170 : : *
3171 : : * @param conn A pointer to the connection
3172 : : * @returns 1 if the handshake completed and Client Auth was negotiated during then
3173 : : * handshake.
3174 : : */
3175 : : S2N_API extern int s2n_connection_client_cert_used(struct s2n_connection *conn);
3176 : :
3177 : : /**
3178 : : * A function that provides a human readable string of the cipher suite that was chosen
3179 : : * for a connection.
3180 : : *
3181 : : * @warning The string "TLS_NULL_WITH_NULL_NULL" is returned before the TLS handshake has been performed.
3182 : : * This does not mean that the ciphersuite "TLS_NULL_WITH_NULL_NULL" will be used by the connection,
3183 : : * it is merely being used as a placeholder.
3184 : : *
3185 : : * @note This function is only accurate after the TLS handshake.
3186 : : *
3187 : : * @param conn A pointer to the connection
3188 : : * @returns A string indicating the cipher suite negotiated by s2n in OpenSSL format.
3189 : : */
3190 : : S2N_API extern const char *s2n_connection_get_cipher(struct s2n_connection *conn);
3191 : :
3192 : : /**
3193 : : * A metric to determine whether or not the server found a certificate that matched
3194 : : * the client's SNI extension.
3195 : : *
3196 : : * S2N_SNI_NONE: Client did not send the SNI extension.
3197 : : * S2N_SNI_EXACT_MATCH: Server had a certificate that matched the client's SNI extension.
3198 : : * S2N_SNI_WILDCARD_MATCH: Server had a certificate with a domain name containing a wildcard character
3199 : : * that could be matched to the client's SNI extension.
3200 : : * S2N_SNI_NO_MATCH: Server did not have a certificate that could be matched to the client's
3201 : : * SNI extension.
3202 : : */
3203 : : typedef enum {
3204 : : S2N_SNI_NONE = 1,
3205 : : S2N_SNI_EXACT_MATCH,
3206 : : S2N_SNI_WILDCARD_MATCH,
3207 : : S2N_SNI_NO_MATCH,
3208 : : } s2n_cert_sni_match;
3209 : :
3210 : : /**
3211 : : * A function that provides insight into whether or not the server was able to send a certificate that
3212 : : * partially or completely matched the client's SNI extension.
3213 : : *
3214 : : * @note This function can be used as a metric in a failed connection as long as the failure
3215 : : * occurs after certificate selection.
3216 : : *
3217 : : * @param conn A pointer to the connection
3218 : : * @param cert_match An enum indicating whether or not the server found a certificate
3219 : : * that matched the client's SNI extension.
3220 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
3221 : : */
3222 : : S2N_API extern int s2n_connection_get_certificate_match(struct s2n_connection *conn, s2n_cert_sni_match *match_status);
3223 : :
3224 : : /**
3225 : : * Provides access to the TLS master secret.
3226 : : *
3227 : : * This is a dangerous method and should not be used unless absolutely necessary.
3228 : : * Mishandling the master secret can compromise both the current connection
3229 : : * and any past or future connections that use the same master secret due to
3230 : : * session resumption.
3231 : : *
3232 : : * This method is only supported for older TLS versions, and will report an S2N_ERR_INVALID_STATE
3233 : : * usage error if called for a TLS1.3 connection. TLS1.3 includes a new key schedule
3234 : : * that derives independent secrets from the master secret for specific purposes,
3235 : : * such as separate traffic, session ticket, and exporter secrets. Using the master
3236 : : * secret directly circumvents that security feature, reducing the security of
3237 : : * the protocol.
3238 : : *
3239 : : * If you need cryptographic material tied to the current TLS session, consider
3240 : : * `s2n_connection_tls_exporter` instead. Although s2n_connection_tls_exporter
3241 : : * currently only supports TLS1.3, there is also an RFC that describes exporters
3242 : : * for older TLS versions: https://datatracker.ietf.org/doc/html/rfc5705
3243 : : * Using the master secret as-is or defining your own exporter is dangerous.
3244 : : *
3245 : : * @param conn A pointer to the connection.
3246 : : * @param secret_bytes Memory to copy the master secret into. The secret
3247 : : * is always 48 bytes long.
3248 : : * @param max_size The size of the memory available at `secret_bytes`. Must be
3249 : : * at least 48 bytes.
3250 : : * @returns S2N_SUCCESS on success, S2N_FAILURE otherwise. `secret_bytes`
3251 : : * will be set on success.
3252 : : */
3253 : : S2N_API extern int s2n_connection_get_master_secret(const struct s2n_connection *conn,
3254 : : uint8_t *secret_bytes, size_t max_size);
3255 : :
3256 : : /**
3257 : : * Provides access to the TLS-Exporter functionality.
3258 : : *
3259 : : * See https://datatracker.ietf.org/doc/html/rfc5705 and https://www.rfc-editor.org/rfc/rfc8446.
3260 : : *
3261 : : * @note This is currently only available with TLS 1.3 connections which have finished a handshake.
3262 : : *
3263 : : * @param conn A pointer to the connection
3264 : : * @returns A POSIX error signal. If an error was returned, the value contained in `output` should be considered invalid.
3265 : : */
3266 : : S2N_API extern int s2n_connection_tls_exporter(struct s2n_connection *conn,
3267 : : const uint8_t *label, uint32_t label_length, const uint8_t *context, uint32_t context_length,
3268 : : uint8_t *output, uint32_t output_length);
3269 : :
3270 : : /**
3271 : : * Returns the IANA value for the connection's negotiated cipher suite.
3272 : : *
3273 : : * The value is returned in the form of `first,second`, in order to closely match
3274 : : * the values defined in the [IANA Registry](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
3275 : : * For example if the connection's negotiated cipher suite is `TLS_AES_128_GCM_SHA256`,
3276 : : * which is registered as `0x13,0x01`, then `first = 0x13` and `second = 0x01`.
3277 : : *
3278 : : * This method will only succeed after the cipher suite has been negotiated with the peer.
3279 : : *
3280 : : * @param conn A pointer to the connection being read
3281 : : * @param first A pointer to a single byte, which will be updated with the first byte in the registered IANA value.
3282 : : * @param second A pointer to a single byte, which will be updated with the second byte in the registered IANA value.
3283 : : * @returns A POSIX error signal. If an error was returned, the values contained in `first` and `second` should be considered invalid.
3284 : : */
3285 : : S2N_API extern int s2n_connection_get_cipher_iana_value(struct s2n_connection *conn, uint8_t *first, uint8_t *second);
3286 : :
3287 : : /**
3288 : : * Function to check if the cipher used by current connection is supported by the current
3289 : : * cipher preferences.
3290 : : * @param conn A pointer to the s2n connection
3291 : : * @param version A string representing the security policy to check against.
3292 : : * @returns 1 if the connection satisfies the cipher suite. 0 if the connection does not satisfy the cipher suite. -1 if there is an error.
3293 : : */
3294 : : S2N_API extern int s2n_connection_is_valid_for_cipher_preferences(struct s2n_connection *conn, const char *version);
3295 : :
3296 : : /**
3297 : : * Function to get the human readable elliptic curve name for the connection.
3298 : : *
3299 : : * @deprecated Use `s2n_connection_get_key_exchange_group` instead
3300 : : *
3301 : : * @param conn A pointer to the s2n connection
3302 : : * @returns A string indicating the elliptic curve used during ECDHE key exchange. The string "NONE" is returned if no curve was used.
3303 : : */
3304 : : S2N_API extern const char *s2n_connection_get_curve(struct s2n_connection *conn);
3305 : :
3306 : : /**
3307 : : * Function to get the human readable KEM name for the connection.
3308 : : *
3309 : : * @deprecated This function was previously used to retrieve the negotiated PQ group in TLS 1.2.
3310 : : * PQ key exchange in TLS1.2 was experimental and is now deprecated. Use s2n_connection_get_kem_group_name()
3311 : : * to retrieve the PQ TLS 1.3 Group name.
3312 : : *
3313 : : * @param conn A pointer to the s2n connection
3314 : : * @returns A human readable string for the KEM group. If there is no KEM configured returns "NONE"
3315 : : */
3316 : : S2N_API extern const char *s2n_connection_get_kem_name(struct s2n_connection *conn);
3317 : :
3318 : : /**
3319 : : * Function to get the human readable KEM group name for the connection.
3320 : : *
3321 : : * @note PQ key exchange will not occur if the connection is < TLS1.3 or the configured security
3322 : : * policy has no KEM groups on it. It also will not occur if the peer does not support PQ key exchange.
3323 : : * In these instances this function will return "NONE".
3324 : : *
3325 : : * @param conn A pointer to the s2n connection
3326 : : * @returns A human readable string for the KEM group. Returns "NONE" if no PQ key exchange occurred.
3327 : : */
3328 : : S2N_API extern const char *s2n_connection_get_kem_group_name(struct s2n_connection *conn);
3329 : :
3330 : : /**
3331 : : * Function to get the human readable key exchange group name for the connection, for example:
3332 : : * `secp521r1` or `SecP256r1MLKEM768`. If an EC curve or KEM was not negotiated, S2N_FAILURE will be
3333 : : * returned.
3334 : : *
3335 : : * @note This function replaces `s2n_connection_get_curve` and `s2n_connection_get_kem_group_name`, returning
3336 : : * the named group regardless if a hybrid PQ group was negotiated or not.
3337 : : *
3338 : : * @param conn A pointer to the s2n connection
3339 : : * @param group_name A pointer that will be set to point to a const char* containing the group name
3340 : : * @returns S2N_SUCCESS on success, S2N_FAILURE otherwise. `group_name` will be set on success.
3341 : : */
3342 : : S2N_API extern int s2n_connection_get_key_exchange_group(struct s2n_connection *conn, const char **group_name);
3343 : :
3344 : : /**
3345 : : * Function to get the alert that caused a connection to close. s2n-tls considers all
3346 : : * TLS alerts fatal and shuts down a connection whenever one is received.
3347 : : *
3348 : : * @param conn A pointer to the s2n connection
3349 : : * @returns The TLS alert code that caused a connection to be shut down
3350 : : */
3351 : : S2N_API extern int s2n_connection_get_alert(struct s2n_connection *conn);
3352 : :
3353 : : /**
3354 : : * Function to return the last TLS handshake type that was processed. The returned format is a human readable string.
3355 : : *
3356 : : * @param conn A pointer to the s2n connection
3357 : : * @returns A human-readable handshake type name, e.g. "NEGOTIATED|FULL_HANDSHAKE|PERFECT_FORWARD_SECRECY"
3358 : : */
3359 : : S2N_API extern const char *s2n_connection_get_handshake_type_name(struct s2n_connection *conn);
3360 : :
3361 : : /**
3362 : : * Function to return the last TLS message that was processed. The returned format is a human readable string.
3363 : : * @param conn A pointer to the s2n connection
3364 : : * @returns The last message name in the TLS state machine, e.g. "SERVER_HELLO", "APPLICATION_DATA".
3365 : : */
3366 : : S2N_API extern const char *s2n_connection_get_last_message_name(struct s2n_connection *conn);
3367 : :
3368 : : /**
3369 : : * Opaque async private key operation handle
3370 : : */
3371 : : struct s2n_async_pkey_op;
3372 : :
3373 : : /**
3374 : : * Sets whether or not a connection should enforce strict signature validation during the
3375 : : * `s2n_async_pkey_op_apply` call.
3376 : : *
3377 : : * `mode` can take the following values:
3378 : : * - `S2N_ASYNC_PKEY_VALIDATION_FAST` - default behavior: s2n-tls will perform only the minimum validation required for safe use of the asyn pkey operation.
3379 : : * - `S2N_ASYNC_PKEY_VALIDATION_STRICT` - in addition to the previous checks, s2n-tls will also ensure that the signature created as a result of the async private key sign operation matches the public key on the connection.
3380 : : */
3381 : : typedef enum {
3382 : : S2N_ASYNC_PKEY_VALIDATION_FAST,
3383 : : S2N_ASYNC_PKEY_VALIDATION_STRICT
3384 : : } s2n_async_pkey_validation_mode;
3385 : :
3386 : : /**
3387 : : * The type of private key operation
3388 : : */
3389 : : typedef enum {
3390 : : S2N_ASYNC_DECRYPT,
3391 : : S2N_ASYNC_SIGN
3392 : : } s2n_async_pkey_op_type;
3393 : :
3394 : : /**
3395 : : * Callback function for handling private key operations
3396 : : *
3397 : : * Invoked every time an operation requiring the private key is encountered
3398 : : * during the handshake.
3399 : : *
3400 : : * # Safety
3401 : : * * `op` is owned by the application and MUST be freed.
3402 : : *
3403 : : * @param conn Connection which triggered the callback
3404 : : * @param op An opaque object representing the private key operation
3405 : : */
3406 : : typedef int (*s2n_async_pkey_fn)(struct s2n_connection *conn, struct s2n_async_pkey_op *op);
3407 : :
3408 : : /**
3409 : : * Sets up the callback to invoke when private key operations occur.
3410 : : *
3411 : : * @param config Config to set the callback
3412 : : * @param fn The function that should be called for each private key operation
3413 : : */
3414 : : S2N_API extern int s2n_config_set_async_pkey_callback(struct s2n_config *config, s2n_async_pkey_fn fn);
3415 : :
3416 : : /**
3417 : : * Performs a private key operation using the given private key.
3418 : : *
3419 : : * # Safety
3420 : : * * Can only be called once. Any subsequent calls will produce a `S2N_ERR_T_USAGE` error.
3421 : : * * Safe to call from inside s2n_async_pkey_fn
3422 : : * * Safe to call from a different thread, as long as no other thread is operating on `op`.
3423 : : *
3424 : : * @param op An opaque object representing the private key operation
3425 : : * @param key The private key used for the operation. It can be extracted from
3426 : : * `conn` through the `s2n_connection_get_selected_cert` and `s2n_cert_chain_and_key_get_private_key` calls
3427 : : */
3428 : : S2N_API extern int s2n_async_pkey_op_perform(struct s2n_async_pkey_op *op, s2n_cert_private_key *key);
3429 : :
3430 : : /**
3431 : : * Finalizes a private key operation and unblocks the connection.
3432 : : *
3433 : : * # Safety
3434 : : * * `conn` must match the connection that originally triggered the callback.
3435 : : * * Must be called after the operation is performed.
3436 : : * * Can only be called once. Any subsequent calls will produce a `S2N_ERR_T_USAGE` error.
3437 : : * * Safe to call from inside s2n_async_pkey_fn
3438 : : * * Safe to call from a different thread, as long as no other thread is operating on `op`.
3439 : : *
3440 : : * @param op An opaque object representing the private key operation
3441 : : * @param conn The connection associated with the operation that should be unblocked
3442 : : */
3443 : : S2N_API extern int s2n_async_pkey_op_apply(struct s2n_async_pkey_op *op, struct s2n_connection *conn);
3444 : :
3445 : : /**
3446 : : * Frees the opaque structure representing a private key operation.
3447 : : *
3448 : : * # Safety
3449 : : * * MUST be called for every operation passed to s2n_async_pkey_fn
3450 : : * * Safe to call before or after the connection that created the operation is freed
3451 : : *
3452 : : * @param op An opaque object representing the private key operation
3453 : : */
3454 : : S2N_API extern int s2n_async_pkey_op_free(struct s2n_async_pkey_op *op);
3455 : :
3456 : : /**
3457 : : * Configures whether or not s2n-tls will perform potentially expensive validation of
3458 : : * the results of a private key operation.
3459 : : *
3460 : : * @param config Config to set the validation mode for
3461 : : * @param mode What level of validation to perform
3462 : : */
3463 : : S2N_API extern int s2n_config_set_async_pkey_validation_mode(struct s2n_config *config, s2n_async_pkey_validation_mode mode);
3464 : :
3465 : : /**
3466 : : * Returns the type of the private key operation.
3467 : : *
3468 : : * @param op An opaque object representing the private key operation
3469 : : * @param type A pointer to be set to the type
3470 : : */
3471 : : S2N_API extern int s2n_async_pkey_op_get_op_type(struct s2n_async_pkey_op *op, s2n_async_pkey_op_type *type);
3472 : :
3473 : : /**
3474 : : * Returns the size of the input to the private key operation.
3475 : : *
3476 : : * @param op An opaque object representing the private key operation
3477 : : * @param data_len A pointer to be set to the size
3478 : : */
3479 : : S2N_API extern int s2n_async_pkey_op_get_input_size(struct s2n_async_pkey_op *op, uint32_t *data_len);
3480 : :
3481 : : /**
3482 : : * Returns the input to the private key operation.
3483 : : *
3484 : : * When signing, the input is the digest to sign.
3485 : : * When decrypting, the input is the data to decrypt.
3486 : : *
3487 : : * When signing with ML-DSA, the input is the "external mu" pre-hash value described in
3488 : : * https://www.ietf.org/archive/id/draft-ietf-lamps-dilithium-certificates-09.html#appendix-D
3489 : : *
3490 : : * # Safety
3491 : : * * `data` must be sufficiently large to contain the input.
3492 : : * `s2n_async_pkey_op_get_input_size` can be called to determine how much memory is required.
3493 : : * * s2n-tls does not take ownership of `data`.
3494 : : * The application still owns the memory and must free it if necessary.
3495 : : *
3496 : : * @param op An opaque object representing the private key operation
3497 : : * @param data A pointer to a buffer to copy the input into
3498 : : * @param data_len The maximum size of the `data` buffer
3499 : : */
3500 : : S2N_API extern int s2n_async_pkey_op_get_input(struct s2n_async_pkey_op *op, uint8_t *data, uint32_t data_len);
3501 : :
3502 : : /**
3503 : : * Sets the output of the private key operation.
3504 : : *
3505 : : * # Safety
3506 : : * * s2n-tls does not take ownership of `data`.
3507 : : * The application still owns the memory and must free it if necessary.
3508 : : *
3509 : : * @param op An opaque object representing the private key operation
3510 : : * @param data A pointer to a buffer containing the output
3511 : : * @param data_len The size of the `data` buffer
3512 : : */
3513 : : S2N_API extern int s2n_async_pkey_op_set_output(struct s2n_async_pkey_op *op, const uint8_t *data, uint32_t data_len);
3514 : :
3515 : : /**
3516 : : * Callback function for handling key log events
3517 : : *
3518 : : * THIS SHOULD BE USED FOR DEBUGGING PURPOSES ONLY!
3519 : : *
3520 : : * Each log line is formatted with the
3521 : : * [NSS Key Log Format](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)
3522 : : * without a newline.
3523 : : *
3524 : : * # Safety
3525 : : *
3526 : : * * `ctx` MUST be cast into the same type of pointer that was originally created
3527 : : * * `logline` bytes MUST be copied or discarded before this function returns
3528 : : *
3529 : : * @param ctx Context for the callback
3530 : : * @param conn Connection for which the log line is being emitted
3531 : : * @param logline Pointer to the log line data
3532 : : * @param len Length of the log line data
3533 : : */
3534 : : typedef int (*s2n_key_log_fn)(void *ctx, struct s2n_connection *conn, uint8_t *logline, size_t len);
3535 : :
3536 : : /**
3537 : : * Sets a key logging callback on the provided config
3538 : : *
3539 : : * THIS SHOULD BE USED FOR DEBUGGING PURPOSES ONLY!
3540 : : *
3541 : : * Setting this function enables configurations to emit secrets in the
3542 : : * [NSS Key Log Format](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)
3543 : : *
3544 : : * # Safety
3545 : : *
3546 : : * * `callback` MUST cast `ctx` into the same type of pointer that was originally created
3547 : : * * `ctx` MUST live for at least as long as it is set on the config
3548 : : *
3549 : : * @param config Config to set the callback
3550 : : * @param callback The function that should be called for each secret log entry
3551 : : * @param ctx The context to be passed when the callback is called
3552 : : */
3553 : : S2N_API extern int s2n_config_set_key_log_cb(struct s2n_config *config, s2n_key_log_fn callback, void *ctx);
3554 : :
3555 : : /**
3556 : : * s2n_config_enable_cert_req_dss_legacy_compat adds a dss cert type in the server certificate request when being called.
3557 : : * It only sends the dss cert type in the cert request but does not succeed the handshake if a dss cert is received.
3558 : : * Please DO NOT call this api unless you know you actually need legacy DSS certificate type compatibility
3559 : : * @param config Config to enable legacy DSS certificates for
3560 : : */
3561 : : S2N_API extern int s2n_config_enable_cert_req_dss_legacy_compat(struct s2n_config *config);
3562 : :
3563 : : /**
3564 : : * Sets the maximum bytes of early data the server will accept.
3565 : : *
3566 : : * The default maximum is 0. If the maximum is 0, the server rejects all early data requests.
3567 : : * The config maximum can be overridden by the connection maximum or the maximum on an external pre-shared key.
3568 : : *
3569 : : * @param config A pointer to the config
3570 : : * @param max_early_data_size The maximum early data that the server will accept
3571 : : * @returns A POSIX error signal. If successful, the maximum early data size was updated.
3572 : : */
3573 : : S2N_API int s2n_config_set_server_max_early_data_size(struct s2n_config *config, uint32_t max_early_data_size);
3574 : :
3575 : : /**
3576 : : * Sets the maximum bytes of early data the server will accept.
3577 : : *
3578 : : * The default maximum is 0. If the maximum is 0, the server rejects all early data requests.
3579 : : * The connection maximum can be overridden by the maximum on an external pre-shared key.
3580 : : *
3581 : : * @param conn A pointer to the connection
3582 : : * @param max_early_data_size The maximum early data the server will accept
3583 : : * @returns A POSIX error signal. If successful, the maximum early data size was updated.
3584 : : */
3585 : : S2N_API int s2n_connection_set_server_max_early_data_size(struct s2n_connection *conn, uint32_t max_early_data_size);
3586 : :
3587 : : /**
3588 : : * Sets the user context associated with early data on a server.
3589 : : *
3590 : : * This context is passed to the `s2n_early_data_cb` callback to help decide whether to accept or reject early data.
3591 : : *
3592 : : * Unlike most contexts, the early data context is a byte buffer instead of a void pointer.
3593 : : * This is because we need to serialize the context into session tickets.
3594 : : *
3595 : : * This API is intended for use with session resumption, and will not affect pre-shared keys.
3596 : : *
3597 : : * @param conn A pointer to the connection
3598 : : * @param context A pointer to the user context data. This data will be copied.
3599 : : * @param context_size The size of the data to read from the `context` pointer.
3600 : : * @returns A POSIX error signal. If successful, the context was updated.
3601 : : */
3602 : : S2N_API int s2n_connection_set_server_early_data_context(struct s2n_connection *conn, const uint8_t *context, uint16_t context_size);
3603 : :
3604 : : /**
3605 : : * Configures a particular pre-shared key to allow early data.
3606 : : *
3607 : : * `max_early_data_size` must be set to the maximum early data accepted by the server.
3608 : : *
3609 : : * In order to use early data, the cipher suite set on the pre-shared key must match the cipher suite
3610 : : * ultimately negotiated by the TLS handshake. Additionally, the cipher suite must have the same
3611 : : * hmac algorithm as the pre-shared key.
3612 : : *
3613 : : * @param psk A pointer to the pre-shared key, created with `s2n_external_psk_new`.
3614 : : * @param max_early_data_size The maximum early data that can be sent or received using this key.
3615 : : * @param cipher_suite_first_byte The first byte in the registered IANA value of the associated cipher suite.
3616 : : * @param cipher_suite_second_byte The second byte in the registered IANA value of the associated cipher suite.
3617 : : * @returns A POSIX error signal. If successful, `psk` was updated.
3618 : : */
3619 : : S2N_API int s2n_psk_configure_early_data(struct s2n_psk *psk, uint32_t max_early_data_size,
3620 : : uint8_t cipher_suite_first_byte, uint8_t cipher_suite_second_byte);
3621 : :
3622 : : /**
3623 : : * Sets the optional `application_protocol` associated with the given pre-shared key.
3624 : : *
3625 : : * In order to use early data, the `application_protocol` set on the pre-shared key must match
3626 : : * the `application_protocol` ultimately negotiated by the TLS handshake.
3627 : : *
3628 : : * @param psk A pointer to the pre-shared key, created with `s2n_external_psk_new`.
3629 : : * @param application_protocol A pointer to the associated application protocol data. This data will be copied.
3630 : : * @param size The size of the data to read from the `application_protocol` pointer.
3631 : : * @returns A POSIX error signal. If successful, the application protocol was set.
3632 : : */
3633 : : S2N_API int s2n_psk_set_application_protocol(struct s2n_psk *psk, const uint8_t *application_protocol, uint8_t size);
3634 : :
3635 : : /**
3636 : : * Sets the optional user early data context associated with the given pre-shared key.
3637 : : *
3638 : : * The early data context is passed to the `s2n_early_data_cb` callback to help decide whether
3639 : : * to accept or reject early data.
3640 : : *
3641 : : * @param psk A pointer to the pre-shared key, created with `s2n_external_psk_new`.
3642 : : * @param context A pointer to the associated user context data. This data will be copied.
3643 : : * @param size The size of the data to read from the `context` pointer.
3644 : : * @returns A POSIX error signal. If successful, the context was set.
3645 : : */
3646 : : S2N_API int s2n_psk_set_early_data_context(struct s2n_psk *psk, const uint8_t *context, uint16_t size);
3647 : :
3648 : : /**
3649 : : * The status of early data on a connection.
3650 : : *
3651 : : * S2N_EARLY_DATA_STATUS_OK: Early data is in progress.
3652 : : * S2N_EARLY_DATA_STATUS_NOT_REQUESTED: The client did not request early data, so none was sent or received.
3653 : : * S2N_EARLY_DATA_STATUS_REJECTED: The client requested early data, but the server rejected the request.
3654 : : * Early data may have been sent, but was not received.
3655 : : * S2N_EARLY_DATA_STATUS_END: All early data was successfully sent and received.
3656 : : */
3657 : : typedef enum {
3658 : : S2N_EARLY_DATA_STATUS_OK,
3659 : : S2N_EARLY_DATA_STATUS_NOT_REQUESTED,
3660 : : S2N_EARLY_DATA_STATUS_REJECTED,
3661 : : S2N_EARLY_DATA_STATUS_END,
3662 : : } s2n_early_data_status_t;
3663 : :
3664 : : /**
3665 : : * Reports the current state of early data for a connection.
3666 : : *
3667 : : * See `s2n_early_data_status_t` for all possible states.
3668 : : *
3669 : : * @param conn A pointer to the connection
3670 : : * @param status A pointer which will be set to the current early data status
3671 : : * @returns A POSIX error signal.
3672 : : */
3673 : : S2N_API int s2n_connection_get_early_data_status(struct s2n_connection *conn, s2n_early_data_status_t *status);
3674 : :
3675 : : /**
3676 : : * Reports the remaining size of the early data allowed by a connection.
3677 : : *
3678 : : * If early data was rejected or not requested, the remaining early data size is 0.
3679 : : * Otherwise, the remaining early data size is the maximum early data allowed by the connection,
3680 : : * minus the early data sent or received so far.
3681 : : *
3682 : : * @param conn A pointer to the connection
3683 : : * @param allowed_early_data_size A pointer which will be set to the remaining early data currently allowed by `conn`
3684 : : * @returns A POSIX error signal.
3685 : : */
3686 : : S2N_API int s2n_connection_get_remaining_early_data_size(struct s2n_connection *conn, uint32_t *allowed_early_data_size);
3687 : :
3688 : : /**
3689 : : * Reports the maximum size of the early data allowed by a connection.
3690 : : *
3691 : : * This is the maximum amount of early data that can ever be sent and received for a connection.
3692 : : * It is not affected by the actual status of the early data, so can be non-zero even if early data
3693 : : * is rejected or not requested.
3694 : : *
3695 : : * @param conn A pointer to the connection
3696 : : * @param max_early_data_size A pointer which will be set to the maximum early data allowed by `conn`
3697 : : * @returns A POSIX error signal.
3698 : : */
3699 : : S2N_API int s2n_connection_get_max_early_data_size(struct s2n_connection *conn, uint32_t *max_early_data_size);
3700 : :
3701 : : /**
3702 : : * Called by the client to begin negotiation and send early data.
3703 : : *
3704 : : * See https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch14-early-data.md
3705 : : * for usage and examples. DO NOT USE unless you have considered the security issues and
3706 : : * implemented mitigation for anti-replay attacks.
3707 : : *
3708 : : * @param conn A pointer to the connection
3709 : : * @param data A pointer to the early data to be sent
3710 : : * @param data_len The size of the early data to send
3711 : : * @param data_sent A pointer which will be set to the size of the early data sent
3712 : : * @param blocked A pointer which will be set to the blocked status, as in `s2n_negotiate`.
3713 : : * @returns A POSIX error signal. The error should be handled as in `s2n_negotiate`.
3714 : : */
3715 : : S2N_API int s2n_send_early_data(struct s2n_connection *conn, const uint8_t *data, ssize_t data_len,
3716 : : ssize_t *data_sent, s2n_blocked_status *blocked);
3717 : :
3718 : : /**
3719 : : * Called by the server to begin negotiation and accept any early data the client sends.
3720 : : *
3721 : : * See https://github.com/aws/s2n-tls/blob/main/docs/usage-guide/topics/ch14-early-data.md
3722 : : * for usage and examples. DO NOT USE unless you have considered the security issues and
3723 : : * implemented mitigation for anti-replay attacks.
3724 : : *
3725 : : * @param conn A pointer to the connection
3726 : : * @param data A pointer to a buffer to store the early data received
3727 : : * @param max_data_len The size of the early data buffer
3728 : : * @param data_received A pointer which will be set to the size of the early data received
3729 : : * @param blocked A pointer which will be set to the blocked status, as in `s2n_negotiate`.
3730 : : * @returns A POSIX error signal. The error should be handled as in `s2n_negotiate`.
3731 : : */
3732 : : S2N_API int s2n_recv_early_data(struct s2n_connection *conn, uint8_t *data, ssize_t max_data_len,
3733 : : ssize_t *data_received, s2n_blocked_status *blocked);
3734 : :
3735 : : struct s2n_offered_early_data;
3736 : :
3737 : : /**
3738 : : * A callback which can be implemented to accept or reject early data.
3739 : : *
3740 : : * This callback is triggered only after the server has determined early data is otherwise acceptable according
3741 : : * to the TLS early data specification. Implementations therefore only need to cover application-specific checks,
3742 : : * not the standard TLS early data validation.
3743 : : *
3744 : : * This callback can be synchronous or asynchronous. For asynchronous behavior, return success without
3745 : : * calling `s2n_offered_early_data_reject` or `s2n_offered_early_data_accept`. `early_data` will
3746 : : * still be a valid reference, and the connection will block until `s2n_offered_early_data_reject` or
3747 : : * `s2n_offered_early_data_accept` is called.
3748 : : *
3749 : : * @param conn A pointer to the connection
3750 : : * @param early_data A pointer which can be used to access information about the proposed early data
3751 : : * and then accept or reject it.
3752 : : * @returns A POSIX error signal. If unsuccessful, the connection will be closed with an error.
3753 : : */
3754 : : typedef int (*s2n_early_data_cb)(struct s2n_connection *conn, struct s2n_offered_early_data *early_data);
3755 : :
3756 : : /**
3757 : : * Set a callback to accept or reject early data.
3758 : : *
3759 : : * @param config A pointer to the connection config
3760 : : * @param cb A pointer to the implementation of the callback.
3761 : : * @returns A POSIX error signal. If successful, the callback was set.
3762 : : */
3763 : : S2N_API int s2n_config_set_early_data_cb(struct s2n_config *config, s2n_early_data_cb cb);
3764 : :
3765 : : /**
3766 : : * Get the length of the early data context set by the user.
3767 : : *
3768 : : * @param early_data A pointer to the early data information
3769 : : * @param context_len The length of the user context
3770 : : * @returns A POSIX error signal.
3771 : : */
3772 : : S2N_API int s2n_offered_early_data_get_context_length(struct s2n_offered_early_data *early_data, uint16_t *context_len);
3773 : :
3774 : : /**
3775 : : * Get the early data context set by the user.
3776 : : *
3777 : : * @param early_data A pointer to the early data information
3778 : : * @param context A byte buffer to copy the user context into
3779 : : * @param max_len The size of `context`. Must be >= to the result of `s2n_offered_early_data_get_context_length`.
3780 : : * @returns A POSIX error signal.
3781 : : */
3782 : : S2N_API int s2n_offered_early_data_get_context(struct s2n_offered_early_data *early_data, uint8_t *context, uint16_t max_len);
3783 : :
3784 : : /**
3785 : : * Reject early data offered by the client.
3786 : : *
3787 : : * @param early_data A pointer to the early data information
3788 : : * @returns A POSIX error signal. If success, the client's early data will be rejected.
3789 : : */
3790 : : S2N_API int s2n_offered_early_data_reject(struct s2n_offered_early_data *early_data);
3791 : :
3792 : : /**
3793 : : * Accept early data offered by the client.
3794 : : *
3795 : : * @param early_data A pointer to the early data information
3796 : : * @returns A POSIX error signal. If success, the client's early data will be accepted.
3797 : : */
3798 : : S2N_API int s2n_offered_early_data_accept(struct s2n_offered_early_data *early_data);
3799 : :
3800 : : /**
3801 : : * Retrieves the list of supported groups configured by the security policy associated with `config`.
3802 : : *
3803 : : * The retrieved list of groups will contain all of the supported groups for a security policy that are compatible
3804 : : * with the build of s2n-tls. For instance, PQ kem groups that are not supported by the linked libcrypto will not
3805 : : * be written. Otherwise, all of the supported groups configured for the security policy will be written. This API
3806 : : * can be used with the s2n_client_hello_get_supported_groups() API as a means of comparing compatibility between
3807 : : * a client and server.
3808 : : *
3809 : : * IANA values for each of the supported groups are written to the provided `groups` array, and `groups_count` is
3810 : : * set to the number of written supported groups.
3811 : : *
3812 : : * `groups_count_max` should be set to the maximum capacity of the `groups` array. If `groups_count_max` is less
3813 : : * than the number of supported groups configured by the security policy, this function will error.
3814 : : *
3815 : : * Note that this API retrieves only the groups from a security policy that are available to negotiate via the
3816 : : * supported groups extension, and does not return TLS 1.2 PQ kem groups that are negotiated in the supported PQ
3817 : : * kem parameters extension.
3818 : : *
3819 : : * @param config A pointer to the s2n_config object from which the supported groups will be retrieved.
3820 : : * @param groups The array to populate with the supported groups.
3821 : : * @param groups_count_max The maximum number of supported groups that can fit in the `groups` array.
3822 : : * @param groups_count Set to the number of supported groups written to `groups`.
3823 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
3824 : : */
3825 : : S2N_API int s2n_config_get_supported_groups(struct s2n_config *config, uint16_t *groups, uint16_t groups_count_max,
3826 : : uint16_t *groups_count);
3827 : :
3828 : : /* Indicates which serialized connection version will be provided. The default value is
3829 : : * S2N_SERIALIZED_CONN_NONE, which indicates the feature is off.
3830 : : */
3831 : : typedef enum {
3832 : : S2N_SERIALIZED_CONN_NONE = 0,
3833 : : S2N_SERIALIZED_CONN_V1 = 1
3834 : : } s2n_serialization_version;
3835 : :
3836 : : /**
3837 : : * Set what version to use when serializing connections
3838 : : *
3839 : : * A version is required to serialize connections. Versioning ensures that all features negotiated
3840 : : * during the handshake will be available wherever the connection is deserialized. Applications may
3841 : : * need to update this version to pick up new features, since versioning may disable newer TLS
3842 : : * features to ensure compatibility.
3843 : : *
3844 : : * @param config A pointer to the config object.
3845 : : * @param version The requested version.
3846 : : * @returns S2N_SUCCESS on success, S2N_FAILURE on error.
3847 : : */
3848 : : S2N_API int s2n_config_set_serialization_version(struct s2n_config *config, s2n_serialization_version version);
3849 : :
3850 : : /**
3851 : : * Retrieves the length of the serialized connection from `s2n_connection_serialize()`. Should be
3852 : : * used to allocate enough memory for the serialized connection buffer.
3853 : : *
3854 : : * @note The size of the serialized connection changes based on parameters negotiated in the TLS
3855 : : * handshake. Do not expect the size to always remain the same.
3856 : : *
3857 : : * @param conn A pointer to the connection object.
3858 : : * @param length Output parameter where the length will be written.
3859 : : * @returns S2N_SUCCESS on success, S2N_FAILURE on error.
3860 : : */
3861 : : S2N_API int s2n_connection_serialization_length(struct s2n_connection *conn, uint32_t *length);
3862 : :
3863 : : /**
3864 : : * Serializes the s2n_connection into the provided buffer.
3865 : : *
3866 : : * This API takes an established s2n-tls connection object and "serializes" it
3867 : : * into a transferable object to be sent off-box or to another process. This transferable object can
3868 : : * then be "deserialized" using the `s2n_connection_deserialize` method to instantiate an s2n-tls
3869 : : * connection object that can talk to the original peer with the same encryption keys.
3870 : : *
3871 : : * @warning This feature is dangerous because it provides cryptographic material from a TLS session
3872 : : * in plaintext. Users MUST both encrypt and MAC the contents of the outputted material to provide
3873 : : * secrecy and integrity if this material is transported off-box. DO NOT store or send this material off-box
3874 : : * without encryption.
3875 : : *
3876 : : * @note You MUST have used `s2n_config_set_serialization_version()` to set a version on the
3877 : : * s2n_config object associated with this connection before this connection began its TLS handshake.
3878 : : * @note Call `s2n_connection_serialization_length` to retrieve the amount of memory needed for the
3879 : : * buffer parameter.
3880 : : * @note This API will error if the handshake is not yet complete.
3881 : : *
3882 : : * @param conn A pointer to the connection object.
3883 : : * @param buffer A pointer to the buffer where the serialized connection will be written.
3884 : : * @param buffer_length Maximum amount of data that can be written to the buffer param.
3885 : : * @returns S2N_SUCCESS on success, S2N_FAILURE on error.
3886 : : */
3887 : : S2N_API int s2n_connection_serialize(struct s2n_connection *conn, uint8_t *buffer, uint32_t buffer_length);
3888 : :
3889 : : /**
3890 : : * Deserializes the provided buffer into the `s2n_connection` parameter.
3891 : : *
3892 : : * @warning s2n-tls DOES NOT check the integrity of the provided buffer. s2n-tls may successfully
3893 : : * deserialize a corrupted buffer which WILL cause a connection failure when attempting to resume
3894 : : * sending/receiving encrypted data. To avoid this, it is recommended to MAC and encrypt the serialized
3895 : : * connection before sending it off-box and deserializing it.
3896 : : *
3897 : : * @warning Only a minimal amount of information about the original TLS connection is serialized.
3898 : : * Therefore, after deserialization, the connection will behave like a new `s2n_connection` from the
3899 : : * `s2n_connection_new()` call, except that it can read/write encrypted data from a peer. Any desired
3900 : : * config-level or connection-level configuration will need to be re-applied to the deserialized connection.
3901 : : * For this same reason none of the connection getters will return useful information about the
3902 : : * original connection after deserialization. Any information about the original connection needs to
3903 : : * be retrieved before serialization.
3904 : : *
3905 : : * @param conn A pointer to the connection object. Should be a new s2n_connection object.
3906 : : * @param buffer A pointer to the buffer where the serialized connection will be read from.
3907 : : * @param buffer_length Maximum amount of data that can be read from the buffer parameter.
3908 : : * @returns S2N_SUCCESS on success, S2N_FAILURE on error.
3909 : : */
3910 : : S2N_API int s2n_connection_deserialize(struct s2n_connection *conn, uint8_t *buffer, uint32_t buffer_length);
3911 : :
3912 : : /* Load all acceptable certificate authorities from the currently configured trust store.
3913 : : *
3914 : : * The loaded certificate authorities will be advertised during the handshake.
3915 : : * This can help your peer select a certificate if they have multiple certificate
3916 : : * chains available.
3917 : : *
3918 : : * For now, s2n-tls only supports advertising certificate authorities to support
3919 : : * client auth, so only servers will send the list of certificate authorities.
3920 : : *
3921 : : * To avoid configuration mistakes, certificate authorities cannot be loaded from
3922 : : * a trust store that includes the default system certificates. That means that
3923 : : * s2n_config_new_minimal or s2n_config_wipe_trust_store should be used.
3924 : : *
3925 : : * s2n-tls currently limits the total certificate authorities size to 10k bytes.
3926 : : * This method will fail if the certificate authorities retrieved from the trust
3927 : : * store exceed that limit.
3928 : : *
3929 : : * @param config A pointer to the s2n_config object.
3930 : : * @returns S2N_SUCCESS on success. S2N_FAILURE on failure.
3931 : : */
3932 : : S2N_API int s2n_config_set_cert_authorities_from_trust_store(struct s2n_config *config);
3933 : :
3934 : : #ifdef __cplusplus
3935 : : }
3936 : : #endif
|
