From 5af30545c000c195ca6e44f207da004e5780ddb5 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sat, 5 Nov 2016 15:32:20 +0000 Subject: move manual pages from doc/ to man/ for consistency with other libraries, in particular considering that there are unrelated files in doc/; requested by jsing@ and beck@ --- src/lib/libssl/man/BIO_f_ssl.3 | 479 +++++++ src/lib/libssl/man/Makefile | 93 ++ src/lib/libssl/man/SSL_CIPHER_get_name.3 | 196 +++ .../libssl/man/SSL_COMP_add_compression_method.3 | 68 + src/lib/libssl/man/SSL_CTX_add_extra_chain_cert.3 | 45 + src/lib/libssl/man/SSL_CTX_add_session.3 | 90 ++ src/lib/libssl/man/SSL_CTX_ctrl.3 | 49 + src/lib/libssl/man/SSL_CTX_flush_sessions.3 | 57 + src/lib/libssl/man/SSL_CTX_free.3 | 53 + src/lib/libssl/man/SSL_CTX_get_ex_new_index.3 | 70 ++ src/lib/libssl/man/SSL_CTX_get_verify_mode.3 | 73 ++ src/lib/libssl/man/SSL_CTX_load_verify_locations.3 | 161 +++ src/lib/libssl/man/SSL_CTX_new.3 | 111 ++ src/lib/libssl/man/SSL_CTX_sess_number.3 | 104 ++ src/lib/libssl/man/SSL_CTX_sess_set_cache_size.3 | 55 + src/lib/libssl/man/SSL_CTX_sess_set_get_cb.3 | 159 +++ src/lib/libssl/man/SSL_CTX_sessions.3 | 35 + src/lib/libssl/man/SSL_CTX_set_cert_store.3 | 80 ++ .../libssl/man/SSL_CTX_set_cert_verify_callback.3 | 112 ++ src/lib/libssl/man/SSL_CTX_set_cipher_list.3 | 82 ++ src/lib/libssl/man/SSL_CTX_set_client_CA_list.3 | 132 ++ src/lib/libssl/man/SSL_CTX_set_client_cert_cb.3 | 143 +++ src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 | 95 ++ .../libssl/man/SSL_CTX_set_generate_session_id.3 | 196 +++ src/lib/libssl/man/SSL_CTX_set_info_callback.3 | 167 +++ src/lib/libssl/man/SSL_CTX_set_max_cert_list.3 | 105 ++ src/lib/libssl/man/SSL_CTX_set_mode.3 | 126 ++ src/lib/libssl/man/SSL_CTX_set_msg_callback.3 | 135 ++ src/lib/libssl/man/SSL_CTX_set_options.3 | 395 ++++++ .../libssl/man/SSL_CTX_set_psk_client_callback.3 | 68 + src/lib/libssl/man/SSL_CTX_set_quiet_shutdown.3 | 115 ++ .../libssl/man/SSL_CTX_set_session_cache_mode.3 | 143 +++ .../libssl/man/SSL_CTX_set_session_id_context.3 | 105 ++ src/lib/libssl/man/SSL_CTX_set_ssl_version.3 | 81 ++ src/lib/libssl/man/SSL_CTX_set_timeout.3 | 65 + src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 | 235 ++++ src/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3 | 231 ++++ src/lib/libssl/man/SSL_CTX_set_verify.3 | 415 ++++++ src/lib/libssl/man/SSL_CTX_use_certificate.3 | 336 +++++ src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3 | 110 ++ src/lib/libssl/man/SSL_SESSION_free.3 | 84 ++ src/lib/libssl/man/SSL_SESSION_get_ex_new_index.3 | 80 ++ src/lib/libssl/man/SSL_SESSION_get_time.3 | 98 ++ src/lib/libssl/man/SSL_accept.3 | 103 ++ src/lib/libssl/man/SSL_alert_type_string.3 | 193 +++ src/lib/libssl/man/SSL_clear.3 | 92 ++ src/lib/libssl/man/SSL_connect.3 | 102 ++ src/lib/libssl/man/SSL_do_handshake.3 | 101 ++ src/lib/libssl/man/SSL_free.3 | 67 + src/lib/libssl/man/SSL_get_SSL_CTX.3 | 28 + src/lib/libssl/man/SSL_get_ciphers.3 | 68 + src/lib/libssl/man/SSL_get_client_CA_list.3 | 61 + src/lib/libssl/man/SSL_get_current_cipher.3 | 52 + src/lib/libssl/man/SSL_get_default_timeout.3 | 36 + src/lib/libssl/man/SSL_get_error.3 | 169 +++ .../man/SSL_get_ex_data_X509_STORE_CTX_idx.3 | 65 + src/lib/libssl/man/SSL_get_ex_new_index.3 | 76 ++ src/lib/libssl/man/SSL_get_fd.3 | 46 + src/lib/libssl/man/SSL_get_peer_cert_chain.3 | 47 + src/lib/libssl/man/SSL_get_peer_certificate.3 | 53 + src/lib/libssl/man/SSL_get_psk_identity.3 | 44 + src/lib/libssl/man/SSL_get_rbio.3 | 45 + src/lib/libssl/man/SSL_get_session.3 | 97 ++ src/lib/libssl/man/SSL_get_verify_result.3 | 49 + src/lib/libssl/man/SSL_get_version.3 | 35 + src/lib/libssl/man/SSL_library_init.3 | 54 + src/lib/libssl/man/SSL_load_client_CA_file.3 | 53 + src/lib/libssl/man/SSL_new.3 | 41 + src/lib/libssl/man/SSL_pending.3 | 44 + src/lib/libssl/man/SSL_read.3 | 193 +++ src/lib/libssl/man/SSL_rstate_string.3 | 55 + src/lib/libssl/man/SSL_session_reused.3 | 32 + src/lib/libssl/man/SSL_set_bio.3 | 51 + src/lib/libssl/man/SSL_set_connect_state.3 | 71 ++ src/lib/libssl/man/SSL_set_fd.3 | 73 ++ src/lib/libssl/man/SSL_set_session.3 | 68 + src/lib/libssl/man/SSL_set_shutdown.3 | 88 ++ src/lib/libssl/man/SSL_set_verify_result.3 | 42 + src/lib/libssl/man/SSL_shutdown.3 | 204 +++ src/lib/libssl/man/SSL_state_string.3 | 57 + src/lib/libssl/man/SSL_want.3 | 103 ++ src/lib/libssl/man/SSL_write.3 | 175 +++ src/lib/libssl/man/d2i_SSL_SESSION.3 | 129 ++ src/lib/libssl/man/ssl.3 | 1319 ++++++++++++++++++++ 84 files changed, 10313 insertions(+) create mode 100644 src/lib/libssl/man/BIO_f_ssl.3 create mode 100644 src/lib/libssl/man/Makefile create mode 100644 src/lib/libssl/man/SSL_CIPHER_get_name.3 create mode 100644 src/lib/libssl/man/SSL_COMP_add_compression_method.3 create mode 100644 src/lib/libssl/man/SSL_CTX_add_extra_chain_cert.3 create mode 100644 src/lib/libssl/man/SSL_CTX_add_session.3 create mode 100644 src/lib/libssl/man/SSL_CTX_ctrl.3 create mode 100644 src/lib/libssl/man/SSL_CTX_flush_sessions.3 create mode 100644 src/lib/libssl/man/SSL_CTX_free.3 create mode 100644 src/lib/libssl/man/SSL_CTX_get_ex_new_index.3 create mode 100644 src/lib/libssl/man/SSL_CTX_get_verify_mode.3 create mode 100644 src/lib/libssl/man/SSL_CTX_load_verify_locations.3 create mode 100644 src/lib/libssl/man/SSL_CTX_new.3 create mode 100644 src/lib/libssl/man/SSL_CTX_sess_number.3 create mode 100644 src/lib/libssl/man/SSL_CTX_sess_set_cache_size.3 create mode 100644 src/lib/libssl/man/SSL_CTX_sess_set_get_cb.3 create mode 100644 src/lib/libssl/man/SSL_CTX_sessions.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_cert_store.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_cert_verify_callback.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_cipher_list.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_client_CA_list.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_client_cert_cb.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_generate_session_id.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_info_callback.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_max_cert_list.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_mode.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_msg_callback.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_options.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_psk_client_callback.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_quiet_shutdown.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_session_cache_mode.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_session_id_context.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_ssl_version.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_timeout.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3 create mode 100644 src/lib/libssl/man/SSL_CTX_set_verify.3 create mode 100644 src/lib/libssl/man/SSL_CTX_use_certificate.3 create mode 100644 src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3 create mode 100644 src/lib/libssl/man/SSL_SESSION_free.3 create mode 100644 src/lib/libssl/man/SSL_SESSION_get_ex_new_index.3 create mode 100644 src/lib/libssl/man/SSL_SESSION_get_time.3 create mode 100644 src/lib/libssl/man/SSL_accept.3 create mode 100644 src/lib/libssl/man/SSL_alert_type_string.3 create mode 100644 src/lib/libssl/man/SSL_clear.3 create mode 100644 src/lib/libssl/man/SSL_connect.3 create mode 100644 src/lib/libssl/man/SSL_do_handshake.3 create mode 100644 src/lib/libssl/man/SSL_free.3 create mode 100644 src/lib/libssl/man/SSL_get_SSL_CTX.3 create mode 100644 src/lib/libssl/man/SSL_get_ciphers.3 create mode 100644 src/lib/libssl/man/SSL_get_client_CA_list.3 create mode 100644 src/lib/libssl/man/SSL_get_current_cipher.3 create mode 100644 src/lib/libssl/man/SSL_get_default_timeout.3 create mode 100644 src/lib/libssl/man/SSL_get_error.3 create mode 100644 src/lib/libssl/man/SSL_get_ex_data_X509_STORE_CTX_idx.3 create mode 100644 src/lib/libssl/man/SSL_get_ex_new_index.3 create mode 100644 src/lib/libssl/man/SSL_get_fd.3 create mode 100644 src/lib/libssl/man/SSL_get_peer_cert_chain.3 create mode 100644 src/lib/libssl/man/SSL_get_peer_certificate.3 create mode 100644 src/lib/libssl/man/SSL_get_psk_identity.3 create mode 100644 src/lib/libssl/man/SSL_get_rbio.3 create mode 100644 src/lib/libssl/man/SSL_get_session.3 create mode 100644 src/lib/libssl/man/SSL_get_verify_result.3 create mode 100644 src/lib/libssl/man/SSL_get_version.3 create mode 100644 src/lib/libssl/man/SSL_library_init.3 create mode 100644 src/lib/libssl/man/SSL_load_client_CA_file.3 create mode 100644 src/lib/libssl/man/SSL_new.3 create mode 100644 src/lib/libssl/man/SSL_pending.3 create mode 100644 src/lib/libssl/man/SSL_read.3 create mode 100644 src/lib/libssl/man/SSL_rstate_string.3 create mode 100644 src/lib/libssl/man/SSL_session_reused.3 create mode 100644 src/lib/libssl/man/SSL_set_bio.3 create mode 100644 src/lib/libssl/man/SSL_set_connect_state.3 create mode 100644 src/lib/libssl/man/SSL_set_fd.3 create mode 100644 src/lib/libssl/man/SSL_set_session.3 create mode 100644 src/lib/libssl/man/SSL_set_shutdown.3 create mode 100644 src/lib/libssl/man/SSL_set_verify_result.3 create mode 100644 src/lib/libssl/man/SSL_shutdown.3 create mode 100644 src/lib/libssl/man/SSL_state_string.3 create mode 100644 src/lib/libssl/man/SSL_want.3 create mode 100644 src/lib/libssl/man/SSL_write.3 create mode 100644 src/lib/libssl/man/d2i_SSL_SESSION.3 create mode 100644 src/lib/libssl/man/ssl.3 (limited to 'src/lib/libssl/man') diff --git a/src/lib/libssl/man/BIO_f_ssl.3 b/src/lib/libssl/man/BIO_f_ssl.3 new file mode 100644 index 0000000000..e322fd7887 --- /dev/null +++ b/src/lib/libssl/man/BIO_f_ssl.3 @@ -0,0 +1,479 @@ +.\" +.\" $OpenBSD: BIO_f_ssl.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt BIO_F_SSL 3 +.Os +.Sh NAME +.Nm BIO_f_ssl , +.Nm BIO_set_ssl , +.Nm BIO_get_ssl , +.Nm BIO_set_ssl_mode , +.Nm BIO_set_ssl_renegotiate_bytes , +.Nm BIO_get_num_renegotiates , +.Nm BIO_set_ssl_renegotiate_timeout , +.Nm BIO_new_ssl , +.Nm BIO_new_ssl_connect , +.Nm BIO_new_buffer_ssl_connect , +.Nm BIO_ssl_copy_session_id , +.Nm BIO_ssl_shutdown , +.Nm BIO_do_handshake +.Nd SSL BIO +.Sh SYNOPSIS +.In openssl/bio.h +.In openssl/ssl.h +.Ft BIO_METHOD * +.Fn BIO_f_ssl void +.Fd #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) +.Fd #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) +.Fd #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) +.Fd #define BIO_set_ssl_renegotiate_bytes(b,num) \ +BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL) +.Fd #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ +BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL) +.Fd #define BIO_get_num_renegotiates(b) \ +BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL) +.Ft BIO * +.Fn BIO_new_ssl "SSL_CTX *ctx" "int client" +.Ft BIO * +.Fn BIO_new_ssl_connect "SSL_CTX *ctx" +.Ft BIO * +.Fn BIO_new_buffer_ssl_connect "SSL_CTX *ctx" +.Ft int +.Fn BIO_ssl_copy_session_id "BIO *to" "BIO *from" +.Ft void +.Fn BIO_ssl_shutdown "BIO *bio" +.Fd #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) +.Sh DESCRIPTION +.Fn BIO_f_ssl +returns the +.Vt SSL +.Vt BIO +method. +This is a filter +.Vt BIO +which is a wrapper around the OpenSSL +.Vt SSL +routines adding a +.Vt BIO +.Dq flavor +to SSL I/O. +.Pp +I/O performed on an +.Vt SSL +.Vt BIO +communicates using the SSL protocol with +the +.Vt SSL Ns 's +read and write +.Vt BIO Ns s. +If an SSL connection is not established then an attempt is made to establish +one on the first I/O call. +.Pp +If a +.Vt BIO +is appended to an +.Vt SSL +.Vt BIO +using +.Xr BIO_push 3 +it is automatically used as the +.Vt SSL +.Vt BIO Ns 's read and write +.Vt BIO Ns s. +.Pp +Calling +.Xr BIO_reset 3 +on an +.Vt SSL +.Vt BIO +closes down any current SSL connection by calling +.Xr SSL_shutdown 3 . +.Xr BIO_reset +is then sent to the next +.Vt BIO +in the chain; this will typically disconnect the underlying transport. +The +.Vt SSL +.Vt BIO +is then reset to the initial accept or connect state. +.Pp +If the close flag is set when an +.Vt SSL +.Vt BIO +is freed then the internal +.Vt SSL +structure is also freed using +.Xr SSL_free 3 . +.Pp +.Fn BIO_set_ssl +sets the internal +.Vt SSL +pointer of +.Vt BIO +.Fa b +to +.Fa ssl +using +the close flag +.Fa c . +.Pp +.Fn BIO_get_ssl +retrieves the +.Vt SSL +pointer of +.Vt BIO +.Fa b ; +it can then be manipulated using the standard SSL library functions. +.Pp +.Fn BIO_set_ssl_mode +sets the +.Vt SSL +.Vt BIO +mode to +.Fa client . +If +.Fa client +is 1, client mode is set. +If +.Fa client +is 0, server mode is set. +.Pp +.Fn BIO_set_ssl_renegotiate_bytes +sets the renegotiate byte count to +.Fa num . +When set after every +.Fa num +bytes of I/O (read and write) the SSL session is automatically renegotiated. +.Fa num +must be at least 512 bytes. +.Pp +.Fn BIO_set_ssl_renegotiate_timeout +sets the renegotiate timeout to +.Fa seconds . +When the renegotiate timeout elapses the session is automatically renegotiated. +.Pp +.Fn BIO_get_num_renegotiates +returns the total number of session renegotiations due to I/O or timeout. +.Pp +.Fn BIO_new_ssl +allocates an +.Vt SSL +.Vt BIO +using +.Vt SSL_CTX +.Va ctx +and using client mode if +.Fa client +is nonzero. +.Pp +.Fn BIO_new_ssl_connect +creates a new +.Vt BIO +chain consisting of an +.Vt SSL +.Vt BIO +(using +.Fa ctx ) +followed by a connect BIO. +.Pp +.Fn BIO_new_buffer_ssl_connect +creates a new +.Vt BIO +chain consisting of a buffering +.Vt BIO , +an +.Vt SSL +.Vt BIO +(using +.Fa ctx ) +and a connect +.Vt BIO . +.Pp +.Fn BIO_ssl_copy_session_id +copies an SSL session id between +.Vt BIO +chains +.Fa from +and +.Fa to . +It does this by locating the +.Vt SSL +.Vt BIO Ns s +in each chain and calling +.Xr SSL_copy_session_id 3 +on the internal +.Vt SSL +pointer. +.Pp +.Fn BIO_ssl_shutdown +closes down an SSL connection on +.Vt BIO +chain +.Fa bio . +It does this by locating the +.Vt SSL +.Vt BIO +in the +chain and calling +.Xr SSL_shutdown 3 +on its internal +.Vt SSL +pointer. +.Pp +.Fn BIO_do_handshake +attempts to complete an SSL handshake on the supplied +.Vt BIO +and establish the SSL connection. +It returns 1 if the connection was established successfully. +A zero or negative value is returned if the connection could not be +established; the call +.Xr BIO_should_retry 3 +should be used for non blocking connect +.Vt BIO Ns s +to determine if the call should be retried. +If an SSL connection has already been established this call has no effect. +.Sh NOTES +.Vt SSL +.Vt BIO Ns s +are exceptional in that if the underlying transport is non-blocking they can +still request a retry in exceptional circumstances. +Specifically this will happen if a session renegotiation takes place during a +.Xr BIO_read 3 +operation. +One case where this happens is when step up occurs. +.Pp +In OpenSSL 0.9.6 and later the SSL flag +.Dv SSL_AUTO_RETRY +can be set to disable this behaviour. +In other words, when this flag is set an +.Vt SSL +.Vt BIO +using a blocking transport will never request a retry. +.Pp +Since unknown +.Xr BIO_ctrl 3 +operations are sent through filter +.Vt BIO Ns s +the server name and port can be set using +.Xr BIO_set_host 3 +on the +.Vt BIO +returned by +.Fn BIO_new_ssl_connect +without having to locate the connect +.Vt BIO +first. +.Pp +Applications do not have to call +.Fn BIO_do_handshake +but may wish to do so to separate the handshake process from other I/O +processing. +.Sh RETURN VALUES +.\" XXX +This section is incomplete. +.Sh EXAMPLES +This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web +server. +The I/O routines are identical to those of the unencrypted example in +.Xr BIO_s_connect 3 . +.Bd -literal +BIO *sbio, *out; +int len; +char tmpbuf[1024]; +SSL_CTX *ctx; +SSL *ssl; + +ERR_load_crypto_strings(); +ERR_load_SSL_strings(); +OpenSSL_add_all_algorithms(); + +/* + * We would seed the PRNG here if the platform didn't do it automatically + */ + +ctx = SSL_CTX_new(SSLv23_client_method()); + +/* + * We'd normally set some stuff like the verify paths and mode here because + * as things stand this will connect to any server whose certificate is + * signed by any CA. + */ + +sbio = BIO_new_ssl_connect(ctx); + +BIO_get_ssl(sbio, &ssl); + +if (!ssl) { + fprintf(stderr, "Can't locate SSL pointer\en"); + /* whatever ... */ +} + +/* Don't want any retries */ +SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + +/* We might want to do other things with ssl here */ + +BIO_set_conn_hostname(sbio, "localhost:https"); + +out = BIO_new_fp(stdout, BIO_NOCLOSE); +if (BIO_do_connect(sbio) <= 0) { + fprintf(stderr, "Error connecting to server\en"); + ERR_print_errors_fp(stderr); + /* whatever ... */ +} + +if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error establishing SSL connection\en"); + ERR_print_errors_fp(stderr); + /* whatever ... */ +} + +/* Could examine ssl here to get connection info */ + +BIO_puts(sbio, "GET / HTTP/1.0\en\en"); +for (;;) { + len = BIO_read(sbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(out, tmpbuf, len); +} +BIO_free_all(sbio); +BIO_free(out); +.Ed +.Pp +Here is a simple server example. +It makes use of a buffering +.Vt BIO +to allow lines to be read from the +.Vt SSL +.Vt BIO +using +.Xr BIO_gets 3 . +It creates a pseudo web page containing the actual request from a client and +also echoes the request to standard output. +.Bd -literal +BIO *sbio, *bbio, *acpt, *out; +int len; +char tmpbuf[1024]; +SSL_CTX *ctx; +SSL *ssl; + +ERR_load_crypto_strings(); +ERR_load_SSL_strings(); +OpenSSL_add_all_algorithms(); + +/* Might seed PRNG here */ + +ctx = SSL_CTX_new(SSLv23_server_method()); + +if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) + || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) + || !SSL_CTX_check_private_key(ctx)) { + fprintf(stderr, "Error setting up SSL_CTX\en"); + ERR_print_errors_fp(stderr); + return 0; +} + +/* + * Might do other things here like setting verify locations and DH and/or + * RSA temporary key callbacks + */ + +/* New SSL BIO setup as server */ +sbio = BIO_new_ssl(ctx,0); + +BIO_get_ssl(sbio, &ssl); + +if (!ssl) { + fprintf(stderr, "Can't locate SSL pointer\en"); + /* whatever ... */ +} + +/* Don't want any retries */ +SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); + +/* Create the buffering BIO */ + +bbio = BIO_new(BIO_f_buffer()); + +/* Add to chain */ +sbio = BIO_push(bbio, sbio); + +acpt = BIO_new_accept("4433"); + +/* + * By doing this when a new connection is established we automatically + * have sbio inserted into it. The BIO chain is now 'swallowed' by the + * accept BIO and will be freed when the accept BIO is freed. + */ + +BIO_set_accept_bios(acpt,sbio); + +out = BIO_new_fp(stdout, BIO_NOCLOSE); + +/* Setup accept BIO */ +if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error setting up accept BIO\en"); + ERR_print_errors_fp(stderr); + return 0; +} + +/* Now wait for incoming connection */ +if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error in connection\en"); + ERR_print_errors_fp(stderr); + return 0; +} + +/* We only want one connection so remove and free accept BIO */ + +sbio = BIO_pop(acpt); + +BIO_free_all(acpt); + +if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error in SSL handshake\en"); + ERR_print_errors_fp(stderr); + return 0; +} + +BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent-type: text/plain\er\en\er\en"); +BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en"); +BIO_puts(sbio, "--------------------------------------------------\er\en"); + +for (;;) { + len = BIO_gets(sbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(sbio, tmpbuf, len); + BIO_write(out, tmpbuf, len); + /* Look for blank line signifying end of headers */ + if ((tmpbuf[0] == '\er') || (tmpbuf[0] == '\en')) + break; +} + +BIO_puts(sbio, "--------------------------------------------------\er\en"); +BIO_puts(sbio, "\er\en"); + +/* Since there is a buffering BIO present we had better flush it */ +BIO_flush(sbio); + +BIO_free_all(sbio); +.Ed +.Sh BUGS +In OpenSSL versions before 1.0.0 the +.Xr BIO_pop 3 +call was handled incorrectly: +the I/O BIO reference count was incorrectly incremented (instead of +decremented) and dissociated with the +.Vt SSL +.Vt BIO +even if the +.Vt SSL +.Vt BIO +was not +explicitly being popped (e.g., a pop higher up the chain). +Applications which included workarounds for this bug (e.g., freeing BIOs more +than once) should be modified to handle this fix or they may free up an already +freed +.Vt BIO . diff --git a/src/lib/libssl/man/Makefile b/src/lib/libssl/man/Makefile new file mode 100644 index 0000000000..76afab5718 --- /dev/null +++ b/src/lib/libssl/man/Makefile @@ -0,0 +1,93 @@ +# $OpenBSD: Makefile,v 1.36 2016/11/05 15:32:19 schwarze Exp $ + +.include + +MAN = BIO_f_ssl.3 \ + SSL_CIPHER_get_name.3 \ + SSL_COMP_add_compression_method.3 \ + SSL_CTX_add_extra_chain_cert.3 \ + SSL_CTX_add_session.3 \ + SSL_CTX_ctrl.3 \ + SSL_CTX_flush_sessions.3 \ + SSL_CTX_free.3 \ + SSL_CTX_get_ex_new_index.3 \ + SSL_CTX_get_verify_mode.3 \ + SSL_CTX_load_verify_locations.3 \ + SSL_CTX_new.3 \ + SSL_CTX_sess_number.3 \ + SSL_CTX_sess_set_cache_size.3 \ + SSL_CTX_sess_set_get_cb.3 \ + SSL_CTX_sessions.3 \ + SSL_CTX_set_cert_store.3 \ + SSL_CTX_set_cert_verify_callback.3 \ + SSL_CTX_set_cipher_list.3 \ + SSL_CTX_set_client_CA_list.3 \ + SSL_CTX_set_client_cert_cb.3 \ + SSL_CTX_set_default_passwd_cb.3 \ + SSL_CTX_set_generate_session_id.3 \ + SSL_CTX_set_info_callback.3 \ + SSL_CTX_set_max_cert_list.3 \ + SSL_CTX_set_mode.3 \ + SSL_CTX_set_msg_callback.3 \ + SSL_CTX_set_options.3 \ + SSL_CTX_set_psk_client_callback.3 \ + SSL_CTX_set_quiet_shutdown.3 \ + SSL_CTX_set_session_cache_mode.3 \ + SSL_CTX_set_session_id_context.3 \ + SSL_CTX_set_ssl_version.3 \ + SSL_CTX_set_timeout.3 \ + SSL_CTX_set_tmp_dh_callback.3 \ + SSL_CTX_set_tmp_rsa_callback.3 \ + SSL_CTX_set_verify.3 \ + SSL_CTX_use_certificate.3 \ + SSL_CTX_use_psk_identity_hint.3 \ + SSL_SESSION_free.3 \ + SSL_SESSION_get_ex_new_index.3 \ + SSL_SESSION_get_time.3 \ + SSL_accept.3 \ + SSL_alert_type_string.3 \ + SSL_clear.3 \ + SSL_connect.3 \ + SSL_do_handshake.3 \ + SSL_free.3 \ + SSL_get_SSL_CTX.3 \ + SSL_get_ciphers.3 \ + SSL_get_client_CA_list.3 \ + SSL_get_current_cipher.3 \ + SSL_get_default_timeout.3 \ + SSL_get_error.3 \ + SSL_get_ex_data_X509_STORE_CTX_idx.3 \ + SSL_get_ex_new_index.3 \ + SSL_get_fd.3 \ + SSL_get_peer_cert_chain.3 \ + SSL_get_peer_certificate.3 \ + SSL_get_psk_identity.3 \ + SSL_get_rbio.3 \ + SSL_get_session.3 \ + SSL_get_verify_result.3 \ + SSL_get_version.3 \ + SSL_library_init.3 \ + SSL_load_client_CA_file.3 \ + SSL_new.3 \ + SSL_pending.3 \ + SSL_read.3 \ + SSL_rstate_string.3 \ + SSL_session_reused.3 \ + SSL_set_bio.3 \ + SSL_set_connect_state.3 \ + SSL_set_fd.3 \ + SSL_set_session.3 \ + SSL_set_shutdown.3 \ + SSL_set_verify_result.3 \ + SSL_shutdown.3 \ + SSL_state_string.3 \ + SSL_want.3 \ + SSL_write.3 \ + d2i_SSL_SESSION.3 \ + ssl.3 + +all clean cleandir depend includes obj tags: + +install: maninstall + +.include diff --git a/src/lib/libssl/man/SSL_CIPHER_get_name.3 b/src/lib/libssl/man/SSL_CIPHER_get_name.3 new file mode 100644 index 0000000000..c4661c8faf --- /dev/null +++ b/src/lib/libssl/man/SSL_CIPHER_get_name.3 @@ -0,0 +1,196 @@ +.\" +.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CIPHER_GET_NAME 3 +.Os +.Sh NAME +.Nm SSL_CIPHER_get_name , +.Nm SSL_CIPHER_get_bits , +.Nm SSL_CIPHER_get_version , +.Nm SSL_CIPHER_description +.Nd get SSL_CIPHER properties +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft const char * +.Fn SSL_CIPHER_get_name "const SSL_CIPHER *cipher" +.Ft int +.Fn SSL_CIPHER_get_bits "const SSL_CIPHER *cipher" "int *alg_bits" +.Ft char * +.Fn SSL_CIPHER_get_version "const SSL_CIPHER *cipher" +.Ft char * +.Fn SSL_CIPHER_description "const SSL_CIPHER *cipher" "char *buf" "int size" +.Sh DESCRIPTION +.Fn SSL_CIPHER_get_name +returns a pointer to the name of +.Fa cipher . +If the +argument is the +.Dv NULL +pointer, a pointer to the constant value +.Qq NONE +is returned. +.Pp +.Fn SSL_CIPHER_get_bits +returns the number of secret bits used for +.Fa cipher . +If +.Fa alg_bits +is not +.Dv NULL , +it contains the number of bits processed by the +chosen algorithm. +If +.Fa cipher +is +.Dv NULL , +0 is returned. +.Pp +.Fn SSL_CIPHER_get_version +returns a string which indicates the SSL/TLS protocol version that first +defined the cipher. +This is currently +.Qq SSLv2 +or +.Qq TLSv1/SSLv3 . +In some cases it should possibly return +.Qq TLSv1.2 +but the function does not; use +.Xr SSL_CIPHER_description 3 +instead. +If +.Fa cipher +is +.Dv NULL , +.Qq (NONE) +is returned. +.Pp +.Fn SSL_CIPHER_description +returns a textual description of the cipher used into the buffer +.Fa buf +of length +.Fa len +provided. +If +.Fa buf +is +.Dv NULL , +a buffer is allocated using +.Xr asprintf 3 ; +that buffer should be freed using the +.Xr free 3 +function. +If +.Fa len +is too small, or if +.Fa buf +is +.Dv NULL +and the allocation fails, a pointer to the string +.Qq Buffer too small +is returned. +.Sh NOTES +The number of bits processed can be different from the secret bits. +For example, an export cipher like EXP-RC4-MD5 has only 40 secret bits. +The algorithm does use the full 128 bits (which would be returned for +.Fa alg_bits ) , +but 88 bits are fixed. +The search space is hence only 40 bits. +.Pp +The string returned by +.Fn SSL_CIPHER_description +in case of success consists +of cleartext information separated by one or more blanks in the following +sequence: +.Bl -tag -width Ds +.It Aq Ar ciphername +Textual representation of the cipher name. +.It Aq Ar protocol version +Protocol version: +.Em SSLv2 , +.Em SSLv3 , +.Em TLSv1.2 . +The TLSv1.0 ciphers are flagged with SSLv3. +No new ciphers were added by TLSv1.1. +.It Kx= Ns Aq Ar key exchange +Key exchange method: +.Em RSA +(for export ciphers as +.Em RSA(512) +or +.Em RSA(1024) ) , +.Em DH +(for export ciphers as +.Em DH(512) +or +.Em DH(1024) ) , +.Em DH/RSA , +.Em DH/DSS , +.Em Fortezza . +.It Au= Ns Aq Ar authentication +Authentication method: +.Em RSA , +.Em DSS , +.Em DH , +.Em None . +.Em None +is the representation of anonymous ciphers. +.It Enc= Ns Aq Ar symmetric encryption method +Encryption method with number of secret bits: +.Em DES(40) , +.Em DES(56) , +.Em 3DES(168) , +.Em RC4(40) , +.Em RC4(56) , +.Em RC4(64) , +.Em RC4(128) , +.Em RC2(40) , +.Em RC2(56) , +.Em RC2(128) , +.Em IDEA(128) , +.Em Fortezza , +.Em None . +.It Mac= Ns Aq Ar message authentication code +Message digest: +.Em MD5 , +.Em SHA1 . +.It Aq Ar export flag +If the cipher is flagged exportable with respect to old US crypto +regulations, the word +.Dq export +is printed. +.El +.Sh RETURN VALUES +See +.Sx DESCRIPTION +.Sh EXAMPLES +Some examples for the output of +.Fn SSL_CIPHER_description : +.D1 "EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1" +.D1 "EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1" +.D1 "RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5" +.D1 "EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export" +.Pp +A complete list can be retrieved by invoking the following command: +.Pp +.Dl $ openssl ciphers -v ALL +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_get_ciphers 3 , +.Xr SSL_get_current_cipher 3 +.Sh BUGS +If +.Fn SSL_CIPHER_description +is called with +.Fa cipher +being +.Dv NULL , +the library crashes. +.Pp +If +.Fn SSL_CIPHER_description +cannot handle a built-in cipher, +the according description of the cipher property is +.Qq unknown . +This case should not occur. diff --git a/src/lib/libssl/man/SSL_COMP_add_compression_method.3 b/src/lib/libssl/man/SSL_COMP_add_compression_method.3 new file mode 100644 index 0000000000..957b2e8bed --- /dev/null +++ b/src/lib/libssl/man/SSL_COMP_add_compression_method.3 @@ -0,0 +1,68 @@ +.\" +.\" $OpenBSD: SSL_COMP_add_compression_method.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_COMP_ADD_COMPRESSION_METHOD 3 +.Os +.Sh NAME +.Nm SSL_COMP_add_compression_method +.Nd handle SSL/TLS integrated compression methods +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_COMP_add_compression_method "int id" "COMP_METHOD *cm" +.Sh DESCRIPTION +.Fn SSL_COMP_add_compression_method +adds the compression method +.Fa cm +with the identifier +.Fa id +to the list of available compression methods. +This list is globally maintained for all SSL operations within this application. +It cannot be set for specific SSL_CTX or SSL objects. +.Sh NOTES +The TLS standard (or SSLv3) allows the integration of compression methods +into the communication. +The TLS RFC does however not specify compression methods or their corresponding +identifiers, so there is currently no compatible way to integrate compression +with unknown peers. +It is therefore currently not recommended to integrate compression into +applications. +Applications for non-public use may agree on certain compression methods. +Using different compression methods with the same identifier will lead to +connection failure. +.Pp +An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) +will unconditionally send the list of all compression methods enabled with +.Fn SSL_COMP_add_compression_method +to the server during the handshake. +Unlike the mechanisms to set a cipher list, there is no method available to +restrict the list of compression method on a per connection basis. +.Pp +An OpenSSL server will match the identifiers listed by a client against +its own compression methods and will unconditionally activate compression +when a matching identifier is found. +There is no way to restrict the list of compression methods supported on a per +connection basis. +.Pp +The OpenSSL library has the compression methods +.Fn COMP_rle +and (when especially enabled during compilation) +.Fn COMP_zlib +available. +.Sh WARNINGS +Once the identities of the compression methods for the TLS protocol have +been standardized, the compression API will most likely be changed. +Using it in the current state is not recommended. +.Sh RETURN VALUES +.Fn SSL_COMP_add_compression_method +may return the following values: +.Bl -tag -width Ds +.It 0 +The operation succeeded. +.It 1 +The operation failed. +Check the error queue to find out the reason. +.El +.Sh SEE ALSO +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_CTX_add_extra_chain_cert.3 b/src/lib/libssl/man/SSL_CTX_add_extra_chain_cert.3 new file mode 100644 index 0000000000..b7ece44811 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_add_extra_chain_cert.3 @@ -0,0 +1,45 @@ +.\" +.\" $OpenBSD: SSL_CTX_add_extra_chain_cert.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_ADD_EXTRA_CHAIN_CERT 3 +.Os +.Sh NAME +.Nm SSL_CTX_add_extra_chain_cert +.Nd add certificate to chain +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_add_extra_chain_cert "SSL_CTX ctx" "X509 *x509" +.Sh DESCRIPTION +.Fn SSL_CTX_add_extra_chain_cert +adds the certificate +.Fa x509 +to the certificate chain presented together with the certificate. +Several certificates can be added one after the other. +.Sh NOTES +When constructing the certificate chain, the chain will be formed from +these certificates explicitly specified. +If no chain is specified, the library will try to complete the chain from the +available CA certificates in the trusted CA storage, see +.Xr SSL_CTX_load_verify_locations 3 . +.Pp +The x509 certificate provided to +.Fn SSL_CTX_add_extra_chain_cert +will be freed by the library when the +.Vt SSL_CTX +is destroyed. +An application +.Em should not +free the +.Fa x509 +object. +.Sh RETURN VALUES +.Fn SSL_CTX_add_extra_chain_cert +returns 1 on success. +Check out the error stack to find out the reason for failure otherwise. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_use_certificate 3 diff --git a/src/lib/libssl/man/SSL_CTX_add_session.3 b/src/lib/libssl/man/SSL_CTX_add_session.3 new file mode 100644 index 0000000000..fe60c6ea92 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_add_session.3 @@ -0,0 +1,90 @@ +.\" +.\" $OpenBSD: SSL_CTX_add_session.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_ADD_SESSION 3 +.Os +.Sh NAME +.Nm SSL_CTX_add_session , +.Nm SSL_add_session , +.Nm SSL_CTX_remove_session , +.Nm SSL_remove_session +.Nd manipulate session cache +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_add_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Ft int +.Fn SSL_add_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Ft int +.Fn SSL_CTX_remove_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Ft int +.Fn SSL_remove_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Sh DESCRIPTION +.Fn SSL_CTX_add_session +adds the session +.Fa c +to the context +.Fa ctx . +The reference count for session +.Fa c +is incremented by 1. +If a session with the same session id already exists, +the old session is removed by calling +.Xr SSL_SESSION_free 3 . +.Pp +.Fn SSL_CTX_remove_session +removes the session +.Fa c +from the context +.Fa ctx . +.Xr SSL_SESSION_free 3 +is called once for +.Fa c . +.Pp +.Fn SSL_add_session +and +.Fn SSL_remove_session +are synonyms for their +.Fn SSL_CTX_* +counterparts. +.Sh NOTES +When adding a new session to the internal session cache, it is examined +whether a session with the same session id already exists. +In this case it is assumed that both sessions are identical. +If the same session is stored in a different +.Vt SSL_SESSION +object, the old session is removed and replaced by the new session. +If the session is actually identical (the +.Vt SSL_SESSION +object is identical), +.Fn SSL_CTX_add_session +is a no-op, and the return value is 0. +.Pp +If a server +.Vt SSL_CTX +is configured with the +.Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +flag then the internal cache will not be populated automatically by new +sessions negotiated by the SSL/TLS implementation, even though the internal +cache will be searched automatically for session-resume requests (the +latter can be suppressed by +.Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP ) . +So the application can use +.Fn SSL_CTX_add_session +directly to have full control over the sessions that can be resumed if desired. +.Sh RETURN VALUES +The following values are returned by all functions: +.Bl -tag -width Ds +.It 0 +The operation failed. +In case of the add operation, it was tried to add the same (identical) session +twice. +In case of the remove operation, the session was not found in the cache. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_SESSION_free 3 diff --git a/src/lib/libssl/man/SSL_CTX_ctrl.3 b/src/lib/libssl/man/SSL_CTX_ctrl.3 new file mode 100644 index 0000000000..47cf609491 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_ctrl.3 @@ -0,0 +1,49 @@ +.\" +.\" $OpenBSD: SSL_CTX_ctrl.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_CTRL 3 +.Os +.Sh NAME +.Nm SSL_CTX_ctrl , +.Nm SSL_CTX_callback_ctrl , +.Nm SSL_ctrl , +.Nm SSL_callback_ctrl +.Nd internal handling functions for SSL_CTX and SSL objects +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_ctrl "SSL_CTX *ctx" "int cmd" "long larg" "void *parg" +.Ft long +.Fn SSL_CTX_callback_ctrl "SSL_CTX *" "int cmd" "void (*fp)()" +.Ft long +.Fn SSL_ctrl "SSL *ssl" "int cmd" "long larg" "void *parg" +.Ft long +.Fn SSL_callback_ctrl "SSL *" "int cmd" "void (*fp)()" +.Sh DESCRIPTION +The +.Fn SSL_*_ctrl +family of functions is used to manipulate settings of +the +.Vt SSL_CTX +and +.Vt SSL +objects. +Depending on the command +.Fa cmd +the arguments +.Fa larg , +.Fa parg , +or +.Fa fp +are evaluated. +These functions should never be called directly. +All functionalities needed are made available via other functions or macros. +.Sh RETURN VALUES +The return values of the +.Fn SSL*_ctrl +functions depend on the command supplied via the +.Fn cmd +parameter. +.Sh SEE ALSO +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_CTX_flush_sessions.3 b/src/lib/libssl/man/SSL_CTX_flush_sessions.3 new file mode 100644 index 0000000000..11d33e81a1 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_flush_sessions.3 @@ -0,0 +1,57 @@ +.\" +.\" $OpenBSD: SSL_CTX_flush_sessions.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_FLUSH_SESSIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_flush_sessions , +.Nm SSL_flush_sessions +.Nd remove expired sessions +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_flush_sessions "SSL_CTX *ctx" "long tm" +.Ft void +.Fn SSL_flush_sessions "SSL_CTX *ctx" "long tm" +.Sh DESCRIPTION +.Fn SSL_CTX_flush_sessions +causes a run through the session cache of +.Fa ctx +to remove sessions expired at time +.Fa tm . +.Pp +.Fn SSL_flush_sessions +is a synonym for +.Fn SSL_CTX_flush_sessions . +.Sh NOTES +If enabled, the internal session cache will collect all sessions established +up to the specified maximum number (see +.Fn SSL_CTX_sess_set_cache_size ) . +As sessions will not be reused ones they are expired, they should be +removed from the cache to save resources. +This can either be done automatically whenever 255 new sessions were +established (see +.Xr SSL_CTX_set_session_cache_mode 3 ) +or manually by calling +.Fn SSL_CTX_flush_sessions . +.Pp +The parameter +.Fa tm +specifies the time which should be used for the +expiration test, in most cases the actual time given by +.Fn time 0 +will be used. +.Pp +.Fn SSL_CTX_flush_sessions +will only check sessions stored in the internal cache. +When a session is found and removed, the +.Va remove_session_cb +is however called to synchronize with the external cache (see +.Xr SSL_CTX_sess_set_get_cb 3 ) . +.Sh RETURN VALUES +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_CTX_set_timeout 3 diff --git a/src/lib/libssl/man/SSL_CTX_free.3 b/src/lib/libssl/man/SSL_CTX_free.3 new file mode 100644 index 0000000000..24a19ffaf6 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_free.3 @@ -0,0 +1,53 @@ +.\" +.\" $OpenBSD: SSL_CTX_free.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_FREE 3 +.Os +.Sh NAME +.Nm SSL_CTX_free +.Nd free an allocated SSL_CTX object +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_free "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_free +decrements the reference count of +.Fa ctx , +and removes the +.Vt SSL_CTX +object pointed to by +.Fa ctx +and frees up the allocated memory if the reference count has reached 0. +If +.Fa ctx +is a +.Dv NULL +pointer, no action occurs. +.Pp +It also calls the +.Xr free 3 Ns ing +procedures for indirectly affected items, if applicable: +the session cache, the list of ciphers, the list of Client CAs, +the certificates and keys. +.Sh WARNINGS +If a session-remove callback is set +.Pq Xr SSL_CTX_sess_set_remove_cb 3 , +this callback will be called for each session being freed from +.Fa ctx Ns 's +session cache. +This implies that all corresponding sessions from an external session cache are +removed as well. +If this is not desired, the user should explicitly unset the callback by +calling +.Fn SSL_CTX_sess_set_remove_cb ctx NULL +prior to calling +.Fn SSL_CTX_free . +.Sh RETURN VALUES +.Fn SSL_CTX_free +does not provide diagnostic information. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_sess_set_get_cb 3 diff --git a/src/lib/libssl/man/SSL_CTX_get_ex_new_index.3 b/src/lib/libssl/man/SSL_CTX_get_ex_new_index.3 new file mode 100644 index 0000000000..8afb1ebc96 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_get_ex_new_index.3 @@ -0,0 +1,70 @@ +.\" +.\" $OpenBSD: SSL_CTX_get_ex_new_index.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm SSL_CTX_get_ex_new_index , +.Nm SSL_CTX_set_ex_data , +.Nm SSL_CTX_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fn SSL_CTX_set_ex_data "SSL_CTX *ctx" "int idx" "void *arg" +.Ft void * +.Fn SSL_CTX_get_ex_data "const SSL_CTX *ctx" "int idx" +.Bd -literal + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); +.Ed +.Sh DESCRIPTION +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.Pp +.Fn SSL_CTX_get_ex_new_index +is used to register a new index for application specific data. +.Pp +.Fn SSL_CTX_set_ex_data +is used to store application data at +.Fa arg +for +.Fa idx +into the +.Fa ctx +object. +.Pp +.Fn SSL_CTX_get_ex_data +is used to retrieve the information for +.Fa idx +from +.Fa ctx . +.Pp +A detailed description for the +.Fn *_get_ex_new_index +functionality can be found in +.Xr RSA_get_ex_new_index 3 . +The +.Fn *_get_ex_data +and +.Fn *_set_ex_data +functionality is described in +.Xr CRYPTO_set_ex_data 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_CTX_get_verify_mode.3 b/src/lib/libssl/man/SSL_CTX_get_verify_mode.3 new file mode 100644 index 0000000000..c8ada8fb21 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_get_verify_mode.3 @@ -0,0 +1,73 @@ +.\" +.\" $OpenBSD: SSL_CTX_get_verify_mode.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_GET_VERIFY_MODE 3 +.Os +.Sh NAME +.Nm SSL_CTX_get_verify_mode , +.Nm SSL_get_verify_mode , +.Nm SSL_CTX_get_verify_depth , +.Nm SSL_get_verify_depth , +.Nm SSL_get_verify_callback , +.Nm SSL_CTX_get_verify_callback +.Nd get currently set verification parameters +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_get_verify_mode "const SSL_CTX *ctx" +.Ft int +.Fn SSL_get_verify_mode "const SSL *ssl" +.Ft int +.Fn SSL_CTX_get_verify_depth "const SSL_CTX *ctx" +.Ft int +.Fn SSL_get_verify_depth "const SSL *ssl" +.Ft int +.Fo "(*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))" +.Fa int "X509_STORE_CTX *" +.Fc +.Ft int +.Fo "(*SSL_get_verify_callback(const SSL *ssl))" +.Fa int "X509_STORE_CTX *" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_get_verify_mode +returns the verification mode currently set in +.Fa ctx . +.Pp +.Fn SSL_get_verify_mode +returns the verification mode currently set in +.Fa ssl . +.Pp +.Fn SSL_CTX_get_verify_depth +returns the verification depth limit currently set +in +.Fa ctx . +If no limit has been explicitly set, +\(mi1 is returned and the default value will be used. +.Pp +.Fn SSL_get_verify_depth +returns the verification depth limit currently set in +.Fa ssl . +If no limit has been explicitly set, +\(mi1 is returned and the default value will be used. +.Pp +.Fn SSL_CTX_get_verify_callback +returns a function pointer to the verification callback currently set in +.Fa ctx . +If no callback was explicitly set, the +.Dv NULL +pointer is returned and the default callback will be used. +.Pp +.Fn SSL_get_verify_callback +returns a function pointer to the verification callback currently set in +.Fa ssl . +If no callback was explicitly set, the +.Dv NULL +pointer is returned and the default callback will be used. +.Sh RETURN VALUES +See +.Sx DESCRIPTION +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 diff --git a/src/lib/libssl/man/SSL_CTX_load_verify_locations.3 b/src/lib/libssl/man/SSL_CTX_load_verify_locations.3 new file mode 100644 index 0000000000..0d023cb475 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_load_verify_locations.3 @@ -0,0 +1,161 @@ +.\" +.\" $OpenBSD: SSL_CTX_load_verify_locations.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_LOAD_VERIFY_LOCATIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_load_verify_locations +.Nd set default locations for trusted CA certificates +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_load_verify_locations +.Fa "SSL_CTX *ctx" "const char *CAfile" "const char *CApath" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_load_verify_locations +specifies the locations for +.Fa ctx , +at which CA certificates for verification purposes are located. +The certificates available via +.Fa CAfile +and +.Fa CApath +are trusted. +.Sh NOTES +If +.Fa CAfile +is not +.Dv NULL , +it points to a file of CA certificates in PEM format. +The file can contain several CA certificates identified by sequences of: +.Bd -literal + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- +.Ed +Before, between, and after the certificates arbitrary text is allowed which can +be used, e.g., for descriptions of the certificates. +.Pp +The +.Fa CAfile +is processed on execution of the +.Fn SSL_CTX_load_verify_locations +function. +.Pp +If +.Fa CApath +is not NULL, it points to a directory containing CA certificates in PEM format. +The files each contain one CA certificate. +The files are looked up by the CA subject name hash value, +which must hence be available. +If more than one CA certificate with the same name hash value exist, +the extension must be different (e.g., +.Pa 9d66eef0.0 , +.Pa 9d66eef0.1 , +etc.). +The search is performed in the ordering of the extension number, +regardless of other properties of the certificates. +.Pp +The certificates in +.Fa CApath +are only looked up when required, e.g., when building the certificate chain or +when actually performing the verification of a peer certificate. +.Pp +When looking up CA certificates, the OpenSSL library will first search the +certificates in +.Fa CAfile , +then those in +.Fa CApath . +Certificate matching is done based on the subject name, the key identifier (if +present), and the serial number as taken from the certificate to be verified. +If these data do not match, the next certificate will be tried. +If a first certificate matching the parameters is found, +the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. +.Pp +In server mode, when requesting a client certificate, the server must send +the list of CAs of which it will accept client certificates. +This list is not influenced by the contents of +.Fa CAfile +or +.Fa CApath +and must explicitly be set using the +.Xr SSL_CTX_set_client_CA_list 3 +family of functions. +.Pp +When building its own certificate chain, an OpenSSL client/server will try to +fill in missing certificates from +.Fa CAfile Ns / Fa CApath , +if the +certificate chain was not explicitly specified (see +.Xr SSL_CTX_add_extra_chain_cert 3 +and +.Xr SSL_CTX_use_certificate 3 ) . +.Sh WARNINGS +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. +This may lead to unexpected results if the same CA certificate is available +with different expiration dates. +If a +.Dq certificate expired +verification error occurs, no other certificate will be searched. +Make sure to not have expired certificates mixed with valid ones. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The operation failed because +.Fa CAfile +and +.Fa CApath +are +.Dv NULL +or the processing at one of the locations specified failed. +Check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh EXAMPLES +Generate a CA certificate file with descriptive text from the CA certificates +.Pa ca1.pem +.Pa ca2.pem +.Pa ca3.pem : +.Bd -literal +#!/bin/sh +rm CAfile.pem +for i in ca1.pem ca2.pem ca3.pem; do + openssl x509 -in $i -text >> CAfile.pem +done +.Ed +.Pp +Prepare the directory /some/where/certs containing several CA certificates +for use as +.Fa CApath : +.Bd -literal +$ cd /some/where/certs +$ rm -f *.[0-9]* *.r[0-9]* +$ for c in *.pem; do +> [ "$c" = "*.pem" ] && continue +> hash=$(openssl x509 -noout -hash -in "$c") +> if egrep -q -- '-BEGIN( X509 | TRUSTED | )CERTIFICATE-' "$c"; then +> suf=0 +> while [ -e $hash.$suf ]; do suf=$(( $suf + 1 )); done +> ln -s "$c" $hash.$suf +> fi +> if egrep -q -- '-BEGIN X509 CRL-' "$c"; then +> suf=0 +> while [ -e $hash.r$suf ]; do suf=$(( $suf + 1 )); done +> ln -s "$c" $hash.r$suf +> fi +> done +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_set_cert_store 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_get_client_CA_list 3 diff --git a/src/lib/libssl/man/SSL_CTX_new.3 b/src/lib/libssl/man/SSL_CTX_new.3 new file mode 100644 index 0000000000..872d302b24 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_new.3 @@ -0,0 +1,111 @@ +.\" +.\" $OpenBSD: SSL_CTX_new.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_NEW 3 +.Os +.Sh NAME +.Nm SSL_CTX_new , +.Nm SSLv3_method , +.Nm SSLv3_server_method , +.Nm SSLv3_client_method , +.Nm TLSv1_method , +.Nm TLSv1_server_method , +.Nm TLSv1_client_method , +.Nm TLSv1_1_method , +.Nm TLSv1_1_server_method , +.Nm TLSv1_1_client_method , +.Nm SSLv23_method , +.Nm SSLv23_server_method , +.Nm SSLv23_client_method +.Nd create a new SSL_CTX object as framework for TLS/SSL enabled functions +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft SSL_CTX * +.Fn SSL_CTX_new "const SSL_METHOD *method" +.Sh DESCRIPTION +.Fn SSL_CTX_new +creates a new +.Vt SSL_CTX +object as framework to establish TLS/SSL enabled connections. +.Sh NOTES +The +.Vt SSL_CTX +object uses +.Fa method +as its connection method. +The methods exist in a generic type (for client and server use), +a server only type, and a client only type. +.Fa method +can be of the following types: +.Bl -tag -width Ds +.It Fn SSLv3_method void , Fn SSLv3_server_method void , \ +Fn SSLv3_client_method void +A TLS/SSL connection established with these methods will only understand the +SSLv3 protocol. +A client will send out SSLv3 client hello messages and will indicate that it +only understands SSLv3. +A server will only understand SSLv3 client hello messages. +Importantly, this means that it will not understand SSLv2 client hello messages +which are widely used for compatibility reasons; see +.Fn SSLv23_*_method . +.It Fn TLSv1_method void , Fn TLSv1_server_method void , \ +Fn TLSv1_client_method void +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. +A client will send out TLSv1 client hello messages and will indicate that it +only understands TLSv1. +A server will only understand TLSv1 client hello messages. +Importantly, this means that it will not understand SSLv2 client hello messages +which are widely used for compatibility reasons; see +.Fn SSLv23_*_method . +It will also not understand SSLv3 client hello messages. +.It Fn SSLv23_method void , Fn SSLv23_server_method void , \ +Fn SSLv23_client_method void +A TLS/SSL connection established with these methods may understand the SSLv3, +TLSv1, TLSv1.1 and TLSv1.2 protocols. +.Pp +A client will send out TLSv1 client hello messages including extensions and +will indicate that it also understands TLSv1.1, TLSv1.2 and permits a fallback +to SSLv3. +A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. +This is the best choice when compatibility is a concern. +.El +.Pp +The list of protocols available can later be limited using the +.Dv SSL_OP_NO_SSLv3 , +.Dv SSL_OP_NO_TLSv1 , +.Dv SSL_OP_NO_TLSv1_1 , +and +.Dv SSL_OP_NO_TLSv1_2 +options of the +.Fn SSL_CTX_set_options +or +.Fn SSL_set_options +functions. +Using these options it is possible to choose, for example, +.Fn SSLv23_server_method +and be able to negotiate with all possible clients, +but to only allow newer protocols like TLSv1, TLSv1.1 or TLS v1.2. +.Pp +.Fn SSL_CTX_new +initializes the list of ciphers, the session cache setting, the callbacks, +the keys and certificates, and the options to its default values. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +The creation of a new +.Vt SSL_CTX +object failed. +Check the error stack to find out the reason. +.It Pointer to an SSL_CTX object +The return value points to an allocated +.Vt SSL_CTX +object. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_CTX_free 3 , +.Xr SSL_set_connect_state 3 diff --git a/src/lib/libssl/man/SSL_CTX_sess_number.3 b/src/lib/libssl/man/SSL_CTX_sess_number.3 new file mode 100644 index 0000000000..3171fe21ea --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_sess_number.3 @@ -0,0 +1,104 @@ +.\" +.\" $OpenBSD: SSL_CTX_sess_number.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SESS_NUMBER 3 +.Os +.Sh NAME +.Nm SSL_CTX_sess_number , +.Nm SSL_CTX_sess_connect , +.Nm SSL_CTX_sess_connect_good , +.Nm SSL_CTX_sess_connect_renegotiate , +.Nm SSL_CTX_sess_accept , +.Nm SSL_CTX_sess_accept_good , +.Nm SSL_CTX_sess_accept_renegotiate , +.Nm SSL_CTX_sess_hits , +.Nm SSL_CTX_sess_cb_hits , +.Nm SSL_CTX_sess_misses , +.Nm SSL_CTX_sess_timeouts , +.Nm SSL_CTX_sess_cache_full +.Nd obtain session cache statistics +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_sess_number "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_connect "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_connect_good "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_connect_renegotiate "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_accept "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_accept_good "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_accept_renegotiate "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_hits "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_cb_hits "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_misses "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_timeouts "SSL_CTX *ctx" +.Ft long +.Fn SSL_CTX_sess_cache_full "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_sess_number +returns the current number of sessions in the internal session cache. +.Pp +.Fn SSL_CTX_sess_connect +returns the number of started SSL/TLS handshakes in client mode. +.Pp +.Fn SSL_CTX_sess_connect_good +returns the number of successfully established SSL/TLS sessions in client mode. +.Pp +.Fn SSL_CTX_sess_connect_renegotiate +returns the number of start renegotiations in client mode. +.Pp +.Fn SSL_CTX_sess_accept +returns the number of started SSL/TLS handshakes in server mode. +.Pp +.Fn SSL_CTX_sess_accept_good +returns the number of successfully established SSL/TLS sessions in server mode. +.Pp +.Fn SSL_CTX_sess_accept_renegotiate +returns the number of start renegotiations in server mode. +.Pp +.Fn SSL_CTX_sess_hits +returns the number of successfully reused sessions. +In client mode a session set with +.Xr SSL_set_session 3 +successfully reused is counted as a hit. +In server mode a session successfully retrieved from internal or external cache +is counted as a hit. +.Pp +.Fn SSL_CTX_sess_cb_hits +returns the number of successfully retrieved sessions from the external session +cache in server mode. +.Pp +.Fn SSL_CTX_sess_misses +returns the number of sessions proposed by clients that were not found in the +internal session cache in server mode. +.Pp +.Fn SSL_CTX_sess_timeouts +returns the number of sessions proposed by clients and either found in the +internal or external session cache in server mode, +but that were invalid due to timeout. +These sessions are not included in the +.Fn SSL_CTX_sess_hits +count. +.Pp +.Fn SSL_CTX_sess_cache_full +returns the number of sessions that were removed because the maximum session +cache size was exceeded. +.Sh RETURN VALUES +The functions return the values indicated in the +.Sx DESCRIPTION +section. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_set_session 3 diff --git a/src/lib/libssl/man/SSL_CTX_sess_set_cache_size.3 b/src/lib/libssl/man/SSL_CTX_sess_set_cache_size.3 new file mode 100644 index 0000000000..1cc6516d20 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_sess_set_cache_size.3 @@ -0,0 +1,55 @@ +.\" +.\" $OpenBSD: SSL_CTX_sess_set_cache_size.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SESS_SET_CACHE_SIZE 3 +.Os +.Sh NAME +.Nm SSL_CTX_sess_set_cache_size , +.Nm SSL_CTX_sess_get_cache_size +.Nd manipulate session cache size +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_sess_set_cache_size "SSL_CTX *ctx" "long t" +.Ft long +.Fn SSL_CTX_sess_get_cache_size "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_sess_set_cache_size +sets the size of the internal session cache of context +.Fa ctx +to +.Fa t . +.Pp +.Fn SSL_CTX_sess_get_cache_size +returns the currently valid session cache size. +.Sh NOTES +The internal session cache size is +.Dv SSL_SESSION_CACHE_MAX_SIZE_DEFAULT , +currently 1024\(mu20, so that up to 20000 sessions can be held. +This size can be modified using the +.Fn SSL_CTX_sess_set_cache_size +call. +A special case is the size 0, which is used for unlimited size. +.Pp +When the maximum number of sessions is reached, +no more new sessions are added to the cache. +New space may be added by calling +.Xr SSL_CTX_flush_sessions 3 +to remove expired sessions. +.Pp +If the size of the session cache is reduced and more sessions are already in +the session cache, +old session will be removed the next time a session shall be added. +This removal is not synchronized with the expiration of sessions. +.Sh RETURN VALUES +.Fn SSL_CTX_sess_set_cache_size +returns the previously valid size. +.Pp +.Fn SSL_CTX_sess_get_cache_size +returns the currently valid size. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_set_session_cache_mode 3 diff --git a/src/lib/libssl/man/SSL_CTX_sess_set_get_cb.3 b/src/lib/libssl/man/SSL_CTX_sess_set_get_cb.3 new file mode 100644 index 0000000000..44ed2cb82a --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_sess_set_get_cb.3 @@ -0,0 +1,159 @@ +.\" +.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SESS_SET_GET_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_sess_set_new_cb , +.Nm SSL_CTX_sess_set_remove_cb , +.Nm SSL_CTX_sess_set_get_cb , +.Nm SSL_CTX_sess_get_new_cb , +.Nm SSL_CTX_sess_get_remove_cb , +.Nm SSL_CTX_sess_get_get_cb +.Nd provide callback functions for server side external session caching +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_sess_set_new_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*new_session_cb)(SSL *, SSL_SESSION *)" +.Fc +.Ft void +.Fo SSL_CTX_sess_set_remove_cb +.Fa "SSL_CTX *ctx" +.Fa "void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)" +.Fc +.Ft void +.Fo SSL_CTX_sess_set_get_cb +.Fa "SSL_CTX *ctx" +.Fa "SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)" +.Fc +.Ft int +.Fo "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" +.Fa "struct ssl_st *ssl" +.Fa "SSL_SESSION *sess" +.Fc +.Ft void +.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))" +.Fa "struct ssl_ctx_st *ctx" +.Fa "SSL_SESSION *sess" +.Fc +.Ft SSL_SESSION * +.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))" +.Fa "struct ssl_st *ssl" +.Fa "unsigned char *data" +.Fa "int len" +.Fa "int *copy" +.Fc +.Ft int +.Fo "(*new_session_cb)" +.Fa "struct ssl_st *ssl" +.Fa "SSL_SESSION *sess" +.Fc +.Ft void +.Fo "(*remove_session_cb)" +.Fa "struct ssl_ctx_st *ctx" +.Fa "SSL_SESSION *sess" +.Fc +.Ft SSL_SESSION * +.Fo "(*get_session_cb)" +.Fa "struct ssl_st *ssl" +.Fa "unsigned char *data" +.Fa "int len" +.Fa "int *copy" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_sess_set_new_cb +sets the callback function which is automatically called whenever a new session +was negotiated. +.Pp +.Fn SSL_CTX_sess_set_remove_cb +sets the callback function which is automatically called whenever a session is +removed by the SSL engine (because it is considered faulty or the session has +become obsolete because of exceeding the timeout value). +.Pp +.Fn SSL_CTX_sess_set_get_cb +sets the callback function which is called whenever a SSL/TLS client proposes +to resume a session but the session cannot be found in the internal session +cache (see +.Xr SSL_CTX_set_session_cache_mode 3 ) . +(SSL/TLS server only.) +.Pp +.Fn SSL_CTX_sess_get_new_cb , +.Fn SSL_CTX_sess_get_remove_cb , +and +.Fn SSL_CTX_sess_get_get_cb +retrieve the function pointers of the provided callback functions. +If a callback function has not been set, the +.Dv NULL +pointer is returned. +.Sh NOTES +In order to allow external session caching, synchronization with the internal +session cache is realized via callback functions. +Inside these callback functions, session can be saved to disk or put into a +database using the +.Xr d2i_SSL_SESSION 3 +interface. +.Pp +The +.Fn new_session_cb +function is called whenever a new session has been negotiated and session +caching is enabled (see +.Xr SSL_CTX_set_session_cache_mode 3 ) . +The +.Fn new_session_cb +is passed the +.Fa ssl +connection and the ssl session +.Fa sess . +If the callback returns 0, the session will be immediately removed again. +.Pp +The +.Fn remove_session_cb +is called whenever the SSL engine removes a session from the internal cache. +This happens when the session is removed because it is expired or when a +connection was not shut down cleanly. +It also happens for all sessions in the internal session cache when +.Xr SSL_CTX_free 3 +is called. +The +.Fn remove_session_cb +function is passed the +.Fa ctx +and the +.Vt ssl +session +.Fa sess . +It does not provide any feedback. +.Pp +The +.Fn get_session_cb +function is only called on SSL/TLS servers with the session id proposed by the +client. +The +.Fn get_session_cb +function is always called, also when session caching was disabled. +The +.Fn get_session_cb +is passed the +.Fa ssl +connection, the session id of length +.Fa length +at the memory location +.Fa data . +With the parameter +.Fa copy +the callback can require the SSL engine to increment the reference count of the +.Vt SSL_SESSION +object, +Normally the reference count is not incremented and therefore the session must +not be explicitly freed with +.Xr SSL_SESSION_free 3 . +.Sh SEE ALSO +.Xr d2i_SSL_SESSION 3 , +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_free 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_SESSION_free 3 diff --git a/src/lib/libssl/man/SSL_CTX_sessions.3 b/src/lib/libssl/man/SSL_CTX_sessions.3 new file mode 100644 index 0000000000..72311699c8 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_sessions.3 @@ -0,0 +1,35 @@ +.\" +.\" $OpenBSD: SSL_CTX_sessions.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SESSIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_sessions +.Nd access internal session cache +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft struct lhash_st * +.Fn SSL_CTX_sessions "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_sessions +returns a pointer to the lhash databases containing the internal session cache +for +.Fa ctx . +.Sh NOTES +The sessions in the internal session cache are kept in an +lhash-type database +(see +.Xr lh_new 3 ) . +It is possible to directly access this database, e.g., for searching. +In parallel, +the sessions form a linked list which is maintained separately from the +lhash operations, +so that the database must not be modified directly but by using the +.Xr SSL_CTX_add_session 3 +family of functions. +.Sh SEE ALSO +.Xr lh_new 3 , +.Xr ssl 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_set_session_cache_mode 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_cert_store.3 b/src/lib/libssl/man/SSL_CTX_set_cert_store.3 new file mode 100644 index 0000000000..fcd531136a --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_cert_store.3 @@ -0,0 +1,80 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_cert_store.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_CERT_STORE 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_cert_store , +.Nm SSL_CTX_get_cert_store +.Nd manipulate X509 certificate verification storage +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_cert_store "SSL_CTX *ctx" "X509_STORE *store" +.Ft X509_STORE * +.Fn SSL_CTX_get_cert_store "const SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_cert_store +setsthe verification storage of +.Fa ctx +to or replaces it with +.Fa store . +If another +.Vt X509_STORE +object is currently set in +.Fa ctx , +it will be +.Xr X509_STORE_free 3 Ns ed. +.Pp +.Fn SSL_CTX_get_cert_store +returns a pointer to the current certificate verification storage. +.Sh NOTES +In order to verify the certificates presented by the peer, trusted CA +certificates must be accessed. +These CA certificates are made available via lookup methods, handled inside the +.Vt X509_STORE . +From the +.Vt X509_STORE +the +.Vt X509_STORE_CTX +used when verifying certificates is created. +.Pp +Typically the trusted certificate store is handled indirectly via using +.Xr SSL_CTX_load_verify_locations 3 . +Using the +.Fn SSL_CTX_set_cert_store +and +.Fn SSL_CTX_get_cert_store +functions it is possible to manipulate the +.Vt X509_STORE +object beyond the +.Xr SSL_CTX_load_verify_locations 3 +call. +.Pp +Currently no detailed documentation on how to use the +.Vt X509_STORE +object is available. +Not all members of the +.Vt X509_STORE +are used when the verification takes place. +So will, for example, the +.Fn verify_callback +be overridden with the +.Fn verify_callback +set via the +.Xr SSL_CTX_set_verify 3 +family of functions. +This document must therefore be updated when documentation about the +.Vt X509_STORE +object and its handling becomes available. +.Sh RETURN VALUES +.Fn SSL_CTX_set_cert_store +does not return diagnostic output. +.Pp +.Fn SSL_CTX_get_cert_store +returns the current setting. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_verify 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_cert_verify_callback.3 b/src/lib/libssl/man/SSL_CTX_set_cert_verify_callback.3 new file mode 100644 index 0000000000..1dc57001aa --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_cert_verify_callback.3 @@ -0,0 +1,112 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_cert_verify_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_CERT_VERIFY_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_cert_verify_callback +.Nd set peer certificate verification procedure +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_cert_verify_callback +.Fa "SSL_CTX *ctx" +.Fa "int (*callback)(X509_STORE_CTX *, void *)" +.Fa "void *arg" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_cert_verify_callback +sets the verification callback function for +.Fa ctx . +.Vt SSL +objects that are created from +.Fa ctx +inherit the setting valid at the time when +.Xr SSL_new 3 +is called. +.Sh NOTES +Whenever a certificate is verified during a SSL/TLS handshake, +a verification function is called. +If the application does not explicitly specify a verification callback +function, the built-in verification function is used. +If a verification callback +.Fa callback +is specified via +.Fn SSL_CTX_set_cert_verify_callback , +the supplied callback function is called instead. +By setting +.Fa callback +to +.Dv NULL , +the default behaviour is restored. +.Pp +When the verification must be performed, +.Fa callback +will be called with the arguments +.Fn callback "X509_STORE_CTX *x509_store_ctx" "void *arg" . +The argument +.Fa arg +is specified by the application when setting +.Fa callback . +.Pp +.Fa callback +should return 1 to indicate verification success and 0 to indicate verification +failure. +If +.Dv SSL_VERIFY_PEER +is set and +.Fa callback +returns 0, the handshake will fail. +As the verification procedure may allow the connection to continue in case of +failure (by always returning 1) the verification result must be set in any case +using the +.Fa error +member of +.Fa x509_store_ctx +so that the calling application will be informed about the detailed result of +the verification procedure! +.Pp +Within +.Fa x509_store_ctx , +.Fa callback +has access to the +.Fa verify_callback +function set using +.Xr SSL_CTX_set_verify 3 . +.Sh WARNINGS +Do not mix the verification callback described in this function with the +.Fa verify_callback +function called during the verification process. +The latter is set using the +.Xr SSL_CTX_set_verify 3 +family of functions. +.Pp +Providing a complete verification procedure including certificate purpose +settings, etc., is a complex task. +The built-in procedure is quite powerful and in most cases it should be +sufficient to modify its behaviour using the +.Fa verify_callback +function. +.Sh RETURN VALUES +.Fn SSL_CTX_set_cert_verify_callback +does not provide diagnostic information. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_get_verify_result 3 +.Sh HISTORY +Previous to OpenSSL 0.9.7, the +.Fa arg +argument to +.Fn SSL_CTX_set_cert_verify_callback +was ignored, and +.Fa callback +was called +simply as +.Ft int +.Fn (*callback) "X509_STORE_CTX *" . +To compile software written for previous versions of OpenSSL, +a dummy argument will have to be added to +.Fa callback . diff --git a/src/lib/libssl/man/SSL_CTX_set_cipher_list.3 b/src/lib/libssl/man/SSL_CTX_set_cipher_list.3 new file mode 100644 index 0000000000..7fb094a3b1 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_cipher_list.3 @@ -0,0 +1,82 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_CIPHER_LIST 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_cipher_list , +.Nm SSL_set_cipher_list +.Nd choose list of available SSL_CIPHERs +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "const char *str" +.Ft int +.Fn SSL_set_cipher_list "SSL *ssl" "const char *str" +.Sh DESCRIPTION +.Fn SSL_CTX_set_cipher_list +sets the list of available ciphers for +.Fa ctx +using the control string +.Fa str . +The format of the string is described +in +.Xr openssl 1 . +The list of ciphers is inherited by all +.Fa ssl +objects created from +.Fa ctx . +.Pp +.Fn SSL_set_cipher_list +sets the list of ciphers only for +.Fa ssl . +.Sh NOTES +The control string +.Fa str +should be universally usable and not depend on details of the library +configuration (ciphers compiled in). +Thus no syntax checking takes place. +Items that are not recognized, because the corresponding ciphers are not +compiled in or because they are mistyped, are simply ignored. +Failure is only flagged if no ciphers could be collected at all. +.Pp +It should be noted that inclusion of a cipher to be used into the list is a +necessary condition. +On the client side, the inclusion into the list is also sufficient. +On the server side, additional restrictions apply. +All ciphers have additional requirements. +ADH ciphers don't need a certificate, but DH-parameters must have been set. +All other ciphers need a corresponding certificate and key. +.Pp +A RSA cipher can only be chosen when a RSA certificate is available. +RSA export ciphers with a keylength of 512 bits for the RSA key require a +temporary 512 bit RSA key, as typically the supplied key has a length of 1024 +bits (see +.Xr SSL_CTX_set_tmp_rsa_callback 3 ) . +RSA ciphers using EDH need a certificate and key and additional DH-parameters +(see +.Xr SSL_CTX_set_tmp_dh_callback 3 ) . +.Pp +A DSA cipher can only be chosen when a DSA certificate is available. +DSA ciphers always use DH key exchange and therefore need DH-parameters (see +.Xr SSL_CTX_set_tmp_dh_callback 3 ) . +.Pp +When these conditions are not met for any cipher in the list (for example, a +client only supports export RSA ciphers with an asymmetric key length of 512 +bits and the server is not configured to use temporary RSA keys), the +.Dq no shared cipher +.Pq Dv SSL_R_NO_SHARED_CIPHER +error is generated and the handshake will fail. +.Sh RETURN VALUES +.Fn SSL_CTX_set_cipher_list +and +.Fn SSL_set_cipher_list +return 1 if any cipher could be selected and 0 on complete failure. +.Sh SEE ALSO +.Xr ciphers 1 , +.Xr ssl 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_CTX_set_tmp_rsa_callback 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_get_ciphers 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_client_CA_list.3 b/src/lib/libssl/man/SSL_CTX_set_client_CA_list.3 new file mode 100644 index 0000000000..bcc53fb0d6 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_client_CA_list.3 @@ -0,0 +1,132 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_client_CA_list.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_CLIENT_CA_LIST 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_client_CA_list , +.Nm SSL_set_client_CA_list , +.Nm SSL_CTX_add_client_CA , +.Nm SSL_add_client_CA +.Nd set list of CAs sent to the client when requesting a client certificate +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK_OF(X509_NAME) *list" +.Ft void +.Fn SSL_set_client_CA_list "SSL *s" "STACK_OF(X509_NAME) *list" +.Ft int +.Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *cacert" +.Ft int +.Fn SSL_add_client_CA "SSL *ssl" "X509 *cacert" +.Sh DESCRIPTION +.Fn SSL_CTX_set_client_CA_list +sets the +.Fa list +of CAs sent to the client when requesting a client certificate for +.Fa ctx . +.Pp +.Fn SSL_set_client_CA_list +sets the +.Fa list +of CAs sent to the client when requesting a client certificate for the chosen +.Fa ssl , +overriding the setting valid for +.Fa ssl Ns 's +.Vt SSL_CTX +object. +.Pp +.Fn SSL_CTX_add_client_CA +adds the CA name extracted from +.Fa cacert +to the list of CAs sent to the client when requesting a client certificate for +.Fa ctx . +.Pp +.Fn SSL_add_client_CA +adds the CA name extracted from +.Fa cacert +to the list of CAs sent to the client when requesting a client certificate for +the chosen +.Fa ssl , +overriding the setting valid for +.Fa ssl Ns 's +.Va SSL_CTX +object. +.Sh NOTES +When a TLS/SSL server requests a client certificate (see +.Fn SSL_CTX_set_verify ) , +it sends a list of CAs for which it will accept certificates to the client. +.Pp +This list must explicitly be set using +.Fn SSL_CTX_set_client_CA_list +for +.Fa ctx +and +.Fn SSL_set_client_CA_list +for the specific +.Fa ssl . +The list specified overrides the previous setting. +The CAs listed do not become trusted +.Po +.Fa list +only contains the names, not the complete certificates +.Pc ; +use +.Xr SSL_CTX_load_verify_locations 3 +to additionally load them for verification. +.Pp +If the list of acceptable CAs is compiled in a file, the +.Xr SSL_load_client_CA_file 3 +function can be used to help importing the necessary data. +.Pp +.Fn SSL_CTX_add_client_CA +and +.Fn SSL_add_client_CA +can be used to add additional items the list of client CAs. +If no list was specified before using +.Fn SSL_CTX_set_client_CA_list +or +.Fn SSL_set_client_CA_list , +a new client CA list for +.Fa ctx +or +.Fa ssl +(as appropriate) is opened. +.Pp +These functions are only useful for TLS/SSL servers. +.Sh RETURN VALUES +.Fn SSL_CTX_set_client_CA_list +and +.Fn SSL_set_client_CA_list +do not return diagnostic information. +.Pp +.Fn SSL_CTX_add_client_CA +and +.Fn SSL_add_client_CA +have the following return values: +.Bl -tag -width Ds +.It 0 +A failure while manipulating the +.Dv STACK_OF Ns +.Pq Vt X509_NAME +object occurred or the +.Vt X509_NAME +could not be extracted from +.Fa cacert . +Check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh EXAMPLES +Scan all certificates in +.Fa CAfile +and list them as acceptable CAs: +.Bd -literal +SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile)); +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_get_client_CA_list 3 , +.Xr SSL_load_client_CA_file 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_client_cert_cb.3 b/src/lib/libssl/man/SSL_CTX_set_client_cert_cb.3 new file mode 100644 index 0000000000..c4057ae4cc --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_client_cert_cb.3 @@ -0,0 +1,143 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_client_cert_cb.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_CLIENT_CERT_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_client_cert_cb , +.Nm SSL_CTX_get_client_cert_cb +.Nd handle client certificate callback function +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_client_cert_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)" +.Fc +.Ft int +.Fo "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))" +.Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey" +.Fc +.Ft int +.Fn "(*client_cert_cb)" "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey" +.Sh DESCRIPTION +.Fn SSL_CTX_set_client_cert_cb +sets the +.Fa client_cert_cb() +callback that is called when a client certificate is requested by a server and +no certificate was yet set for the SSL object. +.Pp +When +.Fa client_cert_cb +is +.Dv NULL , +no callback function is used. +.Pp +.Fn SSL_CTX_get_client_cert_cb +returns a pointer to the currently set callback function. +.Pp +.Fn client_cert_cb +is the application-defined callback. +If it wants to set a certificate, +a certificate/private key combination must be set using the +.Fa x509 +and +.Fa pkey +arguments and 1 must be returned. +The certificate will be installed into +.Fa ssl ; +see the +.Sx NOTES +and +.Sx BUGS +sections. +If no certificate should be set, +0 has to be returned and no certificate will be sent. +A negative return value will suspend the handshake and the handshake function +will return immediately. +.Xr SSL_get_error 3 +will return +.Dv SSL_ERROR_WANT_X509_LOOKUP +to indicate that the handshake was suspended. +The next call to the handshake function will again lead to the call of +.Fa client_cert_cb() . +It is the job of the +.Fa client_cert_cb() +to store information +about the state of the last call, if required to continue. +.Sh NOTES +During a handshake (or renegotiation) +a server may request a certificate from the client. +A client certificate must only be sent when the server did send the request. +.Pp +When a certificate has been set using the +.Xr SSL_CTX_use_certificate 3 +family of functions, +it will be sent to the server. +The TLS standard requires that only a certificate is sent if it matches the +list of acceptable CAs sent by the server. +This constraint is violated by the default behavior of the OpenSSL library. +Using the callback function it is possible to implement a proper selection +routine or to allow a user interaction to choose the certificate to be sent. +.Pp +If a callback function is defined and no certificate was yet defined for the +.Vt SSL +object, the callback function will be called. +If the callback function returns a certificate, the OpenSSL library +will try to load the private key and certificate data into the +.Vt SSL +object using the +.Fn SSL_use_certificate +and +.Fn SSL_use_private_key +functions. +Thus it will permanently install the certificate and key for this SSL object. +It will not be reset by calling +.Xr SSL_clear 3 . +If the callback returns no certificate, the OpenSSL library will not send a +certificate. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_free 3 , +.Xr SSL_get_client_CA_list 3 +.Sh BUGS +The +.Fa client_cert_cb() +cannot return a complete certificate chain; +it can only return one client certificate. +If the chain only has a length of 2, +the root CA certificate may be omitted according to the TLS standard and +thus a standard conforming answer can be sent to the server. +For a longer chain, the client must send the complete chain +(with the option to leave out the root CA certificate). +This can be accomplished only by either adding the intermediate CA certificates +into the trusted certificate store for the +.Vt SSL_CTX +object (resulting in having to add CA certificates that otherwise maybe would +not be trusted), or by adding the chain certificates using the +.Xr SSL_CTX_add_extra_chain_cert 3 +function, which is only available for the +.Vt SSL_CTX +object as a whole and that therefore probably can only apply for one client +certificate, making the concept of the callback function +(to allow the choice from several certificates) questionable. +.Pp +Once the +.Vt SSL +object has been used in conjunction with the callback function, +the certificate will be set for the +.Vt SSL +object and will not be cleared even when +.Xr SSL_clear 3 +is called. +It is therefore +.Em mandatory +to destroy the +.Vt SSL +object using +.Xr SSL_free 3 +and create a new one to return to the previous state. diff --git a/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 b/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 new file mode 100644 index 0000000000..599c574c3d --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 @@ -0,0 +1,95 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_DEFAULT_PASSWD_CB 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_default_passwd_cb , +.Nm SSL_CTX_set_default_passwd_cb_userdata +.Nd set passwd callback for encrypted PEM file handling +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb" +.Ft void +.Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *u" +.Ft int +.Fn pem_passwd_cb "char *buf" "int size" "int rwflag" "void *userdata" +.Sh DESCRIPTION +.Fn SSL_CTX_set_default_passwd_cb +sets the default password callback called when loading/storing a PEM +certificate with encryption. +.Pp +.Fn SSL_CTX_set_default_passwd_cb_userdata +sets a pointer to userdata +.Fa u +which will be provided to the password callback on invocation. +.Pp +The +.Fn pem_passwd_cb , +which must be provided by the application, +hands back the password to be used during decryption. +On invocation a pointer to +.Fa userdata +is provided. +The pem_passwd_cb must write the password into the provided buffer +.Fa buf +which is of size +.Fa size . +The actual length of the password must be returned to the calling function. +.Fa rwflag +indicates whether the callback is used for reading/decryption +.Pq Fa rwflag No = 0 +or writing/encryption +.Pq Fa rwflag No = 1 . +.Sh NOTES +When loading or storing private keys, a password might be supplied to protect +the private key. +The way this password can be supplied may depend on the application. +If only one private key is handled, it can be practical to have +.Fn pem_passwd_cb +handle the password dialog interactively. +If several keys have to be handled, it can be practical to ask for the password +once, then keep it in memory and use it several times. +In the last case, the password could be stored into the +.Fa userdata +storage and the +.Fn pem_passwd_cb +only returns the password already stored. +.Pp +When asking for the password interactively, +.Fn pem_passwd_cb +can use +.Fa rwflag +to check whether an item shall be encrypted +.Pq Fa rwflag No = 1 . +In this case the password dialog may ask for the same password twice for +comparison in order to catch typos which would make decryption impossible. +.Pp +Other items in PEM formatting (certificates) can also be encrypted; it is +however atypical, as certificate information is considered public. +.Sh RETURN VALUES +.Fn SSL_CTX_set_default_passwd_cb +and +.Fn SSL_CTX_set_default_passwd_cb_userdata +do not provide diagnostic information. +.Sh EXAMPLES +The following example returns the password provided as +.Fa userdata +to the calling function. +The password is considered to be a +.Sq \e0 +terminated string. +If the password does not fit into the buffer, the password is truncated. +.Bd -literal +int pem_passwd_cb(char *buf, int size, int rwflag, void *password) +{ + strncpy(buf, (char *)password, size); + buf[size - 1] = '\e0'; + return strlen(buf); +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_use_certificate 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_generate_session_id.3 b/src/lib/libssl/man/SSL_CTX_set_generate_session_id.3 new file mode 100644 index 0000000000..29ff6a123e --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_generate_session_id.3 @@ -0,0 +1,196 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_generate_session_id.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_GENERATE_SESSION_ID 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_generate_session_id , +.Nm SSL_set_generate_session_id , +.Nm SSL_has_matching_session_id +.Nd manipulate generation of SSL session IDs (server only) +.Sh SYNOPSIS +.In openssl/ssl.h +.Bd -literal + typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, + unsigned int *id_len); +.Ed +.Ft int +.Fn SSL_CTX_set_generate_session_id "SSL_CTX *ctx" "GEN_SESSION_CB cb" +.Ft int +.Fn SSL_set_generate_session_id "SSL *ssl" "GEN_SESSION_CB" "cb);" +.Ft int +.Fo SSL_has_matching_session_id +.Fa "const SSL *ssl" "const unsigned char *id" "unsigned int id_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_generate_session_id +sets the callback function for generating new session ids for SSL/TLS sessions +for +.Fa ctx +to be +.Fa cb . +.Pp +.Fn SSL_set_generate_session_id +sets the callback function for generating new session ids for SSL/TLS sessions +for +.Fa ssl +to be +.Fa cb . +.Pp +.Fn SSL_has_matching_session_id +checks, whether a session with id +.Fa id +(of length +.Fa id_len ) +is already contained in the internal session cache +of the parent context of +.Fa ssl . +.Sh NOTES +When a new session is established between client and server, +the server generates a session id. +The session id is an arbitrary sequence of bytes. +The length of the session id is 16 bytes for SSLv2 sessions and between 1 and +32 bytes for SSLv3/TLSv1. +The session id is not security critical but must be unique for the server. +Additionally, the session id is transmitted in the clear when reusing the +session so it must not contain sensitive information. +.Pp +Without a callback being set, an OpenSSL server will generate a unique session +id from pseudo random numbers of the maximum possible length. +Using the callback function, the session id can be changed to contain +additional information like, e.g., a host id in order to improve load balancing +or external caching techniques. +.Pp +The callback function receives a pointer to the memory location to put +.Fa id +into and a pointer to the maximum allowed length +.Fa id_len . +The buffer at location +.Fa id +is only guaranteed to have the size +.Fa id_len . +The callback is only allowed to generate a shorter id and reduce +.Fa id_len ; +the callback +.Em must never +increase +.Fa id_len +or write to the location +.Fa id +exceeding the given limit. +.Pp +If a SSLv2 session id is generated and +.Fa id_len +is reduced, it will be restored after the callback has finished and the session +id will be padded with 0x00. +It is not recommended to change the +.Fa id_len +for SSLv2 sessions. +The callback can use the +.Xr SSL_get_version 3 +function to check whether the session is of type SSLv2. +.Pp +The location +.Fa id +is filled with 0x00 before the callback is called, +so the callback may only fill part of the possible length and leave +.Fa id_len +untouched while maintaining reproducibility. +.Pp +Since the sessions must be distinguished, session ids must be unique. +Without the callback a random number is used, +so that the probability of generating the same session id is extremely small +(2^128 possible ids for an SSLv2 session, 2^256 for SSLv3/TLSv1). +In order to ensure the uniqueness of the generated session id, +the callback must call +.Fn SSL_has_matching_session_id +and generate another id if a conflict occurs. +If an id conflict is not resolved, the handshake will fail. +If the application codes, e.g., a unique host id, a unique process number, and +a unique sequence number into the session id, uniqueness could easily be +achieved without randomness added (it should however be taken care that +no confidential information is leaked this way). +If the application cannot guarantee uniqueness, +it is recommended to use the maximum +.Fa id_len +and fill in the bytes not used to code special information with random data to +avoid collisions. +.Pp +.Fn SSL_has_matching_session_id +will only query the internal session cache, not the external one. +Since the session id is generated before the handshake is completed, +it is not immediately added to the cache. +If another thread is using the same internal session cache, +a race condition can occur in that another thread generates the same session id. +Collisions can also occur when using an external session cache, +since the external cache is not tested with +.Fn SSL_has_matching_session_id +and the same race condition applies. +.Pp +When calling +.Fn SSL_has_matching_session_id +for an SSLv2 session with reduced +.Fa id_len Ns , +the match operation will be performed using the fixed length required and with +a 0x00 padded id. +.Pp +The callback must return 0 if it cannot generate a session id for whatever +reason and return 1 on success. +.Sh RETURN VALUES +.Fn SSL_CTX_set_generate_session_id +and +.Fn SSL_set_generate_session_id +always return 1. +.Pp +.Fn SSL_has_matching_session_id +returns 1 if another session with the same id is already in the cache. +.Sh EXAMPLES +The callback function listed will generate a session id with the server id +given, and will fill the rest with pseudo random bytes: +.Bd -literal +const char session_id_prefix = "www-18"; + +#define MAX_SESSION_ID_ATTEMPTS 10 +static int +generate_session_id(const SSL *ssl, unsigned char *id, + unsigned int *id_len) +{ + unsigned int count = 0; + const char *version; + + version = SSL_get_version(ssl); + if (!strcmp(version, "SSLv2")) { + /* we must not change id_len */ + ; + } + + do { + RAND_pseudo_bytes(id, *id_len); + /* + * Prefix the session_id with the required prefix. NB: If + * our prefix is too long, clip it \(en but there will be + * worse effects anyway, e.g., the server could only + * possibly create one session ID (the prefix!) so all + * future session negotiations will fail due to conflicts. + */ + memcpy(id, session_id_prefix, + (strlen(session_id_prefix) < *id_len) ? + strlen(session_id_prefix) : *id_len); + } while (SSL_has_matching_session_id(ssl, id, *id_len) && + (++count < MAX_SESSION_ID_ATTEMPTS)); + + if (count >= MAX_SESSION_ID_ATTEMPTS) + return 0; + return 1; +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_version 3 +.Sh HISTORY +.Fn SSL_CTX_set_generate_session_id , +.Fn SSL_set_generate_session_id +and +.Fn SSL_has_matching_session_id +were introduced in OpenSSL 0.9.7. diff --git a/src/lib/libssl/man/SSL_CTX_set_info_callback.3 b/src/lib/libssl/man/SSL_CTX_set_info_callback.3 new file mode 100644 index 0000000000..760c239951 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_info_callback.3 @@ -0,0 +1,167 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_info_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_INFO_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_info_callback , +.Nm SSL_CTX_get_info_callback , +.Nm SSL_set_info_callback , +.Nm SSL_get_info_callback +.Nd handle information callback for SSL connections +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_info_callback "SSL_CTX *ctx" "void (*callback)()" +.Ft void +.Fn "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))" +.Ft void +.Fn SSL_set_info_callback "SSL *ssl" "void (*callback)()" +.Ft void +.Fn "(*SSL_get_info_callback(const SSL *ssl))" +.Sh DESCRIPTION +.Fn SSL_CTX_set_info_callback +sets the +.Fa callback +function that can be used to obtain state information for SSL objects created +from +.Fa ctx +during connection setup and use. +The setting for +.Fa ctx +is overridden from the setting for a specific SSL object, if specified. +When +.Fa callback +is +.Dv NULL , +no callback function is used. +.Pp +.Fn SSL_set_info_callback +sets the +.Fa callback +function that can be used to +obtain state information for +.Fa ssl +during connection setup and use. +When +.Fa callback +is +.Dv NULL , +the callback setting currently valid for +.Fa ctx +is used. +.Pp +.Fn SSL_CTX_get_info_callback +returns a pointer to the currently set information callback function for +.Fa ctx . +.Pp +.Fn SSL_get_info_callback +returns a pointer to the currently set information callback function for +.Fa ssl . +.Sh NOTES +When setting up a connection and during use, +it is possible to obtain state information from the SSL/TLS engine. +When set, an information callback function is called whenever the state changes, +an alert appears, or an error occurs. +.Pp +The callback function is called as +.Fn callback "SSL *ssl" "int where" "int ret" . +The +.Fa where +argument specifies information about where (in which context) +the callback function was called. +If +.Fa ret +is 0, an error condition occurred. +If an alert is handled, +.Dv SSL_CB_ALERT +is set and +.Fa ret +specifies the alert information. +.Pp +.Fa where +is a bitmask made up of the following bits: +.Bl -tag -width Ds +.It Dv SSL_CB_LOOP +Callback has been called to indicate state change inside a loop. +.It Dv SSL_CB_EXIT +Callback has been called to indicate error exit of a handshake function. +(May be soft error with retry option for non-blocking setups.) +.It Dv SSL_CB_READ +Callback has been called during read operation. +.It Dv SSL_CB_WRITE +Callback has been called during write operation. +.It Dv SSL_CB_ALERT +Callback has been called due to an alert being sent or received. +.It Dv SSL_CB_READ_ALERT +.It Dv SSL_CB_WRITE_ALERT +.It Dv SSL_CB_ACCEPT_LOOP +.It Dv SSL_CB_ACCEPT_EXIT +.It Dv SSL_CB_CONNECT_LOOP +.It Dv SSL_CB_CONNECT_EXIT +.It Dv SSL_CB_HANDSHAKE_START +Callback has been called because a new handshake is started. +.It Dv SSL_CB_HANDSHAKE_DONE +Callback has been called because a handshake is finished. +.El +.Pp +The current state information can be obtained using the +.Xr SSL_state_string 3 +family of functions. +.Pp +The +.Fa ret +information can be evaluated using the +.Xr SSL_alert_type_string 3 +family of functions. +.Sh RETURN VALUES +.Fn SSL_set_info_callback +does not provide diagnostic information. +.Pp +.Fn SSL_get_info_callback +returns the current setting. +.Sh EXAMPLES +The following example callback function prints state strings, +information about alerts being handled and error messages to the +.Va bio_err +.Vt BIO . +.Bd -literal +void +apps_ssl_info_callback(SSL *s, int where, int ret) +{ + const char *str; + int w; + + w = where & ~SSL_ST_MASK; + + if (w & SSL_ST_CONNECT) + str = "SSL_connect"; + else if (w & SSL_ST_ACCEPT) + str = "SSL_accept"; + else + str = "undefined"; + + if (where & SSL_CB_LOOP) { + BIO_printf(bio_err, "%s:%s\en", str, + SSL_state_string_long(s)); + } else if (where & SSL_CB_ALERT) { + str = (where & SSL_CB_READ) ? "read" : "write"; + BIO_printf(bio_err, "SSL3 alert %s:%s:%s\en", str, + SSL_alert_type_string_long(ret), + SSL_alert_desc_string_long(ret)); + } else if (where & SSL_CB_EXIT) { + if (ret == 0) + BIO_printf(bio_err, "%s:failed in %s\en", + str, SSL_state_string_long(s)); + else if (ret < 0) { + BIO_printf(bio_err, "%s:error in %s\en", + str, SSL_state_string_long(s)); + } + } +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_alert_type_string 3 , +.Xr SSL_state_string 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_max_cert_list.3 b/src/lib/libssl/man/SSL_CTX_set_max_cert_list.3 new file mode 100644 index 0000000000..c9cd6e6d2b --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_max_cert_list.3 @@ -0,0 +1,105 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_max_cert_list.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_MAX_CERT_LIST 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_max_cert_list , +.Nm SSL_CTX_get_max_cert_list , +.Nm SSL_set_max_cert_list , +.Nm SSL_get_max_cert_list +.Nd manipulate allowed size for the peer's certificate chain +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_max_cert_list "SSL_CTX *ctx" "long size" +.Ft long +.Fn SSL_CTX_get_max_cert_list "SSL_CTX *ctx" +.Ft long +.Fn SSL_set_max_cert_list "SSL *ssl" "long size" +.Ft long +.Fn SSL_get_max_cert_list "SSL *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_max_cert_list +sets the maximum size allowed for the peer's certificate chain for all +.Vt SSL +objects created from +.Fa ctx +to be +.Fa size +bytes. +The +.Vt SSL +objects inherit the setting valid for +.Fa ctx +at the time +.Xr SSL_new 3 +is being called. +.Pp +.Fn SSL_CTX_get_max_cert_list +returns the currently set maximum size for +.Fa ctx . +.Pp +.Fn SSL_set_max_cert_list +sets the maximum size allowed for the peer's certificate chain for +.Fa ssl +to be +.Fa size +bytes. +This setting stays valid until a new value is set. +.Pp +.Fn SSL_get_max_cert_list +returns the currently set maximum size for +.Fa ssl . +.Sh NOTES +During the handshake process, the peer may send a certificate chain. +The TLS/SSL standard does not give any maximum size of the certificate chain. +The OpenSSL library handles incoming data by a dynamically allocated buffer. +In order to prevent this buffer from growing without bound due to data +received from a faulty or malicious peer, a maximum size for the certificate +chain is set. +.Pp +The default value for the maximum certificate chain size is 100kB (30kB +on the 16bit DOS platform). +This should be sufficient for usual certificate chains +(OpenSSL's default maximum chain length is 10, see +.Xr SSL_CTX_set_verify 3 , +and certificates without special extensions have a typical size of 1-2kB). +.Pp +For special applications it can be necessary to extend the maximum certificate +chain size allowed to be sent by the peer. +See for example the work on +.%T "Internet X.509 Public Key Infrastructure Proxy Certificate Profile" +and +.%T "TLS Delegation Protocol" +at +.Lk https://www.ietf.org/ +and +.Lk http://www.globus.org/ . +.Pp +Under normal conditions it should never be necessary to set a value smaller +than the default, as the buffer is handled dynamically and only uses the +memory actually required by the data sent by the peer. +.Pp +If the maximum certificate chain size allowed is exceeded, the handshake will +fail with a +.Dv SSL_R_EXCESSIVE_MESSAGE_SIZE +error. +.Sh RETURN VALUES +.Fn SSL_CTX_set_max_cert_list +and +.Fn SSL_set_max_cert_list +return the previously set value. +.Pp +.Fn SSL_CTX_get_max_cert_list +and +.Fn SSL_get_max_cert_list +return the currently set value. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Fn SSL*_set/get_max_cert_list +were introduced in OpenSSL 0.9.7. diff --git a/src/lib/libssl/man/SSL_CTX_set_mode.3 b/src/lib/libssl/man/SSL_CTX_set_mode.3 new file mode 100644 index 0000000000..a2d53884da --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_mode.3 @@ -0,0 +1,126 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_mode.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_MODE 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_mode , +.Nm SSL_set_mode , +.Nm SSL_CTX_get_mode , +.Nm SSL_get_mode +.Nd manipulate SSL engine mode +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_mode "SSL_CTX *ctx" "long mode" +.Ft long +.Fn SSL_set_mode "SSL *ssl" "long mode" +.Ft long +.Fn SSL_CTX_get_mode "SSL_CTX *ctx" +.Ft long +.Fn SSL_get_mode "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_mode +adds the mode set via bitmask in +.Fa mode +to +.Fa ctx . +Options already set before are not cleared. +.Pp +.Fn SSL_set_mode +adds the mode set via bitmask in +.Fa mode +to +.Fa ssl . +Options already set before are not cleared. +.Pp +.Fn SSL_CTX_get_mode +returns the mode set for +.Fa ctx . +.Pp +.Fn SSL_get_mode +returns the mode set for +.Fa ssl . +.Sh NOTES +The following mode changes are available: +.Bl -tag -width Ds +.It Dv SSL_MODE_ENABLE_PARTIAL_WRITE +Allow +.Fn SSL_write ... n +to return +.Ms r +with +.EQ +0 < r < n +.EN +(i.e., report success when just a single record has been written). +When not set (the default), +.Xr SSL_write 3 +will only report success once the complete chunk was written. +Once +.Xr SSL_write 3 +returns with +.Ms r , +.Ms r +bytes have been successfully written and the next call to +.Xr SSL_write 3 +must only send the +.Ms n \(mi r +bytes left, imitating the behaviour of +.Xr write 2 . +.It Dv SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER +Make it possible to retry +.Xr SSL_write 3 +with changed buffer location (the buffer contents must stay the same). +This is not the default to avoid the misconception that non-blocking +.Xr SSL_write 3 +behaves like non-blocking +.Xr write 2 . +.It Dv SSL_MODE_AUTO_RETRY +Never bother the application with retries if the transport is blocking. +If a renegotiation take place during normal operation, a +.Xr SSL_read 3 +or +.Xr SSL_write 3 +would return +with \(mi1 and indicate the need to retry with +.Dv SSL_ERROR_WANT_READ . +In a non-blocking environment applications must be prepared to handle +incomplete read/write operations. +In a blocking environment, applications are not always prepared to deal with +read/write operations returning without success report. +The flag +.Dv SSL_MODE_AUTO_RETRY +will cause read/write operations to only return after the handshake and +successful completion. +.It Dv SSL_MODE_RELEASE_BUFFERS +When we no longer need a read buffer or a write buffer for a given +.Vt SSL , +then release the memory we were using to hold it. +Released memory is either appended to a list of unused RAM chunks on the +.Vt SSL_CTX , +or simply freed if the list of unused chunks would become longer than +.Va "SSL_CTX->freelist_max_len" , +which defaults to 32. +Using this flag can save around 34k per idle SSL connection. +This flag has no effect on SSL v2 connections, or on DTLS connections. +.El +.Sh RETURN VALUES +.Fn SSL_CTX_set_mode +and +.Fn SSL_set_mode +return the new mode bitmask after adding +.Fa mode . +.Pp +.Fn SSL_CTX_get_mode +and +.Fn SSL_get_mode +return the current bitmask. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 +.Sh HISTORY +.Dv SSL_MODE_AUTO_RETRY +was added in OpenSSL 0.9.6. diff --git a/src/lib/libssl/man/SSL_CTX_set_msg_callback.3 b/src/lib/libssl/man/SSL_CTX_set_msg_callback.3 new file mode 100644 index 0000000000..7142c40545 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_msg_callback.3 @@ -0,0 +1,135 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_msg_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_MSG_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_msg_callback , +.Nm SSL_CTX_set_msg_callback_arg , +.Nm SSL_set_msg_callback , +.Nm SSL_set_msg_callback_arg +.Nd install callback for observing protocol messages +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_msg_callback +.Fa "SSL_CTX *ctx" +.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)" +.Fc +.Ft void +.Fn SSL_CTX_set_msg_callback_arg "SSL_CTX *ctx" "void *arg" +.Ft void +.Fo SSL_set_msg_callback +.Fa "SSL *ssl" +.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)" +.Fc +.Ft void +.Fn SSL_set_msg_callback_arg "SSL *ssl" "void *arg" +.Sh DESCRIPTION +.Fn SSL_CTX_set_msg_callback +or +.Fn SSL_set_msg_callback +can be used to define a message callback function +.Fa cb +for observing all SSL/TLS protocol messages (such as handshake messages) +that are received or sent. +.Fn SSL_CTX_set_msg_callback_arg +and +.Fn SSL_set_msg_callback_arg +can be used to set argument +.Fa arg +to the callback function, which is available for arbitrary application use. +.Pp +.Fn SSL_CTX_set_msg_callback +and +.Fn SSL_CTX_set_msg_callback_arg +specify default settings that will be copied to new +.Vt SSL +objects by +.Xr SSL_new 3 . +.Fn SSL_set_msg_callback +and +.Fn SSL_set_msg_callback_arg +modify the actual settings of an +.Vt SSL +object. +Using a +.Dv NULL +pointer for +.Fa cb +disables the message callback. +.Pp +When +.Fa cb +is called by the SSL/TLS library for a protocol message, +the function arguments have the following meaning: +.Bl -tag -width Ds +.It Fa write_p +This flag is 0 when a protocol message has been received and 1 when a protocol +message has been sent. +.It Fa version +The protocol version according to which the protocol message is +interpreted by the library. +Currently, this is one of +.Dv SSL2_VERSION , +.Dv SSL3_VERSION +and +.Dv TLS1_VERSION +(for SSL 2.0, SSL 3.0 and TLS 1.0, respectively). +.It Fa content_type +In the case of SSL 2.0, this is always 0. +In the case of SSL 3.0 or TLS 1.0, this is one of the +.Em ContentType +values defined in the protocol specification +.Po +.Dq change_cipher_spec(20) , +.Dq alert(21) , +.Dq handshake(22) ; +but never +.Dq application_data(23) +because the callback will only be called for protocol messages. +.Pc +.It Fa buf , Fa len +.Fa buf +points to a buffer containing the protocol message, which consists of +.Fa len +bytes. +The buffer is no longer valid after the callback function has returned. +.It Fa ssl +The +.Vt SSL +object that received or sent the message. +.It Fa arg +The user-defined argument optionally defined by +.Fn SSL_CTX_set_msg_callback_arg +or +.Fn SSL_set_msg_callback_arg . +.El +.Sh NOTES +Protocol messages are passed to the callback function after decryption +and fragment collection where applicable. +(Thus record boundaries are not visible.) +.Pp +If processing a received protocol message results in an error, +the callback function may not be called. +For example, the callback function will never see messages that are considered +too large to be processed. +.Pp +Due to automatic protocol version negotiation, +.Fa version +is not necessarily the protocol version used by the sender of the message: +If a TLS 1.0 ClientHello message is received by an SSL 3.0-only server, +.Fa version +will be +.Dv SSL3_VERSION . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Fn SSL_CTX_set_msg_callback , +.Fn SSL_CTX_set_msg_callback_arg , +.Fn SSL_set_msg_callback +and +.Fn SSL_set_msg_callback_arg +were added in OpenSSL 0.9.7. diff --git a/src/lib/libssl/man/SSL_CTX_set_options.3 b/src/lib/libssl/man/SSL_CTX_set_options.3 new file mode 100644 index 0000000000..1818be0d86 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_options.3 @@ -0,0 +1,395 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_options.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_OPTIONS 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_options , +.Nm SSL_set_options , +.Nm SSL_CTX_clear_options , +.Nm SSL_clear_options , +.Nm SSL_CTX_get_options , +.Nm SSL_get_options , +.Nm SSL_get_secure_renegotiation_support +.Nd manipulate SSL options +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_options "SSL_CTX *ctx" "long options" +.Ft long +.Fn SSL_set_options "SSL *ssl" "long options" +.Ft long +.Fn SSL_CTX_clear_options "SSL_CTX *ctx" "long options" +.Ft long +.Fn SSL_clear_options "SSL *ssl" "long options" +.Ft long +.Fn SSL_CTX_get_options "SSL_CTX *ctx" +.Ft long +.Fn SSL_get_options "SSL *ssl" +.Ft long +.Fn SSL_get_secure_renegotiation_support "SSL *ssl" +.Sh DESCRIPTION +Note: all these functions are implemented using macros. +.Pp +.Fn SSL_CTX_set_options +adds the options set via bitmask in +.Fa options +to +.Fa ctx . +Options already set before are not cleared! +.Pp +.Fn SSL_set_options +adds the options set via bitmask in +.Fa options +to +.Fa ssl . +Options already set before are not cleared! +.Pp +.Fn SSL_CTX_clear_options +clears the options set via bitmask in +.Fa options +to +.Fa ctx . +.Pp +.Fn SSL_clear_options +clears the options set via bitmask in +.Fa options +to +.Fa ssl . +.Pp +.Fn SSL_CTX_get_options +returns the options set for +.Fa ctx . +.Pp +.Fn SSL_get_options +returns the options set for +.Fa ssl . +.Pp +.Fn SSL_get_secure_renegotiation_support +indicates whether the peer supports secure renegotiation. +.Sh NOTES +The behaviour of the SSL library can be changed by setting several options. +The options are coded as bitmasks and can be combined by a bitwise OR +operation (|). +.Pp +.Fn SSL_CTX_set_options +and +.Fn SSL_set_options +affect the (external) protocol behaviour of the SSL library. +The (internal) behaviour of the API can be changed by using the similar +.Xr SSL_CTX_set_mode 3 +and +.Xr SSL_set_mode 3 +functions. +.Pp +During a handshake, the option settings of the SSL object are used. +When a new SSL object is created from a context using +.Xr SSL_new 3 , +the current option setting is copied. +Changes to +.Fa ctx +do not affect already created +.Vt SSL +objects. +.Fn SSL_clear +does not affect the settings. +.Pp +The following +.Em bug workaround +options are available: +.Bl -tag -width Ds +.It Dv SSL_OP_MICROSOFT_SESS_ID_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_NETSCAPE_CHALLENGE_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG +As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. +.It Dv SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_SAFARI_ECDHE_ECDSA_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_SSLEAY_080_CLIENT_DH_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_TLS_D5_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_TLS_BLOCK_PADDING_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS +Disables a countermeasure against a SSL 3.0/TLS 1.0 protocol vulnerability +affecting CBC ciphers, which cannot be handled by some broken SSL +implementations. +This option has no effect for connections using other ciphers. +.It Dv SSL_OP_TLSEXT_PADDING +Adds a padding extension to ensure the ClientHello size is never between 256 +and 511 bytes in length. +This is needed as a workaround for some implementations. +.It Dv SSL_OP_ALL +All of the above bug workarounds. +.El +.Pp +It is usually safe to use +.Dv SSL_OP_ALL +to enable the bug workaround options if compatibility with somewhat broken +implementations is desired. +.Pp +The following +.Em modifying +options are available: +.Bl -tag -width Ds +.It Dv SSL_OP_TLS_ROLLBACK_BUG +Disable version rollback attack detection. +.Pp +During the client key exchange, the client must send the same information +about acceptable SSL/TLS protocol levels as during the first hello. +Some clients violate this rule by adapting to the server's answer. +(Example: the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, +the server only understands up to SSLv3. +In this case the client must still use the same SSLv3.1=TLSv1 announcement. +Some clients step down to SSLv3 with respect to the server's answer and violate +the version rollback protection.) +.It Dv SSL_OP_SINGLE_DH_USE +Always create a new key when using temporary/ephemeral DH parameters +(see +.Xr SSL_CTX_set_tmp_dh_callback 3 ) . +This option must be used to prevent small subgroup attacks, when the DH +parameters were not generated using +.Dq strong +primes (e.g., when using DSA-parameters, see +.Xr openssl 1 ) . +If +.Dq strong +primes were used, it is not strictly necessary to generate a new DH key during +each handshake but it is also recommended. +.Dv SSL_OP_SINGLE_DH_USE +should therefore be enabled whenever temporary/ephemeral DH parameters are used. +.It SSL_OP_EPHEMERAL_RSA +Always use ephemeral (temporary) RSA key when doing RSA operations (see +.Xr SSL_CTX_set_tmp_rsa_callback 3 ) . +According to the specifications, this is only done when a RSA key can only be +used for signature operations (namely under export ciphers with restricted RSA +keylength). +By setting this option, ephemeral RSA keys are always used. +This option breaks compatibility with the SSL/TLS specifications and may lead +to interoperability problems with clients and should therefore never be used. +Ciphers with EDH (ephemeral Diffie-Hellman) key exchange should be used instead. +.It Dv SSL_OP_CIPHER_SERVER_PREFERENCE +When choosing a cipher, use the server's preferences instead of the client +preferences. +When not set, the SSL server will always follow the client's preferences. +When set, the SSLv3/TLSv1 server will choose following its own preferences. +Because of the different protocol, for SSLv2 the server will send its list of +preferences to the client and the client chooses. +.It Dv SSL_OP_NETSCAPE_CA_DN_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG +As of +.Ox 5.8 , +this option has no effect. +.It Dv SSL_OP_NO_SSLv2 +As of +.Ox 5.6 , +this option has no effect as SSLv2 support has been removed. +In previous versions it disabled use of the SSLv2 protocol. +.It Dv SSL_OP_NO_SSLv3 +Do not use the SSLv3 protocol. +.It Dv SSL_OP_NO_TLSv1 +Do not use the TLSv1.0 protocol. +.It Dv SSL_OP_NO_TLSv1_1 +Do not use the TLSv1.1 protocol. +.It Dv SSL_OP_NO_TLSv1_2 +Do not use the TLSv1.2 protocol. +.It Dv SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION +When performing renegotiation as a server, always start a new session (i.e., +session resumption requests are only accepted in the initial handshake). +This option is not needed for clients. +.It Dv SSL_OP_NO_TICKET +Normally clients and servers will, where possible, transparently make use of +RFC4507bis tickets for stateless session resumption. +.Pp +If this option is set this functionality is disabled and tickets will not be +used by clients or servers. +.It Dv SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION +As of +.Ox 5.6 , +this option has no effect. +In previous versions it allowed legacy insecure renegotiation between OpenSSL +and unpatched clients or servers. +See the +.Sx SECURE RENEGOTIATION +section for more details. +.It Dv SSL_OP_LEGACY_SERVER_CONNECT +Allow legacy insecure renegotiation between OpenSSL and unpatched servers +.Em only : +this option is currently set by default. +See the +.Sx SECURE RENEGOTIATION +section for more details. +.El +.Sh SECURE RENEGOTIATION +OpenSSL 0.9.8m and later always attempts to use secure renegotiation as +described in RFC5746. +This counters the prefix attack described in CVE-2009-3555 and elsewhere. +.Pp +The deprecated and highly broken SSLv2 protocol does not support renegotiation +at all; its use is +.Em strongly +discouraged. +.Pp +This attack has far-reaching consequences which application writers should be +aware of. +In the description below an implementation supporting secure renegotiation is +referred to as +.Dq patched . +A server not supporting secure +renegotiation is referred to as +.Dq unpatched . +.Pp +The following sections describe the operations permitted by OpenSSL's secure +renegotiation implementation. +.Ss Patched client and server +Connections and renegotiation are always permitted by OpenSSL implementations. +.Ss Unpatched client and patched OpenSSL server +The initial connection succeeds but client renegotiation is denied by the +server with a +.Em no_renegotiation +warning alert if TLS v1.0 is used or a fatal +.Em handshake_failure +alert in SSL v3.0. +.Pp +If the patched OpenSSL server attempts to renegotiate a fatal +.Em handshake_failure +alert is sent. +This is because the server code may be unaware of the unpatched nature of the +client. +.Pp +.Em N.B.: +a bug in OpenSSL clients earlier than 0.9.8m (all of which are unpatched) will +result in the connection hanging if it receives a +.Em no_renegotiation +alert. +OpenSSL versions 0.9.8m and later will regard a +.Em no_renegotiation +alert as fatal and respond with a fatal +.Em handshake_failure +alert. +This is because the OpenSSL API currently has no provision to indicate to an +application that a renegotiation attempt was refused. +.Ss Patched OpenSSL client and unpatched server +If the option +.Dv SSL_OP_LEGACY_SERVER_CONNECT +is set then initial connections and renegotiation between patched OpenSSL +clients and unpatched servers succeeds. +If neither option is set then initial connections to unpatched servers will +fail. +.Pp +The option +.Dv SSL_OP_LEGACY_SERVER_CONNECT +is currently set by default even though it has security implications: +otherwise it would be impossible to connect to unpatched servers (i.e., all of +them initially) and this is clearly not acceptable. +Renegotiation is permitted because this does not add any additional security +issues: during an attack clients do not see any renegotiations anyway. +.Pp +As more servers become patched the option +.Dv SSL_OP_LEGACY_SERVER_CONNECT +will +.Em not +be set by default in a future version of OpenSSL. +.Pp +OpenSSL client applications wishing to ensure they can connect to unpatched +servers should always +.Em set +.Dv SSL_OP_LEGACY_SERVER_CONNECT +.Pp +OpenSSL client applications that want to ensure they can +.Em not +connect to unpatched servers (and thus avoid any security issues) should always +.Em clear +.Dv SSL_OP_LEGACY_SERVER_CONNECT +using +.Fn SSL_CTX_clear_options +or +.Fn SSL_clear_options . +.Sh RETURN VALUES +.Fn SSL_CTX_set_options +and +.Fn SSL_set_options +return the new options bitmask after adding +.Fa options . +.Pp +.Fn SSL_CTX_clear_options +and +.Fn SSL_clear_options +return the new options bitmask after clearing +.Fa options . +.Pp +.Fn SSL_CTX_get_options +and +.Fn SSL_get_options +return the current bitmask. +.Pp +.Fn SSL_get_secure_renegotiation_support +returns 1 is the peer supports secure renegotiation and 0 if it does not. +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_CTX_set_tmp_rsa_callback 3 , +.Xr SSL_new 3 +.Sh HISTORY +.Dv SSL_OP_CIPHER_SERVER_PREFERENCE +and +.Dv SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION +have been added in +OpenSSL 0.9.7. +.Pp +.Dv SSL_OP_TLS_ROLLBACK_BUG +has been added in OpenSSL 0.9.6 and was automatically enabled with +.Dv SSL_OP_ALL . +As of 0.9.7, it is no longer included in +.Dv SSL_OP_ALL +and must be explicitly set. +.Pp +.Dv SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS +has been added in OpenSSL 0.9.6e. +Versions up to OpenSSL 0.9.6c do not include the countermeasure that can be +disabled with this option (in OpenSSL 0.9.6d, it was always enabled). +.Pp +.Fn SSL_CTX_clear_options +and +.Fn SSL_clear_options +were first added in OpenSSL 0.9.8m. +.Pp +.Dv SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION , +.Dv SSL_OP_LEGACY_SERVER_CONNECT +and the function +.Fn SSL_get_secure_renegotiation_support +were first added in OpenSSL 0.9.8m. +.Pp +.Dv SSL_OP_NO_SSLv2 +and +.Dv SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION +were changed to have no effect in +.Ox 5.6 . diff --git a/src/lib/libssl/man/SSL_CTX_set_psk_client_callback.3 b/src/lib/libssl/man/SSL_CTX_set_psk_client_callback.3 new file mode 100644 index 0000000000..0325a9405a --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_psk_client_callback.3 @@ -0,0 +1,68 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_psk_client_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_PSK_CLIENT_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_psk_client_callback , +.Nm SSL_set_psk_client_callback +.Nd set PSK client callback +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_psk_client_callback +.Fa "SSL_CTX *ctx" +.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \ +unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)" +.Fc +.Ft void +.Fo SSL_set_psk_client_callback +.Fa "SSL *ssl" +.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \ +unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)" +.Fc +.Sh DESCRIPTION +A client application must provide a callback function which is called +when the client is sending the ClientKeyExchange message to the server. +.Pp +The purpose of the callback function is to select the PSK identity and +the pre-shared key to use during the connection setup phase. +.Pp +The callback is set using functions +.Fn SSL_CTX_set_psk_client_callback +or +.Fn SSL_set_psk_client_callback . +The callback function is given the connection in parameter +.Fa ssl , +a +.Dv NULL Ns +-terminated PSK identity hint sent by the server in parameter +.Fa hint , +a buffer +.Fa identity +of length +.Fa max_identity_len +bytes where the resulting +.Dv NULL Ns +-terminated identity is to be stored, and a buffer +.Fa psk +of +length +.Fa max_psk_len +bytes where the resulting pre-shared key is to be stored. +.Sh NOTES +Note that parameter +.Fa hint +given to the callback may be +.Dv NULL . +.Sh RETURN VALUES +Return values from the client callback are interpreted as follows: +.Pp +On success (callback found a PSK identity and a pre-shared key to use) +the length (> 0) of +.Fa psk +in bytes is returned. +.Pp +Otherwise or on errors callback should return 0. +In this case the connection setup fails. diff --git a/src/lib/libssl/man/SSL_CTX_set_quiet_shutdown.3 b/src/lib/libssl/man/SSL_CTX_set_quiet_shutdown.3 new file mode 100644 index 0000000000..e840661125 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_quiet_shutdown.3 @@ -0,0 +1,115 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_quiet_shutdown.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_QUIET_SHUTDOWN 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_quiet_shutdown , +.Nm SSL_CTX_get_quiet_shutdown , +.Nm SSL_set_quiet_shutdown , +.Nm SSL_get_quiet_shutdown +.Nd manipulate shutdown behaviour +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_CTX_set_quiet_shutdown "SSL_CTX *ctx" "int mode" +.Ft int +.Fn SSL_CTX_get_quiet_shutdown "const SSL_CTX *ctx" +.Ft void +.Fn SSL_set_quiet_shutdown "SSL *ssl" "int mode" +.Ft int +.Fn SSL_get_quiet_shutdown "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_quiet_shutdown +sets the +.Dq quiet shutdown +flag for +.Fa ctx +to be +.Fa mode . +.Vt SSL +objects created from +.Fa ctx +inherit the +.Fa mode +valid at the time +.Xr SSL_new 3 +is called. +.Fa mode +may be 0 or 1. +.Pp +.Fn SSL_CTX_get_quiet_shutdown +returns the +.Dq quiet shutdown +setting of +.Fa ctx . +.Pp +.Fn SSL_set_quiet_shutdown +sets the +.Dq quiet shutdown +flag for +.Fa ssl +to be +.Fa mode . +The setting stays valid until +.Fa ssl +is removed with +.Xr SSL_free 3 +or +.Fn SSL_set_quiet_shutdown +is called again. +It is not changed when +.Xr SSL_clear 3 +is called. +.Fa mode +may be 0 or 1. +.Pp +.Fn SSL_get_quiet_shutdown +returns the +.Dq quiet shutdown +setting of +.Fa ssl . +.Sh NOTES +Normally when a SSL connection is finished, the parties must send out +.Dq close notify +alert messages using +.Xr SSL_shutdown 3 +for a clean shutdown. +.Pp +When setting the +.Dq quiet shutdown +flag to 1, +.Xr SSL_shutdown 3 +will set the internal flags to +.Dv SSL_SENT_SHUTDOWN Ns | Ns Dv SSL_RECEIVED_SHUTDOWN +.Po +.Xr SSL_shutdown 3 +then behaves like +.Xr SSL_set_shutdown 3 +called with +.Dv SSL_SENT_SHUTDOWN Ns | Ns Dv SSL_RECEIVED_SHUTDOWN +.Pc . +The session is thus considered to be shut down, but no +.Dq close notify +alert is sent to the peer. +This behaviour violates the TLS standard. +.Pp +The default is normal shutdown behaviour as described by the TLS standard. +.Sh RETURN VALUES +.Fn SSL_CTX_set_quiet_shutdown +and +.Fn SSL_set_quiet_shutdown +do not return diagnostic information. +.Pp +.Fn SSL_CTX_get_quiet_shutdown +and +.Fn SSL_get_quiet_shutdown +return the current setting. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_free 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_session_cache_mode.3 b/src/lib/libssl/man/SSL_CTX_set_session_cache_mode.3 new file mode 100644 index 0000000000..5ba6728a8a --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_session_cache_mode.3 @@ -0,0 +1,143 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_session_cache_mode.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_SESSION_CACHE_MODE 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_session_cache_mode , +.Nm SSL_CTX_get_session_cache_mode +.Nd enable/disable session caching +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_session_cache_mode "SSL_CTX ctx" "long mode" +.Ft long +.Fn SSL_CTX_get_session_cache_mode "SSL_CTX ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_session_cache_mode +enables/disables session caching by setting the operational mode for +.Ar ctx +to +.Ar mode . +.Pp +.Fn SSL_CTX_get_session_cache_mode +returns the currently used cache mode. +.Sh NOTES +The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. +The sessions can be held in memory for each +.Fa ctx , +if more than one +.Vt SSL_CTX +object is being maintained, the sessions are unique for each +.Vt SSL_CTX +object. +.Pp +In order to reuse a session, a client must send the session's id to the server. +It can only send exactly one id. +The server then either agrees to reuse the session or it starts a full +handshake (to create a new session). +.Pp +A server will lookup up the session in its internal session storage. +If the session is not found in internal storage or lookups for the internal +storage have been deactivated +.Pq Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP , +the server will try the external storage if available. +.Pp +Since a client may try to reuse a session intended for use in a different +context, the session id context must be set by the server (see +.Xr SSL_CTX_set_session_id_context 3 ) . +.Pp +The following session cache modes and modifiers are available: +.Bl -tag -width Ds +.It Dv SSL_SESS_CACHE_OFF +No session caching for client or server takes place. +.It Dv SSL_SESS_CACHE_CLIENT +Client sessions are added to the session cache. +As there is no reliable way for the OpenSSL library to know whether a session +should be reused or which session to choose (due to the abstract BIO layer the +SSL engine does not have details about the connection), +the application must select the session to be reused by using the +.Xr SSL_set_session 3 +function. +This option is not activated by default. +.It Dv SSL_SESS_CACHE_SERVER +Server sessions are added to the session cache. +When a client proposes a session to be reused, the server looks for the +corresponding session in (first) the internal session cache (unless +.Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP +is set), then (second) in the external cache if available. +If the session is found, the server will try to reuse the session. +This is the default. +.It Dv SSL_SESS_CACHE_BOTH +Enable both +.Dv SSL_SESS_CACHE_CLIENT +and +.Dv SSL_SESS_CACHE_SERVER +at the same time. +.It Dv SSL_SESS_CACHE_NO_AUTO_CLEAR +Normally the session cache is checked for expired sessions every 255 +connections using the +.Xr SSL_CTX_flush_sessions 3 +function. +Since this may lead to a delay which cannot be controlled, +the automatic flushing may be disabled and +.Xr SSL_CTX_flush_sessions 3 +can be called explicitly by the application. +.It Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP +By setting this flag, session-resume operations in an SSL/TLS server will not +automatically look up sessions in the internal cache, +even if sessions are automatically stored there. +If external session caching callbacks are in use, +this flag guarantees that all lookups are directed to the external cache. +As automatic lookup only applies for SSL/TLS servers, +the flag has no effect on clients. +.It Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +Depending on the presence of +.Dv SSL_SESS_CACHE_CLIENT +and/or +.Dv SSL_SESS_CACHE_SERVER , +sessions negotiated in an SSL/TLS handshake may be cached for possible reuse. +Normally a new session is added to the internal cache as well as any external +session caching (callback) that is configured for the +.Vt SSL_CTX . +This flag will prevent sessions being stored in the internal cache +(though the application can add them manually using +.Xr SSL_CTX_add_session 3 ) . +Note: +in any SSL/TLS servers where external caching is configured, any successful +session lookups in the external cache (e.g., for session-resume requests) would +normally be copied into the local cache before processing continues \(en this +flag prevents these additions to the internal cache as well. +.It Dv SSL_SESS_CACHE_NO_INTERNAL +Enable both +.Dv SSL_SESS_CACHE_NO_INTERNAL_LOOKUP +and +.Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +at the same time. +.El +.Pp +The default mode is +.Dv SSL_SESS_CACHE_SERVER . +.Sh RETURN VALUES +.Fn SSL_CTX_set_session_cache_mode +returns the previously set cache mode. +.Pp +.Fn SSL_CTX_get_session_cache_mode +returns the currently set cache mode. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_set_session_id_context 3 , +.Xr SSL_CTX_set_timeout 3 , +.Xr SSL_session_reused 3 , +.Xr SSL_set_session 3 +.Sh HISTORY +.Dv SSL_SESS_CACHE_NO_INTERNAL_STORE +and +.Dv SSL_SESS_CACHE_NO_INTERNAL +were introduced in OpenSSL 0.9.6h. diff --git a/src/lib/libssl/man/SSL_CTX_set_session_id_context.3 b/src/lib/libssl/man/SSL_CTX_set_session_id_context.3 new file mode 100644 index 0000000000..37028cc6ca --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_session_id_context.3 @@ -0,0 +1,105 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_session_id_context.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_SESSION_ID_CONTEXT 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_session_id_context , +.Nm SSL_set_session_id_context +.Nd set context within which session can be reused (server side only) +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_CTX_set_session_id_context +.Fa "SSL_CTX *ctx" +.Fa "const unsigned char *sid_ctx" +.Fa "unsigned int sid_ctx_len" +.Fc +.Ft int +.Fo SSL_set_session_id_context +.Fa "SSL *ssl" +.Fa "const unsigned char *sid_ctx" +.Fa "unsigned int sid_ctx_len" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_set_session_id_context +sets the context +.Fa sid_ctx +of length +.Fa sid_ctx_len +within which a session can be reused for the +.Fa ctx +object. +.Pp +.Fn SSL_set_session_id_context +sets the context +.Fa sid_ctx +of length +.Fa sid_ctx_len +within which a session can be reused for the +.Fa ssl +object. +.Sh NOTES +Sessions are generated within a certain context. +When exporting/importing sessions with +.Xr i2d_SSL_SESSION 3 +and +.Xr d2i_SSL_SESSION 3 , +it would be possible to re-import a session generated from another context +(e.g., another application), which might lead to malfunctions. +Therefore each application must set its own session id context +.Fa sid_ctx +which is used to distinguish the contexts and is stored in exported sessions. +The +.Fa sid_ctx +can be any kind of binary data with a given length; it is therefore possible +to use, for instance, the name of the application, the hostname, the service +name... +.Pp +The session id context becomes part of the session. +The session id context is set by the SSL/TLS server. +The +.Fn SSL_CTX_set_session_id_context +and +.Fn SSL_set_session_id_context +functions are therefore only useful on the server side. +.Pp +OpenSSL clients will check the session id context returned by the server when +reusing a session. +.Pp +The maximum length of the +.Fa sid_ctx +is limited to +.Dv SSL_MAX_SSL_SESSION_ID_LENGTH . +.Sh WARNINGS +If the session id context is not set on an SSL/TLS server and client +certificates are used, stored sessions will not be reused but a fatal error +will be flagged and the handshake will fail. +.Pp +If a server returns a different session id context to an OpenSSL client +when reusing a session, an error will be flagged and the handshake will +fail. +OpenSSL servers will always return the correct session id context, +as an OpenSSL server checks the session id context itself before reusing +a session as described above. +.Sh RETURN VALUES +.Fn SSL_CTX_set_session_id_context +and +.Fn SSL_set_session_id_context +return the following values: +.Bl -tag -width Ds +.It 0 +The length +.Fa sid_ctx_len +of the session id context +.Fa sid_ctx +exceeded +the maximum allowed length of +.Dv SSL_MAX_SSL_SESSION_ID_LENGTH . +The error is logged to the error stack. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_ssl_version.3 b/src/lib/libssl/man/SSL_CTX_set_ssl_version.3 new file mode 100644 index 0000000000..3359f195b4 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_ssl_version.3 @@ -0,0 +1,81 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_ssl_version.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_SSL_VERSION 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_ssl_version , +.Nm SSL_set_ssl_method , +.Nm SSL_get_ssl_method +.Nd choose a new TLS/SSL method +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_set_ssl_version "SSL_CTX *ctx" "const SSL_METHOD *method" +.Ft int +.Fn SSL_set_ssl_method "SSL *s" "const SSL_METHOD *method" +.Ft const SSL_METHOD * +.Fn SSL_get_ssl_method "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_CTX_set_ssl_version +sets a new default TLS/SSL +.Fa method +for +.Vt SSL +objects newly created from this +.Fa ctx . +.Vt SSL +objects already created with +.Xr SSL_new 3 +are not affected, except when +.Xr SSL_clear 3 +is called. +.Pp +.Fn SSL_set_ssl_method +sets a new TLS/SSL +.Fa method +for a particular +.Vt SSL +object +.Fa s . +It may be reset when +.Xr SSL_clear 3 +is called. +.Pp +.Fn SSL_get_ssl_method +returns a function pointer to the TLS/SSL method set in +.Fa ssl . +.Sh NOTES +The available +.Fa method +choices are described in +.Xr SSL_CTX_new 3 . +.Pp +When +.Xr SSL_clear 3 +is called and no session is connected to an +.Vt SSL +object, the method of the +.Vt SSL +object is reset to the method currently set in the corresponding +.Vt SSL_CTX +object. +.Sh RETURN VALUES +The following return values can occur for +.Fn SSL_CTX_set_ssl_version +and +.Fn SSL_set_ssl_method : +.Bl -tag -width Ds +.It 0 +The new choice failed. +Check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_new 3 , +.Xr SSL_set_connect_state 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_timeout.3 b/src/lib/libssl/man/SSL_CTX_set_timeout.3 new file mode 100644 index 0000000000..d8d699352e --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_timeout.3 @@ -0,0 +1,65 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_timeout.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_TIMEOUT 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_timeout , +.Nm SSL_CTX_get_timeout +.Nd manipulate timeout values for session caching +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_CTX_set_timeout "SSL_CTX *ctx" "long t" +.Ft long +.Fn SSL_CTX_get_timeout "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_timeout +sets the timeout for newly created sessions for +.Fa ctx +to +.Fa t . +The timeout value +.Fa t +must be given in seconds. +.Pp +.Fn SSL_CTX_get_timeout +returns the currently set timeout value for +.Fa ctx . +.Sh NOTES +Whenever a new session is created, it is assigned a maximum lifetime. +This lifetime is specified by storing the creation time of the session and the +timeout value valid at this time. +If the actual time is later than creation time plus timeout, +the session is not reused. +.Pp +Due to this realization, all sessions behave according to the timeout value +valid at the time of the session negotiation. +Changes of the timeout value do not affect already established sessions. +.Pp +The expiration time of a single session can be modified using the +.Xr SSL_SESSION_get_time 3 +family of functions. +.Pp +Expired sessions are removed from the internal session cache, whenever +.Xr SSL_CTX_flush_sessions 3 +is called, either directly by the application or automatically (see +.Xr SSL_CTX_set_session_cache_mode 3 ) . +.Pp +The default value for session timeout is decided on a per-protocol basis; see +.Xr SSL_get_default_timeout 3 . +All currently supported protocols have the same default timeout value of 300 +seconds. +.Sh RETURN VALUES +.Fn SSL_CTX_set_timeout +returns the previously set timeout value. +.Pp +.Fn SSL_CTX_get_timeout +returns the currently set timeout value. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_get_default_timeout 3 , +.Xr SSL_SESSION_get_time 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 b/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 new file mode 100644 index 0000000000..ad734839a9 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 @@ -0,0 +1,235 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_TMP_DH_CALLBACK 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tmp_dh_callback , +.Nm SSL_CTX_set_tmp_dh , +.Nm SSL_set_tmp_dh_callback , +.Nm SSL_set_tmp_dh +.Nd handle DH keys for ephemeral key exchange +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_tmp_dh_callback +.Fa "SSL_CTX *ctx" +.Fa "DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft long +.Fn SSL_CTX_set_tmp_dh "SSL_CTX *ctx" "DH *dh" +.Ft void +.Fo SSL_set_tmp_dh_callback +.Fa "SSL *ssl" +.Fa "DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength" +.Fc +.Ft long +.Fn SSL_set_tmp_dh "SSL *ssl" "DH *dh" +.Sh DESCRIPTION +.Fn SSL_CTX_set_tmp_dh_callback +sets the callback function for +.Fa ctx +to be used when a DH parameters are required to +.Fa tmp_dh_callback . +The callback is inherited by all +.Vt ssl +objects created from +.Fa ctx . +.Pp +.Fn SSL_CTX_set_tmp_dh +sets DH parameters to be used to be +.Sy dh Ns . +The key is inherited by all +.Fa ssl +objects created from +.Fa ctx . +.Pp +.Fn SSL_set_tmp_dh_callback +sets the callback only for +.Fa ssl . +.Pp +.Fn SSL_set_tmp_dh +sets the parameters only for +.Fa ssl . +.Pp +These functions apply to SSL/TLS servers only. +.Sh NOTES +When using a cipher with RSA authentication, +an ephemeral DH key exchange can take place. +Ciphers with DSA keys always use ephemeral DH keys as well. +In these cases, the session data are negotiated using the ephemeral/temporary +DH key and the key supplied and certified by the certificate chain is only used +for signing. +Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. +.Pp +Using ephemeral DH key exchange yields forward secrecy, +as the connection can only be decrypted when the DH key is known. +By generating a temporary DH key inside the server application that is lost +when the application is left, it becomes impossible for an attacker to decrypt +past sessions, even if he gets hold of the normal (certified) key, +as this key was only used for signing. +.Pp +In order to perform a DH key exchange the server must use a DH group +(DH parameters) and generate a DH key. +The server will always generate a new DH key during the negotiation, +when the DH parameters are supplied via callback and/or when the +.Dv SSL_OP_SINGLE_DH_USE +option of +.Xr SSL_CTX_set_options 3 +is set. +It will immediately create a DH key, when DH parameters are supplied via +.Fn SSL_CTX_set_tmp_dh +and +.Dv SSL_OP_SINGLE_DH_USE +is not set. +In this case, it may happen that a key is generated on initialization without +later being needed, while on the other hand the computer time during the +negotiation is being saved. +.Pp +If +.Dq strong +primes were used to generate the DH parameters, it is not strictly necessary to +generate a new key for each handshake but it does improve forward secrecy. +If it is not assured that +.Dq strong +primes were used (see especially the section about DSA parameters below), +.Dv SSL_OP_SINGLE_DH_USE +must be used in order to prevent small subgroup attacks. +Always using +.Dv SSL_OP_SINGLE_DH_USE +has an impact on the computer time needed during negotiation, +but it is not very large, +so application authors/users should consider always enabling this option. +.Pp +As generating DH parameters is extremely time consuming, an application should +not generate the parameters on the fly but supply the parameters. +DH parameters can be reused, +as the actual key is newly generated during the negotiation. +The risk in reusing DH parameters is that an attacker may specialize on a very +often used DH group. +Applications should therefore generate their own DH parameters during the +installation process using the openssl +.Xr openssl 1 +application. +In order to reduce the computer time needed for this generation, +it is possible to use DSA parameters instead (see +.Xr openssl 1 ) , +but in this case +.Dv SSL_OP_SINGLE_DH_USE +is mandatory. +.Pp +Application authors may compile in DH parameters. +Files +.Pa dh512.pem , +.Pa dh1024.pem , +.Pa dh2048.pem , +and +.Pa dh4096.pem +in the +.Pa apps +directory of the current version of the OpenSSL distribution contain the +.Sq SKIP +DH parameters, +which use safe primes and were generated verifiably pseudo-randomly. +These files can be converted into C code using the +.Fl C +option of the +.Xr openssl 1 +application. +Authors may also generate their own set of parameters using +.Xr openssl 1 , +but a user may not be sure how the parameters were generated. +The generation of DH parameters during installation is therefore recommended. +.Pp +An application may either directly specify the DH parameters or can supply the +DH parameters via a callback function. +The callback approach has the advantage that the callback may supply DH +parameters for different key lengths. +.Pp +The +.Fa tmp_dh_callback +is called with the +.Fa keylength +needed and the +.Fa is_export +information. +The +.Fa is_export +flag is set when the ephemeral DH key exchange is performed with an export +cipher. +.Sh RETURN VALUES +.Fn SSL_CTX_set_tmp_dh_callback +and +.Fn SSL_set_tmp_dh_callback +do not return diagnostic output. +.Pp +.Fn SSL_CTX_set_tmp_dh +and +.Fn SSL_set_tmp_dh +do return 1 on success and 0 on failure. +Check the error queue to find out the reason of failure. +.Sh EXAMPLES +Handle DH parameters for key lengths of 512 and 1024 bits. +(Error handling partly left out.) +.Bd -literal +\&... +/* Set up ephemeral DH stuff */ +DH *dh_512 = NULL; +DH *dh_1024 = NULL; +FILE *paramfile; + +\&... + +/* "openssl dhparam -out dh_param_512.pem -2 512" */ +paramfile = fopen("dh_param_512.pem", "r"); +if (paramfile) { + dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); +} +/* "openssl dhparam -out dh_param_1024.pem -2 1024" */ +paramfile = fopen("dh_param_1024.pem", "r"); +if (paramfile) { + dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); +} + +\&... + +/* "openssl dhparam -C -2 512" etc... */ +DH *get_dh512() { ... } +DH *get_dh1024() { ... } + +DH * +tmp_dh_callback(SSL *s, int is_export, int keylength) +{ + DH *dh_tmp=NULL; + + switch (keylength) { + case 512: + if (!dh_512) + dh_512 = get_dh512(); + dh_tmp = dh_512; + break; + case 1024: + if (!dh_1024) + dh_1024 = get_dh1024(); + dh_tmp = dh_1024; + break; + default: + /* + * Generating a key on the fly is very costly, + * so use what is there + */ + setup_dh_parameters_like_above(); + } + + return(dh_tmp); +} +.Ed +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_tmp_rsa_callback 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3 b/src/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3 new file mode 100644 index 0000000000..bf68f49206 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_tmp_rsa_callback.3 @@ -0,0 +1,231 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.1 2016/11/05 15:32:19 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_TMP_RSA_CALLBACK.POD 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_tmp_rsa_callback , +.Nm SSL_CTX_set_tmp_rsa , +.Nm SSL_CTX_need_tmp_rsa , +.Nm SSL_set_tmp_rsa_callback , +.Nm SSL_set_tmp_rsa , +.Nm SSL_need_tmp_rsa +.Nd handle RSA keys for ephemeral key exchange +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_tmp_rsa_callback +.Fa "SSL_CTX *ctx" +.Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft long +.Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa" +.Ft long +.Fn SSL_CTX_need_tmp_rsa "SSL_CTX *ctx" +.Ft void +.Fo SSL_set_tmp_rsa_callback +.Fa "SSL_CTX *ctx" +.Fa "RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)" +.Fc +.Ft long +.Fn SSL_set_tmp_rsa "SSL *ssl" "RSA *rsa" +.Ft long +.Fn SSL_need_tmp_rsa "SSL *ssl" +.Ft RSA * +.Fn "(*tmp_rsa_callback)" "SSL *ssl" "int is_export" "int keylength" +.Sh DESCRIPTION +.Fn SSL_CTX_set_tmp_rsa_callback +sets the callback function for +.Fa ctx +to be used when a temporary/ephemeral RSA key is required to +.Fa tmp_rsa_callback . +The callback is inherited by all +.Vt SSL +objects newly created from +.Fa ctx +with +.Xr SSL_new 3 . +Already created SSL objects are not affected. +.Pp +.Fn SSL_CTX_set_tmp_rsa +sets the temporary/ephemeral RSA key to be used to be +.Fa rsa . +The key is inherited by all +.Vt SSL +objects newly created from +.Fa ctx +with +.Xr SSL_new 3 . +Already created SSL objects are not affected. +.Pp +.Fn SSL_CTX_need_tmp_rsa +returns 1, +if a temporary/ephemeral RSA key is needed for RSA-based strength-limited +.Sq exportable +ciphersuites because a RSA key with a keysize larger than 512 bits is installed. +.Pp +.Fn SSL_set_tmp_rsa_callback +sets the callback only for +.Fa ssl . +.Pp +.Fn SSL_set_tmp_rsa +sets the key only for +.Fa ssl . +.Pp +.Fn SSL_need_tmp_rsa +returns 1, +if a temporary/ephemeral RSA key is needed for RSA-based strength-limited +.Sq exportable +ciphersuites because a RSA key with a keysize larger than 512 bits is installed. +.Pp +These functions apply to SSL/TLS servers only. +.Sh NOTES +When using a cipher with RSA authentication, +an ephemeral RSA key exchange can take place. +In this case the session data are negotiated using the ephemeral/temporary RSA +key and the RSA key supplied and certified by the certificate chain is only +used for signing. +.Pp +Under previous export restrictions, ciphers with RSA keys shorter (512 bits) +than the usual key length of 1024 bits were created. +To use these ciphers with RSA keys of usual length, an ephemeral key exchange +must be performed, as the normal (certified) key cannot be directly used. +.Pp +Using ephemeral RSA key exchange yields forward secrecy, +as the connection can only be decrypted when the RSA key is known. +By generating a temporary RSA key inside the server application that is lost +when the application is left, it becomes impossible for an attacker to decrypt +past sessions, even if he gets hold of the normal (certified) RSA key, +as this key was used for signing only. +The downside is that creating a RSA key is computationally expensive. +.Pp +Additionally, the use of ephemeral RSA key exchange is only allowed in the TLS +standard when the RSA key can be used for signing only, that is, +for export ciphers. +Using ephemeral RSA key exchange for other purposes violates the standard and +can break interoperability with clients. +It is therefore strongly recommended to not use ephemeral RSA key exchange and +use EDH (Ephemeral Diffie-Hellman) key exchange instead in order to achieve +forward secrecy (see +.Xr SSL_CTX_set_tmp_dh_callback 3 ) . +.Pp +On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default +and must be explicitly enabled using the +.Dv SSL_OP_EPHEMERAL_RSA +option of +.Xr SSL_CTX_set_options 3 , +violating the TLS/SSL +standard. +When ephemeral RSA key exchange is required for export ciphers, +it will automatically be used without this option! +.Pp +An application may either directly specify the key or can supply the key via +a callback function. +The callback approach has the advantage that the callback may generate the key +only in case it is actually needed. +However, as the generation of a RSA key is costly, +it will lead to a significant delay in the handshake procedure. +Another advantage of the callback function is that it can supply keys of +different size (e.g., for +.Dv SSL_OP_EPHEMERAL_RSA +usage) while the explicit setting of the key is only useful for key size of +512 bits to satisfy the export restricted ciphers and does give away key length +if a longer key would be allowed. +.Pp +The +.Fa tmp_rsa_callback +is called with the +.Fa keylength +needed and the +.Fa is_export +information. +The +.Fa is_export +flag is set when the ephemeral RSA key exchange is performed with an export +cipher. +.Sh RETURN VALUES +.Fn SSL_CTX_set_tmp_rsa_callback +and +.Fn SSL_set_tmp_rsa_callback +do not return diagnostic output. +.Pp +.Fn SSL_CTX_set_tmp_rsa +and +.Fn SSL_set_tmp_rsa +return 1 on success and 0 on failure. +Check the error queue to find out the reason of failure. +.Pp +.Fn SSL_CTX_need_tmp_rsa +and +.Fn SSL_need_tmp_rsa +return 1 if a temporary RSA key is needed and 0 otherwise. +.Sh EXAMPLES +Generate temporary RSA keys to prepare ephemeral RSA key exchange. +As the generation of a RSA key costs a lot of computer time, +they are saved for later reuse. +For demonstration purposes, two keys for 512 bits and 1024 bits +respectively are generated. +.Bd -literal +\&... + +/* Set up ephemeral RSA stuff */ +RSA *rsa_512 = NULL; +RSA *rsa_1024 = NULL; + +rsa_512 = RSA_generate_key(512, RSA_F4, NULL, NULL); +if (rsa_512 == NULL) + evaluate_error_queue(); + +rsa_1024 = RSA_generate_key(1024, RSA_F4, NULL, NULL); +if (rsa_1024 == NULL) + evaluate_error_queue(); + +\&... + +RSA * +tmp_rsa_callback(SSL *s, int is_export, int keylength) +{ + RSA *rsa_tmp = NULL; + + switch (keylength) { + case 512: + if (rsa_512) + rsa_tmp = rsa_512; + else { + /* + * generate on the fly, + * should not happen in this example + */ + rsa_tmp = RSA_generate_key(keylength, RSA_F4, NULL, + NULL); + rsa_512 = rsa_tmp; /* Remember for later reuse */ + } + break; + case 1024: + if (rsa_1024) + rsa_tmp = rsa_1024; + else + should_not_happen_in_this_example(); + break; + default: + /* + * Generating a key on the fly is very costly, + * so use what is there + */ + if (rsa_1024) + rsa_tmp = rsa_1024; + else + /* Use at least a shorter key */ + rsa_tmp = rsa_512; + } + return rsa_tmp; +} +.Ed +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_new 3 diff --git a/src/lib/libssl/man/SSL_CTX_set_verify.3 b/src/lib/libssl/man/SSL_CTX_set_verify.3 new file mode 100644 index 0000000000..d9821146e7 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_set_verify.3 @@ -0,0 +1,415 @@ +.\" +.\" $OpenBSD: SSL_CTX_set_verify.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_SET_VERIFY 3 +.Os +.Sh NAME +.Nm SSL_CTX_set_verify , +.Nm SSL_set_verify , +.Nm SSL_CTX_set_verify_depth , +.Nm SSL_set_verify_depth +.Nd set peer certificate verification parameters +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fo SSL_CTX_set_verify +.Fa "SSL_CTX *ctx" +.Fa "int mode" +.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" +.Fc +.Ft void +.Fo SSL_set_verify +.Fa "SSL *s" +.Fa "int mode" +.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" +.Fc +.Ft void +.Fn SSL_CTX_set_verify_depth "SSL_CTX *ctx" "int depth" +.Ft void +.Fn SSL_set_verify_depth "SSL *s" "int depth" +.Ft int +.Fn verify_callback "int preverify_ok" "X509_STORE_CTX *x509_ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_set_verify +sets the verification flags for +.Fa ctx +to be +.Fa mode +and +specifies the +.Fa verify_callback +function to be used. +If no callback function shall be specified, the +.Dv NULL +pointer can be used for +.Fa verify_callback . +.Pp +.Fn SSL_set_verify +sets the verification flags for +.Fa ssl +to be +.Fa mode +and specifies the +.Fa verify_callback +function to be used. +If no callback function shall be specified, the +.Dv NULL +pointer can be used for +.Fa verify_callback . +In this case last +.Fa verify_callback +set specifically for this +.Fa ssl +remains. +If no special callback was set before, the default callback for the underlying +.Fa ctx +is used, that was valid at the time +.Fa ssl +was created with +.Xr SSL_new 3 . +.Pp +.Fn SSL_CTX_set_verify_depth +sets the maximum +.Fa depth +for the certificate chain verification that shall be allowed for +.Fa ctx . +(See the +.Sx BUGS +section.) +.Pp +.Fn SSL_set_verify_depth +sets the maximum +.Fa depth +for the certificate chain verification that shall be allowed for +.Fa ssl . +(See the +.Sx BUGS +section.) +.Sh NOTES +The verification of certificates can be controlled by a set of bitwise ORed +.Fa mode +flags: +.Bl -tag -width Ds +.It Dv SSL_VERIFY_NONE +.Em Server mode: +the server will not send a client certificate request to the client, +so the client will not send a certificate. +.Pp +.Em Client mode: +if not using an anonymous cipher (by default disabled), +the server will send a certificate which will be checked. +The result of the certificate verification process can be checked after the +TLS/SSL handshake using the +.Xr SSL_get_verify_result 3 +function. +The handshake will be continued regardless of the verification result. +.It Dv SSL_VERIFY_PEER +.Em Server mode: +the server sends a client certificate request to the client. +The certificate returned (if any) is checked. +If the verification process fails, +the TLS/SSL handshake is immediately terminated with an alert message +containing the reason for the verification failure. +The behaviour can be controlled by the additional +.Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT +and +.Dv SSL_VERIFY_CLIENT_ONCE +flags. +.Pp +.Em Client mode: +the server certificate is verified. +If the verification process fails, +the TLS/SSL handshake is immediately terminated with an alert message +containing the reason for the verification failure. +If no server certificate is sent, because an anonymous cipher is used, +.Dv SSL_VERIFY_PEER +is ignored. +.It Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT +.Em Server mode: +if the client did not return a certificate, the TLS/SSL +handshake is immediately terminated with a +.Dq handshake failure +alert. +This flag must be used together with +.Dv SSL_VERIFY_PEER. +.Pp +.Em Client mode: +ignored +.It Dv SSL_VERIFY_CLIENT_ONCE +.Em Server mode: +only request a client certificate on the initial TLS/SSL handshake. +Do not ask for a client certificate again in case of a renegotiation. +This flag must be used together with +.Dv SSL_VERIFY_PEER . +.Pp +.Em Client mode: +ignored +.El +.Pp +Exactly one of the +.Fa mode +flags +.Dv SSL_VERIFY_NONE +and +.Dv SSL_VERIFY_PEER +must be set at any time. +.Pp +The actual verification procedure is performed either using the built-in +verification procedure or using another application provided verification +function set with +.Xr SSL_CTX_set_cert_verify_callback 3 . +The following descriptions apply in the case of the built-in procedure. +An application provided procedure also has access to the verify depth +information and the +.Fa verify_callback Ns () +function, but the way this information is used may be different. +.Pp +.Fn SSL_CTX_set_verify_depth +and +.Fn SSL_set_verify_depth +set the limit up to which depth certificates in a chain are used during the +verification procedure. +If the certificate chain is longer than allowed, +the certificates above the limit are ignored. +Error messages are generated as if these certificates would not be present, +most likely a +.Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY +will be issued. +The depth count is +.Dq level 0: peer certificate , +.Dq level 1: CA certificate , +.Dq level 2: higher level CA certificate , +and so on. +Setting the maximum depth to 2 allows the levels 0, 1, and 2. +The default depth limit is 100, +allowing for the peer certificate and an additional 100 CA certificates. +.Pp +The +.Fa verify_callback +function is used to control the behaviour when the +.Dv SSL_VERIFY_PEER +flag is set. +It must be supplied by the application and receives two arguments: +.Fa preverify_ok +indicates whether the verification of the certificate in question was passed +(preverify_ok=1) or not (preverify_ok=0). +.Fa x509_ctx +is a pointer to the complete context used +for the certificate chain verification. +.Pp +The certificate chain is checked starting with the deepest nesting level +(the root CA certificate) and worked upward to the peer's certificate. +At each level signatures and issuer attributes are checked. +Whenever a verification error is found, the error number is stored in +.Fa x509_ctx +and +.Fa verify_callback +is called with +.Fa preverify_ok +equal to 0. +By applying +.Fn X509_CTX_store_* +functions +.Fa verify_callback +can locate the certificate in question and perform additional steps (see +.Sx EXAMPLES ) . +If no error is found for a certificate, +.Fa verify_callback +is called with +.Fa preverify_ok +equal to 1 before advancing to the next level. +.Pp +The return value of +.Fa verify_callback +controls the strategy of the further verification process. +If +.Fa verify_callback +returns 0, the verification process is immediately stopped with +.Dq verification failed +state. +If +.Dv SSL_VERIFY_PEER +is set, a verification failure alert is sent to the peer and the TLS/SSL +handshake is terminated. +If +.Fa verify_callback +returns 1, the verification process is continued. +If +.Fa verify_callback +always returns 1, +the TLS/SSL handshake will not be terminated with respect to verification +failures and the connection will be established. +The calling process can however retrieve the error code of the last +verification error using +.Xr SSL_get_verify_result 3 +or by maintaining its own error storage managed by +.Fa verify_callback . +.Pp +If no +.Fa verify_callback +is specified, the default callback will be used. +Its return value is identical to +.Fa preverify_ok , +so that any verification +failure will lead to a termination of the TLS/SSL handshake with an +alert message, if +.Dv SSL_VERIFY_PEER +is set. +.Sh RETURN VALUES +The +.Fn SSL*_set_verify* +functions do not provide diagnostic information. +.Sh EXAMPLES +The following code sequence realizes an example +.Fa verify_callback +function that will always continue the TLS/SSL handshake regardless of +verification failure, if wished. +The callback realizes a verification depth limit with more informational output. +.Pp +All verification errors are printed; +information about the certificate chain is printed on request. +The example is realized for a server that does allow but not require client +certificates. +.Pp +The example makes use of the ex_data technique to store application data +into/retrieve application data from the +.Vt SSL +structure (see +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 ) . +.Bd -literal +\&... + +typedef struct { + int verbose_mode; + int verify_depth; + int always_continue; +} mydata_t; +int mydata_index; +\&... +static int +verify_callback(int preverify_ok, X509_STORE_CTX *ctx) +{ + char buf[256]; + X509 *err_cert; + int err, depth; + SSL *ssl; + mydata_t *mydata; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + /* + * Retrieve the pointer to the SSL of the connection currently + * treated * and the application specific data stored into the + * SSL object. + */ + ssl = X509_STORE_CTX_get_ex_data(ctx, + SSL_get_ex_data_X509_STORE_CTX_idx()); + mydata = SSL_get_ex_data(ssl, mydata_index); + + X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); + + /* + * Catch a too long certificate chain. The depth limit set using + * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so + * that whenever the "depth>verify_depth" condition is met, we + * have violated the limit and want to log this error condition. + * We must do it here, because the CHAIN_TOO_LONG error would not + * be found explicitly; only errors introduced by cutting off the + * additional certificates would be logged. + */ + if (depth > mydata->verify_depth) { + preverify_ok = 0; + err = X509_V_ERR_CERT_CHAIN_TOO_LONG; + X509_STORE_CTX_set_error(ctx, err); + } + if (!preverify_ok) { + printf("verify error:num=%d:%s:depth=%d:%s\en", err, + X509_verify_cert_error_string(err), depth, buf); + } else if (mydata->verbose_mode) { + printf("depth=%d:%s\en", depth, buf); + } + + /* + * At this point, err contains the last verification error. + * We can use it for something special + */ + if (!preverify_ok && (err == + X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) { + X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), + buf, 256); + printf("issuer= %s\en", buf); + } + + if (mydata->always_continue) + return 1; + else + return preverify_ok; +} +\&... + +mydata_t mydata; + +\&... + +mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); + +\&... + +SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, + verify_callback); + +/* + * Let the verify_callback catch the verify_depth error so that we get + * an appropriate error in the logfile. + */ +SSL_CTX_set_verify_depth(verify_depth + 1); + +/* + * Set up the SSL specific data into "mydata" and store it into the SSL + * structure. + */ +mydata.verify_depth = verify_depth; ... +SSL_set_ex_data(ssl, mydata_index, &mydata); + +\&... + +SSL_accept(ssl); /* check of success left out for clarity */ +if (peer = SSL_get_peer_certificate(ssl)) { + if (SSL_get_verify_result(ssl) == X509_V_OK) { + /* The client sent a certificate which verified OK */ + } +} +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_get_verify_mode 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_cert_verify_callback 3 , +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_verify_result 3 , +.Xr SSL_new 3 +.Sh BUGS +In client mode, it is not checked whether the +.Dv SSL_VERIFY_PEER +flag is set, but whether +.Dv SSL_VERIFY_NONE +is not set. +This can lead to unexpected behaviour, if the +.Dv SSL_VERIFY_PEER +and +.Dv SSL_VERIFY_NONE +are not used as required (exactly one must be set at any time). +.Pp +The certificate verification depth set with +.Fn SSL[_CTX]_verify_depth +stops the verification at a certain depth. +The error message produced will be that of an incomplete certificate chain and +not +.Dv X509_V_ERR_CERT_CHAIN_TOO_LONG +as may be expected. diff --git a/src/lib/libssl/man/SSL_CTX_use_certificate.3 b/src/lib/libssl/man/SSL_CTX_use_certificate.3 new file mode 100644 index 0000000000..58a9310533 --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_use_certificate.3 @@ -0,0 +1,336 @@ +.\" +.\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_USE_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_CTX_use_certificate , +.Nm SSL_CTX_use_certificate_ASN1 , +.Nm SSL_CTX_use_certificate_file , +.Nm SSL_use_certificate , +.Nm SSL_use_certificate_ASN1 , +.Nm SSL_use_certificate_file , +.Nm SSL_CTX_use_certificate_chain_file , +.Nm SSL_CTX_use_certificate_chain_mem , +.Nm SSL_CTX_use_PrivateKey , +.Nm SSL_CTX_use_PrivateKey_ASN1 , +.Nm SSL_CTX_use_PrivateKey_file , +.Nm SSL_CTX_use_RSAPrivateKey , +.Nm SSL_CTX_use_RSAPrivateKey_ASN1 , +.Nm SSL_CTX_use_RSAPrivateKey_file , +.Nm SSL_use_PrivateKey_file , +.Nm SSL_use_PrivateKey_ASN1 , +.Nm SSL_use_PrivateKey , +.Nm SSL_use_RSAPrivateKey , +.Nm SSL_use_RSAPrivateKey_ASN1 , +.Nm SSL_use_RSAPrivateKey_file , +.Nm SSL_CTX_check_private_key , +.Nm SSL_check_private_key +.Nd load certificate and key data +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x" +.Ft int +.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d" +.Ft int +.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "const char *file" "int type" +.Ft int +.Fn SSL_use_certificate "SSL *ssl" "X509 *x" +.Ft int +.Fn SSL_use_certificate_ASN1 "SSL *ssl" "unsigned char *d" "int len" +.Ft int +.Fn SSL_use_certificate_file "SSL *ssl" "const char *file" "int type" +.Ft int +.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file" +.Ft int +.Fn SSL_CTX_use_certificate_chain_mem "SSL_CTX *ctx" "void *buf" "int len" +.Ft int +.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey" +.Ft int +.Fo SSL_CTX_use_PrivateKey_ASN1 +.Fa "int pk" "SSL_CTX *ctx" "unsigned char *d" "long len" +.Fc +.Ft int +.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa" +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len" +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "const char *file" "int type" +.Ft int +.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey" +.Ft int +.Fn SSL_use_PrivateKey_ASN1 "int pk" "SSL *ssl" "unsigned char *d" "long len" +.Ft int +.Fn SSL_use_PrivateKey_file "SSL *ssl" "const char *file" "int type" +.Ft int +.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa" +.Ft int +.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len" +.Ft int +.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "const char *file" "int type" +.Ft int +.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx" +.Ft int +.Fn SSL_check_private_key "const SSL *ssl" +.Sh DESCRIPTION +These functions load the certificates and private keys into the +.Vt SSL_CTX +or +.Vt SSL +object, respectively. +.Pp +The +.Fn SSL_CTX_* +class of functions loads the certificates and keys into the +.Vt SSL_CTX +object +.Fa ctx . +The information is passed to +.Vt SSL +objects +.Fa ssl +created from +.Fa ctx +with +.Xr SSL_new 3 +by copying, so that changes applied to +.Fa ctx +do not propagate to already existing +.Vt SSL +objects. +.Pp +The +.Fn SSL_* +class of functions only loads certificates and keys into a specific +.Vt SSL +object. +The specific information is kept when +.Xr SSL_clear 3 +is called for this +.Vt SSL +object. +.Pp +.Fn SSL_CTX_use_certificate +loads the certificate +.Fa x +into +.Fa ctx ; +.Fn SSL_use_certificate +loads +.Fa x +into +.Fa ssl . +The rest of the certificates needed to form the complete certificate chain can +be specified using the +.Xr SSL_CTX_add_extra_chain_cert 3 +function. +.Pp +.Fn SSL_CTX_use_certificate_ASN1 +loads the ASN1 encoded certificate from the memory location +.Fa d +(with length +.Fa len ) +into +.Fa ctx ; +.Fn SSL_use_certificate_ASN1 +loads the ASN1 encoded certificate into +.Fa ssl . +.Pp +.Fn SSL_CTX_use_certificate_file +loads the first certificate stored in +.Fa file +into +.Fa ctx . +The formatting +.Fa type +of the certificate must be specified from the known types +.Dv SSL_FILETYPE_PEM +and +.Dv SSL_FILETYPE_ASN1 . +.Fn SSL_use_certificate_file +loads the certificate from +.Fa file +into +.Fa ssl . +See the +.Sx NOTES +section on why +.Fn SSL_CTX_use_certificate_chain_file +should be preferred. +.Pp +The +.Fn SSL_CTX_use_certificate_chain* +functions load a certificate chain into +.Fa ctx . +The certificates must be in PEM format and must be sorted starting with the +subject's certificate (actual client or server certificate), +followed by intermediate CA certificates if applicable, +and ending at the highest level (root) CA. +There is no corresponding function working on a single +.Vt SSL +object. +.Pp +.Fn SSL_CTX_use_PrivateKey +adds +.Fa pkey +as private key to +.Fa ctx . +.Fn SSL_CTX_use_RSAPrivateKey +adds the private key +.Fa rsa +of type RSA to +.Fa ctx . +.Fn SSL_use_PrivateKey +adds +.Fa pkey +as private key to +.Fa ssl ; +.Fn SSL_use_RSAPrivateKey +adds +.Fa rsa +as private key of type RSA to +.Fa ssl . +If a certificate has already been set and the private does not belong to the +certificate, an error is returned. +To change a certificate private key pair, +the new certificate needs to be set with +.Fn SSL_use_certificate +or +.Fn SSL_CTX_use_certificate +before setting the private key with +.Fn SSL_CTX_use_PrivateKey +or +.Fn SSL_use_PrivateKey . +.Pp +.Fn SSL_CTX_use_PrivateKey_ASN1 +adds the private key of type +.Fa pk +stored at memory location +.Fa d +(length +.Fa len ) +to +.Fa ctx . +.Fn SSL_CTX_use_RSAPrivateKey_ASN1 +adds the private key of type RSA stored at memory location +.Fa d +(length +.Fa len ) +to +.Fa ctx . +.Fn SSL_use_PrivateKey_ASN1 +and +.Fn SSL_use_RSAPrivateKey_ASN1 +add the private key to +.Fa ssl . +.Pp +.Fn SSL_CTX_use_PrivateKey_file +adds the first private key found in +.Fa file +to +.Fa ctx . +The formatting +.Fa type +of the certificate must be specified from the known types +.Dv SSL_FILETYPE_PEM +and +.Dv SSL_FILETYPE_ASN1 . +.Fn SSL_CTX_use_RSAPrivateKey_file +adds the first private RSA key found in +.Fa file +to +.Fa ctx . +.Fn SSL_use_PrivateKey_file +adds the first private key found in +.Fa file +to +.Fa ssl ; +.Fn SSL_use_RSAPrivateKey_file +adds the first private RSA key found to +.Fa ssl . +.Pp +.Fn SSL_CTX_check_private_key +checks the consistency of a private key with the corresponding certificate +loaded into +.Fa ctx . +If more than one key/certificate pair (RSA/DSA) is installed, +the last item installed will be checked. +If, e.g., the last item was a RSA certificate or key, +the RSA key/certificate pair will be checked. +.Fn SSL_check_private_key +performs the same check for +.Fa ssl . +If no key/certificate was explicitly added for this +.Fa ssl , +the last item added into +.Fa ctx +will be checked. +.Sh NOTES +The internal certificate store of OpenSSL can hold two private key/certificate +pairs at a time: +one key/certificate of type RSA and one key/certificate of type DSA. +The certificate used depends on the cipher select, see also +.Xr SSL_CTX_set_cipher_list 3 . +.Pp +When reading certificates and private keys from file, files of type +.Dv SSL_FILETYPE_ASN1 +(also known as +.Em DER , +binary encoding) can only contain one certificate or private key; consequently, +.Fn SSL_CTX_use_certificate_chain_file +is only applicable to PEM formatting. +Files of type +.Dv SSL_FILETYPE_PEM +can contain more than one item. +.Pp +.Fn SSL_CTX_use_certificate_chain_file +adds the first certificate found in the file to the certificate store. +The other certificates are added to the store of chain certificates using +.Xr SSL_CTX_add_extra_chain_cert 3 . +There exists only one extra chain store, so that the same chain is appended +to both types of certificates, RSA and DSA! +If it is not intended to use both type of certificate at the same time, +it is recommended to use the +.Fn SSL_CTX_use_certificate_chain_file +instead of the +.Fn SSL_CTX_use_certificate_file +function in order to allow the use of complete certificate chains even when no +trusted CA storage is used or when the CA issuing the certificate shall not be +added to the trusted CA storage. +.Pp +If additional certificates are needed to complete the chain during the TLS +negotiation, CA certificates are additionally looked up in the locations of +trusted CA certificates (see +.Xr SSL_CTX_load_verify_locations 3 ) . +.Pp +The private keys loaded from file can be encrypted. +In order to successfully load encrypted keys, +a function returning the passphrase must have been supplied (see +.Xr SSL_CTX_set_default_passwd_cb 3 ) . +(Certificate files might be encrypted as well from the technical point of view, +it however does not make sense as the data in the certificate is considered +public anyway.) +.Sh RETURN VALUES +On success, the functions return 1. +Otherwise check out the error stack to find out the reason. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_default_passwd_cb 3 , +.Xr SSL_new 3 +.Sh HISTORY +Support for DER encoded private keys +.Pq Dv SSL_FILETYPE_ASN1 +in +.Fn SSL_CTX_use_PrivateKey_file +and +.Fn SSL_use_PrivateKey_file +was added in 0.9.8. diff --git a/src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3 b/src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3 new file mode 100644 index 0000000000..7d5d6b1dfd --- /dev/null +++ b/src/lib/libssl/man/SSL_CTX_use_psk_identity_hint.3 @@ -0,0 +1,110 @@ +.\" +.\" $OpenBSD: SSL_CTX_use_psk_identity_hint.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CTX_USE_PSK_IDENTITY_HINT 3 +.Os +.Sh NAME +.Nm SSL_CTX_use_psk_identity_hint , +.Nm SSL_use_psk_identity_hint , +.Nm SSL_CTX_set_psk_server_callback , +.Nm SSL_set_psk_server_callback +.Nd set PSK identity hint to use +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_CTX_use_psk_identity_hint "SSL_CTX *ctx" "const char *hint" +.Ft int +.Fn SSL_use_psk_identity_hint "SSL *ssl" "const char *hint" +.Ft void +.Fo SSL_CTX_set_psk_server_callback +.Fa "SSL_CTX *ctx" +.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)" +.Fc +.Ft void +.Fo SSL_set_psk_server_callback +.Fa "SSL *ssl" +.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)" +.Fc +.Sh DESCRIPTION +.Fn SSL_CTX_use_psk_identity_hint +sets the given +.Dv NULL Ns +-terminated PSK identity hint +.Fa hint +to SSL context object +.Fa ctx . +.Fn SSL_use_psk_identity_hint +sets the given +.Dv NULL Ns +-terminated +PSK identity hint +.Fa hint +to SSL connection object +.Fa ssl . +If +.Fa hint +is +.Dv NULL +the current hint from +.Fa ctx +or +.Fa ssl +is deleted. +.Pp +In the case where PSK identity hint is +.Dv NULL , +the server does not send the +.Em ServerKeyExchange +message to the client. +.Pp +A server application must provide a callback function which is called when the +server receives the +.Em ClientKeyExchange +message from the client. +The purpose of the callback function is to validate the received PSK identity +and to fetch the pre-shared key used during the connection setup phase. +The callback is set using functions +.Fn SSL_CTX_set_psk_server_callback +or +.Fn SSL_set_psk_server_callback . +The callback function is given the connection in parameter +.Fa ssl , +.Dv NULL Ns +-terminated PSK identity sent by the client in parameter +.Fa identity , +and a buffer +.Fa psk +of length +.Fa max_psk_len +bytes where the pre-shared key is to be stored. +.Sh RETURN VALUES +.Fn SSL_CTX_use_psk_identity_hint +and +.Fn SSL_use_psk_identity_hint +return 1 on success, 0 otherwise. +.Pp +Return values from the server callback are interpreted as follows: +.Bl -tag -width Ds +.It >0 +PSK identity was found and the server callback has provided the PSK +successfully in parameter +.Fa psk . +Return value is the length of +.Fa psk +in bytes. +It is an error to return a value greater than +.Fa max_psk_len . +.Pp +If the PSK identity was not found but the callback instructs the protocol to +continue anyway, the callback must provide some random data to +.Fa psk +and return the length of the random data, so the connection will fail with +.Dq decryption_error +before it will be finished completely. +.It 0 +PSK identity was not found. +An +.Dq unknown_psk_identity +alert message will be sent and the connection setup fails. +.El diff --git a/src/lib/libssl/man/SSL_SESSION_free.3 b/src/lib/libssl/man/SSL_SESSION_free.3 new file mode 100644 index 0000000000..8eabe8da80 --- /dev/null +++ b/src/lib/libssl/man/SSL_SESSION_free.3 @@ -0,0 +1,84 @@ +.\" +.\" $OpenBSD: SSL_SESSION_free.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SESSION_FREE 3 +.Os +.Sh NAME +.Nm SSL_SESSION_free +.Nd free an allocated SSL_SESSION structure +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_SESSION_free "SSL_SESSION *session" +.Sh DESCRIPTION +.Fn SSL_SESSION_free +decrements the reference count of +.Fa session +and removes the +.Vt SSL_SESSION +structure pointed to by +.Fa session +and frees up the allocated memory, if the reference count has reached 0. +If +.Fa session +is a +.Dv NULL +pointer, no action occurs. +.Sh NOTES +.Vt SSL_SESSION +objects are allocated when a TLS/SSL handshake operation is successfully +completed. +Depending on the settings, see +.Xr SSL_CTX_set_session_cache_mode 3 , +the +.Vt SSL_SESSION +objects are internally referenced by the +.Vt SSL_CTX +and linked into its session cache. +.Vt SSL +objects may be using the +.Vt SSL_SESSION +object; as a session may be reused, several +.Vt SSL +objects may be using one +.Vt SSL_SESSION +object at the same time. +It is therefore crucial to keep the reference count (usage information) correct +and not delete a +.Vt SSL_SESSION +object that is still used, as this may lead to program failures due to dangling +pointers. +These failures may also appear delayed, e.g., when an +.Vt SSL_SESSION +object is completely freed as the reference count incorrectly becomes 0, but it +is still referenced in the internal session cache and the cache list is +processed during a +.Xr SSL_CTX_flush_sessions 3 +operation. +.Pp +.Fn SSL_SESSION_free +must only be called for +.Vt SSL_SESSION +objects, for which the reference count was explicitly incremented (e.g., by +calling +.Xr SSL_get1_session 3 ; +see +.Xr SSL_get_session 3 ) +or when the +.Vt SSL_SESSION +object was generated outside a TLS handshake operation, e.g., by using +.Xr d2i_SSL_SESSION 3 . +It must not be called on other +.Vt SSL_SESSION +objects, as this would cause incorrect reference counts and therefore program +failures. +.Sh RETURN VALUES +.Fn SSL_SESSION_free +does not provide diagnostic information. +.Sh SEE ALSO +.Xr d2i_SSL_SESSION 3 , +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_get_session 3 diff --git a/src/lib/libssl/man/SSL_SESSION_get_ex_new_index.3 b/src/lib/libssl/man/SSL_SESSION_get_ex_new_index.3 new file mode 100644 index 0000000000..0779db91b8 --- /dev/null +++ b/src/lib/libssl/man/SSL_SESSION_get_ex_new_index.3 @@ -0,0 +1,80 @@ +.\" +.\" $OpenBSD: SSL_SESSION_get_ex_new_index.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SESSION_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_ex_new_index , +.Nm SSL_SESSION_set_ex_data , +.Nm SSL_SESSION_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_SESSION_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fn SSL_SESSION_set_ex_data "SSL_SESSION *session" "int idx" "void *arg" +.Ft void * +.Fn SSL_SESSION_get_ex_data "const SSL_SESSION *session" "int idx" +.Bd -literal + typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); +.Ed +.Sh DESCRIPTION +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate +application-specific data attached to a specific structure. +.Pp +.Fn SSL_SESSION_get_ex_new_index +is used to register a new index for application-specific data. +.Pp +.Fn SSL_SESSION_set_ex_data +is used to store application data at +.Fa arg +for +.Fa idx +into the +.Fa session +object. +.Pp +.Fn SSL_SESSION_get_ex_data +is used to retrieve the information for +.Fa idx +from +.Fa session . +.Pp +A detailed description for the +.Fn *_get_ex_new_index +functionality +can be found in +.Xr RSA_get_ex_new_index 3 . +The +.Fn *_get_ex_data +and +.Fn *_set_ex_data +functionality is described in +.Xr CRYPTO_set_ex_data 3 . +.Sh WARNINGS +The application data is only maintained for sessions held in memory. +The application data is not included when dumping the session with +.Xr i2d_SSL_SESSION 3 +(and all functions indirectly calling the dump functions like +.Xr PEM_write_SSL_SESSION 3 +and +.Xr PEM_write_bio_SSL_SESSION 3 ) +and can therefore not be restored. +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_SESSION_get_time.3 b/src/lib/libssl/man/SSL_SESSION_get_time.3 new file mode 100644 index 0000000000..9641290e71 --- /dev/null +++ b/src/lib/libssl/man/SSL_SESSION_get_time.3 @@ -0,0 +1,98 @@ +.\" +.\" $OpenBSD: SSL_SESSION_get_time.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SESSION_GET_TIME 3 +.Os +.Sh NAME +.Nm SSL_SESSION_get_time , +.Nm SSL_SESSION_set_time , +.Nm SSL_SESSION_get_timeout , +.Nm SSL_SESSION_set_timeout , +.Nm SSL_get_time , +.Nm SSL_set_time , +.Nm SSL_get_timeout , +.Nm SSL_set_timeout +.Nd retrieve and manipulate session time and timeout settings +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_SESSION_get_time "const SSL_SESSION *s" +.Ft long +.Fn SSL_SESSION_set_time "SSL_SESSION *s" "long tm" +.Ft long +.Fn SSL_SESSION_get_timeout "const SSL_SESSION *s" +.Ft long +.Fn SSL_SESSION_set_timeout "SSL_SESSION *s" "long tm" +.Ft long +.Fn SSL_get_time "const SSL_SESSION *s" +.Ft long +.Fn SSL_set_time "SSL_SESSION *s" "long tm" +.Ft long +.Fn SSL_get_timeout "const SSL_SESSION *s" +.Ft long +.Fn SSL_set_timeout "SSL_SESSION *s" "long tm" +.Sh DESCRIPTION +.Fn SSL_SESSION_get_time +returns the time at which the session +.Fa s +was established. +The time is given in seconds since the Epoch and therefore compatible to the +time delivered by the +.Xr time 3 +call. +.Pp +.Fn SSL_SESSION_set_time +replaces the creation time of the session +.Fa s +with +the chosen value +.Fa tm . +.Pp +.Fn SSL_SESSION_get_timeout +returns the timeout value set for session +.Fa s +in seconds. +.Pp +.Fn SSL_SESSION_set_timeout +sets the timeout value for session +.Fa s +in seconds to +.Fa tm . +.Pp +The +.Fn SSL_get_time , +.Fn SSL_set_time , +.Fn SSL_get_timeout , +and +.Fn SSL_set_timeout +functions are synonyms for the +.Fn SSL_SESSION_* +counterparts. +.Sh NOTES +Sessions are expired by examining the creation time and the timeout value. +Both are set at creation time of the session to the actual time and the default +timeout value at creation, respectively, as set by +.Xr SSL_CTX_set_timeout 3 . +Using these functions it is possible to extend or shorten the lifetime of the +session. +.Sh RETURN VALUES +.Fn SSL_SESSION_get_time +and +.Fn SSL_SESSION_get_timeout +return the currently valid values. +.Pp +.Fn SSL_SESSION_set_time +and +.Fn SSL_SESSION_set_timeout +return 1 on success. +.Pp +If any of the function is passed the +.Dv NULL +pointer for the session +.Fa s , +0 is returned. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_timeout 3 , +.Xr SSL_get_default_timeout 3 diff --git a/src/lib/libssl/man/SSL_accept.3 b/src/lib/libssl/man/SSL_accept.3 new file mode 100644 index 0000000000..944fb50c28 --- /dev/null +++ b/src/lib/libssl/man/SSL_accept.3 @@ -0,0 +1,103 @@ +.\" +.\" $OpenBSD: SSL_accept.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_ACCEPT 3 +.Os +.Sh NAME +.Nm SSL_accept +.Nd wait for a TLS/SSL client to initiate a TLS/SSL handshake +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_accept "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_accept +waits for a TLS/SSL client to initiate the TLS/SSL handshake. +The communication channel must already have been set and assigned to the +.Fa ssl +object by setting an underlying +.Vt BIO . +.Sh NOTES +The behaviour of +.Fn SSL_accept +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_accept +will only return once the handshake has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_accept +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_accept +to continue the handshake, indicating the problem by the return value \(mi1. +In this case a call to +.Xr SSL_get_error 3 +with the +return value of +.Fn SSL_accept +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_accept . +The action depends on the underlying +.Dv BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and by +the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <0 +The TLS/SSL handshake was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. +The shutdown was not clean. +It can also occur of action is need to continue the operation for non-blocking +.Vt BIO Ns +s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_alert_type_string.3 b/src/lib/libssl/man/SSL_alert_type_string.3 new file mode 100644 index 0000000000..ff68ba5858 --- /dev/null +++ b/src/lib/libssl/man/SSL_alert_type_string.3 @@ -0,0 +1,193 @@ +.\" +.\" $OpenBSD: SSL_alert_type_string.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_ALERT_TYPE_STRING.POD 3 +.Os +.Sh NAME +.Nm SSL_alert_type_string , +.Nm SSL_alert_type_string_long , +.Nm SSL_alert_desc_string , +.Nm SSL_alert_desc_string_long +.Nd get textual description of alert information +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft const char * +.Fn SSL_alert_type_string "int value" +.Ft const char * +.Fn SSL_alert_type_string_long "int value" +.Ft const char * +.Fn SSL_alert_desc_string "int value" +.Ft const char * +.Fn SSL_alert_desc_string_long "int value" +.Sh DESCRIPTION +.Fn SSL_alert_type_string +returns a one letter string indicating the type of the alert specified by +.Fa value . +.Pp +.Fn SSL_alert_type_string_long +returns a string indicating the type of the alert specified by +.Fa value . +.Pp +.Fn SSL_alert_desc_string +returns a two letter string as a short form describing the reason of the alert +specified by +.Fa value . +.Pp +.Fn SSL_alert_desc_string_long +returns a string describing the reason of the alert specified by +.Fa value . +.Sh NOTES +When one side of an SSL/TLS communication wants to inform the peer about +a special situation, it sends an alert. +The alert is sent as a special message and does not influence the normal data +stream (unless its contents results in the communication being canceled). +.Pp +A warning alert is sent, when a non-fatal error condition occurs. +The +.Dq close notify +alert is sent as a warning alert. +Other examples for non-fatal errors are certificate errors +.Po +.Dq certificate expired , +.Dq unsupported certificate +.Pc , +for which a warning alert may be sent. +(The sending party may, however, decide to send a fatal error.) +The receiving side may cancel the connection on reception of a warning alert at +its discretion. +.Pp +Several alert messages must be sent as fatal alert messages as specified +by the TLS RFC. +A fatal alert always leads to a connection abort. +.Sh RETURN VALUES +The following strings can occur for +.Fn SSL_alert_type_string +or +.Fn SSL_alert_type_string_long : +.Bl -tag -width Ds +.It \(dqW\(dq/\(dqwarning\(dq +.It \(dqF\(dq/\(dqfatal\(dq +.It \(dqU\(dq/\(dqunknown\(dq +This indicates that no support is available for this alert type. +Probably +.Fa value +does not contain a correct alert message. +.El +.Pp +The following strings can occur for +.Fn SSL_alert_desc_string +or +.Fn SSL_alert_desc_string_long : +.Bl -tag -width Ds +.It \(dqCN\(dq/\(dqclose notify\(dq +The connection shall be closed. +This is a warning alert. +.It \(dqUM\(dq/\(dqunexpected message\(dq +An inappropriate message was received. +This alert is always fatal and should never be observed in communication +between proper implementations. +.It \(dqBM\(dq/\(dqbad record mac\(dq +This alert is returned if a record is received with an incorrect MAC. +This message is always fatal. +.It \(dqDF\(dq/\(dqdecompression failure\(dq +The decompression function received improper input +(e.g., data that would expand to excessive length). +This message is always fatal. +.It \(dqHF\(dq/\(dqhandshake failure\(dq +Reception of a handshake_failure alert message indicates that the sender was +unable to negotiate an acceptable set of security parameters given the options +available. +This is a fatal error. +.It \(dqNC\(dq/\(dqno certificate\(dq +A client, that was asked to send a certificate, does not send a certificate +(SSLv3 only). +.It \(dqBC\(dq/\(dqbad certificate\(dq +A certificate was corrupt, contained signatures that did not verify correctly, +etc. +.It \(dqUC\(dq/\(dqunsupported certificate\(dq +A certificate was of an unsupported type. +.It \(dqCR\(dq/\(dqcertificate revoked\(dq +A certificate was revoked by its signer. +.It \(dqCE\(dq/\(dqcertificate expired\(dq +A certificate has expired or is not currently valid. +.It \(dqCU\(dq/\(dqcertificate unknown\(dq +Some other (unspecified) issue arose in processing the certificate, +rendering it unacceptable. +.It \(dqIP\(dq/\(dqillegal parameter\(dq +A field in the handshake was out of range or inconsistent with other fields. +This is always fatal. +.It \(dqDC\(dq/\(dqdecryption failed\(dq +A TLSCiphertext decrypted in an invalid way: either it wasn't an even multiple +of the block length or its padding values, when checked, weren't correct. +This message is always fatal. +.It \(dqRO\(dq/\(dqrecord overflow\(dq +A TLSCiphertext record was received which had a length more than +2^14+2048 bytes, or a record decrypted to a TLSCompressed record with more than +2^14+1024 bytes. +This message is always fatal. +.It \(dqCA\(dq/\(dqunknown CA\(dq +A valid certificate chain or partial chain was received, +but the certificate was not accepted because the CA certificate could not be +located or couldn't be matched with a known, trusted CA. +This message is always fatal. +.It \(dqAD\(dq/\(dqaccess denied\(dq +A valid certificate was received, but when access control was applied, +the sender decided not to proceed with negotiation. +This message is always fatal. +.It \(dqDE\(dq/\(dqdecode error\(dq +A message could not be decoded because some field was out of the specified +range or the length of the message was incorrect. +This message is always fatal. +.It \(dqCY\(dq/\(dqdecrypt error\(dq +A handshake cryptographic operation failed, including being unable to correctly +verify a signature, decrypt a key exchange, or validate a finished message. +.It \(dqER\(dq/\(dqexport restriction\(dq +A negotiation not in compliance with export restrictions was detected; +for example, attempting to transfer a 1024 bit ephemeral RSA key for the +RSA_EXPORT handshake method. +This message is always fatal. +.It \(dqPV\(dq/\(dqprotocol version\(dq +The protocol version the client has attempted to negotiate is recognized, +but not supported. +(For example, old protocol versions might be avoided for security reasons.) +This message is always fatal. +.It \(dqIS\(dq/\(dqinsufficient security\(dq +Returned instead of handshake_failure when a negotiation has failed +specifically because the server requires ciphers more secure than those +supported by the client. +This message is always fatal. +.It \(dqIE\(dq/\(dqinternal error\(dq +An internal error unrelated to the peer or the correctness of the protocol +makes it impossible to continue (such as a memory allocation failure). +This message is always fatal. +.It \(dqUS\(dq/\(dquser canceled\(dq +This handshake is being canceled for some reason unrelated to a protocol +failure. +If the user cancels an operation after the handshake is complete, +just closing the connection by sending a close_notify is more appropriate. +This alert should be followed by a close_notify. +This message is generally a warning. +.It \(dqNR\(dq/\(dqno renegotiation\(dq +Sent by the client in response to a hello request or by the server in response +to a client hello after initial handshaking. +Either of these would normally lead to renegotiation; when that is not +appropriate, the recipient should respond with this alert; at that point, +the original requester can decide whether to proceed with the connection. +One case where this would be appropriate would be where a server has spawned a +process to satisfy a request; the process might receive security parameters +(key length, authentication, etc.) at startup and it might be difficult to +communicate changes to these parameters after that point. +This message is always a warning. +.It \(dqUP\(dq/\(dqunknown PSK identity\(dq +Sent by the server to indicate that it does not recognize a PSK identity or an +SRP identity. +.It \(dqUK\(dq/\(dqunknown\(dq +This indicates that no description is available for this alert type. +Probably +.Fa value +does not contain a correct alert message. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_info_callback 3 diff --git a/src/lib/libssl/man/SSL_clear.3 b/src/lib/libssl/man/SSL_clear.3 new file mode 100644 index 0000000000..a9e318320f --- /dev/null +++ b/src/lib/libssl/man/SSL_clear.3 @@ -0,0 +1,92 @@ +.\" +.\" $OpenBSD: SSL_clear.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CLEAR 3 +.Os +.Sh NAME +.Nm SSL_clear +.Nd reset SSL object to allow another connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_clear "SSL *ssl" +.Sh DESCRIPTION +Reset +.Fa ssl +to allow another connection. +All settings (method, ciphers, BIOs) are kept. +.Sh NOTES +.Fn SSL_clear +is used to prepare an +.Vt SSL +object for a new connection. +While all settings are kept, +a side effect is the handling of the current SSL session. +If a session is still +.Em open , +it is considered bad and will be removed from the session cache, +as required by RFC2246. +A session is considered open if +.Xr SSL_shutdown 3 +was not called for the connection or at least +.Xr SSL_set_shutdown 3 +was used to +set the +.Dv SSL_SENT_SHUTDOWN +state. +.Pp +If a session was closed cleanly, +the session object will be kept and all settings corresponding. +This explicitly means that for example the special method used during the +session will be kept for the next handshake. +So if the session was a TLSv1 session, a +.Vt SSL +client object will use a TLSv1 client method for the next handshake and a +.Vt SSL +server object will use a TLSv1 server method, even if +.Fn SSLv23_*_method Ns s +were chosen on startup. +This might lead to connection failures (see +.Xr SSL_new 3 ) +for a description of the method's properties. +.Sh WARNINGS +.Fn SSL_clear +resets the +.Vt SSL +object to allow for another connection. +The reset operation however keeps several settings of the last sessions +(some of these settings were made automatically during the last handshake). +It only makes sense for a new connection with the exact same peer that shares +these settings, +and may fail if that peer changes its settings between connections. +Use the sequence +.Xr SSL_get_session 3 ; +.Xr SSL_new 3 ; +.Xr SSL_set_session 3 ; +.Xr SSL_free 3 +instead to avoid such failures (or simply +.Xr SSL_free 3 ; +.Xr SSL_new 3 +if session reuse is not desired). +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The +.Fn SSL_clear +operation could not be performed. +Check the error stack to find out the reason. +.It 1 +The +.Fn SSL_clear +operation was successful. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_free 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_connect.3 b/src/lib/libssl/man/SSL_connect.3 new file mode 100644 index 0000000000..761fde3548 --- /dev/null +++ b/src/lib/libssl/man/SSL_connect.3 @@ -0,0 +1,102 @@ +.\" +.\" $OpenBSD: SSL_connect.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_CONNECT 3 +.Os +.Sh NAME +.Nm SSL_connect +.Nd initiate the TLS/SSL handshake with a TLS/SSL server +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_connect "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_connect +initiates the TLS/SSL handshake with a server. +The communication channel must already have been set and assigned to the +.Fa ssl +by setting an underlying +.Vt BIO . +.Sh NOTES +The behaviour of +.Fn SSL_connect +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_connect +will only return once the handshake has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_connect +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_connect +to continue the handshake, indicating the problem with the return value \(mi1. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_connect +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_connect . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <0 +The TLS/SSL handshake was not successful, because either a fatal error occurred +at the protocol level or a connection failure occurred. +The shutdown was not clean. +It can also occur if action is needed to continue the operation for +non-blocking +.Vt BIO Ns s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_do_handshake.3 b/src/lib/libssl/man/SSL_do_handshake.3 new file mode 100644 index 0000000000..7f8a9a4509 --- /dev/null +++ b/src/lib/libssl/man/SSL_do_handshake.3 @@ -0,0 +1,101 @@ +.\" +.\" $OpenBSD: SSL_do_handshake.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_DO_HANDSHAKE 3 +.Os +.Sh NAME +.Nm SSL_do_handshake +.Nd perform a TLS/SSL handshake +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_do_handshake "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_do_handshake +will wait for a SSL/TLS handshake to take place. +If the connection is in client mode, the handshake will be started. +The handshake routines may have to be explicitly set in advance using either +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 . +.Sh NOTES +The behaviour of +.Fn SSL_do_handshake +depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_do_handshake +will only return once the handshake has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_do_handshake +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_do_handshake +to continue the handshake. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_do_handshake +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_do_handshake . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The TLS/SSL handshake was not successful but was shut down controlled and +by the specifications of the TLS/SSL protocol. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.It 1 +The TLS/SSL handshake was successfully completed, +and a TLS/SSL connection has been established. +.It <0 +The TLS/SSL handshake was not successful because either a fatal error occurred +at the protocol level or a connection failure occurred. +The shutdown was not clean. +It can also occur if action is needed to continue the operation for +non-blocking +.Vt BIO Ns s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_connect_state 3 diff --git a/src/lib/libssl/man/SSL_free.3 b/src/lib/libssl/man/SSL_free.3 new file mode 100644 index 0000000000..fe1e6b8aa5 --- /dev/null +++ b/src/lib/libssl/man/SSL_free.3 @@ -0,0 +1,67 @@ +.\" +.\" $OpenBSD: SSL_free.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_FREE 3 +.Os +.Sh NAME +.Nm SSL_free +.Nd free an allocated SSL structure +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_free "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_free +decrements the reference count of +.Fa ssl , +and removes the +.Vt SSL +structure pointed to by +.Fa ssl +and frees up the allocated memory if the reference count has reached 0. +If +.Fa ssl +is a +.Dv NULL +pointer, no action occurs. +.Sh NOTES +.Fn SSL_free +also calls the +.Xr free 3 Ns +ing procedures for indirectly affected items, if applicable: the buffering +.Vt BIO , +the read and write +.Vt BIOs , +cipher lists specially created for this +.Fa ssl , +the +.Sy SSL_SESSION . +Do not explicitly free these indirectly freed up items before or after calling +.Fn SSL_free , +as trying to free things twice may lead to program failure. +.Pp +The +.Fa ssl +session has reference counts from two users: the +.Vt SSL +object, for which the reference count is removed by +.Fn SSL_free +and the internal session cache. +If the session is considered bad, because +.Xr SSL_shutdown 3 +was not called for the connection and +.Xr SSL_set_shutdown 3 +was not used to set the +.Vt SSL_SENT_SHUTDOWN +state, the session will also be removed from the session cache as required by +RFC2246. +.Sh RETURN VALUES +.Fn SSL_free +does not provide diagnostic information. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_new 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_get_SSL_CTX.3 b/src/lib/libssl/man/SSL_get_SSL_CTX.3 new file mode 100644 index 0000000000..ee211f8fdc --- /dev/null +++ b/src/lib/libssl/man/SSL_get_SSL_CTX.3 @@ -0,0 +1,28 @@ +.\" +.\" $OpenBSD: SSL_get_SSL_CTX.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_SSL_CTX 3 +.Os +.Sh NAME +.Nm SSL_get_SSL_CTX +.Nd get the SSL_CTX from which an SSL is created +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft SSL_CTX * +.Fn SSL_get_SSL_CTX "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_SSL_CTX +returns a pointer to the +.Vt SSL_CTX +object from which +.Fa ssl +was created with +.Xr SSL_new 3 . +.Sh RETURN VALUES +The pointer to the +.Vt SSL_CTX +object is returned. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_new 3 diff --git a/src/lib/libssl/man/SSL_get_ciphers.3 b/src/lib/libssl/man/SSL_get_ciphers.3 new file mode 100644 index 0000000000..4469b73f92 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_ciphers.3 @@ -0,0 +1,68 @@ +.\" +.\" $OpenBSD: SSL_get_ciphers.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_CIPHERS 3 +.Os +.Sh NAME +.Nm SSL_get_ciphers , +.Nm SSL_get_cipher_list +.Nd get list of available SSL_CIPHERs +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft STACK_OF(SSL_CIPHER) * +.Fn SSL_get_ciphers "const SSL *ssl" +.Ft const char * +.Fn SSL_get_cipher_list "const SSL *ssl" "int priority" +.Sh DESCRIPTION +.Fn SSL_get_ciphers +returns the stack of available +.Vt SSL_CIPHER Ns s +for +.Fa ssl , +sorted by preference. +If +.Fa ssl +is +.Dv NULL +or no ciphers are available, +.Dv NULL +is returned. +.Pp +.Fn SSL_get_cipher_list +returns a pointer to the name of the +.Vt SSL_CIPHER +listed for +.Fa ssl +with +.Fa priority . +If +.Fa ssl +is +.Dv NULL , +no ciphers are available, or there are fewer ciphers than +.Fa priority +available, +.Dv NULL +is returned. +.Sh NOTES +The details of the ciphers obtained by +.Fn SSL_get_ciphers +can be obtained using the +.Xr SSL_CIPHER_get_name 3 +family of functions. +.Pp +Call +.Fn SSL_get_cipher_list +with +.Fa priority +starting from 0 to obtain the sorted list of available ciphers, until +.Dv NULL +is returned. +.Sh RETURN VALUES +See +.Sx DESCRIPTION . +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CIPHER_get_name 3 , +.Xr SSL_CTX_set_cipher_list 3 diff --git a/src/lib/libssl/man/SSL_get_client_CA_list.3 b/src/lib/libssl/man/SSL_get_client_CA_list.3 new file mode 100644 index 0000000000..6675bc3793 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_client_CA_list.3 @@ -0,0 +1,61 @@ +.\" +.\" $OpenBSD: SSL_get_client_CA_list.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_CLIENT_CA_LIST 3 +.Os +.Sh NAME +.Nm SSL_get_client_CA_list , +.Nm SSL_CTX_get_client_CA_list +.Nd get list of client CAs +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft STACK_OF(X509_NAME) * +.Fn SSL_get_client_CA_list "const SSL *s" +.Ft STACK_OF(X509_NAME) * +.Fn SSL_CTX_get_client_CA_list "const SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_CTX_get_client_CA_list +returns the list of client CAs explicitly set for +.Fa ctx +using +.Xr SSL_CTX_set_client_CA_list 3 . +.Pp +.Fn SSL_get_client_CA_list +returns the list of client CAs explicitly set for +.Fa ssl +using +.Fn SSL_set_client_CA_list +or +.Fa ssl Ns 's +.Vt SSL_CTX +object with +.Xr SSL_CTX_set_client_CA_list 3 , +when in server mode. +In client mode, +.Fn SSL_get_client_CA_list +returns the list of client CAs sent from the server, if any. +.Sh RETURN VALUES +.Fn SSL_CTX_set_client_CA_list +and +.Fn SSL_set_client_CA_list +do not return diagnostic information. +.Pp +.Fn SSL_CTX_add_client_CA +and +.Fn SSL_add_client_CA +have the following return values: +.Bl -tag -width Ds +.It Dv STACK_OF Ns Po Vt X509_NAMES Pc +List of CA names explicitly set (for +.Fa ctx +or in server mode) or sent by the server (client mode). +.It Dv NULL +No client CA list was explicitly set (for +.Fa ctx +or in server mode) or the server did not send a list of CAs (client mode). +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_set_client_cert_cb 3 diff --git a/src/lib/libssl/man/SSL_get_current_cipher.3 b/src/lib/libssl/man/SSL_get_current_cipher.3 new file mode 100644 index 0000000000..de46f3d21c --- /dev/null +++ b/src/lib/libssl/man/SSL_get_current_cipher.3 @@ -0,0 +1,52 @@ +.\" +.\" $OpenBSD: SSL_get_current_cipher.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_CURRENT_CIPHER 3 +.Os +.Sh NAME +.Nm SSL_get_current_cipher , +.Nm SSL_get_cipher , +.Nm SSL_get_cipher_name , +.Nm SSL_get_cipher_bits , +.Nm SSL_get_cipher_version +.Nd get SSL_CIPHER of a connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft SSL_CIPHER * +.Fn SSL_get_current_cipher "const SSL *ssl" +.Fd #define SSL_get_cipher(s) SSL_CIPHER_get_name(SSL_get_current_cipher(s)) +.Fd #define SSL_get_cipher_name(s) \ +SSL_CIPHER_get_name(SSL_get_current_cipher(s)) +.Fd #define SSL_get_cipher_bits(s,np) \ +SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) +.Fd #define SSL_get_cipher_version(s) \ +SSL_CIPHER_get_version(SSL_get_current_cipher(s)) +.Sh DESCRIPTION +.Fn SSL_get_current_cipher +returns a pointer to an +.Vt SSL_CIPHER +object containing the description of the actually used cipher of a connection +established with the +.Fa ssl +object. +.Pp +.Fn SSL_get_cipher +and +.Fn SSL_get_cipher_name +are identical macros to obtain the name of the currently used cipher. +.Fn SSL_get_cipher_bits +is a macro to obtain the number of secret/algorithm bits used and +.Fn SSL_get_cipher_version +returns the protocol name. +See +.Xr SSL_CIPHER_get_name 3 +for more details. +.Sh RETURN VALUES +.Fn SSL_get_current_cipher +returns the cipher actually used or +.Dv NULL , +when no session has been established. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CIPHER_get_name 3 diff --git a/src/lib/libssl/man/SSL_get_default_timeout.3 b/src/lib/libssl/man/SSL_get_default_timeout.3 new file mode 100644 index 0000000000..a14d8041e2 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_default_timeout.3 @@ -0,0 +1,36 @@ +.\" +.\" $OpenBSD: SSL_get_default_timeout.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_DEFAULT_TIMEOUT 3 +.Os +.Sh NAME +.Nm SSL_get_default_timeout +.Nd get default session timeout value +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_get_default_timeout "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_default_timeout +returns the default timeout value assigned to +.Vt SSL_SESSION +objects negotiated for the protocol valid for +.Fa ssl . +.Sh NOTES +Whenever a new session is negotiated, it is assigned a timeout value, +after which it will not be accepted for session reuse. +If the timeout value was not explicitly set using +.Xr SSL_CTX_set_timeout 3 , +the hardcoded default timeout for the protocol will be used. +.Pp +.Fn SSL_get_default_timeout +return this hardcoded value, which is 300 seconds for all currently supported +protocols (SSLv2, SSLv3, and TLSv1). +.Sh RETURN VALUES +See description. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_SESSION_get_time 3 diff --git a/src/lib/libssl/man/SSL_get_error.3 b/src/lib/libssl/man/SSL_get_error.3 new file mode 100644 index 0000000000..b3e7c9e491 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_error.3 @@ -0,0 +1,169 @@ +.\" +.\" $OpenBSD: SSL_get_error.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_ERROR 3 +.Os +.Sh NAME +.Nm SSL_get_error +.Nd obtain result code for TLS/SSL I/O operation +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_get_error "const SSL *ssl" "int ret" +.Sh DESCRIPTION +.Fn SSL_get_error +returns a result code (suitable for the C +.Dq switch +statement) for a preceding call to +.Xr SSL_connect 3 , +.Xr SSL_accept 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_read 3 , +.Xr SSL_peek 3 , +or +.Xr SSL_write 3 +on +.Fa ssl . +The value returned by that TLS/SSL I/O function must be passed to +.Fn SSL_get_error +in parameter +.Fa ret . +.Pp +In addition to +.Fa ssl +and +.Fa ret , +.Fn SSL_get_error +inspects the current thread's OpenSSL error queue. +Thus, +.Fn SSL_get_error +must be used in the same thread that performed the TLS/SSL I/O operation, +and no other OpenSSL function calls should appear in between. +The current thread's error queue must be empty before the TLS/SSL I/O operation +is attempted, or +.Fn SSL_get_error +will not work reliably. +.Sh RETURN VALUES +The following return values can currently occur: +.Bl -tag -width Ds +.It Dv SSL_ERROR_NONE +The TLS/SSL I/O operation completed. +This result code is returned if and only if +.Fa ret +< 0. +.It Dv SSL_ERROR_ZERO_RETURN +The TLS/SSL connection has been closed. +If the protocol version is SSL 3.0 or TLS 1.0, this result code is returned +only if a closure alert has occurred in the protocol, i.e., if the connection +has been closed cleanly. +Note that in this case +.Dv SSL_ERROR_ZERO_RETURN +does not necessarily indicate that the underlying transport has been closed. +.It Dv SSL_ERROR_WANT_READ , Dv SSL_ERROR_WANT_WRITE +The operation did not complete; +the same TLS/SSL I/O function should be called again later. +If, by then, the underlying +.Vt BIO +has data available for reading (if the result code is +.Dv SSL_ERROR_WANT_READ ) +or allows writing data +.Pq Dv SSL_ERROR_WANT_WRITE , +then some TLS/SSL protocol progress will take place, +i.e., at least part of a TLS/SSL record will be read or written. +Note that the retry may again lead to a +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +condition. +There is no fixed upper limit for the number of iterations that may be +necessary until progress becomes visible at application protocol level. +.Pp +For socket +.Fa BIO Ns +s (e.g., when +.Fn SSL_set_fd +was used), +.Xr select 2 +or +.Xr poll 2 +on the underlying socket can be used to find out when the TLS/SSL I/O function +should be retried. +.Pp +Caveat: Any TLS/SSL I/O function can lead to either of +.Dv SSL_ERROR_WANT_READ +and +.Dv SSL_ERROR_WANT_WRITE . +In particular, +.Xr SSL_read 3 +or +.Xr SSL_peek 3 +may want to write data and +.Xr SSL_write 3 +may want +to read data. +This is mainly because TLS/SSL handshakes may occur at any time during the +protocol (initiated by either the client or the server); +.Xr SSL_read 3 , +.Xr SSL_peek 3 , +and +.Xr SSL_write 3 +will handle any pending handshakes. +.It Dv SSL_ERROR_WANT_CONNECT , Dv SSL_ERROR_WANT_ACCEPT +The operation did not complete; the same TLS/SSL I/O function should be +called again later. +The underlying BIO was not connected yet to the peer and the call would block +in +.Xr connect 2 Ns / Ns +.Xr accept 2 . +The SSL function should be +called again when the connection is established. +These messages can only appear with a +.Xr BIO_s_connect 3 +or +.Xr BIO_s_accept 3 +.Vt BIO , +respectively. +In order to find out when the connection has been successfully established, +on many platforms +.Xr select 2 +or +.Xr poll 2 +for writing on the socket file descriptor can be used. +.It Dv SSL_ERROR_WANT_X509_LOOKUP +The operation did not complete because an application callback set by +.Xr SSL_CTX_set_client_cert_cb 3 +has asked to be called again. +The TLS/SSL I/O function should be called again later. +Details depend on the application. +.It Dv SSL_ERROR_SYSCALL +Some I/O error occurred. +The OpenSSL error queue may contain more information on the error. +If the error queue is empty (i.e., +.Fn ERR_get_error +returns 0), +.Fa ret +can be used to find out more about the error: +If +.Fa ret +== 0, an +.Dv EOF +was observed that violates the protocol. +If +.Fa ret +== \(mi1, the underlying +.Vt BIO +reported an +I/O error (for socket I/O on Unix systems, consult +.Dv errno +for details). +.It Dv SSL_ERROR_SSL +A failure in the SSL library occurred, usually a protocol error. +The OpenSSL error queue contains more information on the error. +.El +.Sh SEE ALSO +.Xr err 3 , +.Xr ssl 3 +.Sh HISTORY +.Fn SSL_get_error +was added in SSLeay 0.8. diff --git a/src/lib/libssl/man/SSL_get_ex_data_X509_STORE_CTX_idx.3 b/src/lib/libssl/man/SSL_get_ex_data_X509_STORE_CTX_idx.3 new file mode 100644 index 0000000000..ab9b7ae376 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_ex_data_X509_STORE_CTX_idx.3 @@ -0,0 +1,65 @@ +.\" +.\" $OpenBSD: SSL_get_ex_data_X509_STORE_CTX_idx.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_EX_DATA_X509_STORE_CTX_IDX 3 +.Os +.Sh NAME +.Nm SSL_get_ex_data_X509_STORE_CTX_idx +.Nd get ex_data index to access SSL structure from X509_STORE_CTX +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_get_ex_data_X509_STORE_CTX_idx void +.Sh DESCRIPTION +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +returns the index number under which the pointer to the +.Vt SSL +object is stored into the +.Vt X509_STORE_CTX +object. +.Sh NOTES +Whenever a +.Vt X509_STORE_CTX +object is created for the verification of the peer's certificate during a +handshake, a pointer to the +.Vt SSL +object is stored into the +.Vt X509_STORE_CTX +object to identify the connection affected. +To retrieve this pointer the +.Xr X509_STORE_CTX_get_ex_data 3 +function can be used with the correct index. +This index is globally the same for all +.Vt X509_STORE_CTX +objects and can be retrieved using +.Fn SSL_get_ex_data_X509_STORE_CTX_idx . +The index value is set when +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +is first called either by the application program directly or indirectly during +other SSL setup functions or during the handshake. +.Pp +The value depends on other index values defined for +.Vt X509_STORE_CTX +objects before the SSL index is created. +.Sh RETURN VALUES +.Bl -tag -width Ds +.It \(>=0 +The index value to access the pointer. +.It <0 +An error occurred, check the error stack for a detailed error message. +.El +.Sh EXAMPLES +The index returned from +.Fn SSL_get_ex_data_X509_STORE_CTX_idx +provides access to +.Vt SSL +object for the connection during the +.Fn verify_callback +when checking the peer's certificate. +Please check the example in +.Xr SSL_CTX_set_verify 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 diff --git a/src/lib/libssl/man/SSL_get_ex_new_index.3 b/src/lib/libssl/man/SSL_get_ex_new_index.3 new file mode 100644 index 0000000000..87cb281560 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_ex_new_index.3 @@ -0,0 +1,76 @@ +.\" +.\" $OpenBSD: SSL_get_ex_new_index.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm SSL_get_ex_new_index , +.Nm SSL_set_ex_data , +.Nm SSL_get_ex_data +.Nd internal application specific data functions +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fo SSL_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fn SSL_set_ex_data "SSL *ssl" "int idx" "void *arg" +.Ft void * +.Fn SSL_get_ex_data "const SSL *ssl" "int idx" +.Bd -literal +typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); +typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); +typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, + int idx, long argl, void *argp); +.Ed +.Sh DESCRIPTION +Several OpenSSL structures can have application specific data attached to them. +These functions are used internally by OpenSSL to manipulate application +specific data attached to a specific structure. +.Pp +.Fn SSL_get_ex_new_index +is used to register a new index for application specific data. +.Pp +.Fn SSL_set_ex_data +is used to store application data at +.Fa arg +for +.Fa idx +into the +.Fa ssl +object. +.Pp +.Fn SSL_get_ex_data +is used to retrieve the information for +.Fa idx +from +.Fa ssl . +.Pp +A detailed description for the +.Fn *_get_ex_new_index +functionality can be found in +.Xr RSA_get_ex_new_index 3 . +The +.Fn *_get_ex_data +and +.Fn *_set_ex_data +functionality is described in +.Xr CRYPTO_set_ex_data 3 . +.Sh EXAMPLES +An example of how to use the functionality is included in the example +.Fn verify_callback +in +.Xr SSL_CTX_set_verify 3 . +.Sh SEE ALSO +.Xr CRYPTO_set_ex_data 3 , +.Xr RSA_get_ex_new_index 3 , +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 diff --git a/src/lib/libssl/man/SSL_get_fd.3 b/src/lib/libssl/man/SSL_get_fd.3 new file mode 100644 index 0000000000..e21e75f978 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_fd.3 @@ -0,0 +1,46 @@ +.\" +.\" $OpenBSD: SSL_get_fd.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_FD 3 +.Os +.Sh NAME +.Nm SSL_get_fd , +.Nm SSL_get_rfd , +.Nm SSL_get_wfd +.Nd get file descriptor linked to an SSL object +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_get_fd "const SSL *ssl" +.Ft int +.Fn SSL_get_rfd "const SSL *ssl" +.Ft int +.Fn SSL_get_wfd "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_fd +returns the file descriptor which is linked to +.Fa ssl . +.Fn SSL_get_rfd +and +.Fn SSL_get_wfd +return the file descriptors for the read or the write channel, +which can be different. +If the read and the write channel are different, +.Fn SSL_get_fd +will return the file descriptor of the read channel. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It \(mi1 +The operation failed, because the underlying +.Vt BIO +is not of the correct type (suitable for file descriptors). +.It \(>=0 +The file descriptor linked to +.Fa ssl . +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_set_fd 3 diff --git a/src/lib/libssl/man/SSL_get_peer_cert_chain.3 b/src/lib/libssl/man/SSL_get_peer_cert_chain.3 new file mode 100644 index 0000000000..bf5d04f3cf --- /dev/null +++ b/src/lib/libssl/man/SSL_get_peer_cert_chain.3 @@ -0,0 +1,47 @@ +.\" +.\" $OpenBSD: SSL_get_peer_cert_chain.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_PEER_CERT_CHAIN 3 +.Os +.Sh NAME +.Nm SSL_get_peer_cert_chain +.Nd get the X509 certificate chain of the peer +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft STACK_OF(X509) * +.Fn SSL_get_peer_cert_chain "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_peer_cert_chain +returns a pointer to +.Dv STACK_OF Ns Po Vt X509 Pc +certificates forming the certificate chain of the peer. +If called on the client side, the stack also contains the peer's certificate; +if called on the server side, the peer's certificate must be obtained +separately using +.Xr SSL_get_peer_certificate 3 . +If the peer did not present a certificate, +.Dv NULL +is returned. +.Sh NOTES +The peer certificate chain is not necessarily available after reusing a +session, in which case a +.Dv NULL +pointer is returned. +.Pp +The reference count of the +.Dv STACK_OF Ns Po Vt X509 Pc +object is not incremented. +If the corresponding session is freed, the pointer must not be used any longer. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +No certificate was presented by the peer or no connection was established or +the certificate chain is no longer available when a session is reused. +.It Pointer to a Dv STACK_OF Ns Po X509 Pc +The return value points to the certificate chain presented by the peer. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_get_peer_certificate 3 diff --git a/src/lib/libssl/man/SSL_get_peer_certificate.3 b/src/lib/libssl/man/SSL_get_peer_certificate.3 new file mode 100644 index 0000000000..f1b34dfa08 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_peer_certificate.3 @@ -0,0 +1,53 @@ +.\" +.\" $OpenBSD: SSL_get_peer_certificate.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_PEER_CERTIFICATE 3 +.Os +.Sh NAME +.Nm SSL_get_peer_certificate +.Nd get the X509 certificate of the peer +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft X509 * +.Fn SSL_get_peer_certificate "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_peer_certificate +returns a pointer to the X509 certificate the peer presented. +If the peer did not present a certificate, +.Dv NULL +is returned. +.Sh NOTES +Due to the protocol definition, a TLS/SSL server will always send a +certificate, if present. +A client will only send a certificate when explicitly requested to do so by the +server (see +.Xr SSL_CTX_set_verify 3 ) . +If an anonymous cipher is used, no certificates are sent. +.Pp +That a certificate is returned does not indicate information about the +verification state. +Use +.Xr SSL_get_verify_result 3 +to check the verification state. +.Pp +The reference count of the +.Vt X509 +object is incremented by one, so that it will not be destroyed when the session +containing the peer certificate is freed. +The +.Vt X509 +object must be explicitly freed using +.Xr X509_free 3 . +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +No certificate was presented by the peer or no connection was established. +.It Pointer to an X509 certificate +The return value points to the certificate presented by the peer. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_get_verify_result 3 diff --git a/src/lib/libssl/man/SSL_get_psk_identity.3 b/src/lib/libssl/man/SSL_get_psk_identity.3 new file mode 100644 index 0000000000..a2f91ee1c7 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_psk_identity.3 @@ -0,0 +1,44 @@ +.\" +.\" $OpenBSD: SSL_get_psk_identity.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_PSK_IDENTITY 3 +.Os +.Sh NAME +.Nm SSL_get_psk_identity , +.Nm SSL_get_psk_identity_hint +.Nd get PSK client identity and hint +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft const char * +.Fn SSL_get_psk_identity_hint "const SSL *ssl" +.Ft const char * +.Fn SSL_get_psk_identity "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_psk_identity_hint +is used to retrieve the PSK identity hint used during the connection setup +related to +.Vt SSL +object +.Fa ssl . +Similarly, +.Fn SSL_get_psk_identity +is used to retrieve the PSK identity used during the connection setup. +.Sh RETURN VALUES +If +.Pf non- Dv NULL , +.Fn SSL_get_psk_identity_hint +returns the PSK identity hint and +.Fn SSL_get_psk_identity +returns the PSK identity. +Both are +.Dv NULL Ns -terminated. +.Fn SSL_get_psk_identity_hint +may return +.Dv NULL +if no PSK identity hint was used during the connection setup. +.Pp +Note that the return value is valid only during the lifetime of the +.Vt SSL +object +.Fa ssl . diff --git a/src/lib/libssl/man/SSL_get_rbio.3 b/src/lib/libssl/man/SSL_get_rbio.3 new file mode 100644 index 0000000000..adef98ec6a --- /dev/null +++ b/src/lib/libssl/man/SSL_get_rbio.3 @@ -0,0 +1,45 @@ +.\" +.\" $OpenBSD: SSL_get_rbio.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_RBIO 3 +.Os +.Sh NAME +.Nm SSL_get_rbio , +.Nm SSL_get_wbio +.Nd get BIO linked to an SSL object +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft BIO * +.Fn SSL_get_rbio "SSL *ssl" +.Ft BIO * +.Fn SSL_get_wbio "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_rbio +and +.Fn SSL_get_wbio +return pointers to the +.Vt BIO Ns s +for the read or the write channel, which can be different. +The reference count of the +.Vt BIO +is not incremented. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +No +.Vt BIO +was connected to the +.Vt SSL +object. +.It Any other pointer +The +.Vt BIO +linked to +.Fa ssl . +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_set_bio 3 diff --git a/src/lib/libssl/man/SSL_get_session.3 b/src/lib/libssl/man/SSL_get_session.3 new file mode 100644 index 0000000000..03e47c59c2 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_session.3 @@ -0,0 +1,97 @@ +.\" +.\" $OpenBSD: SSL_get_session.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_SESSION 3 +.Os +.Sh NAME +.Nm SSL_get_session , +.Nm SSL_get0_session , +.Nm SSL_get1_session +.Nd retrieve TLS/SSL session data +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft SSL_SESSION * +.Fn SSL_get_session "const SSL *ssl" +.Ft SSL_SESSION * +.Fn SSL_get0_session "const SSL *ssl" +.Ft SSL_SESSION * +.Fn SSL_get1_session "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_session +returns a pointer to the +.Vt SSL_SESSION +actually used in +.Fa ssl . +The reference count of the +.Vt SSL_SESSION +is not incremented, so that the pointer can become invalid by other operations. +.Pp +.Fn SSL_get0_session +is the same as +.Fn SSL_get_session . +.Pp +.Fn SSL_get1_session +is the same as +.Fn SSL_get_session , +but the reference count of the +.Vt SSL_SESSION +is incremented by one. +.Sh NOTES +The +Fa ssl +session contains all information required to re-establish the connection +without a new handshake. +.Pp +.Fn SSL_get0_session +returns a pointer to the actual session. +As the reference counter is not incremented, +the pointer is only valid while the connection is in use. +If +.Xr SSL_clear 3 +or +.Xr SSL_free 3 +is called, the session may be removed completely (if considered bad), +and the pointer obtained will become invalid. +Even if the session is valid, +it can be removed at any time due to timeout during +.Xr SSL_CTX_flush_sessions 3 . +.Pp +If the data is to be kept, +.Fn SSL_get1_session +will increment the reference count, so that the session will not be implicitly +removed by other operations but stays in memory. +In order to remove the session +.Xr SSL_SESSION_free 3 +must be explicitly called once to decrement the reference count again. +.Pp +.Vt SSL_SESSION +objects keep internal link information about the session cache list when being +inserted into one +.Vt SSL_CTX +object's session cache. +One +.Vt SSL_SESSION +object, regardless of its reference count, must therefore only be used with one +.Vt SSL_CTX +object (and the +.Vt SSL +objects created from this +.Vt SSL_CTX +object). +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +There is no session available in +.Fa ssl . +.It Pointer to an Vt SSL +The return value points to the data of an +.Vt SSL +session. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_free 3 , +.Xr SSL_SESSION_free 3 diff --git a/src/lib/libssl/man/SSL_get_verify_result.3 b/src/lib/libssl/man/SSL_get_verify_result.3 new file mode 100644 index 0000000000..d93feee3be --- /dev/null +++ b/src/lib/libssl/man/SSL_get_verify_result.3 @@ -0,0 +1,49 @@ +.\" +.\" $OpenBSD: SSL_get_verify_result.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_VERIFY_RESULT 3 +.Os +.Sh NAME +.Nm SSL_get_verify_result +.Nd get result of peer certificate verification +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft long +.Fn SSL_get_verify_result "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_verify_result +returns the result of the verification of the X509 certificate presented by the +peer, if any. +.Sh NOTES +.Fn SSL_get_verify_result +can only return one error code while the verification of a certificate can fail +because of many reasons at the same time. +Only the last verification error that occurred during the processing is +available from +.Fn SSL_get_verify_result . +.Pp +The verification result is part of the established session and is restored when +a session is reused. +.Sh RETURN VALUES +The following return values can currently occur: +.Bl -tag -width Ds +.It Dv X509_V_OK +The verification succeeded or no peer certificate was presented. +.It Any other value +Documented in +.Xr openssl 1 . +.El +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_set_verify_result 3 +.Sh BUGS +If no peer certificate was presented, the returned result code is +.Dv X509_V_OK . +This is because no verification error occurred; +however, it does not indicate success. +.Fn SSL_get_verify_result +is only useful in connection with +.Xr SSL_get_peer_certificate 3 . diff --git a/src/lib/libssl/man/SSL_get_version.3 b/src/lib/libssl/man/SSL_get_version.3 new file mode 100644 index 0000000000..ebbee0cb15 --- /dev/null +++ b/src/lib/libssl/man/SSL_get_version.3 @@ -0,0 +1,35 @@ +.\" +.\" $OpenBSD: SSL_get_version.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_GET_VERSION 3 +.Os +.Sh NAME +.Nm SSL_get_version +.Nd get the protocol version of a connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft const char * +.Fn SSL_get_version "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_get_version +returns the name of the protocol used for the connection +.Fa ssl . +.Sh RETURN VALUES +The following strings can be returned: +.Bl -tag -width Ds +.It Qq SSLv2 +The connection uses the SSLv2 protocol. +.It Qq SSLv3 +The connection uses the SSLv3 protocol. +.It Qq TLSv1 +The connection uses the TLSv1.0 protocol. +.It Qq TLSv1.1 +The connection uses the TLSv1.1 protocol. +.It Qq TLSv1.2 +The connection uses the TLSv1.2 protocol. +.It Qq unknown +This indicates that no version has been set (no connection established). +.El +.Sh SEE ALSO +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_library_init.3 b/src/lib/libssl/man/SSL_library_init.3 new file mode 100644 index 0000000000..ab5326bc4d --- /dev/null +++ b/src/lib/libssl/man/SSL_library_init.3 @@ -0,0 +1,54 @@ +.\" +.\" $OpenBSD: SSL_library_init.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_LIBRARY_INIT 3 +.Os +.Sh NAME +.Nm SSL_library_init , +.Nm OpenSSL_add_ssl_algorithms , +.Nm SSLeay_add_ssl_algorithms +.Nd initialize SSL library by registering algorithms +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_library_init void +.Fd #define OpenSSL_add_ssl_algorithms() SSL_library_init() +.Fd #define SSLeay_add_ssl_algorithms() SSL_library_init() +.Sh DESCRIPTION +.Fn SSL_library_init +registers the available SSL/TLS ciphers and digests. +.Pp +.Fn OpenSSL_add_ssl_algorithms +and +.Fn SSLeay_add_ssl_algorithms +are synonyms for +.Fn SSL_library_init . +.Sh NOTES +.Fn SSL_library_init +must be called before any other action takes place. +.Fn SSL_library_init +is not reentrant. +.Sh WARNING +.Fn SSL_library_init +adds ciphers and digests used directly and indirectly by SSL/TLS. +.Sh RETURN VALUES +.Fn SSL_library_init +always returns 1, so it is safe to discard the return value. +.Sh EXAMPLES +A typical TLS/SSL application will start with the library initialization, and +provide readable error messages. +.Bd -literal +SSL_load_error_strings(); /* readable error messages */ +SSL_library_init(); /* initialize library */ +.Ed +.Sh NOTES +OpenSSL 0.9.8o and 1.0.0a and later added SHA2 algorithms to +.Fn SSL_library_init . +Applications which need to use SHA2 in earlier versions of OpenSSL should call +.Fn OpenSSL_add_all_algorithms +as well. +.Sh SEE ALSO +.Xr RAND_add 3 , +.Xr ssl 3 , +.Xr SSL_load_error_strings 3 diff --git a/src/lib/libssl/man/SSL_load_client_CA_file.3 b/src/lib/libssl/man/SSL_load_client_CA_file.3 new file mode 100644 index 0000000000..21d8054fd4 --- /dev/null +++ b/src/lib/libssl/man/SSL_load_client_CA_file.3 @@ -0,0 +1,53 @@ +.\" +.\" $OpenBSD: SSL_load_client_CA_file.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_LOAD_CLIENT_CA_FILE 3 +.Os +.Sh NAME +.Nm SSL_load_client_CA_file +.Nd load certificate names from file +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft STACK_OF(X509_NAME) * +.Fn SSL_load_client_CA_file "const char *file" +.Sh DESCRIPTION +.Fn SSL_load_client_CA_file +reads certificates from +.Fa file +and returns a +.Dv STACK_OF Ns +.Pq Vt X509_NAME +with the subject names found. +.Sh NOTES +.Fn SSL_load_client_CA_file +reads a file of PEM formatted certificates and extracts the +.Vt X509_NAME Ns s +of the certificates found. +While the name suggests the specific usage as support function for +.Xr SSL_CTX_set_client_CA_list 3 , +it is not limited to CA certificates. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +The operation failed, check out the error stack for the reason. +.It Pointer to Dv STACK_OF Ns Po Vt X509_NAME Pc +Pointer to the subject names of the successfully read certificates. +.El +.Sh EXAMPLES +Load names of CAs from file and use it as a client CA list: +.Bd -literal +SSL_CTX *ctx; +STACK_OF(X509_NAME) *cert_names; +\&... +cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem"); +if (cert_names != NULL) + SSL_CTX_set_client_CA_list(ctx, cert_names); +else + error_handling(); +\&... +.Ed +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_client_CA_list 3 diff --git a/src/lib/libssl/man/SSL_new.3 b/src/lib/libssl/man/SSL_new.3 new file mode 100644 index 0000000000..14883f46ad --- /dev/null +++ b/src/lib/libssl/man/SSL_new.3 @@ -0,0 +1,41 @@ +.\" +.\" $OpenBSD: SSL_new.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_NEW 3 +.Os +.Sh NAME +.Nm SSL_new +.Nd create a new SSL structure for a connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft SSL * +.Fn SSL_new "SSL_CTX *ctx" +.Sh DESCRIPTION +.Fn SSL_new +creates a new +.Vt SSL +structure which is needed to hold the data for a TLS/SSL connection. +The new structure inherits the settings of the underlying context +.Fa ctx : +connection method (SSLv2/v3/TLSv1), options, verification settings, +timeout settings. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It Dv NULL +The creation of a new +.Vt SSL +structure failed. +Check the error stack to find out the reason. +.It Pointer to an Vt SSL No structure +The return value points to an allocated +.Vt SSL +structure. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_free 3 , +.Xr SSL_get_SSL_CTX 3 diff --git a/src/lib/libssl/man/SSL_pending.3 b/src/lib/libssl/man/SSL_pending.3 new file mode 100644 index 0000000000..dadeec4b92 --- /dev/null +++ b/src/lib/libssl/man/SSL_pending.3 @@ -0,0 +1,44 @@ +.\" +.\" $OpenBSD: SSL_pending.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_PENDING 3 +.Os +.Sh NAME +.Nm SSL_pending +.Nd obtain number of readable bytes buffered in an SSL object +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_pending "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_pending +returns the number of bytes which are available inside +.Fa ssl +for immediate read. +.Sh NOTES +Data are received in blocks from the peer. +Therefore data can be buffered inside +.Fa ssl +and are ready for immediate retrieval with +.Xr SSL_read 3 . +.Sh RETURN VALUES +The number of bytes pending is returned. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_read 3 +.Sh BUGS +.Fn SSL_pending +takes into account only bytes from the TLS/SSL record that is currently being +processed (if any). +If the +.Vt SSL +object's +.Em read_ahead +flag is set, additional protocol bytes may have been read containing more +TLS/SSL records; these are ignored by +.Fn SSL_pending . +.Pp +Up to OpenSSL 0.9.6, +.Fn SSL_pending +does not check if the record type of pending data is application data. diff --git a/src/lib/libssl/man/SSL_read.3 b/src/lib/libssl/man/SSL_read.3 new file mode 100644 index 0000000000..662aed4daa --- /dev/null +++ b/src/lib/libssl/man/SSL_read.3 @@ -0,0 +1,193 @@ +.\" +.\" $OpenBSD: SSL_read.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_READ 3 +.Os +.Sh NAME +.Nm SSL_read +.Nd read bytes from a TLS/SSL connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_read "SSL *ssl" "void *buf" "int num" +.Sh DESCRIPTION +.Fn SSL_read +tries to read +.Fa num +bytes from the specified +.Fa ssl +into the buffer +.Fa buf . +.Sh NOTES +If necessary, +.Fn SSL_read +will negotiate a TLS/SSL session, if not already explicitly performed by +.Xr SSL_connect 3 +or +.Xr SSL_accept 3 . +If the peer requests a re-negotiation, +it will be performed transparently during the +.Fn SSL_read +operation. +The behaviour of +.Fn SSL_read +depends on the underlying +.Vt BIO . +.Pp +For the transparent negotiation to succeed, the +.Fa ssl +must have been initialized to client or server mode. +This is being done by calling +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 +before the first call to +.Fn SSL_read +or +.Xr SSL_write 3 . +.Pp +.Fn SSL_read +works based on the SSL/TLS records. +The data are received in records (with a maximum record size of 16kB for +SSLv3/TLSv1). +Only after a record has been completely received can it be processed +(decrypted and checked for integrity). +Therefore data not retrieved at the last call of +.Fn SSL_read +can still be buffered inside the SSL layer and will be retrieved on the next +call to +.Fn SSL_read . +If +.Fa num +is higher than the number of bytes buffered, +.Fn SSL_read +will return with the bytes buffered. +If no more bytes are in the buffer, +.Fn SSL_read +will trigger the processing of the next record. +Only when the record has been received and processed completely will +.Fn SSL_read +return reporting success. +At most the contents of the record will be returned. +As the size of an SSL/TLS record may exceed the maximum packet size of the +underlying transport (e.g., TCP), it may be necessary to read several packets +from the transport layer before the record is complete and +.Fn SSL_read +can succeed. +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_read +will only return once the read operation has been finished or an error +has occurred, except when a renegotiation take place, in which case a +.Dv SSL_ERROR_WANT_READ +may occur. +This behavior can be controlled with the +.Dv SSL_MODE_AUTO_RETRY +flag of the +.Xr SSL_CTX_set_mode 3 +call. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_read +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_read +to continue the operation. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_read +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +As at any time a re-negotiation is possible, a call to +.Fn SSL_read +can also cause write operations! +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_read . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Pp +.Xr SSL_pending 3 +can be used to find out whether there are buffered bytes available for +immediate retrieval. +In this case +.Fn SSL_read +can be called without blocking or actually receiving new data from the +underlying socket. +.Sh WARNING +When an +.Fn SSL_read +operation has to be repeated because of +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE , +it must be repeated with the same arguments. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It >0 +The read operation was successful; the return value is the number of bytes +actually read from the TLS/SSL connection. +.It 0 +The read operation was not successful. +The reason may either be a clean shutdown due to a +.Dq close notify +alert sent by the peer (in which case the +.Dv SSL_RECEIVED_SHUTDOWN +flag in the ssl shutdown state is set (see +.Xr SSL_shutdown 3 +and +.Xr SSL_set_shutdown 3 ) . +It is also possible that the peer simply shut down the underlying transport and +the shutdown is incomplete. +Call +.Fn SSL_get_error +with the return value to find out whether an error occurred or the connection +was shut down cleanly +.Pq Dv SSL_ERROR_ZERO_RETURN . +.Pp +SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only +be detected whether the underlying connection was closed. +It cannot be checked whether the closure was initiated by the peer or by +something else. +.It <0 +The read operation was not successful, because either an error occurred or +action must be taken by the calling process. +Call +.Fn SSL_get_error +with the return value to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_get_error 3 , +.Xr SSL_pending 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 , +.Xr SSL_write 3 diff --git a/src/lib/libssl/man/SSL_rstate_string.3 b/src/lib/libssl/man/SSL_rstate_string.3 new file mode 100644 index 0000000000..4b29fed86e --- /dev/null +++ b/src/lib/libssl/man/SSL_rstate_string.3 @@ -0,0 +1,55 @@ +.\" +.\" $OpenBSD: SSL_rstate_string.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_RSTATE_STRING 3 +.Os +.Sh NAME +.Nm SSL_rstate_string , +.Nm SSL_rstate_string_long +.Nd get textual description of state of an SSL object during read operation +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft const char * +.Fn SSL_rstate_string "SSL *ssl" +.Ft const char * +.Fn SSL_rstate_string_long "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_rstate_string +returns a 2-letter string indicating the current read state of the +.Vt SSL +object +.Fa ssl . +.Pp +.Fn SSL_rstate_string_long +returns a string indicating the current read state of the +.Vt SSL +object +.Fa ssl . +.Sh NOTES +When performing a read operation, the SSL/TLS engine must parse the record, +consisting of header and body. +When working in a blocking environment, +.Fn SSL_rstate_string[_long] +should always return +.Qo RD Qc Ns / Ns Qo read done Qc . +.Pp +This function should only seldom be needed in applications. +.Sh RETURN VALUES +.Fn SSL_rstate_string +and +.Fn SSL_rstate_string_long +can return the following values: +.Bl -tag -width Ds +.It Qo RH Qc Ns / Ns Qo read header Qc +The header of the record is being evaluated. +.It Qo RB Qc Ns / Ns Qo read body Qc +The body of the record is being evaluated. +.It Qo RD Qc Ns / Ns Qo read done Qc +The record has been completely processed. +.It Qo unknown Qc Ns / Ns Qo unknown Qc +The read state is unknown. +This should never happen. +.El +.Sh SEE ALSO +.Xr ssl 3 diff --git a/src/lib/libssl/man/SSL_session_reused.3 b/src/lib/libssl/man/SSL_session_reused.3 new file mode 100644 index 0000000000..6d592a8d55 --- /dev/null +++ b/src/lib/libssl/man/SSL_session_reused.3 @@ -0,0 +1,32 @@ +.\" +.\" $OpenBSD: SSL_session_reused.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SESSION_REUSED 3 +.Os +.Sh NAME +.Nm SSL_session_reused +.Nd query whether a reused session was negotiated during handshake +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_session_reused "SSL *ssl" +.Sh DESCRIPTION +Query whether a reused session was negotiated during the handshake. +.Sh NOTES +During the negotiation, a client can propose to reuse a session. +The server then looks up the session in its cache. +If both client and server agree on the session, +it will be reused and a flag is set that can be queried by the application. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +A new session was negotiated. +.It 1 +A session was reused. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_set_session 3 diff --git a/src/lib/libssl/man/SSL_set_bio.3 b/src/lib/libssl/man/SSL_set_bio.3 new file mode 100644 index 0000000000..21750fd66c --- /dev/null +++ b/src/lib/libssl/man/SSL_set_bio.3 @@ -0,0 +1,51 @@ +.\" +.\" $OpenBSD: SSL_set_bio.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SET_BIO 3 +.Os +.Sh NAME +.Nm SSL_set_bio +.Nd connect the SSL object with a BIO +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_set_bio "SSL *ssl" "BIO *rbio" "BIO *wbio" +.Sh DESCRIPTION +.Fn SSL_set_bio +connects the +.Vt BIO Ns +s +.Fa rbio +and +.Fa wbio +for the read and write operations of the TLS/SSL (encrypted) side of +.Fa ssl . +.Pp +The SSL engine inherits the behaviour of +.Fa rbio +and +.Fa wbio , +respectively. +If a +.Vt BIO +is non-blocking, the +.Fa ssl +will also have non-blocking behaviour. +.Pp +If there was already a +.Vt BIO +connected to +.Fa ssl , +.Xr BIO_free 3 +will be called (for both the reading and writing side, if different). +.Sh RETURN VALUES +.Fn SSL_set_bio +cannot fail. +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_rbio 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_set_connect_state.3 b/src/lib/libssl/man/SSL_set_connect_state.3 new file mode 100644 index 0000000000..8def2ecde5 --- /dev/null +++ b/src/lib/libssl/man/SSL_set_connect_state.3 @@ -0,0 +1,71 @@ +.\" +.\" $OpenBSD: SSL_set_connect_state.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SET_CONNECT_STATE 3 +.Os +.Sh NAME +.Nm SSL_set_connect_state , +.Nm SSL_set_accept_state +.Nd prepare SSL object to work in client or server mode +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_set_connect_state "SSL *ssl" +.Ft void +.Fn SSL_set_accept_state "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_set_connect_state +sets +.Fa ssl +to work in client mode. +.Pp +.Fn SSL_set_accept_state +sets +.Fa ssl +to work in server mode. +.Sh NOTES +When the +.Vt SSL_CTX +object was created with +.Xr SSL_CTX_new 3 , +it was either assigned a dedicated client method, a dedicated server method, or +a generic method, that can be used for both client and server connections. +(The method might have been changed with +.Xr SSL_CTX_set_ssl_version 3 +or +.Xr SSL_set_ssl_method 3 . ) +.Pp +When beginning a new handshake, the SSL engine must know whether it must call +the connect (client) or accept (server) routines. +Even though it may be clear from the method chosen whether client or server +mode was requested, the handshake routines must be explicitly set. +.Pp +When using the +.Xr SSL_connect 3 +or +.Xr SSL_accept 3 +routines, the correct handshake routines are automatically set. +When performing a transparent negotiation using +.Xr SSL_write 3 +or +.Xr SSL_read 3 , +the handshake routines must be explicitly set in advance using either +.Fn SSL_set_connect_state +or +.Fn SSL_set_accept_state . +.Sh RETURN VALUES +.Fn SSL_set_connect_state +and +.Fn SSL_set_accept_state +do not return diagnostic information. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_ssl_version 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_new 3 , +.Xr SSL_read 3 , +.Xr SSL_write 3 diff --git a/src/lib/libssl/man/SSL_set_fd.3 b/src/lib/libssl/man/SSL_set_fd.3 new file mode 100644 index 0000000000..0e9d272913 --- /dev/null +++ b/src/lib/libssl/man/SSL_set_fd.3 @@ -0,0 +1,73 @@ +.\" +.\" $OpenBSD: SSL_set_fd.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SET_FD 3 +.Os +.Sh NAME +.Nm SSL_set_fd , +.Nm SSL_set_rfd , +.Nm SSL_set_wfd +.Nd connect the SSL object with a file descriptor +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_set_fd "SSL *ssl" "int fd" +.Ft int +.Fn SSL_set_rfd "SSL *ssl" "int fd" +.Ft int +.Fn SSL_set_wfd "SSL *ssl" "int fd" +.Sh DESCRIPTION +.Fn SSL_set_fd +sets the file descriptor +.Fa fd +as the input/output facility for the TLS/SSL (encrypted) side of +.Fa ssl . +.Fa fd +will typically be the socket file descriptor of a network connection. +.Pp +When performing the operation, a socket +.Vt BIO +is automatically created to interface between the +.Fa ssl +and +.Fa fd . +The +.Vt BIO +and hence the SSL engine inherit the behaviour of +.Fa fd . +If +.Fa fd +is non-blocking, the +.Fa ssl +will also have non-blocking behaviour. +.Pp +If there was already a +.Vt BIO +connected to +.Fa ssl , +.Xr BIO_free 3 +will be called (for both the reading and writing side, if different). +.Pp +.Fn SSL_set_rfd +and +.Fn SSL_set_wfd +perform the respective action, but only for the read channel or the write +channel, which can be set independently. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The operation failed. +Check the error stack to find out why. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_get_fd 3 , +.Xr SSL_set_bio 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_set_session.3 b/src/lib/libssl/man/SSL_set_session.3 new file mode 100644 index 0000000000..28f1aa667a --- /dev/null +++ b/src/lib/libssl/man/SSL_set_session.3 @@ -0,0 +1,68 @@ +.\" +.\" $OpenBSD: SSL_set_session.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SET_SESSION 3 +.Os +.Sh NAME +.Nm SSL_set_session +.Nd set a TLS/SSL session to be used during TLS/SSL connect +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_set_session "SSL *ssl" "SSL_SESSION *session" +.Sh DESCRIPTION +.Fn SSL_set_session +sets +.Fa session +to be used when the TLS/SSL connection is to be established. +.Fn SSL_set_session +is only useful for TLS/SSL clients. +When the session is set, the reference count of +.Fa session +is incremented +by 1. +If the session is not reused, the reference count is decremented again during +.Fn SSL_connect . +Whether the session was reused can be queried with the +.Xr SSL_session_reused 3 +call. +.Pp +If there is already a session set inside +.Fa ssl +(because it was set with +.Fn SSL_set_session +before or because the same +.Fa ssl +was already used for a connection), +.Xr SSL_SESSION_free 3 +will be called for that session. +.Sh NOTES +.Vt SSL_SESSION +objects keep internal link information about the session cache list when being +inserted into one +.Vt SSL_CTX +object's session cache. +One +.Vt SSL_SESSION +object, regardless of its reference count, must therefore only be used with one +.Vt SSL_CTX +object (and the +.Vt SSL +objects created from this +.Vt SSL_CTX +object). +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The operation failed; check the error stack to find out the reason. +.It 1 +The operation succeeded. +.El +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_get_session 3 , +.Xr SSL_SESSION_free 3 , +.Xr SSL_session_reused 3 diff --git a/src/lib/libssl/man/SSL_set_shutdown.3 b/src/lib/libssl/man/SSL_set_shutdown.3 new file mode 100644 index 0000000000..81eb703c67 --- /dev/null +++ b/src/lib/libssl/man/SSL_set_shutdown.3 @@ -0,0 +1,88 @@ +.\" +.\" $OpenBSD: SSL_set_shutdown.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SET_SHUTDOWN 3 +.Os +.Sh NAME +.Nm SSL_set_shutdown , +.Nm SSL_get_shutdown +.Nd manipulate shutdown state of an SSL connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_set_shutdown "SSL *ssl" "int mode" +.Ft int +.Fn SSL_get_shutdown "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_set_shutdown +sets the shutdown state of +.Fa ssl +to +.Fa mode . +.Pp +.Fn SSL_get_shutdown +returns the shutdown mode of +.Fa ssl . +.Sh NOTES +The shutdown state of an ssl connection is a bitmask of: +.Bl -tag -width Ds +.It 0 +No shutdown setting, yet. +.It Dv SSL_SENT_SHUTDOWN +A +.Dq close notify +shutdown alert was sent to the peer; the connection is being considered closed +and the session is closed and correct. +.It Dv SSL_RECEIVED_SHUTDOWN +A shutdown alert was received form the peer, either a normal +.Dq close notify +or a fatal error. +.El +.Pp +.Dv SSL_SENT_SHUTDOWN +and +.Dv SSL_RECEIVED_SHUTDOWN +can be set at the same time. +.Pp +The shutdown state of the connection is used to determine the state of the +.Fa ssl +session. +If the session is still open when +.Xr SSL_clear 3 +or +.Xr SSL_free 3 +is called, it is considered bad and removed according to RFC2246. +The actual condition for a correctly closed session is +.Dv SSL_SENT_SHUTDOWN +(according to the TLS RFC, it is acceptable to only send the +.Dq close notify +alert but to not wait for the peer's answer when the underlying connection is +closed). +.Fn SSL_set_shutdown +can be used to set this state without sending a close alert to the peer (see +.Xr SSL_shutdown 3 ) . +.Pp +If a +.Dq close notify +was received, +.Dv SSL_RECEIVED_SHUTDOWN +will be set, but to set +.Dv SSL_SENT_SHUTDOWN +the application must still call +.Xr SSL_shutdown 3 +or +.Fn SSL_set_shutdown +itself. +.Sh RETURN VALUES +.Fn SSL_set_shutdown +does not return diagnostic information. +.Pp +.Fn SSL_get_shutdown +returns the current setting. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_clear 3 , +.Xr SSL_CTX_set_quiet_shutdown 3 , +.Xr SSL_free 3 , +.Xr SSL_shutdown 3 diff --git a/src/lib/libssl/man/SSL_set_verify_result.3 b/src/lib/libssl/man/SSL_set_verify_result.3 new file mode 100644 index 0000000000..298b6b28c6 --- /dev/null +++ b/src/lib/libssl/man/SSL_set_verify_result.3 @@ -0,0 +1,42 @@ +.\" +.\" $OpenBSD: SSL_set_verify_result.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SET_VERIFY_RESULT 3 +.Os +.Sh NAME +.Nm SSL_set_verify_result +.Nd override result of peer certificate verification +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft void +.Fn SSL_set_verify_result "SSL *ssl" "long verify_result" +.Sh DESCRIPTION +.Fn SSL_set_verify_result +sets +.Fa verify_result +of the object +.Fa ssl +to be the result of the verification of the X509 certificate presented by the +peer, if any. +.Sh NOTES +.Fn SSL_set_verify_result +overrides the verification result. +It only changes the verification result of the +.Fa ssl +object. +It does not become part of the established session, so if the session is to be +reused later, the original value will reappear. +.Pp +The valid codes for +.Fa verify_result +are documented in +.Xr openssl 1 . +.Sh RETURN VALUES +.Fn SSL_set_verify_result +does not provide a return value. +.Sh SEE ALSO +.Xr openssl 1 , +.Xr ssl 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_verify_result 3 diff --git a/src/lib/libssl/man/SSL_shutdown.3 b/src/lib/libssl/man/SSL_shutdown.3 new file mode 100644 index 0000000000..1dfcb54bfe --- /dev/null +++ b/src/lib/libssl/man/SSL_shutdown.3 @@ -0,0 +1,204 @@ +.\" +.\" $OpenBSD: SSL_shutdown.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_SHUTDOWN 3 +.Os +.Sh NAME +.Nm SSL_shutdown +.Nd shut down a TLS/SSL connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_shutdown "SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_shutdown +shuts down an active TLS/SSL connection. +It sends the +.Dq close notify +shutdown alert to the peer. +.Sh NOTES +.Fn SSL_shutdown +tries to send the +.Dq close notify +shutdown alert to the peer. +Whether the operation succeeds or not, the +.Dv SSL_SENT_SHUTDOWN +flag is set and a currently open session is considered closed and good and will +be kept in the session cache for further reuse. +.Pp +The shutdown procedure consists of 2 steps: the sending of the +.Dq close notify +shutdown alert and the reception of the peer's +.Dq close notify +shutdown alert. +According to the TLS standard, it is acceptable for an application to only send +its shutdown alert and then close the underlying connection without waiting for +the peer's response (this way resources can be saved, as the process can +already terminate or serve another connection). +When the underlying connection shall be used for more communications, +the complete shutdown procedure (bidirectional +.Dq close notify +alerts) must be performed, so that the peers stay synchronized. +.Pp +.Fn SSL_shutdown +supports both uni- and bidirectional shutdown by its 2 step behavior. +.Pp +When the application is the first party to send the +.Dq close notify +alert, +.Fn SSL_shutdown +will only send the alert and then set the +.Dv SSL_SENT_SHUTDOWN +flag (so that the session is considered good and will be kept in cache). +.Fn SSL_shutdown +will then return 0. +If a unidirectional shutdown is enough +(the underlying connection shall be closed anyway), this first call to +.Fn SSL_shutdown +is sufficient. +In order to complete the bidirectional shutdown handshake, +.Fn SSL_shutdown +must be called again. +The second call will make +.Fn SSL_shutdown +wait for the peer's +.Dq close notify +shutdown alert. +On success, the second call to +.Fn SSL_shutdown +will return 1. +.Pp +If the peer already sent the +.Dq close notify +alert and it was already processed implicitly inside another function +.Pq Xr SSL_read 3 , +the +.Dv SSL_RECEIVED_SHUTDOWN +flag is set. +.Fn SSL_shutdown +will send the +.Dq close notify +alert, set the +.Dv SSL_SENT_SHUTDOWN +flag and will immediately return with 1. +Whether +.Dv SSL_RECEIVED_SHUTDOWN +is already set can be checked using the +.Fn SSL_get_shutdown +(see also the +.Xr SSL_set_shutdown 3 +call). +.Pp +It is therefore recommended to check the return value of +.Fn SSL_shutdown +and call +.Fn SSL_shutdown +again, if the bidirectional shutdown is not yet complete (return value of the +first call is 0). +As the shutdown is not specially handled in the SSLv2 protocol, +.Fn SSL_shutdown +will succeed on the first call. +.Pp +The behaviour of +.Fn SSL_shutdown +additionally depends on the underlying +.Vt BIO . +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_shutdown +will only return once the +handshake step has been finished or an error occurred. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_shutdown +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_shutdown +to continue the handshake. +In this case a call to +.Xr SSL_get_error 3 +with the +return value of +.Fn SSL_shutdown +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_shutdown . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the +.Vt BIO +before being able to continue. +.Pp +.Fn SSL_shutdown +can be modified to only set the connection to +.Dq shutdown +state but not actually send the +.Dq close notify +alert messages; see +.Xr SSL_CTX_set_quiet_shutdown 3 . +When +.Dq quiet shutdown +is enabled, +.Fn SSL_shutdown +will always succeed and return 1. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It 0 +The shutdown is not yet finished. +Call +.Fn SSL_shutdown +for a second time, if a bidirectional shutdown shall be performed. +The output of +.Xr SSL_get_error 3 +may be misleading, as an erroneous +.Dv SSL_ERROR_SYSCALL +may be flagged even though no error occurred. +.It 1 +The shutdown was successfully completed. +The +.Dq close notify +alert was sent and the peer's +.Dq close notify +alert was received. +.It \(mi1 +The shutdown was not successful because a fatal error occurred either +at the protocol level or a connection failure occurred. +It can also occur if action is need to continue the operation for non-blocking +.Vt BIO Ns +s. +Call +.Xr SSL_get_error 3 +with the return value +.Fa ret +to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_clear 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_set_quiet_shutdown 3 , +.Xr SSL_free 3 , +.Xr SSL_get_error 3 , +.Xr SSL_set_shutdown 3 diff --git a/src/lib/libssl/man/SSL_state_string.3 b/src/lib/libssl/man/SSL_state_string.3 new file mode 100644 index 0000000000..bde359243e --- /dev/null +++ b/src/lib/libssl/man/SSL_state_string.3 @@ -0,0 +1,57 @@ +.\" +.\" $OpenBSD: SSL_state_string.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_STATE_STRING 3 +.Os +.Sh NAME +.Nm SSL_state_string , +.Nm SSL_state_string_long +.Nd get textual description of state of an SSL object +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft const char * +.Fn SSL_state_string "const SSL *ssl" +.Ft const char * +.Fn SSL_state_string_long "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_state_string +returns a 6 letter string indicating the current state of the +.Vt SSL +object +.Fa ssl . +.Pp +.Fn SSL_state_string_long +returns a string indicating the current state of the +.Vt SSL +object +.Fa ssl . +.Sh NOTES +During its use, an +.Vt SSL +object passes several states. +The state is internally maintained. +Querying the state information is not very informative before or when a +connection has been established. +It however can be of significant interest during the handshake. +.Pp +When using non-blocking sockets, +the function call performing the handshake may return with +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +condition, so that +.Fn SSL_state_string[_long] +may be called. +.Pp +For both blocking or non-blocking sockets, +the details state information can be used within the +.Fn info_callback +function set with the +.Xr SSL_set_info_callback 3 +call. +.Sh RETURN VALUES +Detailed description of possible states to be included later. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_set_info_callback 3 diff --git a/src/lib/libssl/man/SSL_want.3 b/src/lib/libssl/man/SSL_want.3 new file mode 100644 index 0000000000..456d0728dc --- /dev/null +++ b/src/lib/libssl/man/SSL_want.3 @@ -0,0 +1,103 @@ +.\" +.\" $OpenBSD: SSL_want.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_WANT 3 +.Os +.Sh NAME +.Nm SSL_want , +.Nm SSL_want_nothing , +.Nm SSL_want_read , +.Nm SSL_want_write , +.Nm SSL_want_x509_lookup +.Nd obtain state information TLS/SSL I/O operation +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_want "const SSL *ssl" +.Ft int +.Fn SSL_want_nothing "const SSL *ssl" +.Ft int +.Fn SSL_want_read "const SSL *ssl" +.Ft int +.Fn SSL_want_write "const SSL *ssl" +.Ft int +.Fn SSL_want_x509_lookup "const SSL *ssl" +.Sh DESCRIPTION +.Fn SSL_want +returns state information for the +.Vt SSL +object +.Fa ssl . +.Pp +The other +.Fn SSL_want_* +calls are shortcuts for the possible states returned by +.Fn SSL_want . +.Sh NOTES +.Fn SSL_want +examines the internal state information of the +.Vt SSL +object. +Its return values are similar to those of +.Xr SSL_get_error 3 . +Unlike +.Xr SSL_get_error 3 , +which also evaluates the error queue, +the results are obtained by examining an internal state flag only. +The information must therefore only be used for normal operation under +non-blocking I/O. +Error conditions are not handled and must be treated using +.Xr SSL_get_error 3 . +.Pp +The result returned by +.Fn SSL_want +should always be consistent with the result of +.Xr SSL_get_error 3 . +.Sh RETURN VALUES +The following return values can currently occur for +.Fn SSL_want : +.Bl -tag -width Ds +.It .Dv SSL_NOTHING +There is no data to be written or to be read. +.It .Dv SSL_WRITING +There are data in the SSL buffer that must be written to the underlying +.Vt BIO +layer in order to complete the actual +.Fn SSL_* +operation. +A call to +.Xr SSL_get_error 3 +should return +.Dv SSL_ERROR_WANT_WRITE . +.It Dv SSL_READING +More data must be read from the underlying +.Vt BIO +layer in order to +complete the actual +.Fn SSL_* +operation. +A call to +.Xr SSL_get_error 3 +should return +.Dv SSL_ERROR_WANT_READ. +.It Dv SSL_X509_LOOKUP +The operation did not complete because an application callback set by +.Xr SSL_CTX_set_client_cert_cb 3 +has asked to be called again. +A call to +.Xr SSL_get_error 3 +should return +.Dv SSL_ERROR_WANT_X509_LOOKUP . +.El +.Pp +.Fn SSL_want_nothing , +.Fn SSL_want_read , +.Fn SSL_want_write , +and +.Fn SSL_want_x509_lookup +return 1 when the corresponding condition is true or 0 otherwise. +.Sh SEE ALSO +.Xr err 3 , +.Xr ssl 3 , +.Xr SSL_get_error 3 diff --git a/src/lib/libssl/man/SSL_write.3 b/src/lib/libssl/man/SSL_write.3 new file mode 100644 index 0000000000..a4db3d37de --- /dev/null +++ b/src/lib/libssl/man/SSL_write.3 @@ -0,0 +1,175 @@ +.\" +.\" $OpenBSD: SSL_write.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL_WRITE 3 +.Os +.Sh NAME +.Nm SSL_write +.Nd write bytes to a TLS/SSL connection +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft int +.Fn SSL_write "SSL *ssl" "const void *buf" "int num" +.Sh DESCRIPTION +.Fn SSL_write +writes +.Fa num +bytes from the buffer +.Fa buf +into the specified +.Fa ssl +connection. +.Sh NOTES +If necessary, +.Fn SSL_write +will negotiate a TLS/SSL session, if not already explicitly performed by +.Xr SSL_connect 3 +or +.Xr SSL_accept 3 . +If the peer requests a re-negotiation, +it will be performed transparently during the +.Fn SSL_write +operation. +The behaviour of +.Fn SSL_write +depends on the underlying +.Vt BIO . +.Pp +For the transparent negotiation to succeed, the +.Fa ssl +must have been initialized to client or server mode. +This is being done by calling +.Xr SSL_set_connect_state 3 +or +.Xr SSL_set_accept_state 3 +before the first call to an +.Xr SSL_read 3 +or +.Fn SSL_write +function. +.Pp +If the underlying +.Vt BIO +is +.Em blocking , +.Fn SSL_write +will only return once the write operation has been finished or an error +occurred, except when a renegotiation take place, in which case a +.Dv SSL_ERROR_WANT_READ +may occur. +This behaviour can be controlled with the +.Dv SSL_MODE_AUTO_RETRY +flag of the +.Xr SSL_CTX_set_mode 3 +call. +.Pp +If the underlying +.Vt BIO +is +.Em non-blocking , +.Fn SSL_write +will also return when the underlying +.Vt BIO +could not satisfy the needs of +.Fn SSL_write +to continue the operation. +In this case a call to +.Xr SSL_get_error 3 +with the return value of +.Fn SSL_write +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE . +As at any time a re-negotiation is possible, a call to +.Fn SSL_write +can also cause read operations! +The calling process then must repeat the call after taking appropriate action +to satisfy the needs of +.Fn SSL_write . +The action depends on the underlying +.Vt BIO . +When using a non-blocking socket, nothing is to be done, but +.Xr select 2 +can be used to check for the required condition. +When using a buffering +.Vt BIO , +like a +.Vt BIO +pair, data must be written into or retrieved out of the BIO before being able +to continue. +.Pp +.Fn SSL_write +will only return with success, when the complete contents of +.Fa buf +of length +.Fa num +have been written. +This default behaviour can be changed with the +.Dv SSL_MODE_ENABLE_PARTIAL_WRITE +option of +.Xr SSL_CTX_set_mode 3 . +When this flag is set, +.Fn SSL_write +will also return with success when a partial write has been successfully +completed. +In this case the +.Fn SSL_write +operation is considered completed. +The bytes are sent and a new +.Fn SSL_write +operation with a new buffer (with the already sent bytes removed) must be +started. +A partial write is performed with the size of a message block, which is 16kB +for SSLv3/TLSv1. +.Sh WARNING +When an +.Fn SSL_write +operation has to be repeated because of +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE , +it must be repeated with the same arguments. +.Pp +When calling +.Fn SSL_write +with +.Fa num Ns +=0 bytes to be sent the behaviour is undefined. +.Sh RETURN VALUES +The following return values can occur: +.Bl -tag -width Ds +.It >0 +The write operation was successful. +The return value is the number of bytes actually written to the TLS/SSL +connection. +.It 0 +The write operation was not successful. +Probably the underlying connection was closed. +Call +.Xr SSL_get_error 3 +with the return value to find out whether an error occurred or the connection +was shut down cleanly +.Pq Dv SSL_ERROR_ZERO_RETURN . +.Pp +SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only +be detected whether the underlying connection was closed. +It cannot be checked why the closure happened. +.It <0 +The write operation was not successful, because either an error occurred or +action must be taken by the calling process. +Call +.Xr SSL_get_error 3 +with the return value to find out the reason. +.El +.Sh SEE ALSO +.Xr bio 3 , +.Xr ssl 3 , +.Xr SSL_accept 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_get_error 3 , +.Xr SSL_read 3 , +.Xr SSL_set_connect_state 3 diff --git a/src/lib/libssl/man/d2i_SSL_SESSION.3 b/src/lib/libssl/man/d2i_SSL_SESSION.3 new file mode 100644 index 0000000000..9a96a5b8ec --- /dev/null +++ b/src/lib/libssl/man/d2i_SSL_SESSION.3 @@ -0,0 +1,129 @@ +.\" +.\" $OpenBSD: d2i_SSL_SESSION.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt D2I_SSL_SESSION 3 +.Os +.Sh NAME +.Nm d2i_SSL_SESSION , +.Nm i2d_SSL_SESSION +.Nd convert SSL_SESSION object from/to ASN1 representation +.Sh SYNOPSIS +.In openssl/ssl.h +.Ft SSL_SESSION * +.Fn d2i_SSL_SESSION "SSL_SESSION **a" "const unsigned char **pp" "long length" +.Ft int +.Fn i2d_SSL_SESSION "SSL_SESSION *in" "unsigned char **pp" +.Sh DESCRIPTION +.Fn d2i_SSL_SESSION +transforms the external ASN1 representation of an SSL/TLS session, +stored as binary data at location +.Fa pp +with length +.Fa length , +into +an +.Vt SSL_SESSION +object. +.Pp +.Fn i2d_SSL_SESSION +transforms the +.Vt SSL_SESSION +object +.Fa in +into the ASN1 representation and stores it into the memory location pointed to +by +.Fa pp . +The length of the resulting ASN1 representation is returned. +If +.Fa pp +is the +.Dv NULL +pointer, only the length is calculated and returned. +.Sh NOTES +The +.Vt SSL_SESSION +object is built from several +.Xr malloc 3 Ns +-ed parts; it can therefore not be moved, copied or stored directly. +In order to store session data on disk or into a database, +it must be transformed into a binary ASN1 representation. +.Pp +When using +.Fn d2i_SSL_SESSION , +the +.Vt SSL_SESSION +object is automatically allocated. +The reference count is 1, so that the session must be explicitly removed using +.Xr SSL_SESSION_free 3 , +unless the +.Vt SSL_SESSION +object is completely taken over, when being called inside the +.Xr get_session_cb 3 +(see +.Xr SSL_CTX_sess_set_get_cb 3 ) . +.Pp +.Vt SSL_SESSION +objects keep internal link information about the session cache list when being +inserted into one +.Vt SSL_CTX +object's session cache. +One +.Vt SSL_SESSION +object, regardless of its reference count, must therefore only be used with one +.Vt SSL_CTX +object (and the +.Vt SSL +objects created from this +.Vt SSL_CTX +object). +.Pp +When using +.Fn i2d_SSL_SESSION , +the memory location pointed to by +.Fa pp +must be large enough to hold the binary representation of the session. +There is no known limit on the size of the created ASN1 representation, +so the necessary amount of space should be obtained by first calling +.Fn i2d_SSL_SESSION +with +.Fa pp Ns += Ns +.Dv NULL , +and obtain the size needed, then allocate the memory and call +.Fn i2d_SSL_SESSION +again. +Note that this will advance the value contained in +.Fa *pp +so it is necessary to save a copy of the original allocation. +For example: +.Bd -literal +int i, j; + +char *p, *temp; + + i = i2d_SSL_SESSION(sess, NULL); + p = temp = malloc(i); + if (temp != NULL) { + j = i2d_SSL_SESSION(sess, &temp); + assert(i == j); + assert(p + i == temp); + } +.Ed +.Sh RETURN VALUES +.Fn d2i_SSL_SESSION +returns a pointer to the newly allocated +.Vt SSL_SESSION +object. +In case of failure a +.Dv NULL +pointer is returned and the error message can be retrieved from the error +stack. +.Pp +.Fn i2d_SSL_SESSION +returns the size of the ASN1 representation in bytes. +When the session is not valid, 0 is returned and no operation is performed. +.Sh SEE ALSO +.Xr ssl 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_SESSION_free 3 diff --git a/src/lib/libssl/man/ssl.3 b/src/lib/libssl/man/ssl.3 new file mode 100644 index 0000000000..004d71f9f2 --- /dev/null +++ b/src/lib/libssl/man/ssl.3 @@ -0,0 +1,1319 @@ +.\" +.\" $OpenBSD: ssl.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $ +.\" +.Dd $Mdocdate: November 5 2016 $ +.Dt SSL 3 +.Os +.Sh NAME +.Nm ssl +.Nd OpenSSL SSL/TLS library +.Sh DESCRIPTION +The OpenSSL +.Nm ssl +library implements the Secure Sockets Layer (SSL v2/v3) and +Transport Layer Security (TLS v1) protocols. +It provides a rich API which is documented here. +.Pp +At first the library must be initialized; see +.Xr SSL_library_init 3 . +.Pp +Then an +.Vt SSL_CTX +object is created as a framework to establish TLS/SSL enabled connections (see +.Xr SSL_CTX_new 3 ) . +Various options regarding certificates, algorithms, etc., can be set in this +object. +.Pp +When a network connection has been created, it can be assigned to an +.Vt SSL +object. +After the +.Vt SSL +object has been created using +.Xr SSL_new 3 , +.Xr SSL_set_fd 3 +or +.Xr SSL_set_bio 3 +can be used to associate the network connection with the object. +.Pp +Then the TLS/SSL handshake is performed using +.Xr SSL_accept 3 +or +.Xr SSL_connect 3 +respectively. +.Xr SSL_read 3 +and +.Xr SSL_write 3 +are used to read and write data on the TLS/SSL connection. +.Xr SSL_shutdown 3 +can be used to shut down the TLS/SSL connection. +.Sh DATA STRUCTURES +Currently the OpenSSL +.Nm ssl +library functions deals with the following data structures: +.Bl -tag -width Ds +.It Vt SSL_METHOD No (SSL Method) +That's a dispatch structure describing the internal +.Nm ssl +library methods/functions which implement the various protocol versions +(SSLv1, SSLv2 and TLSv1). +It's needed to create an +.Vt SSL_CTX . +.It Vt SSL_CIPHER No (SSL Cipher) +This structure holds the algorithm information for a particular cipher which +is a core part of the SSL/TLS protocol. +The available ciphers are configured on an +.Vt SSL_CTX +basis and the actually used ones are then part of the +.Vt SSL_SESSION . +.It Vt SSL_CTX No (SSL Context) +That's the global context structure which is created by a server or client +once per program lifetime and which holds mainly default values for the +.Vt SSL +structures which are later created for the connections. +.It Vt SSL_SESSION No (SSL Session) +This is a structure containing the current TLS/SSL session details for a +connection: +.Vt SSL_CIPHER Ns s, client and server certificates, keys, etc. +.It Vt SSL No (SSL Connection) +That's the main SSL/TLS structure which is created by a server or client per +established connection. +This actually is the core structure in the SSL API. +Under run-time the application usually deals with this structure which has +links to mostly all other structures. +.El +.Sh HEADER FILES +Currently the OpenSSL +.Nm ssl +library provides the following C header files containing the prototypes for the +data structures and functions: +.Bl -tag -width Ds +.It Pa ssl.h +That's the common header file for the SSL/TLS API. +Include it into your program to make the API of the +.Nm ssl +library available. +It internally includes both more private SSL headers and headers from the +.Em crypto +library. +Whenever you need hardcore details on the internals of the SSL API, look inside +this header file. +.It Pa ssl2.h +That's the sub header file dealing with the SSLv2 protocol only. +.Bf Em + Usually you don't have to include it explicitly because it's already included +by +.Pa ssl.h . +.Ef +.It Pa ssl3.h +That's the sub header file dealing with the SSLv3 protocol only. +.Bf Em +Usually you don't have to include it explicitly because it's already included +by +.Pa ssl.h . +.Ef +.It Pa ssl23.h +That's the sub header file dealing with the combined use of the SSLv2 and SSLv3 +protocols. +.Bf Em +Usually you don't have to include it explicitly because it's already included +by +.Pa ssl.h . +.Ef +.It Pa tls1.h +That's the sub header file dealing with the TLSv1 protocol only. +.Bf Em +Usually you don't have to include it explicitly because it's already included +by +.Pa ssl.h . +.Ef +.El +.Sh API FUNCTIONS +The functions that the OpenSSL +.Nm ssl +library exports are documented below: +.Ss DEALING WITH PROTOCOL METHODS +Here we document the various API functions which deal with the SSL/TLS protocol +methods defined in +.Vt SSL_METHOD +structures. +.Bl -tag -width Ds +.It Xo +.Ft const SSL_METHOD * +.Fn SSLv2_client_method void +.Xc +Constructor for the SSLv2 +.Vt SSL_METHOD +structure for a dedicated client. +.It Xo +.Ft const SSL_METHOD * +.Fn SSLv2_server_method void +.Xc +Constructor for the SSLv2 +.Vt SSL_METHOD +structure for a dedicated server. +.It Xo +.Ft const SSL_METHOD * +.Fn SSLv2_method void +.Xc +Constructor for the SSLv2 +.Vt SSL_METHOD +structure for combined client and server. +.It Xo +.Ft const SSL_METHOD * +.Fn SSLv3_client_method void +.Xc +Constructor for the SSLv3 +.Vt SSL_METHOD +structure for a dedicated client. +.It Xo +.Ft const SSL_METHOD * +.Fn SSLv3_server_method void +.Xc +Constructor for the SSLv3 +.Vt SSL_METHOD +structure for a dedicated server. +.It Xo +.Ft const SSL_METHOD * +.Fn SSLv3_method void +.Xc +Constructor for the SSLv3 +.Vt SSL_METHOD +structure for combined client and server. +.It Xo +.Ft const SSL_METHOD * +.Fn TLSv1_client_method void +.Xc +Constructor for the TLSv1 +.Vt SSL_METHOD +structure for a dedicated client. +.It Xo +.Ft const SSL_METHOD * +.Fn TLSv1_server_method void +.Xc +Constructor for the TLSv1 +.Vt SSL_METHOD +structure for a dedicated server. +.It Xo +.Ft const SSL_METHOD * +.Fn TLSv1_method void +.Xc +Constructor for the TLSv1 +.Vt SSL_METHOD +structure for combined client and server. +.El +.Ss DEALING WITH CIPHERS +Here we document the various API functions which deal with the SSL/TLS ciphers +defined in +.Vt SSL_CIPHER +structures. +.Bl -tag -width Ds +.It Xo +.Ft char * +.Fn SSL_CIPHER_description "SSL_CIPHER *cipher" "char *buf" "int len" +.Xc +Write a string to +.Fa buf +(with a maximum size of +.Fa len ) +containing a human readable description of +.Fa cipher . +Returns +.Fa buf . +.It Xo +.Ft int +.Fn SSL_CIPHER_get_bits "SSL_CIPHER *cipher" "int *alg_bits" +.Xc +Determine the number of bits in +.Fa cipher . +Because of export crippled ciphers there are two bits: +the bits the algorithm supports in general (stored to +.Fa alg_bits ) +and the bits which are actually used (the return value). +.It Xo +.Ft const char * +.Fn SSL_CIPHER_get_name "SSL_CIPHER *cipher" +.Xc +Return the internal name of +.Fa cipher +as a string. +These are the various strings defined by the +.Dv SSL2_TXT_xxx , +.Dv SSL3_TXT_xxx +and +.Dv TLS1_TXT_xxx +definitions in the header files. +.It Xo +.Ft char * +.Fn SSL_CIPHER_get_version "SSL_CIPHER *cipher" +.Xc +Returns a string like +Qq TLSv1/SSLv3 +or +Qq SSLv2 +which indicates the SSL/TLS protocol version to which +.Fa cipher +belongs (i.e., where it was defined in the specification the first time). +.El +.Ss DEALING WITH PROTOCOL CONTEXTS +Here we document the various API functions which deal with the SSL/TLS +protocol context defined in the +.Vt SSL_CTX +structure. +.Bl -tag -width Ds +.It Xo +.Ft int +.Fn SSL_CTX_add_client_CA "SSL_CTX *ctx" "X509 *x" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_add_extra_chain_cert "SSL_CTX *ctx" "X509 *x509" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_add_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_check_private_key "const SSL_CTX *ctx" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_ctrl "SSL_CTX *ctx" "int cmd" "long larg" "char *parg" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_flush_sessions "SSL_CTX *s" "long t" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_free "SSL_CTX *a" +.Xc +.It Xo +.Ft char * +.Fn SSL_CTX_get_app_data "SSL_CTX *ctx" +.Xc +.It Xo +.Ft X509_STORE * +.Fn SSL_CTX_get_cert_store "SSL_CTX *ctx" +.Xc +.It Xo +.Ft STACK * +.Fn SSL_CTX_get_client_CA_list "const SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn "(*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))" +.Fa "SSL *ssl" "X509 **x509" "EVP_PKEY **pkey" +.Xc +.It Xo +.Ft char * +.Fn SSL_CTX_get_ex_data "const SSL_CTX *s" "int idx" +.Xc +.It Xo +.Ft int +.Fo SSL_CTX_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Xc +.It Xo +.Ft void +.Fo "(*SSL_CTX_get_info_callback(const SSL_CTX *ctx))" +.Fa "SSL *ssl" +.Fa "int cb" +.Fa "int ret" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_get_quiet_shutdown "const SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_get_session_cache_mode "SSL_CTX *ctx" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_get_timeout "const SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fo "(*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))" +.Fa "int ok" +.Fa "X509_STORE_CTX *ctx" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_get_verify_mode "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_load_verify_locations "SSL_CTX *ctx" "char *CAfile" "char *CApath" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_need_tmp_RSA "SSL_CTX *ctx" +.Xc +.It Xo +.Ft SSL_CTX * +.Fn SSL_CTX_new "const SSL_METHOD *meth" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_remove_session "SSL_CTX *ctx" "SSL_SESSION *c" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_accept "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_accept_good "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_accept_renegotiate "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_cache_full "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_cb_hits "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_connect "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_connect_good "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_connect_renegotiate "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_get_cache_size "SSL_CTX *ctx" +.Xc +.It Xo +.Ft SSL_SESSION * +.Fo "(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))" +.Fa "SSL *ssl" +.Fa "unsigned char *data" +.Fa "int len" +.Fa "int *copy" +.Fc +.Xc +.It Xo +.Ft int +.Fn "(*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))" "SSL *ssl" "SSL_SESSION *sess" +.Xc +.It Xo +.Ft void +.Fo "(*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))" +.Fa "SSL_CTX *ctx" +.Fa "SSL_SESSION *sess" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_hits "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_misses "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_number "SSL_CTX *ctx" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_sess_set_cache_size "SSL_CTX *ctx" "long t" +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_sess_set_get_cb +.Fa "SSL_CTX *ctx" +.Fa "SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)" +.Fc +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_sess_set_new_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*cb)(SSL *ssl, SSL_SESSION *sess)" +.Fc +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_sess_set_remove_cb +.Fa "SSL_CTX *ctx" +.Fa "void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_sess_timeouts "SSL_CTX *ctx" +.Xc +.It Xo +.Ft LHASH * +.Fn SSL_CTX_sessions "SSL_CTX *ctx" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_app_data "SSL_CTX *ctx" "void *arg" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_cert_store "SSL_CTX *ctx" "X509_STORE *cs" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_cert_verify_cb "SSL_CTX *ctx" "int (*cb)()" "char *arg" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_set_cipher_list "SSL_CTX *ctx" "char *str" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_client_CA_list "SSL_CTX *ctx" "STACK *list" +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_set_client_cert_cb +.Fa "SSL_CTX *ctx" +.Fa "int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)" +.Fc +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_default_read_ahead "SSL_CTX *ctx" "int m" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_set_default_verify_paths "SSL_CTX *ctx" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_set_ex_data "SSL_CTX *s" "int idx" "char *arg" +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_set_info_callback +.Fa "SSL_CTX *ctx" +.Fa "void (*cb)(SSL *ssl, int cb, int ret)" +.Fc +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_set_msg_callback +.Fa "SSL_CTX *ctx" +.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, \ +size_t len, SSL *ssl, void *arg)" +.Fc +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_msg_callback_arg "SSL_CTX *ctx" "void *arg" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_options "SSL_CTX *ctx" "unsigned long op" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_quiet_shutdown "SSL_CTX *ctx" "int mode" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_session_cache_mode "SSL_CTX *ctx" "int mode" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_set_ssl_version "SSL_CTX *ctx" "const SSL_METHOD *meth" +.Xc +.It Xo +.Ft void +.Fn SSL_CTX_set_timeout "SSL_CTX *ctx" "long t" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_set_tmp_dh "SSL_CTX* ctx" "DH *dh" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_set_tmp_dh_callback "SSL_CTX *ctx" "DH *(*cb)(void)" +.Xc +.It Xo +.Ft long +.Fn SSL_CTX_set_tmp_rsa "SSL_CTX *ctx" "RSA *rsa" +.Xc +.It Xo +.Fn SSL_CTX_set_tmp_rsa_callback +.Xc +.Ft long +.Fo SSL_CTX_set_tmp_rsa_callback +.Fa "SSL_CTX *ctx" +.Fa "RSA *(*cb)(SSL *ssl, int export, int keylength)" +.Fc +.Pp +Sets the callback which will be called when a temporary private key is +required. +The +.Fa export +flag will be set if the reason for needing a temp key is that an export +ciphersuite is in use, in which case, +.Fa keylength +will contain the required keylength in bits. +.\" XXX using what? +Generate a key of appropriate size (using ???) and return it. +.It Xo +.Fn SSL_set_tmp_rsa_callback +.Xc +.Ft long +.Fo SSL_set_tmp_rsa_callback +.Fa "SSL *ssl" +.Fa "RSA *(*cb)(SSL *ssl, int export, int keylength)" +.Fc +.Pp +The same as +.Fn SSL_CTX_set_tmp_rsa_callback , +except it operates on an +.Vt SSL +session instead of a context. +.It Xo +.Ft void +.Fn SSL_CTX_set_verify "SSL_CTX *ctx" "int mode" "int (*cb)(void)" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_PrivateKey "SSL_CTX *ctx" "EVP_PKEY *pkey" +.Xc +.It Xo +.Ft int +.Fo SSL_CTX_use_PrivateKey_ASN1 +.Fa "int type" +.Fa "SSL_CTX *ctx" +.Fa "unsigned char *d" +.Fa "long len" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_PrivateKey_file "SSL_CTX *ctx" "char *file" "int type" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey "SSL_CTX *ctx" "RSA *rsa" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey_ASN1 "SSL_CTX *ctx" "unsigned char *d" "long len" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_RSAPrivateKey_file "SSL_CTX *ctx" "char *file" "int type" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_certificate "SSL_CTX *ctx" "X509 *x" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_certificate_ASN1 "SSL_CTX *ctx" "int len" "unsigned char *d" +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_certificate_file "SSL_CTX *ctx" "char *file" "int type" +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_set_psk_client_callback +.Fa "SSL_CTX *ctx" +.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \ +unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_CTX_use_psk_identity_hint "SSL_CTX *ctx" "const char *hint" +.Xc +.It Xo +.Ft void +.Fo SSL_CTX_set_psk_server_callback +.Fa "SSL_CTX *ctx" +.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, \ +unsigned char *psk, int max_psk_len)" +.Fc +.Xc +.El +.Ss DEALING WITH SESSIONS +Here we document the various API functions which deal with the SSL/TLS sessions +defined in the +.Vt SSL_SESSION +structures. +.Bl -tag -width Ds +.It Xo +.Ft int +.Fn SSL_SESSION_cmp "const SSL_SESSION *a" "const SSL_SESSION *b" +.Xc +.It Xo +.Ft void +.Fn SSL_SESSION_free "SSL_SESSION *ss" +.Xc +.It Xo +.Ft char * +.Fn SSL_SESSION_get_app_data "SSL_SESSION *s" +.Xc +.It Xo +.Ft char * +.Fn SSL_SESSION_get_ex_data "const SSL_SESSION *s" "int idx" +.Xc +.It Xo +.Ft int +.Fo SSL_SESSION_get_ex_new_index +.Fa "long argl" +.Fa "char *argp" +.Fa "int (*new_func)(void)" +.Fa "int (*dup_func)(void), void (*free_func)(void)" +.Fc +.Xc +.It Xo +.Ft long +.Fn SSL_SESSION_get_time "const SSL_SESSION *s" +.Xc +.It Xo +.Ft long +.Fn SSL_SESSION_get_timeout "const SSL_SESSION *s" +.Xc +.It Xo +.Ft unsigned long +.Fn SSL_SESSION_hash "const SSL_SESSION *a" +.Xc +.It Xo +.Ft SSL_SESSION * +.Fn SSL_SESSION_new void +.Xc +.It Xo +.Ft int +.Fn SSL_SESSION_print "BIO *bp" "const SSL_SESSION *x" +.Xc +.It Xo +.Ft int +.Fn SSL_SESSION_print_fp "FILE *fp" "const SSL_SESSION *x" +.Xc +.It Xo +.Ft void +.Fn SSL_SESSION_set_app_data "SSL_SESSION *s" "char *a" +.Xc +.It Xo +.Ft int +.Fn SSL_SESSION_set_ex_data "SSL_SESSION *s" "int idx" "char *arg" +.Xc +.It Xo +.Ft long +.Fn SSL_SESSION_set_time "SSL_SESSION *s" "long t" +.Xc +.It Xo +.Ft long +.Fn SSL_SESSION_set_timeout "SSL_SESSION *s" "long t" +.Xc +.El +.Ss DEALING WITH CONNECTIONS +Here we document the various API functions which deal with the SSL/TLS +connection defined in the +.Vt SSL +structure. +.Bl -tag -width Ds +.It Xo +.Ft int +.Fn SSL_accept "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_add_dir_cert_subjects_to_stack "STACK *stack" "const char *dir" +.Xc +.It Xo +.Ft int +.Fn SSL_add_file_cert_subjects_to_stack "STACK *stack" "const char *file" +.Xc +.It Xo +.Ft int +.Fn SSL_add_client_CA "SSL *ssl" "X509 *x" +.Xc +.It Xo +.Ft char * +.Fn SSL_alert_desc_string "int value" +.Xc +.It Xo +.Ft char * +.Fn SSL_alert_desc_string_long "int value" +.Xc +.It Xo +.Ft char * +.Fn SSL_alert_type_string "int value" +.Xc +.It Xo +.Ft char * +.Fn SSL_alert_type_string_long "int value" +.Xc +.It Xo +.Ft int +.Fn SSL_check_private_key "const SSL *ssl" +.Xc +.It Xo +.Ft void +.Fn SSL_clear "SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_clear_num_renegotiations "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_connect "SSL *ssl" +.Xc +.It Xo +.Ft void +.Fn SSL_copy_session_id "SSL *t" "const SSL *f" +.Xc +.It Xo +.Ft long +.Fn SSL_ctrl "SSL *ssl" "int cmd" "long larg" "char *parg" +.Xc +.It Xo +.Ft int +.Fn SSL_do_handshake "SSL *ssl" +.Xc +.It Xo +.Ft SSL * +.Fn SSL_dup "SSL *ssl" +.Xc +.It Xo +.Ft STACK * +.Fn SSL_dup_CA_list "STACK *sk" +.Xc +.It Xo +.Ft void +.Fn SSL_free "SSL *ssl" +.Xc +.It Xo +.Ft SSL_CTX * +.Fn SSL_get_SSL_CTX "const SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_app_data "SSL *ssl" +.Xc +.It Xo +.Ft X509 * +.Fn SSL_get_certificate "const SSL *ssl" +.Xc +.It Xo +.Ft const char * +.Fn SSL_get_cipher "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_get_cipher_bits "const SSL *ssl" "int *alg_bits" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_cipher_list "const SSL *ssl" "int n" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_cipher_name "const SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_cipher_version "const SSL *ssl" +.Xc +.It Xo +.Ft STACK * +.Fn SSL_get_ciphers "const SSL *ssl" +.Xc +.It Xo +.Ft STACK * +.Fn SSL_get_client_CA_list "const SSL *ssl" +.Xc +.It Xo +.Ft SSL_CIPHER * +.Fn SSL_get_current_cipher "SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_get_default_timeout "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_get_error "const SSL *ssl" "int i" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_ex_data "const SSL *ssl" "int idx" +.Xc +.It Xo +.Ft int +.Fn SSL_get_ex_data_X509_STORE_CTX_idx void +.Xc +.It Xo +.Ft int +.Fo SSL_get_ex_new_index +.Fa "long argl" +.Fa "char *argp" +.Fa "int (*new_func)(void)" +.Fa "int (*dup_func)(void)" +.Fa "void (*free_func)(void)" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_get_fd "const SSL *ssl" +.Xc +.It Xo +.Ft void +.Fn "(*SSL_get_info_callback(const SSL *ssl))" +.Xc +.It Xo +.Ft STACK * +.Fn SSL_get_peer_cert_chain "const SSL *ssl" +.Xc +.It Xo +.Ft X509 * +.Fn SSL_get_peer_certificate "const SSL *ssl" +.Xc +.It Xo +.Ft EVP_PKEY * +.Fn SSL_get_privatekey "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_get_quiet_shutdown "const SSL *ssl" +.Xc +.It Xo +.Ft BIO * +.Fn SSL_get_rbio "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_get_read_ahead "const SSL *ssl" +.Xc +.It Xo +.Ft SSL_SESSION * +.Fn SSL_get_session "const SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_shared_ciphers "const SSL *ssl" "char *buf" "int len" +.Xc +.It Xo +.Ft int +.Fn SSL_get_shutdown "const SSL *ssl" +.Xc +.It Xo +.Ft const SSL_METHOD * +.Fn SSL_get_ssl_method "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_get_state "const SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_get_time "const SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_get_timeout "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn "(*SSL_get_verify_callback(const SSL *ssl))" int "X509_STORE_CTX *" +.Xc +.It Xo +.Ft int +.Fn SSL_get_verify_mode "const SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_get_verify_result "const SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_get_version "const SSL *ssl" +.Xc +.It Xo +.Ft BIO * +.Fn SSL_get_wbio "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_in_accept_init "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_in_before "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_in_connect_init "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_in_init "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_is_init_finished "SSL *ssl" +.Xc +.It Xo +.Ft STACK * +.Fn SSL_load_client_CA_file "char *file" +.Xc +.It Xo +.Ft void +.Fn SSL_load_error_strings "void" +.Xc +.It Xo +.Ft SSL * +.Fn SSL_new "SSL_CTX *ctx" +.Xc +.It Xo +.Ft long +.Fn SSL_num_renegotiations "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_peek "SSL *ssl" "void *buf" "int num" +.Xc +.It Xo +.Ft int +.Fn SSL_pending "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_read "SSL *ssl" "void *buf" "int num" +.Xc +.It Xo +.Ft int +.Fn SSL_renegotiate "SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_rstate_string "SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_rstate_string_long "SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_session_reused "SSL *ssl" +.Xc +.It Xo +.Ft void +.Fn SSL_set_accept_state "SSL *ssl" +.Xc +.It Xo +.Ft void +.Fn SSL_set_app_data "SSL *ssl" "char *arg" +.Xc +.It Xo +.Ft void +.Fn SSL_set_bio "SSL *ssl" "BIO *rbio" "BIO *wbio" +.Xc +.It Xo +.Ft int +.Fn SSL_set_cipher_list "SSL *ssl" "char *str" +.Xc +.It Xo +.Ft void +.Fn SSL_set_client_CA_list "SSL *ssl" "STACK *list" +.Xc +.It Xo +.Ft void +.Fn SSL_set_connect_state "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_set_ex_data "SSL *ssl" "int idx" "char *arg" +.Xc +.It Xo +.Ft int +.Fn SSL_set_fd "SSL *ssl" "int fd" +.Xc +.It Xo +.Ft void +.Fn SSL_set_info_callback "SSL *ssl" "void (*cb)(void)" +.Xc +.It Xo +.Ft void +.Fo SSL_set_msg_callback +.Fa "SSL *ctx" +.Fa "void (*cb)(int write_p, int version, int content_type, const void *buf, \ +size_t len, SSL *ssl, void *arg)" +.Fc +.Xc +.It Xo +.Ft void +.Fn SSL_set_msg_callback_arg "SSL *ctx" "void *arg" +.Xc +.It Xo +.Ft void +.Fn SSL_set_options "SSL *ssl" "unsigned long op" +.Xc +.It Xo +.Ft void +.Fn SSL_set_quiet_shutdown "SSL *ssl" "int mode" +.Xc +.It Xo +.Ft void +.Fn SSL_set_read_ahead "SSL *ssl" "int yes" +.Xc +.It Xo +.Ft int +.Fn SSL_set_rfd "SSL *ssl" "int fd" +.Xc +.It Xo +.Ft int +.Fn SSL_set_session "SSL *ssl" "SSL_SESSION *session" +.Xc +.It Xo +.Ft void +.Fn SSL_set_shutdown "SSL *ssl" "int mode" +.Xc +.It Xo +.Ft int +.Fn SSL_set_ssl_method "SSL *ssl" "const SSL_METHOD *meth" +.Xc +.It Xo +.Ft void +.Fn SSL_set_time "SSL *ssl" "long t" +.Xc +.It Xo +.Ft void +.Fn SSL_set_timeout "SSL *ssl" "long t" +.Xc +.It Xo +.Ft void +.Fn SSL_set_verify "SSL *ssl" "int mode" "int (*callback)(void)" +.Xc +.It Xo +.Ft void +.Fn SSL_set_verify_result "SSL *ssl" "long arg" +.Xc +.It Xo +.Ft int +.Fn SSL_set_wfd "SSL *ssl" "int fd" +.Xc +.It Xo +.Ft int +.Fn SSL_shutdown "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_state "const SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_state_string "const SSL *ssl" +.Xc +.It Xo +.Ft char * +.Fn SSL_state_string_long "const SSL *ssl" +.Xc +.It Xo +.Ft long +.Fn SSL_total_renegotiations "SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_use_PrivateKey "SSL *ssl" "EVP_PKEY *pkey" +.Xc +.It Xo +.Ft int +.Fn SSL_use_PrivateKey_ASN1 "int type" "SSL *ssl" "unsigned char *d" "long len" +.Xc +.It Xo +.Ft int +.Fn SSL_use_PrivateKey_file "SSL *ssl" "char *file" "int type" +.Xc +.It Xo +.Ft int +.Fn SSL_use_RSAPrivateKey "SSL *ssl" "RSA *rsa" +.Xc +.It Xo +.Ft int +.Fn SSL_use_RSAPrivateKey_ASN1 "SSL *ssl" "unsigned char *d" "long len" +.Xc +.It Xo +.Ft int +.Fn SSL_use_RSAPrivateKey_file "SSL *ssl" "char *file" "int type" +.Xc +.It Xo +.Ft int +.Fn SSL_use_certificate "SSL *ssl" "X509 *x" +.Xc +.It Xo +.Ft int +.Fn SSL_use_certificate_ASN1 "SSL *ssl" "int len" "unsigned char *d" +.Xc +.It Xo +.Ft int +.Fn SSL_use_certificate_file "SSL *ssl" "char *file" "int type" +.Xc +.It Xo +.Ft int +.Fn SSL_version "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_want "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_want_nothing "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_want_read "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_want_write "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_want_x509_lookup "const SSL *ssl" +.Xc +.It Xo +.Ft int +.Fn SSL_write "SSL *ssl" "const void *buf" "int num" +.Xc +.It Xo +.Ft void +.Fo SSL_set_psk_client_callback +.Fa "SSL *ssl" +.Fa "unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, \ +unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)" +.Fc +.Xc +.It Xo +.Ft int +.Fn SSL_use_psk_identity_hint "SSL *ssl" "const char *hint" +.Xc +.It Xo +.Ft void +.Fo SSL_set_psk_server_callback +.Fa "SSL *ssl" +.Fa "unsigned int (*callback)(SSL *ssl, const char *identity, \ +unsigned char *psk, int max_psk_len)" +.Fc +.Xc +.It Xo +.Ft const char * +.Fn SSL_get_psk_identity_hint "SSL *ssl" +.Xc +.It Xo +.Ft const char * +.Fn SSL_get_psk_identity "SSL *ssl" +.Xc +.El +.Sh SEE ALSO +.Xr openssl 1 , +.Xr crypto 3 , +.Xr d2i_SSL_SESSION 3 , +.Xr SSL_accept 3 , +.Xr SSL_alert_type_string 3 , +.Xr SSL_CIPHER_get_name 3 , +.Xr SSL_clear 3 , +.Xr SSL_COMP_add_compression_method 3 , +.Xr SSL_connect 3 , +.Xr SSL_CTX_add_extra_chain_cert 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_ctrl 3 , +.Xr SSL_CTX_flush_sessions 3 , +.Xr SSL_CTX_get_ex_new_index 3 , +.Xr SSL_CTX_get_verify_mode 3 , +.Xr SSL_CTX_load_verify_locations 3 , +.Xr SSL_CTX_new 3 , +.Xr SSL_CTX_sess_number 3 , +.Xr SSL_CTX_sess_set_cache_size 3 , +.Xr SSL_CTX_sess_set_get_cb 3 , +.Xr SSL_CTX_sessions 3 , +.Xr SSL_CTX_set_cert_store 3 , +.Xr SSL_CTX_set_cert_verify_callback 3 , +.Xr SSL_CTX_set_cipher_list 3 , +.Xr SSL_CTX_set_client_CA_list 3 , +.Xr SSL_CTX_set_client_cert_cb 3 , +.Xr SSL_CTX_set_default_passwd_cb 3 , +.Xr SSL_CTX_set_generate_session_id 3 , +.Xr SSL_CTX_set_info_callback 3 , +.Xr SSL_CTX_set_max_cert_list 3 , +.Xr SSL_CTX_set_mode 3 , +.Xr SSL_CTX_set_msg_callback 3 , +.Xr SSL_CTX_set_options 3 , +.Xr SSL_CTX_set_psk_client_callback 3 , +.Xr SSL_CTX_set_quiet_shutdown 3 , +.Xr SSL_CTX_set_session_cache_mode 3 , +.Xr SSL_CTX_set_session_id_context 3 , +.Xr SSL_CTX_set_ssl_version 3 , +.Xr SSL_CTX_set_timeout 3 , +.Xr SSL_CTX_set_tmp_dh_callback 3 , +.Xr SSL_CTX_set_tmp_rsa_callback 3 , +.Xr SSL_CTX_set_verify 3 , +.Xr SSL_CTX_use_certificate 3 , +.Xr SSL_CTX_use_psk_identity_hint 3 , +.Xr SSL_do_handshake 3 , +.Xr SSL_get_ciphers 3 , +.Xr SSL_get_client_CA_list 3 , +.Xr SSL_get_default_timeout 3 , +.Xr SSL_get_error 3 , +.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , +.Xr SSL_get_ex_new_index 3 , +.Xr SSL_get_fd 3 , +.Xr SSL_get_peer_cert_chain 3 , +.Xr SSL_get_psk_identity 3 , +.Xr SSL_get_rbio 3 , +.Xr SSL_get_session 3 , +.Xr SSL_get_SSL_CTX 3 , +.Xr SSL_get_verify_result 3 , +.Xr SSL_get_version 3 , +.Xr SSL_library_init 3 , +.Xr SSL_load_client_CA_file 3 , +.Xr SSL_new 3 , +.Xr SSL_pending 3 , +.Xr SSL_read 3 , +.Xr SSL_rstate_string 3 , +.Xr SSL_SESSION_free 3 , +.Xr SSL_SESSION_get_ex_new_index 3 , +.Xr SSL_SESSION_get_time 3 , +.Xr SSL_session_reused 3 , +.Xr SSL_set_bio 3 , +.Xr SSL_set_connect_state 3 , +.Xr SSL_set_fd 3 , +.Xr SSL_set_session 3 , +.Xr SSL_set_shutdown 3 , +.Xr SSL_shutdown 3 , +.Xr SSL_state_string 3 , +.Xr SSL_want 3 , +.Xr SSL_write 3 +.Sh HISTORY +The +.Nm +document appeared in OpenSSL 0.9.2. -- cgit v1.2.3-55-g6feb