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 #pragma once
17 
18 #if ((__GNUC__ >= 4) || defined(__clang__)) && defined(S2N_EXPORTS)
19 #    define S2N_API __attribute__((visibility("default")))
20 #else
21 #    define S2N_API
22 #endif /* __GNUC__ >= 4 || defined(__clang__) */
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 #include <sys/types.h>
29 #include <stdbool.h>
30 #include <stdint.h>
31 #include <stdio.h>
32 #include <sys/uio.h>
33 
34 /* Function return code  */
35 #define S2N_SUCCESS 0
36 #define S2N_FAILURE -1
37 
38 /* Callback return code */
39 #define S2N_CALLBACK_BLOCKED -2
40 
41 #define S2N_MINIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION 2
42 #define S2N_MAXIMUM_SUPPORTED_TLS_RECORD_MAJOR_VERSION 3
43 #define S2N_SSLv2 20
44 #define S2N_SSLv3 30
45 #define S2N_TLS10 31
46 #define S2N_TLS11 32
47 #define S2N_TLS12 33
48 #define S2N_TLS13 34
49 #define S2N_UNKNOWN_PROTOCOL_VERSION 0
50 
51 S2N_API
52 extern __thread int s2n_errno;
53 
54 /**
55  * Returns the address of the thread-local `s2n_errno` variable
56  *
57  * This function can be used instead of trying to resolve `s2n_errno` directly
58  * in runtimes where thread-local variables may not be easily accessible.
59  */
60 S2N_API
61 extern int *s2n_errno_location(void);
62 
63 typedef enum {
64     S2N_ERR_T_OK=0,
65     S2N_ERR_T_IO,
66     S2N_ERR_T_CLOSED,
67     S2N_ERR_T_BLOCKED,
68     S2N_ERR_T_ALERT,
69     S2N_ERR_T_PROTO,
70     S2N_ERR_T_INTERNAL,
71     S2N_ERR_T_USAGE
72 } s2n_error_type;
73 
74 S2N_API
75 extern int s2n_error_get_type(int error);
76 
77 struct s2n_config;
78 struct s2n_connection;
79 
80 /**
81  * Prevents S2N from calling `OPENSSL_crypto_init`/`OPENSSL_cleanup`/`EVP_cleanup` on OpenSSL versions
82  * prior to 1.1.x. This allows applications or languages that also init OpenSSL to interoperate
83  * with S2N.
84  */
85 S2N_API
86 extern int s2n_crypto_disable_init(void);
87 
88 /**
89  * Prevents S2N from installing an atexit handler, which allows safe shutdown of S2N from within a
90  * re-entrant shared library
91  */
92 S2N_API
93 extern int s2n_disable_atexit(void);
94 
95 S2N_API
96 extern unsigned long s2n_get_openssl_version(void);
97 S2N_API
98 extern int s2n_init(void);
99 S2N_API
100 extern int s2n_cleanup(void);
101 S2N_API
102 extern struct s2n_config *s2n_config_new(void);
103 S2N_API
104 extern int s2n_config_free(struct s2n_config *config);
105 S2N_API
106 extern int s2n_config_free_dhparams(struct s2n_config *config);
107 S2N_API
108 extern int s2n_config_free_cert_chain_and_key(struct s2n_config *config);
109 
110 typedef int (*s2n_clock_time_nanoseconds) (void *, uint64_t *);
111 typedef int (*s2n_cache_retrieve_callback) (struct s2n_connection *conn, void *, const void *key, uint64_t key_size, void *value, uint64_t *value_size);
112 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);
113 typedef int (*s2n_cache_delete_callback) (struct s2n_connection *conn,  void *, const void *key, uint64_t key_size);
114 
115 S2N_API
116 extern int s2n_config_set_wall_clock(struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx);
117 S2N_API
118 extern int s2n_config_set_monotonic_clock(struct s2n_config *config, s2n_clock_time_nanoseconds clock_fn, void *ctx);
119 
120 S2N_API
121 extern const char *s2n_strerror(int error, const char *lang);
122 S2N_API
123 extern const char *s2n_strerror_debug(int error, const char *lang);
124 S2N_API
125 extern const char *s2n_strerror_name(int error);
126 
127 struct s2n_stacktrace;
128 S2N_API
129 extern bool s2n_stack_traces_enabled(void);
130 S2N_API
131 extern int s2n_stack_traces_enabled_set(bool newval);
132 S2N_API
133 extern int s2n_calculate_stacktrace(void);
134 S2N_API
135 extern int s2n_print_stacktrace(FILE *fptr);
136 S2N_API
137 extern int s2n_free_stacktrace(void);
138 S2N_API
139 extern int s2n_get_stacktrace(struct s2n_stacktrace *trace);
140 
141 S2N_API
142 extern int s2n_config_set_cache_store_callback(struct s2n_config *config, s2n_cache_store_callback cache_store_callback, void *data);
143 S2N_API
144 extern int s2n_config_set_cache_retrieve_callback(struct s2n_config *config, s2n_cache_retrieve_callback cache_retrieve_callback, void *data);
145 S2N_API
146 extern int s2n_config_set_cache_delete_callback(struct s2n_config *config, s2n_cache_delete_callback cache_delete_callback, void *data);
147 
148 typedef int (*s2n_mem_init_callback)(void);
149 typedef int (*s2n_mem_cleanup_callback)(void);
150 typedef int (*s2n_mem_malloc_callback)(void **ptr, uint32_t requested, uint32_t *allocated);
151 typedef int (*s2n_mem_free_callback)(void *ptr, uint32_t size);
152 
153 S2N_API
154 extern int s2n_mem_set_callbacks(s2n_mem_init_callback mem_init_callback, s2n_mem_cleanup_callback mem_cleanup_callback,
155                                  s2n_mem_malloc_callback mem_malloc_callback, s2n_mem_free_callback mem_free_callback);
156 
157 typedef int (*s2n_rand_init_callback)(void);
158 typedef int (*s2n_rand_cleanup_callback)(void);
159 typedef int (*s2n_rand_seed_callback)(void *data, uint32_t size);
160 typedef int (*s2n_rand_mix_callback)(void *data, uint32_t size);
161 
162 S2N_API
163 extern int s2n_rand_set_callbacks(s2n_rand_init_callback rand_init_callback, s2n_rand_cleanup_callback rand_cleanup_callback,
164         s2n_rand_seed_callback rand_seed_callback, s2n_rand_mix_callback rand_mix_callback);
165 
166 typedef enum {
167     S2N_EXTENSION_SERVER_NAME = 0,
168     S2N_EXTENSION_MAX_FRAG_LEN = 1,
169     S2N_EXTENSION_OCSP_STAPLING = 5,
170     S2N_EXTENSION_SUPPORTED_GROUPS = 10,
171     S2N_EXTENSION_EC_POINT_FORMATS = 11,
172     S2N_EXTENSION_SIGNATURE_ALGORITHMS = 13,
173     S2N_EXTENSION_ALPN = 16,
174     S2N_EXTENSION_CERTIFICATE_TRANSPARENCY = 18,
175     S2N_EXTENSION_RENEGOTIATION_INFO = 65281,
176 } s2n_tls_extension_type;
177 
178 typedef enum {
179     S2N_TLS_MAX_FRAG_LEN_512 = 1,
180     S2N_TLS_MAX_FRAG_LEN_1024 = 2,
181     S2N_TLS_MAX_FRAG_LEN_2048 = 3,
182     S2N_TLS_MAX_FRAG_LEN_4096 = 4,
183 } s2n_max_frag_len;
184 
185 struct s2n_cert;
186 struct s2n_cert_chain_and_key;
187 struct s2n_pkey;
188 typedef struct s2n_pkey s2n_cert_public_key;
189 typedef struct s2n_pkey s2n_cert_private_key;
190 
191 S2N_API
192 extern struct s2n_cert_chain_and_key *s2n_cert_chain_and_key_new(void);
193 S2N_API
194 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);
195 S2N_API
196 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);
197 S2N_API
198 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);
199 S2N_API
200 extern int s2n_cert_chain_and_key_free(struct s2n_cert_chain_and_key *cert_and_key);
201 S2N_API
202 extern int s2n_cert_chain_and_key_set_ctx(struct s2n_cert_chain_and_key *cert_and_key, void *ctx);
203 S2N_API
204 extern void *s2n_cert_chain_and_key_get_ctx(struct s2n_cert_chain_and_key *cert_and_key);
205 S2N_API
206 extern s2n_cert_private_key *s2n_cert_chain_and_key_get_private_key(struct s2n_cert_chain_and_key *cert_and_key);
207 
208 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);
209 S2N_API
210 extern int s2n_config_set_cert_tiebreak_callback(struct s2n_config *config, s2n_cert_tiebreak_callback cert_tiebreak_cb);
211 
212 S2N_API
213 extern int s2n_config_add_cert_chain_and_key(struct s2n_config *config, const char *cert_chain_pem, const char *private_key_pem);
214 S2N_API
215 extern int s2n_config_add_cert_chain_and_key_to_store(struct s2n_config *config, struct s2n_cert_chain_and_key *cert_key_pair);
216 S2N_API
217 extern int s2n_config_set_cert_chain_and_key_defaults(struct s2n_config *config,
218                                                       struct s2n_cert_chain_and_key **cert_key_pairs,
219                                                       uint32_t num_cert_key_pairs);
220 
221 S2N_API
222 extern int s2n_config_set_verification_ca_location(struct s2n_config *config, const char *ca_pem_filename, const char *ca_dir);
223 S2N_API
224 extern int s2n_config_add_pem_to_trust_store(struct s2n_config *config, const char *pem);
225 
226 /**
227  * Clear the trust store.
228  *
229  * Note that the trust store will be initialized with the common locations for
230  * the host operating system by default. To completely override those locations,
231  * call this before functions like `s2n_config_set_verification_ca_location()`
232  * or `s2n_config_add_pem_to_trust_store()`
233  *
234  * @param config The configuration object being updated
235  *
236  * @return 0 on success and -1 on error
237  */
238 S2N_API
239 extern int s2n_config_wipe_trust_store(struct s2n_config *config);
240 
241 typedef uint8_t (*s2n_verify_host_fn) (const char *host_name, size_t host_name_len, void *data);
242 /* will be inherited by s2n_connection. If s2n_connection specifies a callback, that callback will be used for that connection. */
243 S2N_API
244 extern int s2n_config_set_verify_host_callback(struct s2n_config *config, s2n_verify_host_fn, void *data);
245 
246 S2N_API
247 extern int s2n_config_set_check_stapled_ocsp_response(struct s2n_config *config, uint8_t check_ocsp);
248 S2N_API
249 extern int s2n_config_disable_x509_verification(struct s2n_config *config);
250 S2N_API
251 extern int s2n_config_set_max_cert_chain_depth(struct s2n_config *config, uint16_t max_depth);
252 
253 S2N_API
254 extern int s2n_config_add_dhparams(struct s2n_config *config, const char *dhparams_pem);
255 S2N_API
256 extern int s2n_config_set_cipher_preferences(struct s2n_config *config, const char *version);
257 
258 /**
259  * Appends the provided application protocol to the preference list
260  *
261  * The data provided in `protocol` parameter will be copied into an internal buffer
262  *
263  * @param config The configuration object being updated
264  * @param protocol A pointer to a byte array value
265  * @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.
266  */
267 S2N_API
268 extern int s2n_config_append_protocol_preference(struct s2n_config *config, const uint8_t *protocol, uint8_t protocol_len);
269 
270 S2N_API
271 extern int s2n_config_set_protocol_preferences(struct s2n_config *config, const char * const *protocols, int protocol_count);
272 typedef enum { S2N_STATUS_REQUEST_NONE = 0, S2N_STATUS_REQUEST_OCSP = 1 } s2n_status_request_type;
273 S2N_API
274 extern int s2n_config_set_status_request_type(struct s2n_config *config, s2n_status_request_type type);
275 typedef enum { S2N_CT_SUPPORT_NONE = 0, S2N_CT_SUPPORT_REQUEST = 1 } s2n_ct_support_level;
276 S2N_API
277 extern int s2n_config_set_ct_support_level(struct s2n_config *config, s2n_ct_support_level level);
278 typedef enum { S2N_ALERT_FAIL_ON_WARNINGS = 0, S2N_ALERT_IGNORE_WARNINGS = 1 } s2n_alert_behavior;
279 S2N_API
280 extern int s2n_config_set_alert_behavior(struct s2n_config *config, s2n_alert_behavior alert_behavior);
281 S2N_API
282 extern int s2n_config_set_extension_data(struct s2n_config *config, s2n_tls_extension_type type, const uint8_t *data, uint32_t length);
283 S2N_API
284 extern int s2n_config_send_max_fragment_length(struct s2n_config *config, s2n_max_frag_len mfl_code);
285 S2N_API
286 extern int s2n_config_accept_max_fragment_length(struct s2n_config *config);
287 
288 S2N_API
289 extern int s2n_config_set_session_state_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
290 
291 S2N_API
292 extern int s2n_config_set_session_tickets_onoff(struct s2n_config *config, uint8_t enabled);
293 S2N_API
294 extern int s2n_config_set_session_cache_onoff(struct s2n_config *config, uint8_t enabled);
295 S2N_API
296 extern int s2n_config_set_ticket_encrypt_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
297 S2N_API
298 extern int s2n_config_set_ticket_decrypt_key_lifetime(struct s2n_config *config, uint64_t lifetime_in_secs);
299 S2N_API
300 extern int s2n_config_add_ticket_crypto_key(struct s2n_config *config,
301                                             const uint8_t *name, uint32_t name_len,
302                                             uint8_t *key, uint32_t key_len,
303                                             uint64_t intro_time_in_seconds_from_epoch);
304 
305 typedef enum { S2N_SERVER, S2N_CLIENT } s2n_mode;
306 S2N_API
307 extern struct s2n_connection *s2n_connection_new(s2n_mode mode);
308 S2N_API
309 extern int s2n_connection_set_config(struct s2n_connection *conn, struct s2n_config *config);
310 
311 S2N_API
312 extern int s2n_connection_set_ctx(struct s2n_connection *conn, void *ctx);
313 S2N_API
314 extern void *s2n_connection_get_ctx(struct s2n_connection *conn);
315 
316 typedef int s2n_client_hello_fn(struct s2n_connection *conn, void *ctx);
317 typedef enum { S2N_CLIENT_HELLO_CB_BLOCKING, S2N_CLIENT_HELLO_CB_NONBLOCKING } s2n_client_hello_cb_mode;
318 S2N_API
319 extern int s2n_config_set_client_hello_cb(struct s2n_config *config, s2n_client_hello_fn client_hello_callback, void *ctx);
320 S2N_API
321 extern int s2n_config_set_client_hello_cb_mode(struct s2n_config *config, s2n_client_hello_cb_mode cb_mode);
322 S2N_API
323 extern int s2n_client_hello_cb_done(struct s2n_connection *conn);
324 S2N_API
325 extern int s2n_connection_server_name_extension_used(struct s2n_connection *conn);
326 
327 struct s2n_client_hello;
328 S2N_API
329 extern struct s2n_client_hello *s2n_connection_get_client_hello(struct s2n_connection *conn);
330 S2N_API
331 extern ssize_t s2n_client_hello_get_raw_message_length(struct s2n_client_hello *ch);
332 S2N_API
333 extern ssize_t s2n_client_hello_get_raw_message(struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length);
334 S2N_API
335 extern ssize_t s2n_client_hello_get_cipher_suites_length(struct s2n_client_hello *ch);
336 S2N_API
337 extern ssize_t s2n_client_hello_get_cipher_suites(struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length);
338 S2N_API
339 extern ssize_t s2n_client_hello_get_extensions_length(struct s2n_client_hello *ch);
340 S2N_API
341 extern ssize_t s2n_client_hello_get_extensions(struct s2n_client_hello *ch, uint8_t *out, uint32_t max_length);
342 S2N_API
343 extern ssize_t s2n_client_hello_get_extension_length(struct s2n_client_hello *ch, s2n_tls_extension_type extension_type);
344 S2N_API
345 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);
346 S2N_API
347 extern int s2n_client_hello_get_session_id_length(struct s2n_client_hello *ch, uint32_t *out_length);
348 S2N_API
349 extern int s2n_client_hello_get_session_id(struct s2n_client_hello *ch, uint8_t *out, uint32_t *out_length, uint32_t max_length);
350 
351 S2N_API
352 extern int s2n_connection_set_fd(struct s2n_connection *conn, int fd);
353 S2N_API
354 extern int s2n_connection_set_read_fd(struct s2n_connection *conn, int readfd);
355 S2N_API
356 extern int s2n_connection_set_write_fd(struct s2n_connection *conn, int writefd);
357 
358 /**
359   * Gets the assigned file descriptor for the read channel of an s2n connection.
360   *
361   * @param conn A pointer to the s2n connection
362   * @param readfd pointer to place the used file descriptor.
363  */
364 S2N_API
365 extern int s2n_connection_get_read_fd(struct s2n_connection *conn, int *readfd);
366 
367 /**
368   * Gets the assigned file descriptor for the write channel of an s2n connection.
369   *
370   * @param conn A pointer to the s2n connection
371   * @param writefd pointer to place the used file descriptor.
372  */
373 S2N_API
374 extern int s2n_connection_get_write_fd(struct s2n_connection *conn, int *writefd);
375 
376 S2N_API
377 extern int s2n_connection_use_corked_io(struct s2n_connection *conn);
378 
379 typedef int s2n_recv_fn(void *io_context, uint8_t *buf, uint32_t len);
380 typedef int s2n_send_fn(void *io_context, const uint8_t *buf, uint32_t len);
381 S2N_API
382 extern int s2n_connection_set_recv_ctx(struct s2n_connection *conn, void *ctx);
383 S2N_API
384 extern int s2n_connection_set_send_ctx(struct s2n_connection *conn, void *ctx);
385 S2N_API
386 extern int s2n_connection_set_recv_cb(struct s2n_connection *conn, s2n_recv_fn recv);
387 S2N_API
388 extern int s2n_connection_set_send_cb(struct s2n_connection *conn, s2n_send_fn send);
389 
390 S2N_API
391 extern int s2n_connection_prefer_throughput(struct s2n_connection *conn);
392 S2N_API
393 extern int s2n_connection_prefer_low_latency(struct s2n_connection *conn);
394 S2N_API
395 extern int s2n_connection_set_dynamic_record_threshold(struct s2n_connection *conn, uint32_t resize_threshold, uint16_t timeout_threshold);
396 
397 /* If you don't want to use the configuration wide callback, you can set this per connection and it will be honored. */
398 S2N_API
399 extern int s2n_connection_set_verify_host_callback(struct s2n_connection *config, s2n_verify_host_fn host_fn, void *data);
400 
401 typedef enum { S2N_BUILT_IN_BLINDING, S2N_SELF_SERVICE_BLINDING } s2n_blinding;
402 S2N_API
403 extern int s2n_connection_set_blinding(struct s2n_connection *conn, s2n_blinding blinding);
404 S2N_API
405 extern uint64_t s2n_connection_get_delay(struct s2n_connection *conn);
406 
407 S2N_API
408 extern int s2n_connection_set_cipher_preferences(struct s2n_connection *conn, const char *version);
409 
410 /**
411  * Appends the provided application protocol to the preference list
412  *
413  * The data provided in `protocol` parameter will be copied into an internal buffer
414  *
415  * @param conn The connection object being updated
416  * @param protocol A pointer to a slice of bytes
417  * @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.
418  */
419 S2N_API
420 extern int s2n_connection_append_protocol_preference(struct s2n_connection *conn, const uint8_t *protocol, uint8_t protocol_len);
421 
422 S2N_API
423 extern int s2n_connection_set_protocol_preferences(struct s2n_connection *conn, const char * const *protocols, int protocol_count);
424 S2N_API
425 extern int s2n_set_server_name(struct s2n_connection *conn, const char *server_name);
426 S2N_API
427 extern const char *s2n_get_server_name(struct s2n_connection *conn);
428 S2N_API
429 extern const char *s2n_get_application_protocol(struct s2n_connection *conn);
430 S2N_API
431 extern const uint8_t *s2n_connection_get_ocsp_response(struct s2n_connection *conn, uint32_t *length);
432 S2N_API
433 extern const uint8_t *s2n_connection_get_sct_list(struct s2n_connection *conn, uint32_t *length);
434 
435 typedef enum {
436     S2N_NOT_BLOCKED = 0,
437     S2N_BLOCKED_ON_READ,
438     S2N_BLOCKED_ON_WRITE,
439     S2N_BLOCKED_ON_APPLICATION_INPUT,
440     S2N_BLOCKED_ON_EARLY_DATA,
441 } s2n_blocked_status;
442 S2N_API
443 extern int s2n_negotiate(struct s2n_connection *conn, s2n_blocked_status *blocked);
444 S2N_API
445 extern ssize_t s2n_send(struct s2n_connection *conn, const void *buf, ssize_t size, s2n_blocked_status *blocked);
446 S2N_API
447 extern ssize_t s2n_sendv(struct s2n_connection *conn, const struct iovec *bufs, ssize_t count, s2n_blocked_status *blocked);
448 S2N_API
449 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);
450 S2N_API
451 extern ssize_t s2n_recv(struct s2n_connection *conn,  void *buf, ssize_t size, s2n_blocked_status *blocked);
452 S2N_API
453 extern uint32_t s2n_peek(struct s2n_connection *conn);
454 
455 S2N_API
456 extern int s2n_connection_free_handshake(struct s2n_connection *conn);
457 S2N_API
458 extern int s2n_connection_release_buffers(struct s2n_connection *conn);
459 S2N_API
460 extern int s2n_connection_wipe(struct s2n_connection *conn);
461 S2N_API
462 extern int s2n_connection_free(struct s2n_connection *conn);
463 S2N_API
464 extern int s2n_shutdown(struct s2n_connection *conn, s2n_blocked_status *blocked);
465 
466 typedef enum { S2N_CERT_AUTH_NONE, S2N_CERT_AUTH_REQUIRED, S2N_CERT_AUTH_OPTIONAL } s2n_cert_auth_type;
467 
468 S2N_API
469 extern int s2n_config_get_client_auth_type(struct s2n_config *config, s2n_cert_auth_type *client_auth_type);
470 S2N_API
471 extern int s2n_config_set_client_auth_type(struct s2n_config *config, s2n_cert_auth_type client_auth_type);
472 S2N_API
473 extern int s2n_connection_get_client_auth_type(struct s2n_connection *conn, s2n_cert_auth_type *client_auth_type);
474 S2N_API
475 extern int s2n_connection_set_client_auth_type(struct s2n_connection *conn, s2n_cert_auth_type client_auth_type);
476 S2N_API
477 extern int s2n_connection_get_client_cert_chain(struct s2n_connection *conn, uint8_t **der_cert_chain_out, uint32_t *cert_chain_len);
478 
479 /**
480  * Sets the initial number of session tickets to send after a >=TLS1.3 handshake. The default value is one ticket.
481  *
482  * @param config A pointer to the config object.
483  * @param num The number of session tickets that will be sent.
484  */
485 S2N_API
486 extern int s2n_config_set_initial_ticket_count(struct s2n_config *config, uint8_t num);
487 
488 /**
489  * Increases the number of session tickets to send after a >=TLS1.3 handshake.
490  *
491  * @param conn A pointer to the connection object.
492  * @param num The number of additional session tickets to send.
493  */
494 S2N_API
495 extern int s2n_connection_add_new_tickets_to_send(struct s2n_connection *conn, uint8_t num);
496 
497 /**
498  * Returns the number of session tickets issued by the server.
499  *
500  * In TLS1.3, this number can be up to the limit configured by s2n_config_set_initial_ticket_count
501  * and s2n_connection_add_new_tickets_to_send. In earlier versions of TLS, this number will be either 0 or 1.
502  *
503  * This method only works for server connections.
504  *
505  * @param conn A pointer to the connection object.
506  * @param num The number of additional session tickets sent.
507  */
508 S2N_API
509 extern int s2n_connection_get_tickets_sent(struct s2n_connection *conn, uint16_t *num);
510 
511 /**
512  * Sets the keying material lifetime for >=TLS1.3 session tickets so that one session doesn't get re-used ad infinitum.
513  * The default value is one week.
514  *
515  * @param conn A pointer to the connection object.
516  * @param lifetime_in_secs Lifetime of keying material in seconds.
517  */
518 S2N_API
519 extern int s2n_connection_set_server_keying_material_lifetime(struct s2n_connection *conn, uint32_t lifetime_in_secs);
520 
521 struct s2n_session_ticket;
522 
523 /**
524  * Callback function for receiving a session ticket.
525  *
526  * # Safety
527  *
528  * `ctx` is a void pointer and the caller is responsible for ensuring it is cast to the correct type.
529  * `ticket` is valid only within the scope of this callback.
530  *
531  * @param conn A pointer to the connection object.
532  * @param ctx Context for the session ticket callback function.
533  * @param ticket Pointer to the received session ticket object.
534  */
535 typedef int (*s2n_session_ticket_fn)(struct s2n_connection *conn, void *ctx, struct s2n_session_ticket *ticket);
536 
537 /**
538  * Sets a session ticket callback to be called when a client receives a new session ticket.
539  *
540  * # Safety
541  *
542  * `callback` MUST cast `ctx` into the same type of pointer that was originally created.
543  * `ctx` MUST be valid for the lifetime of the config, or until a different context is set.
544  *
545  * @param config A pointer to the config object.
546  * @param callback The function that should be called when the callback is triggered.
547  * @param ctx The context to be passed when the callback is called.
548  */
549 S2N_API
550 extern int s2n_config_set_session_ticket_cb(struct s2n_config *config, s2n_session_ticket_fn callback, void *ctx);
551 
552 /**
553  * Gets the length of the session ticket from a session ticket object.
554  *
555  * @param ticket Pointer to the session ticket object.
556  * @param data_len Pointer to be set to the length of the session ticket on success.
557  */
558 S2N_API
559 extern int s2n_session_ticket_get_data_len(struct s2n_session_ticket *ticket, size_t *data_len);
560 
561 /**
562  * Gets the session ticket data from a session ticket object.
563  *
564  * # Safety
565  * The entire session ticket will be copied into `data` on success. Therefore, `data` MUST have enough
566  * memory to store the session ticket data.
567  *
568  * @param ticket Pointer to the session ticket object.
569  * @param max_data_len Maximum length of data that can be written to the 'data' pointer.
570  * @param data Pointer to where the session ticket data will be stored.
571  */
572 S2N_API
573 extern int s2n_session_ticket_get_data(struct s2n_session_ticket *ticket, size_t max_data_len, uint8_t *data);
574 
575 /**
576  * Gets the lifetime in seconds of the session ticket from a session ticket object.
577  *
578  * @param ticket Pointer to the session ticket object.
579  * @param session_lifetime Pointer to a variable where the lifetime of the session ticket will be stored.
580  */
581 S2N_API
582 extern int s2n_session_ticket_get_lifetime(struct s2n_session_ticket *ticket, uint32_t *session_lifetime);
583 
584 S2N_API
585 extern int s2n_connection_set_session(struct s2n_connection *conn, const uint8_t *session, size_t length);
586 S2N_API
587 extern int s2n_connection_get_session(struct s2n_connection *conn, uint8_t *session, size_t max_length);
588 S2N_API
589 extern int s2n_connection_get_session_ticket_lifetime_hint(struct s2n_connection *conn);
590 S2N_API
591 extern int s2n_connection_get_session_length(struct s2n_connection *conn);
592 S2N_API
593 extern int s2n_connection_get_session_id_length(struct s2n_connection *conn);
594 S2N_API
595 extern int s2n_connection_get_session_id(struct s2n_connection *conn, uint8_t *session_id, size_t max_length);
596 S2N_API
597 extern int s2n_connection_is_session_resumed(struct s2n_connection *conn);
598 S2N_API
599 extern int s2n_connection_is_ocsp_stapled(struct s2n_connection *conn);
600 
601 /* TLS Signature Algorithms - RFC 5246 7.4.1.4.1 */
602 /* https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16 */
603 typedef enum {
604     S2N_TLS_SIGNATURE_ANONYMOUS = 0,
605     S2N_TLS_SIGNATURE_RSA = 1,
606     S2N_TLS_SIGNATURE_ECDSA = 3,
607 
608     /* Use Private Range for RSA PSS since it's not defined there */
609     S2N_TLS_SIGNATURE_RSA_PSS_RSAE = 224,
610     S2N_TLS_SIGNATURE_RSA_PSS_PSS
611 } s2n_tls_signature_algorithm;
612 
613 /* TLS Hash Algorithm - https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1 */
614 /* https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18 */
615 typedef enum {
616     S2N_TLS_HASH_NONE = 0,
617     S2N_TLS_HASH_MD5 = 1,
618     S2N_TLS_HASH_SHA1 = 2,
619     S2N_TLS_HASH_SHA224 = 3,
620     S2N_TLS_HASH_SHA256 = 4,
621     S2N_TLS_HASH_SHA384 = 5,
622     S2N_TLS_HASH_SHA512 = 6,
623 
624     /* Use Private Range for MD5_SHA1 */
625     S2N_TLS_HASH_MD5_SHA1 = 224
626 } s2n_tls_hash_algorithm;
627 
628 S2N_API
629 extern int s2n_connection_get_selected_signature_algorithm(struct s2n_connection *conn, s2n_tls_signature_algorithm *chosen_alg);
630 S2N_API
631 extern int s2n_connection_get_selected_digest_algorithm(struct s2n_connection *conn, s2n_tls_hash_algorithm *chosen_alg);
632 S2N_API
633 extern int s2n_connection_get_selected_client_cert_signature_algorithm(struct s2n_connection *conn, s2n_tls_signature_algorithm *chosen_alg);
634 S2N_API
635 extern int s2n_connection_get_selected_client_cert_digest_algorithm(struct s2n_connection *conn, s2n_tls_hash_algorithm *chosen_alg);
636 
637 S2N_API
638 extern struct s2n_cert_chain_and_key *s2n_connection_get_selected_cert(struct s2n_connection *conn);
639 
640 /**
641  * Returns the length of the s2n certificate chain `chain_and_key`.
642  *
643  * @param chain_and_key A pointer to the s2n_cert_chain_and_key object being read.
644  * @param cert_length This return value represents the length of the s2n certificate chain `chain_and_key`.
645  */
646 S2N_API
647 extern int s2n_cert_chain_get_length(const struct s2n_cert_chain_and_key *chain_and_key, uint32_t *cert_length);
648 
649 /**
650  * Returns the certificate `out_cert` present at the index `cert_idx` of the certificate chain `chain_and_key`.
651  *
652  * Note that the index of the leaf certificate is zero. If the certificate chain `chain_and_key` is NULL or the
653  * certificate index value is not in the acceptable range for the input certificate chain, an error is returned.
654  *
655  * # Safety
656  *
657  * There is no memory allocation required for `out_cert` buffer prior to calling the `s2n_cert_chain_get_cert` API.
658  * The `out_cert` will contain the pointer to the s2n_cert initialized within the input s2n_cert_chain_and_key `chain_and_key`.
659  * The pointer to the output s2n certificate `out_cert` is valid until `chain_and_key` is freed up.
660  * If a caller wishes to persist the `out_cert` beyond the lifetime of `chain_and_key`, the contents would need to be
661  * copied prior to freeing `chain_and_key`.
662  *
663  * @param chain_and_key A pointer to the s2n_cert_chain_and_key object being read.
664  * @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`.
665  * @param cert_idx The certificate index for the requested certificate within the s2n certificate chain.
666  */
667 S2N_API
668 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);
669 
670 /**
671  * Returns the s2n certificate in DER format along with its length.
672  *
673  * The API gets the s2n certificate `cert` in DER format. The certificate is returned in the `out_cert_der` buffer.
674  * Here, `cert_len` represents the length of the certificate.
675  *
676  * A caller can use certificate parsing tools such as the ones provided by OpenSSL to parse the DER encoded certificate chain returned.
677  *
678  * # Safety
679  *
680  * The memory for the `out_cert_der` buffer is allocated and owned by s2n-tls.
681  * Since the size of the certificate can potentially be very large, a pointer to internal connection data is returned instead of
682  * copying the contents into a caller-provided buffer.
683  *
684  * The pointer to the output buffer `out_cert_der` is valid only while the connection exists.
685  * The `s2n_connection_free` API frees the memory associated with the out_cert_der buffer and after the `s2n_connection_wipe` API is
686  * called the memory pointed by out_cert_der is invalid.
687  *
688  * If a caller wishes to persist the `out_cert_der` beyond the lifetime of the connection, the contents would need to be
689  * copied prior to the connection termination.
690  *
691  * @param cert A pointer to the s2n_cert object being read.
692  * @param out_cert_der A pointer to the output buffer which will hold the s2n certificate `cert` in DER format.
693  * @param cert_length This return value represents the length of the certificate.
694  */
695 S2N_API
696 extern int s2n_cert_get_der(const struct s2n_cert *cert, const uint8_t **out_cert_der, uint32_t *cert_length);
697 
698 /**
699  * Returns the validated peer certificate chain as a `s2n_cert_chain_and_key` opaque object.
700  *
701  * The `s2n_cert_chain_and_key` parameter must be allocated by the caller using the `s2n_cert_chain_and_key_new` API
702  * prior to this function call and must be empty. To free the memory associated with the `s2n_cert_chain_and_key` object use the
703  * `s2n_cert_chain_and_key_free` API.
704  *
705  * @param conn A pointer to the s2n_connection object being read.
706  * @param s2n_cert_chain_and_key The returned validated peer certificate chain `cert_chain` retrieved from the s2n connection.
707  */
708 S2N_API
709 extern int s2n_connection_get_peer_cert_chain(const struct s2n_connection *conn, struct s2n_cert_chain_and_key *cert_chain);
710 
711 /**
712  * Returns the length of the DER encoded extension value of the ASN.1 X.509 certificate extension.
713  *
714  * @param cert A pointer to the s2n_cert object being read.
715  * @param oid A null-terminated cstring that contains the OID of the X.509 certificate extension to be read.
716  * @param ext_value_len This return value contains the length of DER encoded extension value of the ASN.1 X.509 certificate extension.
717  */
718 S2N_API
719 extern int s2n_cert_get_x509_extension_value_length(struct s2n_cert *cert, const uint8_t *oid, uint32_t *ext_value_len);
720 
721 /**
722  * Returns the DER encoding of an ASN.1 X.509 certificate extension value, it's length and a boolean critical.
723  *
724  * @param cert A pointer to the s2n_cert object being read.
725  * @param oid A null-terminated cstring that contains the OID of the X.509 certificate extension to be read.
726  * @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.
727  * @param ext_value_len  This value is both an input and output parameter and represents the length of the output buffer `ext_value`.
728  * When used as an input parameter, the caller must use this parameter to convey the maximum length of `ext_value`.
729  * 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.
730  * @param critical This return value contains the boolean value for `critical`.
731  */
732 S2N_API
733 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);
734 
735 /**
736  * Returns the UTF8 String length of the ASN.1 X.509 certificate extension data.
737  *
738  * @param extension_data A pointer to the DER encoded ASN.1 X.509 certificate extension value being read.
739  * @param extension_len represents the length of the input buffer `extension_data`.
740  * @param utf8_str_len This return value contains the UTF8 String length of the ASN.1 X.509 certificate extension data.
741  */
742 S2N_API
743 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);
744 
745 /**
746  * Returns the UTF8 String representation of the DER encoded ASN.1 X.509 certificate extension data.
747  *
748  * @param extension_data A pointer to the DER encoded ASN.1 X.509 certificate extension value being read.
749  * @param extension_len represents the length of the input buffer `extension_data`.
750  * @param out_data A pointer to the output buffer which will hold the UTF8 String representation of the DER encoded ASN.1 X.509
751  * certificate extension data returned.
752  * @param out_len This value is both an input and output parameter and represents the length of the output buffer `out_data`.
753  * When used as an input parameter, the caller must use this parameter to convey the maximum length of `out_data`.
754  * When used as an output parameter, `out_len` holds the actual length of UTF8 String returned.
755  */
756 S2N_API
757 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);
758 
759 /* Pre-shared key (PSK) Hash Algorithm - RFC 8446 Section-2.2 */
760 typedef enum {
761     S2N_PSK_HMAC_SHA256,
762     S2N_PSK_HMAC_SHA384,
763 } s2n_psk_hmac;
764 
765 struct s2n_psk;
766 
767 /**
768  * Creates a new s2n external pre-shared key (PSK) object with `S2N_PSK_HMAC_SHA256` as the default
769  * PSK hash algorithm. An external PSK is a key established outside of TLS using a secure mutually agreed upon mechanism.
770  *
771  * Use `s2n_psk_free` to free the memory allocated to the s2n external PSK object created by this API.
772  *
773  * @return struct s2n_psk* Returns a pointer to the newly created external PSK object.
774  */
775 S2N_API
776 struct s2n_psk* s2n_external_psk_new(void);
777 
778 /**
779  * Frees the memory associated with the external PSK object.
780  *
781  * @param psk Pointer to the PSK object to be freed.
782  */
783 S2N_API
784 int s2n_psk_free(struct s2n_psk **psk);
785 
786 /**
787  * Sets the identity for a given external PSK object.
788  * The identity is a unique identifier for the pre-shared secret.
789  * It is a non-secret value represented by raw bytes.
790  *
791  * # Safety
792  *
793  * The identity is transmitted over the network unencrypted and is a non-secret value.
794  * Do not include confidential information in the identity.
795  *
796  * Note that the identity is copied into s2n-tls memory and the caller is responsible for
797  * freeing the memory associated with the identity input.
798  *
799  * @param psk A pointer to a PSK object to be updated with the identity.
800  * @param identity The identity in raw bytes format to be copied.
801  * @param identity_size The length of the PSK identity being set.
802  */
803 S2N_API
804 int s2n_psk_set_identity(struct s2n_psk *psk, const uint8_t *identity, uint16_t identity_size);
805 
806 /**
807  * Sets the out-of-band/externally provisioned secret for a given external PSK object.
808  *
809  * # Safety
810  *
811  * Note that the secret is copied into s2n-tls memory and the caller is responsible for
812  * freeing the memory associated with the `secret` input.
813  *
814  * Deriving a shared secret from a password or other low-entropy source
815  * is not secure and is subject to dictionary attacks.
816  * See https://tools.ietf.org/rfc/rfc8446#section-2.2 for more information.
817  *
818  * @param psk A pointer to a PSK object to be updated with the secret.
819  * @param secret The secret in raw bytes format to be copied.
820  * @param secret_size The length of the pre-shared secret being set.
821  */
822 S2N_API
823 int s2n_psk_set_secret(struct s2n_psk *psk, const uint8_t *secret, uint16_t secret_size);
824 
825 /**
826  * Sets the hash algorithm for a given external PSK object. The supported PSK hash
827  * algorithms are as listed in the enum `s2n_psk_hmac` above.
828  *
829  * @param psk A pointer to the external PSK object to be updated with the PSK hash algorithm.
830  * @param hmac The PSK hash algorithm being set.
831  */
832 S2N_API
833 int s2n_psk_set_hmac(struct s2n_psk *psk, s2n_psk_hmac hmac);
834 
835 /**
836  * Appends a PSK object to the list of PSKs supported by the s2n connection.
837  * If a PSK with a duplicate identity is found, an error is returned and the PSK is not added to the list.
838  * Note that a copy of `psk` is stored on the connection. The user is still responsible for freeing the
839  * memory associated with `psk`.
840  *
841  * @param conn A pointer to the s2n_connection object that contains the list of PSKs supported.
842  * @param psk A pointer to the `s2n_psk` object to be appended to the list of PSKs on the s2n connection.
843  */
844 S2N_API
845 int s2n_connection_append_psk(struct s2n_connection *conn, struct s2n_psk *psk);
846 
847 /**
848  * The list of PSK modes supported by s2n-tls for TLS versions >= TLS1.3.
849  * Currently s2n-tls supports two modes - `S2N_PSK_MODE_RESUMPTION`, which represents the PSKs established
850  * using the previous connection via session resumption, and `S2N_PSK_MODE_EXTERNAL`, which represents PSKs
851  * established out-of-band/externally using a secure mutually agreed upon mechanism.
852  */
853 typedef enum {
854     S2N_PSK_MODE_RESUMPTION,
855     S2N_PSK_MODE_EXTERNAL
856 } s2n_psk_mode;
857 
858 /**
859  * Sets the PSK mode on the s2n config object.
860  * The supported PSK modes are listed in the enum `s2n_psk_mode` above.
861  *
862  * @param config A pointer to the s2n_config object being updated.
863  * @param mode The PSK mode to be set.
864  */
865 S2N_API
866 int s2n_config_set_psk_mode(struct s2n_config *config, s2n_psk_mode mode);
867 
868 /**
869  * Sets the PSK mode on the s2n connection object.
870  * The supported PSK modes are listed in the enum `s2n_psk_mode` above.
871  * This API overrides the PSK mode set on config for this connection.
872  *
873  * @param conn A pointer to the s2n_connection object being updated.
874  * @param mode The PSK mode to be set.
875  */
876 S2N_API
877 int s2n_connection_set_psk_mode(struct s2n_connection *conn, s2n_psk_mode mode);
878 
879 /**
880  * Gets the negotiated PSK identity length from the s2n connection object. The negotiated PSK
881  * refers to the chosen PSK by the server to be used for the connection.
882  *
883  * This API can be used to determine if the negotiated PSK exists. If negotiated PSK exists a
884  * call to this API returns a value greater than zero. If the negotiated PSK does not exist, the
885  * value `0` is returned.
886  *
887  * @param conn A pointer to the s2n_connection object that successfully negotiated a PSK connection.
888  * @param identity_length The length of the negotiated PSK identity.
889  */
890 S2N_API
891 int s2n_connection_get_negotiated_psk_identity_length(struct s2n_connection *conn, uint16_t *identity_length);
892 
893 /**
894  * Gets the negotiated PSK identity from the s2n connection object.
895  * If the negotiated PSK does not exist, the PSK identity will not be obtained and no error will be returned.
896  * Prior to this API call, use `s2n_connection_get_negotiated_psk_identity_length` to determine if a
897  * negotiated PSK exists or not.
898  *
899  * # Safety
900  *
901  * The negotiated PSK identity will be copied into the identity buffer on success.
902  * Therefore, the identity buffer must have enough memory to fit the identity length.
903  *
904  * @param conn A pointer to the s2n_connection object.
905  * @param identity The negotiated PSK identity obtained from the s2n_connection object.
906  * @param max_identity_length The maximum length for the PSK identity. If the negotiated psk_identity length is
907  * greater than this `max_identity_length` value an error will be returned.
908  */
909 S2N_API
910 int s2n_connection_get_negotiated_psk_identity(struct s2n_connection *conn, uint8_t *identity, uint16_t max_identity_length);
911 
912 struct s2n_offered_psk;
913 
914 /**
915  * Creates a new s2n offered PSK object.
916  * An offered PSK object represents a single PSK sent by the client.
917  *
918  * # Safety
919  *
920  * Use `s2n_offered_psk_free` to free the memory allocated to the s2n offered PSK object created by this API.
921  *
922  * @return struct s2n_offered_psk* Returns a pointer to the newly created offered PSK object.
923  */
924 S2N_API
925 struct s2n_offered_psk* s2n_offered_psk_new(void);
926 
927 /**
928  * Frees the memory associated with the `s2n_offered_psk` object.
929  *
930  * @param psk A pointer to the `s2n_offered_psk` object to be freed.
931  */
932 S2N_API
933 int s2n_offered_psk_free(struct s2n_offered_psk **psk);
934 
935 /**
936  * Gets the PSK identity and PSK identity length for a given offered PSK object.
937  *
938  * @param psk A pointer to the offered PSK object being read.
939  * @param identity The PSK identity being obtained.
940  * @param size The length of the PSK identity being obtained.
941  */
942 S2N_API
943 int s2n_offered_psk_get_identity(struct s2n_offered_psk *psk, uint8_t** identity, uint16_t *size);
944 
945 struct s2n_offered_psk_list;
946 
947 /**
948  * Checks whether the offered PSK list has an offered psk object next in line in the list.
949  * An offered PSK list contains all the PSKs offered by the client for the server to select.
950  *
951  * # Safety
952  *
953  * This API returns a pointer to the s2n-tls internal memory with limited lifetime.
954  * After the completion of `s2n_psk_selection_callback` this pointer is invalid.
955  *
956  * @param psk_list A pointer to the offered PSK list being read.
957  * @return bool A boolean value representing whether an offered psk object is present next in line in the offered PSK list.
958  */
959 S2N_API
960 bool s2n_offered_psk_list_has_next(struct s2n_offered_psk_list *psk_list);
961 
962 /**
963  * Obtains the next offered PSK object from the list of offered PSKs. Use `s2n_offered_psk_list_has_next`
964  * prior to this API call to ensure we have not reached the end of the list.
965  *
966  * @param psk_list A pointer to the offered PSK list being read.
967  * @param psk A pointer to the next offered PSK object being obtained.
968  */
969 S2N_API
970 int s2n_offered_psk_list_next(struct s2n_offered_psk_list *psk_list, struct s2n_offered_psk *psk);
971 
972 /**
973  * Returns the offered PSK list to its original read state.
974  *
975  * When `s2n_offered_psk_list_reread` is called, `s2n_offered_psk_list_next` will return the first PSK
976  * in the offered PSK list.
977  *
978  * @param psk_list A pointer to the offered PSK list being reread.
979  */
980 S2N_API
981 int s2n_offered_psk_list_reread(struct s2n_offered_psk_list *psk_list);
982 
983 /**
984  * Chooses a PSK from the offered PSK list to be used for the connection.
985  * This API matches the PSK identity received from the client against the server's known PSK identities
986  * list, in order to choose the PSK to be used for the connection. If the PSK identity sent from the client
987  * is NULL, no PSK is chosen for the connection. If the client offered PSK identity has no matching PSK identity
988  * with the server, an error will be returned. Use this API along with the `s2n_psk_selection_callback` callback
989  * to select a PSK identity.
990  *
991  * @param psk_list A pointer to the server's known PSK list used to compare for a matching PSK with the client.
992  * @param psk A pointer to the client's PSK object used to compare with the server's known PSK identities.
993  */
994 S2N_API int s2n_offered_psk_list_choose_psk(struct s2n_offered_psk_list *psk_list, struct s2n_offered_psk *psk);
995 
996 /**
997  * Callback function to select a PSK from a list of offered PSKs.
998  * Use this callback to implement custom PSK selection logic. The s2n-tls default PSK selection logic
999  * chooses the first matching PSK from the list of offered PSKs sent by the client.
1000  *
1001  * # Safety
1002  *
1003  * `context` is a void pointer and the caller is responsible for ensuring it is cast to the correct type.
1004  * After the completion of this callback, the pointer to `psk_list` is invalid.
1005  *
1006  * @param conn A pointer to the s2n_connection object.
1007  * @param context A pointer to a context for the caller to pass state to the callback, if needed.
1008  * @param psk_list A pointer to the offered PSK list being read.
1009  */
1010 typedef int (*s2n_psk_selection_callback)(struct s2n_connection *conn, void *context,
1011                                           struct s2n_offered_psk_list *psk_list);
1012 
1013 /**
1014  * Sets the callback to select the matching PSK.
1015  * If this callback is not set s2n-tls uses a default PSK selection logic that selects the first matching
1016  * server PSK.
1017  *
1018  * @param config A pointer to the s2n_config object.
1019  * @param cb The function that should be called when the callback is triggered.
1020  * @param context A pointer to a context for the caller to pass state to the callback, if needed.
1021  */
1022 S2N_API
1023 int s2n_config_set_psk_selection_callback(struct s2n_config *config, s2n_psk_selection_callback cb, void *context);
1024 
1025 S2N_API
1026 extern uint64_t s2n_connection_get_wire_bytes_in(struct s2n_connection *conn);
1027 S2N_API
1028 extern uint64_t s2n_connection_get_wire_bytes_out(struct s2n_connection *conn);
1029 S2N_API
1030 extern int s2n_connection_get_client_protocol_version(struct s2n_connection *conn);
1031 S2N_API
1032 extern int s2n_connection_get_server_protocol_version(struct s2n_connection *conn);
1033 S2N_API
1034 extern int s2n_connection_get_actual_protocol_version(struct s2n_connection *conn);
1035 S2N_API
1036 extern int s2n_connection_get_client_hello_version(struct s2n_connection *conn);
1037 S2N_API
1038 extern int s2n_connection_client_cert_used(struct s2n_connection *conn);
1039 S2N_API
1040 extern const char *s2n_connection_get_cipher(struct s2n_connection *conn);
1041 
1042 /**
1043  * Returns the IANA value for the connection's negotiated cipher suite.
1044  *
1045  * The value is returned in the form of `first,second`, in order to closely match
1046  * the values defined in the [IANA Registry](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#table-tls-parameters-4).
1047  * For example if the connection's negotiated cipher suite is `TLS_AES_128_GCM_SHA256`,
1048  * which is registered as `0x13,0x01`, then `first = 0x13` and `second = 0x01`.
1049  *
1050  * This method will only succeed after the cipher suite has been negotiated with the peer.
1051  *
1052  * @param conn A pointer to the connection being read
1053  * @param first A pointer to a single byte, which will be updated with the first byte in the registered IANA value.
1054  * @param second A pointer to a single byte, which will be updated with the second byte in the registered IANA value.
1055  * @return A POSIX error signal. If an error was returned, the values contained in `first` and `second` should be considered invalid.
1056  */
1057 S2N_API
1058 extern int s2n_connection_get_cipher_iana_value(struct s2n_connection *conn, uint8_t *first, uint8_t *second);
1059 
1060 S2N_API
1061 extern int s2n_connection_is_valid_for_cipher_preferences(struct s2n_connection *conn, const char *version);
1062 S2N_API
1063 extern const char *s2n_connection_get_curve(struct s2n_connection *conn);
1064 S2N_API
1065 extern const char *s2n_connection_get_kem_name(struct s2n_connection *conn);
1066 S2N_API
1067 extern const char *s2n_connection_get_kem_group_name(struct s2n_connection *conn);
1068 S2N_API
1069 extern int s2n_connection_get_alert(struct s2n_connection *conn);
1070 S2N_API
1071 extern const char *s2n_connection_get_handshake_type_name(struct s2n_connection *conn);
1072 S2N_API
1073 extern const char *s2n_connection_get_last_message_name(struct s2n_connection *conn);
1074 
1075 struct s2n_async_pkey_op;
1076 typedef enum { S2N_ASYNC_PKEY_VALIDATION_FAST, S2N_ASYNC_PKEY_VALIDATION_STRICT } s2n_async_pkey_validation_mode;
1077 typedef enum { S2N_ASYNC_DECRYPT, S2N_ASYNC_SIGN } s2n_async_pkey_op_type;
1078 
1079 typedef int (*s2n_async_pkey_fn)(struct s2n_connection *conn, struct s2n_async_pkey_op *op);
1080 S2N_API
1081 extern int s2n_config_set_async_pkey_callback(struct s2n_config *config, s2n_async_pkey_fn fn);
1082 S2N_API
1083 extern int s2n_async_pkey_op_perform(struct s2n_async_pkey_op *op, s2n_cert_private_key *key);
1084 S2N_API
1085 extern int s2n_async_pkey_op_apply(struct s2n_async_pkey_op *op, struct s2n_connection *conn);
1086 S2N_API
1087 extern int s2n_async_pkey_op_free(struct s2n_async_pkey_op *op);
1088 S2N_API
1089 extern int s2n_config_set_async_pkey_validation_mode(struct s2n_config *config, s2n_async_pkey_validation_mode mode);
1090 
1091 S2N_API
1092 extern int s2n_async_pkey_op_get_op_type(struct s2n_async_pkey_op *op, s2n_async_pkey_op_type *type);
1093 S2N_API
1094 extern int s2n_async_pkey_op_get_input_size(struct s2n_async_pkey_op *op, uint32_t *data_len);
1095 S2N_API
1096 extern int s2n_async_pkey_op_get_input(struct s2n_async_pkey_op *op, uint8_t *data, uint32_t data_len);
1097 S2N_API
1098 extern int s2n_async_pkey_op_set_output(struct s2n_async_pkey_op *op, const uint8_t *data, uint32_t data_len);
1099 
1100 /**
1101  * Callback function for handling key log events
1102  *
1103  * THIS SHOULD BE USED FOR DEBUGGING PURPOSES ONLY!
1104  *
1105  * Each log line is formatted with the
1106  * [NSS Key Log Format](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)
1107  * without a newline.
1108  *
1109  * # Safety
1110  *
1111  * * `ctx` MUST be cast into the same type of pointer that was originally created
1112  * * `logline` bytes MUST be copied or discarded before this function returns
1113  *
1114  * @param ctx Context for the callback
1115  * @param conn Connection for which the log line is being emitted
1116  * @param logline Pointer to the log line data
1117  * @param len Length of the log line data
1118  */
1119 typedef int (*s2n_key_log_fn)(void *ctx, struct s2n_connection *conn, uint8_t *logline, size_t len);
1120 
1121 /**
1122  * Sets a key logging callback on the provided config
1123  *
1124  * THIS SHOULD BE USED FOR DEBUGGING PURPOSES ONLY!
1125  *
1126  * Setting this function enables configurations to emit secrets in the
1127  * [NSS Key Log Format](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format)
1128  *
1129  * # Safety
1130  *
1131  * * `callback` MUST cast `ctx` into the same type of pointer that was originally created
1132  * * `ctx` MUST live for at least as long as it is set on the config
1133  *
1134  * @param config Config to set the callback
1135  * @param callback The function that should be called for each secret log entry
1136  * @param ctx The context to be passed when the callback is called
1137  */
1138 S2N_API
1139 extern int s2n_config_set_key_log_cb(struct s2n_config *config, s2n_key_log_fn callback, void *ctx);
1140 
1141 /* s2n_config_enable_cert_req_dss_legacy_compat adds a dss cert type in the server certificate request when being called.
1142  * It only sends the dss cert type in the cert request but does not succeed the handshake if a dss cert is received.
1143  * Please DO NOT call this api unless you know you actually need legacy DSS certificate type compatibility
1144  */
1145 S2N_API
1146 extern int s2n_config_enable_cert_req_dss_legacy_compat(struct s2n_config *config);
1147 
1148 /**
1149  * Sets the maximum bytes of early data the server will accept.
1150  *
1151  * The default maximum is 0. If the maximum is 0, the server rejects all early data requests.
1152  * The config maximum can be overridden by the connection maximum or the maximum on an external pre-shared key.
1153  *
1154  * @param config A pointer to the config
1155  * @param max_early_data_size The maximum early data that the server will accept
1156  * @return A POSIX error signal. If successful, the maximum early data size was updated.
1157  */
1158 S2N_API int s2n_config_set_server_max_early_data_size(struct s2n_config *config, uint32_t max_early_data_size);
1159 
1160 /**
1161  * Sets the maximum bytes of early data the server will accept.
1162  *
1163  * The default maximum is 0. If the maximum is 0, the server rejects all early data requests.
1164  * The connection maximum can be overridden by the maximum on an external pre-shared key.
1165  *
1166  * @param conn A pointer to the connection
1167  * @param max_early_data_size The maximum early data the server will accept
1168  * @return A POSIX error signal. If successful, the maximum early data size was updated.
1169  */
1170 S2N_API int s2n_connection_set_server_max_early_data_size(struct s2n_connection *conn, uint32_t max_early_data_size);
1171 
1172 /**
1173  * Sets the user context associated with early data on a server.
1174  *
1175  * This context is passed to the `s2n_early_data_cb` callback to help decide whether to accept or reject early data.
1176  *
1177  * Unlike most contexts, the early data context is a byte buffer instead of a void pointer.
1178  * This is because we need to serialize the context into session tickets.
1179  *
1180  * This API is intended for use with session resumption, and will not affect pre-shared keys.
1181  *
1182  * @param conn A pointer to the connection
1183  * @param context A pointer to the user context data. This data will be copied.
1184  * @param context_size The size of the data to read from the `context` pointer.
1185  * @return A POSIX error signal. If successful, the context was updated.
1186  */
1187 S2N_API int s2n_connection_set_server_early_data_context(struct s2n_connection *conn, const uint8_t *context, uint16_t context_size);
1188 
1189 /**
1190  * Configures a particular pre-shared key to allow early data.
1191  *
1192  * `max_early_data_size` must be set to the maximum early data accepted by the server.
1193  *
1194  * In order to use early data, the cipher suite set on the pre-shared key must match the cipher suite
1195  * ultimately negotiated by the TLS handshake. Additionally, the cipher suite must have the same
1196  * hmac algorithm as the pre-shared key.
1197  *
1198  * @param psk A pointer to the pre-shared key, created with `s2n_external_psk_new`.
1199  * @param max_early_data_size The maximum early data that can be sent or received using this key.
1200  * @param cipher_suite_first_byte The first byte in the registered IANA value of the associated cipher suite.
1201  * @param cipher_suite_second_byte The second byte in the registered IANA value of the associated cipher suite.
1202  * @return A POSIX error signal. If successful, `psk` was updated.
1203  */
1204 S2N_API int s2n_psk_configure_early_data(struct s2n_psk *psk, uint32_t max_early_data_size,
1205         uint8_t cipher_suite_first_byte, uint8_t cipher_suite_second_byte);
1206 
1207 /**
1208  * Sets the optional `application_protocol` associated with the given pre-shared key.
1209  *
1210  * In order to use early data, the `application_protocol` set on the pre-shared key must match
1211  * the `application_protocol` ultimately negotiated by the TLS handshake.
1212  *
1213  * @param psk A pointer to the pre-shared key, created with `s2n_external_psk_new`.
1214  * @param application_protocol A pointer to the associated application protocol data. This data will be copied.
1215  * @param size The size of the data to read from the `application_protocol` pointer.
1216  * @return A POSIX error signal. If successful, the application protocol was set.
1217  */
1218 S2N_API int s2n_psk_set_application_protocol(struct s2n_psk *psk, const uint8_t *application_protocol, uint8_t size);
1219 
1220 /**
1221  * Sets the optional user early data context associated with the given pre-shared key.
1222  *
1223  * The early data context is passed to the `s2n_early_data_cb` callback to help decide whether
1224  * to accept or reject early data.
1225  *
1226  * @param psk A pointer to the pre-shared key, created with `s2n_external_psk_new`.
1227  * @param context A pointer to the associated user context data. This data will be copied.
1228  * @param size The size of the data to read from the `context` pointer.
1229  * @return A POSIX error signal. If successful, the context was set.
1230  */
1231 S2N_API int s2n_psk_set_early_data_context(struct s2n_psk *psk, const uint8_t *context, uint16_t size);
1232 
1233 /* The status of early data on a connection.
1234  *
1235  * S2N_EARLY_DATA_STATUS_OK: Early data is in progress.
1236  * S2N_EARLY_DATA_STATUS_NOT_REQUESTED: The client did not request early data, so none was sent or received.
1237  * S2N_EARLY_DATA_STATUS_REJECTED: The client requested early data, but the server rejected the request.
1238  *                                 Early data may have been sent, but was not received.
1239  * S2N_EARLY_DATA_STATUS_END: All early data was successfully sent and received.
1240  */
1241 typedef enum {
1242     S2N_EARLY_DATA_STATUS_OK,
1243     S2N_EARLY_DATA_STATUS_NOT_REQUESTED,
1244     S2N_EARLY_DATA_STATUS_REJECTED,
1245     S2N_EARLY_DATA_STATUS_END,
1246 } s2n_early_data_status_t;
1247 
1248 /**
1249  * Reports the current state of early data for a connection.
1250  *
1251  * See `s2n_early_data_status_t` for all possible states.
1252  *
1253  * @param conn A pointer to the connection
1254  * @param status A pointer which will be set to the current early data status
1255  * @return A POSIX error signal.
1256  */
1257 S2N_API int s2n_connection_get_early_data_status(struct s2n_connection *conn, s2n_early_data_status_t *status);
1258 
1259 /**
1260  * Reports the remaining size of the early data allowed by a connection.
1261  *
1262  * If early data was rejected or not requested, the remaining early data size is 0.
1263  * Otherwise, the remaining early data size is the maximum early data allowed by the connection,
1264  * minus the early data sent or received so far.
1265  *
1266  * @param conn A pointer to the connection
1267  * @param allowed_early_data_size A pointer which will be set to the remaining early data currently allowed by `conn`
1268  * @return A POSIX error signal.
1269  */
1270 S2N_API int s2n_connection_get_remaining_early_data_size(struct s2n_connection *conn, uint32_t *allowed_early_data_size);
1271 
1272 /**
1273  * Reports the maximum size of the early data allowed by a connection.
1274  *
1275  * This is the maximum amount of early data that can ever be sent and received for a connection.
1276  * It is not affected by the actual status of the early data, so can be non-zero even if early data
1277  * is rejected or not requested.
1278  *
1279  * @param conn A pointer to the connection
1280  * @param max_early_data_size A pointer which will be set to the maximum early data allowed by `conn`
1281  * @return A POSIX error signal.
1282  */
1283 S2N_API int s2n_connection_get_max_early_data_size(struct s2n_connection *conn, uint32_t *max_early_data_size);
1284 
1285 /**
1286  * Called by the client to begin negotiation and send early data.
1287  *
1288  * See https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#using-early-data--0rtt
1289  * for usage and examples. DO NOT USE unless you have considered the security issues and
1290  * implemented mitigation for anti-replay attacks.
1291  *
1292  * @param conn A pointer to the connection
1293  * @param data A pointer to the early data to be sent
1294  * @param data_len The size of the early data to send
1295  * @param data_sent A pointer which will be set to the size of the early data sent
1296  * @param blocked A pointer which will be set to the blocked status, as in `s2n_negotiate`.
1297  * @return A POSIX error signal. The error should be handled as in `s2n_negotiate`.
1298  */
1299 S2N_API int s2n_send_early_data(struct s2n_connection *conn, const uint8_t *data, ssize_t data_len,
1300         ssize_t *data_sent, s2n_blocked_status *blocked);
1301 
1302 /**
1303  * Called by the server to begin negotiation and accept any early data the client sends.
1304  *
1305  * See https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#using-early-data--0rtt
1306  * for usage and examples. DO NOT USE unless you have considered the security issues and
1307  * implemented mitigation for anti-replay attacks.
1308  *
1309  * @param conn A pointer to the connection
1310  * @param data A pointer to a buffer to store the early data received
1311  * @param max_data_len The size of the early data buffer
1312  * @param data_received A pointer which will be set to the size of the early data received
1313  * @param blocked A pointer which will be set to the blocked status, as in `s2n_negotiate`.
1314  * @return A POSIX error signal. The error should be handled as in `s2n_negotiate`.
1315  */
1316 S2N_API int s2n_recv_early_data(struct s2n_connection *conn, uint8_t *data, ssize_t max_data_len,
1317         ssize_t *data_received, s2n_blocked_status *blocked);
1318 
1319 struct s2n_offered_early_data;
1320 
1321 /**
1322  * A callback which can be implemented to accept or reject early data.
1323  *
1324  * This callback is triggered only after the server has determined early data is otherwise acceptable according
1325  * to the TLS early data specification. Implementations therefore only need to cover application-specific checks,
1326  * not the standard TLS early data validation.
1327  *
1328  * This callback can be synchronous or asynchronous. For asynchronous behavior, return success without
1329  * calling `s2n_offered_early_data_reject` or `s2n_offered_early_data_accept`. `early_data` will
1330  * still be a valid reference, and the connection will block until `s2n_offered_early_data_reject` or
1331  * `s2n_offered_early_data_accept` is called.
1332  *
1333  * @param conn A pointer to the connection
1334  * @param early_data A pointer which can be used to access information about the proposed early data
1335  *                   and then accept or reject it.
1336  * @return A POSIX error signal. If unsuccessful, the connection will be closed with an error.
1337  */
1338 typedef int (*s2n_early_data_cb)(struct s2n_connection *conn, struct s2n_offered_early_data *early_data);
1339 
1340 /**
1341  * Set a callback to accept or reject early data.
1342  *
1343  * @param conn A pointer to the connection
1344  * @param cb A pointer to the implementation of the callback.
1345  * @return A POSIX error signal. If successful, the callback was set.
1346  */
1347 S2N_API int s2n_config_set_early_data_cb(struct s2n_config *config, s2n_early_data_cb cb);
1348 
1349 /**
1350  * Get the length of the early data context set by the user.
1351  *
1352  * @param early_data A pointer to the early data information
1353  * @param context_len The length of the user context
1354  * @return A POSIX error signal.
1355  */
1356 S2N_API int s2n_offered_early_data_get_context_length(struct s2n_offered_early_data *early_data, uint16_t *context_len);
1357 
1358 /**
1359  * Get the early data context set by the user.
1360  *
1361  * @param early_data A pointer to the early data information
1362  * @param context A byte buffer to copy the user context into
1363  * @param max_len The size of `context`. Must be >= to the result of `s2n_offered_early_data_get_context_length`.
1364  * @return A POSIX error signal.
1365  */
1366 S2N_API int s2n_offered_early_data_get_context(struct s2n_offered_early_data *early_data, uint8_t *context, uint16_t max_len);
1367 
1368 /**
1369  * Reject early data offered by the client.
1370  *
1371  * @param early_data A pointer to the early data information
1372  * @return A POSIX error signal. If success, the client's early data will be rejected.
1373  */
1374 S2N_API int s2n_offered_early_data_reject(struct s2n_offered_early_data *early_data);
1375 
1376 /**
1377  * Accept early data offered by the client.
1378  *
1379  * @param early_data A pointer to the early data information
1380  * @return A POSIX error signal. If success, the client's early data will be accepted.
1381  */
1382 S2N_API int s2n_offered_early_data_accept(struct s2n_offered_early_data *early_data);
1383 
1384 #ifdef __cplusplus
1385 }
1386 #endif
1387