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/Makefile | 4 +- src/lib/libssl/doc/BIO_f_ssl.3 | 479 ------- src/lib/libssl/doc/Makefile | 93 -- src/lib/libssl/doc/SSL_CIPHER_get_name.3 | 196 --- .../libssl/doc/SSL_COMP_add_compression_method.3 | 68 - src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 | 45 - src/lib/libssl/doc/SSL_CTX_add_session.3 | 90 -- src/lib/libssl/doc/SSL_CTX_ctrl.3 | 49 - src/lib/libssl/doc/SSL_CTX_flush_sessions.3 | 57 - src/lib/libssl/doc/SSL_CTX_free.3 | 53 - src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 | 70 -- src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 | 73 -- src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 | 161 --- src/lib/libssl/doc/SSL_CTX_new.3 | 111 -- src/lib/libssl/doc/SSL_CTX_sess_number.3 | 104 -- src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 | 55 - src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 | 159 --- src/lib/libssl/doc/SSL_CTX_sessions.3 | 35 - src/lib/libssl/doc/SSL_CTX_set_cert_store.3 | 80 -- .../libssl/doc/SSL_CTX_set_cert_verify_callback.3 | 112 -- src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 | 82 -- src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 | 132 -- src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 | 143 --- src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 | 95 -- .../libssl/doc/SSL_CTX_set_generate_session_id.3 | 196 --- src/lib/libssl/doc/SSL_CTX_set_info_callback.3 | 167 --- src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 | 105 -- src/lib/libssl/doc/SSL_CTX_set_mode.3 | 126 -- src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 | 135 -- src/lib/libssl/doc/SSL_CTX_set_options.3 | 395 ------ .../libssl/doc/SSL_CTX_set_psk_client_callback.3 | 68 - src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 | 115 -- .../libssl/doc/SSL_CTX_set_session_cache_mode.3 | 143 --- .../libssl/doc/SSL_CTX_set_session_id_context.3 | 105 -- src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 | 81 -- src/lib/libssl/doc/SSL_CTX_set_timeout.3 | 65 - src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 | 235 ---- src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 | 231 ---- src/lib/libssl/doc/SSL_CTX_set_verify.3 | 415 ------ src/lib/libssl/doc/SSL_CTX_use_certificate.3 | 336 ----- src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 | 110 -- src/lib/libssl/doc/SSL_SESSION_free.3 | 84 -- src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 | 80 -- src/lib/libssl/doc/SSL_SESSION_get_time.3 | 98 -- src/lib/libssl/doc/SSL_accept.3 | 103 -- src/lib/libssl/doc/SSL_alert_type_string.3 | 193 --- src/lib/libssl/doc/SSL_clear.3 | 92 -- src/lib/libssl/doc/SSL_connect.3 | 102 -- src/lib/libssl/doc/SSL_do_handshake.3 | 101 -- src/lib/libssl/doc/SSL_free.3 | 67 - src/lib/libssl/doc/SSL_get_SSL_CTX.3 | 28 - src/lib/libssl/doc/SSL_get_ciphers.3 | 68 - src/lib/libssl/doc/SSL_get_client_CA_list.3 | 61 - src/lib/libssl/doc/SSL_get_current_cipher.3 | 52 - src/lib/libssl/doc/SSL_get_default_timeout.3 | 36 - src/lib/libssl/doc/SSL_get_error.3 | 169 --- .../doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 | 65 - src/lib/libssl/doc/SSL_get_ex_new_index.3 | 76 -- src/lib/libssl/doc/SSL_get_fd.3 | 46 - src/lib/libssl/doc/SSL_get_peer_cert_chain.3 | 47 - src/lib/libssl/doc/SSL_get_peer_certificate.3 | 53 - src/lib/libssl/doc/SSL_get_psk_identity.3 | 44 - src/lib/libssl/doc/SSL_get_rbio.3 | 45 - src/lib/libssl/doc/SSL_get_session.3 | 97 -- src/lib/libssl/doc/SSL_get_verify_result.3 | 49 - src/lib/libssl/doc/SSL_get_version.3 | 35 - src/lib/libssl/doc/SSL_library_init.3 | 54 - src/lib/libssl/doc/SSL_load_client_CA_file.3 | 53 - src/lib/libssl/doc/SSL_new.3 | 41 - src/lib/libssl/doc/SSL_pending.3 | 44 - src/lib/libssl/doc/SSL_read.3 | 193 --- src/lib/libssl/doc/SSL_rstate_string.3 | 55 - src/lib/libssl/doc/SSL_session_reused.3 | 32 - src/lib/libssl/doc/SSL_set_bio.3 | 51 - src/lib/libssl/doc/SSL_set_connect_state.3 | 71 -- src/lib/libssl/doc/SSL_set_fd.3 | 73 -- src/lib/libssl/doc/SSL_set_session.3 | 68 - src/lib/libssl/doc/SSL_set_shutdown.3 | 88 -- src/lib/libssl/doc/SSL_set_verify_result.3 | 42 - src/lib/libssl/doc/SSL_shutdown.3 | 204 --- src/lib/libssl/doc/SSL_state_string.3 | 57 - src/lib/libssl/doc/SSL_want.3 | 103 -- src/lib/libssl/doc/SSL_write.3 | 175 --- src/lib/libssl/doc/d2i_SSL_SESSION.3 | 129 -- src/lib/libssl/doc/ssl.3 | 1319 -------------------- 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 ++++++++++++++++++++ 169 files changed, 10315 insertions(+), 10315 deletions(-) delete mode 100644 src/lib/libssl/doc/BIO_f_ssl.3 delete mode 100644 src/lib/libssl/doc/Makefile delete mode 100644 src/lib/libssl/doc/SSL_CIPHER_get_name.3 delete mode 100644 src/lib/libssl/doc/SSL_COMP_add_compression_method.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_add_session.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_ctrl.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_flush_sessions.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_free.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_new.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_sess_number.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_sessions.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_cert_store.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_info_callback.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_mode.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_options.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_psk_client_callback.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_session_cache_mode.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_session_id_context.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_timeout.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_set_verify.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_use_certificate.3 delete mode 100644 src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 delete mode 100644 src/lib/libssl/doc/SSL_SESSION_free.3 delete mode 100644 src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 delete mode 100644 src/lib/libssl/doc/SSL_SESSION_get_time.3 delete mode 100644 src/lib/libssl/doc/SSL_accept.3 delete mode 100644 src/lib/libssl/doc/SSL_alert_type_string.3 delete mode 100644 src/lib/libssl/doc/SSL_clear.3 delete mode 100644 src/lib/libssl/doc/SSL_connect.3 delete mode 100644 src/lib/libssl/doc/SSL_do_handshake.3 delete mode 100644 src/lib/libssl/doc/SSL_free.3 delete mode 100644 src/lib/libssl/doc/SSL_get_SSL_CTX.3 delete mode 100644 src/lib/libssl/doc/SSL_get_ciphers.3 delete mode 100644 src/lib/libssl/doc/SSL_get_client_CA_list.3 delete mode 100644 src/lib/libssl/doc/SSL_get_current_cipher.3 delete mode 100644 src/lib/libssl/doc/SSL_get_default_timeout.3 delete mode 100644 src/lib/libssl/doc/SSL_get_error.3 delete mode 100644 src/lib/libssl/doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 delete mode 100644 src/lib/libssl/doc/SSL_get_ex_new_index.3 delete mode 100644 src/lib/libssl/doc/SSL_get_fd.3 delete mode 100644 src/lib/libssl/doc/SSL_get_peer_cert_chain.3 delete mode 100644 src/lib/libssl/doc/SSL_get_peer_certificate.3 delete mode 100644 src/lib/libssl/doc/SSL_get_psk_identity.3 delete mode 100644 src/lib/libssl/doc/SSL_get_rbio.3 delete mode 100644 src/lib/libssl/doc/SSL_get_session.3 delete mode 100644 src/lib/libssl/doc/SSL_get_verify_result.3 delete mode 100644 src/lib/libssl/doc/SSL_get_version.3 delete mode 100644 src/lib/libssl/doc/SSL_library_init.3 delete mode 100644 src/lib/libssl/doc/SSL_load_client_CA_file.3 delete mode 100644 src/lib/libssl/doc/SSL_new.3 delete mode 100644 src/lib/libssl/doc/SSL_pending.3 delete mode 100644 src/lib/libssl/doc/SSL_read.3 delete mode 100644 src/lib/libssl/doc/SSL_rstate_string.3 delete mode 100644 src/lib/libssl/doc/SSL_session_reused.3 delete mode 100644 src/lib/libssl/doc/SSL_set_bio.3 delete mode 100644 src/lib/libssl/doc/SSL_set_connect_state.3 delete mode 100644 src/lib/libssl/doc/SSL_set_fd.3 delete mode 100644 src/lib/libssl/doc/SSL_set_session.3 delete mode 100644 src/lib/libssl/doc/SSL_set_shutdown.3 delete mode 100644 src/lib/libssl/doc/SSL_set_verify_result.3 delete mode 100644 src/lib/libssl/doc/SSL_shutdown.3 delete mode 100644 src/lib/libssl/doc/SSL_state_string.3 delete mode 100644 src/lib/libssl/doc/SSL_want.3 delete mode 100644 src/lib/libssl/doc/SSL_write.3 delete mode 100644 src/lib/libssl/doc/d2i_SSL_SESSION.3 delete mode 100644 src/lib/libssl/doc/ssl.3 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') diff --git a/src/lib/libssl/Makefile b/src/lib/libssl/Makefile index 01d7f04036..2e90b02054 100644 --- a/src/lib/libssl/Makefile +++ b/src/lib/libssl/Makefile @@ -1,8 +1,8 @@ -# $OpenBSD: Makefile,v 1.26 2016/11/05 15:01:54 schwarze Exp $ +# $OpenBSD: Makefile,v 1.27 2016/11/05 15:32:19 schwarze Exp $ .include .ifndef NOMAN -SUBDIR= doc +SUBDIR= man .endif PC_FILES=openssl.pc libssl.pc diff --git a/src/lib/libssl/doc/BIO_f_ssl.3 b/src/lib/libssl/doc/BIO_f_ssl.3 deleted file mode 100644 index f70b6c1e23..0000000000 --- a/src/lib/libssl/doc/BIO_f_ssl.3 +++ /dev/null @@ -1,479 +0,0 @@ -.\" -.\" $OpenBSD: BIO_f_ssl.3,v 1.4 2015/11/11 22:14:40 jmc Exp $ -.\" -.Dd $Mdocdate: November 11 2015 $ -.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/doc/Makefile b/src/lib/libssl/doc/Makefile deleted file mode 100644 index dfe4e7b3cb..0000000000 --- a/src/lib/libssl/doc/Makefile +++ /dev/null @@ -1,93 +0,0 @@ -# $OpenBSD: Makefile,v 1.1 2016/11/05 15:01:54 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/doc/SSL_CIPHER_get_name.3 b/src/lib/libssl/doc/SSL_CIPHER_get_name.3 deleted file mode 100644 index ebc478f9c6..0000000000 --- a/src/lib/libssl/doc/SSL_CIPHER_get_name.3 +++ /dev/null @@ -1,196 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_COMP_add_compression_method.3 b/src/lib/libssl/doc/SSL_COMP_add_compression_method.3 deleted file mode 100644 index d683574dd3..0000000000 --- a/src/lib/libssl/doc/SSL_COMP_add_compression_method.3 +++ /dev/null @@ -1,68 +0,0 @@ -.\" -.\" $OpenBSD: SSL_COMP_add_compression_method.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_add_extra_chain_cert.3 b/src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 deleted file mode 100644 index c18d220643..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 +++ /dev/null @@ -1,45 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_add_extra_chain_cert.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_add_session.3 b/src/lib/libssl/doc/SSL_CTX_add_session.3 deleted file mode 100644 index 073b919dc1..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_add_session.3 +++ /dev/null @@ -1,90 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_add_session.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_ctrl.3 b/src/lib/libssl/doc/SSL_CTX_ctrl.3 deleted file mode 100644 index a016845585..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_ctrl.3 +++ /dev/null @@ -1,49 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_ctrl.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_flush_sessions.3 b/src/lib/libssl/doc/SSL_CTX_flush_sessions.3 deleted file mode 100644 index 9d3c52cdd5..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_flush_sessions.3 +++ /dev/null @@ -1,57 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_flush_sessions.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_free.3 b/src/lib/libssl/doc/SSL_CTX_free.3 deleted file mode 100644 index 84f5eb57ee..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_free.3 +++ /dev/null @@ -1,53 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_free.3,v 1.3 2015/12/30 18:45:02 millert Exp $ -.\" -.Dd $Mdocdate: December 30 2015 $ -.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/doc/SSL_CTX_get_ex_new_index.3 b/src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 deleted file mode 100644 index 18e41dd7d2..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 +++ /dev/null @@ -1,70 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_get_ex_new_index.3,v 1.3 2015/09/14 15:51:20 schwarze Exp $ -.\" -.Dd $Mdocdate: September 14 2015 $ -.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/doc/SSL_CTX_get_verify_mode.3 b/src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 deleted file mode 100644 index 12e21db6a3..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 +++ /dev/null @@ -1,73 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_get_verify_mode.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_load_verify_locations.3 b/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 deleted file mode 100644 index 09884db5da..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 +++ /dev/null @@ -1,161 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_load_verify_locations.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_new.3 b/src/lib/libssl/doc/SSL_CTX_new.3 deleted file mode 100644 index d2c2b03452..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_new.3 +++ /dev/null @@ -1,111 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_new.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_sess_number.3 b/src/lib/libssl/doc/SSL_CTX_sess_number.3 deleted file mode 100644 index f3af4eab07..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_sess_number.3 +++ /dev/null @@ -1,104 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_sess_number.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_sess_set_cache_size.3 b/src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 deleted file mode 100644 index 89d02dd32b..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 +++ /dev/null @@ -1,55 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_sess_set_cache_size.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_sess_set_get_cb.3 b/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 deleted file mode 100644 index 7a372138c1..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 +++ /dev/null @@ -1,159 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_sess_set_get_cb.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_sessions.3 b/src/lib/libssl/doc/SSL_CTX_sessions.3 deleted file mode 100644 index 23d9edb6e2..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_sessions.3 +++ /dev/null @@ -1,35 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_sessions.3,v 1.3 2015/11/15 22:02:10 jmc Exp $ -.\" -.Dd $Mdocdate: November 15 2015 $ -.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/doc/SSL_CTX_set_cert_store.3 b/src/lib/libssl/doc/SSL_CTX_set_cert_store.3 deleted file mode 100644 index 8ef3c5561e..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_cert_store.3 +++ /dev/null @@ -1,80 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_cert_store.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_cert_verify_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3 deleted file mode 100644 index bb242d6929..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3 +++ /dev/null @@ -1,112 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_cert_verify_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_cipher_list.3 b/src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 deleted file mode 100644 index e7ce24fb34..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 +++ /dev/null @@ -1,82 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_cipher_list.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_client_CA_list.3 b/src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 deleted file mode 100644 index 688c4ac023..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 +++ /dev/null @@ -1,132 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_client_CA_list.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_client_cert_cb.3 b/src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 deleted file mode 100644 index 7a7d9466d2..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 +++ /dev/null @@ -1,143 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_client_cert_cb.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_default_passwd_cb.3 b/src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 deleted file mode 100644 index ac4d55ae73..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 +++ /dev/null @@ -1,95 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_generate_session_id.3 b/src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 deleted file mode 100644 index 0bea48904e..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 +++ /dev/null @@ -1,196 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_generate_session_id.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_info_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_info_callback.3 deleted file mode 100644 index 24ee74dda9..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_info_callback.3 +++ /dev/null @@ -1,167 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_info_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_max_cert_list.3 b/src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 deleted file mode 100644 index e82f7b14a0..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 +++ /dev/null @@ -1,105 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_max_cert_list.3,v 1.3 2016/03/10 23:21:46 mmcc Exp $ -.\" -.Dd $Mdocdate: March 10 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/doc/SSL_CTX_set_mode.3 b/src/lib/libssl/doc/SSL_CTX_set_mode.3 deleted file mode 100644 index 2a3fcd5531..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_mode.3 +++ /dev/null @@ -1,126 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_mode.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_msg_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 deleted file mode 100644 index c72f37ccd9..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 +++ /dev/null @@ -1,135 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_msg_callback.3,v 1.3 2015/11/11 22:14:40 jmc Exp $ -.\" -.Dd $Mdocdate: November 11 2015 $ -.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/doc/SSL_CTX_set_options.3 b/src/lib/libssl/doc/SSL_CTX_set_options.3 deleted file mode 100644 index 852553e97f..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_options.3 +++ /dev/null @@ -1,395 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_options.3,v 1.10 2015/07/18 19:41:54 doug Exp $ -.\" -.Dd $Mdocdate: July 18 2015 $ -.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/doc/SSL_CTX_set_psk_client_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_psk_client_callback.3 deleted file mode 100644 index 40504ce59a..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_psk_client_callback.3 +++ /dev/null @@ -1,68 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_psk_client_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_quiet_shutdown.3 b/src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 deleted file mode 100644 index 5cad447318..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 +++ /dev/null @@ -1,115 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_quiet_shutdown.3,v 1.3 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_session_cache_mode.3 b/src/lib/libssl/doc/SSL_CTX_set_session_cache_mode.3 deleted file mode 100644 index a4e147f05a..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_session_cache_mode.3 +++ /dev/null @@ -1,143 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_session_cache_mode.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_session_id_context.3 b/src/lib/libssl/doc/SSL_CTX_set_session_id_context.3 deleted file mode 100644 index c8132a910c..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_session_id_context.3 +++ /dev/null @@ -1,105 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_session_id_context.3,v 1.3 2015/09/14 15:51:20 schwarze Exp $ -.\" -.Dd $Mdocdate: September 14 2015 $ -.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/doc/SSL_CTX_set_ssl_version.3 b/src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 deleted file mode 100644 index f4bd74e73b..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 +++ /dev/null @@ -1,81 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_ssl_version.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_timeout.3 b/src/lib/libssl/doc/SSL_CTX_set_timeout.3 deleted file mode 100644 index 6454c4616f..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_timeout.3 +++ /dev/null @@ -1,65 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_timeout.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_tmp_dh_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 deleted file mode 100644 index 17eed868ee..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 +++ /dev/null @@ -1,235 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_tmp_dh_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_tmp_rsa_callback.3 b/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 deleted file mode 100644 index 253274d122..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 +++ /dev/null @@ -1,231 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_tmp_rsa_callback.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_set_verify.3 b/src/lib/libssl/doc/SSL_CTX_set_verify.3 deleted file mode 100644 index 9292f2086b..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_set_verify.3 +++ /dev/null @@ -1,415 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_verify.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_CTX_use_certificate.3 b/src/lib/libssl/doc/SSL_CTX_use_certificate.3 deleted file mode 100644 index 6282c3b0d7..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_use_certificate.3 +++ /dev/null @@ -1,336 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_use_certificate.3,v 1.3 2015/02/06 01:37:11 reyk Exp $ -.\" -.Dd $Mdocdate: February 6 2015 $ -.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/doc/SSL_CTX_use_psk_identity_hint.3 b/src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 deleted file mode 100644 index 00c92b51ab..0000000000 --- a/src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 +++ /dev/null @@ -1,110 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_use_psk_identity_hint.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_SESSION_free.3 b/src/lib/libssl/doc/SSL_SESSION_free.3 deleted file mode 100644 index 69491f714b..0000000000 --- a/src/lib/libssl/doc/SSL_SESSION_free.3 +++ /dev/null @@ -1,84 +0,0 @@ -.\" -.\" $OpenBSD: SSL_SESSION_free.3,v 1.3 2015/12/30 18:45:02 millert Exp $ -.\" -.Dd $Mdocdate: December 30 2015 $ -.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/doc/SSL_SESSION_get_ex_new_index.3 b/src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 deleted file mode 100644 index a31f519506..0000000000 --- a/src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 +++ /dev/null @@ -1,80 +0,0 @@ -.\" -.\" $OpenBSD: SSL_SESSION_get_ex_new_index.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_SESSION_get_time.3 b/src/lib/libssl/doc/SSL_SESSION_get_time.3 deleted file mode 100644 index e906b5ad67..0000000000 --- a/src/lib/libssl/doc/SSL_SESSION_get_time.3 +++ /dev/null @@ -1,98 +0,0 @@ -.\" -.\" $OpenBSD: SSL_SESSION_get_time.3,v 1.3 2015/11/11 22:14:40 jmc Exp $ -.\" -.Dd $Mdocdate: November 11 2015 $ -.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/doc/SSL_accept.3 b/src/lib/libssl/doc/SSL_accept.3 deleted file mode 100644 index 8c7409d04f..0000000000 --- a/src/lib/libssl/doc/SSL_accept.3 +++ /dev/null @@ -1,103 +0,0 @@ -.\" -.\" $OpenBSD: SSL_accept.3,v 1.3 2015/06/18 22:51:05 doug Exp $ -.\" -.Dd $Mdocdate: June 18 2015 $ -.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/doc/SSL_alert_type_string.3 b/src/lib/libssl/doc/SSL_alert_type_string.3 deleted file mode 100644 index 10c947dae9..0000000000 --- a/src/lib/libssl/doc/SSL_alert_type_string.3 +++ /dev/null @@ -1,193 +0,0 @@ -.\" -.\" $OpenBSD: SSL_alert_type_string.3,v 1.3 2015/09/14 15:58:48 schwarze Exp $ -.\" -.Dd $Mdocdate: September 14 2015 $ -.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/doc/SSL_clear.3 b/src/lib/libssl/doc/SSL_clear.3 deleted file mode 100644 index 8d49a840ca..0000000000 --- a/src/lib/libssl/doc/SSL_clear.3 +++ /dev/null @@ -1,92 +0,0 @@ -.\" -.\" $OpenBSD: SSL_clear.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_connect.3 b/src/lib/libssl/doc/SSL_connect.3 deleted file mode 100644 index 105e0ed923..0000000000 --- a/src/lib/libssl/doc/SSL_connect.3 +++ /dev/null @@ -1,102 +0,0 @@ -.\" -.\" $OpenBSD: SSL_connect.3,v 1.3 2015/07/24 15:25:08 jmc Exp $ -.\" -.Dd $Mdocdate: July 24 2015 $ -.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/doc/SSL_do_handshake.3 b/src/lib/libssl/doc/SSL_do_handshake.3 deleted file mode 100644 index 78a37b08c9..0000000000 --- a/src/lib/libssl/doc/SSL_do_handshake.3 +++ /dev/null @@ -1,101 +0,0 @@ -.\" -.\" $OpenBSD: SSL_do_handshake.3,v 1.3 2015/06/18 22:51:05 doug Exp $ -.\" -.Dd $Mdocdate: June 18 2015 $ -.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/doc/SSL_free.3 b/src/lib/libssl/doc/SSL_free.3 deleted file mode 100644 index 1a3711e6c7..0000000000 --- a/src/lib/libssl/doc/SSL_free.3 +++ /dev/null @@ -1,67 +0,0 @@ -.\" -.\" $OpenBSD: SSL_free.3,v 1.3 2015/12/30 18:45:02 millert Exp $ -.\" -.Dd $Mdocdate: December 30 2015 $ -.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/doc/SSL_get_SSL_CTX.3 b/src/lib/libssl/doc/SSL_get_SSL_CTX.3 deleted file mode 100644 index 7ba5b0cb81..0000000000 --- a/src/lib/libssl/doc/SSL_get_SSL_CTX.3 +++ /dev/null @@ -1,28 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_SSL_CTX.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_ciphers.3 b/src/lib/libssl/doc/SSL_get_ciphers.3 deleted file mode 100644 index 89abc172b4..0000000000 --- a/src/lib/libssl/doc/SSL_get_ciphers.3 +++ /dev/null @@ -1,68 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_ciphers.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_client_CA_list.3 b/src/lib/libssl/doc/SSL_get_client_CA_list.3 deleted file mode 100644 index 7aa5a90c9a..0000000000 --- a/src/lib/libssl/doc/SSL_get_client_CA_list.3 +++ /dev/null @@ -1,61 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_client_CA_list.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_current_cipher.3 b/src/lib/libssl/doc/SSL_get_current_cipher.3 deleted file mode 100644 index d7140571b0..0000000000 --- a/src/lib/libssl/doc/SSL_get_current_cipher.3 +++ /dev/null @@ -1,52 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_current_cipher.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_default_timeout.3 b/src/lib/libssl/doc/SSL_get_default_timeout.3 deleted file mode 100644 index 1a58e87f27..0000000000 --- a/src/lib/libssl/doc/SSL_get_default_timeout.3 +++ /dev/null @@ -1,36 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_default_timeout.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_error.3 b/src/lib/libssl/doc/SSL_get_error.3 deleted file mode 100644 index f6e5045b01..0000000000 --- a/src/lib/libssl/doc/SSL_get_error.3 +++ /dev/null @@ -1,169 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_error.3,v 1.3 2015/07/24 15:25:08 jmc Exp $ -.\" -.Dd $Mdocdate: July 24 2015 $ -.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/doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 b/src/lib/libssl/doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 deleted file mode 100644 index ac8a27c952..0000000000 --- a/src/lib/libssl/doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 +++ /dev/null @@ -1,65 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_ex_data_X509_STORE_CTX_idx.3,v 1.3 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_ex_new_index.3 b/src/lib/libssl/doc/SSL_get_ex_new_index.3 deleted file mode 100644 index d4613a6210..0000000000 --- a/src/lib/libssl/doc/SSL_get_ex_new_index.3 +++ /dev/null @@ -1,76 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_ex_new_index.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_fd.3 b/src/lib/libssl/doc/SSL_get_fd.3 deleted file mode 100644 index b66b5f1044..0000000000 --- a/src/lib/libssl/doc/SSL_get_fd.3 +++ /dev/null @@ -1,46 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_fd.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_peer_cert_chain.3 b/src/lib/libssl/doc/SSL_get_peer_cert_chain.3 deleted file mode 100644 index e4faece5d0..0000000000 --- a/src/lib/libssl/doc/SSL_get_peer_cert_chain.3 +++ /dev/null @@ -1,47 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_peer_cert_chain.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_peer_certificate.3 b/src/lib/libssl/doc/SSL_get_peer_certificate.3 deleted file mode 100644 index bb32572356..0000000000 --- a/src/lib/libssl/doc/SSL_get_peer_certificate.3 +++ /dev/null @@ -1,53 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_peer_certificate.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_psk_identity.3 b/src/lib/libssl/doc/SSL_get_psk_identity.3 deleted file mode 100644 index 408555c0ee..0000000000 --- a/src/lib/libssl/doc/SSL_get_psk_identity.3 +++ /dev/null @@ -1,44 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_psk_identity.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_rbio.3 b/src/lib/libssl/doc/SSL_get_rbio.3 deleted file mode 100644 index 4455692eac..0000000000 --- a/src/lib/libssl/doc/SSL_get_rbio.3 +++ /dev/null @@ -1,45 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_rbio.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_session.3 b/src/lib/libssl/doc/SSL_get_session.3 deleted file mode 100644 index 435fe20956..0000000000 --- a/src/lib/libssl/doc/SSL_get_session.3 +++ /dev/null @@ -1,97 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_session.3,v 1.3 2014/12/04 18:27:10 schwarze Exp $ -.\" -.Dd $Mdocdate: December 4 2014 $ -.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/doc/SSL_get_verify_result.3 b/src/lib/libssl/doc/SSL_get_verify_result.3 deleted file mode 100644 index e89e3dea61..0000000000 --- a/src/lib/libssl/doc/SSL_get_verify_result.3 +++ /dev/null @@ -1,49 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_verify_result.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_get_version.3 b/src/lib/libssl/doc/SSL_get_version.3 deleted file mode 100644 index ecfd005f12..0000000000 --- a/src/lib/libssl/doc/SSL_get_version.3 +++ /dev/null @@ -1,35 +0,0 @@ -.\" -.\" $OpenBSD: SSL_get_version.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_library_init.3 b/src/lib/libssl/doc/SSL_library_init.3 deleted file mode 100644 index 0c84c5d9c9..0000000000 --- a/src/lib/libssl/doc/SSL_library_init.3 +++ /dev/null @@ -1,54 +0,0 @@ -.\" -.\" $OpenBSD: SSL_library_init.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_load_client_CA_file.3 b/src/lib/libssl/doc/SSL_load_client_CA_file.3 deleted file mode 100644 index d1f085583f..0000000000 --- a/src/lib/libssl/doc/SSL_load_client_CA_file.3 +++ /dev/null @@ -1,53 +0,0 @@ -.\" -.\" $OpenBSD: SSL_load_client_CA_file.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_new.3 b/src/lib/libssl/doc/SSL_new.3 deleted file mode 100644 index 884b51270b..0000000000 --- a/src/lib/libssl/doc/SSL_new.3 +++ /dev/null @@ -1,41 +0,0 @@ -.\" -.\" $OpenBSD: SSL_new.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_pending.3 b/src/lib/libssl/doc/SSL_pending.3 deleted file mode 100644 index 25ef4ea0ba..0000000000 --- a/src/lib/libssl/doc/SSL_pending.3 +++ /dev/null @@ -1,44 +0,0 @@ -.\" -.\" $OpenBSD: SSL_pending.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_read.3 b/src/lib/libssl/doc/SSL_read.3 deleted file mode 100644 index d6e5960958..0000000000 --- a/src/lib/libssl/doc/SSL_read.3 +++ /dev/null @@ -1,193 +0,0 @@ -.\" -.\" $OpenBSD: SSL_read.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_rstate_string.3 b/src/lib/libssl/doc/SSL_rstate_string.3 deleted file mode 100644 index 81d83e52a1..0000000000 --- a/src/lib/libssl/doc/SSL_rstate_string.3 +++ /dev/null @@ -1,55 +0,0 @@ -.\" -.\" $OpenBSD: SSL_rstate_string.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_session_reused.3 b/src/lib/libssl/doc/SSL_session_reused.3 deleted file mode 100644 index 6ea45f749b..0000000000 --- a/src/lib/libssl/doc/SSL_session_reused.3 +++ /dev/null @@ -1,32 +0,0 @@ -.\" -.\" $OpenBSD: SSL_session_reused.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_set_bio.3 b/src/lib/libssl/doc/SSL_set_bio.3 deleted file mode 100644 index 7e2611e000..0000000000 --- a/src/lib/libssl/doc/SSL_set_bio.3 +++ /dev/null @@ -1,51 +0,0 @@ -.\" -.\" $OpenBSD: SSL_set_bio.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_set_connect_state.3 b/src/lib/libssl/doc/SSL_set_connect_state.3 deleted file mode 100644 index 291d9ac177..0000000000 --- a/src/lib/libssl/doc/SSL_set_connect_state.3 +++ /dev/null @@ -1,71 +0,0 @@ -.\" -.\" $OpenBSD: SSL_set_connect_state.3,v 1.3 2015/11/11 22:14:40 jmc Exp $ -.\" -.Dd $Mdocdate: November 11 2015 $ -.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/doc/SSL_set_fd.3 b/src/lib/libssl/doc/SSL_set_fd.3 deleted file mode 100644 index 94e0c7614a..0000000000 --- a/src/lib/libssl/doc/SSL_set_fd.3 +++ /dev/null @@ -1,73 +0,0 @@ -.\" -.\" $OpenBSD: SSL_set_fd.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_set_session.3 b/src/lib/libssl/doc/SSL_set_session.3 deleted file mode 100644 index 8b4b78b6e2..0000000000 --- a/src/lib/libssl/doc/SSL_set_session.3 +++ /dev/null @@ -1,68 +0,0 @@ -.\" -.\" $OpenBSD: SSL_set_session.3,v 1.3 2015/09/14 15:14:55 schwarze Exp $ -.\" -.Dd $Mdocdate: September 14 2015 $ -.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/doc/SSL_set_shutdown.3 b/src/lib/libssl/doc/SSL_set_shutdown.3 deleted file mode 100644 index 546b52dad5..0000000000 --- a/src/lib/libssl/doc/SSL_set_shutdown.3 +++ /dev/null @@ -1,88 +0,0 @@ -.\" -.\" $OpenBSD: SSL_set_shutdown.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_set_verify_result.3 b/src/lib/libssl/doc/SSL_set_verify_result.3 deleted file mode 100644 index 9d5474d07a..0000000000 --- a/src/lib/libssl/doc/SSL_set_verify_result.3 +++ /dev/null @@ -1,42 +0,0 @@ -.\" -.\" $OpenBSD: SSL_set_verify_result.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_shutdown.3 b/src/lib/libssl/doc/SSL_shutdown.3 deleted file mode 100644 index 187e656fe3..0000000000 --- a/src/lib/libssl/doc/SSL_shutdown.3 +++ /dev/null @@ -1,204 +0,0 @@ -.\" -.\" $OpenBSD: SSL_shutdown.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_state_string.3 b/src/lib/libssl/doc/SSL_state_string.3 deleted file mode 100644 index e9a042a3ce..0000000000 --- a/src/lib/libssl/doc/SSL_state_string.3 +++ /dev/null @@ -1,57 +0,0 @@ -.\" -.\" $OpenBSD: SSL_state_string.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_want.3 b/src/lib/libssl/doc/SSL_want.3 deleted file mode 100644 index e9513c8793..0000000000 --- a/src/lib/libssl/doc/SSL_want.3 +++ /dev/null @@ -1,103 +0,0 @@ -.\" -.\" $OpenBSD: SSL_want.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/SSL_write.3 b/src/lib/libssl/doc/SSL_write.3 deleted file mode 100644 index f020b8b59c..0000000000 --- a/src/lib/libssl/doc/SSL_write.3 +++ /dev/null @@ -1,175 +0,0 @@ -.\" -.\" $OpenBSD: SSL_write.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/d2i_SSL_SESSION.3 b/src/lib/libssl/doc/d2i_SSL_SESSION.3 deleted file mode 100644 index ef8a36de79..0000000000 --- a/src/lib/libssl/doc/d2i_SSL_SESSION.3 +++ /dev/null @@ -1,129 +0,0 @@ -.\" -.\" $OpenBSD: d2i_SSL_SESSION.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.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/doc/ssl.3 b/src/lib/libssl/doc/ssl.3 deleted file mode 100644 index 7a76403bdc..0000000000 --- a/src/lib/libssl/doc/ssl.3 +++ /dev/null @@ -1,1319 +0,0 @@ -.\" -.\" $OpenBSD: ssl.3,v 1.4 2015/11/11 22:14:40 jmc Exp $ -.\" -.Dd $Mdocdate: November 11 2015 $ -.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. 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