lib/libtls/tls.h

   1 /* $OpenBSD: tls.h,v 1.51 2017/08/10 18:18:30 jsing 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
  22 extern "C" {
  23 #endif
  24
  25 #include <sys/types.h>
  26
  27 #include <stddef.h>
  28 #include <stdint.h>
  29
  30 #define TLS_API 20170126
  31
  32 #define TLS_PROTOCOL_TLSv1_0    (1 << 1)
  33 #define TLS_PROTOCOL_TLSv1_1    (1 << 2)
  34 #define TLS_PROTOCOL_TLSv1_2    (1 << 3)
  35 #define TLS_PROTOCOL_TLSv1 \
  36         (TLS_PROTOCOL_TLSv1_0|TLS_PROTOCOL_TLSv1_1|TLS_PROTOCOL_TLSv1_2)
  37
  38 #define TLS_PROTOCOLS_ALL TLS_PROTOCOL_TLSv1
  39 #define TLS_PROTOCOLS_DEFAULT TLS_PROTOCOL_TLSv1_2
  40
  41 #define TLS_WANT_POLLIN         -2
  42 #define TLS_WANT_POLLOUT        -3
  43
  44 /* RFC 6960 Section 2.3 */
  45 #define TLS_OCSP_RESPONSE_SUCCESSFUL            0
  46 #define TLS_OCSP_RESPONSE_MALFORMED             1
  47 #define TLS_OCSP_RESPONSE_INTERNALERROR         2
  48 #define TLS_OCSP_RESPONSE_TRYLATER              3
  49 #define TLS_OCSP_RESPONSE_SIGREQUIRED           4
  50 #define TLS_OCSP_RESPONSE_UNAUTHORIZED          5
  51
  52 /* RFC 6960 Section 2.2 */
  53 #define TLS_OCSP_CERT_GOOD                      0
  54 #define TLS_OCSP_CERT_REVOKED                   1
  55 #define TLS_OCSP_CERT_UNKNOWN                   2
  56
  57 /* RFC 5280 Section 5.3.1 */
  58 #define TLS_CRL_REASON_UNSPECIFIED              0
  59 #define TLS_CRL_REASON_KEY_COMPROMISE           1
  60 #define TLS_CRL_REASON_CA_COMPROMISE            2
  61 #define TLS_CRL_REASON_AFFILIATION_CHANGED      3
  62 #define TLS_CRL_REASON_SUPERSEDED               4
  63 #define TLS_CRL_REASON_CESSATION_OF_OPERATION   5
  64 #define TLS_CRL_REASON_CERTIFICATE_HOLD         6
  65 #define TLS_CRL_REASON_REMOVE_FROM_CRL          8
  66 #define TLS_CRL_REASON_PRIVILEGE_WITHDRAWN      9
  67 #define TLS_CRL_REASON_AA_COMPROMISE            10
  68
  69 #define TLS_MAX_SESSION_ID_LENGTH               32
  70 #define TLS_TICKET_KEY_SIZE                     48
  71
  72 struct tls;
  73 struct tls_config;
  74
  75 typedef ssize_t (*tls_read_cb)(struct tls *_ctx, void *_buf, size_t _buflen,
  76     void *_cb_arg);
  77 typedef ssize_t (*tls_write_cb)(struct tls *_ctx, const void *_buf,
  78     size_t _buflen, void *_cb_arg);
  79
  80 int tls_init(void);
  81
  82 const char *tls_config_error(struct tls_config *_config);
  83 const char *tls_error(struct tls *_ctx);
  84
  85 struct tls_config *tls_config_new(void);
  86 void tls_config_free(struct tls_config *_config);
  87
  88 int tls_config_add_keypair_file(struct tls_config *_config,
  89     const char *_cert_file, const char *_key_file);
  90 int tls_config_add_keypair_mem(struct tls_config *_config, const uint8_t *_cert,
  91     size_t _cert_len, const uint8_t *_key, size_t _key_len);
  92 int tls_config_add_keypair_ocsp_file(struct tls_config *_config,
  93     const char *_cert_file, const char *_key_file,
  94     const char *_ocsp_staple_file);
  95 int tls_config_add_keypair_ocsp_mem(struct tls_config *_config, const uint8_t *_cert,
  96     size_t _cert_len, const uint8_t *_key, size_t _key_len,
  97     const uint8_t *_staple, size_t _staple_len);
  98 int tls_config_set_alpn(struct tls_config *_config, const char *_alpn);
  99 int tls_config_set_ca_file(struct tls_config *_config, const char *_ca_file);
 100 int tls_config_set_ca_path(struct tls_config *_config, const char *_ca_path);
 101 int tls_config_set_ca_mem(struct tls_config *_config, const uint8_t *_ca,
 102     size_t _len);
 103 int tls_config_set_cert_file(struct tls_config *_config,
 104     const char *_cert_file);
 105 int tls_config_set_cert_mem(struct tls_config *_config, const uint8_t *_cert,
 106     size_t _len);
 107 int tls_config_set_ciphers(struct tls_config *_config, const char *_ciphers);
 108 int tls_config_set_crl_file(struct tls_config *_config, const char *_crl_file);
 109 int tls_config_set_crl_mem(struct tls_config *_config, const uint8_t *_crl,
 110     size_t _len);
 111 int tls_config_set_dheparams(struct tls_config *_config, const char *_params);
 112 int tls_config_set_ecdhecurve(struct tls_config *_config, const char *_curve);
 113 int tls_config_set_ecdhecurves(struct tls_config *_config, const char *_curves);
 114 int tls_config_set_key_file(struct tls_config *_config, const char *_key_file);
 115 int tls_config_set_key_mem(struct tls_config *_config, const uint8_t *_key,
 116     size_t _len);
 117 int tls_config_set_keypair_file(struct tls_config *_config,
 118     const char *_cert_file, const char *_key_file);
 119 int tls_config_set_keypair_mem(struct tls_config *_config, const uint8_t *_cert,
 120     size_t _cert_len, const uint8_t *_key, size_t _key_len);
 121 int tls_config_set_keypair_ocsp_file(struct tls_config *_config,
 122     const char *_cert_file, const char *_key_file, const char *_staple_file);
 123 int tls_config_set_keypair_ocsp_mem(struct tls_config *_config, const uint8_t *_cert,
 124     size_t _cert_len, const uint8_t *_key, size_t _key_len,
 125     const uint8_t *_staple, size_t staple_len);
 126 int tls_config_set_ocsp_staple_mem(struct tls_config *_config,
 127     const uint8_t *_staple, size_t _len);
 128 int tls_config_set_ocsp_staple_file(struct tls_config *_config,
 129     const char *_staple_file);
 130 int tls_config_set_protocols(struct tls_config *_config, uint32_t _protocols);
 131 int tls_config_set_verify_depth(struct tls_config *_config, int _verify_depth);
 132
 133 void tls_config_prefer_ciphers_client(struct tls_config *_config);
 134 void tls_config_prefer_ciphers_server(struct tls_config *_config);
 135
 136 void tls_config_insecure_noverifycert(struct tls_config *_config);
 137 void tls_config_insecure_noverifyname(struct tls_config *_config);
 138 void tls_config_insecure_noverifytime(struct tls_config *_config);
 139 void tls_config_verify(struct tls_config *_config);
 140
 141 void tls_config_ocsp_require_stapling(struct tls_config *_config);
 142 void tls_config_verify_client(struct tls_config *_config);
 143 void tls_config_verify_client_optional(struct tls_config *_config);
 144
 145 void tls_config_clear_keys(struct tls_config *_config);
 146 int tls_config_parse_protocols(uint32_t *_protocols, const char *_protostr);
 147
 148 int tls_config_set_session_id(struct tls_config *_config,
 149     const unsigned char *_session_id, size_t _len);
 150 int tls_config_set_session_lifetime(struct tls_config *_config, int _lifetime);
 151 int tls_config_add_ticket_key(struct tls_config *_config, uint32_t _keyrev,
 152     unsigned char *_key, size_t _keylen);
 153
 154 struct tls *tls_client(void);
 155 struct tls *tls_server(void);
 156 int tls_configure(struct tls *_ctx, struct tls_config *_config);
 157 void tls_reset(struct tls *_ctx);
 158 void tls_free(struct tls *_ctx);
 159
 160 int tls_accept_fds(struct tls *_ctx, struct tls **_cctx, int _fd_read,
 161     int _fd_write);
 162 int tls_accept_socket(struct tls *_ctx, struct tls **_cctx, int _socket);
 163 int tls_accept_cbs(struct tls *_ctx, struct tls **_cctx,
 164     tls_read_cb _read_cb, tls_write_cb _write_cb, void *_cb_arg);
 165 int tls_connect(struct tls *_ctx, const char *_host, const char *_port);
 166 int tls_connect_fds(struct tls *_ctx, int _fd_read, int _fd_write,
 167     const char *_servername);
 168 int tls_connect_servername(struct tls *_ctx, const char *_host,
 169     const char *_port, const char *_servername);
 170 int tls_connect_socket(struct tls *_ctx, int _s, const char *_servername);
 171 int tls_connect_cbs(struct tls *_ctx, tls_read_cb _read_cb,
 172     tls_write_cb _write_cb, void *_cb_arg, const char *_servername);
 173 int tls_handshake(struct tls *_ctx);
 174 ssize_t tls_read(struct tls *_ctx, void *_buf, size_t _buflen);
 175 ssize_t tls_write(struct tls *_ctx, const void *_buf, size_t _buflen);
 176 int tls_close(struct tls *_ctx);
 177
 178 int tls_peer_cert_provided(struct tls *_ctx);
 179 int tls_peer_cert_contains_name(struct tls *_ctx, const char *_name);
 180
 181 const char *tls_peer_cert_hash(struct tls *_ctx);
 182 const char *tls_peer_cert_issuer(struct tls *_ctx);
 183 const char *tls_peer_cert_subject(struct tls *_ctx);
 184 time_t  tls_peer_cert_notbefore(struct tls *_ctx);
 185 time_t  tls_peer_cert_notafter(struct tls *_ctx);
 186 const uint8_t *tls_peer_cert_chain_pem(struct tls *_ctx, size_t *_len);
 187
 188 const char *tls_conn_alpn_selected(struct tls *_ctx);
 189 const char *tls_conn_cipher(struct tls *_ctx);
 190 const char *tls_conn_servername(struct tls *_ctx);
 191 const char *tls_conn_version(struct tls *_ctx);
 192
 193 uint8_t *tls_load_file(const char *_file, size_t *_len, char *_password);
 194 void tls_unload_file(uint8_t *_buf, size_t len);
 195
 196 int tls_ocsp_process_response(struct tls *_ctx, const unsigned char *_response,
 197     size_t _size);
 198 int tls_peer_ocsp_cert_status(struct tls *_ctx);
 199 int tls_peer_ocsp_crl_reason(struct tls *_ctx);
 200 time_t tls_peer_ocsp_next_update(struct tls *_ctx);
 201 int tls_peer_ocsp_response_status(struct tls *_ctx);
 202 const char *tls_peer_ocsp_result(struct tls *_ctx);
 203 time_t tls_peer_ocsp_revocation_time(struct tls *_ctx);
 204 time_t tls_peer_ocsp_this_update(struct tls *_ctx);
 205 const char *tls_peer_ocsp_url(struct tls *_ctx);
 206
 207 #ifdef __cplusplus
 208 }
 209 #endif
 210
 211 #endif /* HEADER_TLS_H */