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 <matt@openssl.org>
(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 5db981bc6fce6d554e4bc3f104a1fa3c4e14028e..efcd25a5383db605448a659ef2c1398b6bba8664 100644 (file)
--- 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<arg> value is pointer which is passed to the application callback.
+SSL_CTX_set_cert_cb() and SSL_set_cert_cb() sets the I<cert_cb> callback,
+I<arg> value is pointer which is passed to the application callback.
 
-When cert_cb() is NULL, no callback function is used.
+When I<cert_cb> is NULL, no callback function is used.
 
-cert_cb() is the application defined callback. It is called before a
+I<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<ssl> structure and set or clear any appropriate certificates. If
+the passed I<ssl> structure and set or clear any appropriate certificates. If
 the callback is successful it B<MUST> 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<SSL_get_error(3)> 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<cert_cb>. It is the job of the
+I<cert_cb> 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 719e831a3f3c571e2920457f0c78a2270deefa9e..977ad02155d5726819490410b99e91691c12d7f8 100644 (file)
--- 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<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.
+When I<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
+I<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<x509> and B<pkey> arguments and "1" must be returned. The
-certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
+using the I<x509> and I<pkey> arguments and "1" must be returned. The
+certificate will be installed into I<ssl>, 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<SSL_get_error(3)>
 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<client_cert_cb>. It is the job of the I<client_cert_cb> 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<client_cert_cb> or
 NULL if the callback is not set.
 
 =head1 BUGS
 
-The client_cert_cb() cannot return a complete certificate chain, it can
+The I<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