diff options
author | jkim <jkim@FreeBSD.org> | 2016-01-28 18:41:59 +0000 |
---|---|---|
committer | jkim <jkim@FreeBSD.org> | 2016-01-28 18:41:59 +0000 |
commit | 71cece53f20ad0348c8e6a83b032a4bcfa42cdcf (patch) | |
tree | 7af4d87a03d869e528631ede778e4423dd6a281a /doc/ssl | |
parent | afd52a5fc90e70242dbb0e7d29987c976eb993e0 (diff) | |
download | FreeBSD-src-71cece53f20ad0348c8e6a83b032a4bcfa42cdcf.zip FreeBSD-src-71cece53f20ad0348c8e6a83b032a4bcfa42cdcf.tar.gz |
Import OpenSSL 1.0.2f.
Diffstat (limited to 'doc/ssl')
-rw-r--r-- | doc/ssl/SSL_CTX_set1_verify_cert_store.pod | 8 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_tlsext_status_cb.pod | 73 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 29 |
3 files changed, 82 insertions, 28 deletions
diff --git a/doc/ssl/SSL_CTX_set1_verify_cert_store.pod b/doc/ssl/SSL_CTX_set1_verify_cert_store.pod index 493cca4..3e3a4fa 100644 --- a/doc/ssl/SSL_CTX_set1_verify_cert_store.pod +++ b/doc/ssl/SSL_CTX_set1_verify_cert_store.pod @@ -17,10 +17,10 @@ verification or chain store 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 *ctx, X509_STORE *st); - int SSL_set1_verify_cert_store(SSL_CTX *ctx, X509_STORE *st); - int SSL_set0_chain_cert_store(SSL_CTX *ctx, X509_STORE *st); - int SSL_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 diff --git a/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod b/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod new file mode 100644 index 0000000..b8147ba --- /dev/null +++ b/doc/ssl/SSL_CTX_set_tlsext_status_cb.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_status_cb, SSL_CTX_set_tlsext_status_arg, +SSL_set_tlsext_status_type, SSL_get_tlsext_status_ocsp_resp, +SSL_set_tlsext_status_ocsp_resp - OCSP Certificate Status Request functions + +=head1 SYNOPSIS + + #include <openssl/tls1.h> + + long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, + int (*callback)(SSL *, void *)); + long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg); + + long SSL_set_tlsext_status_type(SSL *s, int type); + + 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_set_tlsext_status_type() function prior to the start of the handshake. +Currently the only supported type is B<TLSEXT_STATUSTYPE_ocsp>. This value +should be passed in the B<type> argument. 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 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<resp> argument, and the length of that data should be in +the B<len> 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_set_tlsext_status_type() and SSL_set_tlsext_status_ocsp_resp() return 0 on +error or 1 on success. + +SSL_get_tlsext_status_ocsp_resp() returns the length of the OCSP response data +or -1 if there is no OCSP response data. + +=cut diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod index b754c16..234fbc8 100644 --- a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod +++ b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -48,25 +48,8 @@ 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 -if either the DH parameters are supplied via callback or the -SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set (or both). -It will immediately create a DH key if DH parameters are supplied via -SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. -In this case, -it may happen that a key is generated on initialization without later -being needed, while on the other hand the computer time during the -negotiation is being saved. - -If "strong" primes were used to generate the DH parameters, it is not strictly -necessary to generate a new key for each handshake but it does improve forward -secrecy. If it is not assured that "strong" primes were used, -SSL_OP_SINGLE_DH_USE must be used in order to prevent small subgroup -attacks. Always using SSL_OP_SINGLE_DH_USE has an impact on the -computer time needed during negotiation, but it is not very large, so -application authors/users should consider always enabling this option. -The option is required to implement perfect forward secrecy (PFS). +(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. @@ -93,10 +76,9 @@ can supply the DH parameters via a callback function. Previous versions of the callback used B<is_export> and B<keylength> 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() in combination with -SSL_OP_SINGLE_DH_USE, or alternatively, use the callback but ignore -B<keylength> and B<is_export> and simply supply at least 2048-bit -parameters in the callback. +are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use +the callback but ignore B<keylength> and B<is_export> and simply +supply at least 2048-bit parameters in the callback. =head1 EXAMPLES @@ -128,7 +110,6 @@ partly left out.) if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { /* Error. */ } - SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE); ... =head1 RETURN VALUES |