From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod | 102 +++ openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod | 84 ++ openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod | 128 ++++ .../doc/ssl/SSL_COMP_add_compression_method.pod | 116 +++ openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod | 50 ++ .../doc/ssl/SSL_CONF_CTX_set1_prefix.pod | 58 ++ openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod | 84 ++ .../doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod | 56 ++ openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod | 563 ++++++++++++++ openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod | 51 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod | 158 ++++ .../doc/ssl/SSL_CTX_add_extra_chain_cert.pod | 80 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod | 82 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod | 93 +++ openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod | 43 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod | 384 ++++++++++ openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod | 56 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod | 51 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod | 64 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod | 59 ++ .../doc/ssl/SSL_CTX_has_client_custom_ext.pod | 37 + .../doc/ssl/SSL_CTX_load_verify_locations.pod | 161 ++++ openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod | 218 ++++++ openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod | 85 +++ .../doc/ssl/SSL_CTX_sess_set_cache_size.pod | 62 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod | 96 +++ openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod | 43 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod | 90 +++ openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod | 113 +++ .../doc/ssl/SSL_CTX_set1_verify_cert_store.pod | 100 +++ .../doc/ssl/SSL_CTX_set_alpn_select_cb.pod | 197 +++++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod | 77 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod | 73 ++ .../doc/ssl/SSL_CTX_set_cert_verify_callback.pod | 74 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod | 74 ++ .../doc/ssl/SSL_CTX_set_client_CA_list.pod | 103 +++ .../doc/ssl/SSL_CTX_set_client_cert_cb.pod | 103 +++ .../doc/ssl/SSL_CTX_set_ct_validation_callback.pod | 145 ++++ .../doc/ssl/SSL_CTX_set_ctlog_list_file.pod | 53 ++ .../doc/ssl/SSL_CTX_set_default_passwd_cb.pod | 113 +++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod | 52 ++ .../doc/ssl/SSL_CTX_set_generate_session_id.pod | 139 ++++ .../doc/ssl/SSL_CTX_set_info_callback.pod | 162 ++++ .../doc/ssl/SSL_CTX_set_max_cert_list.pod | 82 ++ .../doc/ssl/SSL_CTX_set_min_proto_version.pod | 73 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod | 114 +++ .../doc/ssl/SSL_CTX_set_msg_callback.pod | 103 +++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod | 307 ++++++++ .../doc/ssl/SSL_CTX_set_psk_client_callback.pod | 63 ++ .../doc/ssl/SSL_CTX_set_quiet_shutdown.pod | 72 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod | 60 ++ .../doc/ssl/SSL_CTX_set_security_level.pod | 169 +++++ .../doc/ssl/SSL_CTX_set_session_cache_mode.pod | 141 ++++ .../doc/ssl/SSL_CTX_set_session_id_context.pod | 92 +++ .../doc/ssl/SSL_CTX_set_split_send_fragment.pod | 132 ++++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod | 70 ++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod | 68 ++ .../doc/ssl/SSL_CTX_set_tlsext_status_cb.pod | 125 +++ .../doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod | 198 +++++ .../doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 137 ++++ openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod | 307 ++++++++ openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod | 180 +++++ .../doc/ssl/SSL_CTX_use_psk_identity_hint.pod | 87 +++ openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod | 56 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod | 78 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod | 42 + .../doc/ssl/SSL_SESSION_get0_hostname.pod | 37 + .../doc/ssl/SSL_SESSION_get0_id_context.pod | 56 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod | 38 + .../doc/ssl/SSL_SESSION_get_compress_id.pod | 39 + openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod | 47 ++ .../doc/ssl/SSL_SESSION_get_protocol_version.pod | 44 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod | 76 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod | 53 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod | 47 ++ openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod | 50 ++ openssl-1.1.0h/doc/ssl/SSL_accept.pod | 82 ++ openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod | 242 ++++++ openssl-1.1.0h/doc/ssl/SSL_check_chain.pod | 94 +++ openssl-1.1.0h/doc/ssl/SSL_clear.pod | 84 ++ openssl-1.1.0h/doc/ssl/SSL_connect.pod | 82 ++ openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod | 81 ++ .../doc/ssl/SSL_export_keying_material.pod | 61 ++ openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod | 145 ++++ openssl-1.1.0h/doc/ssl/SSL_free.pod | 54 ++ openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod | 45 ++ openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod | 35 + openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod | 88 +++ openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod | 84 ++ openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod | 62 ++ openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod | 88 +++ openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod | 55 ++ openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod | 50 ++ openssl-1.1.0h/doc/ssl/SSL_get_error.pod | 143 ++++ openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod | 40 + openssl-1.1.0h/doc/ssl/SSL_get_fd.pod | 53 ++ openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod | 77 ++ .../doc/ssl/SSL_get_peer_certificate.pod | 64 ++ openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod | 44 ++ openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod | 49 ++ openssl-1.1.0h/doc/ssl/SSL_get_session.pod | 82 ++ openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod | 86 +++ openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod | 66 ++ openssl-1.1.0h/doc/ssl/SSL_get_version.pod | 67 ++ openssl-1.1.0h/doc/ssl/SSL_library_init.pod | 57 ++ openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod | 71 ++ openssl-1.1.0h/doc/ssl/SSL_new.pod | 61 ++ openssl-1.1.0h/doc/ssl/SSL_pending.pod | 68 ++ openssl-1.1.0h/doc/ssl/SSL_read.pod | 121 +++ openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod | 68 ++ openssl-1.1.0h/doc/ssl/SSL_session_reused.pod | 54 ++ openssl-1.1.0h/doc/ssl/SSL_set1_host.pod | 121 +++ openssl-1.1.0h/doc/ssl/SSL_set_bio.pod | 108 +++ openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod | 64 ++ openssl-1.1.0h/doc/ssl/SSL_set_fd.pod | 63 ++ openssl-1.1.0h/doc/ssl/SSL_set_session.pod | 70 ++ openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod | 81 ++ openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod | 47 ++ openssl-1.1.0h/doc/ssl/SSL_shutdown.pod | 132 ++++ openssl-1.1.0h/doc/ssl/SSL_state_string.pod | 54 ++ openssl-1.1.0h/doc/ssl/SSL_want.pod | 103 +++ openssl-1.1.0h/doc/ssl/SSL_write.pod | 111 +++ openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod | 49 ++ openssl-1.1.0h/doc/ssl/ssl.pod | 843 +++++++++++++++++++++ 124 files changed, 12524 insertions(+) create mode 100644 openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod create mode 100644 openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_accept.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_check_chain.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_clear.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_connect.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_extension_supported.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_free.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get0_peer_scts.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_SSL_CTX.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_all_async_fds.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_ciphers.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_client_CA_list.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_client_random.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_current_cipher.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_default_timeout.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_error.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_extms_support.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_fd.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_peer_cert_chain.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_peer_certificate.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_psk_identity.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_rbio.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_session.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_shared_sigalgs.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_verify_result.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_get_version.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_library_init.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_load_client_CA_file.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_new.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_pending.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_read.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_rstate_string.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_session_reused.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set1_host.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set_bio.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set_connect_state.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set_fd.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set_session.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set_shutdown.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_set_verify_result.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_shutdown.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_state_string.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_want.pod create mode 100644 openssl-1.1.0h/doc/ssl/SSL_write.pod create mode 100644 openssl-1.1.0h/doc/ssl/d2i_SSL_SESSION.pod create mode 100644 openssl-1.1.0h/doc/ssl/ssl.pod (limited to 'openssl-1.1.0h/doc/ssl') diff --git a/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod b/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod new file mode 100644 index 0000000..a839d9f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/DTLSv1_listen.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +DTLSv1_listen - listen for incoming DTLS connections + +=head1 SYNOPSIS + + #include + + int DTLSv1_listen(SSL *ssl, BIO_ADDR *peer); + +=head1 DESCRIPTION + +DTLSv1_listen() listens for new incoming DTLS connections. If a ClientHello is +received that does not contain a cookie, then DTLSv1_listen() responds with a +HelloVerifyRequest. If a ClientHello is received with a cookie that is verified +then control is returned to user code to enable the handshake to be completed +(for example by using SSL_accept()). + +=head1 NOTES + +Datagram based protocols can be susceptible to Denial of Service attacks. A +DTLS attacker could, for example, submit a series of handshake initiation +requests that cause the server to allocate state (and possibly perform +cryptographic operations) thus consuming server resources. The attacker could +also (with UDP) quite simply forge the source IP address in such an attack. + +As a counter measure to that DTLS includes a stateless cookie mechanism. The +idea is that when a client attempts to connect to a server it sends a +ClientHello message. The server responds with a HelloVerifyRequest which +contains a unique cookie. The client then resends the ClientHello, but this time +includes the cookie in the message thus proving that the client is capable of +receiving messages sent to that address. All of this can be done by the server +without allocating any state, and thus without consuming expensive resources. + +OpenSSL implements this capability via the DTLSv1_listen() function. The B +parameter should be a newly allocated SSL object with its read and write BIOs +set, in the same way as might be done for a call to SSL_accept(). Typically the +read BIO will be in an "unconnected" state and thus capable of receiving +messages from any peer. + +When a ClientHello is received that contains a cookie that has been verified, +then DTLSv1_listen() will return with the B parameter updated into a state +where the handshake can be continued by a call to (for example) SSL_accept(). +Additionally the B pointed to by B will be filled in with +details of the peer that sent the ClientHello. If the underlying BIO is unable +to obtain the B of the peer (for example because the BIO does not +support this), then B<*peer> will be cleared and the family set to AF_UNSPEC. +Typically user code is expected to "connect" the underlying socket to the peer +and continue the handshake in a connected state. + +Prior to calling DTLSv1_listen() user code must ensure that cookie generation +and verification callbacks have been set up using +SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb() +respectively. + +Since DTLSv1_listen() operates entirely statelessly whilst processing incoming +ClientHellos it is unable to process fragmented messages (since this would +require the allocation of state). An implication of this is that DTLSv1_listen() +B supports ClientHellos that fit inside a single datagram. + +=head1 RETURN VALUES + +From OpenSSL 1.1.0 a return value of >= 1 indicates success. In this instance +the B value will be filled in and the B object set up ready to +continue the handshake. + +A return value of 0 indicates a non-fatal error. This could (for +example) be because of non-blocking IO, or some invalid message having been +received from a peer. Errors may be placed on the OpenSSL error queue with +further information if appropriate. Typically user code is expected to retry the +call to DTLSv1_listen() in the event of a non-fatal error. Any old errors on the +error queue will be cleared in the subsequent call. + +A return value of <0 indicates a fatal error. This could (for example) be +because of a failure to allocate sufficient memory for the operation. + +Prior to OpenSSL 1.1.0 fatal and non-fatal errors both produce return codes +<= 0 (in typical implementations user code treats all errors as non-fatal), +whilst return codes >0 indicate success. + +=head1 SEE ALSO + +L, L, +L, L + +=head1 HISTORY + +DTLSv1_listen() return codes were clarified in OpenSSL 1.1.0. The type of "peer" +also changed in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod b/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod new file mode 100644 index 0000000..b963e5e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/OPENSSL_init_ssl.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +OPENSSL_init_ssl - OpenSSL (libssl and libcrypto) initialisation + +=head1 SYNOPSIS + + #include + + int OPENSSL_init_ssl(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); + +=head1 DESCRIPTION + +During normal operation OpenSSL (libssl and libcrypto) will allocate various +resources at start up that must, subsequently, be freed on close down of the +library. Additionally some resources are allocated on a per thread basis (if the +application is multi-threaded), and these resources must be freed prior to the +thread closing. + +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. + +However, there may be situations when explicit initialisation is desirable or +needed, for example when some non-default initialisation is required. The +function OPENSSL_init_ssl() can be used for this purpose. Calling +this function will explicitly initialise BOTH libcrypto and libssl. To +explicitly initialise ONLY libcrypto see the +L function. + +Numerous internal OpenSSL functions call OPENSSL_init_ssl(). +Therefore, in order to perform non-default initialisation, +OPENSSL_init_ssl() MUST be called by application code prior to +any other OpenSSL function calls. + +The B parameter specifies which aspects of libssl and libcrypto should be +initialised. Valid options for libcrypto are described on the +L page. In addition to any libcrypto +specific option the following libssl options can also be used: + +=over 4 + +=item OPENSSL_INIT_NO_LOAD_SSL_STRINGS + +Suppress automatic loading of the libssl error strings. This option is +not a default option. Once selected subsequent calls to +OPENSSL_init_ssl() with the option +B will be ignored. + +=item OPENSSL_INIT_LOAD_SSL_STRINGS + +Automatic loading of the libssl error strings. This option is a +default option. Once selected subsequent calls to +OPENSSL_init_ssl() with the option +B will be ignored. + +=back + +OPENSSL_init_ssl() takes a B parameter which can be used to +set parameter values. See L for details. + +=head1 RETURN VALUES + +The function OPENSSL_init_ssl() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The OPENSSL_init_ssl() function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod b/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod new file mode 100644 index 0000000..b7ee3c8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CIPHER_get_name.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_kx_nid, +SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead, +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); + int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c); + int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c); + int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c); + int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c); + int SSL_CIPHER_is_aead(const SSL_CIPHER *c); + +=head1 DESCRIPTION + +SSL_CIPHER_get_name() returns a pointer to the name of B. If the +B is NULL, it returns "(NONE)". + +SSL_CIPHER_get_bits() returns the number of secret bits used for B. +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. It returns "(NONE)" if B is NULL. + +SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B. +If there is no cipher (e.g. for ciphersuites with no encryption) then +B is returned. + +SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC +used by B. If there is no digest (e.g. for AEAD ciphersuites) then +B is returned. + +SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method +used by B. If there is no key exchange, then B is returned. Examples (not comprehensive): + + NID_kx_rsa + NID_kx_ecdhe + NID_kx_dhe + NID_kx_psk + +SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method +used by B. If there is no authentication, then B is returned. +Examples (not comprehensive): + + NID_auth_rsa + NID_auth_ecdsa + NID_auth_psk + +SSL_CIPHER_is_aead() returns 1 if the cipher B is AEAD (e.g. GCM or +ChaCha20/Poly1305), and 0 if it is not AEAD. + +SSL_CIPHER_description() returns a textual description of the cipher used +into the buffer B of length B provided. If B is provided, it +must be at least 128 bytes, otherwise a buffer will be allocated using +OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails, +B is returned. + +The string returned by SSL_CIPHER_description() consists of several fields +separated by whitespace: + +=over 4 + +=item + +Textual representation of the cipher name. + +=item + +Protocol version, such as B, when the cipher was first defined. + +=item Kx= + +Key exchange method such as B, B, etc. + +=item Au= + +Authentication method such as B, B, etc.. None is the +representation of anonymous ciphers. + +=item Enc= + +Encryption method, with number of secret bits, such as B. + +=item Mac= + +Message digest, such as B. + +=back + +Some examples for the output of SSL_CIPHER_description(): + + ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD + RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384 + +=head1 HISTORY + +SSL_CIPHER_get_version() was updated to always return the correct protocol +string in OpenSSL 1.1. + +SSL_CIPHER_description() was changed to return B on error, +rather than a fixed string, in OpenSSL 1.1 + +=head1 SEE ALSO + +L, L, +L, L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod b/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod new file mode 100644 index 0000000..15929df --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_COMP_add_compression_method.pod @@ -0,0 +1,116 @@ +=pod + +=head1 NAME + +SSL_COMP_add_compression_method, SSL_COMP_get_compression_methods, +SSL_COMP_get0_name, SSL_COMP_get_id, SSL_COMP_free_compression_methods +- handle SSL/TLS integrated compression methods + +=head1 SYNOPSIS + + #include + + int SSL_COMP_add_compression_method(int id, COMP_METHOD *cm); + STACK_OF(SSL_COMP) *SSL_COMP_get_compression_methods(void); + const char *SSL_COMP_get0_name(const SSL_COMP *comp); + int SSL_COMP_get_id(const SSL_COMP *comp); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void SSL_COMP_free_compression_methods(void) + #endif + +=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. + +SSL_COMP_get_compression_methods() returns a stack of all of the available +compression methods or NULL on error. + +SSL_COMP_get0_name() returns the name of the compression method B. + +SSL_COMP_get_id() returns the id of the compression method B. + +In versions of OpenSSL prior to 1.1.0 SSL_COMP_free_compression_methods() freed +the internal table of compression methods that were built internally, and +possibly augmented by adding SSL_COMP_add_compression_method(). However this is +now unnecessary from version 1.1.0. No explicit initialisation or +de-initialisation is necessary. See L and +L. From OpenSSL 1.1.0 calling this function does nothing. + +=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. + +If enabled during compilation, the OpenSSL library will have the +COMP_zlib() compression method 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 Z<>0 + +The operation succeeded. + +=item Z<>1 + +The operation failed. Check the error queue to find out the reason. + +=back + +SSL_COMP_get_compression_methods() returns the stack of compressions methods or +NULL on error. + +SSL_COMP_get0_name() returns the name of the compression method or NULL on error. + +SSL_COMP_get_id() returns the name of the compression method or -1 on error. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +SSL_COMP_free_compression_methods() was deprecated in OpenSSL 1.1.0. +SSL_COMP_get0_name() and SSL_comp_get_id() were added in OpenSSL 1.1.0d. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod new file mode 100644 index 0000000..79f0bbc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_new.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_new, SSL_CONF_CTX_free - SSL configuration allocation functions + +=head1 SYNOPSIS + + #include + + SSL_CONF_CTX *SSL_CONF_CTX_new(void); + void SSL_CONF_CTX_free(SSL_CONF_CTX *cctx); + +=head1 DESCRIPTION + +The function SSL_CONF_CTX_new() allocates and initialises an B +structure for use with the SSL_CONF functions. + +The function SSL_CONF_CTX_free() frees up the context B. +If B is NULL nothing is done. + +=head1 RETURN VALUES + +SSL_CONF_CTX_new() returns either the newly allocated B structure +or B if an error occurs. + +SSL_CONF_CTX_free() does not return a value. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod new file mode 100644 index 0000000..da9e580 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set1_prefix.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_set1_prefix - Set configuration context command prefix + +=head1 SYNOPSIS + + #include + + unsigned int SSL_CONF_CTX_set1_prefix(SSL_CONF_CTX *cctx, const char *prefix); + +=head1 DESCRIPTION + +The function SSL_CONF_CTX_set1_prefix() sets the command prefix of B +to B. If B is B it is restored to the default value. + +=head1 NOTES + +Command prefixes alter the commands recognised by subsequent SSL_CTX_cmd() +calls. For example for files, if the prefix "SSL" is set then command names +such as "SSLProtocol", "SSLOptions" etc. are recognised instead of "Protocol" +and "Options". Similarly for command lines if the prefix is "--ssl-" then +"--ssl-no_tls1_2" is recognised instead of "-no_tls1_2". + +If the B flag is set then prefix checks are case +sensitive and "-" is the default. In the unlikely even an application +explicitly wants to set no prefix it must be explicitly set to "". + +If the B flag is set then prefix checks are case +insensitive and no prefix is the default. + +=head1 RETURN VALUES + +SSL_CONF_CTX_set1_prefix() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod new file mode 100644 index 0000000..efd8da3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_flags.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_set_flags, SSL_CONF_CTX_clear_flags - Set of clear SSL configuration context flags + +=head1 SYNOPSIS + + #include + + unsigned int SSL_CONF_CTX_set_flags(SSL_CONF_CTX *cctx, unsigned int flags); + unsigned int SSL_CONF_CTX_clear_flags(SSL_CONF_CTX *cctx, unsigned int flags); + +=head1 DESCRIPTION + +The function SSL_CONF_CTX_set_flags() sets B in the context B. + +The function SSL_CONF_CTX_clear_flags() clears B in the context B. + +=head1 NOTES + +The flags set affect how subsequent calls to SSL_CONF_cmd() or +SSL_CONF_argv() behave. + +Currently the following B values are recognised: + +=over 4 + +=item SSL_CONF_FLAG_CMDLINE, SSL_CONF_FLAG_FILE + +recognise options intended for command line or configuration file use. At +least one of these flags must be set. + +=item SSL_CONF_FLAG_CLIENT, SSL_CONF_FLAG_SERVER + +recognise options intended for use in SSL/TLS clients or servers. One or +both of these flags must be set. + +=item SSL_CONF_FLAG_CERTIFICATE + +recognise certificate and private key options. + +=item SSL_CONF_FLAG_REQUIRE_PRIVATE + +If this option is set then if a private key is not specified for a certificate +it will attempt to load a private key from the certificate file when +SSL_CONF_CTX_finish() is called. If a key cannot be loaded from the certificate +file an error occurs. + +=item SSL_CONF_FLAG_SHOW_ERRORS + +indicate errors relating to unrecognised options or missing arguments in +the error queue. If this option isn't set such errors are only reflected +in the return values of SSL_CONF_set_cmd() or SSL_CONF_set_argv() + +=back + +=head1 RETURN VALUES + +SSL_CONF_CTX_set_flags() and SSL_CONF_CTX_clear_flags() returns the new flags +value after setting or clearing flags. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod new file mode 100644 index 0000000..7e4120f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_CTX_set_ssl_ctx.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_CONF_CTX_set_ssl_ctx, SSL_CONF_CTX_set_ssl - set context to configure + +=head1 SYNOPSIS + + #include + + void SSL_CONF_CTX_set_ssl_ctx(SSL_CONF_CTX *cctx, SSL_CTX *ctx); + void SSL_CONF_CTX_set_ssl(SSL_CONF_CTX *cctx, SSL *ssl); + +=head1 DESCRIPTION + +SSL_CONF_CTX_set_ssl_ctx() sets the context associated with B to the +B structure B. Any previous B or B associated with +B is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to +B. + +SSL_CONF_CTX_set_ssl() sets the context associated with B to the +B structure B. Any previous B or B associated with +B is cleared. Subsequent calls to SSL_CONF_cmd() will be sent to +B. + +=head1 NOTES + +The context need not be set or it can be set to B in which case only +syntax checking of commands is performed, where possible. + +=head1 RETURN VALUES + +SSL_CONF_CTX_set_ssl_ctx() and SSL_CTX_set_ssl() do not return a value. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod new file mode 100644 index 0000000..a28e218 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd.pod @@ -0,0 +1,563 @@ +=pod + +=head1 NAME + +SSL_CONF_cmd_value_type, SSL_CONF_finish, +SSL_CONF_cmd - send configuration command + +=head1 SYNOPSIS + + #include + + int SSL_CONF_cmd(SSL_CONF_CTX *cctx, const char *cmd, const char *value); + int SSL_CONF_cmd_value_type(SSL_CONF_CTX *cctx, const char *cmd); + int SSL_CONF_finish(SSL_CONF_CTX *cctx); + +=head1 DESCRIPTION + +The function SSL_CONF_cmd() performs configuration operation B with +optional parameter B on B. Its purpose is to simplify application +configuration of B or B structures by providing a common +framework for command line options or configuration files. + +SSL_CONF_cmd_value_type() returns the type of value that B refers to. + +The function SSL_CONF_finish() must be called after all configuration +operations have been completed. It is used to finalise any operations +or to process defaults. + +=head1 SUPPORTED COMMAND LINE COMMANDS + +Currently supported B names for command lines (i.e. when the +flag B is set) are listed below. Note: all B names +are case sensitive. Unless otherwise stated commands can be used by +both clients and servers and the B parameter is not used. The default +prefix for command line commands is B<-> and that is reflected below. + +=over 4 + +=item B<-sigalgs> + +This sets the supported signature algorithms for TLS v1.2. For clients this +value is used directly for the supported signature algorithms extension. For +servers it is used to determine which signature algorithms to support. + +The B argument should be a colon separated list of signature algorithms +in order of decreasing preference of the form B. B +is one of B, B or B and B is a supported algorithm +OID short name such as B, B, B, B of B. +Note: algorithm and hash names are case sensitive. + +If this option is not set then all signature algorithms supported by the +OpenSSL library are permissible. + +=item B<-client_sigalgs> + +This sets the supported signature algorithms associated with client +authentication for TLS v1.2. For servers the value is used in the supported +signature algorithms field of a certificate request. For clients it is +used to determine which signature algorithm to with the client certificate. +If a server does not request a certificate this option has no effect. + +The syntax of B is identical to B<-sigalgs>. If not set then +the value set for B<-sigalgs> will be used instead. + +=item B<-curves> + +This sets the supported elliptic curves. For clients the curves are +sent using the supported curves extension. For servers it is used +to determine which curve to use. This setting affects curves used for both +signatures and key exchange, if applicable. + +The B argument is a colon separated list of curves. The curve can be +either the B name (e.g. B) or an OpenSSL OID name (e.g +B). Curve names are case sensitive. + +=item B<-named_curve> + +This sets the temporary curve used for ephemeral ECDH modes. Only used by +servers + +The B argument is a curve name or the special value B which +picks an appropriate curve based on client and server preferences. The curve +can be either the B name (e.g. B) or an OpenSSL OID name +(e.g B). Curve names are case sensitive. + +=item B<-cipher> + +Sets the cipher suite list to B. Note: syntax checking of B is +currently not performed unless a B or B structure is +associated with B. + +=item B<-cert> + +Attempts to use the file B as the certificate for the appropriate +context. It currently uses SSL_CTX_use_certificate_chain_file() if an B +structure is set or SSL_use_certificate_file() with filetype PEM if an B +structure is set. This option is only supported if certificate operations +are permitted. + +=item B<-key> + +Attempts to use the file B as the private key for the appropriate +context. This option is only supported if certificate operations +are permitted. Note: if no B<-key> option is set then a private key is +not loaded unless the flag B is set. + +=item B<-dhparam> + +Attempts to use the file B as the set of temporary DH parameters for +the appropriate context. This option is only supported if certificate +operations are permitted. + +=item B<-no_renegotiation> + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B. + +=item B<-min_protocol>, B<-max_protocol> + +Sets the minimum and maximum supported protocol. +Currently supported protocol values are B, B, +B, B for TLS and B, B for DTLS, +and B for no limit. +If the either bound is not specified then only the other bound applies, +if specified. +To restrict the supported protocol versions use these commands rather +than the deprecated alternative commands below. + +=item B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2> + +Disables protocol support for SSLv3, TLSv1.0, TLSv1.1 or TLSv1.2 by setting the +corresponding options B, B, B +and B respectively. +These options are deprecated, instead use B<-min_protocol> and B<-max_protocol>. + +=item B<-bugs> + +Various bug workarounds are set, same as setting B. + +=item B<-comp> + +Enables support for SSL/TLS compression, same as clearing +B. +This command was introduced in OpenSSL 1.1.0. +As of OpenSSL 1.1.0, compression is off by default. + +=item B<-no_comp> + +Disables support for SSL/TLS compression, same as setting +B. +As of OpenSSL 1.1.0, compression is off by default. + +=item B<-no_ticket> + +Disables support for session tickets, same as setting B. + +=item B<-serverpref> + +Use server and not client preference order when determining which cipher suite, +signature algorithm or elliptic curve to use for an incoming connection. +Equivalent to B. Only used by servers. + +=item B<-no_resumption_on_reneg> + +set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag. Only used by servers. + +=item B<-legacyrenegotiation> + +permits the use of unsafe legacy renegotiation. Equivalent to setting +B. + +=item B<-legacy_server_connect>, B<-no_legacy_server_connect> + +permits or prohibits the use of unsafe legacy renegotiation for OpenSSL +clients only. Equivalent to setting or clearing B. +Set by default. + +=item B<-strict> + +enables strict mode protocol handling. Equivalent to setting +B. + +=back + +=head1 SUPPORTED CONFIGURATION FILE COMMANDS + +Currently supported B names for configuration files (i.e. when the +flag B is set) are listed below. All configuration file +B names are case insensitive so B is recognised +as well as B. Unless otherwise stated the B names +are also case insensitive. + +Note: the command prefix (if set) alters the recognised B values. + +=over 4 + +=item B + +Sets the cipher suite list to B. Note: syntax checking of B is +currently not performed unless an B or B structure is +associated with B. + +=item B + +Attempts to use the file B as the certificate for the appropriate +context. It currently uses SSL_CTX_use_certificate_chain_file() if an B +structure is set or SSL_use_certificate_file() with filetype PEM if an B +structure is set. This option is only supported if certificate operations +are permitted. + +=item B + +Attempts to use the file B as the private key for the appropriate +context. This option is only supported if certificate operations +are permitted. Note: if no B option is set then a private key is +not loaded unless the B is set. + +=item B, B, B, B + +These options indicate a file or directory used for building certificate +chains or verifying certificate chains. These options are only supported +if certificate operations are permitted. + +=item B + +Attempts to use the file B in the "serverinfo" extension using the +function SSL_CTX_use_serverinfo_file. + +=item B + +Attempts to use the file B as the set of temporary DH parameters for +the appropriate context. This option is only supported if certificate +operations are permitted. + +=item B + +Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting +B. + +=item B + +This sets the supported signature algorithms for TLS v1.2. For clients this +value is used directly for the supported signature algorithms extension. For +servers it is used to determine which signature algorithms to support. + +The B argument should be a colon separated list of signature algorithms +in order of decreasing preference of the form B. B +is one of B, B or B and B is a supported algorithm +OID short name such as B, B, B, B of B. +Note: algorithm and hash names are case sensitive. + +If this option is not set then all signature algorithms supported by the +OpenSSL library are permissible. + +=item B + +This sets the supported signature algorithms associated with client +authentication for TLS v1.2. For servers the value is used in the supported +signature algorithms field of a certificate request. For clients it is +used to determine which signature algorithm to with the client certificate. + +The syntax of B is identical to B. If not set then +the value set for B will be used instead. + +=item B + +This sets the supported elliptic curves. For clients the curves are +sent using the supported curves extension. For servers it is used +to determine which curve to use. This setting affects curves used for both +signatures and key exchange, if applicable. + +The B argument is a colon separated list of curves. The curve can be +either the B name (e.g. B) or an OpenSSL OID name (e.g +B). Curve names are case sensitive. + +=item B + +This sets the minimum supported SSL, TLS or DTLS version. + +Currently supported protocol values are B, B, B, +B, B and B. +The value B will disable the limit. + +=item B + +This sets the maximum supported SSL, TLS or DTLS version. + +Currently supported protocol values are B, B, B, +B, B and B. +The value B will disable the limit. + +=item B + +This can be used to enable or disable certain versions of the SSL, +TLS or DTLS protocol. + +The B argument is a comma separated list of supported protocols +to enable or disable. +If a protocol is preceded by B<-> that version is disabled. + +All protocol versions are enabled by default. +You need to disable at least one protocol version for this setting have any +effect. +Only enabling some protocol versions does not disable the other protocol +versions. + +Currently supported protocol values are B, B, B, +B, B and B. +The special value B refers to all supported versions. + +This can't enable protocols that are disabled using B +or B, but can disable protocols that are still allowed +by them. + +The B command is fragile and deprecated; do not use it. +Use B and B instead. +If you do use B, make sure that the resulting range of enabled +protocols has no "holes", e.g. if TLS 1.0 and TLS 1.2 are both enabled, make +sure to also leave TLS 1.1 enabled. + +=item B + +The B argument is a comma separated list of various flags to set. +If a flag string is preceded B<-> it is disabled. +See the L function for more details of +individual options. + +Each option is listed below. Where an operation is enabled by default +the B<-flag> syntax is needed to disable it. + +B: session ticket support, enabled by default. Inverse of +B: that is B<-SessionTicket> is the same as setting +B. + +B: SSL/TLS compression support, enabled by default. Inverse +of B. + +B: use empty fragments as a countermeasure against a +SSL 3.0/TLS 1.0 protocol vulnerability affecting CBC ciphers. It +is set by default. Inverse of B. + +B: enable various bug workarounds. Same as B. + +B: enable single use DH keys, set by default. Inverse of +B. Only used by servers. + +B enable single use ECDH keys, set by default. Inverse of +B. Only used by servers. + +B use server and not client preference order when +determining which cipher suite, signature algorithm or elliptic curve +to use for an incoming connection. Equivalent to +B. Only used by servers. + +B set +B flag. Only used by servers. + +B permits the use of unsafe legacy renegotiation. +Equivalent to B. + +B permits the use of unsafe legacy renegotiation +for OpenSSL clients only. Equivalent to B. +Set by default. + +=item B + +The B argument is a comma separated list of flags to set. + +B enables peer verification: for clients only. + +B requests but does not require a certificate from the client. +Servers only. + +B requests and requires a certificate from the client: an error +occurs if the client does not present a certificate. Servers only. + +B requests a certificate from a client only on the initial connection: +not when renegotiating. Servers only. + +=item B, B + +A file or directory of certificates in PEM format whose names are used as the +set of acceptable names for client CAs. Servers only. This option is only +supported if certificate operations are permitted. + +=back + +=head1 SUPPORTED COMMAND TYPES + +The function SSL_CONF_cmd_value_type() currently returns one of the following +types: + +=over 4 + +=item B + +The B string is unrecognised, this return value can be use to flag +syntax errors. + +=item B + +The value is a string without any specific structure. + +=item B + +The value is a file name. + +=item B + +The value is a directory name. + +=item B + +The value string is not used e.g. a command line option which doesn't take an +argument. + +=back + +=head1 NOTES + +The order of operations is significant. This can be used to set either defaults +or values which cannot be overridden. For example if an application calls: + + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + SSL_CONF_cmd(ctx, userparam, uservalue); + +it will disable SSLv3 support by default but the user can override it. If +however the call sequence is: + + SSL_CONF_cmd(ctx, userparam, uservalue); + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + +SSLv3 is B disabled and attempt to override this by the user are +ignored. + +By checking the return code of SSL_CTX_cmd() it is possible to query if a +given B is recognised, this is useful if SSL_CTX_cmd() values are +mixed with additional application specific operations. + +For example an application might call SSL_CTX_cmd() and if it returns +-2 (unrecognised command) continue with processing of application specific +commands. + +Applications can also use SSL_CTX_cmd() to process command lines though the +utility function SSL_CTX_cmd_argv() is normally used instead. One way +to do this is to set the prefix to an appropriate value using +SSL_CONF_CTX_set1_prefix(), pass the current argument to B and the +following argument to B (which may be NULL). + +In this case if the return value is positive then it is used to skip that +number of arguments as they have been processed by SSL_CTX_cmd(). If -2 is +returned then B is not recognised and application specific arguments +can be checked instead. If -3 is returned a required argument is missing +and an error is indicated. If 0 is returned some other error occurred and +this can be reported back to the user. + +The function SSL_CONF_cmd_value_type() can be used by applications to +check for the existence of a command or to perform additional syntax +checking or translation of the command value. For example if the return +value is B an application could translate a relative +pathname to an absolute pathname. + +=head1 EXAMPLES + +Set supported signature algorithms: + + SSL_CONF_cmd(ctx, "SignatureAlgorithms", "ECDSA+SHA256:RSA+SHA256:DSA+SHA256"); + +There are various ways to select the supported protocols. + +This set the minimum protocol version to TLSv1, and so disables SSLv3. +This is the recommended way to disable protocols. + + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1"); + +The following also disables SSLv3: + + SSL_CONF_cmd(ctx, "Protocol", "-SSLv3"); + +The following will first enable all protocols, and then disable +SSLv3. +If no protocol versions were disabled before this has the same effect as +"-SSLv3", but if some versions were disables this will re-enable them before +disabling SSLv3. + + SSL_CONF_cmd(ctx, "Protocol", "ALL,-SSLv3"); + +Only enable TLSv1.2: + + SSL_CONF_cmd(ctx, "MinProtocol", "TLSv1.2"); + SSL_CONF_cmd(ctx, "MaxProtocol", "TLSv1.2"); + +This also only enables TLSv1.2: + + SSL_CONF_cmd(ctx, "Protocol", "-ALL,TLSv1.2"); + +Disable TLS session tickets: + + SSL_CONF_cmd(ctx, "Options", "-SessionTicket"); + +Enable compression: + + SSL_CONF_cmd(ctx, "Options", "Compression"); + +Set supported curves to P-256, P-384: + + SSL_CONF_cmd(ctx, "Curves", "P-256:P-384"); + +Set automatic support for any elliptic curve for key exchange: + + SSL_CONF_cmd(ctx, "ECDHParameters", "Automatic"); + +=head1 RETURN VALUES + +SSL_CONF_cmd() returns 1 if the value of B is recognised and B is +B used and 2 if both B and B are used. In other words it +returns the number of arguments processed. This is useful when processing +command lines. + +A return value of -2 means B is not recognised. + +A return value of -3 means B is recognised and the command requires a +value but B is NULL. + +A return code of 0 indicates that both B and B are valid but an +error occurred attempting to perform the operation: for example due to an +error in the syntax of B in this case the error queue may provide +additional information. + +SSL_CONF_finish() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +SSL_CONF_cmd() was first added to OpenSSL 1.0.2 + +B doesn't have effect since 1.1.0, but the macro is retained +for backwards compatibility. + +B was first added to OpenSSL 1.1.0. In earlier versions of +OpenSSL passing a command which didn't take an argument would return +B. + +B and B where added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2012-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod new file mode 100644 index 0000000..15529a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CONF_cmd_argv.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +SSL_CONF_cmd_argv - SSL configuration command line processing + +=head1 SYNOPSIS + + #include + + int SSL_CONF_cmd_argv(SSL_CONF_CTX *cctx, int *pargc, char ***pargv); + +=head1 DESCRIPTION + +The function SSL_CONF_cmd_argv() processes at most two command line +arguments from B and B. The values of B and B +are updated to reflect the number of command options processed. The B +argument can be set to B is it is not used. + +=head1 RETURN VALUES + +SSL_CONF_cmd_argv() returns the number of command arguments processed: 0, 1, 2 +or a negative error code. + +If -2 is returned then an argument for a command is missing. + +If -1 is returned the command is recognised but couldn't be processed due +to an error: for example a syntax error in the argument. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2 + +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod new file mode 100644 index 0000000..1f0418b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add1_chain_cert.pod @@ -0,0 +1,158 @@ +=pod + +=head1 NAME + +SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, +SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, +SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, +SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, +SSL_build_cert_chain, SSL_CTX_select_current_cert, +SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert - extra +chain certificate processing + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); + int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk); + int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509); + int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509); + int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk); + int SSL_CTX_clear_chain_certs(SSL_CTX *ctx); + + int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk); + int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk); + int SSL_add0_chain_cert(SSL *ssl, X509 *x509); + int SSL_add1_chain_cert(SSL *ssl, X509 *x509); + int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk); + int SSL_clear_chain_certs(SSL *ssl); + + int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags); + int SSL_build_cert_chain(SSL *ssl, flags); + + int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509); + int SSL_select_current_cert(SSL *ssl, X509 *x509); + int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op); + int SSL_set_current_cert(SSL *ssl, long op); + +=head1 DESCRIPTION + +SSL_CTX_set0_chain() and SSL_CTX_set1_chain() set the certificate chain +associated with the current certificate of B to B. + +SSL_CTX_add0_chain_cert() and SSL_CTX_add1_chain_cert() append the single +certificate B to the chain associated with the current certificate of +B. + +SSL_CTX_get0_chain_certs() retrieves the chain associated with the current +certificate of B. + +SSL_CTX_clear_chain_certs() clears any existing chain associated with the +current certificate of B. (This is implemented by calling +SSL_CTX_set0_chain() with B set to B). + +SSL_CTX_build_cert_chain() builds the certificate chain for B normally +this uses the chain store or the verify store if the chain store is not set. +If the function is successful the built chain will replace any existing chain. +The B parameter can be set to B to use +existing chain certificates as untrusted CAs, B +to omit the root CA from the built chain, B to +use all existing chain certificates only to build the chain (effectively +sanity checking and rearranging them if necessary), the flag +B ignores any errors during verification: +if flag B is also set verification errors +are cleared from the error queue. + +Each of these functions operates on the I end entity +(i.e. server or client) certificate. This is the last certificate loaded or +selected on the corresponding B structure. + +SSL_CTX_select_current_cert() selects B as the current end entity +certificate, but only if B has already been loaded into B using a +function such as SSL_CTX_use_certificate(). + +SSL_set0_chain(), SSL_set1_chain(), SSL_add0_chain_cert(), +SSL_add1_chain_cert(), SSL_get0_chain_certs(), SSL_clear_chain_certs(), +SSL_build_cert_chain(), SSL_select_current_cert() and SSL_set_current_cert() +are similar except they apply to SSL structure B. + +SSL_CTX_set_current_cert() changes the current certificate to a value based +on the B argument. Currently B can be B to use +the first valid certificate or B to set the next valid +certificate after the current certificate. These two operations can be +used to iterate over all certificates in an B structure. + +SSL_set_current_cert() also supports the option B. +If B is a server and has sent a certificate to a connected client +this option sets that certificate to the current certificate and returns 1. +If the negotiated ciphersuite is anonymous (and thus no certificate will +be sent) 2 is returned and the current certificate is unchanged. If B +is not a server or a certificate has not been sent 0 is returned and +the current certificate is unchanged. + +All these functions are implemented as macros. Those containing a B<1> +increment the reference count of the supplied certificate or chain so it must +be freed at some point after the operation. Those containing a B<0> do +not increment reference counts and the supplied certificate or chain +B be freed after the operation. + +=head1 NOTES + +The chains associate with an SSL_CTX structure are copied to any SSL +structures when SSL_new() is called. SSL structures will not be affected +by any chains subsequently changed in the parent SSL_CTX. + +One chain can be set for each key type supported by a server. So, for example, +an RSA and a DSA certificate can (and often will) have different chains. + +The functions SSL_CTX_build_cert_chain() and SSL_build_cert_chain() can +be used to check application configuration and to ensure any necessary +subordinate CAs are sent in the correct order. Misconfigured applications +sending incorrect certificate chains often cause problems with peers. + +For example an application can add any set of certificates using +SSL_CTX_use_certificate_chain_file() then call SSL_CTX_build_cert_chain() +with the option B to check and reorder them. + +Applications can issue non fatal warnings when checking chains by setting +the flag B and checking the return +value. + +Calling SSL_CTX_build_cert_chain() or SSL_build_cert_chain() is more +efficient than the automatic chain building as it is only performed once. +Automatic chain building is performed on each new session. + +If any certificates are added using these functions no certificates added +using SSL_CTX_add_extra_chain_cert() will be used. + +=head1 RETURN VALUES + +SSL_set_current_cert() with B return 1 for success, 2 if +no server certificate is used because the ciphersuites is anonymous and 0 +for failure. + +SSL_CTX_build_cert_chain() and SSL_build_cert_chain() return 1 for success +and 0 for failure. If the flag B and +a verification error occurs then 2 is returned. + +All other functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod new file mode 100644 index 0000000..e2783de --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_extra_chain_cert.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear +extra chain certificates + +=head1 SYNOPSIS + + #include + + long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509); + long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_add_extra_chain_cert() adds the certificate B to the extra chain +certificates associated with B. Several certificates can be added one +after another. + +SSL_CTX_clear_extra_chain_certs() clears all extra chain certificates +associated with B. + +These functions are implemented as macros. + +=head1 NOTES + +When sending a certificate chain, extra chain certificates are sent in order +following the end entity certificate. + +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 RESTRICTIONS + +Only one set of extra chain certificates can be specified per SSL_CTX +structure. Different chains for different certificates (for example if both +RSA and DSA certificates are specified by the same server) or different SSL +structures with the same parent SSL_CTX cannot be specified using this +function. For more flexibility functions such as SSL_add1_chain_cert() should +be used instead. + +=head1 RETURN VALUES + +SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return +1 on success and 0 for failure. Check out the error stack to find out the +reason for failure. + +=head1 SEE ALSO + +L, +L, +L, +L +L +L +L +L +L +L +L +L +L +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod new file mode 100644 index 0000000..dbdd9f0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_add_session.pod @@ -0,0 +1,82 @@ +=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 Z<>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 Z<>1 + + The operation succeeded. + +=back + +=head1 SEE ALSO + +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod new file mode 100644 index 0000000..ec744ad --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_config.pod @@ -0,0 +1,93 @@ +=pod + +=head1 NAME + +SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure + +=head1 SYNOPSIS + + #include + + int SSL_CTX_config(SSL_CTX *ctx, const char *name); + int SSL_config(SSL *s, const char *name); + +=head1 DESCRIPTION + +The functions SSL_CTX_config() and SSL_config() configure an B or +B structure using the configuration B. + +=head1 NOTES + +By calling SSL_CTX_config() or SSL_config() an application can perform many +complex tasks based on the contents of the configuration file: greatly +simplifying application configuration code. A degree of future proofing +can also be achieved: an application can support configuration features +in newer versions of OpenSSL automatically. + +A configuration file must have been previously loaded, for example using +CONF_modules_load_file(). See L for details of the configuration +file syntax. + +=head1 RETURN VALUES + +SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error +occurred. + +=head1 EXAMPLE + +If the file "config.cnf" contains the following: + + testapp = test_sect + + [test_sect] + # list of configuration modules + + ssl_conf = ssl_sect + + [ssl_sect] + + server = server_section + + [server_section] + + RSA.Certificate = server-rsa.pem + ECDSA.Certificate = server-ecdsa.pem + Ciphers = ALL:!RC4 + +An application could call: + + if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) { + fprintf(stderr, "Error processing config file\n"); + goto err; + } + + ctx = SSL_CTX_new(TLS_server_method()); + + if (SSL_CTX_config(ctx, "server") == 0) { + fprintf(stderr, "Error configuring server.\n"); + goto err; + } + +In this example two certificates and the cipher list are configured without +the need for any additional application code. + +=head1 SEE ALSO + +L, +L, +L + +=head1 HISTORY + +SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod new file mode 100644 index 0000000..e8386a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_ctrl.pod @@ -0,0 +1,43 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod new file mode 100644 index 0000000..cdb6d1b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_dane_enable.pod @@ -0,0 +1,384 @@ +=pod + +=head1 NAME + +SSL_CTX_dane_enable, SSL_CTX_dane_mtype_set, SSL_dane_enable, +SSL_dane_tlsa_add, SSL_get0_dane_authority, SSL_get0_dane_tlsa, +SSL_CTX_dane_set_flags, SSL_CTX_dane_clear_flags, +SSL_dane_set_flags, SSL_dane_clear_flags +- enable DANE TLS authentication of the remote TLS server in the local +TLS client + +=head1 SYNOPSIS + + #include + + int SSL_CTX_dane_enable(SSL_CTX *ctx); + int SSL_CTX_dane_mtype_set(SSL_CTX *ctx, const EVP_MD *md, + uint8_t mtype, uint8_t ord); + int SSL_dane_enable(SSL *s, const char *basedomain); + int SSL_dane_tlsa_add(SSL *s, uint8_t usage, uint8_t selector, + uint8_t mtype, unsigned char *data, size_t dlen); + int SSL_get0_dane_authority(SSL *s, X509 **mcert, EVP_PKEY **mspki); + int SSL_get0_dane_tlsa(SSL *s, uint8_t *usage, uint8_t *selector, + uint8_t *mtype, unsigned const char **data, + size_t *dlen); + unsigned long SSL_CTX_dane_set_flags(SSL_CTX *ctx, unsigned long flags); + unsigned long SSL_CTX_dane_clear_flags(SSL_CTX *ctx, unsigned long flags); + unsigned long SSL_dane_set_flags(SSL *ssl, unsigned long flags); + unsigned long SSL_dane_clear_flags(SSL *ssl, unsigned long flags); + +=head1 DESCRIPTION + +These functions implement support for DANE TLSA (RFC6698 and RFC7671) +peer authentication. + +SSL_CTX_dane_enable() must be called first to initialize the shared state +required for DANE support. +Individual connections associated with the context can then enable +per-connection DANE support as appropriate. +DANE authentication is implemented in the L function, and +applications that override L via +L are responsible to authenticate the peer +chain in whatever manner they see fit. + +SSL_CTX_dane_mtype_set() may then be called zero or more times to adjust the +supported digest algorithms. +This must be done before any SSL handles are created for the context. + +The B argument specifies a DANE TLSA matching type and the B +argument specifies the associated digest algorithm handle. +The B argument specifies a strength ordinal. +Algorithms with a larger strength ordinal are considered more secure. +Strength ordinals are used to implement RFC7671 digest algorithm agility. +Specifying a B digest algorithm for a matching type disables +support for that matching type. +Matching type Full(0) cannot be modified or disabled. + +By default, matching type C (see RFC7218 for definitions +of the DANE TLSA parameter acronyms) is mapped to C +with a strength ordinal of C<1> and matching type C +is mapped to C with a strength ordinal of C<2>. + +SSL_dane_enable() must be called before the SSL handshake is initiated with +L if (and only if) you want to enable DANE for that connection. +(The connection must be associated with a DANE-enabled SSL context). +The B argument specifies the RFC7671 TLSA base domain, +which will be the primary peer reference identifier for certificate +name checks. +Additional server names can be specified via L. +The B is used as the default SNI hint if none has yet been +specified via L. + +SSL_dane_tlsa_add() may then be called one or more times, to load each of the +TLSA records that apply to the remote TLS peer. +(This too must be done prior to the beginning of the SSL handshake). +The arguments specify the fields of the TLSA record. +The B field is provided in binary (wire RDATA) form, not the hexadecimal +ASCII presentation form, with an explicit length passed via B. +The library takes a copy of the B buffer contents and the caller may +free the original B buffer when convenient. +A return value of 0 indicates that "unusable" TLSA records (with invalid or +unsupported parameters) were provided. +A negative return value indicates an internal error in processing the record. + +The caller is expected to check the return value of each SSL_dane_tlsa_add() +call and take appropriate action if none are usable or an internal error +is encountered in processing some records. + +If no TLSA records are added successfully, DANE authentication is not enabled, +and authentication will be based on any configured traditional trust-anchors; +authentication success in this case does not mean that the peer was +DANE-authenticated. + +SSL_get0_dane_authority() can be used to get more detailed information about +the matched DANE trust-anchor after successful connection completion. +The return value is negative if DANE verification failed (or was not enabled), +0 if an EE TLSA record directly matched the leaf certificate, or a positive +number indicating the depth at which a TA record matched an issuer certificate. +The complete verified chain can be retrieved via L. +The return value is an index into this verified chain, rather than the list of +certificates sent by the peer as returned by L. + +If the B argument is not B and a TLSA record matched a chain +certificate, a pointer to the matching certificate is returned via B. +The returned address is a short-term internal reference to the certificate and +must not be freed by the application. +Applications that want to retain access to the certificate can call +L to obtain a long-term reference which must then be freed via +L once no longer needed. + +If no TLSA records directly matched any elements of the certificate chain, but +a DANE-TA(2) SPKI(1) Full(0) record provided the public key that signed an +element of the chain, then that key is returned via B argument (if not +NULL). +In this case the return value is the depth of the top-most element of the +validated certificate chain. +As with B this is a short-term internal reference, and +L and L can be used to acquire and +release long-term references respectively. + +SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that +matched the peer certificate chain. +The return value indicates the match depth or failure to match just as with +SSL_get0_dane_authority(). +When the return value is non-negative, the storage pointed to by the B, +B, B and B parameters is updated to the corresponding +TLSA record fields. +The B field is in binary wire form, and is therefore not NUL-terminated, +its length is returned via the B parameter. +If any of these parameters is NULL, the corresponding field is not returned. +The B parameter is set to a short-term internal-copy of the associated +data field and must not be freed by the application. +Applications that need long-term access to this field need to copy the content. + +SSL_CTX_dane_set_flags() and SSL_dane_set_flags() can be used to enable +optional DANE verification features. +SSL_CTX_dane_clear_flags() and SSL_dane_clear_flags() can be used to disable +the same features. +The B argument is a bitmask of the features to enable or disable. +The B set for an B context are copied to each B handle +associated with that context at the time the handle is created. +Subsequent changes in the context's B have no effect on the B set +for the handle. + +At present, the only available option is B +which can be used to disable server name checks when authenticating via +DANE-EE(3) TLSA records. +For some applications, primarily web browsers, it is not safe to disable name +checks due to "unknown key share" attacks, in which a malicious server can +convince a client that a connection to a victim server is instead a secure +connection to the malicious server. +The malicious server may then be able to violate cross-origin scripting +restrictions. +Thus, despite the text of RFC7671, name checks are by default enabled for +DANE-EE(3) TLSA records, and can be disabled in applications where it is safe +to do so. +In particular, SMTP and XMPP clients should set this option as SRV and MX +records already make it possible for a remote domain to redirect client +connections to any server of its choice, and in any case SMTP and XMPP clients +do not execute scripts downloaded from remote servers. + +=head1 RETURN VALUES + +The functions SSL_CTX_dane_enable(), SSL_CTX_dane_mtype_set(), +SSL_dane_enable() and SSL_dane_tlsa_add() return a positive value on success. +Negative return values indicate resource problems (out of memory, etc.) in the +SSL library, while a return value of B<0> indicates incorrect usage or invalid +input, such as an unsupported TLSA record certificate usage, selector or +matching type. +Invalid input also includes malformed data, either a digest length that does +not match the digest algorithm, or a C (binary ASN.1 DER form) +certificate or a public key that fails to parse. + +The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a +negative value when DANE authentication failed or was not enabled, a +non-negative value indicates the chain depth at which the TLSA record matched a +chain certificate, or the depth of the top-most certificate, when the TLSA +record is a full public key that is its signer. + +The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(), +SSL_dane_set_flags() and SSL_dane_clear_flags() return the B in effect +before they were called. + +=head1 EXAMPLE + +Suppose "smtp.example.com" is the MX host of the domain "example.com", and has +DNSSEC-validated TLSA records. +The calls below will perform DANE authentication and arrange to match either +the MX hostname or the destination domain name in the SMTP server certificate. +Wildcards are supported, but must match the entire label. +The actual name matched in the certificate (which might be a wildcard) is +retrieved, and must be copied by the application if it is to be retained beyond +the lifetime of the SSL connection. + + SSL_CTX *ctx; + SSL *ssl; + int (*verify_cb)(int ok, X509_STORE_CTX *sctx) = NULL; + int num_usable = 0; + const char *nexthop_domain = "example.com"; + const char *dane_tlsa_domain = "smtp.example.com"; + uint8_t usage, selector, mtype; + + if ((ctx = SSL_CTX_new(TLS_client_method())) == NULL) + /* handle error */ + if (SSL_CTX_dane_enable(ctx) <= 0) + /* handle error */ + + if ((ssl = SSL_new(ctx)) == NULL) + /* handle error */ + + if (SSL_dane_enable(ssl, dane_tlsa_domain) <= 0) + /* handle error */ + + /* + * For many applications it is safe to skip DANE-EE(3) namechecks. Do not + * disable the checks unless "unknown key share" attacks pose no risk for + * your application. + */ + SSL_dane_set_flags(ssl, DANE_FLAG_NO_DANE_EE_NAMECHECKS); + + if (!SSL_add1_host(ssl, nexthop_domain)) + /* handle error */ + SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS); + + for (... each TLSA record ...) { + unsigned char *data; + size_t len; + int ret; + + /* set usage, selector, mtype, data, len */ + + /* + * Opportunistic DANE TLS clients support only DANE-TA(2) or DANE-EE(3). + * They treat all other certificate usages, and in particular PKIX-TA(0) + * and PKIX-EE(1), as unusable. + */ + switch (usage) { + default: + case 0: /* PKIX-TA(0) */ + case 1: /* PKIX-EE(1) */ + continue; + case 2: /* DANE-TA(2) */ + case 3: /* DANE-EE(3) */ + break; + } + + ret = SSL_dane_tlsa_add(ssl, usage, selector, mtype, data, len); + /* free data as appropriate */ + + if (ret < 0) + /* handle SSL library internal error */ + else if (ret == 0) + /* handle unusable TLSA record */ + else + ++num_usable; + } + + /* + * At this point, the verification mode is still the default SSL_VERIFY_NONE. + * Opportunistic DANE clients use unauthenticated TLS when all TLSA records + * are unusable, so continue the handshake even if authentication fails. + */ + if (num_usable == 0) { + /* Log all records unusable? */ + + /* Optionally set verify_cb to a suitable non-NULL callback. */ + SSL_set_verify(ssl, SSL_VERIFY_NONE, verify_cb); + } else { + /* At least one usable record. We expect to verify the peer */ + + /* Optionally set verify_cb to a suitable non-NULL callback. */ + + /* + * Below we elect to fail the handshake when peer verification fails. + * Alternatively, use the permissive SSL_VERIFY_NONE verification mode, + * complete the handshake, check the verification status, and if not + * verified disconnect gracefully at the application layer, especially if + * application protocol supports informing the server that authentication + * failed. + */ + SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb); + } + + /* + * Load any saved session for resumption, making sure that the previous + * session applied the same security and authentication requirements that + * would be expected of a fresh connection. + */ + + /* Perform SSL_connect() handshake and handle errors here */ + + if (SSL_session_reused(ssl)) { + if (SSL_get_verify_result(ssl) == X509_V_OK) { + /* + * Resumed session was originally verified, this connection is + * authenticated. + */ + } else { + /* + * Resumed session was not originally verified, this connection is not + * authenticated. + */ + } + } else if (SSL_get_verify_result(ssl) == X509_V_OK) { + const char *peername = SSL_get0_peername(ssl); + EVP_PKEY *mspki = NULL; + + int depth = SSL_get0_dane_authority(ssl, NULL, &mspki); + if (depth >= 0) { + (void) SSL_get0_dane_tlsa(ssl, &usage, &selector, &mtype, NULL, NULL); + printf("DANE TLSA %d %d %d %s at depth %d\n", usage, selector, mtype, + (mspki != NULL) ? "TA public key verified certificate" : + depth ? "matched TA certificate" : "matched EE certificate", + depth); + } + if (peername != NULL) { + /* Name checks were in scope and matched the peername */ + printf("Verified peername: %s\n", peername); + } + } else { + /* + * Not authenticated, presumably all TLSA rrs unusable, but possibly a + * callback suppressed connection termination despite the presence of + * usable TLSA RRs none of which matched. Do whatever is appropriate for + * fresh unauthenticated connections. + */ + } + +=head1 NOTES + +It is expected that the majority of clients employing DANE TLS will be doing +"opportunistic DANE TLS" in the sense of RFC7672 and RFC7435. +That is, they will use DANE authentication when DNSSEC-validated TLSA records +are published for a given peer, and otherwise will use unauthenticated TLS or +even cleartext. + +Such applications should generally treat any TLSA records published by the peer +with usages PKIX-TA(0) and PKIX-EE(1) as "unusable", and should not include +them among the TLSA records used to authenticate peer connections. +In addition, some TLSA records with supported usages may be "unusable" as a +result of invalid or unsupported parameters. + +When a peer has TLSA records, but none are "usable", an opportunistic +application must avoid cleartext, but cannot authenticate the peer, +and so should generally proceed with an unauthenticated connection. +Opportunistic applications need to note the return value of each +call to SSL_dane_tlsa_add(), and if all return 0 (due to invalid +or unsupported parameters) disable peer authentication by calling +L with B equal to B. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod new file mode 100644 index 0000000..7639451 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_flush_sessions.pod @@ -0,0 +1,56 @@ +=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 SEE ALSO + +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod new file mode 100644 index 0000000..e5cc1aa --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_free.pod @@ -0,0 +1,51 @@ +=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 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. + +If B is NULL nothing is done. + +=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 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod new file mode 100644 index 0000000..6b93737 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_get0_param.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +SSL_CTX_get0_param, SSL_get0_param, SSL_CTX_set1_param, SSL_set1_param - +get and set verification parameters + +=head1 SYNOPSIS + + #include + + X509_VERIFY_PARAM *SSL_CTX_get0_param(SSL_CTX *ctx) + X509_VERIFY_PARAM *SSL_get0_param(SSL *ssl) + int SSL_CTX_set1_param(SSL_CTX *ctx, X509_VERIFY_PARAM *vpm) + int SSL_set1_param(SSL *ssl, X509_VERIFY_PARAM *vpm) + +=head1 DESCRIPTION + +SSL_CTX_get0_param() and SSL_get0_param() retrieve an internal pointer to +the verification parameters for B or B respectively. The returned +pointer must not be freed by the calling application. + +SSL_CTX_set1_param() and SSL_set1_param() set the verification parameters +to B for B or B. + +=head1 NOTES + +Typically parameters are retrieved from an B or B structure +using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies +them to suit its needs: for example to add a hostname check. + +=head1 EXAMPLE + +Check hostname matches "www.foo.com" in peer certificate: + + X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); + X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); + +=head1 RETURN VALUES + +SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an +B structure. + +SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0 +for failure. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod new file mode 100644 index 0000000..bd10034 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_get_verify_mode.pod @@ -0,0 +1,59 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod new file mode 100644 index 0000000..d9e9a06 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_has_client_custom_ext.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +SSL_CTX_has_client_custom_ext - check whether a handler exists for a particular +client extension type + +=head1 SYNOPSIS + + #include + + int SSL_CTX_has_client_custom_ext(const SSL_CTX *ctx, unsigned int ext_type); + +=head1 DESCRIPTION + +SSL_CTX_has_client_custom_ext() checks whether a handler has been set for a +client extension of type B using SSL_CTX_add_client_custom_ext(). + +=head1 RETURN VALUES + +Returns 1 if a handler has been set, 0 otherwise. + +=head1 SEE ALSO + +L, +L + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 0000000..59d11e0 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -0,0 +1,161 @@ +=pod + +=head1 NAME + +SSL_CTX_load_verify_locations, SSL_CTX_set_default_verify_paths, +SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file - 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); + + int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx); + + int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx); + + int SSL_CTX_set_default_verify_file(SSL_CTX *ctx); + +=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. + +SSL_CTX_set_default_verify_paths() specifies that the default locations from +which CA certificates are loaded should be used. There is one default directory +and one default file. The default CA certificates directory is called "certs" in +the default OpenSSL directory. Alternatively the SSL_CERT_DIR environment +variable can be defined to override this location. The default CA certificates +file is called "cert.pem" in the default OpenSSL directory. Alternatively the +SSL_CERT_FILE environment variable can be defined to override this location. + +SSL_CTX_set_default_verify_dir() is similar to +SSL_CTX_set_default_verify_paths() except that just the default directory is +used. + +SSL_CTX_set_default_verify_file() is similar to +SSL_CTX_set_default_verify_paths() except that just the default file is +used. + +=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. +Use the B utility to create the necessary links. + +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 + c_rehash . + +=head1 RETURN VALUES + +For SSL_CTX_load_verify_locations the following return values can occur: + +=over 4 + +=item Z<>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 Z<>1 + +The operation succeeded. + +=back + +SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and +SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A +missing default location is still treated as a success. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod new file mode 100644 index 0000000..7b35bdd --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_new.pod @@ -0,0 +1,218 @@ +=pod + +=head1 NAME + +TLSv1_2_method, TLSv1_2_server_method, TLSv1_2_client_method, +SSL_CTX_new, SSL_CTX_up_ref, 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, TLS_method, +TLS_server_method, TLS_client_method, SSLv23_method, SSLv23_server_method, +SSLv23_client_method, DTLS_method, DTLS_server_method, DTLS_client_method, +DTLSv1_method, DTLSv1_server_method, DTLSv1_client_method, +DTLSv1_2_method, DTLSv1_2_server_method, DTLSv1_2_client_method +- create a new SSL_CTX object as framework for TLS/SSL or DTLS enabled +functions + +=head1 SYNOPSIS + + #include + + SSL_CTX *SSL_CTX_new(const SSL_METHOD *method); + int SSL_CTX_up_ref(SSL_CTX *ctx); + + const SSL_METHOD *TLS_method(void); + const SSL_METHOD *TLS_server_method(void); + const SSL_METHOD *TLS_client_method(void); + + const SSL_METHOD *SSLv23_method(void); + const SSL_METHOD *SSLv23_server_method(void); + const SSL_METHOD *SSLv23_client_method(void); + + #ifndef OPENSSL_NO_SSL3_METHOD + const SSL_METHOD *SSLv3_method(void); + const SSL_METHOD *SSLv3_server_method(void); + const SSL_METHOD *SSLv3_client_method(void); + #endif + + #ifndef OPENSSL_NO_TLS1_METHOD + const SSL_METHOD *TLSv1_method(void); + const SSL_METHOD *TLSv1_server_method(void); + const SSL_METHOD *TLSv1_client_method(void); + #endif + + #ifndef OPENSSL_NO_TLS1_1_METHOD + const SSL_METHOD *TLSv1_1_method(void); + const SSL_METHOD *TLSv1_1_server_method(void); + const SSL_METHOD *TLSv1_1_client_method(void); + #endif + + #ifndef OPENSSL_NO_TLS1_2_METHOD + const SSL_METHOD *TLSv1_2_method(void); + const SSL_METHOD *TLSv1_2_server_method(void); + const SSL_METHOD *TLSv1_2_client_method(void); + #endif + + const SSL_METHOD *DTLS_method(void); + const SSL_METHOD *DTLS_server_method(void); + const SSL_METHOD *DTLS_client_method(void); + + #ifndef OPENSSL_NO_DTLS1_METHOD + const SSL_METHOD *DTLSv1_method(void); + const SSL_METHOD *DTLSv1_server_method(void); + const SSL_METHOD *DTLSv1_client_method(void); + #endif + + #ifndef OPENSSL_NO_DTLS1_2_METHOD + const SSL_METHOD *DTLSv1_2_method(void); + const SSL_METHOD *DTLSv1_2_server_method(void); + const SSL_METHOD *DTLSv1_2_client_method(void); + #endif + +=head1 DESCRIPTION + +SSL_CTX_new() creates a new B object as framework to +establish TLS/SSL or DTLS enabled connections. An B object is +reference counted. Creating an B object for the first time increments +the reference count. Freeing it (using SSL_CTX_free) decrements it. When the +reference count drops to zero, any memory or resources allocated to the +B object are freed. SSL_CTX_up_ref() increments the reference count for +an existing B structure. + +=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 TLS_method(), TLS_server_method(), TLS_client_method() + +These are the general-purpose I SSL/TLS methods. +The actual protocol version used will be negotiated to the highest version +mutually supported by the client and the server. +The supported protocols are SSLv3, TLSv1, TLSv1.1 and TLSv1.2. +Applications should use these methods, and avoid the version-specific +methods described below. + +=item SSLv23_method(), SSLv23_server_method(), SSLv23_client_method() + +Use of these functions is deprecated. They have been replaced with the above +TLS_method(), TLS_server_method() and TLS_client_method() respectively. New +code should use those functions instead. + +=item TLSv1_2_method(), TLSv1_2_server_method(), TLSv1_2_client_method() + +A TLS/SSL connection established with these methods will only understand the +TLSv1.2 protocol. + +=item TLSv1_1_method(), TLSv1_1_server_method(), TLSv1_1_client_method() + +A TLS/SSL connection established with these methods will only understand the +TLSv1.1 protocol. + +=item TLSv1_method(), TLSv1_server_method(), TLSv1_client_method() + +A TLS/SSL connection established with these methods will only understand the +TLSv1 protocol. + +=item SSLv3_method(), SSLv3_server_method(), SSLv3_client_method() + +A TLS/SSL connection established with these methods will only understand the +SSLv3 protocol. +The SSLv3 protocol is deprecated and should not be used. + +=item DTLS_method(), DTLS_server_method(), DTLS_client_method() + +These are the version-flexible DTLS methods. +Currently supported protocols are DTLS 1.0 and DTLS 1.2. + +=item DTLSv1_2_method(), DTLSv1_2_server_method(), DTLSv1_2_client_method() + +These are the version-specific methods for DTLSv1.2. + +=item DTLSv1_method(), DTLSv1_server_method(), DTLSv1_client_method() + +These are the version-specific methods for DTLSv1. + +=back + +SSL_CTX_new() initializes the list of ciphers, the session cache setting, the +callbacks, the keys and certificates and the options to their default values. + +TLS_method(), TLS_server_method(), TLS_client_method(), DTLS_method(), +DTLS_server_method() and DTLS_client_method() are the I +methods. +All other methods only support one specific protocol version. +Use the I methods instead of the version specific methods. + +If you want to limit the supported protocols for the version flexible +methods you can use L, +L, L and +L functions. +Using these functions it is possible to choose e.g. TLS_server_method() +and be able to negotiate with all possible clients, but to only +allow newer protocols like TLS 1.0, TLS 1.1 or TLS 1.2. + +The list of protocols available can also be limited using the +B, B, B and +B options of the L or +L functions, but this approach is not recommended. +Clients should avoid creating "holes" in the set of protocols they support. +When disabling a protocol, make sure that you also disable either all previous +or all subsequent protocol versions. +In clients, when a protocol version is disabled without disabling I +previous protocol versions, the effect is to also disable all subsequent +protocol versions. + +The SSLv3 protocol is deprecated and should generally not be used. +Applications should typically use L to set +the minimum protocol to at least B. + +=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. + +SSL_CTX_up_ref() returns 1 for success and 0 for failure. + +=back + +=head1 HISTORY + +Support for SSLv2 and the corresponding SSLv2_method(), +SSLv2_server_method() and SSLv2_client_method() functions where +removed in OpenSSL 1.1.0. + +SSLv23_method(), SSLv23_server_method() and SSLv23_client_method() +were deprecated and the preferred TLS_method(), TLS_server_method() +and TLS_client_method() functions were introduced in OpenSSL 1.1.0. + +All version-specific methods were deprecated in OpenSSL 1.1.0. + +=head1 SEE ALSO + +L, L, L, +L, L, L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod new file mode 100644 index 0000000..049c04c --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_number.pod @@ -0,0 +1,85 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod new file mode 100644 index 0000000..5aef10b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_cache_size.pod @@ -0,0 +1,62 @@ +=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. +This value is a hint and not an absolute; see the notes below. + +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. + +If adding the session makes the cache exceed its size, then unused +sessions are dropped from the end of the cache. +Cache space may also be reclaimed 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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod new file mode 100644 index 0000000..d2b0e04 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sess_set_get_cb.pod @@ -0,0 +1,96 @@ +=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 *, const 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, const 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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod new file mode 100644 index 0000000..bc4a55e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_sessions.pod @@ -0,0 +1,43 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod new file mode 100644 index 0000000..b0276c8 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_curves.pod @@ -0,0 +1,90 @@ +=pod + +=head1 NAME + +SSL_CTX_set1_curves, SSL_CTX_set1_curves_list, SSL_set1_curves, +SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve - EC supported curve functions + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set1_curves(SSL_CTX *ctx, int *clist, int clistlen); + int SSL_CTX_set1_curves_list(SSL_CTX *ctx, char *list); + + int SSL_set1_curves(SSL *ssl, int *clist, int clistlen); + int SSL_set1_curves_list(SSL *ssl, char *list); + + int SSL_get1_curves(SSL *ssl, int *curves); + int SSL_get_shared_curve(SSL *s, int n); + +=head1 DESCRIPTION + +SSL_CTX_set1_curves() sets the supported curves for B to B +curves in the array B. The array consist of all NIDs of curves in +preference order. For a TLS client the curves are used directly in the +supported curves extension. For a TLS server the curves are used to +determine the set of shared curves. + +SSL_CTX_set1_curves_list() sets the supported curves for B to +string B. The string is a colon separated list of curve NIDs or +names, for example "P-521:P-384:P-256". + +SSL_set1_curves() and SSL_set1_curves_list() are similar except they set +supported curves for the SSL structure B. + +SSL_get1_curves() returns the set of supported curves sent by a client +in the supported curves extension. It returns the total number of +supported curves. The B parameter can be B to simply +return the number of curves for memory allocation purposes. The +B array is in the form of a set of curve NIDs in preference +order. It can return zero if the client did not send a supported curves +extension. + +SSL_get_shared_curve() returns shared curve B for a server-side +SSL B. If B is -1 then the total number of shared curves is +returned, which may be zero. Other than for diagnostic purposes, +most applications will only be interested in the first shared curve +so B is normally set to zero. If the value B is out of range, +NID_undef is returned. + +All these functions are implemented as macros. + +=head1 NOTES + +If an application wishes to make use of several of these functions for +configuration purposes either on a command line or in a file it should +consider using the SSL_CONF interface instead of manually parsing options. + +=head1 RETURN VALUES + +SSL_CTX_set1_curves(), SSL_CTX_set1_curves_list(), SSL_set1_curves() and +SSL_set1_curves_list(), return 1 for success and 0 for failure. + +SSL_get1_curves() returns the number of curves, which may be zero. + +SSL_get_shared_curve() returns the NID of shared curve B or NID_undef if there +is no shared curve B; or the total number of shared curves if B +is -1. + +When called on a client B, SSL_get_shared_curve() has no meaning and +returns -1. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod new file mode 100644 index 0000000..e9073b9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_sigalgs.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +SSL_CTX_set1_sigalgs, SSL_set1_sigalgs, SSL_CTX_set1_sigalgs_list, +SSL_set1_sigalgs_list, SSL_CTX_set1_client_sigalgs, +SSL_set1_client_sigalgs, SSL_CTX_set1_client_sigalgs_list, +SSL_set1_client_sigalgs_list - set supported signature algorithms + +=head1 SYNOPSIS + + #include + + long SSL_CTX_set1_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); + long SSL_set1_sigalgs(SSL *ssl, const int *slist, long slistlen); + long SSL_CTX_set1_sigalgs_list(SSL_CTX *ctx, const char *str); + long SSL_set1_sigalgs_list(SSL *ssl, const char *str); + + long SSL_CTX_set1_client_sigalgs(SSL_CTX *ctx, const int *slist, long slistlen); + long SSL_set1_client_sigalgs(SSL *ssl, const int *slist, long slistlen); + long SSL_CTX_set1_client_sigalgs_list(SSL_CTX *ctx, const char *str); + long SSL_set1_client_sigalgs_list(SSL *ssl, const char *str); + +=head1 DESCRIPTION + +SSL_CTX_set1_sigalgs() and SSL_set1_sigalgs() set the supported signature +algorithms for B or B. The array B of length B +must consist of pairs of NIDs corresponding to digest and public key +algorithms. + +SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list() set the supported +signature algorithms for B or B. The B parameter +must be a null terminated string consisting or a colon separated list of +public key algorithms and digests separated by B<+>. + +SSL_CTX_set1_client_sigalgs(), SSL_set1_client_sigalgs(), +SSL_CTX_set1_client_sigalgs_list() and SSL_set1_client_sigalgs_list() set +signature algorithms related to client authentication, otherwise they are +identical to SSL_CTX_set1_sigalgs(), SSL_set1_sigalgs(), +SSL_CTX_set1_sigalgs_list() and SSL_set1_sigalgs_list(). + +All these functions are implemented as macros. The signature algorithm +parameter (integer array or string) is not freed: the application should +free it, if necessary. + +=head1 NOTES + +If an application wishes to allow the setting of signature algorithms +as one of many user configurable options it should consider using the more +flexible SSL_CONF API instead. + +The signature algorithms set by a client are used directly in the supported +signature algorithm in the client hello message. + +The supported signature algorithms set by a server are not sent to the +client but are used to determine the set of shared signature algorithms +and (if server preferences are set with SSL_OP_CIPHER_SERVER_PREFERENCE) +their order. + +The client authentication signature algorithms set by a server are sent +in a certificate request message if client authentication is enabled, +otherwise they are unused. + +Similarly client authentication signature algorithms set by a client are +used to determined the set of client authentication shared signature +algorithms. + +Signature algorithms will neither be advertised nor used if the security level +prohibits them (for example SHA1 if the security level is 4 or more). + +Currently the NID_md5, NID_sha1, NID_sha224, NID_sha256, NID_sha384 and +NID_sha512 digest NIDs are supported and the public key algorithm NIDs +EVP_PKEY_RSA, EVP_PKEY_DSA and EVP_PKEY_EC. + +The short or long name values for digests can be used in a string (for +example "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512") and +the public key algorithm strings "RSA", "DSA" or "ECDSA". + +The use of MD5 as a digest is strongly discouraged due to security weaknesses. + +=head1 EXAMPLES + +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using an array: + + const int slist[] = {NID_sha256, EVP_PKEY_EC, NID_sha256, EVP_PKEY_RSA}; + + SSL_CTX_set1_sigalgs(ctx, slist, 4); + +Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA +using a string: + + SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256"); + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L, L, +L + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod new file mode 100644 index 0000000..bfe8b70 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set1_verify_cert_store.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +SSL_CTX_set0_verify_cert_store, SSL_CTX_set1_verify_cert_store, +SSL_CTX_set0_chain_cert_store, SSL_CTX_set1_chain_cert_store, +SSL_set0_verify_cert_store, SSL_set1_verify_cert_store, +SSL_set0_chain_cert_store, SSL_set1_chain_cert_store - set certificate +verification or chain store + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set0_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + int SSL_CTX_set1_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); + + int SSL_set0_verify_cert_store(SSL *ctx, X509_STORE *st); + int SSL_set1_verify_cert_store(SSL *ctx, X509_STORE *st); + int SSL_set0_chain_cert_store(SSL *ctx, X509_STORE *st); + int SSL_set1_chain_cert_store(SSL *ctx, X509_STORE *st); + +=head1 DESCRIPTION + +SSL_CTX_set0_verify_cert_store() and SSL_CTX_set1_verify_cert_store() +set the certificate store used for certificate verification to B. + +SSL_CTX_set0_chain_cert_store() and SSL_CTX_set1_chain_cert_store() +set the certificate store used for certificate chain building to B. + +SSL_set0_verify_cert_store(), SSL_set1_verify_cert_store(), +SSL_set0_chain_cert_store() and SSL_set1_chain_cert_store() are similar +except they apply to SSL structure B. + +All these functions are implemented as macros. Those containing a B<1> +increment the reference count of the supplied store so it must +be freed at some point after the operation. Those containing a B<0> do +not increment reference counts and the supplied store B be freed +after the operation. + +=head1 NOTES + +The stores pointers associated with an SSL_CTX structure are copied to any SSL +structures when SSL_new() is called. As a result SSL structures will not be +affected if the parent SSL_CTX store pointer is set to a new value. + +The verification store is used to verify the certificate chain sent by the +peer: that is an SSL/TLS client will use the verification store to verify +the server's certificate chain and a SSL/TLS server will use it to verify +any client certificate chain. + +The chain store is used to build the certificate chain. + +If the mode B is set or a certificate chain is +configured already (for example using the functions such as +L or +L) then +automatic chain building is disabled. + +If the mode B is set then automatic chain building +is disabled. + +If the chain or the verification store is not set then the store associated +with the parent SSL_CTX is used instead to retain compatibility with previous +versions of OpenSSL. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L +L +L +L +L +L +L +L +L +L +L + +=head1 HISTORY + +These functions were first added to OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod new file mode 100644 index 0000000..56c8609 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_alpn_select_cb.pod @@ -0,0 +1,197 @@ +=pod + +=head1 NAME + +SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, +SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, +SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated +- handle application layer protocol negotiation (ALPN) + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos, + unsigned int protos_len); + int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos, + unsigned int protos_len); + void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx, + int (*cb) (SSL *ssl, + const unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg), void *arg); + void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data, + unsigned int *len); + + void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx, + int (*cb)(SSL *ssl, + const unsigned char **out, + unsigned int *outlen, + void *arg), + void *arg); + void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx, + int (*cb)(SSL *s, + unsigned char **out, + unsigned char *outlen, + const unsigned char *in, + unsigned int inlen, + void *arg), + void *arg); + int SSL_select_next_proto(unsigned char **out, unsigned char *outlen, + const unsigned char *server, + unsigned int server_len, + const unsigned char *client, + unsigned int client_len) + void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data, + unsigned *len); + +=head1 DESCRIPTION + +SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to +set the list of protocols available to be negotiated. The B must be in +protocol-list format, described below. The length of B is specified in +B. + +SSL_CTX_set_alpn_select_cb() sets the application callback B used by a +server to select which protocol to use for the incoming connection. When B +is NULL, ALPN is not used. The B value is a pointer which is passed to +the application callback. + +B is the application defined callback. The B, B parameters are a +vector in protocol-list format. The value of the B, B vector +should be set to the value of a single protocol selected from the B, +B vector. The B buffer may point directly into B, or to a +buffer that outlives the handshake. The B parameter is the pointer set via +SSL_CTX_set_alpn_select_cb(). + +SSL_select_next_proto() is a helper function used to select protocols. It +implements the standard protocol selection. It is expected that this function +is called from the application callback B. The protocol data in B, +B and B, B must be in the protocol-list format +described below. The first item in the B, B list that +matches an item in the B, B list is selected, and returned +in B, B. The B value will point into either B or +B, so it should be copied immediately. If no match is found, the first +item in B, B is returned in B, B. This +function can also be used in the NPN callback. + +SSL_CTX_set_next_proto_select_cb() sets a callback B that is called when a +client needs to select a protocol from the server's provided list, and a +user-defined pointer argument B which will be passed to this callback. +For the callback itself, B +must be set to point to the selected protocol (which may be within B). +The length of the protocol name must be written into B. The +server's advertised protocols are provided in B and B. The +callback can assume that B is syntactically valid. The client must +select a protocol. It is fatal to the connection if this callback returns +a value other than B. The B parameter is the pointer +set via SSL_CTX_set_next_proto_select_cb(). + +SSL_CTX_set_next_protos_advertised_cb() sets a callback B that is called +when a TLS server needs a list of supported protocols for Next Protocol +Negotiation. The returned list must be in protocol-list format, described +below. The list is +returned by setting B to point to it and B to its length. This +memory will not be modified, but the B does keep a +reference to it. The callback should return B if it +wishes to advertise. Otherwise, no such extension will be included in the +ServerHello. + +SSL_get0_alpn_selected() returns a pointer to the selected protocol in B +with length B. It is not NUL-terminated. B is set to NULL and B +is set to 0 if no protocol has been selected. B must not be freed. + +SSL_get0_next_proto_negotiated() sets B and B to point to the +client's requested protocol for this connection. If the client did not +request any protocol or NPN is not enabled, then B is set to NULL and +B to 0. Note that +the client can request any protocol it chooses. The value returned from +this function need not be a member of the list of supported protocols +provided by the callback. + +=head1 NOTES + +The protocol-lists must be in wire-format, which is defined as a vector of +non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not +included in the length. Each string is limited to 255 bytes. A byte-string +length of 0 is invalid. A truncated byte-string is invalid. The length of the +vector is not in the vector itself, but in a separate variable. + +Example: + + unsigned char vector[] = { + 6, 's', 'p', 'd', 'y', '/', '1', + 8, 'h', 't', 't', 'p', '/', '1', '.', '1' + }; + unsigned int length = sizeof(vector); + +The ALPN callback is executed after the servername callback; as that servername +callback may update the SSL_CTX, and subsequently, the ALPN callback. + +If there is no ALPN proposed in the ClientHello, the ALPN callback is not +invoked. + +=head1 RETURN VALUES + +SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and +non-0 on failure. WARNING: these functions reverse the return value convention. + +SSL_select_next_proto() returns one of the following: + +=over 4 + +=item OPENSSL_NPN_NEGOTIATED + +A match was found and is returned in B, B. + +=item OPENSSL_NPN_NO_OVERLAP + +No match was found. The first item in B, B is returned in +B, B. + +=back + +The ALPN select callback B, must return one of the following: + +=over 4 + +=item SSL_TLSEXT_ERR_OK + +ALPN protocol selected. + +=item SSL_TLSEXT_ERR_ALERT_FATAL + +There was no overlap between the client's supplied list and the server +configuration. + +=item SSL_TLSEXT_ERR_NOACK + +ALPN protocol not selected, e.g., because no ALPN protocols are configured for +this connection. + +=back + +The callback set using SSL_CTX_set_next_proto_select_cb() should return +B if successful. Any other value is fatal to the connection. + +The callback set using SSL_CTX_set_next_protos_advertised_cb() should return +B if it wishes to advertise. Otherwise, no such extension +will be included in the ServerHello. + +=head1 SEE ALSO + +L, L, +L + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod new file mode 100644 index 0000000..eaa7a4e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_cb.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function + +=head1 SYNOPSIS + + #include + + void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg), void *arg); + void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg); + + int (*cert_cb)(SSL *ssl, void *arg); + +=head1 DESCRIPTION + +SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the cert_cb() callback, +B value is pointer which is passed to the application callback. + +When cert_cb() is NULL, no callback function is used. + +cert_cb() is the application defined callback. It is called before a +certificate will be used by a client or server. The callback can then inspect +the passed B structure and set or clear any appropriate certificates. If +the callback is successful it B return 1 even if no certificates have +been set. A zero is returned on error which will abort the handshake with a +fatal internal error alert. 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 cert_cb(). It is the job of the +cert_cb() to store information about the state of the last call, +if required to continue. + +=head1 NOTES + +An application will typically call SSL_use_certificate() and +SSL_use_PrivateKey() to set the end entity certificate and private key. +It can add intermediate and optionally the root CA certificates using +SSL_add1_chain_cert(). + +It might also call SSL_certs_clear() to delete any certificates associated +with the B object. + +The certificate callback functionality supersedes the (largely broken) +functionality provided by the old client certificate callback interface. +It is B called even is a certificate is already set so the callback +can modify or delete the existing certificate. + +A more advanced callback might examine the handshake parameters and set +whatever chain is appropriate. For example a legacy client supporting only +TLS v1.0 might receive a certificate chain signed using SHA1 whereas a +TLS v1.2 client which advertises support for SHA256 could receive a chain +using SHA256. + +Normal server sanity checks are performed on any certificates set +by the callback. So if an EC chain is set for a curve the client does not +support it will B be used. + +=head1 SEE ALSO + +L, L, +L, +L, +L, L + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod new file mode 100644 index 0000000..7f7a794 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_store.pod @@ -0,0 +1,73 @@ +=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 RESTRICTIONS + +The X509_STORE structure used by an SSL_CTX is used for verifying peer +certificates and building certificate chains, it is also shared by +every child SSL structure. Applications wanting finer control can use +functions such as SSL_CTX_set1_verify_cert_store() instead. + +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod new file mode 100644 index 0000000..af303f2 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cert_verify_callback.pod @@ -0,0 +1,74 @@ +=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 + +SSL_CTX_set_cert_verify_callback() does not provide diagnostic information. + +=head1 SEE ALSO + +L, L, +L, +L + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod new file mode 100644 index 0000000..4e66917 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_cipher_list.pod @@ -0,0 +1,74 @@ +=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 unless the security level excludes it. 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 ciphers using DHE 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 an 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 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod new file mode 100644 index 0000000..0252e7b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_CA_list.pod @@ -0,0 +1,103 @@ +=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 Z<>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 Z<>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 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod new file mode 100644 index 0000000..aed7d4f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_client_cert_cb.pod @@ -0,0 +1,103 @@ +=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 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. + +When client_cert_cb() 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 + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod new file mode 100644 index 0000000..afa45dc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ct_validation_callback.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + +ssl_ct_validation_cb, +SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, +SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, +SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - +control Certificate Transparency policy + +=head1 SYNOPSIS + + #include + + typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, + const STACK_OF(SCT) *scts, void *arg); + + int SSL_enable_ct(SSL *s, int validation_mode); + int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); + int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, + void *arg); + int SSL_CTX_set_ct_validation_callback(SSL_CTX *ctx, + ssl_ct_validation_cb callback, + void *arg); + void SSL_disable_ct(SSL *s); + void SSL_CTX_disable_ct(SSL_CTX *ctx); + int SSL_ct_is_enabled(const SSL *s); + int SSL_CTX_ct_is_enabled(const SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_enable_ct() and SSL_CTX_enable_ct() enable the processing of signed +certificate timestamps (SCTs) either for a given SSL connection or for all +connections that share the given SSL context, respectively. +This is accomplished by setting a built-in CT validation callback. +The behaviour of the callback is determined by the B argument, +which can be either of B or +B as described below. + +If B is equal to B, then in a full +TLS handshake with the verification mode set to B, if the peer +presents no valid SCTs the handshake will be aborted. +If the verification mode is B, the handshake will continue +despite lack of valid SCTs. +However, in that case if the verification status before the built-in callback +was B it will be set to B after the +callback. +Applications can call L to check the status at +handshake completion, even after session resumption since the verification +status is part of the saved session state. +See L, , L. + +If B is equal to B, then the +handshake continues, and the verification status is not modified, regardless of +the validation status of any SCTs. +The application can still inspect the validation status of the SCTs at +handshake completion. +Note that with session resumption there will not be any SCTs presented during +the handshake. +Therefore, in applications that delay SCT policy enforcement until after +handshake completion, such delayed SCT checks should only be performed when the +session is not resumed. + +SSL_set_ct_validation_callback() and SSL_CTX_set_ct_validation_callback() +register a custom callback that may implement a different policy than either of +the above. +This callback can examine the peer's SCTs and determine whether they are +sufficient to allow the connection to continue. +The TLS handshake is aborted if the verification mode is not B +and the callback returns a non-positive result. + +An arbitrary callback context argument, B, can be passed in when setting +the callback. +This will be passed to the callback whenever it is invoked. +Ownership of this context remains with the caller. + +If no callback is set, SCTs will not be requested and Certificate Transparency +validation will not occur. + +No callback will be invoked when the peer presents no certificate, e.g. by +employing an anonymous (aNULL) ciphersuite. +In that case the handshake continues as it would had no callback been +requested. +Callbacks are also not invoked when the peer certificate chain is invalid or +validated via DANE-TA(2) or DANE-EE(3) TLSA records which use a private X.509 +PKI, or no X.509 PKI at all, respectively. +Clients that require SCTs are expected to not have enabled any aNULL ciphers +nor to have specified server verification via DANE-TA(2) or DANE-EE(3) TLSA +records. + +SSL_disable_ct() and SSL_CTX_disable_ct() turn off CT processing, whether +enabled via the built-in or the custom callbacks, by setting a NULL callback. +These may be implemented as macros. + +SSL_ct_is_enabled() and SSL_CTX_ct_is_enabled() return 1 if CT processing is +enabled via either SSL_enable_ct() or a non-null custom callback, and 0 +otherwise. + +=head1 NOTES + +When SCT processing is enabled, OCSP stapling will be enabled. This is because +one possible source of SCTs is the OCSP response from a server. + +The time returned by SSL_SESSION_get_time() will be used to evaluate whether any +presented SCTs have timestamps that are in the future (and therefore invalid). + +=head1 RESTRICTIONS + +Certificate Transparency validation cannot be enabled and so a callback cannot +be set if a custom client extension handler has been registered to handle SCT +extensions (B). + +=head1 RETURN VALUES + +SSL_enable_ct(), SSL_CTX_enable_ct(), SSL_CTX_set_ct_validation_callback() and +SSL_set_ct_validation_callback() return 1 if the B is successfully +set. +They return 0 if an error occurs, e.g. a custom client extension handler has +been setup to handle SCTs. + +SSL_disable_ct() and SSL_CTX_disable_ct() do not return a result. + +SSL_CTX_ct_is_enabled() and SSL_ct_is_enabled() return a 1 if a non-null CT +validation callback is set, or 0 if no callback (or equivalently a NULL +callback) is set. + +=head1 SEE ALSO + +L, +, +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod new file mode 100644 index 0000000..4a2fa94 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ctlog_list_file.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_ctlog_list_file, SSL_CTX_set_ctlog_list_file - +load a Certificate Transparency log list from a file + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set_default_ctlog_list_file(SSL_CTX *ctx); + int SSL_CTX_set_ctlog_list_file(SSL_CTX *ctx, const char *path); + +=head1 DESCRIPTION + +SSL_CTX_set_default_ctlog_list_file() loads a list of Certificate Transparency +(CT) logs from the default file location, "ct_log_list.cnf", found in the +directory where OpenSSL is installed. + +SSL_CTX_set_ctlog_list_file() loads a list of CT logs from a specific path. +See L for the file format. + +=head1 NOTES + +These functions will not clear the existing CT log list - it will be appended +to. To replace the existing list, use L first. + +If an error occurs whilst parsing a particular log entry in the file, that log +entry will be skipped. + +=head1 RETURN VALUES + +SSL_CTX_set_default_ctlog_list_file() and SSL_CTX_set_ctlog_list_file() +return 1 if the log list is successfully loaded, and 0 if an error occurs. In +the case of an error, the log list may have been partially loaded. + +=head1 SEE ALSO + +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod new file mode 100644 index 0000000..2196906 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_default_passwd_cb.pod @@ -0,0 +1,113 @@ +=pod + +=head1 NAME + +SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata, +SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata, +SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata, +SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata - set or +get 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); + pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); + void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx); + + void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb); + void SSL_set_default_passwd_cb_userdata(SSL *s, void *u); + pem_password_cb *SSL_get_default_passwd_cb(SSL *s); + void *SSL_get_default_passwd_cb_userdata(SSL *s); + +=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 userdata, B, +which will be provided to the password callback on invocation. + +SSL_CTX_get_default_passwd_cb() returns a function pointer to the password +callback currently set in B. If no callback was explicitly set, the +NULL pointer is returned. + +SSL_CTX_get_default_passwd_cb_userdata() returns a pointer to the userdata +currently set in B. If no userdata was explicitly set, the NULL pointer +is returned. + +SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(), +SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform +the same function as their SSL_CTX counterparts, but using an SSL object. + +The password callback, which must be provided by the application, hands back the +password to be used during decryption. +On invocation a pointer to userdata +is provided. The function must store 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). +For more details, see L. + +=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 the callback 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 userdata storage and the +callback only returns the password already stored. + +When asking for the password interactively, the callback 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 + +These functions do not provide diagnostic information. + +=head1 EXAMPLES + +The following example returns the password provided as userdata 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 my_cb(char *buf, int size, int rwflag, void *u) + { + strncpy(buf, (char *)u, size); + buf[size - 1] = '\0'; + return strlen(buf); + } + +=head1 HISTORY + +SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(), +SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were +first added to OpenSSL 1.1.0 + +=head1 SEE ALSO + +L, +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod new file mode 100644 index 0000000..fd0364b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ex_data.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SSL_CTX_get_ex_data, SSL_CTX_set_ex_data, +SSL_get_ex_data, SSL_set_ex_data +- Store and retrieve extra data from the SSL_CTX, SSL or SSL_SESSION + +=head1 SYNOPSIS + + #include + + void *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx); + + int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, void *arg); + + void *SSL_get_ex_data(const SSL *s, int idx); + + int SSL_set_ex_data(SSL *s, int idx, void *arg); + +=head1 DESCRIPTION + +SSL*_set_ex_data() functions can be used to store arbitrary user data into the +B, or B object. The user must supply a unique index +which they can subsequently use to retrieve the data using SSL*_get_ex_data(). + +For more detailed information see L and +L which implement these functions and +L for generating a unique index. + +=head1 RETURN VALUES + +The SSL*_set_ex_data() functions return 1 if the item is successfully stored +and 0 if it is not. +The SSL*_get_ex_data() functions return the ex_data pointer if successful, +otherwise NULL. + +=head1 SEE ALSO + +L, L, +L + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod new file mode 100644 index 0000000..1b1171f --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_generate_session_id.pod @@ -0,0 +1,139 @@ +=pod + +=head1 NAME + +SSL_CTX_set_generate_session_id, SSL_set_generate_session_id, +SSL_has_matching_session_id, GEN_SESSION_CB +- 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 between 1 and 32 bytes. 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. + +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^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. + +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; + 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 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod new file mode 100644 index 0000000..f36f217 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_info_callback.pod @@ -0,0 +1,162 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod new file mode 100644 index 0000000..482751e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_max_cert_list.pod @@ -0,0 +1,82 @@ +=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 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod new file mode 100644 index 0000000..ff080e4 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_min_proto_version.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_set_min_proto_version, SSL_CTX_set_max_proto_version, +SSL_CTX_get_min_proto_version, SSL_CTX_get_max_proto_version, +SSL_set_min_proto_version, SSL_set_max_proto_version, +SSL_get_min_proto_version, SSL_get_max_proto_version - Get and set minimum +and maximum supported protocol version + +=head1 SYNOPSIS + + #include + + int SSL_CTX_set_min_proto_version(SSL_CTX *ctx, int version); + int SSL_CTX_set_max_proto_version(SSL_CTX *ctx, int version); + int SSL_CTX_get_min_proto_version(SSL_CTX *ctx); + int SSL_CTX_get_max_proto_version(SSL_CTX *ctx); + + int SSL_set_min_proto_version(SSL *ssl, int version); + int SSL_set_max_proto_version(SSL *ssl, int version); + int SSL_get_min_proto_version(SSL *ssl); + int SSL_get_max_proto_version(SSL *ssl); + +=head1 DESCRIPTION + +The functions get or set the minimum and maximum supported protocol versions +for the B or B. +This works in combination with the options set via +L that also make it possible to disable +specific protocol versions. +Use these functions instead of disabling specific protocol versions. + +Setting the minimum or maximum version to 0, will enable protocol +versions down to the lowest version, or up to the highest version +supported by the library, respectively. + +Getters return 0 in case B or B have been configured to +automatically use the lowest or highest version supported by the library. + +Currently supported versions are B, B, +B, B for TLS and B, +B for DTLS. + +=head1 RETURN VALUES + +These setter functions return 1 on success and 0 on failure. The getter +functions return the configured version or 0 for auto-configuration of +lowest or highest protocol, respectively. + +=head1 NOTES + +All these functions are implemented using macros. + +=head1 HISTORY + +The setter functions were added in OpenSSL 1.1.0. The getter functions +were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod new file mode 100644 index 0000000..1b3e783 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_mode.pod @@ -0,0 +1,114 @@ +=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. +Using this flag can +save around 34k per idle SSL connection. +This flag has no effect on SSL v2 connections, or on DTLS connections. + +=item SSL_MODE_SEND_FALLBACK_SCSV + +Send TLS_FALLBACK_SCSV in the ClientHello. +To be set only by applications that reconnect with a downgraded protocol +version; see draft-ietf-tls-downgrade-scsv-00 for details. + +DO NOT ENABLE THIS if your application attempts a normal handshake. +Only use this in explicit fallback retries, following the guidance +in draft-ietf-tls-downgrade-scsv-00. + +=item SSL_MODE_ASYNC + +Enable asynchronous processing. TLS I/O operations may indicate a retry with +SSL_ERROR_WANT_ASYNC with this mode set if an asynchronous capable engine is +used to perform cryptographic operations. See L. + +=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, L + +=head1 HISTORY + +SSL_MODE_ASYNC was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod new file mode 100644 index 0000000..9546e75 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_msg_callback.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_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 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod new file mode 100644 index 0000000..241aeb3 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_options.pod @@ -0,0 +1,307 @@ +=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 + +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. +Note, this is implemented via a macro. + +=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_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_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 + +This option is no longer implemented and is treated as no op. + +=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 SSL/TLS server will choose following its +own preferences. + +=item SSL_OP_PKCS1_CHECK_1 + +... + +=item SSL_OP_PKCS1_CHECK_2 + +... + + +=item SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, +SSL_OP_NO_TLSv1_2, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2 + +These options turn off the SSLv3, TLSv1, TLSv1.1 or TLSv1.2 protocol +versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS, +respectively. +As of OpenSSL 1.1.0, these options are deprecated, use +L and +L instead. + +=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 + +Allow 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. + +=item SSL_OP_NO_ENCRYPT_THEN_MAC + +Normally clients and servers will transparently attempt to negotiate the +RFC7366 Encrypt-then-MAC option on TLS and DTLS connection. + +If this option is set, Encrypt-then-MAC is disabled. Clients will not +propose, and servers will not accept the extension. + +=item SSL_OP_NO_RENEGOTIATION + +Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest +messages, and ignore renegotiation requests via ClientHello. + +=back + +=head1 SECURE RENEGOTIATION + +OpenSSL always attempts to use secure renegotiation as +described in RFC5746. This counters the prefix attack described in +CVE-2009-3555 and elsewhere. + +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. + +If the option B is set then +renegotiation B succeeds. + +=head2 Patched OpenSSL client and unpatched server. + +If the option B or +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(). + +The difference between the B and +B options is that +B enables initial connections and secure +renegotiation between OpenSSL clients and unpatched servers B, while +B allows initial connections +and renegotiation between OpenSSL and unpatched clients or servers. + +=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 + +The attempt to always try to use secure renegotiation was added in +Openssl 0.9.8m. + +B was added in OpenSSL 1.1.0h. + +=head1 COPYRIGHT + +Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod new file mode 100644 index 0000000..a417508 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_psk_client_callback.pod @@ -0,0 +1,63 @@ +=pod + +=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 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. + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +Copyright 2005 Nokia. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod new file mode 100644 index 0000000..d39d747 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_quiet_shutdown.pod @@ -0,0 +1,72 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod new file mode 100644 index 0000000..bea8390 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_read_ahead.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + +SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead, +SSL_set_read_ahead, SSL_get_read_ahead, +SSL_CTX_get_default_read_ahead +- manage whether to read as many input bytes as possible + +=head1 SYNOPSIS + + #include + + void SSL_set_read_ahead(SSL *s, int yes); + int SSL_get_read_ahead(const SSL *s); + + SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes); + long SSL_CTX_get_read_ahead(SSL_CTX *ctx); + long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx); + +=head1 DESCRIPTION + +SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as +many input bytes as possible (for non-blocking reads) or not. For example if +B bytes are currently required by OpenSSL, but B bytes are available from +the underlying BIO (where B > B), then OpenSSL will read all B bytes +into its buffer (providing that the buffer is large enough) if reading ahead is +on, or B bytes otherwise. The parameter B or B should be 0 to ensure +reading ahead is off, or non zero otherwise. +SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead(). + +SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading +ahead has been set or not. + +=head1 NOTES + +These functions have no impact when used with DTLS. The return values for +SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting +B can impact the behaviour of the SSL_pending() function +(see L). + +=head1 RETURN VALUES + +SSL_get_read_ahead() and SSL_CTX_get_read_ahead() return 0 if reading ahead is off, +and non zero otherwise. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod new file mode 100644 index 0000000..577b393 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_security_level.pod @@ -0,0 +1,169 @@ +=pod + +=head1 NAME + +SSL_CTX_set_security_level, SSL_set_security_level, SSL_CTX_get_security_level, SSL_get_security_level, SSL_CTX_set_security_callback, SSL_set_security_callback, SSL_CTX_get_security_callback, SSL_get_security_callback, SSL_CTX_set0_security_ex_data, SSL_set0_security_ex_data, SSL_CTX_get0_security_ex_data, SSL_get0_security_ex_data - SSL/TLS security framework + +=head1 SYNOPSIS + + #include + + void SSL_CTX_set_security_level(SSL_CTX *ctx, int level); + void SSL_set_security_level(SSL *s, int level); + + int SSL_CTX_get_security_level(const SSL_CTX *ctx); + int SSL_get_security_level(const SSL *s); + + void SSL_CTX_set_security_callback(SSL_CTX *ctx, + int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, + void *other, void *ex)); + + void SSL_set_security_callback(SSL *s, + int (*cb)(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, + void *other, void *ex)); + + int (*SSL_CTX_get_security_callback(const SSL_CTX *ctx))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); + int (*SSL_get_security_callback(const SSL *s))(SSL *s, SSL_CTX *ctx, int op, int bits, int nid, void *other, void *ex); + + void SSL_CTX_set0_security_ex_data(SSL_CTX *ctx, void *ex); + void SSL_set0_security_ex_data(SSL *s, void *ex); + + void *SSL_CTX_get0_security_ex_data(const SSL_CTX *ctx); + void *SSL_get0_security_ex_data(const SSL *s); + +=head1 DESCRIPTION + +The functions SSL_CTX_set_security_level() and SSL_set_security_level() set +the security level to B. If not set the library default security level +is used. + +The functions SSL_CTX_get_security_level() and SSL_get_security_level() +retrieve the current security level. + +SSL_CTX_set_security_callback(), SSL_set_security_callback(), +SSL_CTX_get_security_callback() and SSL_get_security_callback() get or set +the security callback associated with B or B. If not set a default +security callback is used. The meaning of the parameters and the behaviour +of the default callbacks is described below. + +SSL_CTX_set0_security_ex_data(), SSL_set0_security_ex_data(), +SSL_CTX_get0_security_ex_data() and SSL_get0_security_ex_data() set the +extra data pointer passed to the B parameter of the callback. This +value is passed to the callback verbatim and can be set to any convenient +application specific value. + +=head1 DEFAULT CALLBACK BEHAVIOUR + +If an application doesn't set its own security callback the default +callback is used. It is intended to provide sane defaults. The meaning +of each level is described below. + +=over 4 + +=item B + +Everything is permitted. This retains compatibility with previous versions of +OpenSSL. + +=item B + +The security level corresponds to a minimum of 80 bits of security. Any +parameters offering below 80 bits of security are excluded. As a result RSA, +DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits +are prohibited. All export ciphersuites are prohibited since they all offer +less than 80 bits of security. SSL version 2 is prohibited. Any ciphersuite +using MD5 for the MAC is also prohibited. + +=item B + +Security level set to 112 bits of security. As a result RSA, DSA and DH keys +shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. +In addition to the level 1 exclusions any ciphersuite using RC4 is also +prohibited. SSL version 3 is also not allowed. Compression is disabled. + +=item B + +Security level set to 128 bits of security. As a result RSA, DSA and DH keys +shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. +In addition to the level 2 exclusions ciphersuites not offering forward +secrecy are prohibited. TLS versions below 1.1 are not permitted. Session +tickets are disabled. + +=item B + +Security level set to 192 bits of security. As a result RSA, DSA and DH keys +shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. +Ciphersuites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are +not permitted. + +=item B + +Security level set to 256 bits of security. As a result RSA, DSA and DH keys +shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. + +=back + +=head1 APPLICATION DEFINED SECURITY CALLBACKS + +I + +=head1 NOTES + +B at this time setting the security level higher than 1 for +general internet use is likely to cause B interoperability +issues and is not recommended. This is because the B algorithm +is very widely used in certificates and will be rejected at levels +higher than 1 because it only offers 80 bits of security. + +The default security level can be configured when OpenSSL is compiled by +setting B<-DOPENSSL_TLS_SECURITY_LEVEL=level>. If not set then 1 is used. + +The security framework disables or reject parameters inconsistent with the +set security level. In the past this was difficult as applications had to set +a number of distinct parameters (supported ciphers, supported curves supported +signature algorithms) to achieve this end and some cases (DH parameter size +for example) could not be checked at all. + +By setting an appropriate security level much of this complexity can be +avoided. + +The bits of security limits affect all relevant parameters including +ciphersuite encryption algorithms, supported ECC curves, supported +signature algorithms, DH parameter sizes, certificate key sizes and +signature algorithms. This limit applies no matter what other custom +settings an application has set: so if the ciphersuite is set to B +then only ciphersuites consistent with the security level are permissible. + +See SP800-57 for how the security limits are related to individual +algorithms. + +Some security levels require large key sizes for non-ECC public key +algorithms which can severely degrade performance. For example 256 bits +of security requires the use of RSA keys of at least 15360 bits in size. + +Some restrictions can be gracefully handled: for example ciphersuites +offering insufficient security are not sent by the client and will not +be selected by the server. Other restrictions such as the peer certificate +key size or the DH parameter size will abort the handshake with a fatal +alert. + +Attempts to set certificates or parameters with insufficient security are +also blocked. For example trying to set a certificate using a 512 bit RSA +key using SSL_CTX_use_certificate() at level 1. Applications which do not +check the return values for errors will misbehave: for example it might +appear that a certificate is not set at all because it had been rejected. + +=head1 HISTORY + +These functions were first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod new file mode 100644 index 0000000..b237076 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_cache_mode.pod @@ -0,0 +1,141 @@ +=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 look 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 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod new file mode 100644 index 0000000..a873b03 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_session_id_context.pod @@ -0,0 +1,92 @@ +=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 Z<>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 Z<>1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod new file mode 100644 index 0000000..accf5af --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_split_send_fragment.pod @@ -0,0 +1,132 @@ +=pod + +=head1 NAME + +SSL_CTX_set_max_send_fragment, SSL_set_max_send_fragment, +SSL_CTX_set_split_send_fragment, SSL_set_split_send_fragment, +SSL_CTX_set_max_pipelines, SSL_set_max_pipelines, +SSL_CTX_set_default_read_buffer_len, SSL_set_default_read_buffer_len - Control +fragment sizes and pipelining operations + +=head1 SYNOPSIS + + #include + + long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long); + long SSL_set_max_send_fragment(SSL *ssl, long m); + + long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m); + long SSL_set_max_pipelines(SSL_CTX *ssl, long m); + + long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m); + long SSL_set_split_send_fragment(SSL *ssl, long m); + + void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len); + void SSL_set_default_read_buffer_len(SSL *s, size_t len); + +=head1 DESCRIPTION + +Some engines are able to process multiple simultaneous crypto operations. This +capability could be utilised to parallelise the processing of a single +connection. For example a single write can be split into multiple records and +each one encrypted independently and in parallel. Note: this will only work in +TLS1.1+. There is no support in SSLv3, TLSv1.0 or DTLS (any version). This +capability is known as "pipelining" within OpenSSL. + +In order to benefit from the pipelining capability. You need to have an engine +that provides ciphers that support this. The OpenSSL "dasync" engine provides +AES128-SHA based ciphers that have this capability. However these are for +development and test purposes only. + +SSL_CTX_set_max_send_fragment() and SSL_set_max_send_fragment() set the +B parameter for SSL_CTX and SSL objects respectively. This +value restricts the amount of plaintext bytes that will be sent in any one +SSL/TLS record. By default its value is SSL3_RT_MAX_PLAIN_LENGTH (16384). These +functions will only accept a value in the range 512 - SSL3_RT_MAX_PLAIN_LENGTH. + +SSL_CTX_set_max_pipelines() and SSL_set_max_pipelines() set the maximum number +of pipelines that will be used at any one time. This value applies to both +"read" pipelining and "write" pipelining. By default only one pipeline will be +used (i.e. normal non-parallel operation). The number of pipelines set must be +in the range 1 - SSL_MAX_PIPELINES (32). Setting this to a value > 1 will also +automatically turn on "read_ahead" (see L). This is +explained further below. OpenSSL will only every use more than one pipeline if +a ciphersuite is negotiated that uses a pipeline capable cipher provided by an +engine. + +Pipelining operates slightly differently for reading encrypted data compared to +writing encrypted data. SSL_CTX_set_split_send_fragment() and +SSL_set_split_send_fragment() define how data is split up into pipelines when +writing encrypted data. The number of pipelines used will be determined by the +amount of data provided to the SSL_write() call divided by +B. + +For example if B is set to 2000 and B is 4 +then: + +SSL_write called with 0-2000 bytes == 1 pipeline used + +SSL_write called with 2001-4000 bytes == 2 pipelines used + +SSL_write called with 4001-6000 bytes == 3 pipelines used + +SSL_write called with 6001+ bytes == 4 pipelines used + +B must always be less than or equal to +B. By default it is set to be equal to B. +This will mean that the same number of records will always be created as would +have been created in the non-parallel case, although the data will be +apportioned differently. In the parallel case data will be spread equally +between the pipelines. + +Read pipelining is controlled in a slightly different way than with write +pipelining. While reading we are constrained by the number of records that the +peer (and the network) can provide to us in one go. The more records we can get +in one go the more opportunity we have to parallelise the processing. As noted +above when setting B to a value greater than one, B +is automatically set. The B parameter causes OpenSSL to attempt to +read as much data into the read buffer as the network can provide and will fit +into the buffer. Without this set data is read into the read buffer one record +at a time. The more data that can be read, the more opportunity there is for +parallelising the processing at the cost of increased memory overhead per +connection. Setting B can impact the behaviour of the SSL_pending() +function (see L). + +The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() +functions control the size of the read buffer that will be used. The B +parameter sets the size of the buffer. The value will only be used if it is +greater than the default that would have been used anyway. The normal default +value depends on a number of factors but it will be at least +SSL3_RT_MAX_PLAIN_LENGTH + SSL3_RT_MAX_ENCRYPTED_OVERHEAD (16704) bytes. + +=head1 RETURN VALUES + +All non-void functions return 1 on success and 0 on failure. + +=head1 NOTES + +With the exception of SSL_CTX_set_default_read_buffer_len() and +SSL_set_default_read_buffer_len() all these functions are implemented using +macros. + +=head1 HISTORY + +The SSL_CTX_set_max_pipelines(), SSL_set_max_pipelines(), +SSL_CTX_set_split_send_fragment(), SSL_set_split_send_fragment(), +SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len() +functions were added in OpenSSL 1.1.0. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod new file mode 100644 index 0000000..22c0370 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_ssl_version.pod @@ -0,0 +1,70 @@ +=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 Z<>0 + +The new choice failed, check the error stack to find out the reason. + +=item Z<>1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L, L, +L, L, +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod new file mode 100644 index 0000000..470efdf --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_timeout.pod @@ -0,0 +1,68 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod new file mode 100644 index 0000000..c12ff0e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod @@ -0,0 +1,125 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_status_cb, +SSL_CTX_get_tlsext_status_cb, +SSL_CTX_set_tlsext_status_arg, +SSL_CTX_get_tlsext_status_arg, +SSL_CTX_set_tlsext_status_type, +SSL_CTX_get_tlsext_status_type, +SSL_set_tlsext_status_type, +SSL_get_tlsext_status_type, +SSL_get_tlsext_status_ocsp_resp, +SSL_set_tlsext_status_ocsp_resp +- OCSP Certificate Status Request functions + +=head1 SYNOPSIS + + #include + + long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, + int (*callback)(SSL *, void *)); + long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, + int (**callback)(SSL *, void *)); + + long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); + long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg); + + long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type); + long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx); + + long SSL_set_tlsext_status_type(SSL *s, int type); + long SSL_get_tlsext_status_type(SSL *s); + + long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp); + long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len); + +=head1 DESCRIPTION + +A client application may request that a server send back an OCSP status response +(also known as OCSP stapling). To do so the client should call the +SSL_CTX_set_tlsext_status_type() function prior to the creation of any SSL +objects. Alternatively an application can call the SSL_set_tlsext_status_type() +function on an individual SSL object prior to the start of the handshake. +Currently the only supported type is B. This value +should be passed in the B argument. Calling +SSL_CTX_get_tlsext_status_type() will return the type B +previously set via SSL_CTX_set_tlsext_status_type() or -1 if not set. + +The client should additionally provide a callback function to decide what to do +with the returned OCSP response by calling SSL_CTX_set_tlsext_status_cb(). The +callback function should determine whether the returned OCSP response is +acceptable or not. The callback will be passed as an argument the value +previously set via a call to SSL_CTX_set_tlsext_status_arg(). Note that the +callback will not be called in the event of a handshake where session resumption +occurs (because there are no Certificates exchanged in such a handshake). +The callback previously set via SSL_CTX_set_tlsext_status_cb() can be retrieved +by calling SSL_CTX_get_tlsext_status_cb(), and the argument by calling +SSL_CTX_get_tlsext_status_arg(). + +On the client side SSL_get_tlsext_status_type() can be used to determine whether +the client has previously called SSL_set_tlsext_status_type(). It will return +B if it has been called or -1 otherwise. On the server +side SSL_get_tlsext_status_type() can be used to determine whether the client +requested OCSP stapling. If the client requested it then this function will +return B, or -1 otherwise. + +The response returned by the server can be obtained via a call to +SSL_get_tlsext_status_ocsp_resp(). The value B<*resp> will be updated to point +to the OCSP response data and the return value will be the length of that data. +Typically a callback would obtain an OCSP_RESPONSE object from this data via a +call to the d2i_OCSP_RESPONSE() function. If the server has not provided any +response data then B<*resp> will be NULL and the return value from +SSL_get_tlsext_status_ocsp_resp() will be -1. + +A server application must also call the SSL_CTX_set_tlsext_status_cb() function +if it wants to be able to provide clients with OCSP Certificate Status +responses. Typically the server callback would obtain the server certificate +that is being sent back to the client via a call to SSL_get_certificate(); +obtain the OCSP response to be sent back; and then set that response data by +calling SSL_set_tlsext_status_ocsp_resp(). A pointer to the response data should +be provided in the B argument, and the length of that data should be in +the B argument. + +=head1 RETURN VALUES + +The callback when used on the client side should return a negative value on +error; 0 if the response is not acceptable (in which case the handshake will +fail) or a positive value if it is acceptable. + +The callback when used on the server side should return with either +SSL_TLSEXT_ERR_OK (meaning that the OCSP response that has been set should be +returned), SSL_TLSEXT_ERR_NOACK (meaning that an OCSP response should not be +returned) or SSL_TLSEXT_ERR_ALERT_FATAL (meaning that a fatal error has +occurred). + +SSL_CTX_set_tlsext_status_cb(), SSL_CTX_set_tlsext_status_arg(), +SSL_CTX_set_tlsext_status_type(), SSL_set_tlsext_status_type() and +SSL_set_tlsext_status_ocsp_resp() return 0 on error or 1 on success. + +SSL_CTX_get_tlsext_status_type() returns the value previously set by +SSL_CTX_set_tlsext_status_type(), or -1 if not set. + +SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data +or -1 if there is no OCSP response data. + +SSL_get_tlsext_status_type() returns B on the client +side if SSL_set_tlsext_status_type() was previously called, or on the server +side if the client requested OCSP stapling. Otherwise -1 is returned. + +=head1 HISTORY + +SSL_get_tlsext_status_type(), SSL_CTX_get_tlsext_status_type() and +SSL_CTX_set_tlsext_status_type() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod new file mode 100644 index 0000000..34d8ce9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod @@ -0,0 +1,198 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing + +=head1 SYNOPSIS + + #include + + long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, + int (*cb)(SSL *s, unsigned char key_name[16], + unsigned char iv[EVP_MAX_IV_LENGTH], + EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); + +=head1 DESCRIPTION + +SSL_CTX_set_tlsext_ticket_key_cb() sets a callback function I for handling +session tickets for the ssl context I. Session tickets, defined in +RFC5077 provide an enhanced session resumption capability where the server +implementation is not required to maintain per session state. It only applies +to TLS and there is no SSLv3 implementation. + +The callback function I will be called for every client instigated TLS +session when session ticket extension is presented in the TLS hello +message. It is the responsibility of this function to create or retrieve the +cryptographic parameters and to maintain their state. + +The OpenSSL library uses your callback function to help implement a common TLS +ticket construction state according to RFC5077 Section 4 such that per session +state is unnecessary and a small set of cryptographic variables needs to be +maintained by the callback function implementation. + +In order to reuse a session, a TLS client must send the a session ticket +extension to the server. The client can only send exactly one session ticket. +The server, through the callback function, either agrees to reuse the session +ticket information or it starts a full TLS handshake to create a new session +ticket. + +Before the callback function is started I and I have been +initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively. + +For new sessions tickets, when the client doesn't present a session ticket, or +an attempted retrieval of the ticket failed, or a renew option was indicated, +the callback function will be called with I equal to 1. The OpenSSL +library expects that the function will set an arbitrary I, initialize +I, and set the cipher context I and the hash context I. + +The I is 16 characters long and is used as a key identifier. + +The I length is the length of the IV of the corresponding cipher. The +maximum IV length is B bytes defined in B. + +The initialization vector I should be a random value. The cipher context +I should use the initialisation vector I. The cipher context can be +set using L. The hmac context can be set using +L. + +When the client presents a session ticket, the callback function with be called +with I set to 0 indicating that the I function should retrieve a set +of parameters. In this case I and I have already been parsed out of +the session ticket. The OpenSSL library expects that the I will be used +to retrieve a cryptographic parameters and that the cryptographic context +I will be set with the retrieved parameters and the initialization vector +I. using a function like L. The I needs to be +set using L. + +If the I is still valid but a renewal of the ticket is required the +callback function should return 2. The library will call the callback again +with an argument of enc equal to 1 to set the new ticket. + +The return value of the I function is used by OpenSSL to determine what +further processing will occur. The following return values have meaning: + +=over 4 + +=item Z<>2 + +This indicates that the I and I have been set and the session can +continue on those parameters. Additionally it indicates that the session +ticket is in a renewal period and should be replaced. The OpenSSL library will +call I again with an enc argument of 1 to set the new ticket (see RFC5077 +3.3 paragraph 2). + +=item Z<>1 + +This indicates that the I and I have been set and the session can +continue on those parameters. + +=item Z<>0 + +This indicates that it was not possible to set/retrieve a session ticket and +the SSL/TLS session will continue by negotiating a set of cryptographic +parameters or using the alternate SSL/TLS resumption mechanism, session ids. + +If called with enc equal to 0 the library will call the I again to get +a new set of parameters. + +=item less than 0 + +This indicates an error. + +=back + +=head1 NOTES + +Session resumption shortcuts the TLS so that the client certificate +negotiation don't occur. It makes up for this by storing client certificate +an all other negotiated state information encrypted within the ticket. In a +resumed session the applications will have all this state information available +exactly as if a full negotiation had occurred. + +If an attacker can obtain the key used to encrypt a session ticket, they can +obtain the master secret for any ticket using that key and decrypt any traffic +using that session: even if the ciphersuite supports forward secrecy. As +a result applications may wish to use multiple keys and avoid using long term +keys stored in files. + +Applications can use longer keys to maintain a consistent level of security. +For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key +the overall security is only 128 bits because breaking the ticket key will +enable an attacker to obtain the session keys. + +=head1 EXAMPLES + +Reference Implementation: + SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb); + .... + + static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc) + { + if (enc) { /* create new session */ + if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) { + return -1; /* insufficient random */ + } + + key = currentkey(); /* something that you need to implement */ + if ( !key ) { + /* current key doesn't exist or isn't valid */ + key = createkey(); /* something that you need to implement. + * createkey needs to initialise, a name, + * an aes_key, a hmac_key and optionally + * an expire time. */ + if ( !key ) { /* key couldn't be created */ + return 0; + } + } + memcpy(key_name, key->name, 16); + + EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv); + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + + return 1; + + } else { /* retrieve session */ + key = findkey(name); + + if (!key || key->expire < now() ) { + return 0; + } + + HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); + EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv ); + + if (key->expire < ( now() - RENEW_TIME ) ) { + /* return 2 - this session will get a new ticket even though the current is still valid */ + return 2; + } + return 1; + + } + } + + + +=head1 RETURN VALUES + +returns 0 to indicate the callback function was set. + +=head1 SEE ALSO + +L, L, +L, +L, +L, +L, +L, + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod new file mode 100644 index 0000000..fbfb8cb --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -0,0 +1,137 @@ +=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 *ctx, + 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. + +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. This application +guarantees that "strong" primes are used. + +Files dh2048.pem, and dh4096.pem in the 'apps' directory of the 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. Generation of custom DH +parameters during installation should still be preferred to stop an +attacker from specializing on a commonly used group. File dh1024.pem +contains old parameters that must not be used by applications. + +An application may either directly specify the DH parameters or +can supply the DH parameters via a callback function. + +Previous versions of the callback used B and B +parameters to control parameter generation for export and non-export +cipher suites. Modern servers that do not support export ciphersuites +are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use +the callback but ignore B and B and simply +supply at least 2048-bit parameters in the callback. + +=head1 EXAMPLES + +Setup DH parameters with a key length of 2048 bits. (Error handling +partly left out.) + + Command-line parameter generation: + $ openssl dhparam -out dh_param_2048.pem 2048 + + Code for setting up parameters during server initialization: + + ... + SSL_CTX ctx = SSL_CTX_new(); + ... + + /* Set up ephemeral DH parameters. */ + DH *dh_2048 = NULL; + FILE *paramfile; + paramfile = fopen("dh_param_2048.pem", "r"); + if (paramfile) { + dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); + fclose(paramfile); + } else { + /* Error. */ + } + if (dh_2048 == NULL) { + /* Error. */ + } + if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { + /* Error. */ + } + ... + +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod new file mode 100644 index 0000000..7993498 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_set_verify.pod @@ -0,0 +1,307 @@ +=pod + +=head1 NAME + +SSL_get_ex_data_X509_STORE_CTX_idx, +SSL_CTX_set_verify, SSL_set_verify, +SSL_CTX_set_verify_depth, SSL_set_verify_depth, +SSL_verify_cb +- set peer certificate verification parameters + +=head1 SYNOPSIS + + #include + + void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback); + void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback); + SSL_get_ex_data_X509_STORE_CTX_idx(void); + + void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); + void SSL_set_verify_depth(SSL *s, int depth); + + + typedef int (*SSL_verify_cb)(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. Within the callback function, +B can be called to get the data index +of the current SSL object that is doing the verification. + +SSL_CTX_set_verify_depth() sets the maximum B for the certificate chain +verification that shall be allowed for B. + +SSL_set_verify_depth() sets the maximum B for the certificate chain +verification that shall be allowed for B. + +=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 + +If the B is SSL_VERIFY_NONE none of the other flags may be set. + +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 a limit on the +number of certificates between the end-entity and trust-anchor certificates. +Neither the +end-entity nor the trust-anchor certificates count against B. If the +certificate chain needed to reach a trusted issuer is longer than B, +X509_V_ERR_CERT_CHAIN_TOO_LONG 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, 2 and 3 (0 being the end-entity and 3 the +trust-anchor). +The default depth limit is 100, +allowing for the peer certificate, at most 100 intermediate CA certificates and +a final trust anchor certificate. + +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 any flags are set. This can lead to +unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as +required. + +=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(err_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 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod new file mode 100644 index 0000000..c645f58 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_certificate.pod @@ -0,0 +1,180 @@ +=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_file, +SSL_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_file(SSL_CTX *ctx, const char *file); + int SSL_use_certificate_chain_file(SSL *ssl, 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. + +SSL_CTX_use_certificate_chain_file() loads a certificate chain from +B 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. SSL_use_certificate_chain_file() is +similar except it loads the certificate chain into B. + +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 several private +key/certificate pairs at a time. The certificate used depends on the +cipher selected, 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. Note: versions of OpenSSL before 1.0.2 only had a single +certificate chain store for all certificate types, OpenSSL 1.0.2 and later +have a separate chain store for each type. SSL_CTX_use_certificate_chain_file() +should be used 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, +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod new file mode 100644 index 0000000..753074a --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_psk_identity_hint.pod @@ -0,0 +1,87 @@ +=pod + +=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 Z<>0 + +PSK identity was not found. An "unknown_psk_identity" alert message +will be sent and the connection setup fails. + +=item E0 + +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. + +=back + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +Copyright 2005 Nokia. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod new file mode 100644 index 0000000..bd496ff --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_CTX_use_serverinfo.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_CTX_use_serverinfo, SSL_CTX_use_serverinfo_file - use serverinfo extension + +=head1 SYNOPSIS + + #include + + int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo, + size_t serverinfo_length); + + int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file); + +=head1 DESCRIPTION + +These functions load "serverinfo" TLS ServerHello Extensions into the SSL_CTX. +A "serverinfo" extension is returned in response to an empty ClientHello +Extension. + +SSL_CTX_use_serverinfo() loads one or more serverinfo extensions from +a byte array into B. The extensions must be concatenated into a +sequence of bytes. Each extension must consist of a 2-byte Extension Type, +a 2-byte length, and then length bytes of extension_data. + +SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from +B into B. The extensions must be in PEM format. Each extension +must consist of a 2-byte Extension Type, a 2-byte length, and then length +bytes of extension_data. Each PEM extension name must begin with the phrase +"BEGIN SERVERINFO FOR ". + +If more than one certificate (RSA/DSA) is installed using +SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the +last certificate installed. If e.g. the last item was a RSA certificate, the +loaded serverinfo extension data will be loaded for that certificate. To +use the serverinfo extension for multiple certificates, +SSL_CTX_use_serverinfo() needs to be called multiple times, once B +each time a certificate is loaded. + +=head1 RETURN VALUES + +On success, the functions return 1. +On failure, the functions return 0. Check out the error stack to find out +the reason. + +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod new file mode 100644 index 0000000..5bea785 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_free.pod @@ -0,0 +1,78 @@ +=pod + +=head1 NAME + +SSL_SESSION_new, +SSL_SESSION_up_ref, +SSL_SESSION_free - create, free and manage SSL_SESSION structures + +=head1 SYNOPSIS + + #include + + SSL_SESSION *SSL_SESSION_new(void); + int SSL_SESSION_up_ref(SSL_SESSION *ses); + void SSL_SESSION_free(SSL_SESSION *session); + +=head1 DESCRIPTION + +SSL_SESSION_new() creates a new SSL_SESSION structure and returns a pointer to +it. + +SSL_SESSION_up_ref() increments the reference count on the given SSL_SESSION +structure. + +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. +If B is NULL nothing is done. + +=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_new returns a pointer to the newly allocated SSL_SESSION structure +or NULL on error. + +SSL_SESSION_up_ref returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L, L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod new file mode 100644 index 0000000..fdd36ed --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_cipher.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_cipher - retrieve the SSL cipher associated with a session + +=head1 SYNOPSIS + + #include + + const SSL_CIPHER *SSL_SESSION_get0_cipher(const SSL_SESSSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_cipher() retrieves the cipher that was used by the +connection when the session was created, or NULL if it cannot be determined. + +The value returned is a pointer to an object maintained within B and +should not be released. + +=head1 SEE ALSO + +L, +L, +L, +L, +L + +=head1 HISTORY + +SSL_SESSION_get0_cipher() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod new file mode 100644 index 0000000..6fb12be --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_hostname.pod @@ -0,0 +1,37 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_hostname - retrieve the SNI hostname associated with a session + +=head1 SYNOPSIS + + #include + + const char *SSL_SESSION_get0_hostname(const SSL_SESSSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_hostname() retrieves the SNI value that was sent by the +client when the session was created, or NULL if no value was sent. + +The value returned is a pointer to memory maintained within B and +should not be free'd. + +=head1 SEE ALSO + +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod new file mode 100644 index 0000000..ee4a256 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_id_context.pod @@ -0,0 +1,56 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_id_context, +SSL_SESSION_set1_id_context +- get and set the SSL ID context associated with a session + +=head1 SYNOPSIS + + #include + + const unsigned char *SSL_SESSION_get0_id_context(const SSL_SESSION *s, + unsigned int *len) + int SSL_SESSION_set1_id_context(SSL_SESSION *s, const unsigned char *sid_ctx, + unsigned int sid_ctx_len); + +=head1 DESCRIPTION + +See L for further details on session ID +contexts. + +SSL_SESSION_get0_id_context() returns the ID context associated with +the SSL/TLS session B. The length of the ID context is written to +B<*len> if B is not NULL. + +The value returned is a pointer to an object maintained within B and +should not be released. + +SSL_SESSION_set1_id_context() takes a copy of the provided ID context given in +B and associates it with the session B. The length of the ID context +is given by B which must not exceed SSL_MAX_SID_CTX_LENGTH bytes. + +=head1 RETURN VALUES + +SSL_SESSION_set1_id_context() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L, +L + +=head1 HISTORY + +SSL_SESSION_get0_id_context() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod new file mode 100644 index 0000000..a95f8a5 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get0_peer.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_peer +- get details about peer's certificate for a session + +=head1 SYNOPSIS + + #include + + X509 *SSL_SESSION_get0_peer(SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get0_peer() returns the peer certificate associated with the session +B or NULL if no peer certificate is available. The caller should not free the +returned value (unless L has also been called). + +=head1 RETURN VALUES + +SSL_SESSION_get0_peer() returns a pointer to the peer certificate or NULL if +no peer certificate is available. + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod new file mode 100644 index 0000000..5045c53 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_compress_id.pod @@ -0,0 +1,39 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_compress_id +- get details about the compression associated with a session + +=head1 SYNOPSIS + + #include + + unsigned int SSL_SESSION_get_compress_id(const SSL_SESSION *s); + +=head1 DESCRIPTION + +If compression has been negotiated for an ssl session then +SSL_SESSION_get_compress_id() will return the id for the compression method or +0 otherwise. The only built-in supported compression method is zlib which has an +id of 1. + +=head1 RETURN VALUES + +SSL_SESSION_get_compress_id() returns the id of the compression method or 0 if +none. + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod new file mode 100644 index 0000000..e922abc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_ex_data.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_set_ex_data, +SSL_SESSION_get_ex_data +- get and set application specific data on a session + +=head1 SYNOPSIS + + #include + + int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data); + void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx); + +=head1 DESCRIPTION + +SSL_SESSION_set_ex_data() enables an application to store arbitrary application +specific data B in an SSL_SESSION structure B. The index B should +be a value previously returned from a call to L. + +SSL_SESSION_get_ex_data() retrieves application specific data previously stored +in an SSL_SESSION structure B. The B value should be the same as that +used when originally storing the data. + +=head1 RETURN VALUES + +SSL_SESSION_set_ex_data() returns 1 for success or 0 for failure. + +SSL_SESSION_get_ex_data() returns the previously stored value or NULL on +failure. NULL may also be a valid value. + +=head1 SEE ALSO + +L, +L + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod new file mode 100644 index 0000000..a033fdd --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_protocol_version.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_protocol_version - retrieve session protocol version + +=head1 SYNOPSIS + + #include + + int SSL_SESSION_get_protocol_version(const SSL_SESSION *s); + +=head1 DESCRIPTION + +SSL_SESSION_get_protocol_version() returns the protocol version number used +by session B. + +=head1 RETURN VALUES + +SSL_SESSION_get_protocol_version() returns a number indicating the protocol +version used for the session; this number matches the constants I +B or B. + +Note that the SSL_SESSION_get_protocol_version() function +does B perform a null check on the provided session B pointer. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +SSL_SESSION_get_protocol_version() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod new file mode 100644 index 0000000..e98d128 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_get_time.pod @@ -0,0 +1,76 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout, +SSL_SESSION_set_timeout, +SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod new file mode 100644 index 0000000..a84440b --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_has_ticket.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +SSL_SESSION_get0_ticket, +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint +- get details about the ticket associated with a session + +=head1 SYNOPSIS + + #include + + int SSL_SESSION_has_ticket(const SSL_SESSION *s); + unsigned long SSL_SESSION_get_ticket_lifetime_hint(const SSL_SESSION *s); + void SSL_SESSION_get0_ticket(const SSL_SESSION *s, const unsigned char **tick, + size_t *len); + +=head1 DESCRIPTION + +SSL_SESSION_has_ticket() returns 1 if there is a Session Ticket associated with +this session, and 0 otherwise. + +SSL_SESSION_get_ticket_lifetime_hint returns the lifetime hint in seconds +associated with the session ticket. + +SSL_SESSION_get0_ticket obtains a pointer to the ticket associated with a +session. The length of the ticket is written to B<*len>. If B is non +NULL then a pointer to the ticket is written to B<*tick>. The pointer is only +valid while the connection is in use. The session (and hence the ticket pointer) +may also become invalid as a result of a call to SSL_CTX_flush_sessions(). + +=head1 SEE ALSO + +L, +L, +L, +L + +=head1 HISTORY + +SSL_SESSION_has_ticket, SSL_SESSION_get_ticket_lifetime_hint and +SSL_SESSION_get0_ticket were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod new file mode 100644 index 0000000..9a44c11 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_print.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + +SSL_SESSION_print, +SSL_SESSION_print_fp, +SSL_SESSION_print_keylog +- printf information about a session + +=head1 SYNOPSIS + + #include + + int SSL_SESSION_print(BIO *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_fp(FILE *fp, const SSL_SESSION *ses); + int SSL_SESSION_print_keylog(BIO *bp, const SSL_SESSION *x); + +=head1 DESCRIPTION + +SSL_SESSION_print() prints summary information about the session provided in +B to the BIO B. + +SSL_SESSION_print_fp() does the same as SSL_SESSION_print() except it prints it +to the FILE B. + +SSL_SESSION_print_keylog() prints session information to the provided BIO +in NSS keylog format. + +=head1 RETURN VALUES + +SSL_SESSION_print(), SSL_SESSION_print_fp() and SSL_SESSION_print_keylog return +1 on success or 0 on error. + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod b/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod new file mode 100644 index 0000000..0bd9b83 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_SESSION_set1_id.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +SSL_SESSION_get_id, +SSL_SESSION_set1_id +- get and set the SSL session ID + +=head1 SYNOPSIS + + #include + + const unsigned char *SSL_SESSION_get_id(const SSL_SESSION *s, + unsigned int *len) + int SSL_SESSION_set1_id(SSL_SESSION *s, const unsigned char *sid, + unsigned int sid_len); + +=head1 DESCRIPTION + +SSL_SESSION_get_id() returns a pointer to the internal session id value for the +session B. The length of the id in bytes is stored in B<*len>. The length may +be 0. The caller should not free the returned pointer directly. + +SSL_SESSION_set1_id() sets the the session ID for the B SSL/TLS session +to B of length B. + +=head1 RETURN VALUES + +SSL_SESSION_get_id() returns a pointer to the session id value. +SSL_SESSION_set1_id() returns 1 for success and 0 for failure, for example +if the supplied session ID length exceeds B. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +SSL_SESSION_set1_id() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_accept.pod b/openssl-1.1.0h/doc/ssl/SSL_accept.pod new file mode 100644 index 0000000..3248cac --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_accept.pod @@ -0,0 +1,82 @@ +=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. + +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 Z<>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 Z<>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 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod b/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod new file mode 100644 index 0000000..6e2768e --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_alert_type_string.pod @@ -0,0 +1,242 @@ +=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 + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod b/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod new file mode 100644 index 0000000..8691994 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_check_chain.pod @@ -0,0 +1,94 @@ +=pod + +=head1 NAME + +SSL_check_chain - check certificate chain suitability + +=head1 SYNOPSIS + + #include + + int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain); + +=head1 DESCRIPTION + +SSL_check_chain() checks whether certificate B, private key B and +certificate chain B is suitable for use with the current session +B. + +=head1 RETURN VALUES + +SSL_check_chain() returns a bitmap of flags indicating the validity of the +chain. + +B: the chain can be used with the current session. +If this flag is B set then the certificate will never be used even +if the application tries to set it because it is inconsistent with the +peer preferences. + +B: the EE key can be used for signing. + +B: the signature algorithm of the EE certificate is +acceptable. + +B: the signature algorithms of all CA certificates +are acceptable. + +B: the parameters of the end entity certificate are +acceptable (e.g. it is a supported curve). + +B: the parameters of all CA certificates are acceptable. + +B: the end entity certificate algorithm +can be used explicitly for signing (i.e. it is mentioned in the signature +algorithms extension). + +B: the issuer name is acceptable. This is only +meaningful for client authentication. + +B: the certificate type is acceptable. Only meaningful +for client authentication. + +B: chain is suitable for Suite B use. + +=head1 NOTES + +SSL_check_chain() must be called in servers after a client hello message or in +clients after a certificate request message. It will typically be called +in the certificate callback. + +An application wishing to support multiple certificate chains may call this +function on each chain in turn: starting with the one it considers the +most secure. It could then use the chain of the first set which returns +suitable flags. + +As a minimum the flag B must be set for a chain to be +usable. An application supporting multiple chains with different CA signature +algorithms may also wish to check B too. If no +chain is suitable a server should fall back to the most secure chain which +sets B. + +The validity of a chain is determined by checking if it matches a supported +signature algorithm, supported curves and in the case of client authentication +certificate types and issuer names. + +Since the supported signature algorithms extension is only used in TLS 1.2 +and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be +very useful. Applications may wish to specify a different "legacy" chain +for earlier versions of TLS or DTLS. + +=head1 SEE ALSO + +L, +L + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_clear.pod b/openssl-1.1.0h/doc/ssl/SSL_clear.pod new file mode 100644 index 0000000..ed0ad60 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_clear.pod @@ -0,0 +1,84 @@ +=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 TLS_*_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 Z<>0 + +The SSL_clear() operation could not be performed. Check the error stack to +find out the reason. + +=item Z<>1 + +The SSL_clear() operation was successful. + +=back + +L, L, +L, L, +L, L, +L + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_connect.pod b/openssl-1.1.0h/doc/ssl/SSL_connect.pod new file mode 100644 index 0000000..df198f9 --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_connect.pod @@ -0,0 +1,82 @@ +=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 Z<>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 Z<>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 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod b/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod new file mode 100644 index 0000000..ffb71cc --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_do_handshake.pod @@ -0,0 +1,81 @@ +=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. + +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 Z<>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 Z<>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 + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod b/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod new file mode 100644 index 0000000..ccb99ec --- /dev/null +++ b/openssl-1.1.0h/doc/ssl/SSL_export_keying_material.pod @@ -0,0 +1,61 @@ +=pod + +=head1 NAME + +SSL_export_keying_material - obtain keying material for application use + +=head1 SYNOPSIS + + #include + + int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen, + const char *label, size_t llen, + const unsigned char *context, + size_t contextlen, int use_context); + +=head1 DESCRIPTION + +During the creation of a TLS or DTLS connection shared keying material is +established between the two endpoints. The function SSL_export_keying_material() +enables an application to use some of this keying material for its own purposes +in accordance with RFC5705. + +An application may need to securely establish the context within which this +keying material will be used. For example this may include identifiers for the +application session, application algorithms or parameters, or the lifetime of +the context. The context value is left to the application but must be the same +on both sides of the communication. + +For a given SSL connection B, B bytes of data will be written to +B. The application specific context should be supplied in the location +pointed to by B and should be B bytes long. Provision of +a context is optional. If the context should be omitted entirely then +B should be set to 0. Otherwise it should be any other value. If +B is 0 then the values of B and B are ignored. +Note that a zero length context is treated differently to no context at all, and +will result in different keying material being returned. + +An application specific label should be provided in the location pointed to by +B