[openssl] master update
Richard Levitte
levitte at openssl.org
Tue Jul 21 16:53:14 UTC 2020
The branch master has been updated
via 5ac582d949c4f0dbf919c99d59496035a1f7e982 (commit)
via 8eca461731feb25b94ccf181e76ec2723e27769a (commit)
from 904f42509f8d5e6210113e49a7e41ed2b1dd5a81 (commit)
- Log -----------------------------------------------------------------
commit 5ac582d949c4f0dbf919c99d59496035a1f7e982
Author: Richard Levitte <levitte at openssl.org>
Date: Mon Jul 20 17:14:45 2020 +0200
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 at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12494)
commit 8eca461731feb25b94ccf181e76ec2723e27769a
Author: Richard Levitte <levitte at openssl.org>
Date: Mon Jul 20 17:10:44 2020 +0200
util/find-doc-nits: Relax check of function declarations in name_synopsis()
The relaxation allows spaces between function name and argument list,
to allow line breaks like this when there are very long names:
int (fantastically_long_name_breaks_80char_limit)
(fantastically_long_name_breaks_80char_limit *something);
This revealed some other intricaties, such as documented internal
structures with function pointers inside, so a check of open
structures was also added, and they are now simply skipped over.
Reviewed-by: Matt Caswell <matt at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12494)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/SSL_CTX_set_cert_cb.pod | 16 +++++++---------
doc/man3/SSL_CTX_set_client_cert_cb.pod | 17 ++++++++---------
util/find-doc-nits | 25 +++++++++++++++++++++++--
3 files changed, 38 insertions(+), 20 deletions(-)
diff --git a/doc/man3/SSL_CTX_set_cert_cb.pod b/doc/man3/SSL_CTX_set_cert_cb.pod
index 5db981bc6f..efcd25a538 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<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 719e831a3f..977ad02155 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<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
diff --git a/util/find-doc-nits b/util/find-doc-nits
index c82e647bf5..3558180603 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -311,6 +311,7 @@ sub name_synopsis {
# Find all functions in SYNOPSIS
return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
my $syn = $1;
+ my $ignore_until = undef; # If defined, this is a regexp
# Remove all non-code lines
$syn =~ s/^(?:\s*?|\S.*?)$//msg;
# Remove all comments
@@ -327,6 +328,19 @@ sub name_synopsis {
my $line = $1;
$syn = $';
+ print STDERR "DEBUG[name_synopsis] \$line = '$line'\n" if $debug;
+
+ # Special code to skip over documented structures
+ if ( defined $ignore_until) {
+ next if $line !~ /$ignore_until/;
+ $ignore_until = undef;
+ next;
+ }
+ if ( $line =~ /^\s*(?:typedef\s+)?struct(?:\s+\S+)\s*\{/ ) {
+ $ignore_until = qr/\}.*?;/;
+ next;
+ }
+
my $sym;
my $is_prototype = 1;
$line =~ s/STACK_OF\([^)]+\)/int/g;
@@ -353,7 +367,7 @@ sub name_synopsis {
# a callback function pointer: typedef ... (*NAME)(...
# a callback function signature: typedef ... (NAME)(...
$sym = $1;
- } elsif ( $line =~ /typedef.* (\S+)\(/ ) {
+ } elsif ( $line =~ /typedef.* (\S+)\s*\(/ ) {
# a callback function signature: typedef ... NAME(...
$sym = $1;
} elsif ( $line =~ /typedef.* (\S+);/ ) {
@@ -366,12 +380,19 @@ sub name_synopsis {
} elsif ( $line =~ /#\s*(?:define|undef) ([A-Za-z0-9_]+)/ ) {
$is_prototype = 0;
$sym = $1;
- } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) {
+ } elsif ( $line =~ /^[^\(]*?\(\*([A-Za-z0-9_]+)\s*\(/ ) {
+ # a function returning a function pointer: TYPE (*NAME(args))(args)
+ $sym = $1;
+ } elsif ( $line =~ /^[^\(]*?([A-Za-z0-9_]+)\s*\(/ ) {
+ # a simple function declaration
$sym = $1;
}
else {
next;
}
+
+ print STDERR "DEBUG[name_synopsis] \$sym = '$sym'\n" if $debug;
+
err($id, "$sym missing from NAME section")
unless defined $names{$sym};
$names{$sym} = 2;
More information about the openssl-commits
mailing list