1 #ifndef IOSTREAM_SSL_H 2 #define IOSTREAM_SSL_H 3 4 struct ssl_iostream; 5 struct ssl_iostream_context; 6 7 struct ssl_iostream_cert { 8 const char *cert; 9 const char *key; 10 const char *key_password; 11 }; 12 13 struct ssl_iostream_settings { 14 /* NOTE: when updating, remember to update: 15 ssl_iostream_settings_string_offsets[], 16 ssl_iostream_settings_drop_stream_only() */ 17 const char *min_protocol; /* both */ 18 const char *cipher_list; /* both */ 19 const char *ciphersuites; /* both, TLSv1.3 only */ 20 const char *curve_list; /* both */ 21 const char *ca, *ca_file, *ca_dir; /* context-only */ 22 /* alternative cert is for providing certificate using 23 different key algorithm */ 24 struct ssl_iostream_cert cert; /* both */ 25 struct ssl_iostream_cert alt_cert; /* both */ 26 const char *dh; /* context-only */ 27 const char *cert_username_field; /* both */ 28 const char *crypto_device; /* context-only */ 29 30 bool verbose, verbose_invalid_cert; /* stream-only */ 31 bool skip_crl_check; /* context-only */ 32 bool verify_remote_cert; /* neither/both */ 33 bool allow_invalid_cert; /* stream-only */ 34 bool prefer_server_ciphers; /* both */ 35 bool compression; /* context-only */ 36 bool tickets; /* context-only */ 37 }; 38 39 /* Load SSL module */ 40 int ssl_module_load(const char **error_r); 41 42 /* Returns 0 if ok, -1 and sets error_r if failed. The returned error string 43 becomes available via ssl_iostream_get_last_error(). The callback most 44 likely should be calling ssl_iostream_check_cert_validity(). */ 45 typedef int 46 ssl_iostream_handshake_callback_t(const char **error_r, void *context); 47 /* Called when TLS SNI becomes available. */ 48 typedef int ssl_iostream_sni_callback_t(const char *name, const char **error_r, 49 void *context); 50 51 /* Explicitly initialize SSL library globally. This is also done automatically 52 when the first SSL connection is created, but it may be useful to call it 53 earlier in case of chrooting. After the initialization is successful, any 54 further calls will just be ignored. Returns 0 on success, -1 on error. */ 55 int io_stream_ssl_global_init(const struct ssl_iostream_settings *set, 56 const char **error_r); 57 58 int io_stream_create_ssl_client(struct ssl_iostream_context *ctx, const char *host, 59 const struct ssl_iostream_settings *set, 60 struct istream **input, struct ostream **output, 61 struct ssl_iostream **iostream_r, 62 const char **error_r); 63 int io_stream_create_ssl_server(struct ssl_iostream_context *ctx, 64 const struct ssl_iostream_settings *set, 65 struct istream **input, struct ostream **output, 66 struct ssl_iostream **iostream_r, 67 const char **error_r); 68 /* Shutdown SSL connection and unreference ssl iostream. 69 The returned input and output streams must also be unreferenced. */ 70 void ssl_iostream_destroy(struct ssl_iostream **ssl_io); 71 72 /* If verbose logging is enabled, use the specified log prefix */ 73 void ssl_iostream_set_log_prefix(struct ssl_iostream *ssl_io, 74 const char *prefix); 75 76 int ssl_iostream_handshake(struct ssl_iostream *ssl_io); 77 /* Call the given callback when SSL handshake finishes. The callback must 78 verify whether the certificate and its hostname is valid. If there is no 79 callback, the default is to use ssl_iostream_check_cert_validity() with the 80 same host as given to io_stream_create_ssl_client() 81 82 Before the callback is called, certificate is only checked for issuer 83 and validity period. You should call ssl_iostream_check_cert_validity() 84 in your callback. 85 */ 86 void ssl_iostream_set_handshake_callback(struct ssl_iostream *ssl_io, 87 ssl_iostream_handshake_callback_t *callback, 88 void *context); 89 /* Call the given callback when client sends SNI. The callback can change the 90 ssl_iostream's context (with different certificates) by using 91 ssl_iostream_change_context(). */ 92 void ssl_iostream_set_sni_callback(struct ssl_iostream *ssl_io, 93 ssl_iostream_sni_callback_t *callback, 94 void *context); 95 void ssl_iostream_change_context(struct ssl_iostream *ssl_io, 96 struct ssl_iostream_context *ctx); 97 98 bool ssl_iostream_is_handshaked(const struct ssl_iostream *ssl_io); 99 /* Returns TRUE if the remote cert is invalid, or handshake callback returned 100 failure. */ 101 bool ssl_iostream_has_handshake_failed(const struct ssl_iostream *ssl_io); 102 bool ssl_iostream_has_valid_client_cert(const struct ssl_iostream *ssl_io); 103 bool ssl_iostream_has_broken_client_cert(struct ssl_iostream *ssl_io); 104 /* Checks certificate validity based, also performs name checking. Called by 105 default in handshake, unless handshake callback is set with 106 ssl_iostream_check_cert_validity(). 107 108 Host should be set as the name you want to validate the certificate name(s) 109 against. Usually this is the host name you connected to. 110 111 This function is same as calling ssl_iostream_has_valid_client_cert() 112 and ssl_iostream_cert_match_name(). 113 */ 114 int ssl_iostream_check_cert_validity(struct ssl_iostream *ssl_io, 115 const char *host, const char **error_r); 116 /* Returns TRUE if the given name matches the SSL stream's certificate. 117 The returned reason is a human-readable string explaining what exactly 118 matched the name, or why nothing matched. Note that this function works 119 only if the certificate was valid - using it when certificate is invalid 120 will always return FALSE before even checking the hostname. */ 121 bool ssl_iostream_cert_match_name(struct ssl_iostream *ssl_io, const char *name, 122 const char **reason_r); 123 const char *ssl_iostream_get_peer_name(struct ssl_iostream *ssl_io); 124 const char *ssl_iostream_get_compression(struct ssl_iostream *ssl_io); 125 const char *ssl_iostream_get_server_name(struct ssl_iostream *ssl_io); 126 const char *ssl_iostream_get_security_string(struct ssl_iostream *ssl_io); 127 /* Returns SSL context's current used cipher algorithm. Returns NULL 128 if SSL handshake has not been performed. 129 130 This returns values like 'AESGCM' 131 */ 132 const char *ssl_iostream_get_cipher(struct ssl_iostream *ssl_io, 133 unsigned int *bits_r); 134 /* Returns currently used forward secrecy algorithm, if available. 135 Returns NULL if handshake not done yet, empty string if missing. 136 137 This returns values like 'DH', 'ECDH' etc.. 138 */ 139 const char *ssl_iostream_get_pfs(struct ssl_iostream *ssl_io); 140 /* Returns currently used SSL protocol name. Returns NULL if handshake 141 has not yet been made. 142 143 This returns values like SSLv3, TLSv1, TLSv1.1, TLSv1.2 144 */ 145 const char *ssl_iostream_get_protocol_name(struct ssl_iostream *ssl_io); 146 147 const char *ssl_iostream_get_last_error(struct ssl_iostream *ssl_io); 148 149 int ssl_iostream_context_init_client(const struct ssl_iostream_settings *set, 150 struct ssl_iostream_context **ctx_r, 151 const char **error_r); 152 int ssl_iostream_context_init_server(const struct ssl_iostream_settings *set, 153 struct ssl_iostream_context **ctx_r, 154 const char **error_r); 155 void ssl_iostream_context_ref(struct ssl_iostream_context *ctx); 156 void ssl_iostream_context_unref(struct ssl_iostream_context **ctx); 157 158 struct ssl_iostream_settings *ssl_iostream_settings_dup(pool_t pool, 159 const struct ssl_iostream_settings *old_set); 160 void ssl_iostream_settings_init_from(pool_t pool, 161 struct ssl_iostream_settings *dest, 162 const struct ssl_iostream_settings *src); 163 164 /* Persistent cache of ssl_iostream_contexts. The context is permanently stored 165 until ssl_iostream_context_cache_free() is called. The returned context 166 must be unreferenced by the caller. */ 167 int ssl_iostream_client_context_cache_get(const struct ssl_iostream_settings *set, 168 struct ssl_iostream_context **ctx_r, 169 const char **error_r); 170 int ssl_iostream_server_context_cache_get(const struct ssl_iostream_settings *set, 171 struct ssl_iostream_context **ctx_r, 172 const char **error_r); 173 void ssl_iostream_context_cache_free(void); 174 175 #endif 176