[openssl] master update
Richard Levitte
levitte at openssl.org
Sun Nov 1 04:58:40 UTC 2020
The branch master has been updated
via 3b1bfd2160a165a9a1fccc20ab0410e35c435f65 (commit)
via d14e7df8529a3e8fcc2c107369ebcc5abbcccd11 (commit)
from 908cf7cefbb2a4c2a8ea1dd4798d1e689db6e3ed (commit)
- Log -----------------------------------------------------------------
commit 3b1bfd2160a165a9a1fccc20ab0410e35c435f65
Author: Richard Levitte <levitte at openssl.org>
Date: Mon Oct 26 18:38:35 2020 +0100
util/find-doc-nits: ignore OSSL_DEPRECATED*, alongside other reserved symbols
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13240)
commit d14e7df8529a3e8fcc2c107369ebcc5abbcccd11
Author: Richard Levitte <levitte at openssl.org>
Date: Sun Oct 25 12:20:13 2020 +0100
Simplify and clarify doc/internal/man7/deprecation.pod
doc/internal/man7/deprecation.pod was unclear in some areas, and
included general documentation that has no place there.
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13240)
-----------------------------------------------------------------------
Summary of changes:
doc/internal/man3/OSSL_DEPRECATED.pod | 54 +++++++++
doc/internal/man7/deprecation.pod | 211 ++++++++++------------------------
util/find-doc-nits | 3 +-
util/missingmacro.txt | 11 --
4 files changed, 119 insertions(+), 160 deletions(-)
create mode 100644 doc/internal/man3/OSSL_DEPRECATED.pod
diff --git a/doc/internal/man3/OSSL_DEPRECATED.pod b/doc/internal/man3/OSSL_DEPRECATED.pod
new file mode 100644
index 0000000000..8370d60f18
--- /dev/null
+++ b/doc/internal/man3/OSSL_DEPRECATED.pod
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+OSSL_DEPRECATED, OSSL_DEPRECATED_FOR - General deprecation macros
+
+=head1 SYNOPSIS
+
+ #include <openssl/macros.h>
+
+ #define OSSL_DEPRECATED(since)
+ #define OSSL_DEPRECATED_FOR(since, msg)
+
+=head1 DESCRIPTION
+
+OSSL_DEPRECATED() implements the deprecated attribute if the compiler
+supports it, otherwise it expands to nothing. It takes one argument
+I<since> that should be set to the OpenSSL version where the symbol was
+deprecated, and will be displayed with the deprecation warning message,
+for compilers that support user specified deprecation messages.
+
+OSSL_DEPRECATED_FOR() does the same as OSSL_DEPRECATED(), but also takes a
+second argument I<msg>, which is an additional text messages to be displayed
+with the deprecation warning along with the OpenSSL version number, for
+compilers that support user specified deprecation messages.
+
+These macros are used to define the version specific deprecation macros
+described in L<deprecation(7)>.
+
+=begin comment
+
+[RETURN VALUES isn't relevant for these macros, but find-doc-nits demands
+the presence of this section]
+
+=head1 RETURN VALUES
+
+[podchecker doesn't like empty sections]
+
+=end comment
+
+=head1 SEE ALSO
+
+L<deprecation(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/internal/man7/deprecation.pod b/doc/internal/man7/deprecation.pod
index e55da1ffe4..15e1c7aef1 100644
--- a/doc/internal/man7/deprecation.pod
+++ b/doc/internal/man7/deprecation.pod
@@ -2,185 +2,98 @@
=head1 NAME
-deprecation - Macros used for deprecating symbols and simulate removal
-
-=head1 SYNOPSIS
-
- #include <openssl/macros.h>
-
- OSSL_DEPRECATED(since)
- OSSL_DEPRECATED_FOR(since, msg)
-
- OPENSSL_NO_DEPRECATED_3_0
- OSSL_DEPRECATEDIN_3_0
- OSSL_DEPRECATEDIN_3_0_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_1_1
- OSSL_DEPRECATEDIN_1_1_1
- OSSL_DEPRECATEDIN_1_1_1_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_1_0
- OSSL_DEPRECATEDIN_1_1_0
- OSSL_DEPRECATEDIN_1_1_0_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_0_2
- OSSL_DEPRECATEDIN_1_0_2
- OSSL_DEPRECATEDIN_1_0_2_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_0_1
- OSSL_DEPRECATEDIN_1_0_1
- OSSL_DEPRECATEDIN_1_0_1_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_0_0
- OSSL_DEPRECATEDIN_1_0_0
- OSSL_DEPRECATEDIN_1_0_0_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_0_9_8
- OSSL_DEPRECATEDIN_0_9_8
- OSSL_DEPRECATEDIN_0_9_8_FOR(msg)
+OPENSSL_NO_DEPRECATED_3_0, OSSL_DEPRECATEDIN_3_0,
+OPENSSL_NO_DEPRECATED_1_1_1, OSSL_DEPRECATEDIN_1_1_1,
+OPENSSL_NO_DEPRECATED_1_1_0, OSSL_DEPRECATEDIN_1_1_0,
+OPENSSL_NO_DEPRECATED_1_0_2, OSSL_DEPRECATEDIN_1_0_2,
+OPENSSL_NO_DEPRECATED_1_0_1, OSSL_DEPRECATEDIN_1_0_1,
+OPENSSL_NO_DEPRECATED_1_0_0, OSSL_DEPRECATEDIN_1_0_0,
+OPENSSL_NO_DEPRECATED_0_9_8, OSSL_DEPRECATEDIN_0_9_8,
+deprecation - How to do deprecation
=head1 DESCRIPTION
Deprecation of a symbol is adding an attribute to the declaration of that
symbol (function, type, variable, but we currently only do that for
-functions in our F<< <openssl/*.h> >> header files).
+functions in our public header files, F<< <openssl/*.h> >>).
Removal of a symbol is not the same thing as deprecation, as it actually
-removes the symbol from public view.
+explicitly removes the symbol from public view.
OpenSSL configuration supports deprecation as well as simulating removal of
-symbols from public view, and also supports doing this in terms of a
-specified OpenSSL version.
+symbols from public view (with the configuration option `no-deprecated`, or
+if the user chooses to do so, with L<OPENSSL_NO_DEPRECATED(7)>), and also
+supports doing this in terms of a specified OpenSSL version (with the
+configuration option `--api`, or if the user chooses to do so, with
+L<OPENSSL_API_COMPAT(7)>).
-Deprecation is done using attribute macros having names starting with
-B<OSSL_DEPRECATED>, used with any declaration it applies to.
+Deprecation is done using attribute macros named
+B<OSSL_DEPRECATEDIN_I<version>>, used with any declaration it applies to.
-Simulating removal is done with guard macros having names starting with
-L<OPENSSL_NO_DEPRECATED(7)>.
+Simulating removal is done with C<#ifndef> preprocessor guards using macros
+named B<OPENSSL_NO_DEPRECATED_I<version>>.
-The implementation of a deprecated symbol is kept for two reasons:
+B<OSSL_DEPRECATEDIN_I<version>> and B<OPENSSL_NO_DEPRECATED_I<version>> are
+defined in F<< <openssl/macros.h> >>.
-=over 4
-
-=item Kept as legacy for the deprecation period
-
-It's implemented only to have it available as long as the symbol isn't
-removed entirely (be it by explicitly removing it when it's judged that it
-has been deprecated long enough, or because the removal is simulated).
-These need to be guarded appropriately, as shown in the L</Implementations
-kept as legacy>.
-
-=item Kept for internal purposes
-
-The implementation doesn't need to change or be guarded. However, it's
-necessary to ensure that the declaration remains available for the
-translation unit where the implementation is located, even when the symbol
-is publicly unavailable through simulated removal. That's done by including
-an internal header file very early in the translation unit. See
-L</Implementations kept for internal purposes>.
+In those macro names, B<I<version>> corresponds to the OpenSSL release since
+which the deprecation applies, with underscores instead of periods. Because
+of the change in version scheme with OpenSSL 3.0, the B<I<version>> for
+versions before that are three numbers (such as C<1_1_0>), while they are
+two numbers (such as C<3_0>) from 3.0 and on.
-In a future cleanup, the declaration should be explicitly moved to an
-internal header file, with the deprecation attribute removed, and the
-translation unit should adjust its header inclusions accordingly.
+The implementation of a deprecated symbol is kept for one of two reasons:
-=back
-
-=head2 General macros
-
-I<Note: none of these macros should be used directly, please use the version
-specific macros instead>
-
-OSSL_DEPRECATED() implements the deprecated attribute if the compiler
-supports it, otherwise it expands to nothing. It takes one argument
-I<since> that should be set to the OpenSSL version where the symbol was
-deprecated, and will be displayed with the deprecation warning message,
-for compilers that support user specified deprecation messages.
+=over 4
-OSSL_DEPRECATED_FOR() does the same as OSSL_DEPRECATED(), but also takes a
-second argument I<msg>, which is an additional text messages to be displayed
-with the deprecation warning along with the OpenSSL version number, for
-compilers that support user specified deprecation messages.
+=item Planned to be removed
-B<OPENSSL_NO_DEPRECATED> is a macro that's generated by OpenSSL
-configuration in response to the C<no-deprecated> configuration option.
-This macro suppresses the definition of deprecated symbols.
+The symbol and its implementation are planned to be removed some time in the
+future, but needs to remain available until that time.
+Such an implementation needs to be guarded appropriately, as shown in
+L</Implementations to be removed> below.
-=head2 Version specific macros
+=item Planned to remain internally
-OSSL_DEPRECATEDIN_I<major>_I<minor>() macros that are defined to
-OSSL_DEPRECATED() with that version number as I<since>, for any version up
-to and including the one expressed with L<OPENSSL_API_COMPAT(7)>. For any
-known version above the version expressed with L<OPENSSL_API_COMPAT(7)>,
-The are defined to nothing.
+The symbol is planned to be removed from public view, but will otherwise
+remain for internal purposes. In this case, the implementation doesn't need
+to change or be guarded.
-OSSL_DEPRECATEDIN_I<major>_I<minor>_FOR() macros that are defined to
-OSSL_DEPRECATED() with that version number as I<since>, under the same
-conditions as OSSL_DEPRECATEDIN_I<major>_I<minor>().
+However, it's necessary to ensure that the declaration remains available for
+the translation unit where the symbol is used or implemented, even when the
+symbol is publicly unavailable through simulated removal. That's done by
+including an internal header file very early in the affected translation
+units. See L</Implementations to remain internally> below.
-B<OPENSSL_NO_DEPRECATED_I<major>_I<minor>> macros should be used as
-guards around declarations that will eventually disappear from the public
-header files (F<< <openssl/*.h> >>).
+In the future, when the deprecated declaration is to actually be removed
+from public view, it should be moved to an internal header file, with the
+deprecation attribute removed, and the translation units that implement or
+use that symbol should adjust their header inclusions accordingly.
-Any set of symbols deprecated with a B<OSSL_DEPRECATEDIN_I<major>_I<minor>>
-attribute macro B<must> be wrapped with a guard using the corresponding
-B<OPENSSL_NO_DEPRECATED_I<major>_I<minor>> macro, see L</Header files>
-example below. This not only affects what the user of the header file will
-have available, it's also used to determine the conditions for exporting the
-symbol in the shared libraries.
+=back
=head1 EXAMPLES
=head2 Header files
-In public header files (F<< <openssl/*.h> >>), a deprecated symbol will
-always be wrapped with a negative test of the guard:
+In public header files (F<< <openssl/*.h> >>), this is what a deprecation is
+expected to look like, including the preprocessor wrapping for simulated
+removal:
- # ifndef OPENSSL_NO_DEPRECATED_1_1_0
- /* ... */
- OSSL_DEPRECATEDIN_1_1_0 __owur int
- HMAC_Init(HMAC_CTX *ctx, const void *key, int len, const EVP_MD *md);
+ # ifndef OPENSSL_NO_DEPRECATED_3_0
/* ... */
- # endif
-
-=head2 Implementations of deprecated symbols
-
-At least for the period of deprecation for any symbol, its implementation
-needs to be kept, and for symbols that are kept internally, for longer than
-that. There are two things to deal with:
-
-=over 4
-
-=item Deprecation warnings
-
-To remedy deprecation warnings, simply define the macro
-B<OPENSSL_SUPPRESS_DEPRECATED> at the beginning of the translation unit.
-
-=item Simulated removal
-=over 4
-
-=item *
-
-For symbols that are kept as legacy, the simulated removal should be
-enforced, by guarding the implementation the exact same way as the
-declaration in the public header file.
-
-=item *
-
-For symbols that are planned to be kept internally beyond their deprecation
-period, the translation units that implement them must ensure that the
-public header files they include to that declare the symbols don't remove
-the symbols, even when removal is otherwise simulated.
+ OSSL_DEPRECATEDIN_3_0 RSA *RSA_new_method(ENGINE *engine);
-=back
-
-=back
+ /* ... */
+ # endif
-=head3 Implementations kept as legacy
+=head2 Implementations to be removed
-For a deprecated function that we plan to simply remove, for example
+For a deprecated function that we plan to remove in the future, for example
RSA_new_method(), the following should be found very early (before including
-any OpenSSL header file) in the translation unit:
+any OpenSSL header file) in the translation unit that implements it and in
+any translation unit that uses it:
/*
* Suppress deprecation warnings for RSA low level implementations that are
@@ -188,7 +101,8 @@ any OpenSSL header file) in the translation unit:
*/
#define OPENSSL_SUPPRESS_DEPRECATED
-And RSA_new_method() implementation itself should be guarded like this:
+The RSA_new_method() implementation itself must be guarded the same way as
+its declaration in the public header file is:
#ifndef OPENSSL_NO_DEPRECATED_3_0
RSA *RSA_new_method(ENGINE *engine)
@@ -197,11 +111,12 @@ And RSA_new_method() implementation itself should be guarded like this:
}
#endif
-=head3 Implementations kept for internal purposes
+=head2 Implementations to remain internally
For a deprecated function that we plan to keep internally, for example
RSA_size(), the following should be found very early (before including any
-other OpenSSL header file) in the translation unit:
+other OpenSSL header file) in the translation unit that implements it and in
+any translation unit that uses it:
/*
* RSA low level APIs are deprecated for public use, but are kept for
diff --git a/util/find-doc-nits b/util/find-doc-nits
index d614844952..a581adfa35 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -91,10 +91,11 @@ my %mandatory_sections = (
);
# Symbols that we ignored.
-# They are internal macros that we currently don't document
+# They are reserved macros that we currently don't document
my $ignored = qr/(?| ^i2d_
| ^d2i_
| ^DEPRECATEDIN
+ | ^OSSL_DEPRECATED
| \Q_fnsig(3)\E$
| ^IMPLEMENT_
| ^_?DECLARE_
diff --git a/util/missingmacro.txt b/util/missingmacro.txt
index 109bb0870f..2b02fef5f5 100644
--- a/util/missingmacro.txt
+++ b/util/missingmacro.txt
@@ -176,14 +176,3 @@ X509V3_set_ctx_test(3)
X509V3_set_ctx_nodb(3)
EXT_BITSTRING(3)
EXT_IA5STRING(3)
-
-# These are documented internally, in doc/internal/man7/deprecation.pod
-OSSL_DEPRECATED(3)
-OSSL_DEPRECATED_FOR(3)
-OSSL_DEPRECATEDIN_3_0_FOR(3)
-OSSL_DEPRECATEDIN_1_1_1_FOR(3)
-OSSL_DEPRECATEDIN_1_1_0_FOR(3)
-OSSL_DEPRECATEDIN_1_0_2_FOR(3)
-OSSL_DEPRECATEDIN_1_0_1_FOR(3)
-OSSL_DEPRECATEDIN_1_0_0_FOR(3)
-OSSL_DEPRECATEDIN_0_9_8_FOR(3)
More information about the openssl-commits
mailing list