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