The branch master has been updated
via 2b93900e28b330e6066a993278fabd4d560936f9 (commit)
via e19c5a106428f5f805c9c54c60d2ead216277bcf (commit)
via 01fe51578e678da935571965e8d438125392c381 (commit)
via b06e70b868cb8067746e35ea90b714e2f8db7141 (commit)
from bf57cab74b6d64f9d5bb3de8a6c77601ce208b74 (commit)
- Log -----------------------------------------------------------------
commit 2b93900e28b330e6066a993278fabd4d560936f9
Author: Richard Levitte <levi...@openssl.org>
Date: Sat Nov 14 11:58:17 2020 +0100
DOC: Rewrite the section on reporting errors in doc/man3/ERR_put_error.pod
Reviewed-by: Paul Dale <paul.d...@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13320)
commit e19c5a106428f5f805c9c54c60d2ead216277bcf
Author: Richard Levitte <levi...@openssl.org>
Date: Sat Nov 14 11:58:03 2020 +0100
CONF: Convert one last CONFerr() to ERR_raise()
Reviewed-by: Paul Dale <paul.d...@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13320)
commit 01fe51578e678da935571965e8d438125392c381
Author: Richard Levitte <levi...@openssl.org>
Date: Wed Nov 4 12:16:35 2020 +0100
Simplify util/err-to-raise
There's no need to enumerate the possible {NAME}err, as they have a
consistent pattern. Also, this script should not be used on the
engines, as they have already converted appropriately.
Reviewed-by: Paul Dale <paul.d...@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13320)
commit b06e70b868cb8067746e35ea90b714e2f8db7141
Author: Richard Levitte <levi...@openssl.org>
Date: Wed Nov 4 16:28:09 2020 +0100
Really deprecate the old NAMEerr() macros
Reviewed-by: Paul Dale <paul.d...@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13320)
-----------------------------------------------------------------------
Summary of changes:
crypto/conf/conf_def.c | 2 +-
doc/man3/ERR_put_error.pod | 105 ++++++++++++++++++++++++++++++++++++---------
include/openssl/err.h.in | 2 +-
util/err-to-raise | 49 ++-------------------
4 files changed, 91 insertions(+), 67 deletions(-)
diff --git a/crypto/conf/conf_def.c b/crypto/conf/conf_def.c
index 2637e17fd8..3f63a5f88d 100644
--- a/crypto/conf/conf_def.c
+++ b/crypto/conf/conf_def.c
@@ -417,7 +417,7 @@ static int def_load_bio(CONF *conf, BIO *in, long *line)
include_path = OPENSSL_malloc(newlen);
if (include_path == NULL) {
- CONFerr(CONF_F_DEF_LOAD_BIO, ERR_R_MALLOC_FAILURE);
+ ERR_raise(ERR_LIB_CONF, ERR_R_MALLOC_FAILURE);
OPENSSL_free(include);
goto err;
}
diff --git a/doc/man3/ERR_put_error.pod b/doc/man3/ERR_put_error.pod
index c6b42028cc..a4e0cd6bec 100644
--- a/doc/man3/ERR_put_error.pod
+++ b/doc/man3/ERR_put_error.pod
@@ -1,5 +1,7 @@
=pod
+=for openssl foreign manual errno(3)
+
=head1 NAME
ERR_raise, ERR_raise_data,
@@ -65,50 +67,113 @@ error messages for the error code.
=head2 Reporting errors
-=for comment TODO(3.0) should this be internal documentation?
+=head3 OpenSSL library reports
+
+Each OpenSSL sub-library has library code B<ERR_LIB_XXX> and has its own set
+of reason codes B<XXX_R_...>. These are both passed in combination to
+ERR_raise() and ERR_raise_data(), and the combination ultimately produces
+the correct error text for the reported error.
-Each sub-library has a specific macro XXXerr() that is used to report
-errors. Its first argument is a function code B<XXX_F_...>, the second
-argument is a reason code B<XXX_R_...>. Function codes are derived
-from the function names; reason codes consist of textual error
+All these macros and the numbers they have as values are specific to
+OpenSSL's libraries. OpenSSL reason codes normally consist of textual error
descriptions. For example, the function ssl3_read_bytes() reports a
"handshake failure" as follows:
- SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
+ ERR_raise(ERR_LIB_SSL, SSL_R_SSL_HANDSHAKE_FAILURE);
+
+There are two exceptions:
+
+=over 4
+
+=item B<ERR_LIB_SYS>
+
+This "library code" indicates that a system error is being reported. In
+this case, the reason code given to ERR_raise() and ERR_raise_data() I<must>
+be L<errno(3)>.
+
+ ERR_raise(ERR_LIB_SYS, errno);
+
+=item B<ERR_R_XXX>
+
+This set of error codes is considered global, and may be used in combination
+with any sub-library code.
+
+ ERR_raise(ERR_LIB_RSA, ERR_R_PASSED_INVALID_ARGUMENT);
+
+=back
+
+=head3 Other pieces of software
+
+Other pieces of software that may want to use OpenSSL's error reporting
+system, such as engines or applications, must normally get their own
+numbers.
+
+=over 4
+
+=item *
+
+To get a "library" code, call L<ERR_get_next_error_library(3)>; this gives
+the calling code a dynamic number, usable for the duration of the process.
+
+=item *
+
+Reason codes for each such "library" are determined or generated by the
+authors of that code. They must be numbers in the range 1 to 524287 (in
+other words, they must be nonzero unsigned 18 bit integers).
+
+=back
+
+The exceptions mentioned in L</OpenSSL library reports> above are valid for
+other pieces of software, i.e. they may use B<ERR_LIB_SYS> to report system
+errors:
+
+ ERR_raise(ERR_LIB_SYS, errno);
+
+... and they may use B<ERR_R_XXX> macros together with their own "library"
+code.
+
+ int app_lib_code = ERR_get_next_error_library();
+
+ /* ... */
+
+ ERR_raise(app_lib_code, ERR_R_PASSED_INVALID_ARGUMENT);
+
+=begin comment
-Function and reason codes should consist of uppercase characters,
-numbers and underscores only. The error file generation script translates
-function codes into function names by looking in the header files
-for an appropriate function name, if none is found it just uses
-the capitalized form such as "SSL3_READ_BYTES" in the above example.
+[These are OpenSSL specific recommendations]
-The trailing section of a reason code (after the "_R_") is translated
-into lowercase and underscores changed to spaces.
+Reason codes should consist of uppercase characters, numbers and underscores
+only. The error file generation script translates the trailing section of a
+reason code (after the "_R_") into lowercase with underscores changed to
+spaces.
Although a library will normally report errors using its own specific
-XXXerr macro, another library's macro can be used. This is normally
-only done when a library wants to include ASN1 code which must use
-the ASN1err() macro.
+B<ERR_LIB_XXX> macro, another library's macro can be used, together with
+that other library's reason codes. This is normally only done when a library
+wants to include ASN1 code which must be combined with B<ERR_LIB_ASN1>
+macro.
+=end comment
=head1 RETURN VALUES
-ERR_raise(), ERR_put_error(),
+ERR_raise(), ERR_raise_data(), ERR_put_error(),
ERR_add_error_data(), ERR_add_error_vdata()
ERR_add_error_txt(), and ERR_add_error_mem_bio()
return no values.
=head1 NOTES
-ERR_raise() and ERR_put_error() are implemented as macros.
+ERR_raise(), ERR_raise() and ERR_put_error() are implemented as macros.
=head1 SEE ALSO
-L<ERR_load_strings(3)>
+L<ERR_load_strings(3)>, L<ERR_get_next_error_library(3)>
=head1 HISTORY
-B<ERR_add_error_txt> and B<ERR_add_error_mem_bio> were added in OpenSSL 3.0.
+ERR_raise, ERR_raise_data, ERR_add_error_txt() and ERR_add_error_mem_bio()
+were added in OpenSSL 3.0.
=head1 COPYRIGHT
diff --git a/include/openssl/err.h.in b/include/openssl/err.h.in
index 0e6f4fbad2..35db02fad6 100644
--- a/include/openssl/err.h.in
+++ b/include/openssl/err.h.in
@@ -123,7 +123,7 @@ struct err_state_st {
# define ERR_LIB_USER 128
-# if 1 || !defined(OPENSSL_NO_DEPRECATED_3_0)
+# ifndef OPENSSL_NO_DEPRECATED_3_0
# define ASN1err(f, r) ERR_raise_data(ERR_LIB_ASN1, (r), NULL)
# define ASYNCerr(f, r) ERR_raise_data(ERR_LIB_ASYNC, (r), NULL)
# define BIOerr(f, r) ERR_raise_data(ERR_LIB_BIO, (r), NULL)
diff --git a/util/err-to-raise b/util/err-to-raise
index 649ca6bf93..174686d3ab 100755
--- a/util/err-to-raise
+++ b/util/err-to-raise
@@ -7,57 +7,16 @@
# https://www.openssl.org/source/license.html
# Run this program like this:
-# perl -pi util/err-to-error files...
+# perl -pi util/err-to-raise files...
# or
# git ls-files | grep '\.c$' | xargs perl -pi util/err-to-raise
# Consider running util/merge-err-lines first, to catch most (all?) of the
# cases where the XXXerr() call is split into two lines.
-# Also, what to do about the engines files? This includes:
-# AFALGerr, CAPIerr, DASYNC, OSSLTEST
-# There are about 70 such lines.
+# Do not use this in engines/, they have their own error reporting functions,
+# which do call ERR_raise().
use strict;
use warnings;
-s/ASN1err\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_ASN1, $1)/;
-s/([^D])ASYNCerr\(\w+, *(\w+)\)/$1ERR_raise(ERR_LIB_ASYNC, $2)/;
-s/BIOerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_BIO, $1)/;
-s/BNerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_BN, $1)/;
-s/BUFerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_BUF, $1)/;
-s/CMPerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_CMP, $1)/;
-s/CMSerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_CMS, $1)/;
-s/COMPerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_COMP, $1)/;
-s/CONFerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_CONF, $1)/;
-s/CRMFerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_CRMF, $1)/;
-s/CRYPTOerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_CRYPTO, $1)/;
-s/CTerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_CT, $1)/;
-s/DHerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_DH, $1)/;
-s/DSAerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_DSA, $1)/;
-s/DSOerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_DSO, $1)/;
-s/ECDHerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_ECDH, $1)/;
-s/ECDSAerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_ECDSA, $1)/;
-s/ECerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_EC, $1)/;
-s/ENGINEerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_ENGINE, $1)/;
-s/ESSerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_ESS, $1)/;
-s/EVPerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_EVP, $1)/;
-s/FIPSerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_FIPS, $1)/;
-s/HTTPerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_HTTP, $1)/;
-s/KDFerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_KDF, $1)/;
-s/OBJerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_OBJ, $1)/;
-s/OCSPerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_OCSP, $1)/;
-s/OSSL_STOREerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_OSSL_STORE, $1)/;
-s/PEMerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_PEM, $1)/;
-s/PKCS12err\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_PKCS12, $1)/;
-s/PKCS7err\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_PKCS7, $1)/;
-s/PROPerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_PROP, $1)/;
-s/PROVerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_PROV, $1)/;
-s/RANDerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_RAND, $1)/;
-s/RSAerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_RSA, $1)/;
-s/SM2err\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_SM2, $1)/;
-s/SSLerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_SSL, $1)/;
-s/SYSerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_SYS, $1)/;
-s/TSerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_TS, $1)/;
-s/UIerr\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_UI, $1)/;
-s/X509V3err\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_X509V3, $1)/;
-s/X509err\(\w+, *(\w+)\)/ERR_raise(ERR_LIB_X509, $1)/;
+s/\b([_A-Z0-9]+)err\(\s*\w+\s*,/ERR_raise(ERR_LIB_$1,/;
