From d14e7df8529a3e8fcc2c107369ebcc5abbcccd11 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sun, 25 Oct 2020 12:20:13 +0100 Subject: [PATCH] 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 (Merged from https://github.com/openssl/openssl/pull/13240) --- doc/internal/man3/OSSL_DEPRECATED.pod | 54 +++++++ doc/internal/man7/deprecation.pod | 211 ++++++++------------------ 2 files changed, 117 insertions(+), 148 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 + + #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 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, 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. + +=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 + +=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. + +=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 - - 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<< >> header files). +functions in our public header files, F<< >>). 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), 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). -Deprecation is done using attribute macros having names starting with -B, used with any declaration it applies to. +Deprecation is done using attribute macros named +B>, used with any declaration it applies to. -Simulating removal is done with guard macros having names starting with -L. +Simulating removal is done with C<#ifndef> preprocessor guards using macros +named B>. -The implementation of a deprecated symbol is kept for two reasons: +B> and B> are +defined in F<< >>. -=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. - -=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. +In those macro names, B> 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> 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 - -OSSL_DEPRECATED() implements the deprecated attribute if the compiler -supports it, otherwise it expands to nothing. It takes one argument -I 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, 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 is a macro that's generated by OpenSSL -configuration in response to the C 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 below. -=head2 Version specific macros +=item Planned to remain internally -OSSL_DEPRECATEDIN_I_I() macros that are defined to -OSSL_DEPRECATED() with that version number as I, for any version up -to and including the one expressed with L. For any -known version above the version expressed with L, -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_I_FOR() macros that are defined to -OSSL_DEPRECATED() with that version number as I, under the same -conditions as OSSL_DEPRECATEDIN_I_I(). +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 below. -B_I> macros should be used as -guards around declarations that will eventually disappear from the public -header files (F<< >>). +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_I> -attribute macro B be wrapped with a guard using the corresponding -B_I> macro, see L -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<< >>), a deprecated symbol will -always be wrapped with a negative test of the guard: +In public header files (F<< >>), 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 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 -- 2.34.1