From: Richard Levitte Date: Mon, 20 Jul 2020 15:14:45 +0000 (+0200) Subject: DOC: Fix SSL_CTX_set_cert_cb.pod and SSL_CTX_set_client_cert_cb.pod X-Git-Tag: openssl-3.0.0-alpha6~89 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5ac582d949c4f0dbf919c99d59496035a1f7e982;p=thirdparty%2Fopenssl.git DOC: Fix SSL_CTX_set_cert_cb.pod and SSL_CTX_set_client_cert_cb.pod The 'cert_cb' / 'client_cert_cb' arguments had extra, a bit weird documentation. Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/12494) --- diff --git a/doc/man3/SSL_CTX_set_cert_cb.pod b/doc/man3/SSL_CTX_set_cert_cb.pod index 5db981bc6fc..efcd25a5383 100644 --- a/doc/man3/SSL_CTX_set_cert_cb.pod +++ b/doc/man3/SSL_CTX_set_cert_cb.pod @@ -12,26 +12,24 @@ SSL_CTX_set_cert_cb, SSL_set_cert_cb - handle certificate callback function 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. +SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the I callback, +I value is pointer which is passed to the application callback. -When cert_cb() is NULL, no callback function is used. +When I is NULL, no callback function is used. -cert_cb() is the application defined callback. It is called before a +I 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 passed I 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, +function will again lead to the call of I. It is the job of the +I to store information about the state of the last call, if required to continue. =head1 NOTES diff --git a/doc/man3/SSL_CTX_set_client_cert_cb.pod b/doc/man3/SSL_CTX_set_client_cert_cb.pod index 719e831a3f3..977ad02155d 100644 --- a/doc/man3/SSL_CTX_set_client_cert_cb.pod +++ b/doc/man3/SSL_CTX_set_client_cert_cb.pod @@ -13,29 +13,28 @@ SSL_CTX_set_client_cert_cb, SSL_CTX_get_client_cert_cb - handle client certifica 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 +SSL_CTX_set_client_cert_cb() sets the I 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. +When I 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 +I 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. +using the I and I arguments and "1" must be returned. The +certificate will be installed into I, 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 +of I. It is the job of the I to store information about the state of the last call, if required to continue. =head1 NOTES @@ -65,12 +64,12 @@ a certificate. =head1 RETURN VALUES -SSL_CTX_get_client_cert_cb() returns function pointer of client_cert_cb() or +SSL_CTX_get_client_cert_cb() returns function pointer of I or NULL if the callback is not set. =head1 BUGS -The client_cert_cb() cannot return a complete certificate chain, it can +The I 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