From 82b7f378b6907ab315a6e50322d2a0a8794a0aa9 Mon Sep 17 00:00:00 2001 From: bentley <> Date: Sun, 12 Oct 2014 09:33:04 +0000 Subject: Convert libssl manpages from pod to mdoc(7). libcrypto has not been started yet. ok schwarze@ miod@ --- src/lib/libssl/doc/BIO_f_ssl.3 | 475 +++++++ src/lib/libssl/doc/SSL_CIPHER_get_name.3 | 193 +++ .../libssl/doc/SSL_COMP_add_compression_method.3 | 65 + src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 | 42 + src/lib/libssl/doc/SSL_CTX_add_session.3 | 87 ++ src/lib/libssl/doc/SSL_CTX_ctrl.3 | 46 + src/lib/libssl/doc/SSL_CTX_flush_sessions.3 | 54 + src/lib/libssl/doc/SSL_CTX_free.3 | 44 + src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 | 67 + src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 | 70 ++ src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 | 158 +++ src/lib/libssl/doc/SSL_CTX_new.3 | 108 ++ src/lib/libssl/doc/SSL_CTX_sess_number.3 | 101 ++ src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 | 52 + src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 | 156 +++ src/lib/libssl/doc/SSL_CTX_sessions.3 | 31 + src/lib/libssl/doc/SSL_CTX_set_cert_store.3 | 77 ++ .../libssl/doc/SSL_CTX_set_cert_verify_callback.3 | 109 ++ src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 | 79 ++ src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 | 129 ++ src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 | 140 +++ src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 | 92 ++ .../libssl/doc/SSL_CTX_set_generate_session_id.3 | 193 +++ src/lib/libssl/doc/SSL_CTX_set_info_callback.3 | 164 +++ src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 | 102 ++ src/lib/libssl/doc/SSL_CTX_set_mode.3 | 123 ++ src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 | 132 ++ src/lib/libssl/doc/SSL_CTX_set_options.3 | 384 ++++++ .../libssl/doc/SSL_CTX_set_psk_client_callback.3 | 65 + src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 | 116 ++ .../libssl/doc/SSL_CTX_set_session_cache_mode.3 | 140 +++ .../libssl/doc/SSL_CTX_set_session_id_context.3 | 102 ++ src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 | 78 ++ src/lib/libssl/doc/SSL_CTX_set_timeout.3 | 62 + src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 | 233 ++++ src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 | 228 ++++ src/lib/libssl/doc/SSL_CTX_set_verify.3 | 412 ++++++ src/lib/libssl/doc/SSL_CTX_use_certificate.3 | 333 +++++ src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 | 107 ++ src/lib/libssl/doc/SSL_SESSION_free.3 | 76 ++ src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 | 77 ++ src/lib/libssl/doc/SSL_SESSION_get_time.3 | 91 ++ src/lib/libssl/doc/SSL_accept.3 | 110 ++ src/lib/libssl/doc/SSL_alert_type_string.3 | 190 +++ src/lib/libssl/doc/SSL_clear.3 | 89 ++ src/lib/libssl/doc/SSL_connect.3 | 99 ++ src/lib/libssl/doc/SSL_do_handshake.3 | 110 ++ src/lib/libssl/doc/SSL_free.3 | 59 + src/lib/libssl/doc/SSL_get_SSL_CTX.3 | 25 + src/lib/libssl/doc/SSL_get_ciphers.3 | 65 + src/lib/libssl/doc/SSL_get_client_CA_list.3 | 58 + src/lib/libssl/doc/SSL_get_current_cipher.3 | 49 + src/lib/libssl/doc/SSL_get_default_timeout.3 | 33 + src/lib/libssl/doc/SSL_get_error.3 | 166 +++ .../doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 | 62 + src/lib/libssl/doc/SSL_get_ex_new_index.3 | 73 ++ src/lib/libssl/doc/SSL_get_fd.3 | 43 + src/lib/libssl/doc/SSL_get_peer_cert_chain.3 | 44 + src/lib/libssl/doc/SSL_get_peer_certificate.3 | 50 + src/lib/libssl/doc/SSL_get_psk_identity.3 | 41 + src/lib/libssl/doc/SSL_get_rbio.3 | 42 + src/lib/libssl/doc/SSL_get_session.3 | 94 ++ src/lib/libssl/doc/SSL_get_verify_result.3 | 46 + src/lib/libssl/doc/SSL_get_version.3 | 32 + src/lib/libssl/doc/SSL_library_init.3 | 51 + src/lib/libssl/doc/SSL_load_client_CA_file.3 | 50 + src/lib/libssl/doc/SSL_new.3 | 38 + src/lib/libssl/doc/SSL_pending.3 | 41 + src/lib/libssl/doc/SSL_read.3 | 190 +++ src/lib/libssl/doc/SSL_rstate_string.3 | 52 + src/lib/libssl/doc/SSL_session_reused.3 | 29 + src/lib/libssl/doc/SSL_set_bio.3 | 48 + src/lib/libssl/doc/SSL_set_connect_state.3 | 68 + src/lib/libssl/doc/SSL_set_fd.3 | 70 ++ src/lib/libssl/doc/SSL_set_session.3 | 65 + src/lib/libssl/doc/SSL_set_shutdown.3 | 85 ++ src/lib/libssl/doc/SSL_set_verify_result.3 | 39 + src/lib/libssl/doc/SSL_shutdown.3 | 201 +++ src/lib/libssl/doc/SSL_state_string.3 | 54 + src/lib/libssl/doc/SSL_want.3 | 100 ++ src/lib/libssl/doc/SSL_write.3 | 172 +++ src/lib/libssl/doc/d2i_SSL_SESSION.3 | 126 ++ src/lib/libssl/doc/ssl.3 | 1317 ++++++++++++++++++++ src/lib/libssl/src/doc/ssl/BIO_f_ssl.3 | 475 +++++++ src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod | 322 ----- src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.3 | 193 +++ src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.pod | 122 -- .../src/doc/ssl/SSL_COMP_add_compression_method.3 | 65 + .../doc/ssl/SSL_COMP_add_compression_method.pod | 70 -- .../src/doc/ssl/SSL_CTX_add_extra_chain_cert.3 | 42 + .../src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod | 43 - src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.3 | 87 ++ src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.pod | 74 -- src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.3 | 46 + src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod | 35 - .../libssl/src/doc/ssl/SSL_CTX_flush_sessions.3 | 54 + .../libssl/src/doc/ssl/SSL_CTX_flush_sessions.pod | 49 - src/lib/libssl/src/doc/ssl/SSL_CTX_free.3 | 44 + src/lib/libssl/src/doc/ssl/SSL_CTX_free.pod | 41 - .../libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.3 | 67 + .../src/doc/ssl/SSL_CTX_get_ex_new_index.pod | 54 - .../libssl/src/doc/ssl/SSL_CTX_get_verify_mode.3 | 70 ++ .../libssl/src/doc/ssl/SSL_CTX_get_verify_mode.pod | 52 - .../src/doc/ssl/SSL_CTX_load_verify_locations.3 | 158 +++ .../src/doc/ssl/SSL_CTX_load_verify_locations.pod | 137 -- src/lib/libssl/src/doc/ssl/SSL_CTX_new.3 | 108 ++ src/lib/libssl/src/doc/ssl/SSL_CTX_new.pod | 93 -- src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.3 | 101 ++ src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.pod | 80 -- .../src/doc/ssl/SSL_CTX_sess_set_cache_size.3 | 52 + .../src/doc/ssl/SSL_CTX_sess_set_cache_size.pod | 52 - .../libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.3 | 156 +++ .../libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod | 89 -- src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.3 | 31 + src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.pod | 34 - .../libssl/src/doc/ssl/SSL_CTX_set_cert_store.3 | 77 ++ .../libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod | 58 - .../src/doc/ssl/SSL_CTX_set_cert_verify_callback.3 | 109 ++ .../doc/ssl/SSL_CTX_set_cert_verify_callback.pod | 75 -- .../libssl/src/doc/ssl/SSL_CTX_set_cipher_list.3 | 79 ++ .../libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod | 71 -- .../src/doc/ssl/SSL_CTX_set_client_CA_list.3 | 129 ++ .../src/doc/ssl/SSL_CTX_set_client_CA_list.pod | 94 -- .../src/doc/ssl/SSL_CTX_set_client_cert_cb.3 | 140 +++ .../src/doc/ssl/SSL_CTX_set_client_cert_cb.pod | 95 -- .../src/doc/ssl/SSL_CTX_set_default_passwd_cb.3 | 92 ++ .../src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod | 77 -- .../src/doc/ssl/SSL_CTX_set_generate_session_id.3 | 193 +++ .../doc/ssl/SSL_CTX_set_generate_session_id.pod | 152 --- .../libssl/src/doc/ssl/SSL_CTX_set_info_callback.3 | 164 +++ .../src/doc/ssl/SSL_CTX_set_info_callback.pod | 154 --- .../libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.3 | 102 ++ .../src/doc/ssl/SSL_CTX_set_max_cert_list.pod | 78 -- src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.3 | 123 ++ src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod | 92 -- .../libssl/src/doc/ssl/SSL_CTX_set_msg_callback.3 | 132 ++ .../src/doc/ssl/SSL_CTX_set_msg_callback.pod | 101 -- src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.3 | 384 ++++++ src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod | 350 ------ .../src/doc/ssl/SSL_CTX_set_psk_client_callback.3 | 65 + .../doc/ssl/SSL_CTX_set_psk_client_callback.pod | 82 -- .../src/doc/ssl/SSL_CTX_set_quiet_shutdown.3 | 116 ++ .../src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod | 64 - .../src/doc/ssl/SSL_CTX_set_session_cache_mode.3 | 140 +++ .../src/doc/ssl/SSL_CTX_set_session_cache_mode.pod | 138 -- .../src/doc/ssl/SSL_CTX_set_session_id_context.3 | 102 ++ .../src/doc/ssl/SSL_CTX_set_session_id_context.pod | 84 -- .../libssl/src/doc/ssl/SSL_CTX_set_ssl_version.3 | 78 ++ .../libssl/src/doc/ssl/SSL_CTX_set_ssl_version.pod | 61 - src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.3 | 62 + src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod | 60 - .../src/doc/ssl/SSL_CTX_set_tmp_dh_callback.3 | 233 ++++ .../src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 169 --- .../src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.3 | 228 ++++ .../src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod | 168 --- src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 | 412 ++++++ src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod | 295 ----- .../libssl/src/doc/ssl/SSL_CTX_use_certificate.3 | 333 +++++ .../libssl/src/doc/ssl/SSL_CTX_use_certificate.pod | 180 --- .../src/doc/ssl/SSL_CTX_use_psk_identity_hint.3 | 107 ++ .../src/doc/ssl/SSL_CTX_use_psk_identity_hint.pod | 106 -- src/lib/libssl/src/doc/ssl/SSL_SESSION_free.3 | 76 ++ src/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod | 55 - .../src/doc/ssl/SSL_SESSION_get_ex_new_index.3 | 77 ++ .../src/doc/ssl/SSL_SESSION_get_ex_new_index.pod | 62 - src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.3 | 91 ++ .../libssl/src/doc/ssl/SSL_SESSION_get_time.pod | 66 - src/lib/libssl/src/doc/ssl/SSL_accept.3 | 110 ++ src/lib/libssl/src/doc/ssl/SSL_accept.pod | 76 -- src/lib/libssl/src/doc/ssl/SSL_alert_type_string.3 | 190 +++ .../libssl/src/doc/ssl/SSL_alert_type_string.pod | 234 ---- src/lib/libssl/src/doc/ssl/SSL_clear.3 | 89 ++ src/lib/libssl/src/doc/ssl/SSL_clear.pod | 77 -- src/lib/libssl/src/doc/ssl/SSL_connect.3 | 99 ++ src/lib/libssl/src/doc/ssl/SSL_connect.pod | 73 -- src/lib/libssl/src/doc/ssl/SSL_do_handshake.3 | 110 ++ src/lib/libssl/src/doc/ssl/SSL_do_handshake.pod | 75 -- src/lib/libssl/src/doc/ssl/SSL_free.3 | 59 + src/lib/libssl/src/doc/ssl/SSL_free.pod | 46 - src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.3 | 25 + src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod | 26 - src/lib/libssl/src/doc/ssl/SSL_get_ciphers.3 | 65 + src/lib/libssl/src/doc/ssl/SSL_get_ciphers.pod | 42 - .../libssl/src/doc/ssl/SSL_get_client_CA_list.3 | 58 + .../libssl/src/doc/ssl/SSL_get_client_CA_list.pod | 53 - .../libssl/src/doc/ssl/SSL_get_current_cipher.3 | 49 + .../libssl/src/doc/ssl/SSL_get_current_cipher.pod | 43 - .../libssl/src/doc/ssl/SSL_get_default_timeout.3 | 33 + .../libssl/src/doc/ssl/SSL_get_default_timeout.pod | 41 - src/lib/libssl/src/doc/ssl/SSL_get_error.3 | 166 +++ src/lib/libssl/src/doc/ssl/SSL_get_error.pod | 113 -- .../doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.3 | 62 + .../doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod | 61 - src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.3 | 73 ++ .../libssl/src/doc/ssl/SSL_get_ex_new_index.pod | 60 - src/lib/libssl/src/doc/ssl/SSL_get_fd.3 | 43 + src/lib/libssl/src/doc/ssl/SSL_get_fd.pod | 44 - .../libssl/src/doc/ssl/SSL_get_peer_cert_chain.3 | 44 + .../libssl/src/doc/ssl/SSL_get_peer_cert_chain.pod | 52 - .../libssl/src/doc/ssl/SSL_get_peer_certificate.3 | 50 + .../src/doc/ssl/SSL_get_peer_certificate.pod | 55 - src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.3 | 41 + .../libssl/src/doc/ssl/SSL_get_psk_identity.pod | 64 - src/lib/libssl/src/doc/ssl/SSL_get_rbio.3 | 42 + src/lib/libssl/src/doc/ssl/SSL_get_rbio.pod | 40 - src/lib/libssl/src/doc/ssl/SSL_get_session.3 | 94 ++ src/lib/libssl/src/doc/ssl/SSL_get_session.pod | 73 -- src/lib/libssl/src/doc/ssl/SSL_get_verify_result.3 | 46 + .../libssl/src/doc/ssl/SSL_get_verify_result.pod | 57 - src/lib/libssl/src/doc/ssl/SSL_get_version.3 | 32 + src/lib/libssl/src/doc/ssl/SSL_get_version.pod | 54 - src/lib/libssl/src/doc/ssl/SSL_library_init.3 | 51 + src/lib/libssl/src/doc/ssl/SSL_library_init.pod | 57 - .../libssl/src/doc/ssl/SSL_load_client_CA_file.3 | 50 + .../libssl/src/doc/ssl/SSL_load_client_CA_file.pod | 62 - src/lib/libssl/src/doc/ssl/SSL_new.3 | 38 + src/lib/libssl/src/doc/ssl/SSL_new.pod | 44 - src/lib/libssl/src/doc/ssl/SSL_pending.3 | 41 + src/lib/libssl/src/doc/ssl/SSL_pending.pod | 43 - src/lib/libssl/src/doc/ssl/SSL_read.3 | 190 +++ src/lib/libssl/src/doc/ssl/SSL_read.pod | 124 -- src/lib/libssl/src/doc/ssl/SSL_rstate_string.3 | 52 + src/lib/libssl/src/doc/ssl/SSL_rstate_string.pod | 60 - src/lib/libssl/src/doc/ssl/SSL_session_reused.3 | 29 + src/lib/libssl/src/doc/ssl/SSL_session_reused.pod | 46 - src/lib/libssl/src/doc/ssl/SSL_set_bio.3 | 48 + src/lib/libssl/src/doc/ssl/SSL_set_bio.pod | 34 - src/lib/libssl/src/doc/ssl/SSL_set_connect_state.3 | 68 + .../libssl/src/doc/ssl/SSL_set_connect_state.pod | 56 - src/lib/libssl/src/doc/ssl/SSL_set_fd.3 | 70 ++ src/lib/libssl/src/doc/ssl/SSL_set_fd.pod | 54 - src/lib/libssl/src/doc/ssl/SSL_set_session.3 | 65 + src/lib/libssl/src/doc/ssl/SSL_set_session.pod | 57 - src/lib/libssl/src/doc/ssl/SSL_set_shutdown.3 | 85 ++ src/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod | 73 -- src/lib/libssl/src/doc/ssl/SSL_set_verify_result.3 | 39 + .../libssl/src/doc/ssl/SSL_set_verify_result.pod | 38 - src/lib/libssl/src/doc/ssl/SSL_shutdown.3 | 201 +++ src/lib/libssl/src/doc/ssl/SSL_shutdown.pod | 125 -- src/lib/libssl/src/doc/ssl/SSL_state_string.3 | 54 + src/lib/libssl/src/doc/ssl/SSL_state_string.pod | 46 - src/lib/libssl/src/doc/ssl/SSL_want.3 | 100 ++ src/lib/libssl/src/doc/ssl/SSL_want.pod | 78 -- src/lib/libssl/src/doc/ssl/SSL_write.3 | 172 +++ src/lib/libssl/src/doc/ssl/SSL_write.pod | 109 -- src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.3 | 126 ++ src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod | 80 -- src/lib/libssl/src/doc/ssl/ssl.3 | 1317 ++++++++++++++++++++ src/lib/libssl/src/doc/ssl/ssl.pod | 758 ----------- 249 files changed, 19938 insertions(+), 7737 deletions(-) create mode 100644 src/lib/libssl/doc/BIO_f_ssl.3 create mode 100644 src/lib/libssl/doc/SSL_CIPHER_get_name.3 create mode 100644 src/lib/libssl/doc/SSL_COMP_add_compression_method.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_add_session.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_ctrl.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_flush_sessions.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_free.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_new.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_sess_number.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_sessions.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_cert_store.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_info_callback.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_mode.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_options.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_psk_client_callback.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_session_cache_mode.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_session_id_context.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_timeout.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_set_verify.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_use_certificate.3 create mode 100644 src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 create mode 100644 src/lib/libssl/doc/SSL_SESSION_free.3 create mode 100644 src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 create mode 100644 src/lib/libssl/doc/SSL_SESSION_get_time.3 create mode 100644 src/lib/libssl/doc/SSL_accept.3 create mode 100644 src/lib/libssl/doc/SSL_alert_type_string.3 create mode 100644 src/lib/libssl/doc/SSL_clear.3 create mode 100644 src/lib/libssl/doc/SSL_connect.3 create mode 100644 src/lib/libssl/doc/SSL_do_handshake.3 create mode 100644 src/lib/libssl/doc/SSL_free.3 create mode 100644 src/lib/libssl/doc/SSL_get_SSL_CTX.3 create mode 100644 src/lib/libssl/doc/SSL_get_ciphers.3 create mode 100644 src/lib/libssl/doc/SSL_get_client_CA_list.3 create mode 100644 src/lib/libssl/doc/SSL_get_current_cipher.3 create mode 100644 src/lib/libssl/doc/SSL_get_default_timeout.3 create mode 100644 src/lib/libssl/doc/SSL_get_error.3 create mode 100644 src/lib/libssl/doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 create mode 100644 src/lib/libssl/doc/SSL_get_ex_new_index.3 create mode 100644 src/lib/libssl/doc/SSL_get_fd.3 create mode 100644 src/lib/libssl/doc/SSL_get_peer_cert_chain.3 create mode 100644 src/lib/libssl/doc/SSL_get_peer_certificate.3 create mode 100644 src/lib/libssl/doc/SSL_get_psk_identity.3 create mode 100644 src/lib/libssl/doc/SSL_get_rbio.3 create mode 100644 src/lib/libssl/doc/SSL_get_session.3 create mode 100644 src/lib/libssl/doc/SSL_get_verify_result.3 create mode 100644 src/lib/libssl/doc/SSL_get_version.3 create mode 100644 src/lib/libssl/doc/SSL_library_init.3 create mode 100644 src/lib/libssl/doc/SSL_load_client_CA_file.3 create mode 100644 src/lib/libssl/doc/SSL_new.3 create mode 100644 src/lib/libssl/doc/SSL_pending.3 create mode 100644 src/lib/libssl/doc/SSL_read.3 create mode 100644 src/lib/libssl/doc/SSL_rstate_string.3 create mode 100644 src/lib/libssl/doc/SSL_session_reused.3 create mode 100644 src/lib/libssl/doc/SSL_set_bio.3 create mode 100644 src/lib/libssl/doc/SSL_set_connect_state.3 create mode 100644 src/lib/libssl/doc/SSL_set_fd.3 create mode 100644 src/lib/libssl/doc/SSL_set_session.3 create mode 100644 src/lib/libssl/doc/SSL_set_shutdown.3 create mode 100644 src/lib/libssl/doc/SSL_set_verify_result.3 create mode 100644 src/lib/libssl/doc/SSL_shutdown.3 create mode 100644 src/lib/libssl/doc/SSL_state_string.3 create mode 100644 src/lib/libssl/doc/SSL_want.3 create mode 100644 src/lib/libssl/doc/SSL_write.3 create mode 100644 src/lib/libssl/doc/d2i_SSL_SESSION.3 create mode 100644 src/lib/libssl/doc/ssl.3 create mode 100644 src/lib/libssl/src/doc/ssl/BIO_f_ssl.3 delete mode 100644 src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_free.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_free.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_new.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_new.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_SESSION_free.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_accept.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_accept.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_alert_type_string.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_alert_type_string.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_clear.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_clear.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_connect.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_connect.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_do_handshake.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_do_handshake.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_free.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_free.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_ciphers.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_ciphers.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_error.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_error.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_fd.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_fd.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_rbio.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_rbio.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_session.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_session.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_verify_result.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_verify_result.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_version.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_get_version.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_library_init.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_library_init.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_new.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_new.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_pending.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_pending.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_read.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_read.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_rstate_string.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_rstate_string.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_session_reused.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_session_reused.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_bio.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_bio.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_connect_state.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_fd.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_fd.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_session.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_session.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_shutdown.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_verify_result.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_set_verify_result.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_shutdown.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_shutdown.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_state_string.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_state_string.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_want.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_want.pod create mode 100644 src/lib/libssl/src/doc/ssl/SSL_write.3 delete mode 100644 src/lib/libssl/src/doc/ssl/SSL_write.pod create mode 100644 src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.3 delete mode 100644 src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod create mode 100644 src/lib/libssl/src/doc/ssl/ssl.3 delete mode 100644 src/lib/libssl/src/doc/ssl/ssl.pod diff --git a/src/lib/libssl/doc/BIO_f_ssl.3 b/src/lib/libssl/doc/BIO_f_ssl.3 new file mode 100644 index 0000000000..31c9963edb --- /dev/null +++ b/src/lib/libssl/doc/BIO_f_ssl.3 @@ -0,0 +1,475 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.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 SGC or 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 EXAMPLE +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/SSL_CIPHER_get_name.3 b/src/lib/libssl/doc/SSL_CIPHER_get_name.3 new file mode 100644 index 0000000000..0c6cccd1cc --- /dev/null +++ b/src/lib/libssl/doc/SSL_CIPHER_get_name.3 @@ -0,0 +1,193 @@ +.Dd $Mdocdate: October 12 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 ciphers 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 new file mode 100644 index 0000000000..c23d676930 --- /dev/null +++ b/src/lib/libssl/doc/SSL_COMP_add_compression_method.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..2664c67a5a --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_add_extra_chain_cert.3 @@ -0,0 +1,42 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..74b4481496 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_add_session.3 @@ -0,0 +1,87 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..d0a4ffd554 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_ctrl.3 @@ -0,0 +1,46 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..6431008c4f --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_flush_sessions.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..9cf5934303 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_free.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: October 12 2014 $ +.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. +.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 new file mode 100644 index 0000000000..593f39c24c --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_get_ex_new_index.3 @@ -0,0 +1,67 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 new file mode 100644 index 0000000000..4139229d7b --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_get_verify_mode.3 @@ -0,0 +1,70 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..1e494032f4 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_load_verify_locations.3 @@ -0,0 +1,158 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..b798d10a9e --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_new.3 @@ -0,0 +1,108 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..862576ca50 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_sess_number.3 @@ -0,0 +1,101 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..ad434e8496 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_sess_set_cache_size.3 @@ -0,0 +1,52 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..d5c506cec8 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_sess_set_get_cb.3 @@ -0,0 +1,156 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..96aa018289 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_sessions.3 @@ -0,0 +1,31 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.Xr lhash 3 +type database. +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 +.Xr lhash 3 +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 lhash 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 new file mode 100644 index 0000000000..f80670ce78 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_cert_store.3 @@ -0,0 +1,77 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..b34d3a6003 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_cert_verify_callback.3 @@ -0,0 +1,109 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..c3ee5304e3 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_cipher_list.3 @@ -0,0 +1,79 @@ +.Dd $Mdocdate: October 12 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 ciphers 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 new file mode 100644 index 0000000000..5d6fa9bea1 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_client_CA_list.3 @@ -0,0 +1,129 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..6aaa5f1016 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_client_cert_cb.3 @@ -0,0 +1,140 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..2c35ed501c --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 @@ -0,0 +1,92 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..e2e2a70362 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_generate_session_id.3 @@ -0,0 +1,193 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..dcf298addf --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_info_callback.3 @@ -0,0 +1,164 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..7380884867 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_max_cert_list.3 @@ -0,0 +1,102 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 http://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 new file mode 100644 index 0000000000..b980d43dbe --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_mode.3 @@ -0,0 +1,123 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..82c1479af0 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_msg_callback.3 @@ -0,0 +1,132 @@ +.Dd $Mdocdate: October 12 2014 $ +.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_get_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_get_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 new file mode 100644 index 0000000000..8b2f75cc59 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_options.3 @@ -0,0 +1,384 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.Lk www.microsoft.com +\(en when talking SSLv2, if session-id reuse is performed, +the session-id passed back in the server-finished message is different from the +one decided upon. +.It Dv SSL_OP_NETSCAPE_CHALLENGE_BUG +Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte challenge but +then appears to only use 16 bytes when generating the encryption keys. +Using 16 bytes is ok but it should be ok to use 32. +According to the SSLv3 spec, one should use 32 bytes for the challenge when +operating in SSLv2/v3 compatibility mode, but as mentioned above, this breaks +this server so 16 bytes is the way to go. +.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 +\&... +.It Dv SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER +\&... +.It Dv SSL_OP_SAFARI_ECDHE_ECDSA_BUG +Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. +OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. +.It Dv SSL_OP_SSLEAY_080_CLIENT_DH_BUG +\&... +.It Dv SSL_OP_TLS_D5_BUG +\&... +.It Dv SSL_OP_TLS_BLOCK_PADDING_BUG +\&... +.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 dhparam 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 +If we accept a netscape connection, demand a client cert, have a +non-self-signed CA which does not have its CA in netscape, and the browser has +a cert, it will crash/hang. +Works for 3.x and 4.xbeta +.It Dv SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG +\&... +.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 dhparam 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 new file mode 100644 index 0000000000..9bd5c9c545 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_psk_client_callback.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..91e17350f9 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_quiet_shutdown.3 @@ -0,0 +1,116 @@ +.Dd $Mdocdate: October 12 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 +.Pf | +.Dv SSL_RECEIVED_SHUTDOWN . +.Po +.Xr SSL_shutdown 3 +then behaves like +.Xr SSL_set_shutdown 3 +called with +.Dv SSL_SENT_SHUTDOWN Ns +.Pf | +.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 new file mode 100644 index 0000000000..e7ebe2190e --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_session_cache_mode.3 @@ -0,0 +1,140 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..0411c687a4 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_session_id_context.3 @@ -0,0 +1,102 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 new file mode 100644 index 0000000000..f3753dac20 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_ssl_version.3 @@ -0,0 +1,78 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..c8aaee24e2 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_timeout.3 @@ -0,0 +1,62 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..f28d083f45 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_tmp_dh_callback.3 @@ -0,0 +1,233 @@ +.Dd $Mdocdate: October 12 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 dhparam 1 +application. +In order to reduce the computer time needed for this generation, +it is possible to use DSA parameters instead (see +.Xr dhparam 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 dhparam 1 +application. +Authors may also generate their own set of parameters using +.Xr dhparam 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 ciphers 1 , +.Xr dhparam 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 new file mode 100644 index 0000000000..55b3aaafed --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_tmp_rsa_callback.3 @@ -0,0 +1,228 @@ +.Dd $Mdocdate: October 12 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 ciphers 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 new file mode 100644 index 0000000000..6ce2e60089 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_set_verify.3 @@ -0,0 +1,412 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..eac4d8e42c --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_use_certificate.3 @@ -0,0 +1,333 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 , +.Nm SSL_CTX_use_certificate_chain_file , +.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 "SSL_CTX *ctx" "void *buf" "int len" +.Ft int +.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file" +.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 new file mode 100644 index 0000000000..4d4e8a6173 --- /dev/null +++ b/src/lib/libssl/doc/SSL_CTX_use_psk_identity_hint.3 @@ -0,0 +1,107 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..f7d2350b55 --- /dev/null +++ b/src/lib/libssl/doc/SSL_SESSION_free.3 @@ -0,0 +1,76 @@ +.Dd $Mdocdate: October 12 2014 $ +.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. +.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 new file mode 100644 index 0000000000..d6a94cb0b7 --- /dev/null +++ b/src/lib/libssl/doc/SSL_SESSION_get_ex_new_index.3 @@ -0,0 +1,77 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..d094adb50a --- /dev/null +++ b/src/lib/libssl/doc/SSL_SESSION_get_time.3 @@ -0,0 +1,91 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.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 new file mode 100644 index 0000000000..88bea1fde7 --- /dev/null +++ b/src/lib/libssl/doc/SSL_accept.3 @@ -0,0 +1,110 @@ +.Dd $Mdocdate: October 12 2014 $ +.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, +except for SGC (Server Gated Cryptography). +For SGC, +.Fn SSL_accept +may return with \(mi1, but +.Fn SSL_get_error +will yield +.Dv SSL_ERROR_WANT_READ/WRITE +and +.Fn SSL_accept +should be called again. +.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 new file mode 100644 index 0000000000..f4b652bc1a --- /dev/null +++ b/src/lib/libssl/doc/SSL_alert_type_string.3 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 * Ns +.Fn SSL_alert_type_string "int value" +.Ft const char * Ns +.Fn SSL_alert_type_string_long "int value" +.Ft const char * Ns +.Fn SSL_alert_desc_string "int value" +.Ft const char * Ns +.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 new file mode 100644 index 0000000000..dc596ce12a --- /dev/null +++ b/src/lib/libssl/doc/SSL_clear.3 @@ -0,0 +1,89 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..4f8428c3c9 --- /dev/null +++ b/src/lib/libssl/doc/SSL_connect.3 @@ -0,0 +1,99 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL_CONNECT 3 +.Os +.Sh NAME +.Nm SSL_connect +.Nd initiate the TLS/SSL handshake with an 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 new file mode 100644 index 0000000000..8e6e0a820b --- /dev/null +++ b/src/lib/libssl/doc/SSL_do_handshake.3 @@ -0,0 +1,110 @@ +.Dd $Mdocdate: October 12 2014 $ +.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, +except for SGC (Server Gated Cryptography). +For SGC, +.Fn SSL_do_handshake +may return with \(mi1, but +.Xr SSL_get_error 3 +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +and +.Fn SSL_do_handshake +should be called again. +.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 new file mode 100644 index 0000000000..453cd7d424 --- /dev/null +++ b/src/lib/libssl/doc/SSL_free.3 @@ -0,0 +1,59 @@ +.Dd $Mdocdate: October 12 2014 $ +.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. +.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 new file mode 100644 index 0000000000..40effb512f --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_SSL_CTX.3 @@ -0,0 +1,25 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..f836988f39 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_ciphers.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..9c08a8e17d --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_client_CA_list.3 @@ -0,0 +1,58 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..ec1f2bb7df --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_current_cipher.3 @@ -0,0 +1,49 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..28ab34d5e8 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_default_timeout.3 @@ -0,0 +1,33 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..ad533f68c5 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_error.3 @@ -0,0 +1,166 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 an 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 new file mode 100644 index 0000000000..9151f1d989 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_ex_data_X509_STORE_CTX_idx.3 @@ -0,0 +1,62 @@ +.Dd $Mdocdate: October 12 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 \(la0 +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 new file mode 100644 index 0000000000..5b1ff19c54 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_ex_new_index.3 @@ -0,0 +1,73 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..458e73dacc --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_fd.3 @@ -0,0 +1,43 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..850e8cf913 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_peer_cert_chain.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..7e4ab3fccf --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_peer_certificate.3 @@ -0,0 +1,50 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..b3a72cca29 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_psk_identity.3 @@ -0,0 +1,41 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..a8370d5ef2 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_rbio.3 @@ -0,0 +1,42 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..fe9a6d48ef --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_session.3 @@ -0,0 +1,94 @@ +.Dd $Mdocdate: October 12 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 * +SSL_get_session "const SSL *ssl" +.Ft SSL_SESSION * +SSL_get0_session "const SSL *ssl" +.Ft SSL_SESSION * +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 new file mode 100644 index 0000000000..3409dc0698 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_verify_result.3 @@ -0,0 +1,46 @@ +.Dd $Mdocdate: October 12 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 verify 1 . +.El +.Sh SEE ALSO +.Xr verify 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 new file mode 100644 index 0000000000..f8fe406d44 --- /dev/null +++ b/src/lib/libssl/doc/SSL_get_version.3 @@ -0,0 +1,32 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..0644ebd987 --- /dev/null +++ b/src/lib/libssl/doc/SSL_library_init.3 @@ -0,0 +1,51 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..52d21e8e31 --- /dev/null +++ b/src/lib/libssl/doc/SSL_load_client_CA_file.3 @@ -0,0 +1,50 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..3c5b303bbb --- /dev/null +++ b/src/lib/libssl/doc/SSL_new.3 @@ -0,0 +1,38 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..e07ba48283 --- /dev/null +++ b/src/lib/libssl/doc/SSL_pending.3 @@ -0,0 +1,41 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..aed39c300f --- /dev/null +++ b/src/lib/libssl/doc/SSL_read.3 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..77fcd06eac --- /dev/null +++ b/src/lib/libssl/doc/SSL_rstate_string.3 @@ -0,0 +1,52 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..40a88cd881 --- /dev/null +++ b/src/lib/libssl/doc/SSL_session_reused.3 @@ -0,0 +1,29 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..62bc22370d --- /dev/null +++ b/src/lib/libssl/doc/SSL_set_bio.3 @@ -0,0 +1,48 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..37e52788a4 --- /dev/null +++ b/src/lib/libssl/doc/SSL_set_connect_state.3 @@ -0,0 +1,68 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL_SET_CONNECT_STATE 3 +.Os +.Sh NAME +.Nm SSL_set_connect_state , +.Nm SSL_get_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 new file mode 100644 index 0000000000..94345ae236 --- /dev/null +++ b/src/lib/libssl/doc/SSL_set_fd.3 @@ -0,0 +1,70 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..3721b0e0e6 --- /dev/null +++ b/src/lib/libssl/doc/SSL_set_session.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 new file mode 100644 index 0000000000..239bbd6801 --- /dev/null +++ b/src/lib/libssl/doc/SSL_set_shutdown.3 @@ -0,0 +1,85 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..3c7f0540fb --- /dev/null +++ b/src/lib/libssl/doc/SSL_set_verify_result.3 @@ -0,0 +1,39 @@ +.Dd $Mdocdate: October 12 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 verify 1 . +.Sh RETURN VALUES +.Fn SSL_set_verify_result +does not provide a return value. +.Sh SEE ALSO +.Xr verify 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 new file mode 100644 index 0000000000..aa8d483b24 --- /dev/null +++ b/src/lib/libssl/doc/SSL_shutdown.3 @@ -0,0 +1,201 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..828b8f351a --- /dev/null +++ b/src/lib/libssl/doc/SSL_state_string.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..5f9d89ea92 --- /dev/null +++ b/src/lib/libssl/doc/SSL_want.3 @@ -0,0 +1,100 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..19dfffae1b --- /dev/null +++ b/src/lib/libssl/doc/SSL_write.3 @@ -0,0 +1,172 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..3a40c32e69 --- /dev/null +++ b/src/lib/libssl/doc/d2i_SSL_SESSION.3 @@ -0,0 +1,126 @@ +.Dd $Mdocdate: October 12 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 new file mode 100644 index 0000000000..901e1fdfc1 --- /dev/null +++ b/src/lib/libssl/doc/ssl.3 @@ -0,0 +1,1317 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL 3 +.Os +.Sh NAME +.Nm SSL +.Nd OpenSSL SSL/TLS library +.Sh SYNOPSIS +.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 +.Xr ssl 3 +document appeared in OpenSSL 0.9.2. diff --git a/src/lib/libssl/src/doc/ssl/BIO_f_ssl.3 b/src/lib/libssl/src/doc/ssl/BIO_f_ssl.3 new file mode 100644 index 0000000000..31c9963edb --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/BIO_f_ssl.3 @@ -0,0 +1,475 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.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 SGC or 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 EXAMPLE +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/src/doc/ssl/BIO_f_ssl.pod b/src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod deleted file mode 100644 index dfd7833b13..0000000000 --- a/src/lib/libssl/src/doc/ssl/BIO_f_ssl.pod +++ /dev/null @@ -1,322 +0,0 @@ -=pod - -=head1 NAME - -BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, -BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates, -BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect, -BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO - -=head1 SYNOPSIS - - #include - #include - - BIO_METHOD *BIO_f_ssl(void); - - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); - - BIO *BIO_new_ssl(SSL_CTX *ctx,int client); - BIO *BIO_new_ssl_connect(SSL_CTX *ctx); - BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); - int BIO_ssl_copy_session_id(BIO *to,BIO *from); - void BIO_ssl_shutdown(BIO *bio); - - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) - -=head1 DESCRIPTION - -BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which -is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to -SSL I/O. - -I/O performed on an SSL BIO communicates using the SSL protocol with -the SSLs read and write BIOs. If an SSL connection is not established -then an attempt is made to establish one on the first I/O call. - -If a BIO is appended to an SSL BIO using BIO_push() it is automatically -used as the SSL BIOs read and write BIOs. - -Calling BIO_reset() on an SSL BIO closes down any current SSL connection -by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in -the chain: this will typically disconnect the underlying transport. -The SSL BIO is then reset to the initial accept or connect state. - -If the close flag is set when an SSL BIO is freed then the internal -SSL structure is also freed using SSL_free(). - -BIO_set_ssl() sets the internal SSL pointer of BIO B to B using -the close flag B. - -BIO_get_ssl() retrieves the SSL pointer of BIO B, it can then be -manipulated using the standard SSL library functions. - -BIO_set_ssl_mode() sets the SSL BIO mode to B. If B -is 1 client mode is set. If B is 0 server mode is set. - -BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count -to B. When set after every B bytes of I/O (read and write) -the SSL session is automatically renegotiated. B must be at -least 512 bytes. - -BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to -B. When the renegotiate timeout elapses the session is -automatically renegotiated. - -BIO_get_num_renegotiates() returns the total number of session -renegotiations due to I/O or timeout. - -BIO_new_ssl() allocates an SSL BIO using SSL_CTX B and using -client mode if B is non zero. - -BIO_new_ssl_connect() creates a new BIO chain consisting of an -SSL BIO (using B) followed by a connect BIO. - -BIO_new_buffer_ssl_connect() creates a new BIO chain consisting -of a buffering BIO, an SSL BIO (using B) and a connect -BIO. - -BIO_ssl_copy_session_id() copies an SSL session id between -BIO chains B and B. It does this by locating the -SSL BIOs in each chain and calling SSL_copy_session_id() on -the internal SSL pointer. - -BIO_ssl_shutdown() closes down an SSL connection on BIO -chain B. It does this by locating the SSL BIO in the -chain and calling SSL_shutdown() on its internal SSL -pointer. - -BIO_do_handshake() attempts to complete an SSL handshake on the -supplied 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 BIO_should_retry() should be used for non blocking connect BIOs -to determine if the call should be retried. If an SSL connection has -already been established this call has no effect. - -=head1 NOTES - -SSL BIOs 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 BIO_read() operation, one -case where this happens is when SGC or step up occurs. - -In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be -set to disable this behaviour. That is when this flag is set -an SSL BIO using a blocking transport will never request a -retry. - -Since unknown BIO_ctrl() operations are sent through filter -BIOs the servers name and port can be set using BIO_set_host() -on the BIO returned by BIO_new_ssl_connect() without having -to locate the connect BIO first. - -Applications do not have to call BIO_do_handshake() but may wish -to do so to separate the handshake process from other I/O -processing. - -=head1 RETURN VALUES - -TBA - -=head1 EXAMPLE - -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 L. - - 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\n"); - /* 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\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } - - /* Could examine ssl here to get connection info */ - - BIO_puts(sbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(out, tmpbuf, len); - } - BIO_free_all(sbio); - BIO_free(out); - -Here is a simple server example. It makes use of a buffering -BIO to allow lines to be read from the SSL BIO using BIO_gets. -It creates a pseudo web page containing the actual request from -a client and also echoes the request to standard output. - - 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\n"); - 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\n"); - /* 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\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - /* Now wait for incoming connection */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error in connection\n"); - 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\n"); - ERR_print_errors_fp(stderr); - return 0; - } - - BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); - BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); - BIO_puts(sbio, "--------------------------------------------------\r\n"); - - 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] == '\r') || (tmpbuf[0] == '\n')) break; - } - - BIO_puts(sbio, "--------------------------------------------------\r\n"); - BIO_puts(sbio, "\r\n"); - - /* Since there is a buffering BIO present we had better flush it */ - BIO_flush(sbio); - - BIO_free_all(sbio); - -=head1 BUGS - -In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, -the I/O BIO reference count was incorrectly incremented (instead of -decremented) and dissociated with the SSL BIO even if the SSL 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 BIO. - -=head1 SEE ALSO - -TBA diff --git a/src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.3 b/src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.3 new file mode 100644 index 0000000000..0c6cccd1cc --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.3 @@ -0,0 +1,193 @@ +.Dd $Mdocdate: October 12 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 ciphers 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/src/doc/ssl/SSL_CIPHER_get_name.pod b/src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.pod deleted file mode 100644 index 3ed016ee2c..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CIPHER_get_name.pod +++ /dev/null @@ -1,122 +0,0 @@ -=pod - -=head1 NAME - -SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, -SSL_CIPHER_description - get SSL_CIPHER properties - -=head1 SYNOPSIS - - #include - - const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); - int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); - char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); - char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); - -=head1 DESCRIPTION - -SSL_CIPHER_get_name() returns a pointer to the name of B. If the -argument is the NULL pointer, a pointer to the constant value "NONE" is -returned. - -SSL_CIPHER_get_bits() returns the number of secret bits used for B. If -B is not NULL, it contains the number of bits processed by the -chosen algorithm. If B is NULL, 0 is returned. - -SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol -version that first defined the cipher. -This is currently B or B. -In some cases it should possibly return "TLSv1.2" but the function does not; -use SSL_CIPHER_description() instead. -If B is NULL, "(NONE)" is returned. - -SSL_CIPHER_description() returns a textual description of the cipher used -into the buffer B of length B provided. -If B is NULL, a buffer is allocated using asprintf(); that -buffer should be freed up using the B function. -If B is too small, or if B is NULL and the allocation fails, a -pointer to the string "Buffer too small" is returned. - -=head1 NOTES - -The number of bits processed can be different from the secret bits. An -export cipher like e.g. EXP-RC4-MD5 has only 40 secret bits. The algorithm -does use the full 128 bits (which would be returned for B), of -which however 88bits are fixed. The search space is hence only 40 bits. - -The string returned by SSL_CIPHER_description() in case of success consists -of cleartext information separated by one or more blanks in the following -sequence: - -=over 4 - -=item - -Textual representation of the cipher name. - -=item - -Protocol version: B, B, B. The TLSv1.0 ciphers are -flagged with SSLv3. No new ciphers were added by TLSv1.1. - -=item Kx= - -Key exchange method: B (for export ciphers as B or -B), B (for export ciphers as B or B), -B, B, B. - -=item Au= - -Authentication method: B, B, B, B. None is the -representation of anonymous ciphers. - -=item Enc= - -Encryption method with number of secret bits: B, B, -B<3DES(168)>, B, B, B, B, -B, B, B, B, B, B. - -=item Mac= - -Message digest: B, B. - -=item - -If the cipher is flagged exportable with respect to old US crypto -regulations, the word "B" is printed. - -=back - -=head1 EXAMPLES - -Some examples for the output of SSL_CIPHER_description(): - - EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 - EDH-DSS-DES-CBC3-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1 - RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5 - EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export - -A complete list can be retrieved by invoking the following command: - - openssl ciphers -v ALL - -=head1 BUGS - -If SSL_CIPHER_description() is called with B being NULL, the -library crashes. - -If SSL_CIPHER_description() cannot handle a built-in cipher, the according -description of the cipher property is B. This case should not -occur. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.3 b/src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.3 new file mode 100644 index 0000000000..c23d676930 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_COMP_add_compression_method.pod b/src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.pod deleted file mode 100644 index 80175a3c17..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_COMP_add_compression_method.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -SSL_COMP_add_compression_method - handle SSL/TLS integrated compression methods - -=head1 SYNOPSIS - - #include - - int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); - -=head1 DESCRIPTION - -SSL_COMP_add_compression_method() adds the compression method B with -the identifier B 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. - -=head1 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. - -An OpenSSL client speaking a protocol that allows compression (SSLv3, TLSv1) -will unconditionally send the list of all compression methods enabled with -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. - -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. - -The OpenSSL library has the compression methods B and (when -especially enabled during compilation) B available. - -=head1 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. - -=head1 RETURN VALUES - -SSL_COMP_add_compression_method() may return the following values: - -=over 4 - -=item C<0> - -The operation succeeded. - -=item C<1> - -The operation failed. Check the error queue to find out the reason. - -=back - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.3 new file mode 100644 index 0000000000..2664c67a5a --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.3 @@ -0,0 +1,42 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod deleted file mode 100644 index df5441caec..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_add_extra_chain_cert.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_add_extra_chain_cert - add certificate to chain - -=head1 SYNOPSIS - - #include - - long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509) - -=head1 DESCRIPTION - -SSL_CTX_add_extra_chain_cert() adds the certificate B to the certificate -chain presented together with the certificate. Several certificates -can be added one after the other. - -=head1 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 -L. - -The B certificate provided to SSL_CTX_add_extra_chain_cert() will be -freed by the library when the B is destroyed. An application B free the B object. - -=head1 RETURN VALUES - -SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the -error stack to find out the reason for failure otherwise. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.3 new file mode 100644 index 0000000000..74b4481496 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.3 @@ -0,0 +1,87 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_add_session.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.pod deleted file mode 100644 index 7f1a1d5ee6..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_add_session.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_add_session, SSL_add_session, SSL_CTX_remove_session, -SSL_remove_session - manipulate session cache - -=head1 SYNOPSIS - - #include - - int SSL_CTX_add_session(SSL_CTX *ctx, SSL_SESSION *c); - int SSL_add_session(SSL_CTX *ctx, SSL_SESSION *c); - - int SSL_CTX_remove_session(SSL_CTX *ctx, SSL_SESSION *c); - int SSL_remove_session(SSL_CTX *ctx, SSL_SESSION *c); - -=head1 DESCRIPTION - -SSL_CTX_add_session() adds the session B to the context B. The -reference count for session B is incremented by 1. If a session with -the same session id already exists, the old session is removed by calling -L. - -SSL_CTX_remove_session() removes the session B from the context B. -L is called once for B. - -SSL_add_session() and SSL_remove_session() are synonyms for their -SSL_CTX_*() counterparts. - -=head1 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 SSL_SESSION object, The old session is -removed and replaced by the new session. If the session is actually -identical (the SSL_SESSION object is identical), SSL_CTX_add_session() -is a no-op, and the return value is 0. - -If a server SSL_CTX is configured with the 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 SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the -application can use SSL_CTX_add_session() directly to have full control -over the sessions that can be resumed if desired. - - -=head1 RETURN VALUES - -The following values are returned by all functions: - -=over 4 - -=item C<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. - -=item C<1> - - The operation succeeded. - -=back - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.3 new file mode 100644 index 0000000000..d0a4ffd554 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.3 @@ -0,0 +1,46 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_ctrl.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod deleted file mode 100644 index 8133689940..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_ctrl.pod +++ /dev/null @@ -1,35 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_ctrl, SSL_CTX_callback_ctrl, SSL_ctrl, SSL_callback_ctrl - internal -handling functions for SSL_CTX and SSL objects - -=head1 SYNOPSIS - - #include - - long SSL_CTX_ctrl(SSL_CTX *ctx, int cmd, long larg, void *parg); - long SSL_CTX_callback_ctrl(SSL_CTX *, int cmd, void (*fp)()); - - long SSL_ctrl(SSL *ssl, int cmd, long larg, void *parg); - long SSL_callback_ctrl(SSL *, int cmd, void (*fp)()); - -=head1 DESCRIPTION - -The SSL_*_ctrl() family of functions is used to manipulate settings of -the SSL_CTX and SSL objects. Depending on the command B the arguments -B, B, or B are evaluated. These functions should never -be called directly. All functionalities needed are made available via -other functions or macros. - -=head1 RETURN VALUES - -The return values of the SSL*_ctrl() functions depend on the command -supplied via the B parameter. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.3 new file mode 100644 index 0000000000..6431008c4f --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_flush_sessions.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.pod deleted file mode 100644 index 8fb0f1dbaf..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_flush_sessions.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_flush_sessions, SSL_flush_sessions - remove expired sessions - -=head1 SYNOPSIS - - #include - - void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm); - void SSL_flush_sessions(SSL_CTX *ctx, long tm); - -=head1 DESCRIPTION - -SSL_CTX_flush_sessions() causes a run through the session cache of -B to remove sessions expired at time B. - -SSL_flush_sessions() is a synonym for SSL_CTX_flush_sessions(). - -=head1 NOTES - -If enabled, the internal session cache will collect all sessions established -up to the specified maximum number (see 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 -L) -or manually by calling SSL_CTX_flush_sessions(). - -The parameter B specifies the time which should be used for the -expiration test, in most cases the actual time given by time(0) -will be used. - -SSL_CTX_flush_sessions() will only check sessions stored in the internal -cache. When a session is found and removed, the remove_session_cb is however -called to synchronize with the external cache (see -L). - -=head1 RETURN VALUES - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_free.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_free.3 new file mode 100644 index 0000000000..9cf5934303 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_free.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: October 12 2014 $ +.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. +.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/src/doc/ssl/SSL_CTX_free.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_free.pod deleted file mode 100644 index 51d8676968..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_free.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_free - free an allocated SSL_CTX object - -=head1 SYNOPSIS - - #include - - void SSL_CTX_free(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_free() decrements the reference count of B, and removes the -SSL_CTX object pointed to by B and frees up the allocated memory if the -the reference count has reached 0. - -It also calls the free()ing procedures for indirectly affected items, if -applicable: the session cache, the list of ciphers, the list of Client CAs, -the certificates and keys. - -=head1 WARNINGS - -If a session-remove callback is set (SSL_CTX_sess_set_remove_cb()), this -callback will be called for each session being freed from B'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 -SSL_CTX_sess_set_remove_cb(B, NULL) prior to calling SSL_CTX_free(). - -=head1 RETURN VALUES - -SSL_CTX_free() does not provide diagnostic information. - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.3 new file mode 100644 index 0000000000..593f39c24c --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.3 @@ -0,0 +1,67 @@ +.Dd $Mdocdate: October 12 2014 $ +.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/src/doc/ssl/SSL_CTX_get_ex_new_index.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.pod deleted file mode 100644 index 5a03844114..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal -application specific data functions - -=head1 SYNOPSIS - - #include - - int SSL_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg); - - void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx); - - 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); - -=head1 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. - -SSL_CTX_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_CTX_set_ex_data() is used to store application data at B for B -into the B object. - -SSL_CTX_get_ex_data() is used to retrieve the information for B from -B. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.3 new file mode 100644 index 0000000000..4139229d7b --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.3 @@ -0,0 +1,70 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_get_verify_mode.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.pod deleted file mode 100644 index d0201bf263..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_get_verify_mode.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get_verify_mode, SSL_get_verify_mode, SSL_CTX_get_verify_depth, -SSL_get_verify_depth, SSL_get_verify_callback, SSL_CTX_get_verify_callback - -get currently set verification parameters - -=head1 SYNOPSIS - - #include - - int SSL_CTX_get_verify_mode(const SSL_CTX *ctx); - int SSL_get_verify_mode(const SSL *ssl); - int SSL_CTX_get_verify_depth(const SSL_CTX *ctx); - int SSL_get_verify_depth(const SSL *ssl); - int (*SSL_CTX_get_verify_callback(const SSL_CTX *ctx))(int, X509_STORE_CTX *); - int (*SSL_get_verify_callback(const SSL *ssl))(int, X509_STORE_CTX *); - -=head1 DESCRIPTION - -SSL_CTX_get_verify_mode() returns the verification mode currently set in -B. - -SSL_get_verify_mode() returns the verification mode currently set in -B. - -SSL_CTX_get_verify_depth() returns the verification depth limit currently set -in B. If no limit has been explicitly set, -1 is returned and the -default value will be used. - -SSL_get_verify_depth() returns the verification depth limit currently set -in B. If no limit has been explicitly set, -1 is returned and the -default value will be used. - -SSL_CTX_get_verify_callback() returns a function pointer to the verification -callback currently set in B. If no callback was explicitly set, the -NULL pointer is returned and the default callback will be used. - -SSL_get_verify_callback() returns a function pointer to the verification -callback currently set in B. If no callback was explicitly set, the -NULL pointer is returned and the default callback will be used. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.3 new file mode 100644 index 0000000000..1e494032f4 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.3 @@ -0,0 +1,158 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_load_verify_locations.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod deleted file mode 100644 index cd78dd285f..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_load_verify_locations.pod +++ /dev/null @@ -1,137 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_load_verify_locations - set default locations for trusted CA -certificates - -=head1 SYNOPSIS - - #include - - int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, - const char *CApath); - -=head1 DESCRIPTION - -SSL_CTX_load_verify_locations() specifies the locations for B, at -which CA certificates for verification purposes are located. The certificates -available via B and B are trusted. - -=head1 NOTES - -If B is not NULL, it points to a file of CA certificates in PEM -format. The file can contain several CA certificates identified by - - -----BEGIN CERTIFICATE----- - ... (CA certificate in base64 encoding) ... - -----END CERTIFICATE----- - -sequences. Before, between, and after the certificates text is allowed -which can be used e.g. for descriptions of the certificates. - -The B is processed on execution of the SSL_CTX_load_verify_locations() -function. - -If B 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. 9d66eef0.0, 9d66eef0.1 etc). The search -is performed in the ordering of the extension number, regardless of other -properties of the certificates. - -The certificates in B are only looked up when required, e.g. when -building the certificate chain or when actually performing the verification -of a peer certificate. - -When looking up CA certificates, the OpenSSL library will first search the -certificates in B, then those in B. 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. - -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 B or B and must -explicitly be set using the -L -family of functions. - -When building its own certificate chain, an OpenSSL client/server will -try to fill in missing certificates from B/B, if the -certificate chain was not explicitly specified (see -L, -L. - -=head1 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 "certificate expired" verification -error occurs, no other certificate will be searched. Make sure to not -have expired certificates mixed with valid ones. - -=head1 EXAMPLES - -Generate a CA certificate file with descriptive text from the CA certificates -ca1.pem ca2.pem ca3.pem: - - #!/bin/sh - rm CAfile.pem - for i in ca1.pem ca2.pem ca3.pem ; do - openssl x509 -in $i -text >> CAfile.pem - done - -Prepare the directory /some/where/certs containing several CA certificates -for use as B: - - 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 - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The operation failed because B and B are NULL or the -processing at one of the locations specified failed. Check the error -stack to find out the reason. - -=item C<1> - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_new.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_new.3 new file mode 100644 index 0000000000..b798d10a9e --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_new.3 @@ -0,0 +1,108 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_new.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_new.pod deleted file mode 100644 index 023be38c0a..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_new.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_new, SSLv3_method, SSLv3_server_method, SSLv3_client_method, -TLSv1_method, TLSv1_server_method, TLSv1_client_method, -TLSv1_1_method, TLSv1_1_server_method, TLSv1_1_client_method, SSLv23_method, -SSLv23_server_method, SSLv23_client_method - create a new SSL_CTX object as framework for TLS/SSL enabled functions - -=head1 SYNOPSIS - - #include - - SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); - -=head1 DESCRIPTION - -SSL_CTX_new() creates a new B object as framework to establish -TLS/SSL enabled connections. - -=head1 NOTES - -The SSL_CTX object uses B as connection method. The methods exist -in a generic type (for client and server use), a server only type, and a -client only type. B can be of the following types: - -=over 4 - -=item SSLv3_method(void), SSLv3_server_method(void), 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. This especially means, that it will -not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*_method(). - -=item TLSv1_method(void), TLSv1_server_method(void), 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. This especially means, that it will -not understand SSLv2 client hello messages which are widely used for -compatibility reasons, see SSLv23_*_method(). It will also not understand -SSLv3 client hello messages. - -=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void) - -A TLS/SSL connection established with these methods may understand the -SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols. - -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. - -=back - -The list of protocols available can later be limited using the -SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2 -options of the SSL_CTX_set_options() or SSL_set_options() functions. -Using these options it is possible to choose e.g. 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. - -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. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -The creation of a new SSL_CTX object failed. Check the error stack to -find out the reason. - -=item Pointer to an SSL_CTX object - -The return value points to an allocated SSL_CTX object. - -=back - -=head1 SEE ALSO - -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.3 new file mode 100644 index 0000000000..862576ca50 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.3 @@ -0,0 +1,101 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_sess_number.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.pod deleted file mode 100644 index f7192eb761..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_number.pod +++ /dev/null @@ -1,80 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sess_number, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, -SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_accept, -SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_hits, -SSL_CTX_sess_cb_hits, SSL_CTX_sess_misses, SSL_CTX_sess_timeouts, -SSL_CTX_sess_cache_full - obtain session cache statistics - -=head1 SYNOPSIS - - #include - - long SSL_CTX_sess_number(SSL_CTX *ctx); - long SSL_CTX_sess_connect(SSL_CTX *ctx); - long SSL_CTX_sess_connect_good(SSL_CTX *ctx); - long SSL_CTX_sess_connect_renegotiate(SSL_CTX *ctx); - long SSL_CTX_sess_accept(SSL_CTX *ctx); - long SSL_CTX_sess_accept_good(SSL_CTX *ctx); - long SSL_CTX_sess_accept_renegotiate(SSL_CTX *ctx); - long SSL_CTX_sess_hits(SSL_CTX *ctx); - long SSL_CTX_sess_cb_hits(SSL_CTX *ctx); - long SSL_CTX_sess_misses(SSL_CTX *ctx); - long SSL_CTX_sess_timeouts(SSL_CTX *ctx); - long SSL_CTX_sess_cache_full(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_sess_number() returns the current number of sessions in the internal -session cache. - -SSL_CTX_sess_connect() returns the number of started SSL/TLS handshakes in -client mode. - -SSL_CTX_sess_connect_good() returns the number of successfully established -SSL/TLS sessions in client mode. - -SSL_CTX_sess_connect_renegotiate() returns the number of start renegotiations -in client mode. - -SSL_CTX_sess_accept() returns the number of started SSL/TLS handshakes in -server mode. - -SSL_CTX_sess_accept_good() returns the number of successfully established -SSL/TLS sessions in server mode. - -SSL_CTX_sess_accept_renegotiate() returns the number of start renegotiations -in server mode. - -SSL_CTX_sess_hits() returns the number of successfully reused sessions. -In client mode a session set with L -successfully reused is counted as a hit. In server mode a session successfully -retrieved from internal or external cache is counted as a hit. - -SSL_CTX_sess_cb_hits() returns the number of successfully retrieved sessions -from the external session cache in server mode. - -SSL_CTX_sess_misses() returns the number of sessions proposed by clients -that were not found in the internal session cache in server mode. - -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 SSL_CTX_sess_hits() count. - -SSL_CTX_sess_cache_full() returns the number of sessions that were removed -because the maximum session cache size was exceeded. - -=head1 RETURN VALUES - -The functions return the values indicated in the DESCRIPTION section. - -=head1 SEE ALSO - -L, L, -L -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.3 new file mode 100644 index 0000000000..ad434e8496 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.3 @@ -0,0 +1,52 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.pod deleted file mode 100644 index a8d1bd5e3f..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_cache_size.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sess_set_cache_size, SSL_CTX_sess_get_cache_size - manipulate session -cache size - -=head1 SYNOPSIS - - #include - - long SSL_CTX_sess_set_cache_size(SSL_CTX *ctx, long t); - long SSL_CTX_sess_get_cache_size(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_sess_set_cache_size() sets the size of the internal session cache -of context B to B. - -SSL_CTX_sess_get_cache_size() returns the currently valid session cache size. - -=head1 NOTES - -The internal session cache size is SSL_SESSION_CACHE_MAX_SIZE_DEFAULT, -currently 1024*20, so that up to 20000 sessions can be held. This size -can be modified using the SSL_CTX_sess_set_cache_size() call. A special -case is the size 0, which is used for unlimited size. - -When the maximum number of sessions is reached, no more new sessions are -added to the cache. New space may be added by calling -L to remove -expired sessions. - -If the size of the session cache is reduced and more sessions are already -in the session cache, old session will be removed at the next time a -session shall be added. This removal is not synchronized with the -expiration of sessions. - -=head1 RETURN VALUES - -SSL_CTX_sess_set_cache_size() returns the previously valid size. - -SSL_CTX_sess_get_cache_size() returns the currently valid size. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.3 new file mode 100644 index 0000000000..d5c506cec8 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.3 @@ -0,0 +1,156 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod deleted file mode 100644 index d39c088e7c..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_sess_set_get_cb.pod +++ /dev/null @@ -1,89 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, -SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_get_get_cb - -provide callback functions for server side external session caching - -=head1 SYNOPSIS - - #include - - void SSL_CTX_sess_set_new_cb(SSL_CTX *ctx, - int (*new_session_cb)(SSL *, SSL_SESSION *)); - void SSL_CTX_sess_set_remove_cb(SSL_CTX *ctx, - void (*remove_session_cb)(SSL_CTX *ctx, SSL_SESSION *)); - void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx, - SSL_SESSION (*get_session_cb)(SSL *, unsigned char *, int, int *)); - - int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl, SSL_SESSION *sess); - void (*SSL_CTX_sess_get_remove_cb(SSL_CTX *ctx))(struct ssl_ctx_st *ctx, SSL_SESSION *sess); - SSL_SESSION *(*SSL_CTX_sess_get_get_cb(SSL_CTX *ctx))(struct ssl_st *ssl, unsigned char *data, int len, int *copy); - - int (*new_session_cb)(struct ssl_st *ssl, SSL_SESSION *sess); - void (*remove_session_cb)(struct ssl_ctx_st *ctx, SSL_SESSION *sess); - SSL_SESSION *(*get_session_cb)(struct ssl_st *ssl, unsigned char *data, - int len, int *copy); - -=head1 DESCRIPTION - -SSL_CTX_sess_set_new_cb() sets the callback function, which is automatically -called whenever a new session was negotiated. - -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. - -SSL_CTX_sess_set_get_cb() sets the callback function which is called, -whenever a SSL/TLS client proposed to resume a session but the session -could not be found in the internal session cache (see -L). -(SSL/TLS server only.) - -SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb(), and -SSL_CTX_sess_get_get_cb() allow to retrieve the function pointers of the -provided callback functions. If a callback function has not been set, -the NULL pointer is returned. - -=head1 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 -L interface. - -The new_session_cb() is called, whenever a new session has been negotiated -and session caching is enabled (see -L). -The new_session_cb() is passed the B connection and the ssl session -B. If the callback returns B<0>, the session will be immediately -removed again. - -The 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 shutdown cleanly. It also happens -for all sessions in the internal session cache when -L is called. The remove_session_cb() is passed -the B and the ssl session B. It does not provide any feedback. - -The get_session_cb() is only called on SSL/TLS servers with the session id -proposed by the client. The get_session_cb() is always called, also when -session caching was disabled. The get_session_cb() is passed the -B connection, the session id of length B at the memory location -B. With the parameter B the callback can require the -SSL engine to increment the reference count of the SSL_SESSION object, -Normally the reference count is not incremented and therefore the -session must not be explicitly freed with -L. - -=head1 SEE ALSO - -L, L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.3 new file mode 100644 index 0000000000..96aa018289 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.3 @@ -0,0 +1,31 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.Xr lhash 3 +type database. +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 +.Xr lhash 3 +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 lhash 3 , +.Xr ssl 3 , +.Xr SSL_CTX_add_session 3 , +.Xr SSL_CTX_set_session_cache_mode 3 diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.pod deleted file mode 100644 index e05aab3c1b..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_sessions.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_sessions - access internal session cache - -=head1 SYNOPSIS - - #include - - struct lhash_st *SSL_CTX_sessions(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_sessions() returns a pointer to the lhash databases containing the -internal session cache for B. - -=head1 NOTES - -The sessions in the internal session cache are kept in an -L type database. 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 -L operations, so that the database must not be -modified directly but by using the -L family of functions. - -=head1 SEE ALSO - -L, L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.3 new file mode 100644 index 0000000000..f80670ce78 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.3 @@ -0,0 +1,77 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_cert_store.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod deleted file mode 100644 index 2f3980fded..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_store.pod +++ /dev/null @@ -1,58 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cert_store, SSL_CTX_get_cert_store - manipulate X509 certificate -verification storage - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_cert_store(SSL_CTX *ctx, X509_STORE *store); - X509_STORE *SSL_CTX_get_cert_store(const SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_cert_store() sets/replaces the certificate verification storage -of B to/with B. If another X509_STORE object is currently -set in B, it will be X509_STORE_free()ed. - -SSL_CTX_get_cert_store() returns a pointer to the current certificate -verification storage. - -=head1 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 X509_STORE. From the X509_STORE -the X509_STORE_CTX used when verifying certificates is created. - -Typically the trusted certificate store is handled indirectly via using -L. -Using the SSL_CTX_set_cert_store() and SSL_CTX_get_cert_store() functions -it is possible to manipulate the X509_STORE object beyond the -L -call. - -Currently no detailed documentation on how to use the X509_STORE -object is available. Not all members of the X509_STORE are used when -the verification takes place. So will e.g. the verify_callback() be -overridden with the verify_callback() set via the -L family of functions. -This document must therefore be updated when documentation about the -X509_STORE object and its handling becomes available. - -=head1 RETURN VALUES - -SSL_CTX_set_cert_store() does not return diagnostic output. - -SSL_CTX_get_cert_store() returns the current setting. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.3 new file mode 100644 index 0000000000..b34d3a6003 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.3 @@ -0,0 +1,109 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod deleted file mode 100644 index 713b223a63..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cert_verify_callback.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cert_verify_callback - set peer certificate verification procedure - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_cert_verify_callback(SSL_CTX *ctx, int (*callback)(X509_STORE_CTX *,void *), void *arg); - -=head1 DESCRIPTION - -SSL_CTX_set_cert_verify_callback() sets the verification callback function for -I. SSL objects that are created from I inherit the setting valid at -the time when L is called. - -=head1 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 I is specified via -SSL_CTX_set_cert_verify_callback(), the supplied callback function is called -instead. By setting I to NULL, the default behaviour is restored. - -When the verification must be performed, I will be called with -the arguments callback(X509_STORE_CTX *x509_store_ctx, void *arg). The -argument I is specified by the application when setting I. - -I should return 1 to indicate verification success and 0 to -indicate verification failure. If SSL_VERIFY_PEER is set and I -returns 0, the handshake will fail. As the verification procedure may -allow to continue the connection in case of failure (by always returning 1) -the verification result must be set in any case using the B -member of I so that the calling application will be informed -about the detailed result of the verification procedure! - -Within I, I has access to the I -function set using L. - -=head1 WARNINGS - -Do not mix the verification callback described in this function with the -B function called during the verification process. The -latter is set using the L -family of functions. - -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 B function. - -=head1 BUGS - -=head1 RETURN VALUES - -SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -Previous to OpenSSL 0.9.7, the I argument to -B was ignored, and I was called -simply as int (*callback)(X509_STORE_CTX *) To compile software written for -previous versions of OpenSSL, a dummy argument will have to be added to -I. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.3 new file mode 100644 index 0000000000..c3ee5304e3 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.3 @@ -0,0 +1,79 @@ +.Dd $Mdocdate: October 12 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 ciphers 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/src/doc/ssl/SSL_CTX_set_cipher_list.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod deleted file mode 100644 index 83e9c6b7e3..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_cipher_list.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_cipher_list, SSL_set_cipher_list - choose list of available -SSL_CIPHERs - -=head1 SYNOPSIS - - #include - - int SSL_CTX_set_cipher_list(SSL_CTX *ctx, const char *str); - int SSL_set_cipher_list(SSL *ssl, const char *str); - -=head1 DESCRIPTION - -SSL_CTX_set_cipher_list() sets the list of available ciphers for B -using the control string B. The format of the string is described -in L. The list of ciphers is inherited by all -B objects created from B. - -SSL_set_cipher_list() sets the list of ciphers only for B. - -=head1 NOTES - -The control string B 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. - -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. - -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 bit (see -L). -RSA ciphers using EDH need a certificate and key and additional DH-parameters -(see L). - -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 L). - -When these conditions are not met for any cipher in the list (e.g. a -client only supports export RSA ciphers with a asymmetric key length -of 512 bits and the server is not configured to use temporary RSA -keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated -and the handshake will fail. - -=head1 RETURN VALUES - -SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher -could be selected and 0 on complete failure. - -=head1 SEE ALSO - -L, L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.3 new file mode 100644 index 0000000000..5d6fa9bea1 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.3 @@ -0,0 +1,129 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_client_CA_list.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.pod deleted file mode 100644 index d1758a7d20..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_CA_list.pod +++ /dev/null @@ -1,94 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA, -SSL_add_client_CA - set list of CAs sent to the client when requesting a -client certificate - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list); - void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list); - int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert); - int SSL_add_client_CA(SSL *ssl, X509 *cacert); - -=head1 DESCRIPTION - -SSL_CTX_set_client_CA_list() sets the B of CAs sent to the client when -requesting a client certificate for B. - -SSL_set_client_CA_list() sets the B of CAs sent to the client when -requesting a client certificate for the chosen B, overriding the -setting valid for B's SSL_CTX object. - -SSL_CTX_add_client_CA() adds the CA name extracted from B to the -list of CAs sent to the client when requesting a client certificate for -B. - -SSL_add_client_CA() adds the CA name extracted from B to the -list of CAs sent to the client when requesting a client certificate for -the chosen B, overriding the setting valid for B's SSL_CTX object. - -=head1 NOTES - -When a TLS/SSL server requests a client certificate (see -B), it sends a list of CAs, for which -it will accept certificates, to the client. - -This list must explicitly be set using SSL_CTX_set_client_CA_list() for -B and SSL_set_client_CA_list() for the specific B. The list -specified overrides the previous setting. The CAs listed do not become -trusted (B only contains the names, not the complete certificates); use -L -to additionally load them for verification. - -If the list of acceptable CAs is compiled in a file, the -L -function can be used to help importing the necessary data. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional -items the list of client CAs. If no list was specified before using -SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client -CA list for B or B (as appropriate) is opened. - -These functions are only useful for TLS/SSL servers. - -=head1 RETURN VALUES - -SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return -diagnostic information. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return -values: - -=over 4 - -=item C<0> - -A failure while manipulating the STACK_OF(X509_NAME) object occurred or -the X509_NAME could not be extracted from B. Check the error stack -to find out the reason. - -=item C<1> - -The operation succeeded. - -=back - -=head1 EXAMPLES - -Scan all certificates in B and list them as acceptable CAs: - - SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile)); - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.3 new file mode 100644 index 0000000000..6aaa5f1016 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.3 @@ -0,0 +1,140 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod deleted file mode 100644 index 0462bbebac..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_client_cert_cb.pod +++ /dev/null @@ -1,95 +0,0 @@ -3=pod - -=head1 NAME - -SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client -certificate callback function - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); - int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); - int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey); - -=head1 DESCRIPTION - -SSL_CTX_set_client_cert_cb() sets the B callback, that is -called when a client certificate is requested by a server and no certificate -was yet set for the SSL object. - -When B is NULL, no callback function is used. - -SSL_CTX_get_client_cert_cb() returns a pointer to the currently set callback -function. - -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 B and B arguments and "1" must be returned. The -certificate will be installed into B, see the NOTES and 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. L -will return 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 client_cert_cb(). It is the job of the client_cert_cb() to store information -about the state of the last call, if required to continue. - -=head1 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. - -When a certificate was set using the -L 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. - -If a callback function is defined and no certificate was yet defined for the -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 SSL -object using the SSL_use_certificate() and 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 L. -If the callback returns no certificate, the OpenSSL library will not send -a certificate. - -=head1 BUGS - -The 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 only be accomplished by -either adding the intermediate CA certificates into the trusted -certificate store for the 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 -L -function, which is only available for the 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. - -Once the SSL object has been used in conjunction with the callback function, -the certificate will be set for the SSL object and will not be cleared -even when L is being called. It is therefore -mandatory to destroy the SSL object using L -and create a new one to return to the previous state. - -=head1 SEE ALSO - -L, L, -L, -L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.3 new file mode 100644 index 0000000000..2c35ed501c --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.3 @@ -0,0 +1,92 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod deleted file mode 100644 index f7bfc64930..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_default_passwd_cb.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set -passwd callback for encrypted PEM file handling - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); - void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); - - int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata); - -=head1 DESCRIPTION - -SSL_CTX_set_default_passwd_cb() sets the default password callback called -when loading/storing a PEM certificate with encryption. - -SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B which -will be provided to the password callback on invocation. - -The pem_passwd_cb(), which must be provided by the application, hands back the -password to be used during decryption. On invocation a pointer to B -is provided. The pem_passwd_cb must write the password into the provided buffer -B which is of size B. The actual length of the password must -be returned to the calling function. B indicates whether the -callback is used for reading/decryption (rwflag=0) or writing/encryption -(rwflag=1). - -=head1 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 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 B storage and the -pem_passwd_cb() only returns the password already stored. - -When asking for the password interactively, pem_passwd_cb() can use -B to check, whether an item shall be encrypted (rwflag=1). -In this case the password dialog may ask for the same password twice -for comparison in order to catch typos, that would make decryption -impossible. - -Other items in PEM formatting (certificates) can also be encrypted, it is -however not usual, as certificate information is considered public. - -=head1 RETURN VALUES - -SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata() -do not provide diagnostic information. - -=head1 EXAMPLES - -The following example returns the password provided as B to the -calling function. The password is considered to be a '\0' terminated -string. If the password does not fit into the buffer, the password is -truncated. - - int pem_passwd_cb(char *buf, int size, int rwflag, void *password) - { - strncpy(buf, (char *)(password), size); - buf[size - 1] = '\0'; - return(strlen(buf)); - } - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.3 new file mode 100644 index 0000000000..e2e2a70362 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.3 @@ -0,0 +1,193 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_generate_session_id.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.pod deleted file mode 100644 index c04588a03c..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_generate_session_id.pod +++ /dev/null @@ -1,152 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, -SSL_has_matching_session_id - manipulate generation of SSL session IDs (server -only) - -=head1 SYNOPSIS - - #include - - typedef int (*GEN_SESSION_CB)(const SSL *ssl, unsigned char *id, - unsigned int *id_len); - - int SSL_CTX_set_generate_session_id(SSL_CTX *ctx, GEN_SESSION_CB cb); - int SSL_set_generate_session_id(SSL *ssl, GEN_SESSION_CB, cb); - int SSL_has_matching_session_id(const SSL *ssl, const unsigned char *id, - unsigned int id_len); - -=head1 DESCRIPTION - -SSL_CTX_set_generate_session_id() sets the callback function for generating -new session ids for SSL/TLS sessions for B to be B. - -SSL_set_generate_session_id() sets the callback function for generating -new session ids for SSL/TLS sessions for B to be B. - -SSL_has_matching_session_id() checks, whether a session with id B -(of length B) is already contained in the internal session cache -of the parent context of B. - -=head1 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. - -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. - -The callback function receives a pointer to the memory location to put -B into and a pointer to the maximum allowed length B. The -buffer at location B is only guaranteed to have the size B. -The callback is only allowed to generate a shorter id and reduce B; -the callback B increase B or write to the location -B exceeding the given limit. - -If a SSLv2 session id is generated and B 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 B for SSLv2 sessions. -The callback can use the L function -to check, whether the session is of type SSLv2. - -The location B is filled with 0x00 before the callback is called, so the -callback may only fill part of the possible length and leave B -untouched while maintaining reproducibility. - -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 assure the -uniqueness of the generated session id, the callback must call -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 can not -guarantee uniqueness, it is recommended to use the maximum B and -fill in the bytes not used to code special information with random data -to avoid collisions. - -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 SSL_has_matching_session_id() -and the same race condition applies. - -When calling SSL_has_matching_session_id() for an SSLv2 session with -reduced B, the match operation will be performed using the -fixed length required and with a 0x00 padded id. - -The callback must return 0 if it cannot generate a session id for whatever -reason and return 1 on success. - -=head1 EXAMPLES - -The callback function listed will generate a session id with the -server id given, and will fill the rest with pseudo random bytes: - - 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 - but there will be worse effects - * anyway, eg. the server could only possibly create 1 session - * ID (ie. 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; - } - - -=head1 RETURN VALUES - -SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id() -always return 1. - -SSL_has_matching_session_id() returns 1 if another session with the -same id is already in the cache. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -SSL_CTX_set_generate_session_id(), SSL_set_generate_session_id() -and SSL_has_matching_session_id() have been introduced in -OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.3 new file mode 100644 index 0000000000..dcf298addf --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.3 @@ -0,0 +1,164 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_info_callback.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.pod deleted file mode 100644 index f7923dedc1..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_info_callback.pod +++ /dev/null @@ -1,154 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_info_callback, SSL_CTX_get_info_callback, SSL_set_info_callback, -SSL_get_info_callback - handle information callback for SSL connections - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_info_callback(SSL_CTX *ctx, void (*callback)()); - void (*SSL_CTX_get_info_callback(const SSL_CTX *ctx))(); - - void SSL_set_info_callback(SSL *ssl, void (*callback)()); - void (*SSL_get_info_callback(const SSL *ssl))(); - -=head1 DESCRIPTION - -SSL_CTX_set_info_callback() sets the B function, that can be used to -obtain state information for SSL objects created from B during connection -setup and use. The setting for B is overridden from the setting for -a specific SSL object, if specified. -When B is NULL, no callback function is used. - -SSL_set_info_callback() sets the B function, that can be used to -obtain state information for B during connection setup and use. -When B is NULL, the callback setting currently valid for -B is used. - -SSL_CTX_get_info_callback() returns a pointer to the currently set information -callback function for B. - -SSL_get_info_callback() returns a pointer to the currently set information -callback function for B. - -=head1 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. - -The callback function is called as B. -The B argument specifies information about where (in which context) -the callback function was called. If B is 0, an error condition occurred. -If an alert is handled, SSL_CB_ALERT is set and B specifies the alert -information. - -B is a bitmask made up of the following bits: - -=over 4 - -=item SSL_CB_LOOP - -Callback has been called to indicate state change inside a loop. - -=item 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.) - -=item SSL_CB_READ - -Callback has been called during read operation. - -=item SSL_CB_WRITE - -Callback has been called during write operation. - -=item SSL_CB_ALERT - -Callback has been called due to an alert being sent or received. - -=item SSL_CB_READ_ALERT (SSL_CB_ALERT|SSL_CB_READ) - -=item SSL_CB_WRITE_ALERT (SSL_CB_ALERT|SSL_CB_WRITE) - -=item SSL_CB_ACCEPT_LOOP (SSL_ST_ACCEPT|SSL_CB_LOOP) - -=item SSL_CB_ACCEPT_EXIT (SSL_ST_ACCEPT|SSL_CB_EXIT) - -=item SSL_CB_CONNECT_LOOP (SSL_ST_CONNECT|SSL_CB_LOOP) - -=item SSL_CB_CONNECT_EXIT (SSL_ST_CONNECT|SSL_CB_EXIT) - -=item SSL_CB_HANDSHAKE_START - -Callback has been called because a new handshake is started. - -=item SSL_CB_HANDSHAKE_DONE 0x20 - -Callback has been called because a handshake is finished. - -=back - -The current state information can be obtained using the -L family of functions. - -The B information can be evaluated using the -L family of functions. - -=head1 RETURN VALUES - -SSL_set_info_callback() does not provide diagnostic information. - -SSL_get_info_callback() returns the current setting. - -=head1 EXAMPLES - -The following example callback function prints state strings, information -about alerts being handled and error messages to the B BIO. - - 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\n",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\n", - 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\n", - str,SSL_state_string_long(s)); - else if (ret < 0) - { - BIO_printf(bio_err,"%s:error in %s\n", - str,SSL_state_string_long(s)); - } - } - } - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.3 new file mode 100644 index 0000000000..7380884867 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.3 @@ -0,0 +1,102 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 http://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/src/doc/ssl/SSL_CTX_set_max_cert_list.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.pod deleted file mode 100644 index 5b874aa5fd..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_max_cert_list.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, -SSL_get_max_cert_list - manipulate allowed size for the peer's certificate chain - -=head1 SYNOPSIS - - #include - - long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size); - long SSL_CTX_get_max_cert_list(SSL_CTX *ctx); - - long SSL_set_max_cert_list(SSL *ssl, long size); - long SSL_get_max_cert_list(SSL *ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's -certificate chain for all SSL objects created from B to be bytes. -The SSL objects inherit the setting valid for B at the time -L is being called. - -SSL_CTX_get_max_cert_list() returns the currently set maximum size for B. - -SSL_set_max_cert_list() sets the maximum size allowed for the peer's -certificate chain for B to be bytes. This setting stays valid -until a new value is set. - -SSL_get_max_cert_list() returns the currently set maximum size for B. - -=head1 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 bounds due to data -received from a faulty or malicious peer, a maximum size for the certificate -chain is set. - -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 -L, and certificates -without special extensions have a typical size of 1-2kB). - -For special applications it can be necessary to extend the maximum certificate -chain size allowed to be sent by the peer, see e.g. the work on -"Internet X.509 Public Key Infrastructure Proxy Certificate Profile" -and "TLS Delegation Protocol" at http://www.ietf.org/ and -http://www.globus.org/ . - -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. - -If the maximum certificate chain size allowed is exceeded, the handshake will -fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error. - -=head1 RETURN VALUES - -SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously -set value. - -SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently -set value. - -=head1 SEE ALSO - -L, L, -L - -=head1 HISTORY - -SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.3 new file mode 100644 index 0000000000..b980d43dbe --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.3 @@ -0,0 +1,123 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_mode.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod deleted file mode 100644 index 0208d17654..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_mode.pod +++ /dev/null @@ -1,92 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode - manipulate SSL -engine mode - -=head1 SYNOPSIS - - #include - - long SSL_CTX_set_mode(SSL_CTX *ctx, long mode); - long SSL_set_mode(SSL *ssl, long mode); - - long SSL_CTX_get_mode(SSL_CTX *ctx); - long SSL_get_mode(SSL *ssl); - -=head1 DESCRIPTION - -SSL_CTX_set_mode() adds the mode set via bitmask in B to B. -Options already set before are not cleared. - -SSL_set_mode() adds the mode set via bitmask in B to B. -Options already set before are not cleared. - -SSL_CTX_get_mode() returns the mode set for B. - -SSL_get_mode() returns the mode set for B. - -=head1 NOTES - -The following mode changes are available: - -=over 4 - -=item SSL_MODE_ENABLE_PARTIAL_WRITE - -Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success -when just a single record has been written). When not set (the default), -SSL_write() will only report success once the complete chunk was written. -Once SSL_write() returns with r, r bytes have been successfully written -and the next call to SSL_write() must only send the n-r bytes left, -imitating the behaviour of write(). - -=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER - -Make it possible to retry SSL_write() with changed buffer location -(the buffer contents must stay the same). This is not the default to avoid -the misconception that non-blocking SSL_write() behaves like -non-blocking write(). - -=item SSL_MODE_AUTO_RETRY - -Never bother the application with retries if the transport is blocking. -If a renegotiation take place during normal operation, a -L or L would return -with -1 and indicate the need to retry with 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 SSL_MODE_AUTO_RETRY will cause read/write operations to only -return after the handshake and successful completion. - -=item SSL_MODE_RELEASE_BUFFERS - -When we no longer need a read buffer or a write buffer for a given 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 SSL_CTX, or simply -freed if the list of unused chunks would become longer than -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. - -=back - -=head1 RETURN VALUES - -SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask -after adding B. - -SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -SSL_MODE_AUTO_RETRY as been added in OpenSSL 0.9.6. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.3 new file mode 100644 index 0000000000..82c1479af0 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.3 @@ -0,0 +1,132 @@ +.Dd $Mdocdate: October 12 2014 $ +.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_get_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_get_msg_callback_arg +were added in OpenSSL 0.9.7. diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod deleted file mode 100644 index 89a33e8750..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_msg_callback.pod +++ /dev/null @@ -1,101 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, -SSL_get_msg_callback_arg - install callback for observing protocol messages - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_msg_callback(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg); - - void SSL_set_msg_callback(SSL *ssl, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - void SSL_set_msg_callback_arg(SSL *ssl, void *arg); - -=head1 DESCRIPTION - -SSL_CTX_set_msg_callback() or SSL_set_msg_callback() can be used to -define a message callback function I for observing all SSL/TLS -protocol messages (such as handshake messages) that are received or -sent. SSL_CTX_set_msg_callback_arg() and SSL_set_msg_callback_arg() -can be used to set argument I to the callback function, which is -available for arbitrary application use. - -SSL_CTX_set_msg_callback() and SSL_CTX_set_msg_callback_arg() specify -default settings that will be copied to new B objects by -L. SSL_set_msg_callback() and -SSL_set_msg_callback_arg() modify the actual settings of an B -object. Using a B<0> pointer for I disables the message callback. - -When I is called by the SSL/TLS library for a protocol message, -the function arguments have the following meaning: - -=over 4 - -=item I - -This flag is B<0> when a protocol message has been received and B<1> -when a protocol message has been sent. - -=item I - -The protocol version according to which the protocol message is -interpreted by the library. Currently, this is one of -B, B and B (for SSL 2.0, SSL -3.0 and TLS 1.0, respectively). - -=item I - -In the case of SSL 2.0, this is always B<0>. In the case of SSL 3.0 -or TLS 1.0, this is one of the B values defined in the -protocol specification (B, B, -B; but never B because the -callback will only be called for protocol messages). - -=item I, I - -I points to a buffer containing the protocol message, which -consists of I bytes. The buffer is no longer valid after the -callback function has returned. - -=item I - -The B object that received or sent the message. - -=item I - -The user-defined argument optionally defined by -SSL_CTX_set_msg_callback_arg() or SSL_set_msg_callback_arg(). - -=back - -=head1 NOTES - -Protocol messages are passed to the callback function after decryption -and fragment collection where applicable. (Thus record boundaries are -not visible.) - -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. - -Due to automatic protocol version negotiation, I 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, -I will be B. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -SSL_CTX_set_msg_callback(), SSL_CTX_set_msg_callback_arg(), -SSL_set_msg_callback() and SSL_get_msg_callback_arg() were added in OpenSSL -0.9.7. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.3 new file mode 100644 index 0000000000..8b2f75cc59 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.3 @@ -0,0 +1,384 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.Lk www.microsoft.com +\(en when talking SSLv2, if session-id reuse is performed, +the session-id passed back in the server-finished message is different from the +one decided upon. +.It Dv SSL_OP_NETSCAPE_CHALLENGE_BUG +Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte challenge but +then appears to only use 16 bytes when generating the encryption keys. +Using 16 bytes is ok but it should be ok to use 32. +According to the SSLv3 spec, one should use 32 bytes for the challenge when +operating in SSLv2/v3 compatibility mode, but as mentioned above, this breaks +this server so 16 bytes is the way to go. +.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 +\&... +.It Dv SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER +\&... +.It Dv SSL_OP_SAFARI_ECDHE_ECDSA_BUG +Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. +OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. +.It Dv SSL_OP_SSLEAY_080_CLIENT_DH_BUG +\&... +.It Dv SSL_OP_TLS_D5_BUG +\&... +.It Dv SSL_OP_TLS_BLOCK_PADDING_BUG +\&... +.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 dhparam 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 +If we accept a netscape connection, demand a client cert, have a +non-self-signed CA which does not have its CA in netscape, and the browser has +a cert, it will crash/hang. +Works for 3.x and 4.xbeta +.It Dv SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG +\&... +.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 dhparam 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/src/doc/ssl/SSL_CTX_set_options.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod deleted file mode 100644 index c656fb2e19..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_options.pod +++ /dev/null @@ -1,350 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, -SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support - -manipulate SSL options - -=head1 SYNOPSIS - - #include - - long SSL_CTX_set_options(SSL_CTX *ctx, long options); - long SSL_set_options(SSL *ssl, long options); - - long SSL_CTX_clear_options(SSL_CTX *ctx, long options); - long SSL_clear_options(SSL *ssl, long options); - - long SSL_CTX_get_options(SSL_CTX *ctx); - long SSL_get_options(SSL *ssl); - - long SSL_get_secure_renegotiation_support(SSL *ssl); - -=head1 DESCRIPTION - -Note: all these functions are implemented using macros. - -SSL_CTX_set_options() adds the options set via bitmask in B to B. -Options already set before are not cleared! - -SSL_set_options() adds the options set via bitmask in B to B. -Options already set before are not cleared! - -SSL_CTX_clear_options() clears the options set via bitmask in B -to B. - -SSL_clear_options() clears the options set via bitmask in B to B. - -SSL_CTX_get_options() returns the options set for B. - -SSL_get_options() returns the options set for B. - -SSL_get_secure_renegotiation_support() indicates whether the peer supports -secure renegotiation. - -=head1 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 B -operation (|). - -SSL_CTX_set_options() and 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 -L and SSL_set_mode() functions. - -During a handshake, the option settings of the SSL object are used. When -a new SSL object is created from a context using SSL_new(), the current -option setting is copied. Changes to B do not affect already created -SSL objects. SSL_clear() does not affect the settings. - -The following B options are available: - -=over 4 - -=item SSL_OP_MICROSOFT_SESS_ID_BUG - -www.microsoft.com - when talking SSLv2, if session-id reuse is -performed, the session-id passed back in the server-finished message -is different from the one decided upon. - -=item SSL_OP_NETSCAPE_CHALLENGE_BUG - -Netscape-Commerce/1.12, when talking SSLv2, accepts a 32 byte -challenge but then appears to only use 16 bytes when generating the -encryption keys. Using 16 bytes is ok but it should be ok to use 32. -According to the SSLv3 spec, one should use 32 bytes for the challenge -when operating in SSLv2/v3 compatibility mode, but as mentioned above, -this breaks this server so 16 bytes is the way to go. - -=item SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG - -As of OpenSSL 0.9.8q and 1.0.0c, this option has no effect. - -=item SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG - -... - -=item SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER - -... - -=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG - -Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X. -OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers. - -=item SSL_OP_SSLEAY_080_CLIENT_DH_BUG - -... - -=item SSL_OP_TLS_D5_BUG - -... - -=item SSL_OP_TLS_BLOCK_PADDING_BUG - -... - -=item 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. - -=item 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. - -=item SSL_OP_ALL - -All of the above bug workarounds. - -=back - -It is usually safe to use B to enable the bug workaround -options if compatibility with somewhat broken implementations is -desired. - -The following B options are available: - -=over 4 - -=item SSL_OP_TLS_ROLLBACK_BUG - -Disable version rollback attack detection. - -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.) - -=item SSL_OP_SINGLE_DH_USE - -Always create a new key when using temporary/ephemeral DH parameters -(see L). -This option must be used to prevent small subgroup attacks, when -the DH parameters were not generated using "strong" primes -(e.g. when using DSA-parameters, see L). -If "strong" primes were used, it is not strictly necessary to generate -a new DH key during each handshake but it is also recommended. -B should therefore be enabled whenever -temporary/ephemeral DH parameters are used. - -=item SSL_OP_EPHEMERAL_RSA - -Always use ephemeral (temporary) RSA key when doing RSA operations -(see L). -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. - -=item 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 clients -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. - -=item SSL_OP_NETSCAPE_CA_DN_BUG - -If we accept a netscape connection, demand a client cert, have a -non-self-signed CA which does not have its CA in netscape, and the -browser has a cert, it will crash/hang. Works for 3.x and 4.xbeta - -=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG - -... - -=item SSL_OP_NO_SSLv2 - -As of OpenBSD 5.6, this option has no effect as SSLv2 support has been removed. -In previous versions it disabled use of the SSLv2 protocol. - -=item SSL_OP_NO_SSLv3 - -Do not use the SSLv3 protocol. - -=item SSL_OP_NO_TLSv1 - -Do not use the TLSv1.0 protocol. - -=item SSL_OP_NO_TLSv1_1 - -Do not use the TLSv1.1 protocol. - -=item SSL_OP_NO_TLSv1_2 - -Do not use the TLSv1.2 protocol. - -=item 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. - -=item SSL_OP_NO_TICKET - -Normally clients and servers will, where possible, transparently make use -of RFC4507bis tickets for stateless session resumption. - -If this option is set this functionality is disabled and tickets will -not be used by clients or servers. - -=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION - -As of OpenBSD 5.6, this option has no effect. -In previous versions it allowed legacy insecure renegotiation between -OpenSSL and unpatched clients or servers. -See the B section for more details. - -=item SSL_OP_LEGACY_SERVER_CONNECT - -Allow legacy insecure renegotiation between OpenSSL and unpatched servers -B: this option is currently set by default. See the -B section for more details. - -=back - -=head1 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. - -The deprecated and highly broken SSLv2 protocol does not support -renegotiation at all: its use is B discouraged. - -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 I. A server not supporting secure -renegotiation is referred to as I. - -The following sections describe the operations permitted by OpenSSL's secure -renegotiation implementation. - -=head2 Patched client and server - -Connections and renegotiation are always permitted by OpenSSL implementations. - -=head2 Unpatched client and patched OpenSSL server - -The initial connection succeeds but client renegotiation is denied by the -server with a B warning alert if TLS v1.0 is used or a fatal -B alert in SSL v3.0. - -If the patched OpenSSL server attempts to renegotiate a fatal -B alert is sent. This is because the server code may be -unaware of the unpatched nature of the client. - -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 -B alert. OpenSSL versions 0.9.8m and later will regard -a B alert as fatal and respond with a fatal -B alert. This is because the OpenSSL API currently has -no provision to indicate to an application that a renegotiation attempt -was refused. - -=head2 Patched OpenSSL client and unpatched server. - -If the option B 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. - -The option B 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. - -As more servers become patched the option B will -B be set by default in a future version of OpenSSL. - -OpenSSL client applications wishing to ensure they can connect to unpatched -servers should always B B - -OpenSSL client applications that want to ensure they can B connect to -unpatched servers (and thus avoid any security issues) should always B -B using SSL_CTX_clear_options() or -SSL_clear_options(). - -=head1 RETURN VALUES - -SSL_CTX_set_options() and SSL_set_options() return the new options bitmask -after adding B. - -SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask -after clearing B. - -SSL_CTX_get_options() and SSL_get_options() return the current bitmask. - -SSL_get_secure_renegotiation_support() returns 1 is the peer supports -secure renegotiation and 0 if it does not. - -=head1 SEE ALSO - -L, L, L, -L, -L, -L - -=head1 HISTORY - -B and -B have been added in -OpenSSL 0.9.7. - -B has been added in OpenSSL 0.9.6 and was -automatically enabled with B. As of 0.9.7, it is no longer included -in B and must be explicitly set. - -B 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). - -SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL -0.9.8m. - -B, B -and the function SSL_get_secure_renegotiation_support() were first added in -OpenSSL 0.9.8m. - -B and B -were changed to have no effect in OpenBSD 5.6. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.3 new file mode 100644 index 0000000000..9bd5c9c545 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.pod deleted file mode 100644 index 7a85ba16d2..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_psk_client_callback.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=begin comment - -Copyright 2005 Nokia. All rights reserved. - -The portions of the attached software ("Contribution") is developed by -Nokia Corporation and is licensed pursuant to the OpenSSL open source -license. - -The Contribution, originally written by Mika Kousa and Pasi Eronen of -Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites -support (see RFC 4279) to OpenSSL. - -No patent licenses or other rights except those expressly stated in -the OpenSSL open source license shall be deemed granted or received -expressly, by implication, estoppel, or otherwise. - -No assurances are provided by Nokia that the Contribution does not -infringe the patent or other intellectual property rights of any third -party or that the license provides you with all the necessary rights -to make use of the Contribution. - -THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN -ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA -SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY -OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR -OTHERWISE. - -=end comment - -=head1 NAME - -SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback - set PSK client -callback - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, - unsigned int (*callback)(SSL *ssl, const char *hint, - char *identity, unsigned int max_identity_len, - unsigned char *psk, unsigned int max_psk_len)); - void SSL_set_psk_client_callback(SSL *ssl, - unsigned int (*callback)(SSL *ssl, const char *hint, - char *identity, unsigned int max_identity_len, - unsigned char *psk, unsigned int max_psk_len)); - - -=head1 DESCRIPTION - -A client application must provide a callback function which is called -when the client is sending the ClientKeyExchange message to the server. - -The purpose of the callback function is to select the PSK identity and -the pre-shared key to use during the connection setup phase. - -The callback is set using functions SSL_CTX_set_psk_client_callback() -or SSL_set_psk_client_callback(). The callback function is given the -connection in parameter B, a B-terminated PSK identity hint -sent by the server in parameter B, a buffer B of -length B bytes where the the resulting -B-terminated identity is to be stored, and a buffer B of -length B bytes where the resulting pre-shared key is to -be stored. - -=head1 NOTES - -Note that parameter B given to the callback may be B. - -=head1 RETURN VALUES - -Return values from the client callback are interpreted as follows: - -On success (callback found a PSK identity and a pre-shared key to use) -the length (> 0) of B in bytes is returned. - -Otherwise or on errors callback should return 0. In this case -the connection setup fails. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.3 new file mode 100644 index 0000000000..91e17350f9 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.3 @@ -0,0 +1,116 @@ +.Dd $Mdocdate: October 12 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 +.Pf | +.Dv SSL_RECEIVED_SHUTDOWN . +.Po +.Xr SSL_shutdown 3 +then behaves like +.Xr SSL_set_shutdown 3 +called with +.Dv SSL_SENT_SHUTDOWN Ns +.Pf | +.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/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod deleted file mode 100644 index 32604dbd1a..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_quiet_shutdown.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_quiet_shutdown, SSL_CTX_get_quiet_shutdown, SSL_set_quiet_shutdown, -SSL_get_quiet_shutdown - manipulate shutdown behaviour - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_quiet_shutdown(SSL_CTX *ctx, int mode); - int SSL_CTX_get_quiet_shutdown(const SSL_CTX *ctx); - - void SSL_set_quiet_shutdown(SSL *ssl, int mode); - int SSL_get_quiet_shutdown(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_CTX_set_quiet_shutdown() sets the "quiet shutdown" flag for B to be -B. SSL objects created from B inherit the B valid at the time -L is called. B may be 0 or 1. - -SSL_CTX_get_quiet_shutdown() returns the "quiet shutdown" setting of B. - -SSL_set_quiet_shutdown() sets the "quiet shutdown" flag for B to be -B. The setting stays valid until B is removed with -L or SSL_set_quiet_shutdown() is called again. -It is not changed when L is called. -B may be 0 or 1. - -SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B. - -=head1 NOTES - -Normally when a SSL connection is finished, the parties must send out -"close notify" alert messages using L -for a clean shutdown. - -When setting the "quiet shutdown" flag to 1, L -will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN. -(L then behaves like -L called with -SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.) -The session is thus considered to be shutdown, but no "close notify" alert -is sent to the peer. This behaviour violates the TLS standard. - -The default is normal shutdown behaviour as described by the TLS standard. - -=head1 RETURN VALUES - -SSL_CTX_set_quiet_shutdown() and SSL_set_quiet_shutdown() do not return -diagnostic information. - -SSL_CTX_get_quiet_shutdown() and SSL_get_quiet_shutdown return the current -setting. - -=head1 SEE ALSO - -L, L, -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.3 new file mode 100644 index 0000000000..e7ebe2190e --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.3 @@ -0,0 +1,140 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod deleted file mode 100644 index fe8ec09aee..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_cache_mode.pod +++ /dev/null @@ -1,138 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_session_cache_mode, SSL_CTX_get_session_cache_mode - enable/disable -session caching - -=head1 SYNOPSIS - - #include - - long SSL_CTX_set_session_cache_mode(SSL_CTX ctx, long mode); - long SSL_CTX_get_session_cache_mode(SSL_CTX ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_session_cache_mode() enables/disables session caching -by setting the operational mode for B to . - -SSL_CTX_get_session_cache_mode() returns the currently used cache mode. - -=head1 NOTES - -The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse. -The sessions can be held in memory for each B, if more than one -SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX -object. - -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). - -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 (SSL_SESS_CACHE_NO_INTERNAL_LOOKUP), the server will try -the external storage if available. - -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 -L). - -The following session cache modes and modifiers are available: - -=over 4 - -=item SSL_SESS_CACHE_OFF - -No session caching for client or server takes place. - -=item 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 L -function. This option is not activated by default. - -=item 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 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. - -=item SSL_SESS_CACHE_BOTH - -Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time. - -=item SSL_SESS_CACHE_NO_AUTO_CLEAR - -Normally the session cache is checked for expired sessions every -255 connections using the -L function. Since -this may lead to a delay which cannot be controlled, the automatic -flushing may be disabled and -L can be called -explicitly by the application. - -=item 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. - -=item SSL_SESS_CACHE_NO_INTERNAL_STORE - -Depending on the presence of SSL_SESS_CACHE_CLIENT and/or 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 SSL_CTX. This flag will -prevent sessions being stored in the internal cache (though the application can -add them manually using L). Note: -in any SSL/TLS servers where external caching is configured, any successful -session lookups in the external cache (ie. for session-resume requests) would -normally be copied into the local cache before processing continues - this flag -prevents these additions to the internal cache as well. - -=item SSL_SESS_CACHE_NO_INTERNAL - -Enable both SSL_SESS_CACHE_NO_INTERNAL_LOOKUP and -SSL_SESS_CACHE_NO_INTERNAL_STORE at the same time. - - -=back - -The default mode is SSL_SESS_CACHE_SERVER. - -=head1 RETURN VALUES - -SSL_CTX_set_session_cache_mode() returns the previously set cache mode. - -SSL_CTX_get_session_cache_mode() returns the currently set cache mode. - - -=head1 SEE ALSO - -L, L, -L, -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -SSL_SESS_CACHE_NO_INTERNAL_STORE and SSL_SESS_CACHE_NO_INTERNAL -were introduced in OpenSSL 0.9.6h. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.3 new file mode 100644 index 0000000000..0411c687a4 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.3 @@ -0,0 +1,102 @@ +.Dd $Mdocdate: October 12 2014 $ +.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/src/doc/ssl/SSL_CTX_set_session_id_context.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.pod deleted file mode 100644 index 2b1ce18ed9..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_session_id_context.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within -which session can be reused (server side only) - -=head1 SYNOPSIS - - #include - - int SSL_CTX_set_session_id_context(SSL_CTX *ctx, const unsigned char *sid_ctx, - unsigned int sid_ctx_len); - int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx, - unsigned int sid_ctx_len); - -=head1 DESCRIPTION - -SSL_CTX_set_session_id_context() sets the context B of length -B within which a session can be reused for the B object. - -SSL_set_session_id_context() sets the context B of length -B within which a session can be reused for the B object. - -=head1 NOTES - -Sessions are generated within a certain context. When exporting/importing -sessions with B/B 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 B which is used to distinguish -the contexts and is stored in exported sessions. The B can be -any kind of binary data with a given length, it is therefore possible -to use e.g. the name of the application and/or the hostname and/or service -name ... - -The session id context becomes part of the session. The session id context -is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and -SSL_set_session_id_context() functions are therefore only useful on the -server side. - -OpenSSL clients will check the session id context returned by the server -when reusing a session. - -The maximum length of the B is limited to -B. - -=head1 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. - -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. - -=head1 RETURN VALUES - -SSL_CTX_set_session_id_context() and SSL_set_session_id_context() -return the following values: - -=over 4 - -=item C<0> - -The length B of the session id context B exceeded -the maximum allowed length of B. The error -is logged to the error stack. - -=item C<1> - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.3 new file mode 100644 index 0000000000..f3753dac20 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.3 @@ -0,0 +1,78 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_ssl_version.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.pod deleted file mode 100644 index 5ea8f0d4f6..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_ssl_version.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_ssl_version, SSL_set_ssl_method, SSL_get_ssl_method -- choose a new TLS/SSL method - -=head1 SYNOPSIS - - #include - - int SSL_CTX_set_ssl_version(SSL_CTX *ctx, const SSL_METHOD *method); - int SSL_set_ssl_method(SSL *s, const SSL_METHOD *method); - const SSL_METHOD *SSL_get_ssl_method(SSL *ssl); - -=head1 DESCRIPTION - -SSL_CTX_set_ssl_version() sets a new default TLS/SSL B for SSL objects -newly created from this B. SSL objects already created with -L are not affected, except when -L is being called. - -SSL_set_ssl_method() sets a new TLS/SSL B for a particular B -object. It may be reset, when SSL_clear() is called. - -SSL_get_ssl_method() returns a function pointer to the TLS/SSL method -set in B. - -=head1 NOTES - -The available B choices are described in -L. - -When L is called and no session is connected to -an SSL object, the method of the SSL object is reset to the method currently -set in the corresponding SSL_CTX object. - -=head1 RETURN VALUES - -The following return values can occur for SSL_CTX_set_ssl_version() -and SSL_set_ssl_method(): - -=over 4 - -=item C<0> - -The new choice failed, check the error stack to find out the reason. - -=item C<1> - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.3 new file mode 100644 index 0000000000..c8aaee24e2 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.3 @@ -0,0 +1,62 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_timeout.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod deleted file mode 100644 index 4422373fea..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_timeout.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_timeout, SSL_CTX_get_timeout - manipulate timeout values for -session caching - -=head1 SYNOPSIS - - #include - - long SSL_CTX_set_timeout(SSL_CTX *ctx, long t); - long SSL_CTX_get_timeout(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_timeout() sets the timeout for newly created sessions for -B to B. The timeout value B must be given in seconds. - -SSL_CTX_get_timeout() returns the currently set timeout value for B. - -=head1 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. - -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. - -The expiration time of a single session can be modified using the -L family of functions. - -Expired sessions are removed from the internal session cache, whenever -L is called, either -directly by the application or automatically (see -L) - -The default value for session timeout is decided on a per protocol -basis, see L. -All currently supported protocols have the same default timeout value -of 300 seconds. - -=head1 RETURN VALUES - -SSL_CTX_set_timeout() returns the previously set timeout value. - -SSL_CTX_get_timeout() returns the currently set timeout value. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.3 new file mode 100644 index 0000000000..f28d083f45 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.3 @@ -0,0 +1,233 @@ +.Dd $Mdocdate: October 12 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 dhparam 1 +application. +In order to reduce the computer time needed for this generation, +it is possible to use DSA parameters instead (see +.Xr dhparam 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 dhparam 1 +application. +Authors may also generate their own set of parameters using +.Xr dhparam 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 ciphers 1 , +.Xr dhparam 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/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod deleted file mode 100644 index 0fda967814..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod +++ /dev/null @@ -1,169 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, -SSL_set_tmp_dh - handle DH keys for ephemeral key exchange - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, - DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); - - void SSL_set_tmp_dh_callback(SSL *ssl, - DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_set_tmp_dh(SSL *ssl, DH *dh) - -=head1 DESCRIPTION - -SSL_CTX_set_tmp_dh_callback() sets the callback function for B to be -used when a DH parameters are required to B. -The callback is inherited by all B objects created from B. - -SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B. -The key is inherited by all B objects created from B. - -SSL_set_tmp_dh_callback() sets the callback only for B. - -SSL_set_tmp_dh() sets the parameters only for B. - -These functions apply to SSL/TLS servers only. - -=head1 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. - -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. - -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 SSL_OP_SINGLE_DH_USE option of -L is set. It will -immediately create a DH key, when DH parameters are supplied via -SSL_CTX_set_tmp_dh() and 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. - -If "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 "strong" primes were used (see especially -the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used -in order to prevent small subgroup attacks. Always using 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 to always enable -this option. - -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 L application. In order to reduce the computer -time needed for this generation, it is possible to use DSA parameters -instead (see L), but in this case SSL_OP_SINGLE_DH_USE -is mandatory. - -Application authors may compile in DH parameters. Files dh512.pem, -dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current -version of the OpenSSL distribution contain the 'SKIP' DH parameters, -which use safe primes and were generated verifiably pseudo-randomly. -These files can be converted into C code using the B<-C> option of the -L application. -Authors may also generate their own set of parameters using -L, but a user may not be sure how the parameters were -generated. The generation of DH parameters during installation is therefore -recommended. - -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. - -The B is called with the B needed and -the B information. The B flag is set, when the -ephemeral DH key exchange is performed with an export cipher. - -=head1 EXAMPLES - -Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling -partly left out.) - - ... - /* 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); - } - -=head1 RETURN VALUES - -SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return -diagnostic output. - -SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 -on failure. Check the error queue to find out the reason of failure. - -=head1 SEE ALSO - -L, L, -L, -L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.3 new file mode 100644 index 0000000000..55b3aaafed --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.3 @@ -0,0 +1,228 @@ +.Dd $Mdocdate: October 12 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 ciphers 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/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod deleted file mode 100644 index 003dfdb73e..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod +++ /dev/null @@ -1,168 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, -SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys -for ephemeral key exchange - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx, - RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa); - long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx); - - void SSL_set_tmp_rsa_callback(SSL_CTX *ctx, - RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength)); - long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa) - long SSL_need_tmp_rsa(SSL *ssl) - - RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength); - -=head1 DESCRIPTION - -SSL_CTX_set_tmp_rsa_callback() sets the callback function for B to be -used when a temporary/ephemeral RSA key is required to B. -The callback is inherited by all SSL objects newly created from B -with . Already created SSL objects are not affected. - -SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be -B. The key is inherited by all SSL objects newly created from B -with . Already created SSL objects are not affected. - -SSL_CTX_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed -for RSA-based strength-limited 'exportable' ciphersuites because a RSA key -with a keysize larger than 512 bits is installed. - -SSL_set_tmp_rsa_callback() sets the callback only for B. - -SSL_set_tmp_rsa() sets the key only for B. - -SSL_need_tmp_rsa() returns 1, if a temporary/ephemeral RSA key is needed, -for RSA-based strength-limited 'exportable' ciphersuites because a RSA key -with a keysize larger than 512 bits is installed. - -These functions apply to SSL/TLS servers only. - -=head1 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. - -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. - -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. - -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 -L). - -On OpenSSL servers ephemeral RSA key exchange is therefore disabled by default -and must be explicitly enabled using the SSL_OP_EPHEMERAL_RSA option of -L, violating the TLS/SSL -standard. When ephemeral RSA key exchange is required for export ciphers, -it will automatically be used without this option! - -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. As the -generation of a RSA key is however 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 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. - -The B is called with the B needed and -the B information. The B flag is set, when the -ephemeral RSA key exchange is performed with an export cipher. - -=head1 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 saved for later -reuse. For demonstration purposes, two keys for 512 bits and 1024 bits -respectively are generated. - - ... - /* 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 - rsa_tmp=rsa_512; /* Use at least a shorter key */ - } - return(rsa_tmp); - } - -=head1 RETURN VALUES - -SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return -diagnostic output. - -SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0 -on failure. Check the error queue to find out the reason of failure. - -SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary -RSA key is needed and 0 otherwise. - -=head1 SEE ALSO - -L, L, -L, -L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 new file mode 100644 index 0000000000..6ce2e60089 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 @@ -0,0 +1,412 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_set_verify.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod deleted file mode 100644 index 0af8e69441..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.pod +++ /dev/null @@ -1,295 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, -SSL_set_verify_depth - set peer certificate verification parameters - -=head1 SYNOPSIS - - #include - - void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, - int (*verify_callback)(int, X509_STORE_CTX *)); - void SSL_set_verify(SSL *s, int mode, - int (*verify_callback)(int, X509_STORE_CTX *)); - void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); - void SSL_set_verify_depth(SSL *s, int depth); - - int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); - -=head1 DESCRIPTION - -SSL_CTX_set_verify() sets the verification flags for B to be B and -specifies the B function to be used. If no callback function -shall be specified, the NULL pointer can be used for B. - -SSL_set_verify() sets the verification flags for B to be B and -specifies the B function to be used. If no callback function -shall be specified, the NULL pointer can be used for B. In -this case last B set specifically for this B remains. If -no special B was set before, the default callback for the underlying -B is used, that was valid at the time B was created with -L. - -SSL_CTX_set_verify_depth() sets the maximum B for the certificate chain -verification that shall be allowed for B. (See the BUGS section.) - -SSL_set_verify_depth() sets the maximum B for the certificate chain -verification that shall be allowed for B. (See the BUGS section.) - -=head1 NOTES - -The verification of certificates can be controlled by a set of logically -or'ed B flags: - -=over 4 - -=item SSL_VERIFY_NONE - -B the server will not send a client certificate request to the -client, so the client will not send a certificate. - -B 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 L function. -The handshake will be continued regardless of the verification result. - -=item SSL_VERIFY_PEER - -B 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 -SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. - -B 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, SSL_VERIFY_PEER is ignored. - -=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT - -B if the client did not return a certificate, the TLS/SSL -handshake is immediately terminated with a "handshake failure" alert. -This flag must be used together with SSL_VERIFY_PEER. - -B ignored - -=item SSL_VERIFY_CLIENT_ONCE - -B 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 SSL_VERIFY_PEER. - -B ignored - -=back - -Exactly one of the B flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be -set at any time. - -The actual verification procedure is performed either using the built-in -verification procedure or using another application provided verification -function set with -L. -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 verify_callback() function, but the way this information is used -may be different. - -SSL_CTX_set_verify_depth() and 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 -X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. -The depth count is "level 0:peer certificate", "level 1: CA certificate", -"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 additional 100 CA certificates. - -The B function is used to control the behaviour when the -SSL_VERIFY_PEER flag is set. It must be supplied by the application and -receives two arguments: B indicates, whether the verification of -the certificate in question was passed (preverify_ok=1) or not -(preverify_ok=0). B is a pointer to the complete context used -for the certificate chain verification. - -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 B -and B is called with B=0. By applying -X509_CTX_store_* functions B can locate the certificate -in question and perform additional steps (see EXAMPLES). If no error is -found for a certificate, B is called with B=1 -before advancing to the next level. - -The return value of B controls the strategy of the further -verification process. If B returns 0, the verification -process is immediately stopped with "verification failed" state. If -SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and -the TLS/SSL handshake is terminated. If B returns 1, -the verification process is continued. If B 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 -L or by maintaining its -own error storage managed by B. - -If no B is specified, the default callback will be used. -Its return value is identical to B, so that any verification -failure will lead to a termination of the TLS/SSL handshake with an -alert message, if SSL_VERIFY_PEER is set. - -=head1 BUGS - -In client mode, it is not checked whether the SSL_VERIFY_PEER flag -is set, but whether SSL_VERIFY_NONE is not set. This can lead to -unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not -used as required (exactly one must be set at any time). - -The certificate verification depth set with 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 -X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. - -=head1 RETURN VALUES - -The SSL*_set_verify*() functions do not provide diagnostic information. - -=head1 EXAMPLES - -The following code sequence realizes an example B 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. - -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. - -The example makes use of the ex_data technique to store application data -into/retrieve application data from the SSL structure -(see L, -L). - - ... - 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\n", err, - X509_verify_cert_error_string(err), depth, buf); - } - else if (mydata->verbose_mode) - { - printf("depth=%d:%s\n", 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\n", 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 th 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 */ - } - } - -=head1 SEE ALSO - -L, L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.3 new file mode 100644 index 0000000000..eac4d8e42c --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.3 @@ -0,0 +1,333 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 , +.Nm SSL_CTX_use_certificate_chain_file , +.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 "SSL_CTX *ctx" "void *buf" "int len" +.Ft int +.Fn SSL_CTX_use_certificate_chain_file "SSL_CTX *ctx" "const char *file" +.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/src/doc/ssl/SSL_CTX_use_certificate.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod deleted file mode 100644 index 560e00937f..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_use_certificate.pod +++ /dev/null @@ -1,180 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, -SSL_CTX_use_certificate_file, SSL_use_certificate, -SSL_use_certificate_ASN1, SSL_use_certificate_file, -SSL_CTX_use_certificate_chain, SSL_CTX_use_certificate_chain_file, -SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, -SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, -SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, -SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey, -SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, -SSL_CTX_check_private_key, SSL_check_private_key - load certificate and key -data - -=head1 SYNOPSIS - - #include - - int SSL_CTX_use_certificate(SSL_CTX *ctx, X509 *x); - int SSL_CTX_use_certificate_ASN1(SSL_CTX *ctx, int len, unsigned char *d); - int SSL_CTX_use_certificate_file(SSL_CTX *ctx, const char *file, int type); - int SSL_use_certificate(SSL *ssl, X509 *x); - int SSL_use_certificate_ASN1(SSL *ssl, unsigned char *d, int len); - int SSL_use_certificate_file(SSL *ssl, const char *file, int type); - - int SSL_CTX_use_certificate_chain(SSL_CTX *ctx, void *buf, int len); - int SSL_CTX_use_certificate_chain_file(SSL_CTX *ctx, const char *file); - - int SSL_CTX_use_PrivateKey(SSL_CTX *ctx, EVP_PKEY *pkey); - int SSL_CTX_use_PrivateKey_ASN1(int pk, SSL_CTX *ctx, unsigned char *d, - long len); - int SSL_CTX_use_PrivateKey_file(SSL_CTX *ctx, const char *file, int type); - int SSL_CTX_use_RSAPrivateKey(SSL_CTX *ctx, RSA *rsa); - int SSL_CTX_use_RSAPrivateKey_ASN1(SSL_CTX *ctx, unsigned char *d, long len); - int SSL_CTX_use_RSAPrivateKey_file(SSL_CTX *ctx, const char *file, int type); - int SSL_use_PrivateKey(SSL *ssl, EVP_PKEY *pkey); - int SSL_use_PrivateKey_ASN1(int pk,SSL *ssl, unsigned char *d, long len); - int SSL_use_PrivateKey_file(SSL *ssl, const char *file, int type); - int SSL_use_RSAPrivateKey(SSL *ssl, RSA *rsa); - int SSL_use_RSAPrivateKey_ASN1(SSL *ssl, unsigned char *d, long len); - int SSL_use_RSAPrivateKey_file(SSL *ssl, const char *file, int type); - - int SSL_CTX_check_private_key(const SSL_CTX *ctx); - int SSL_check_private_key(const SSL *ssl); - -=head1 DESCRIPTION - -These functions load the certificates and private keys into the SSL_CTX -or SSL object, respectively. - -The SSL_CTX_* class of functions loads the certificates and keys into the -SSL_CTX object B. The information is passed to SSL objects B -created from B with L by copying, so that -changes applied to B do not propagate to already existing SSL objects. - -The SSL_* class of functions only loads certificates and keys into a -specific SSL object. The specific information is kept, when -L is called for this SSL object. - -SSL_CTX_use_certificate() loads the certificate B into B, -SSL_use_certificate() loads B into B. The rest of the -certificates needed to form the complete certificate chain can be -specified using the -L -function. - -SSL_CTX_use_certificate_ASN1() loads the ASN1 encoded certificate from -the memory location B (with length B) into B, -SSL_use_certificate_ASN1() loads the ASN1 encoded certificate into B. - -SSL_CTX_use_certificate_file() loads the first certificate stored in B -into B. The formatting B of the certificate must be specified -from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. -SSL_use_certificate_file() loads the certificate from B into B. -See the NOTES section on why SSL_CTX_use_certificate_chain_file() -should be preferred. - -The SSL_CTX_use_certificate_chain*() functions load a certificate chain -into B. 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 SSL object. - -SSL_CTX_use_PrivateKey() adds B as private key to B. -SSL_CTX_use_RSAPrivateKey() adds the private key B of type RSA -to B. SSL_use_PrivateKey() adds B as private key to B; -SSL_use_RSAPrivateKey() adds B as private key of type RSA to B. -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 SSL_use_certificate() -or SSL_CTX_use_certificate() before setting the private key with -SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey(). - - -SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B -stored at memory location B (length B) to B. -SSL_CTX_use_RSAPrivateKey_ASN1() adds the private key of type RSA -stored at memory location B (length B) to B. -SSL_use_PrivateKey_ASN1() and SSL_use_RSAPrivateKey_ASN1() add the private -key to B. - -SSL_CTX_use_PrivateKey_file() adds the first private key found in -B to B. The formatting B of the certificate must be specified -from the known types SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1. -SSL_CTX_use_RSAPrivateKey_file() adds the first private RSA key found in -B to B. SSL_use_PrivateKey_file() adds the first private key found -in B to B; SSL_use_RSAPrivateKey_file() adds the first private -RSA key found to B. - -SSL_CTX_check_private_key() checks the consistency of a private key with -the corresponding certificate loaded into B. 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. SSL_check_private_key() performs -the same check for B. If no key/certificate was explicitly added for -this B, the last item added into B will be checked. - -=head1 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 L. - -When reading certificates and private keys from file, files of type -SSL_FILETYPE_ASN1 (also known as B, binary encoding) can only contain -one certificate or private key, consequently -SSL_CTX_use_certificate_chain_file() is only applicable to PEM formatting. -Files of type SSL_FILETYPE_PEM can contain more than one item. - -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 -L. -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 -SSL_CTX_use_certificate_chain_file() instead of the -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. - -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 -L. - -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 -L. -(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.) - -=head1 RETURN VALUES - -On success, the functions return 1. -Otherwise check out the error stack to find out the reason. - -=head1 SEE ALSO - -L, L, L, -L, -L, -L, -L, -L - -=head1 HISTORY - -Support for DER encoded private keys (SSL_FILETYPE_ASN1) in -SSL_CTX_use_PrivateKey_file() and SSL_use_PrivateKey_file() was added -in 0.9.8 . - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.3 b/src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.3 new file mode 100644 index 0000000000..4d4e8a6173 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.3 @@ -0,0 +1,107 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.pod deleted file mode 100644 index 9f88d284d2..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_CTX_use_psk_identity_hint.pod +++ /dev/null @@ -1,106 +0,0 @@ -=pod - -=begin comment - -Copyright 2005 Nokia. All rights reserved. - -The portions of the attached software ("Contribution") is developed by -Nokia Corporation and is licensed pursuant to the OpenSSL open source -license. - -The Contribution, originally written by Mika Kousa and Pasi Eronen of -Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites -support (see RFC 4279) to OpenSSL. - -No patent licenses or other rights except those expressly stated in -the OpenSSL open source license shall be deemed granted or received -expressly, by implication, estoppel, or otherwise. - -No assurances are provided by Nokia that the Contribution does not -infringe the patent or other intellectual property rights of any third -party or that the license provides you with all the necessary rights -to make use of the Contribution. - -THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN -ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA -SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY -OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR -OTHERWISE. - -=end comment - -=head1 NAME - -SSL_CTX_use_psk_identity_hint, SSL_use_psk_identity_hint, -SSL_CTX_set_psk_server_callback, SSL_set_psk_server_callback - set PSK -identity hint to use - - -=head1 SYNOPSIS - - #include - - int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint); - int SSL_use_psk_identity_hint(SSL *ssl, const char *hint); - - void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, - unsigned int (*callback)(SSL *ssl, const char *identity, - unsigned char *psk, int max_psk_len)); - void SSL_set_psk_server_callback(SSL *ssl, - unsigned int (*callback)(SSL *ssl, const char *identity, - unsigned char *psk, int max_psk_len)); - - -=head1 DESCRIPTION - -SSL_CTX_use_psk_identity_hint() sets the given B-terminated PSK -identity hint B to SSL context object -B. SSL_use_psk_identity_hint() sets the given B-terminated -PSK identity hint B to SSL connection object B. If B -is B the current hint from B or B is deleted. - -In the case where PSK identity hint is B, the server -does not send the ServerKeyExchange message to the client. - -A server application must provide a callback function which is called -when the server receives the 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 -SSL_CTX_set_psk_server_callback() or -SSL_set_psk_server_callback(). The callback function is given the -connection in parameter B, B-terminated PSK identity sent -by the client in parameter B, and a buffer B of length -B bytes where the pre-shared key is to be stored. - - -=head1 RETURN VALUES - -SSL_CTX_use_psk_identity_hint() and SSL_use_psk_identity_hint() return -1 on success, 0 otherwise. - -Return values from the server callback are interpreted as follows: - -=over 4 - -=item C 0> - -PSK identity was found and the server callback has provided the PSK -successfully in parameter B. Return value is the length of -B in bytes. It is an error to return a value greater than -B. - -If the PSK identity was not found but the callback instructs the -protocol to continue anyway, the callback must provide some random -data to B and return the length of the random data, so the -connection will fail with decryption_error before it will be finished -completely. - -=item C<0> - -PSK identity was not found. An "unknown_psk_identity" alert message -will be sent and the connection setup fails. - -=back - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_SESSION_free.3 b/src/lib/libssl/src/doc/ssl/SSL_SESSION_free.3 new file mode 100644 index 0000000000..f7d2350b55 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_SESSION_free.3 @@ -0,0 +1,76 @@ +.Dd $Mdocdate: October 12 2014 $ +.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. +.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/src/doc/ssl/SSL_SESSION_free.pod b/src/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod deleted file mode 100644 index 110ec73ab6..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_SESSION_free.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_free - free an allocated SSL_SESSION structure - -=head1 SYNOPSIS - - #include - - void SSL_SESSION_free(SSL_SESSION *session); - -=head1 DESCRIPTION - -SSL_SESSION_free() decrements the reference count of B and removes -the B structure pointed to by B and frees up the allocated -memory, if the reference count has reached 0. - -=head1 NOTES - -SSL_SESSION objects are allocated, when a TLS/SSL handshake operation -is successfully completed. Depending on the settings, see -L, -the SSL_SESSION objects are internally referenced by the SSL_CTX and -linked into its session cache. SSL objects may be using the SSL_SESSION object; -as a session may be reused, several SSL objects may be using one SSL_SESSION -object at the same time. It is therefore crucial to keep the reference -count (usage information) correct and not delete a 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 SSL_SESSION object was completely freed as the reference count -incorrectly became 0, but it is still referenced in the internal -session cache and the cache list is processed during a -L operation. - -SSL_SESSION_free() must only be called for SSL_SESSION objects, for -which the reference count was explicitly incremented (e.g. -by calling SSL_get1_session(), see L) -or when the SSL_SESSION object was generated outside a TLS handshake -operation, e.g. by using L. -It must not be called on other SSL_SESSION objects, as this would cause -incorrect reference counts and therefore program failures. - -=head1 RETURN VALUES - -SSL_SESSION_free() does not provide diagnostic information. - -=head1 SEE ALSO - -L, L, -L, -L, - L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.3 b/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.3 new file mode 100644 index 0000000000..d6a94cb0b7 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.3 @@ -0,0 +1,77 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_SESSION_get_ex_new_index.pod b/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.pod deleted file mode 100644 index 1e6bec2314..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_ex_new_index.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data -- internal application specific data functions - -=head1 SYNOPSIS - - #include - - int SSL_SESSION_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg); - - void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, int idx); - - 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); - -=head1 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. - -SSL_SESSION_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_SESSION_set_ex_data() is used to store application data at B for B -into the B object. - -SSL_SESSION_get_ex_data() is used to retrieve the information for B from -B. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L. - -=head1 WARNINGS - -The application data is only maintained for sessions held in memory. The -application data is not included when dumping the session with -i2d_SSL_SESSION() (and all functions indirectly calling the dump functions -like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can -therefore not be restored. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.3 b/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.3 new file mode 100644 index 0000000000..d094adb50a --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.3 @@ -0,0 +1,91 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 +.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/src/doc/ssl/SSL_SESSION_get_time.pod b/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod deleted file mode 100644 index a9b44b3a5c..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_SESSION_get_time.pod +++ /dev/null @@ -1,66 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, -SSL_SESSION_set_timeout - retrieve and manipulate session time and timeout -settings - -=head1 SYNOPSIS - - #include - - long SSL_SESSION_get_time(const SSL_SESSION *s); - long SSL_SESSION_set_time(SSL_SESSION *s, long tm); - long SSL_SESSION_get_timeout(const SSL_SESSION *s); - long SSL_SESSION_set_timeout(SSL_SESSION *s, long tm); - - long SSL_get_time(const SSL_SESSION *s); - long SSL_set_time(SSL_SESSION *s, long tm); - long SSL_get_timeout(const SSL_SESSION *s); - long SSL_set_timeout(SSL_SESSION *s, long tm); - -=head1 DESCRIPTION - -SSL_SESSION_get_time() returns the time at which the session B was -established. The time is given in seconds since the Epoch and therefore -compatible to the time delivered by the time() call. - -SSL_SESSION_set_time() replaces the creation time of the session B with -the chosen value B. - -SSL_SESSION_get_timeout() returns the timeout value set for session B -in seconds. - -SSL_SESSION_set_timeout() sets the timeout value for session B in seconds -to B. - -The SSL_get_time(), SSL_set_time(), SSL_get_timeout(), and SSL_set_timeout() -functions are synonyms for the SSL_SESSION_*() counterparts. - -=head1 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 -L. -Using these functions it is possible to extend or shorten the lifetime -of the session. - -=head1 RETURN VALUES - -SSL_SESSION_get_time() and SSL_SESSION_get_timeout() return the currently -valid values. - -SSL_SESSION_set_time() and SSL_SESSION_set_timeout() return 1 on success. - -If any of the function is passed the NULL pointer for the session B, -0 is returned. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_accept.3 b/src/lib/libssl/src/doc/ssl/SSL_accept.3 new file mode 100644 index 0000000000..88bea1fde7 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_accept.3 @@ -0,0 +1,110 @@ +.Dd $Mdocdate: October 12 2014 $ +.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, +except for SGC (Server Gated Cryptography). +For SGC, +.Fn SSL_accept +may return with \(mi1, but +.Fn SSL_get_error +will yield +.Dv SSL_ERROR_WANT_READ/WRITE +and +.Fn SSL_accept +should be called again. +.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/src/doc/ssl/SSL_accept.pod b/src/lib/libssl/src/doc/ssl/SSL_accept.pod deleted file mode 100644 index 42a539d354..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_accept.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake - -=head1 SYNOPSIS - - #include - - int SSL_accept(SSL *ssl); - -=head1 DESCRIPTION - -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 -B by setting an underlying B. - -=head1 NOTES - -The behaviour of SSL_accept() depends on the underlying BIO. - -If the underlying BIO is B, SSL_accept() will only return once the -handshake has been finished or an error occurred, except for SGC (Server -Gated Cryptography). For SGC, SSL_accept() may return with -1, but -SSL_get_error() will yield B and SSL_accept() -should be called again. - -If the underlying BIO is B, SSL_accept() will also return -when the underlying BIO could not satisfy the needs of SSL_accept() -to continue the handshake, indicating the problem by the return value -1. -In this case a call to SSL_get_error() with the -return value of SSL_accept() will yield B or -B. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_accept(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B to find out the reason. - -=item C<1> - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item E0 - -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 BIOs. Call SSL_get_error() with the return value B -to find out the reason. - -=back - -=head1 SEE ALSO - -L, L, -L, L, L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_alert_type_string.3 b/src/lib/libssl/src/doc/ssl/SSL_alert_type_string.3 new file mode 100644 index 0000000000..f4b652bc1a --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_alert_type_string.3 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 * Ns +.Fn SSL_alert_type_string "int value" +.Ft const char * Ns +.Fn SSL_alert_type_string_long "int value" +.Ft const char * Ns +.Fn SSL_alert_desc_string "int value" +.Ft const char * Ns +.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/src/doc/ssl/SSL_alert_type_string.pod b/src/lib/libssl/src/doc/ssl/SSL_alert_type_string.pod deleted file mode 100644 index 0a70a46890..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_alert_type_string.pod +++ /dev/null @@ -1,234 +0,0 @@ -=pod - -=head1 NAME - -SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, -SSL_alert_desc_string_long - get textual description of alert information - -=head1 SYNOPSIS - - #include - - const char *SSL_alert_type_string(int value); - const char *SSL_alert_type_string_long(int value); - - const char *SSL_alert_desc_string(int value); - const char *SSL_alert_desc_string_long(int value); - -=head1 DESCRIPTION - -SSL_alert_type_string() returns a one letter string indicating the -type of the alert specified by B. - -SSL_alert_type_string_long() returns a string indicating the type of the alert -specified by B. - -SSL_alert_desc_string() returns a two letter string as a short form -describing the reason of the alert specified by B. - -SSL_alert_desc_string_long() returns a string describing the reason -of the alert specified by B. - -=head1 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). - -A warning alert is sent, when a non-fatal error condition occurs. The -"close notify" alert is sent as a warning alert. Other examples for -non-fatal errors are certificate errors ("certificate expired", -"unsupported certificate"), 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 on it discretion. - -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. - -=head1 RETURN VALUES - -The following strings can occur for SSL_alert_type_string() or -SSL_alert_type_string_long(): - -=over 4 - -=item "W"/"warning" - -=item "F"/"fatal" - -=item "U"/"unknown" - -This indicates that no support is available for this alert type. -Probably B does not contain a correct alert message. - -=back - -The following strings can occur for SSL_alert_desc_string() or -SSL_alert_desc_string_long(): - -=over 4 - -=item "CN"/"close notify" - -The connection shall be closed. This is a warning alert. - -=item "UM"/"unexpected message" - -An inappropriate message was received. This alert is always fatal -and should never be observed in communication between proper -implementations. - -=item "BM"/"bad record mac" - -This alert is returned if a record is received with an incorrect -MAC. This message is always fatal. - -=item "DF"/"decompression failure" - -The decompression function received improper input (e.g. data -that would expand to excessive length). This message is always -fatal. - -=item "HF"/"handshake failure" - -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. - -=item "NC"/"no certificate" - -A client, that was asked to send a certificate, does not send a certificate -(SSLv3 only). - -=item "BC"/"bad certificate" - -A certificate was corrupt, contained signatures that did not -verify correctly, etc - -=item "UC"/"unsupported certificate" - -A certificate was of an unsupported type. - -=item "CR"/"certificate revoked" - -A certificate was revoked by its signer. - -=item "CE"/"certificate expired" - -A certificate has expired or is not currently valid. - -=item "CU"/"certificate unknown" - -Some other (unspecified) issue arose in processing the -certificate, rendering it unacceptable. - -=item "IP"/"illegal parameter" - -A field in the handshake was out of range or inconsistent with -other fields. This is always fatal. - -=item "DC"/"decryption failed" - -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. - -=item "RO"/"record overflow" - -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. - -=item "CA"/"unknown CA" - -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. - -=item "AD"/"access denied" - -A valid certificate was received, but when access control was -applied, the sender decided not to proceed with negotiation. -This message is always fatal. - -=item "DE"/"decode error" - -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. - -=item "CY"/"decrypt error" - -A handshake cryptographic operation failed, including being -unable to correctly verify a signature, decrypt a key exchange, -or validate a finished message. - -=item "ER"/"export restriction" - -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. - -=item "PV"/"protocol version" - -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. - -=item "IS"/"insufficient security" - -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. - -=item "IE"/"internal error" - -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. - -=item "US"/"user canceled" - -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. - -=item "NR"/"no renegotiation" - -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. - -=item "UP"/"unknown PSK identity" - -Sent by the server to indicate that it does not recognize a PSK -identity or an SRP identity. - -=item "UK"/"unknown" - -This indicates that no description is available for this alert type. -Probably B does not contain a correct alert message. - -=back - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_clear.3 b/src/lib/libssl/src/doc/ssl/SSL_clear.3 new file mode 100644 index 0000000000..dc596ce12a --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_clear.3 @@ -0,0 +1,89 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_clear.pod b/src/lib/libssl/src/doc/ssl/SSL_clear.pod deleted file mode 100644 index e115a07db6..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_clear.pod +++ /dev/null @@ -1,77 +0,0 @@ -=pod - -=head1 NAME - -SSL_clear - reset SSL object to allow another connection - -=head1 SYNOPSIS - - #include - - int SSL_clear(SSL *ssl); - -=head1 DESCRIPTION - -Reset B to allow another connection. All settings (method, ciphers, -BIOs) are kept. - -=head1 NOTES - -SSL_clear is used to prepare an 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 B, it is considered bad and will be removed -from the session cache, as required by RFC2246. A session is considered open, -if L was not called for the connection -or at least L was used to -set the SSL_SENT_SHUTDOWN state. - -If a session was closed cleanly, the session object will be kept and all -settings corresponding. This explicitly means, that e.g. the special method -used during the session will be kept for the next handshake. So if the -session was a TLSv1 session, a SSL client object will use a TLSv1 client -method for the next handshake and a SSL server object will use a TLSv1 -server method, even if SSLv23_*_methods were chosen on startup. This -will might lead to connection failures (see L) -for a description of the method's properties. - -=head1 WARNINGS - -SSL_clear() resets the 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 -L; -L; -L; -L -instead to avoid such failures -(or simply L; L -if session reuse is not desired). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The SSL_clear() operation could not be performed. Check the error stack to -find out the reason. - -=item C<1> - -The SSL_clear() operation was successful. - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_connect.3 b/src/lib/libssl/src/doc/ssl/SSL_connect.3 new file mode 100644 index 0000000000..4f8428c3c9 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_connect.3 @@ -0,0 +1,99 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL_CONNECT 3 +.Os +.Sh NAME +.Nm SSL_connect +.Nd initiate the TLS/SSL handshake with an 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/src/doc/ssl/SSL_connect.pod b/src/lib/libssl/src/doc/ssl/SSL_connect.pod deleted file mode 100644 index 5b21119a91..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_connect.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server - -=head1 SYNOPSIS - - #include - - int SSL_connect(SSL *ssl); - -=head1 DESCRIPTION - -SSL_connect() initiates the TLS/SSL handshake with a server. The communication -channel must already have been set and assigned to the B by setting an -underlying B. - -=head1 NOTES - -The behaviour of SSL_connect() depends on the underlying BIO. - -If the underlying BIO is B, SSL_connect() will only return once the -handshake has been finished or an error occurred. - -If the underlying BIO is B, SSL_connect() will also return -when the underlying BIO could not satisfy the needs of SSL_connect() -to continue the handshake, indicating the problem by the return value -1. -In this case a call to SSL_get_error() with the -return value of SSL_connect() will yield B or -B. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_connect(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B to find out the reason. - -=item C<1> - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item C0> - -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 BIOs. Call SSL_get_error() with the return value B -to find out the reason. - -=back - -=head1 SEE ALSO - -L, L, -L, L, L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_do_handshake.3 b/src/lib/libssl/src/doc/ssl/SSL_do_handshake.3 new file mode 100644 index 0000000000..8e6e0a820b --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_do_handshake.3 @@ -0,0 +1,110 @@ +.Dd $Mdocdate: October 12 2014 $ +.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, +except for SGC (Server Gated Cryptography). +For SGC, +.Fn SSL_do_handshake +may return with \(mi1, but +.Xr SSL_get_error 3 +will yield +.Dv SSL_ERROR_WANT_READ +or +.Dv SSL_ERROR_WANT_WRITE +and +.Fn SSL_do_handshake +should be called again. +.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/src/doc/ssl/SSL_do_handshake.pod b/src/lib/libssl/src/doc/ssl/SSL_do_handshake.pod deleted file mode 100644 index 1ca18d4723..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_do_handshake.pod +++ /dev/null @@ -1,75 +0,0 @@ -=pod - -=head1 NAME - -SSL_do_handshake - perform a TLS/SSL handshake - -=head1 SYNOPSIS - - #include - - int SSL_do_handshake(SSL *ssl); - -=head1 DESCRIPTION - -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 -L or -L. - -=head1 NOTES - -The behaviour of SSL_do_handshake() depends on the underlying BIO. - -If the underlying BIO is B, SSL_do_handshake() will only return -once the handshake has been finished or an error occurred, except for SGC -(Server Gated Cryptography). For SGC, SSL_do_handshake() may return with -1, -but SSL_get_error() will yield B and -SSL_do_handshake() should be called again. - -If the underlying BIO is B, SSL_do_handshake() will also return -when the underlying BIO could not satisfy the needs of SSL_do_handshake() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_do_handshake() will yield B or -B. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_do_handshake(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The TLS/SSL handshake was not successful but was shut down controlled and -by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the -return value B to find out the reason. - -=item C<1> - -The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been -established. - -=item C0> - -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 BIOs. Call SSL_get_error() with the return value B -to find out the reason. - -=back - -=head1 SEE ALSO - -L, L, -L, L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_free.3 b/src/lib/libssl/src/doc/ssl/SSL_free.3 new file mode 100644 index 0000000000..453cd7d424 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_free.3 @@ -0,0 +1,59 @@ +.Dd $Mdocdate: October 12 2014 $ +.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. +.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/src/doc/ssl/SSL_free.pod b/src/lib/libssl/src/doc/ssl/SSL_free.pod deleted file mode 100644 index 61603d833b..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_free.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -SSL_free - free an allocated SSL structure - -=head1 SYNOPSIS - - #include - - void SSL_free(SSL *ssl); - -=head1 DESCRIPTION - -SSL_free() decrements the reference count of B, and removes the SSL -structure pointed to by B and frees up the allocated memory if the -reference count has reached 0. - -=head1 NOTES - -SSL_free() also calls the free()ing procedures for indirectly affected items, if -applicable: the buffering BIO, the read and write BIOs, -cipher lists specially created for this B, the B. -Do not explicitly free these indirectly freed up items before or after -calling SSL_free(), as trying to free things twice may lead to program -failure. - -The ssl session has reference counts from two users: the SSL object, for -which the reference count is removed by SSL_free() and the internal -session cache. If the session is considered bad, because -L was not called for the connection -and L was not used to set the -SSL_SENT_SHUTDOWN state, the session will also be removed -from the session cache as required by RFC2246. - -=head1 RETURN VALUES - -SSL_free() does not provide diagnostic information. - -=head1 SEE ALSO - -L, L, -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.3 b/src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.3 new file mode 100644 index 0000000000..40effb512f --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.3 @@ -0,0 +1,25 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_SSL_CTX.pod b/src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod deleted file mode 100644 index 659c482c79..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_SSL_CTX.pod +++ /dev/null @@ -1,26 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_SSL_CTX - get the SSL_CTX from which an SSL is created - -=head1 SYNOPSIS - - #include - - SSL_CTX *SSL_get_SSL_CTX(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_SSL_CTX() returns a pointer to the SSL_CTX object, from which -B was created with L. - -=head1 RETURN VALUES - -The pointer to the SSL_CTX object is returned. - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_ciphers.3 b/src/lib/libssl/src/doc/ssl/SSL_get_ciphers.3 new file mode 100644 index 0000000000..f836988f39 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_ciphers.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_ciphers.pod b/src/lib/libssl/src/doc/ssl/SSL_get_ciphers.pod deleted file mode 100644 index aecadd9138..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_ciphers.pod +++ /dev/null @@ -1,42 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ciphers, SSL_get_cipher_list - get list of available SSL_CIPHERs - -=head1 SYNOPSIS - - #include - - STACK_OF(SSL_CIPHER) *SSL_get_ciphers(const SSL *ssl); - const char *SSL_get_cipher_list(const SSL *ssl, int priority); - -=head1 DESCRIPTION - -SSL_get_ciphers() returns the stack of available SSL_CIPHERs for B, -sorted by preference. If B is NULL or no ciphers are available, NULL -is returned. - -SSL_get_cipher_list() returns a pointer to the name of the SSL_CIPHER -listed for B with B. If B is NULL, no ciphers are -available, or there are less ciphers than B available, NULL -is returned. - -=head1 NOTES - -The details of the ciphers obtained by SSL_get_ciphers() can be obtained using -the L family of functions. - -Call SSL_get_cipher_list() with B starting from 0 to obtain the -sorted list of available ciphers, until NULL is returned. - -=head1 RETURN VALUES - -See DESCRIPTION - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.3 b/src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.3 new file mode 100644 index 0000000000..9c08a8e17d --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.3 @@ -0,0 +1,58 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_client_CA_list.pod b/src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod deleted file mode 100644 index 8b5ac0df2c..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_client_CA_list.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs - -=head1 SYNOPSIS - - #include - - STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s); - STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for -B using L. - -SSL_get_client_CA_list() returns the list of client CAs explicitly -set for B using SSL_set_client_CA_list() or B's SSL_CTX object with -L, when in -server mode. In client mode, SSL_get_client_CA_list returns the list of -client CAs sent from the server, if any. - -=head1 RETURN VALUES - -SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return -diagnostic information. - -SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return -values: - -=over 4 - -=item STACK_OF(X509_NAMES) - -List of CA names explicitly set (for B or in server mode) or send -by the server (client mode). - -=item NULL - -No client CA list was explicitly set (for B or in server mode) or -the server did not send a list of CAs (client mode). - -=back - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.3 b/src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.3 new file mode 100644 index 0000000000..ec1f2bb7df --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.3 @@ -0,0 +1,49 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_current_cipher.pod b/src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.pod deleted file mode 100644 index 2f69109a7a..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_current_cipher.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name, -SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection - -=head1 SYNOPSIS - - #include - - SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl); - #define SSL_get_cipher(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_name(s) \ - SSL_CIPHER_get_name(SSL_get_current_cipher(s)) - #define SSL_get_cipher_bits(s,np) \ - SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np) - #define SSL_get_cipher_version(s) \ - SSL_CIPHER_get_version(SSL_get_current_cipher(s)) - -=head1 DESCRIPTION - -SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing -the description of the actually used cipher of a connection established with -the B object. - -SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the -name of the currently used cipher. SSL_get_cipher_bits() is a -macro to obtain the number of secret/algorithm bits used and -SSL_get_cipher_version() returns the protocol name. -See L for more details. - -=head1 RETURN VALUES - -SSL_get_current_cipher() returns the cipher actually used or NULL, when -no session has been established. - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.3 b/src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.3 new file mode 100644 index 0000000000..28ab34d5e8 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.3 @@ -0,0 +1,33 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_default_timeout.pod b/src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.pod deleted file mode 100644 index a648a9b82d..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_default_timeout.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_default_timeout - get default session timeout value - -=head1 SYNOPSIS - - #include - - long SSL_get_default_timeout(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_default_timeout() returns the default timeout value assigned to -SSL_SESSION objects negotiated for the protocol valid for B. - -=head1 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 -L, the hardcoded default -timeout for the protocol will be used. - -SSL_get_default_timeout() return this hardcoded value, which is 300 seconds -for all currently supported protocols (SSLv2, SSLv3, and TLSv1). - -=head1 RETURN VALUES - -See description. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_error.3 b/src/lib/libssl/src/doc/ssl/SSL_get_error.3 new file mode 100644 index 0000000000..ad533f68c5 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_error.3 @@ -0,0 +1,166 @@ +.Dd $Mdocdate: October 12 2014 $ +.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 an 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/src/doc/ssl/SSL_get_error.pod b/src/lib/libssl/src/doc/ssl/SSL_get_error.pod deleted file mode 100644 index ba430bd18d..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_error.pod +++ /dev/null @@ -1,113 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_error - obtain result code for TLS/SSL I/O operation - -=head1 SYNOPSIS - - #include - - int SSL_get_error(const SSL *ssl, int ret); - -=head1 DESCRIPTION - -SSL_get_error() returns a result code (suitable for the C "switch" statement) -for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(), -SSL_read(), SSL_peek(), or SSL_write() on B. The value returned by that -TLS/SSL I/O function must be passed to SSL_get_error() in parameter B. - -In addition to B and B, SSL_get_error() inspects the -current thread's OpenSSL error queue. Thus, 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 SSL_get_error() will not work reliably. - -=head1 RETURN VALUES - -The following return values can currently occur: - -=over 4 - -=item SSL_ERROR_NONE - -The TLS/SSL I/O operation completed. This result code is returned -if and only if B 0>. - -=item 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 B -does not necessarily indicate that the underlying transport -has been closed. - -=item SSL_ERROR_WANT_READ, 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 B has data -available for reading (if the result code is B) -or allows writing data (B), then some TLS/SSL -protocol progress will take place, i.e. at least part of an TLS/SSL -record will be read or written. Note that the retry may again lead to -a B or B condition. -There is no fixed upper limit for the number of iterations that -may be necessary until progress becomes visible at application -protocol level. - -For socket Bs (e.g. when SSL_set_fd() was used), select() or -poll() on the underlying socket can be used to find out when the -TLS/SSL I/O function should be retried. - -Caveat: Any TLS/SSL I/O function can lead to either of -B and B. In particular, -SSL_read() or SSL_peek() may want to write data and SSL_write() 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); -SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes. - -=item SSL_ERROR_WANT_CONNECT, 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 connect()/accept(). The SSL function should be -called again when the connection is established. These messages can only -appear with a BIO_s_connect() or BIO_s_accept() BIO, respectively. -In order to find out, when the connection has been successfully established, -on many platforms select() or poll() for writing on the socket file descriptor -can be used. - -=item SSL_ERROR_WANT_X509_LOOKUP - -The operation did not complete because an application callback set by -SSL_CTX_set_client_cert_cb() has asked to be called again. -The TLS/SSL I/O function should be called again later. -Details depend on the application. - -=item 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. ERR_get_error() returns 0), B can be used to find out more -about the error: If B, an EOF was observed that violates -the protocol. If B, the underlying B reported an -I/O error (for socket I/O on Unix systems, consult B for details). - -=item SSL_ERROR_SSL - -A failure in the SSL library occurred, usually a protocol error. The -OpenSSL error queue contains more information on the error. - -=back - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -SSL_get_error() was added in SSLeay 0.8. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.3 b/src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.3 new file mode 100644 index 0000000000..9151f1d989 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.3 @@ -0,0 +1,62 @@ +.Dd $Mdocdate: October 12 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 \(la0 +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/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod b/src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod deleted file mode 100644 index 165c6a5b2c..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure -from X509_STORE_CTX - -=head1 SYNOPSIS - - #include - - int SSL_get_ex_data_X509_STORE_CTX_idx(void); - -=head1 DESCRIPTION - -SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which -the pointer to the SSL object is stored into the X509_STORE_CTX object. - -=head1 NOTES - -Whenever a X509_STORE_CTX object is created for the verification of the -peers certificate during a handshake, a pointer to the SSL object is -stored into the X509_STORE_CTX object to identify the connection affected. -To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can -be used with the correct index. This index is globally the same for all -X509_STORE_CTX objects and can be retrieved using -SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when -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. - -The value depends on other index values defined for X509_STORE_CTX objects -before the SSL index is created. - -=head1 RETURN VALUES - -=over 4 - -=item E=0 - -The index value to access the pointer. - -=item E0 - -An error occurred, check the error stack for a detailed error message. - -=back - -=head1 EXAMPLES - -The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to -access the SSL object for the connection to be accessed during the -verify_callback() when checking the peers certificate. Please check -the example in L, - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.3 b/src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.3 new file mode 100644 index 0000000000..5b1ff19c54 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.3 @@ -0,0 +1,73 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_ex_new_index.pod b/src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.pod deleted file mode 100644 index 394ae1a406..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_ex_new_index.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application -specific data functions - -=head1 SYNOPSIS - - #include - - int SSL_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_set_ex_data(SSL *ssl, int idx, void *arg); - - void *SSL_get_ex_data(const SSL *ssl, int idx); - - 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); - -=head1 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. - -SSL_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_set_ex_data() is used to store application data at B for B into -the B object. - -SSL_get_ex_data() is used to retrieve the information for B from -B. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L. - -=head1 EXAMPLES - -An example on how to use the functionality is included in the example -verify_callback() in L. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_fd.3 b/src/lib/libssl/src/doc/ssl/SSL_get_fd.3 new file mode 100644 index 0000000000..458e73dacc --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_fd.3 @@ -0,0 +1,43 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_fd.pod b/src/lib/libssl/src/doc/ssl/SSL_get_fd.pod deleted file mode 100644 index 19e52d68d0..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_fd.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_fd, SSL_get_rfd, SSL_get_wfd - get file descriptor linked to an SSL object - -=head1 SYNOPSIS - - #include - - int SSL_get_fd(const SSL *ssl); - int SSL_get_rfd(const SSL *ssl); - int SSL_get_wfd(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_fd() returns the file descriptor which is linked to B. -SSL_get_rfd() and 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, SSL_get_fd() will return the file descriptor -of the read channel. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item -1 - -The operation failed, because the underlying BIO is not of the correct type -(suitable for file descriptors). - -=item E=0 - -The file descriptor linked to B. - -=back - -=head1 SEE ALSO - -L, L , L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.3 b/src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.3 new file mode 100644 index 0000000000..850e8cf913 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_peer_cert_chain.pod b/src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.pod deleted file mode 100644 index 059376c76b..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_peer_cert_chain.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_peer_cert_chain - get the X509 certificate chain of the peer - -=head1 SYNOPSIS - - #include - - STACK_OF(X509) *SSL_get_peer_cert_chain(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_peer_cert_chain() returns a pointer to STACK_OF(X509) 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 -L. -If the peer did not present a certificate, NULL is returned. - -=head1 NOTES - -The peer certificate chain is not necessarily available after reusing -a session, in which case a NULL pointer is returned. - -The reference count of the STACK_OF(X509) object is not incremented. -If the corresponding session is freed, the pointer must not be used -any longer. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item 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. - -=item Pointer to a STACK_OF(X509) - -The return value points to the certificate chain presented by the peer. - -=back - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.3 b/src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.3 new file mode 100644 index 0000000000..7e4ab3fccf --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.3 @@ -0,0 +1,50 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_peer_certificate.pod b/src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod deleted file mode 100644 index ef7c8be180..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_peer_certificate.pod +++ /dev/null @@ -1,55 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_peer_certificate - get the X509 certificate of the peer - -=head1 SYNOPSIS - - #include - - X509 *SSL_get_peer_certificate(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_peer_certificate() returns a pointer to the X509 certificate the -peer presented. If the peer did not present a certificate, NULL is returned. - -=head1 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 -L). If an anonymous cipher -is used, no certificates are sent. - -That a certificate is returned does not indicate information about the -verification state, use L -to check the verification state. - -The reference count of the X509 object is incremented by one, so that it -will not be destroyed when the session containing the peer certificate is -freed. The X509 object must be explicitly freed using X509_free(). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No certificate was presented by the peer or no connection was established. - -=item Pointer to an X509 certificate - -The return value points to the certificate presented by the peer. - -=back - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.3 b/src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.3 new file mode 100644 index 0000000000..b3a72cca29 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.3 @@ -0,0 +1,41 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_psk_identity.pod b/src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.pod deleted file mode 100644 index 6fc72b31b4..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_psk_identity.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=begin comment - -Copyright 2005 Nokia. All rights reserved. - -The portions of the attached software ("Contribution") is developed by -Nokia Corporation and is licensed pursuant to the OpenSSL open source -license. - -The Contribution, originally written by Mika Kousa and Pasi Eronen of -Nokia Corporation, consists of the "PSK" (Pre-Shared Key) ciphersuites -support (see RFC 4279) to OpenSSL. - -No patent licenses or other rights except those expressly stated in -the OpenSSL open source license shall be deemed granted or received -expressly, by implication, estoppel, or otherwise. - -No assurances are provided by Nokia that the Contribution does not -infringe the patent or other intellectual property rights of any third -party or that the license provides you with all the necessary rights -to make use of the Contribution. - -THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN -ADDITION TO THE DISCLAIMERS INCLUDED IN THE LICENSE, NOKIA -SPECIFICALLY DISCLAIMS ANY LIABILITY FOR CLAIMS BROUGHT BY YOU OR ANY -OTHER ENTITY BASED ON INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS OR -OTHERWISE. - -=end comment - -=head1 NAME - -SSL_get_psk_identity, SSL_get_psk_identity_hint - get PSK client identity and -hint - - -=head1 SYNOPSIS - - #include - - const char *SSL_get_psk_identity_hint(const SSL *ssl); - const char *SSL_get_psk_identity(const SSL *ssl); - - -=head1 DESCRIPTION - -SSL_get_psk_identity_hint() is used to retrieve the PSK identity hint -used during the connection setup related to SSL object -B. Similarly, SSL_get_psk_identity() is used to retrieve the PSK -identity used during the connection setup. - - -=head1 RETURN VALUES - -If non-B, SSL_get_psk_identity_hint() returns the PSK identity -hint and SSL_get_psk_identity() returns the PSK identity. Both are -B-terminated. SSL_get_psk_identity_hint() may return B if -no PSK identity hint was used during the connection setup. - -Note that the return value is valid only during the lifetime of the -SSL object B. - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_rbio.3 b/src/lib/libssl/src/doc/ssl/SSL_get_rbio.3 new file mode 100644 index 0000000000..a8370d5ef2 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_rbio.3 @@ -0,0 +1,42 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_rbio.pod b/src/lib/libssl/src/doc/ssl/SSL_get_rbio.pod deleted file mode 100644 index 08dea6a6cd..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_rbio.pod +++ /dev/null @@ -1,40 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_rbio, SSL_get_wbio - get BIO linked to an SSL object - -=head1 SYNOPSIS - - #include - - BIO *SSL_get_rbio(SSL *ssl); - BIO *SSL_get_wbio(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_rbio() and SSL_get_wbio() return pointers to the BIOs for the -read or the write channel, which can be different. The reference count -of the BIO is not incremented. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -No BIO was connected to the SSL object - -=item Any other pointer - -The BIO linked to B. - -=back - -=head1 SEE ALSO - -L, L , L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_session.3 b/src/lib/libssl/src/doc/ssl/SSL_get_session.3 new file mode 100644 index 0000000000..fe9a6d48ef --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_session.3 @@ -0,0 +1,94 @@ +.Dd $Mdocdate: October 12 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 * +SSL_get_session "const SSL *ssl" +.Ft SSL_SESSION * +SSL_get0_session "const SSL *ssl" +.Ft SSL_SESSION * +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/src/doc/ssl/SSL_get_session.pod b/src/lib/libssl/src/doc/ssl/SSL_get_session.pod deleted file mode 100644 index 1a30f7bb5f..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_session.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_session, SSL_get0_session, SSL_get1_session - retrieve TLS/SSL session data - -=head1 SYNOPSIS - - #include - - SSL_SESSION *SSL_get_session(const SSL *ssl); - SSL_SESSION *SSL_get0_session(const SSL *ssl); - SSL_SESSION *SSL_get1_session(SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_session() returns a pointer to the B actually used in -B. The reference count of the B is not incremented, so -that the pointer can become invalid by other operations. - -SSL_get0_session() is the same as SSL_get_session(). - -SSL_get1_session() is the same as SSL_get_session(), but the reference -count of the B is incremented by one. - -=head1 NOTES - -The ssl session contains all information required to re-establish the -connection without a new handshake. - -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 L or -L 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 L. - -If the data is to be kept, 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 -L must be explicitly called once -to decrement the reference count again. - -SSL_SESSION objects keep internal link information about the session cache -list, when being inserted into one SSL_CTX object's session cache. -One SSL_SESSION object, regardless of its reference count, must therefore -only be used with one SSL_CTX object (and the SSL objects created -from this SSL_CTX object). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -There is no session available in B. - -=item Pointer to an SSL - -The return value points to the data of an SSL session. - -=back - -=head1 SEE ALSO - -L, L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_verify_result.3 b/src/lib/libssl/src/doc/ssl/SSL_get_verify_result.3 new file mode 100644 index 0000000000..3409dc0698 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_verify_result.3 @@ -0,0 +1,46 @@ +.Dd $Mdocdate: October 12 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 verify 1 . +.El +.Sh SEE ALSO +.Xr verify 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/src/doc/ssl/SSL_get_verify_result.pod b/src/lib/libssl/src/doc/ssl/SSL_get_verify_result.pod deleted file mode 100644 index 55b56a53f9..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_verify_result.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_verify_result - get result of peer certificate verification - -=head1 SYNOPSIS - - #include - - long SSL_get_verify_result(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_verify_result() returns the result of the verification of the -X509 certificate presented by the peer, if any. - -=head1 NOTES - -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 SSL_get_verify_result(). - -The verification result is part of the established session and is restored -when a session is reused. - -=head1 BUGS - -If no peer certificate was presented, the returned result code is -X509_V_OK. This is because no verification error occurred, it does however -not indicate success. SSL_get_verify_result() is only useful in connection -with L. - -=head1 RETURN VALUES - -The following return values can currently occur: - -=over 4 - -=item X509_V_OK - -The verification succeeded or no peer certificate was presented. - -=item Any other value - -Documented in L. - -=back - -=head1 SEE ALSO - -L, L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_get_version.3 b/src/lib/libssl/src/doc/ssl/SSL_get_version.3 new file mode 100644 index 0000000000..f8fe406d44 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_get_version.3 @@ -0,0 +1,32 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_get_version.pod b/src/lib/libssl/src/doc/ssl/SSL_get_version.pod deleted file mode 100644 index 9ae6f25508..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_get_version.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_version - get the protocol version of a connection. - -=head1 SYNOPSIS - - #include - - const char *SSL_get_version(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_get_version() returns the name of the protocol used for the -connection B. - -=head1 RETURN VALUES - -The following strings can be returned: - -=over 4 - -=item SSLv2 - -The connection uses the SSLv2 protocol. - -=item SSLv3 - -The connection uses the SSLv3 protocol. - -=item TLSv1 - -The connection uses the TLSv1.0 protocol. - -=item TLSv1.1 - -The connection uses the TLSv1.1 protocol. - -=item TLSv1.2 - -The connection uses the TLSv1.2 protocol. - -=item unknown - -This indicates that no version has been set (no connection established). - -=back - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_library_init.3 b/src/lib/libssl/src/doc/ssl/SSL_library_init.3 new file mode 100644 index 0000000000..0644ebd987 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_library_init.3 @@ -0,0 +1,51 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_library_init.pod b/src/lib/libssl/src/doc/ssl/SSL_library_init.pod deleted file mode 100644 index 4767c0ba8b..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_library_init.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_library_init, OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms -- initialize SSL library by registering algorithms - -=head1 SYNOPSIS - - #include - - int SSL_library_init(void); - #define OpenSSL_add_ssl_algorithms() SSL_library_init() - #define SSLeay_add_ssl_algorithms() SSL_library_init() - -=head1 DESCRIPTION - -SSL_library_init() registers the available SSL/TLS ciphers and digests. - -OpenSSL_add_ssl_algorithms() and SSLeay_add_ssl_algorithms() are synonyms -for SSL_library_init(). - -=head1 NOTES - -SSL_library_init() must be called before any other action takes place. -SSL_library_init() is not reentrant. - -=head1 WARNING - -SSL_library_init() adds ciphers and digests used directly and indirectly by -SSL/TLS. - -=head1 EXAMPLES - -A typical TLS/SSL application will start with the library initialization, -and provide readable error messages. - - SSL_load_error_strings(); /* readable error messages */ - SSL_library_init(); /* initialize library */ - -=head1 RETURN VALUES - -SSL_library_init() always returns "1", so it is safe to discard the return -value. - -=head1 NOTES - -OpenSSL 0.9.8o and 1.0.0a and later added SHA2 algorithms to SSL_library_init(). -Applications which need to use SHA2 in earlier versions of OpenSSL should call -OpenSSL_add_all_algorithms() as well. - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.3 b/src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.3 new file mode 100644 index 0000000000..52d21e8e31 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.3 @@ -0,0 +1,50 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_load_client_CA_file.pod b/src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.pod deleted file mode 100644 index 5aa2b73447..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_load_client_CA_file.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -SSL_load_client_CA_file - load certificate names from file - -=head1 SYNOPSIS - - #include - - STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file); - -=head1 DESCRIPTION - -SSL_load_client_CA_file() reads certificates from B and returns -a STACK_OF(X509_NAME) with the subject names found. - -=head1 NOTES - -SSL_load_client_CA_file() reads a file of PEM formatted certificates and -extracts the X509_NAMES of the certificates found. While the name suggests -the specific usage as support function for -L, -it is not limited to CA certificates. - -=head1 EXAMPLES - -Load names of CAs from file and use it as a client CA list: - - 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(); - ... - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -The operation failed, check out the error stack for the reason. - -=item Pointer to STACK_OF(X509_NAME) - -Pointer to the subject names of the successfully read certificates. - -=back - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_new.3 b/src/lib/libssl/src/doc/ssl/SSL_new.3 new file mode 100644 index 0000000000..3c5b303bbb --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_new.3 @@ -0,0 +1,38 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_new.pod b/src/lib/libssl/src/doc/ssl/SSL_new.pod deleted file mode 100644 index 25300e978f..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_new.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -SSL_new - create a new SSL structure for a connection - -=head1 SYNOPSIS - - #include - - SSL *SSL_new(SSL_CTX *ctx); - -=head1 DESCRIPTION - -SSL_new() creates a new B structure which is needed to hold the -data for a TLS/SSL connection. The new structure inherits the settings -of the underlying context B: connection method (SSLv2/v3/TLSv1), -options, verification settings, timeout settings. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item NULL - -The creation of a new SSL structure failed. Check the error stack to -find out the reason. - -=item Pointer to an SSL structure - -The return value points to an allocated SSL structure. - -=back - -=head1 SEE ALSO - -L, L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_pending.3 b/src/lib/libssl/src/doc/ssl/SSL_pending.3 new file mode 100644 index 0000000000..e07ba48283 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_pending.3 @@ -0,0 +1,41 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_pending.pod b/src/lib/libssl/src/doc/ssl/SSL_pending.pod deleted file mode 100644 index 43f2874e8b..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_pending.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -SSL_pending - obtain number of readable bytes buffered in an SSL object - -=head1 SYNOPSIS - - #include - - int SSL_pending(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_pending() returns the number of bytes which are available inside -B for immediate read. - -=head1 NOTES - -Data are received in blocks from the peer. Therefore data can be buffered -inside B and are ready for immediate retrieval with -L. - -=head1 RETURN VALUES - -The number of bytes pending is returned. - -=head1 BUGS - -SSL_pending() takes into account only bytes from the TLS/SSL record -that is currently being processed (if any). If the B object's -I flag is set, additional protocol bytes may have been -read containing more TLS/SSL records; these are ignored by -SSL_pending(). - -Up to OpenSSL 0.9.6, SSL_pending() does not check if the record type -of pending data is application data. - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_read.3 b/src/lib/libssl/src/doc/ssl/SSL_read.3 new file mode 100644 index 0000000000..aed39c300f --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_read.3 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_read.pod b/src/lib/libssl/src/doc/ssl/SSL_read.pod deleted file mode 100644 index 57dfbdfc28..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_read.pod +++ /dev/null @@ -1,124 +0,0 @@ -=pod - -=head1 NAME - -SSL_read - read bytes from a TLS/SSL connection. - -=head1 SYNOPSIS - - #include - - int SSL_read(SSL *ssl, void *buf, int num); - -=head1 DESCRIPTION - -SSL_read() tries to read B bytes from the specified B into the -buffer B. - -=head1 NOTES - -If necessary, SSL_read() will negotiate a TLS/SSL session, if -not already explicitly performed by L or -L. If the -peer requests a re-negotiation, it will be performed transparently during -the SSL_read() operation. The behaviour of SSL_read() depends on the -underlying BIO. - -For the transparent negotiation to succeed, the B must have been -initialized to client or server mode. This is being done by calling -L or SSL_set_accept_state() -before the first call to an SSL_read() or L -function. - -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 when a -record has been completely received, it can be processed (decryption and -check of integrity). Therefore data that was not retrieved at the last -call of SSL_read() can still be buffered inside the SSL layer and will be -retrieved on the next call to SSL_read(). If B is higher than the -number of bytes buffered, SSL_read() will return with the bytes buffered. -If no more bytes are in the buffer, SSL_read() will trigger the processing -of the next record. Only when the record has been received and processed -completely, SSL_read() will 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 SSL_read() can succeed. - -If the underlying BIO is B, SSL_read() will only return, once the -read operation has been finished or an error occurred, except when a -renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. -This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the -L call. - -If the underlying BIO is B, SSL_read() will also return -when the underlying BIO could not satisfy the needs of SSL_read() -to continue the operation. In this case a call to -L with the -return value of SSL_read() will yield B or -B. As at any time a re-negotiation is possible, a -call to SSL_read() can also cause write operations! The calling process -then must repeat the call after taking appropriate action to satisfy the -needs of SSL_read(). The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check -for the required condition. When using a buffering BIO, like a BIO pair, data -must be written into or retrieved out of the BIO before being able to continue. - -L can be used to find out whether there -are buffered bytes available for immediate retrieval. In this case -SSL_read() can be called without blocking or actually receiving new -data from the underlying socket. - -=head1 WARNING - -When an SSL_read() operation has to be repeated because of -B or B, it must be repeated -with the same arguments. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C0> - -The read operation was successful; the return value is the number of -bytes actually read from the TLS/SSL connection. - -=item C<0> - -The read operation was not successful. The reason may either be a clean -shutdown due to a "close notify" alert sent by the peer (in which case -the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set -(see L, -L). It is also possible, that -the peer simply shut down the underlying transport and the shutdown is -incomplete. Call SSL_get_error() with the return value B to find out, -whether an error occurred or the connection was shut down cleanly -(SSL_ERROR_ZERO_RETURN). - -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. - -=item C0> - -The read operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B to find out the reason. - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L, L -L, -L, -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_rstate_string.3 b/src/lib/libssl/src/doc/ssl/SSL_rstate_string.3 new file mode 100644 index 0000000000..77fcd06eac --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_rstate_string.3 @@ -0,0 +1,52 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_rstate_string.pod b/src/lib/libssl/src/doc/ssl/SSL_rstate_string.pod deleted file mode 100644 index af72642210..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_rstate_string.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -SSL_rstate_string, SSL_rstate_string_long - get textual description of state of -an SSL object during read operation - -=head1 SYNOPSIS - - #include - - const char *SSL_rstate_string(SSL *ssl); - const char *SSL_rstate_string_long(SSL *ssl); - -=head1 DESCRIPTION - -SSL_rstate_string() returns a 2 letter string indicating the current read state -of the SSL object B. - -SSL_rstate_string_long() returns a string indicating the current read state of -the SSL object B. - -=head1 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, -SSL_rstate_string[_long]() should always return "RD"/"read done". - -This function should only seldom be needed in applications. - -=head1 RETURN VALUES - -SSL_rstate_string() and SSL_rstate_string_long() can return the following -values: - -=over 4 - -=item "RH"/"read header" - -The header of the record is being evaluated. - -=item "RB"/"read body" - -The body of the record is being evaluated. - -=item "RD"/"read done" - -The record has been completely processed. - -=item "unknown"/"unknown" - -The read state is unknown. This should never happen. - -=back - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_session_reused.3 b/src/lib/libssl/src/doc/ssl/SSL_session_reused.3 new file mode 100644 index 0000000000..40a88cd881 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_session_reused.3 @@ -0,0 +1,29 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_session_reused.pod b/src/lib/libssl/src/doc/ssl/SSL_session_reused.pod deleted file mode 100644 index ef30d82e3d..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_session_reused.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -SSL_session_reused - query whether a reused session was negotiated during -handshake - -=head1 SYNOPSIS - - #include - - int SSL_session_reused(SSL *ssl); - -=head1 DESCRIPTION - -Query, whether a reused session was negotiated during the handshake. - -=head1 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 being set that can be -queried by the application. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -A new session was negotiated. - -=item C<1> - -A session was reused. - -=back - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_bio.3 b/src/lib/libssl/src/doc/ssl/SSL_set_bio.3 new file mode 100644 index 0000000000..62bc22370d --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_set_bio.3 @@ -0,0 +1,48 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_set_bio.pod b/src/lib/libssl/src/doc/ssl/SSL_set_bio.pod deleted file mode 100644 index 67c9756d3f..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_set_bio.pod +++ /dev/null @@ -1,34 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_bio - connect the SSL object with a BIO - -=head1 SYNOPSIS - - #include - - void SSL_set_bio(SSL *ssl, BIO *rbio, BIO *wbio); - -=head1 DESCRIPTION - -SSL_set_bio() connects the BIOs B and B for the read and write -operations of the TLS/SSL (encrypted) side of B. - -The SSL engine inherits the behaviour of B and B, respectively. -If a BIO is non-blocking, the B will also have non-blocking behaviour. - -If there was already a BIO connected to B, BIO_free() will be called -(for both the reading and writing side, if different). - -=head1 RETURN VALUES - -SSL_set_bio() cannot fail. - -=head1 SEE ALSO - -L, -L, L, -L, L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_connect_state.3 b/src/lib/libssl/src/doc/ssl/SSL_set_connect_state.3 new file mode 100644 index 0000000000..37e52788a4 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_set_connect_state.3 @@ -0,0 +1,68 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL_SET_CONNECT_STATE 3 +.Os +.Sh NAME +.Nm SSL_set_connect_state , +.Nm SSL_get_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/src/doc/ssl/SSL_set_connect_state.pod b/src/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod deleted file mode 100644 index 1b19067b47..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_set_connect_state.pod +++ /dev/null @@ -1,56 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_connect_state, SSL_get_accept_state - prepare SSL object to work in -client or server mode - -=head1 SYNOPSIS - - #include - - void SSL_set_connect_state(SSL *ssl); - - void SSL_set_accept_state(SSL *ssl); - -=head1 DESCRIPTION - -SSL_set_connect_state() sets B to work in client mode. - -SSL_set_accept_state() sets B to work in server mode. - -=head1 NOTES - -When the SSL_CTX object was created with L, -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 -L or -SSL_set_ssl_method().) - -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. - -When using the L or -L routines, the correct handshake -routines are automatically set. When performing a transparent negotiation -using L or L, the -handshake routines must be explicitly set in advance using either -SSL_set_connect_state() or SSL_set_accept_state(). - -=head1 RETURN VALUES - -SSL_set_connect_state() and SSL_set_accept_state() do not return diagnostic -information. - -=head1 SEE ALSO - -L, L, L, -L, L, -L, L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_fd.3 b/src/lib/libssl/src/doc/ssl/SSL_set_fd.3 new file mode 100644 index 0000000000..94345ae236 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_set_fd.3 @@ -0,0 +1,70 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_set_fd.pod b/src/lib/libssl/src/doc/ssl/SSL_set_fd.pod deleted file mode 100644 index 7f270c9fbc..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_set_fd.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor - -=head1 SYNOPSIS - - #include - - int SSL_set_fd(SSL *ssl, int fd); - int SSL_set_rfd(SSL *ssl, int fd); - int SSL_set_wfd(SSL *ssl, int fd); - -=head1 DESCRIPTION - -SSL_set_fd() sets the file descriptor B as the input/output facility -for the TLS/SSL (encrypted) side of B. B will typically be the -socket file descriptor of a network connection. - -When performing the operation, a B is automatically created to -interface between the B and B. The BIO and hence the SSL engine -inherit the behaviour of B. If B is non-blocking, the B will -also have non-blocking behaviour. - -If there was already a BIO connected to B, BIO_free() will be called -(for both the reading and writing side, if different). - -SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only -for the read channel or the write channel, which can be set independently. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The operation failed. Check the error stack to find out why. - -=item C<1> - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L, L , L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_session.3 b/src/lib/libssl/src/doc/ssl/SSL_set_session.3 new file mode 100644 index 0000000000..3721b0e0e6 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_set_session.3 @@ -0,0 +1,65 @@ +.Dd $Mdocdate: October 12 2014 $ +.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/src/doc/ssl/SSL_set_session.pod b/src/lib/libssl/src/doc/ssl/SSL_set_session.pod deleted file mode 100644 index d35e6d3b7b..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_set_session.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_session - set a TLS/SSL session to be used during TLS/SSL connect - -=head1 SYNOPSIS - - #include - - int SSL_set_session(SSL *ssl, SSL_SESSION *session); - -=head1 DESCRIPTION - -SSL_set_session() sets B to be used when the TLS/SSL connection -is to be established. SSL_set_session() is only useful for TLS/SSL clients. -When the session is set, the reference count of B is incremented -by 1. If the session is not reused, the reference count is decremented -again during SSL_connect(). Whether the session was reused can be queried -with the L call. - -If there is already a session set inside B (because it was set with -SSL_set_session() before or because the same B was already used for -a connection), SSL_SESSION_free() will be called for that session. - -=head1 NOTES - -SSL_SESSION objects keep internal link information about the session cache -list, when being inserted into one SSL_CTX object's session cache. -One SSL_SESSION object, regardless of its reference count, must therefore -only be used with one SSL_CTX object (and the SSL objects created -from this SSL_CTX object). - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The operation failed; check the error stack to find out the reason. - -=item C<1> - -The operation succeeded. - -=back - -=head1 SEE ALSO - -L, L, -L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_shutdown.3 b/src/lib/libssl/src/doc/ssl/SSL_set_shutdown.3 new file mode 100644 index 0000000000..239bbd6801 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_set_shutdown.3 @@ -0,0 +1,85 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_set_shutdown.pod b/src/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod deleted file mode 100644 index f84da386a1..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_set_shutdown.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_shutdown, SSL_get_shutdown - manipulate shutdown state of an SSL -connection - -=head1 SYNOPSIS - - #include - - void SSL_set_shutdown(SSL *ssl, int mode); - - int SSL_get_shutdown(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_set_shutdown() sets the shutdown state of B to B. - -SSL_get_shutdown() returns the shutdown mode of B. - -=head1 NOTES - -The shutdown state of an ssl connection is a bitmask of: - -=over 4 - -=item Z<>0 - -No shutdown setting, yet. - -=item SSL_SENT_SHUTDOWN - -A "close notify" shutdown alert was sent to the peer, the connection is being -considered closed and the session is closed and correct. - -=item SSL_RECEIVED_SHUTDOWN - -A shutdown alert was received form the peer, either a normal "close notify" -or a fatal error. - -=back - -SSL_SENT_SHUTDOWN and SSL_RECEIVED_SHUTDOWN can be set at the same time. - -The shutdown state of the connection is used to determine the state of -the ssl session. If the session is still open, when -L or L is called, -it is considered bad and removed according to RFC2246. -The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN -(according to the TLS RFC, it is acceptable to only send the "close notify" -alert but to not wait for the peer's answer, when the underlying connection -is closed). -SSL_set_shutdown() can be used to set this state without sending a -close alert to the peer (see L). - -If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set, -for setting SSL_SENT_SHUTDOWN the application must however still call -L or SSL_set_shutdown() itself. - -=head1 RETURN VALUES - -SSL_set_shutdown() does not return diagnostic information. - -SSL_get_shutdown() returns the current setting. - -=head1 SEE ALSO - -L, L, -L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_verify_result.3 b/src/lib/libssl/src/doc/ssl/SSL_set_verify_result.3 new file mode 100644 index 0000000000..3c7f0540fb --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_set_verify_result.3 @@ -0,0 +1,39 @@ +.Dd $Mdocdate: October 12 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 verify 1 . +.Sh RETURN VALUES +.Fn SSL_set_verify_result +does not provide a return value. +.Sh SEE ALSO +.Xr verify 1 , +.Xr ssl 3 , +.Xr SSL_get_peer_certificate 3 , +.Xr SSL_get_verify_result 3 diff --git a/src/lib/libssl/src/doc/ssl/SSL_set_verify_result.pod b/src/lib/libssl/src/doc/ssl/SSL_set_verify_result.pod deleted file mode 100644 index 04ab101aad..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_set_verify_result.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -SSL_set_verify_result - override result of peer certificate verification - -=head1 SYNOPSIS - - #include - - void SSL_set_verify_result(SSL *ssl, long verify_result); - -=head1 DESCRIPTION - -SSL_set_verify_result() sets B of the object B to be the -result of the verification of the X509 certificate presented by the peer, -if any. - -=head1 NOTES - -SSL_set_verify_result() overrides the verification result. It only changes -the verification result of the B object. It does not become part of the -established session, so if the session is to be reused later, the original -value will reappear. - -The valid codes for B are documented in L. - -=head1 RETURN VALUES - -SSL_set_verify_result() does not provide a return value. - -=head1 SEE ALSO - -L, L, -L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_shutdown.3 b/src/lib/libssl/src/doc/ssl/SSL_shutdown.3 new file mode 100644 index 0000000000..aa8d483b24 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_shutdown.3 @@ -0,0 +1,201 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_shutdown.pod b/src/lib/libssl/src/doc/ssl/SSL_shutdown.pod deleted file mode 100644 index 50f47c20d7..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_shutdown.pod +++ /dev/null @@ -1,125 +0,0 @@ -=pod - -=head1 NAME - -SSL_shutdown - shut down a TLS/SSL connection - -=head1 SYNOPSIS - - #include - - int SSL_shutdown(SSL *ssl); - -=head1 DESCRIPTION - -SSL_shutdown() shuts down an active TLS/SSL connection. It sends the -"close notify" shutdown alert to the peer. - -=head1 NOTES - -SSL_shutdown() tries to send the "close notify" shutdown alert to the peer. -Whether the operation succeeds or not, the 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. - -The shutdown procedure consists of 2 steps: the sending of the "close notify" -shutdown alert and the reception of the peer's "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 "close notify" alerts) must be -performed, so that the peers stay synchronized. - -SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step -behaviour. - -=over 4 - -=item When the application is the first party to send the "close notify" -alert, SSL_shutdown() will only send the alert and then set the -SSL_SENT_SHUTDOWN flag (so that the session is considered good and will -be kept in cache). SSL_shutdown() will then return with 0. If a unidirectional -shutdown is enough (the underlying connection shall be closed anyway), this -first call to SSL_shutdown() is sufficient. In order to complete the -bidirectional shutdown handshake, SSL_shutdown() must be called again. -The second call will make SSL_shutdown() wait for the peer's "close notify" -shutdown alert. On success, the second call to SSL_shutdown() will return -with 1. - -=item If the peer already sent the "close notify" alert B it was -already processed implicitly inside another function -(L), the SSL_RECEIVED_SHUTDOWN flag is set. -SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN -flag and will immediately return with 1. -Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the -SSL_get_shutdown() (see also L call. - -=back - -It is therefore recommended, to check the return value of SSL_shutdown() -and call 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, SSL_shutdown() will succeed on -the first call. - -The behaviour of SSL_shutdown() additionally depends on the underlying BIO. - -If the underlying BIO is B, SSL_shutdown() will only return once the -handshake step has been finished or an error occurred. - -If the underlying BIO is B, SSL_shutdown() will also return -when the underlying BIO could not satisfy the needs of SSL_shutdown() -to continue the handshake. In this case a call to SSL_get_error() with the -return value of SSL_shutdown() will yield B or -B. The calling process then must repeat the call after -taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a non-blocking socket, -nothing is to be done, but select() can be used to check for the required -condition. When using a buffering BIO, like a BIO pair, data must be written -into or retrieved out of the BIO before being able to continue. - -SSL_shutdown() can be modified to only set the connection to "shutdown" -state but not actually send the "close notify" alert messages, -see L. -When "quiet shutdown" is enabled, SSL_shutdown() will always succeed -and return 1. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C<0> - -The shutdown is not yet finished. Call SSL_shutdown() for a second time, -if a bidirectional shutdown shall be performed. -The output of L may be misleading, as an -erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred. - -=item C<1> - -The shutdown was successfully completed. The "close notify" alert was sent -and the peer's "close notify" alert was received. - -=item C<-1> - -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 BIOs. -Call L with the return value B -to find out the reason. - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L, -L, L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_state_string.3 b/src/lib/libssl/src/doc/ssl/SSL_state_string.3 new file mode 100644 index 0000000000..828b8f351a --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_state_string.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_state_string.pod b/src/lib/libssl/src/doc/ssl/SSL_state_string.pod deleted file mode 100644 index e7611f1aff..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_state_string.pod +++ /dev/null @@ -1,46 +0,0 @@ -=pod - -=head1 NAME - -SSL_state_string, SSL_state_string_long - get textual description of state of -an SSL object - -=head1 SYNOPSIS - - #include - - const char *SSL_state_string(const SSL *ssl); - const char *SSL_state_string_long(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_state_string() returns a 6 letter string indicating the current state -of the SSL object B. - -SSL_state_string_long() returns a string indicating the current state of -the SSL object B. - -=head1 NOTES - -During its use, an SSL objects 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. - -When using non-blocking sockets, the function call performing the handshake -may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition, -so that SSL_state_string[_long]() may be called. - -For both blocking or non-blocking sockets, the details state information -can be used within the info_callback function set with the -SSL_set_info_callback() call. - -=head1 RETURN VALUES - -Detailed description of possible states to be included later. - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_want.3 b/src/lib/libssl/src/doc/ssl/SSL_want.3 new file mode 100644 index 0000000000..5f9d89ea92 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_want.3 @@ -0,0 +1,100 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_want.pod b/src/lib/libssl/src/doc/ssl/SSL_want.pod deleted file mode 100644 index 7ef6cf6ffa..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_want.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -SSL_want, SSL_want_nothing, SSL_want_read, SSL_want_write, SSL_want_x509_lookup -- obtain state information TLS/SSL I/O operation - -=head1 SYNOPSIS - - #include - - int SSL_want(const SSL *ssl); - int SSL_want_nothing(const SSL *ssl); - int SSL_want_read(const SSL *ssl); - int SSL_want_write(const SSL *ssl); - int SSL_want_x509_lookup(const SSL *ssl); - -=head1 DESCRIPTION - -SSL_want() returns state information for the SSL object B. - -The other SSL_want_*() calls are shortcuts for the possible states returned -by SSL_want(). - -=head1 NOTES - -SSL_want() examines the internal state information of the SSL object. Its -return values are similar to that of L. -Unlike L, 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 L. - -The result returned by SSL_want() should always be consistent with -the result of L. - -=head1 RETURN VALUES - -The following return values can currently occur for SSL_want(): - -=over 4 - -=item SSL_NOTHING - -There is no data to be written or to be read. - -=item SSL_WRITING - -There are data in the SSL buffer that must be written to the underlying -B layer in order to complete the actual SSL_*() operation. -A call to L should return -SSL_ERROR_WANT_WRITE. - -=item SSL_READING - -More data must be read from the underlying B layer in order to -complete the actual SSL_*() operation. -A call to L should return -SSL_ERROR_WANT_READ. - -=item SSL_X509_LOOKUP - -The operation did not complete because an application callback set by -SSL_CTX_set_client_cert_cb() has asked to be called again. -A call to L should return -SSL_ERROR_WANT_X509_LOOKUP. - -=back - -SSL_want_nothing(), SSL_want_read(), SSL_want_write(), SSL_want_x509_lookup() -return 1, when the corresponding condition is true or 0 otherwise. - -=head1 SEE ALSO - -L, L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/SSL_write.3 b/src/lib/libssl/src/doc/ssl/SSL_write.3 new file mode 100644 index 0000000000..19dfffae1b --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/SSL_write.3 @@ -0,0 +1,172 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/SSL_write.pod b/src/lib/libssl/src/doc/ssl/SSL_write.pod deleted file mode 100644 index f248f7d740..0000000000 --- a/src/lib/libssl/src/doc/ssl/SSL_write.pod +++ /dev/null @@ -1,109 +0,0 @@ -=pod - -=head1 NAME - -SSL_write - write bytes to a TLS/SSL connection. - -=head1 SYNOPSIS - - #include - - int SSL_write(SSL *ssl, const void *buf, int num); - -=head1 DESCRIPTION - -SSL_write() writes B bytes from the buffer B into the specified -B connection. - -=head1 NOTES - -If necessary, SSL_write() will negotiate a TLS/SSL session, if -not already explicitly performed by L or -L. If the -peer requests a re-negotiation, it will be performed transparently during -the SSL_write() operation. The behaviour of SSL_write() depends on the -underlying BIO. - -For the transparent negotiation to succeed, the B must have been -initialized to client or server mode. This is being done by calling -L or SSL_set_accept_state() -before the first call to an L or SSL_write() function. - -If the underlying BIO is B, 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 SSL_ERROR_WANT_READ may occur. -This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the -L call. - -If the underlying BIO is B, SSL_write() will also return, -when the underlying BIO could not satisfy the needs of SSL_write() -to continue the operation. In this case a call to -L with the -return value of SSL_write() will yield B or -B. As at any time a re-negotiation is possible, a -call to SSL_write() can also cause read operations! The calling process -then must repeat the call after taking appropriate action to satisfy the -needs of SSL_write(). The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check -for the required condition. When using a buffering BIO, like a BIO pair, data -must be written into or retrieved out of the BIO before being able to continue. - -SSL_write() will only return with success, when the complete contents -of B of length B has been written. This default behaviour -can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of -L. When this flag is set, -SSL_write() will also return with success, when a partial write has been -successfully completed. In this case the SSL_write() operation is considered -completed. The bytes are sent and a new 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. - -=head1 WARNING - -When an SSL_write() operation has to be repeated because of -B or B, it must be repeated -with the same arguments. - -When calling SSL_write() with num=0 bytes to be sent the behaviour is -undefined. - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item C0> - -The write operation was successful, the return value is the number of -bytes actually written to the TLS/SSL connection. - -=item C<0> - -The write operation was not successful. Probably the underlying connection -was closed. Call SSL_get_error() with the return value B to find out, -whether an error occurred or the connection was shut down cleanly -(SSL_ERROR_ZERO_RETURN). - -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. - -=item C0> - -The write operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B to find out the reason. - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L, L -L, -L, L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.3 b/src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.3 new file mode 100644 index 0000000000..3a40c32e69 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.3 @@ -0,0 +1,126 @@ +.Dd $Mdocdate: October 12 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/src/doc/ssl/d2i_SSL_SESSION.pod b/src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod deleted file mode 100644 index d817f72b54..0000000000 --- a/src/lib/libssl/src/doc/ssl/d2i_SSL_SESSION.pod +++ /dev/null @@ -1,80 +0,0 @@ -=pod - -=head1 NAME - -d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 -representation - -=head1 SYNOPSIS - - #include - - SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length); - int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); - -=head1 DESCRIPTION - -d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS -session, stored as binary data at location B with length B, into -an SSL_SESSION object. - -i2d_SSL_SESSION() transforms the SSL_SESSION object B into the ASN1 -representation and stores it into the memory location pointed to by B. -The length of the resulting ASN1 representation is returned. If B is -the NULL pointer, only the length is calculated and returned. - -=head1 NOTES - -The SSL_SESSION object is built from several malloc()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. - -When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically -allocated. The reference count is 1, so that the session must be -explicitly removed using L, -unless the SSL_SESSION object is completely taken over, when being called -inside the get_session_cb() (see -L). - -SSL_SESSION objects keep internal link information about the session cache -list, when being inserted into one SSL_CTX object's session cache. -One SSL_SESSION object, regardless of its reference count, must therefore -only be used with one SSL_CTX object (and the SSL objects created -from this SSL_CTX object). - -When using i2d_SSL_SESSION(), the memory location pointed to by B 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 i2d_SSL_SESSION() with -B, and obtain the size needed, then allocate the memory and -call i2d_SSL_SESSION() again. -Note that this will advance the value contained in B<*pp> so it is necessary -to save a copy of the original allocation. -For example: - 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); - } - -=head1 RETURN VALUES - -d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION -object. In case of failure the NULL-pointer is returned and the error message -can be retrieved from the error stack. - -i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. -When the session is not valid, B<0> is returned and no operation is performed. - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libssl/src/doc/ssl/ssl.3 b/src/lib/libssl/src/doc/ssl/ssl.3 new file mode 100644 index 0000000000..901e1fdfc1 --- /dev/null +++ b/src/lib/libssl/src/doc/ssl/ssl.3 @@ -0,0 +1,1317 @@ +.Dd $Mdocdate: October 12 2014 $ +.Dt SSL 3 +.Os +.Sh NAME +.Nm SSL +.Nd OpenSSL SSL/TLS library +.Sh SYNOPSIS +.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 +.Xr ssl 3 +document appeared in OpenSSL 0.9.2. diff --git a/src/lib/libssl/src/doc/ssl/ssl.pod b/src/lib/libssl/src/doc/ssl/ssl.pod deleted file mode 100644 index 6d3ee24e4e..0000000000 --- a/src/lib/libssl/src/doc/ssl/ssl.pod +++ /dev/null @@ -1,758 +0,0 @@ - -=pod - -=head1 NAME - -SSL - OpenSSL SSL/TLS library - -=head1 SYNOPSIS - -=head1 DESCRIPTION - -The OpenSSL B 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. - -At first the library must be initialized; see -L. - -Then an B object is created as a framework to establish -TLS/SSL enabled connections (see L). -Various options regarding certificates, algorithms etc. can be set -in this object. - -When a network connection has been created, it can be assigned to an -B object. After the B object has been created using -L, L or -L can be used to associate the network -connection with the object. - -Then the TLS/SSL handshake is performed using -L or L -respectively. -L and L are used -to read and write data on the TLS/SSL connection. -L can be used to shut down the -TLS/SSL connection. - -=head1 DATA STRUCTURES - -Currently the OpenSSL B library functions deals with the following data -structures: - -=over 4 - -=item B (SSL Method) - -That's a dispatch structure describing the internal B library -methods/functions which implement the various protocol versions (SSLv1, SSLv2 -and TLSv1). It's needed to create an B. - -=item B (SSL Cipher) - -This structure holds the algorithm information for a particular cipher which -are a core part of the SSL/TLS protocol. The available ciphers are configured -on a B basis and the actually used ones are then part of the -B. - -=item B (SSL Context) - -That's the global context structure which is created by a server or client -once per program life-time and which holds mainly default values for the -B structures which are later created for the connections. - -=item B (SSL Session) - -This is a structure containing the current TLS/SSL session details for a -connection: Bs, client and server certificates, keys, etc. - -=item B (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. - -=back - - -=head1 HEADER FILES - -Currently the OpenSSL B library provides the following C header files -containing the prototypes for the data structures and and functions: - -=over 4 - -=item B - -That's the common header file for the SSL/TLS API. Include it into your -program to make the API of the B library available. It internally -includes both more private SSL headers and headers from the B library. -Whenever you need hard-core details on the internals of the SSL API, look -inside this header file. - -=item B - -That's the sub header file dealing with the SSLv2 protocol only. -I. - -=item B - -That's the sub header file dealing with the SSLv3 protocol only. -I. - -=item B - -That's the sub header file dealing with the combined use of the SSLv2 and -SSLv3 protocols. -I. - -=item B - -That's the sub header file dealing with the TLSv1 protocol only. -I. - -=back - -=head1 API FUNCTIONS - -Currently the OpenSSL B library exports 214 API functions. -They are documented in the following: - -=head2 DEALING WITH PROTOCOL METHODS - -Here we document the various API functions which deal with the SSL/TLS -protocol methods defined in B structures. - -=over 4 - -=item const SSL_METHOD *B(void); - -Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. - -=item const SSL_METHOD *B(void); - -Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. - -=item const SSL_METHOD *B(void); - -Constructor for the SSLv2 SSL_METHOD structure for combined client and server. - -=item const SSL_METHOD *B(void); - -Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. - -=item const SSL_METHOD *B(void); - -Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. - -=item const SSL_METHOD *B(void); - -Constructor for the SSLv3 SSL_METHOD structure for combined client and server. - -=item const SSL_METHOD *B(void); - -Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. - -=item const SSL_METHOD *B(void); - -Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. - -=item const SSL_METHOD *B(void); - -Constructor for the TLSv1 SSL_METHOD structure for combined client and server. - -=back - -=head2 DEALING WITH CIPHERS - -Here we document the various API functions which deal with the SSL/TLS -ciphers defined in B structures. - -=over 4 - -=item char *B(SSL_CIPHER *cipher, char *buf, int len); - -Write a string to I (with a maximum size of I) containing a human -readable description of I. Returns I. - -=item int B(SSL_CIPHER *cipher, int *alg_bits); - -Determine the number of bits in I. Because of export crippled ciphers -there are two bits: The bits the algorithm supports in general (stored to -I) and the bits which are actually used (the return value). - -=item const char *B(SSL_CIPHER *cipher); - -Return the internal name of I as a string. These are the various -strings defined by the I, I and I -definitions in the header files. - -=item char *B(SSL_CIPHER *cipher); - -Returns a string like "C" or "C" which indicates the -SSL/TLS protocol version to which I belongs (i.e. where it was defined -in the specification the first time). - -=back - -=head2 DEALING WITH PROTOCOL CONTEXTS - -Here we document the various API functions which deal with the SSL/TLS -protocol context defined in the B structure. - -=over 4 - -=item int B(SSL_CTX *ctx, X509 *x); - -=item long B(SSL_CTX *ctx, X509 *x509); - -=item int B(SSL_CTX *ctx, SSL_SESSION *c); - -=item int B(const SSL_CTX *ctx); - -=item long B(SSL_CTX *ctx, int cmd, long larg, char *parg); - -=item void B(SSL_CTX *s, long t); - -=item void B(SSL_CTX *a); - -=item char *B(SSL_CTX *ctx); - -=item X509_STORE *B(SSL_CTX *ctx); - -=item STACK *B(const SSL_CTX *ctx); - -=item int (*B(SSL_CTX *ctx))(SSL *ssl, X509 **x509, EVP_PKEY **pkey); - -=item char *B(const SSL_CTX *s, int idx); - -=item int B(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) - -=item void (*B(SSL_CTX *ctx))(SSL *ssl, int cb, int ret); - -=item int B(const SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item long B(const SSL_CTX *ctx); - -=item int (*B(const SSL_CTX *ctx))(int ok, X509_STORE_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx, char *CAfile, char *CApath); - -=item long B(SSL_CTX *ctx); - -=item SSL_CTX *B(const SSL_METHOD *meth); - -=item int B(SSL_CTX *ctx, SSL_SESSION *c); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item SSL_SESSION *(*B(SSL_CTX *ctx))(SSL *ssl, unsigned char *data, int len, int *copy); - -=item int (*B(SSL_CTX *ctx)(SSL *ssl, SSL_SESSION *sess); - -=item void (*B(SSL_CTX *ctx)(SSL_CTX *ctx, SSL_SESSION *sess); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *ctx); - -=item void B(SSL_CTX *ctx,t); - -=item void B(SSL_CTX *ctx, SSL_SESSION *(*cb)(SSL *ssl, unsigned char *data, int len, int *copy)); - -=item void B(SSL_CTX *ctx, int (*cb)(SSL *ssl, SSL_SESSION *sess)); - -=item void B(SSL_CTX *ctx, void (*cb)(SSL_CTX *ctx, SSL_SESSION *sess)); - -=item int B(SSL_CTX *ctx); - -=item LHASH *B(SSL_CTX *ctx); - -=item void B(SSL_CTX *ctx, void *arg); - -=item void B(SSL_CTX *ctx, X509_STORE *cs); - -=item void B(SSL_CTX *ctx, int (*cb)(), char *arg) - -=item int B(SSL_CTX *ctx, char *str); - -=item void B(SSL_CTX *ctx, STACK *list); - -=item void B(SSL_CTX *ctx, int (*cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey)); - -=item void B(SSL_CTX *ctx, int (*cb);(void)) - -=item void B(SSL_CTX *ctx, int m); - -=item int B(SSL_CTX *ctx); - -=item int B(SSL_CTX *s, int idx, char *arg); - -=item void B(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret)); - -=item void B(SSL_CTX *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - -=item void B(SSL_CTX *ctx, void *arg); - -=item void B(SSL_CTX *ctx, unsigned long op); - -=item void B(SSL_CTX *ctx, int mode); - -=item void B(SSL_CTX *ctx, int mode); - -=item int B(SSL_CTX *ctx, const SSL_METHOD *meth); - -=item void B(SSL_CTX *ctx, long t); - -=item long B(SSL_CTX* ctx, DH *dh); - -=item long B(SSL_CTX *ctx, DH *(*cb)(void)); - -=item long B(SSL_CTX *ctx, RSA *rsa); - -=item SSL_CTX_set_tmp_rsa_callback - -C(SSL_CTX *B, RSA *(*B)(SSL *B, int B, int B));> - -Sets the callback which will be called when a temporary private key is -required. The B> flag will be set if the reason for needing -a temp key is that an export ciphersuite is in use, in which case, -B> will contain the required keylength in bits. Generate a key of -appropriate size (using ???) and return it. - -=item SSL_set_tmp_rsa_callback - -long B(SSL *ssl, RSA *(*cb)(SSL *ssl, int export, int keylength)); - -The same as B, except it operates on an SSL -session instead of a context. - -=item void B(SSL_CTX *ctx, int mode, int (*cb);(void)) - -=item int B(SSL_CTX *ctx, EVP_PKEY *pkey); - -=item int B(int type, SSL_CTX *ctx, unsigned char *d, long len); - -=item int B(SSL_CTX *ctx, char *file, int type); - -=item int B(SSL_CTX *ctx, RSA *rsa); - -=item int B(SSL_CTX *ctx, unsigned char *d, long len); - -=item int B(SSL_CTX *ctx, char *file, int type); - -=item int B(SSL_CTX *ctx, X509 *x); - -=item int B(SSL_CTX *ctx, int len, unsigned char *d); - -=item int B(SSL_CTX *ctx, char *file, int type); - -=item void B(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); - -=item int B(SSL_CTX *ctx, const char *hint); - -=item void B(SSL_CTX *ctx, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); - - - - -=back - -=head2 DEALING WITH SESSIONS - -Here we document the various API functions which deal with the SSL/TLS -sessions defined in the B structures. - -=over 4 - -=item int B(const SSL_SESSION *a, const SSL_SESSION *b); - -=item void B(SSL_SESSION *ss); - -=item char *B(SSL_SESSION *s); - -=item char *B(const SSL_SESSION *s, int idx); - -=item int B(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) - -=item long B(const SSL_SESSION *s); - -=item long B(const SSL_SESSION *s); - -=item unsigned long B(const SSL_SESSION *a); - -=item SSL_SESSION *B(void); - -=item int B(BIO *bp, const SSL_SESSION *x); - -=item int B(FILE *fp, const SSL_SESSION *x); - -=item void B(SSL_SESSION *s, char *a); - -=item int B(SSL_SESSION *s, int idx, char *arg); - -=item long B(SSL_SESSION *s, long t); - -=item long B(SSL_SESSION *s, long t); - -=back - -=head2 DEALING WITH CONNECTIONS - -Here we document the various API functions which deal with the SSL/TLS -connection defined in the B structure. - -=over 4 - -=item int B(SSL *ssl); - -=item int B(STACK *stack, const char *dir); - -=item int B(STACK *stack, const char *file); - -=item int B(SSL *ssl, X509 *x); - -=item char *B(int value); - -=item char *B(int value); - -=item char *B(int value); - -=item char *B(int value); - -=item int B(const SSL *ssl); - -=item void B(SSL *ssl); - -=item long B(SSL *ssl); - -=item int B(SSL *ssl); - -=item void B(SSL *t, const SSL *f); - -=item long B(SSL *ssl, int cmd, long larg, char *parg); - -=item int B(SSL *ssl); - -=item SSL *B(SSL *ssl); - -=item STACK *B(STACK *sk); - -=item void B(SSL *ssl); - -=item SSL_CTX *B(const SSL *ssl); - -=item char *B(SSL *ssl); - -=item X509 *B(const SSL *ssl); - -=item const char *B(const SSL *ssl); - -=item int B(const SSL *ssl, int *alg_bits); - -=item char *B(const SSL *ssl, int n); - -=item char *B(const SSL *ssl); - -=item char *B(const SSL *ssl); - -=item STACK *B(const SSL *ssl); - -=item STACK *B(const SSL *ssl); - -=item SSL_CIPHER *B(SSL *ssl); - -=item long B(const SSL *ssl); - -=item int B(const SSL *ssl, int i); - -=item char *B(const SSL *ssl, int idx); - -=item int B(void); - -=item int B(long argl, char *argp, int (*new_func);(void), int (*dup_func)(void), void (*free_func)(void)) - -=item int B(const SSL *ssl); - -=item void (*B(const SSL *ssl);)() - -=item STACK *B(const SSL *ssl); - -=item X509 *B(const SSL *ssl); - -=item EVP_PKEY *B(SSL *ssl); - -=item int B(const SSL *ssl); - -=item BIO *B(const SSL *ssl); - -=item int B(const SSL *ssl); - -=item SSL_SESSION *B(const SSL *ssl); - -=item char *B(const SSL *ssl, char *buf, int len); - -=item int B(const SSL *ssl); - -=item const SSL_METHOD *B(SSL *ssl); - -=item int B(const SSL *ssl); - -=item long B(const SSL *ssl); - -=item long B(const SSL *ssl); - -=item int (*B(const SSL *ssl))(int,X509_STORE_CTX *) - -=item int B(const SSL *ssl); - -=item long B(const SSL *ssl); - -=item char *B(const SSL *ssl); - -=item BIO *B(const SSL *ssl); - -=item int B(SSL *ssl); - -=item int B(SSL *ssl); - -=item int B(SSL *ssl); - -=item int B(SSL *ssl); - -=item int B(SSL *ssl); - -=item STACK *B(char *file); - -=item void B(void); - -=item SSL *B(SSL_CTX *ctx); - -=item long B(SSL *ssl); - -=item int B(SSL *ssl, void *buf, int num); - -=item int B(const SSL *ssl); - -=item int B(SSL *ssl, void *buf, int num); - -=item int B(SSL *ssl); - -=item char *B(SSL *ssl); - -=item char *B(SSL *ssl); - -=item long B(SSL *ssl); - -=item void B(SSL *ssl); - -=item void B(SSL *ssl, char *arg); - -=item void B(SSL *ssl, BIO *rbio, BIO *wbio); - -=item int B(SSL *ssl, char *str); - -=item void B(SSL *ssl, STACK *list); - -=item void B(SSL *ssl); - -=item int B(SSL *ssl, int idx, char *arg); - -=item int B(SSL *ssl, int fd); - -=item void B(SSL *ssl, void (*cb);(void)) - -=item void B(SSL *ctx, void (*cb)(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg)); - -=item void B(SSL *ctx, void *arg); - -=item void B(SSL *ssl, unsigned long op); - -=item void B(SSL *ssl, int mode); - -=item void B(SSL *ssl, int yes); - -=item int B(SSL *ssl, int fd); - -=item int B(SSL *ssl, SSL_SESSION *session); - -=item void B(SSL *ssl, int mode); - -=item int B(SSL *ssl, const SSL_METHOD *meth); - -=item void B(SSL *ssl, long t); - -=item void B(SSL *ssl, long t); - -=item void B(SSL *ssl, int mode, int (*callback);(void)) - -=item void B(SSL *ssl, long arg); - -=item int B(SSL *ssl, int fd); - -=item int B(SSL *ssl); - -=item int B(const SSL *ssl); - -=item char *B(const SSL *ssl); - -=item char *B(const SSL *ssl); - -=item long B(SSL *ssl); - -=item int B(SSL *ssl, EVP_PKEY *pkey); - -=item int B(int type, SSL *ssl, unsigned char *d, long len); - -=item int B(SSL *ssl, char *file, int type); - -=item int B(SSL *ssl, RSA *rsa); - -=item int B(SSL *ssl, unsigned char *d, long len); - -=item int B(SSL *ssl, char *file, int type); - -=item int B(SSL *ssl, X509 *x); - -=item int B(SSL *ssl, int len, unsigned char *d); - -=item int B(SSL *ssl, char *file, int type); - -=item int B(const SSL *ssl); - -=item int B(const SSL *ssl); - -=item int B(const SSL *ssl); - -=item int B(const SSL *ssl); - -=item int B(const SSL *ssl); - -=item int B(const SSL *ssl); - -=item int B(SSL *ssl, const void *buf, int num); - -=item void B(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len)); - -=item int B(SSL *ssl, const char *hint); - -=item void B(SSL *ssl, unsigned int (*callback)(SSL *ssl, const char *identity, unsigned char *psk, int max_psk_len)); - -=item const char *B(SSL *ssl); - -=item const char *B(SSL *ssl); - -=back - -=head1 SEE ALSO - -L, L, -L, L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -The L document appeared in OpenSSL 0.9.2 - -=cut - -- cgit v1.2.3-55-g6feb