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