xref: /openbsd-src/lib/libtls/tls.h (revision 26433cb13cc3308103fce1cf0c8fcad1280ba684)
1*26433cb1Stb /* $OpenBSD: tls.h,v 1.68 2024/12/10 08:40:30 tb Exp $ */
2b600beedSjsing /*
3b600beedSjsing  * Copyright (c) 2014 Joel Sing <jsing@openbsd.org>
4b600beedSjsing  *
5b600beedSjsing  * Permission to use, copy, modify, and distribute this software for any
6b600beedSjsing  * purpose with or without fee is hereby granted, provided that the above
7b600beedSjsing  * copyright notice and this permission notice appear in all copies.
8b600beedSjsing  *
9b600beedSjsing  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10b600beedSjsing  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11b600beedSjsing  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12b600beedSjsing  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13b600beedSjsing  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14b600beedSjsing  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15b600beedSjsing  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16b600beedSjsing  */
17b600beedSjsing 
18b600beedSjsing #ifndef HEADER_TLS_H
19b600beedSjsing #define HEADER_TLS_H
20b600beedSjsing 
210ed661ccSbcook #ifdef __cplusplus
220ed661ccSbcook extern "C" {
230ed661ccSbcook #endif
240ed661ccSbcook 
2527ecf354Sbcook #include <sys/types.h>
2627ecf354Sbcook 
270ed661ccSbcook #include <stddef.h>
280ed661ccSbcook #include <stdint.h>
290ed661ccSbcook 
304c479435Sjsing #define TLS_API	20200120
31b600beedSjsing 
325c389b79Sbeck /*
335c389b79Sbeck  * Deprecated versions of TLS. Using these effectively selects
345c389b79Sbeck  * the minimum supported version.
355c389b79Sbeck  */
366a16e2b3Stb #define TLS_PROTOCOL_TLSv1_0	(1 << 1)
376a16e2b3Stb #define TLS_PROTOCOL_TLSv1_1	(1 << 2)
385c389b79Sbeck /* Supported versions of TLS */
39b600beedSjsing #define TLS_PROTOCOL_TLSv1_2	(1 << 3)
404c479435Sjsing #define TLS_PROTOCOL_TLSv1_3	(1 << 4)
414c479435Sjsing 
42b600beedSjsing #define TLS_PROTOCOL_TLSv1 \
435c389b79Sbeck 	(TLS_PROTOCOL_TLSv1_2|TLS_PROTOCOL_TLSv1_3)
4403b06e2fSjsing 
4503b06e2fSjsing #define TLS_PROTOCOLS_ALL TLS_PROTOCOL_TLSv1
46c6bdffd5Sbeck #define TLS_PROTOCOLS_DEFAULT (TLS_PROTOCOL_TLSv1_2|TLS_PROTOCOL_TLSv1_3)
47b600beedSjsing 
48ab00dbefSbeck #define TLS_WANT_POLLIN		-2
49ab00dbefSbeck #define TLS_WANT_POLLOUT	-3
50b600beedSjsing 
512dc6b4e4Sbeck /* RFC 6960 Section 2.3 */
522dc6b4e4Sbeck #define TLS_OCSP_RESPONSE_SUCCESSFUL		0
532dc6b4e4Sbeck #define TLS_OCSP_RESPONSE_MALFORMED		1
542dc6b4e4Sbeck #define TLS_OCSP_RESPONSE_INTERNALERROR		2
552dc6b4e4Sbeck #define TLS_OCSP_RESPONSE_TRYLATER		3
562dc6b4e4Sbeck #define TLS_OCSP_RESPONSE_SIGREQUIRED		4
572dc6b4e4Sbeck #define TLS_OCSP_RESPONSE_UNAUTHORIZED		5
582dc6b4e4Sbeck 
592dc6b4e4Sbeck /* RFC 6960 Section 2.2 */
602dc6b4e4Sbeck #define TLS_OCSP_CERT_GOOD			0
612dc6b4e4Sbeck #define TLS_OCSP_CERT_REVOKED			1
622dc6b4e4Sbeck #define TLS_OCSP_CERT_UNKNOWN			2
632dc6b4e4Sbeck 
642dc6b4e4Sbeck /* RFC 5280 Section 5.3.1 */
652dc6b4e4Sbeck #define TLS_CRL_REASON_UNSPECIFIED		0
662dc6b4e4Sbeck #define TLS_CRL_REASON_KEY_COMPROMISE		1
672dc6b4e4Sbeck #define TLS_CRL_REASON_CA_COMPROMISE		2
682dc6b4e4Sbeck #define TLS_CRL_REASON_AFFILIATION_CHANGED	3
692dc6b4e4Sbeck #define TLS_CRL_REASON_SUPERSEDED		4
702dc6b4e4Sbeck #define TLS_CRL_REASON_CESSATION_OF_OPERATION	5
712dc6b4e4Sbeck #define TLS_CRL_REASON_CERTIFICATE_HOLD		6
722dc6b4e4Sbeck #define TLS_CRL_REASON_REMOVE_FROM_CRL		8
732dc6b4e4Sbeck #define TLS_CRL_REASON_PRIVILEGE_WITHDRAWN	9
742dc6b4e4Sbeck #define TLS_CRL_REASON_AA_COMPROMISE		10
752dc6b4e4Sbeck 
7647c43cfeSclaudio #define TLS_MAX_SESSION_ID_LENGTH		32
7747c43cfeSclaudio #define TLS_TICKET_KEY_SIZE			48
7847c43cfeSclaudio 
797a756d37Sjoshua /* Error codes */
807a756d37Sjoshua #if defined(LIBRESSL_NEXT_API) || defined(LIBRESSL_INTERNAL)
817a756d37Sjoshua #define TLS_ERROR_UNKNOWN			0x0000
827a756d37Sjoshua #define TLS_ERROR_OUT_OF_MEMORY			0x1000
8340ae7d6bSjoshua #define TLS_ERROR_INVALID_CONTEXT		0x2000
842b31d1bdSjoshua #define TLS_ERROR_INVALID_ARGUMENT		0x2001
857a756d37Sjoshua #endif
867a756d37Sjoshua 
87b600beedSjsing struct tls;
88b600beedSjsing struct tls_config;
89b600beedSjsing 
90f36cb7cfStedu typedef ssize_t (*tls_read_cb)(struct tls *_ctx, void *_buf, size_t _buflen,
91ed19021fSbcook     void *_cb_arg);
92f36cb7cfStedu typedef ssize_t (*tls_write_cb)(struct tls *_ctx, const void *_buf,
93ed19021fSbcook     size_t _buflen, void *_cb_arg);
94ed19021fSbcook 
95b600beedSjsing int tls_init(void);
96b600beedSjsing 
97a88e9e95Sjsing const char *tls_config_error(struct tls_config *_config);
985c6f6e47Sjsing const char *tls_error(struct tls *_ctx);
997a756d37Sjoshua #if defined(LIBRESSL_NEXT_API) || defined(LIBRESSL_INTERNAL)
1007a756d37Sjoshua int tls_config_error_code(struct tls_config *_config);
1017a756d37Sjoshua int tls_error_code(struct tls *_ctx);
1027a756d37Sjoshua #endif
103b600beedSjsing 
104b600beedSjsing struct tls_config *tls_config_new(void);
1055c6f6e47Sjsing void tls_config_free(struct tls_config *_config);
106b600beedSjsing 
107f6b75673Stedu const char *tls_default_ca_cert_file(void);
108f6b75673Stedu 
10955272e79Sjsing int tls_config_add_keypair_file(struct tls_config *_config,
11055272e79Sjsing     const char *_cert_file, const char *_key_file);
11155272e79Sjsing int tls_config_add_keypair_mem(struct tls_config *_config, const uint8_t *_cert,
11255272e79Sjsing     size_t _cert_len, const uint8_t *_key, size_t _key_len);
113ef012c23Sbeck int tls_config_add_keypair_ocsp_file(struct tls_config *_config,
114ef012c23Sbeck     const char *_cert_file, const char *_key_file,
115ef012c23Sbeck     const char *_ocsp_staple_file);
116ef012c23Sbeck int tls_config_add_keypair_ocsp_mem(struct tls_config *_config, const uint8_t *_cert,
117ef012c23Sbeck     size_t _cert_len, const uint8_t *_key, size_t _key_len,
118ef012c23Sbeck     const uint8_t *_staple, size_t _staple_len);
119183da8c6Sjsing int tls_config_set_alpn(struct tls_config *_config, const char *_alpn);
1205c6f6e47Sjsing int tls_config_set_ca_file(struct tls_config *_config, const char *_ca_file);
1215c6f6e47Sjsing int tls_config_set_ca_path(struct tls_config *_config, const char *_ca_path);
1225c6f6e47Sjsing int tls_config_set_ca_mem(struct tls_config *_config, const uint8_t *_ca,
1235c6f6e47Sjsing     size_t _len);
1245c6f6e47Sjsing int tls_config_set_cert_file(struct tls_config *_config,
1255c6f6e47Sjsing     const char *_cert_file);
1265c6f6e47Sjsing int tls_config_set_cert_mem(struct tls_config *_config, const uint8_t *_cert,
1275c6f6e47Sjsing     size_t _len);
1285c6f6e47Sjsing int tls_config_set_ciphers(struct tls_config *_config, const char *_ciphers);
12980bc881dSjsing int tls_config_set_crl_file(struct tls_config *_config, const char *_crl_file);
13080bc881dSjsing int tls_config_set_crl_mem(struct tls_config *_config, const uint8_t *_crl,
13180bc881dSjsing     size_t _len);
1325c6f6e47Sjsing int tls_config_set_dheparams(struct tls_config *_config, const char *_params);
1334896de1eSjsing int tls_config_set_ecdhecurve(struct tls_config *_config, const char *_curve);
1344896de1eSjsing int tls_config_set_ecdhecurves(struct tls_config *_config, const char *_curves);
1355c6f6e47Sjsing int tls_config_set_key_file(struct tls_config *_config, const char *_key_file);
1365c6f6e47Sjsing int tls_config_set_key_mem(struct tls_config *_config, const uint8_t *_key,
1375c6f6e47Sjsing     size_t _len);
1381fe9fea1Sjsing int tls_config_set_keypair_file(struct tls_config *_config,
1391fe9fea1Sjsing     const char *_cert_file, const char *_key_file);
1401fe9fea1Sjsing int tls_config_set_keypair_mem(struct tls_config *_config, const uint8_t *_cert,
1411fe9fea1Sjsing     size_t _cert_len, const uint8_t *_key, size_t _key_len);
142ef012c23Sbeck int tls_config_set_keypair_ocsp_file(struct tls_config *_config,
143ef012c23Sbeck     const char *_cert_file, const char *_key_file, const char *_staple_file);
144ef012c23Sbeck int tls_config_set_keypair_ocsp_mem(struct tls_config *_config, const uint8_t *_cert,
145ef012c23Sbeck     size_t _cert_len, const uint8_t *_key, size_t _key_len,
146ef012c23Sbeck     const uint8_t *_staple, size_t staple_len);
147ef012c23Sbeck int tls_config_set_ocsp_staple_mem(struct tls_config *_config,
148ef012c23Sbeck     const uint8_t *_staple, size_t _len);
14950ef2d71Sjsing int tls_config_set_ocsp_staple_file(struct tls_config *_config,
15050ef2d71Sjsing     const char *_staple_file);
1512b50121aSjsing int tls_config_set_protocols(struct tls_config *_config, uint32_t _protocols);
1520dd084b9Sjsing int tls_config_set_session_fd(struct tls_config *_config, int _session_fd);
1532b50121aSjsing int tls_config_set_verify_depth(struct tls_config *_config, int _verify_depth);
154b600beedSjsing 
155c57e6ec0Sjsing void tls_config_prefer_ciphers_client(struct tls_config *_config);
156c57e6ec0Sjsing void tls_config_prefer_ciphers_server(struct tls_config *_config);
157729a1688Sjsing 
1585c6f6e47Sjsing void tls_config_insecure_noverifycert(struct tls_config *_config);
1595c6f6e47Sjsing void tls_config_insecure_noverifyname(struct tls_config *_config);
160615956a0Sjsing void tls_config_insecure_noverifytime(struct tls_config *_config);
1615c6f6e47Sjsing void tls_config_verify(struct tls_config *_config);
162b600beedSjsing 
16369013f12Sbeck void tls_config_ocsp_require_stapling(struct tls_config *_config);
16451f3bd3dSbeck void tls_config_verify_client(struct tls_config *_config);
16551f3bd3dSbeck void tls_config_verify_client_optional(struct tls_config *_config);
16651f3bd3dSbeck 
167c57e6ec0Sjsing void tls_config_clear_keys(struct tls_config *_config);
168c57e6ec0Sjsing int tls_config_parse_protocols(uint32_t *_protocols, const char *_protostr);
169c57e6ec0Sjsing 
17047c43cfeSclaudio int tls_config_set_session_id(struct tls_config *_config,
17147c43cfeSclaudio     const unsigned char *_session_id, size_t _len);
17247c43cfeSclaudio int tls_config_set_session_lifetime(struct tls_config *_config, int _lifetime);
17347c43cfeSclaudio int tls_config_add_ticket_key(struct tls_config *_config, uint32_t _keyrev,
17447c43cfeSclaudio     unsigned char *_key, size_t _keylen);
17547c43cfeSclaudio 
176b600beedSjsing struct tls *tls_client(void);
177b600beedSjsing struct tls *tls_server(void);
1785c6f6e47Sjsing int tls_configure(struct tls *_ctx, struct tls_config *_config);
1795c6f6e47Sjsing void tls_reset(struct tls *_ctx);
1805c6f6e47Sjsing void tls_free(struct tls *_ctx);
181b600beedSjsing 
182e1e4dea2Sjsing int tls_accept_fds(struct tls *_ctx, struct tls **_cctx, int _fd_read,
183e1e4dea2Sjsing     int _fd_write);
1845c6f6e47Sjsing int tls_accept_socket(struct tls *_ctx, struct tls **_cctx, int _socket);
185ed19021fSbcook int tls_accept_cbs(struct tls *_ctx, struct tls **_cctx,
186ed19021fSbcook     tls_read_cb _read_cb, tls_write_cb _write_cb, void *_cb_arg);
1875c6f6e47Sjsing int tls_connect(struct tls *_ctx, const char *_host, const char *_port);
1885c6f6e47Sjsing int tls_connect_fds(struct tls *_ctx, int _fd_read, int _fd_write,
1895c6f6e47Sjsing     const char *_servername);
1905c6f6e47Sjsing int tls_connect_servername(struct tls *_ctx, const char *_host,
1915c6f6e47Sjsing     const char *_port, const char *_servername);
1925c6f6e47Sjsing int tls_connect_socket(struct tls *_ctx, int _s, const char *_servername);
193ed19021fSbcook int tls_connect_cbs(struct tls *_ctx, tls_read_cb _read_cb,
194ed19021fSbcook     tls_write_cb _write_cb, void *_cb_arg, const char *_servername);
195e2b71c11Sjsing int tls_handshake(struct tls *_ctx);
1961eeda1ffSbeck ssize_t tls_read(struct tls *_ctx, void *_buf, size_t _buflen);
1971eeda1ffSbeck ssize_t tls_write(struct tls *_ctx, const void *_buf, size_t _buflen);
1985c6f6e47Sjsing int tls_close(struct tls *_ctx);
199b600beedSjsing 
2005684be2aSjsing int tls_peer_cert_provided(struct tls *_ctx);
2015684be2aSjsing int tls_peer_cert_contains_name(struct tls *_ctx, const char *_name);
202b838e8e9Sjsing 
203*26433cb1Stb const char *tls_peer_cert_common_name(struct tls *_ctx);
204ab8f2ec6Sbeck const char *tls_peer_cert_hash(struct tls *_ctx);
2055684be2aSjsing const char *tls_peer_cert_issuer(struct tls *_ctx);
2065684be2aSjsing const char *tls_peer_cert_subject(struct tls *_ctx);
2075684be2aSjsing time_t	tls_peer_cert_notbefore(struct tls *_ctx);
2085684be2aSjsing time_t	tls_peer_cert_notafter(struct tls *_ctx);
209c67861f7Sbeck const uint8_t *tls_peer_cert_chain_pem(struct tls *_ctx, size_t *_len);
210f00a4e85Sbeck 
211183da8c6Sjsing const char *tls_conn_alpn_selected(struct tls *_ctx);
212380117c0Sjsing const char *tls_conn_cipher(struct tls *_ctx);
213bbf181b7Sjsing int tls_conn_cipher_strength(struct tls *_ctx);
21455272e79Sjsing const char *tls_conn_servername(struct tls *_ctx);
2150dd084b9Sjsing int tls_conn_session_resumed(struct tls *_ctx);
216183da8c6Sjsing const char *tls_conn_version(struct tls *_ctx);
217a0ec9d6bSjsing 
2185c6f6e47Sjsing uint8_t *tls_load_file(const char *_file, size_t *_len, char *_password);
219028ca023Sjsing void tls_unload_file(uint8_t *_buf, size_t len);
220cbcdaa48Sreyk 
22150ef2d71Sjsing int tls_ocsp_process_response(struct tls *_ctx, const unsigned char *_response,
22250ef2d71Sjsing     size_t _size);
2232dc6b4e4Sbeck int tls_peer_ocsp_cert_status(struct tls *_ctx);
2242dc6b4e4Sbeck int tls_peer_ocsp_crl_reason(struct tls *_ctx);
2252dc6b4e4Sbeck time_t tls_peer_ocsp_next_update(struct tls *_ctx);
2262dc6b4e4Sbeck int tls_peer_ocsp_response_status(struct tls *_ctx);
2272dc6b4e4Sbeck const char *tls_peer_ocsp_result(struct tls *_ctx);
2282dc6b4e4Sbeck time_t tls_peer_ocsp_revocation_time(struct tls *_ctx);
2292dc6b4e4Sbeck time_t tls_peer_ocsp_this_update(struct tls *_ctx);
2302dc6b4e4Sbeck const char *tls_peer_ocsp_url(struct tls *_ctx);
2312dc6b4e4Sbeck 
2320ed661ccSbcook #ifdef __cplusplus
2330ed661ccSbcook }
2340ed661ccSbcook #endif
2350ed661ccSbcook 
236b600beedSjsing #endif /* HEADER_TLS_H */
237