diff options
author | Richard Levitte <levitte@openssl.org> | 2020-10-25 12:20:13 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2020-11-01 05:57:42 +0100 |
commit | d14e7df8529a3e8fcc2c107369ebcc5abbcccd11 (patch) | |
tree | 088c98be051b0a663e4560a520573dc1486cf90b | |
parent | 908cf7cefbb2a4c2a8ea1dd4798d1e689db6e3ed (diff) | |
download | openssl-new-d14e7df8529a3e8fcc2c107369ebcc5abbcccd11.tar.gz |
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@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13240)
-rw-r--r-- | doc/internal/man3/OSSL_DEPRECATED.pod | 54 | ||||
-rw-r--r-- | doc/internal/man7/deprecation.pod | 211 |
2 files changed, 117 insertions, 148 deletions
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 |