1/* $OpenBSD: tls.h,v 1.66 2024/03/27 07:35:30 joshua Exp $ */ 2/* 3 * Copyright (c) 2014 Joel Sing <jsing@openbsd.org> 4 * 5 * Permission to use, copy, modify, and distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18#ifndef HEADER_TLS_H 19#define HEADER_TLS_H 20 21#ifdef __cplusplus 22extern "C" { 23#endif 24 25#include <sys/types.h> 26 27#include <stddef.h> 28#include <stdint.h> 29 30#define TLS_API 20200120 31 32/* 33 * Deprecated versions of TLS. Using these effectively selects 34 * the minimum supported version. 35 */ 36#define TLS_PROTOCOL_TLSv1_0 (1 << 3) 37#define TLS_PROTOCOL_TLSv1_1 (1 << 3) 38/* Supported versions of TLS */ 39#define TLS_PROTOCOL_TLSv1_2 (1 << 3) 40#define TLS_PROTOCOL_TLSv1_3 (1 << 4) 41 42#define TLS_PROTOCOL_TLSv1 \ 43 (TLS_PROTOCOL_TLSv1_2|TLS_PROTOCOL_TLSv1_3) 44 45#define TLS_PROTOCOLS_ALL TLS_PROTOCOL_TLSv1 46#define TLS_PROTOCOLS_DEFAULT (TLS_PROTOCOL_TLSv1_2|TLS_PROTOCOL_TLSv1_3) 47 48#define TLS_WANT_POLLIN -2 49#define TLS_WANT_POLLOUT -3 50 51/* RFC 6960 Section 2.3 */ 52#define TLS_OCSP_RESPONSE_SUCCESSFUL 0 53#define TLS_OCSP_RESPONSE_MALFORMED 1 54#define TLS_OCSP_RESPONSE_INTERNALERROR 2 55#define TLS_OCSP_RESPONSE_TRYLATER 3 56#define TLS_OCSP_RESPONSE_SIGREQUIRED 4 57#define TLS_OCSP_RESPONSE_UNAUTHORIZED 5 58 59/* RFC 6960 Section 2.2 */ 60#define TLS_OCSP_CERT_GOOD 0 61#define TLS_OCSP_CERT_REVOKED 1 62#define TLS_OCSP_CERT_UNKNOWN 2 63 64/* RFC 5280 Section 5.3.1 */ 65#define TLS_CRL_REASON_UNSPECIFIED 0 66#define TLS_CRL_REASON_KEY_COMPROMISE 1 67#define TLS_CRL_REASON_CA_COMPROMISE 2 68#define TLS_CRL_REASON_AFFILIATION_CHANGED 3 69#define TLS_CRL_REASON_SUPERSEDED 4 70#define TLS_CRL_REASON_CESSATION_OF_OPERATION 5 71#define TLS_CRL_REASON_CERTIFICATE_HOLD 6 72#define TLS_CRL_REASON_REMOVE_FROM_CRL 8 73#define TLS_CRL_REASON_PRIVILEGE_WITHDRAWN 9 74#define TLS_CRL_REASON_AA_COMPROMISE 10 75 76#define TLS_MAX_SESSION_ID_LENGTH 32 77#define TLS_TICKET_KEY_SIZE 48 78 79/* Error codes */ 80#if defined(LIBRESSL_NEXT_API) || defined(LIBRESSL_INTERNAL) 81#define TLS_ERROR_UNKNOWN 0x0000 82#define TLS_ERROR_OUT_OF_MEMORY 0x1000 83#define TLS_ERROR_INVALID_CONTEXT 0x2000 84#define TLS_ERROR_INVALID_ARGUMENT 0x2001 85#endif 86 87struct tls; 88struct tls_config; 89 90typedef ssize_t (*tls_read_cb)(struct tls *_ctx, void *_buf, size_t _buflen, 91 void *_cb_arg); 92typedef ssize_t (*tls_write_cb)(struct tls *_ctx, const void *_buf, 93 size_t _buflen, void *_cb_arg); 94 95int tls_init(void); 96 97const char *tls_config_error(struct tls_config *_config); 98const char *tls_error(struct tls *_ctx); 99#if defined(LIBRESSL_NEXT_API) || defined(LIBRESSL_INTERNAL) 100int tls_config_error_code(struct tls_config *_config); 101int tls_error_code(struct tls *_ctx); 102#endif 103 104struct tls_config *tls_config_new(void); 105void tls_config_free(struct tls_config *_config); 106 107const char *tls_default_ca_cert_file(void); 108 109int tls_config_add_keypair_file(struct tls_config *_config, 110 const char *_cert_file, const char *_key_file); 111int tls_config_add_keypair_mem(struct tls_config *_config, const uint8_t *_cert, 112 size_t _cert_len, const uint8_t *_key, size_t _key_len); 113int tls_config_add_keypair_ocsp_file(struct tls_config *_config, 114 const char *_cert_file, const char *_key_file, 115 const char *_ocsp_staple_file); 116int tls_config_add_keypair_ocsp_mem(struct tls_config *_config, const uint8_t *_cert, 117 size_t _cert_len, const uint8_t *_key, size_t _key_len, 118 const uint8_t *_staple, size_t _staple_len); 119int tls_config_set_alpn(struct tls_config *_config, const char *_alpn); 120int tls_config_set_ca_file(struct tls_config *_config, const char *_ca_file); 121int tls_config_set_ca_path(struct tls_config *_config, const char *_ca_path); 122int tls_config_set_ca_mem(struct tls_config *_config, const uint8_t *_ca, 123 size_t _len); 124int tls_config_set_cert_file(struct tls_config *_config, 125 const char *_cert_file); 126int tls_config_set_cert_mem(struct tls_config *_config, const uint8_t *_cert, 127 size_t _len); 128int tls_config_set_ciphers(struct tls_config *_config, const char *_ciphers); 129int tls_config_set_crl_file(struct tls_config *_config, const char *_crl_file); 130int tls_config_set_crl_mem(struct tls_config *_config, const uint8_t *_crl, 131 size_t _len); 132int tls_config_set_dheparams(struct tls_config *_config, const char *_params); 133int tls_config_set_ecdhecurve(struct tls_config *_config, const char *_curve); 134int tls_config_set_ecdhecurves(struct tls_config *_config, const char *_curves); 135int tls_config_set_key_file(struct tls_config *_config, const char *_key_file); 136int tls_config_set_key_mem(struct tls_config *_config, const uint8_t *_key, 137 size_t _len); 138int tls_config_set_keypair_file(struct tls_config *_config, 139 const char *_cert_file, const char *_key_file); 140int tls_config_set_keypair_mem(struct tls_config *_config, const uint8_t *_cert, 141 size_t _cert_len, const uint8_t *_key, size_t _key_len); 142int tls_config_set_keypair_ocsp_file(struct tls_config *_config, 143 const char *_cert_file, const char *_key_file, const char *_staple_file); 144int tls_config_set_keypair_ocsp_mem(struct tls_config *_config, const uint8_t *_cert, 145 size_t _cert_len, const uint8_t *_key, size_t _key_len, 146 const uint8_t *_staple, size_t staple_len); 147int tls_config_set_ocsp_staple_mem(struct tls_config *_config, 148 const uint8_t *_staple, size_t _len); 149int tls_config_set_ocsp_staple_file(struct tls_config *_config, 150 const char *_staple_file); 151int tls_config_set_protocols(struct tls_config *_config, uint32_t _protocols); 152int tls_config_set_session_fd(struct tls_config *_config, int _session_fd); 153int tls_config_set_verify_depth(struct tls_config *_config, int _verify_depth); 154 155void tls_config_prefer_ciphers_client(struct tls_config *_config); 156void tls_config_prefer_ciphers_server(struct tls_config *_config); 157 158void tls_config_insecure_noverifycert(struct tls_config *_config); 159void tls_config_insecure_noverifyname(struct tls_config *_config); 160void tls_config_insecure_noverifytime(struct tls_config *_config); 161void tls_config_verify(struct tls_config *_config); 162 163void tls_config_ocsp_require_stapling(struct tls_config *_config); 164void tls_config_verify_client(struct tls_config *_config); 165void tls_config_verify_client_optional(struct tls_config *_config); 166 167void tls_config_clear_keys(struct tls_config *_config); 168int tls_config_parse_protocols(uint32_t *_protocols, const char *_protostr); 169 170int tls_config_set_session_id(struct tls_config *_config, 171 const unsigned char *_session_id, size_t _len); 172int tls_config_set_session_lifetime(struct tls_config *_config, int _lifetime); 173int tls_config_add_ticket_key(struct tls_config *_config, uint32_t _keyrev, 174 unsigned char *_key, size_t _keylen); 175 176struct tls *tls_client(void); 177struct tls *tls_server(void); 178int tls_configure(struct tls *_ctx, struct tls_config *_config); 179void tls_reset(struct tls *_ctx); 180void tls_free(struct tls *_ctx); 181 182int tls_accept_fds(struct tls *_ctx, struct tls **_cctx, int _fd_read, 183 int _fd_write); 184int tls_accept_socket(struct tls *_ctx, struct tls **_cctx, int _socket); 185int tls_accept_cbs(struct tls *_ctx, struct tls **_cctx, 186 tls_read_cb _read_cb, tls_write_cb _write_cb, void *_cb_arg); 187int tls_connect(struct tls *_ctx, const char *_host, const char *_port); 188int tls_connect_fds(struct tls *_ctx, int _fd_read, int _fd_write, 189 const char *_servername); 190int tls_connect_servername(struct tls *_ctx, const char *_host, 191 const char *_port, const char *_servername); 192int tls_connect_socket(struct tls *_ctx, int _s, const char *_servername); 193int tls_connect_cbs(struct tls *_ctx, tls_read_cb _read_cb, 194 tls_write_cb _write_cb, void *_cb_arg, const char *_servername); 195int tls_handshake(struct tls *_ctx); 196ssize_t tls_read(struct tls *_ctx, void *_buf, size_t _buflen); 197ssize_t tls_write(struct tls *_ctx, const void *_buf, size_t _buflen); 198int tls_close(struct tls *_ctx); 199 200int tls_peer_cert_provided(struct tls *_ctx); 201int tls_peer_cert_contains_name(struct tls *_ctx, const char *_name); 202 203const char *tls_peer_cert_hash(struct tls *_ctx); 204const char *tls_peer_cert_issuer(struct tls *_ctx); 205const char *tls_peer_cert_subject(struct tls *_ctx); 206time_t tls_peer_cert_notbefore(struct tls *_ctx); 207time_t tls_peer_cert_notafter(struct tls *_ctx); 208const uint8_t *tls_peer_cert_chain_pem(struct tls *_ctx, size_t *_len); 209 210const char *tls_conn_alpn_selected(struct tls *_ctx); 211const char *tls_conn_cipher(struct tls *_ctx); 212int tls_conn_cipher_strength(struct tls *_ctx); 213const char *tls_conn_servername(struct tls *_ctx); 214int tls_conn_session_resumed(struct tls *_ctx); 215const char *tls_conn_version(struct tls *_ctx); 216 217uint8_t *tls_load_file(const char *_file, size_t *_len, char *_password); 218void tls_unload_file(uint8_t *_buf, size_t len); 219 220int tls_ocsp_process_response(struct tls *_ctx, const unsigned char *_response, 221 size_t _size); 222int tls_peer_ocsp_cert_status(struct tls *_ctx); 223int tls_peer_ocsp_crl_reason(struct tls *_ctx); 224time_t tls_peer_ocsp_next_update(struct tls *_ctx); 225int tls_peer_ocsp_response_status(struct tls *_ctx); 226const char *tls_peer_ocsp_result(struct tls *_ctx); 227time_t tls_peer_ocsp_revocation_time(struct tls *_ctx); 228time_t tls_peer_ocsp_this_update(struct tls *_ctx); 229const char *tls_peer_ocsp_url(struct tls *_ctx); 230 231#ifdef __cplusplus 232} 233#endif 234 235#endif /* HEADER_TLS_H */ 236