1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5*e7be843bSPierre ProncheryOPENSSL_NO_DEPRECATED_3_1, OSSL_DEPRECATEDIN_3_1, 6b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_3_0, OSSL_DEPRECATEDIN_3_0, 7b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_1_1_1, OSSL_DEPRECATEDIN_1_1_1, 8b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_1_1_0, OSSL_DEPRECATEDIN_1_1_0, 9b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_1_0_2, OSSL_DEPRECATEDIN_1_0_2, 10b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_1_0_1, OSSL_DEPRECATEDIN_1_0_1, 11b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_1_0_0, OSSL_DEPRECATEDIN_1_0_0, 12b077aed3SPierre ProncheryOPENSSL_NO_DEPRECATED_0_9_8, OSSL_DEPRECATEDIN_0_9_8, 13b077aed3SPierre Proncherydeprecation - How to do deprecation 14b077aed3SPierre Pronchery 15b077aed3SPierre Pronchery=head1 DESCRIPTION 16b077aed3SPierre Pronchery 17b077aed3SPierre ProncheryDeprecation of a symbol is adding an attribute to the declaration of that 18b077aed3SPierre Proncherysymbol (function, type, variable, but we currently only do that for 19b077aed3SPierre Proncheryfunctions in our public header files, F<< <openssl/*.h> >>). 20b077aed3SPierre Pronchery 21b077aed3SPierre ProncheryRemoval of a symbol is not the same thing as deprecation, as it actually 22b077aed3SPierre Proncheryexplicitly removes the symbol from public view. 23b077aed3SPierre Pronchery 24b077aed3SPierre ProncheryOpenSSL configuration supports deprecation as well as simulating removal of 25b077aed3SPierre Proncherysymbols from public view (with the configuration option C<no-deprecated>, or 26b077aed3SPierre Proncheryif the user chooses to do so, with L<OPENSSL_NO_DEPRECATED(7)>), and also 27b077aed3SPierre Proncherysupports doing this in terms of a specified OpenSSL version (with the 28b077aed3SPierre Proncheryconfiguration option C<--api>, or if the user chooses to do so, with 29b077aed3SPierre ProncheryL<OPENSSL_API_COMPAT(7)>). 30b077aed3SPierre Pronchery 31b077aed3SPierre ProncheryDeprecation is done using attribute macros named 32b077aed3SPierre ProncheryB<OSSL_DEPRECATEDIN_I<version>>, used with any declaration it applies to. 33b077aed3SPierre Pronchery 34b077aed3SPierre ProncherySimulating removal is done with C<#ifndef> preprocessor guards using macros 35b077aed3SPierre Proncherynamed B<OPENSSL_NO_DEPRECATED_I<version>>. 36b077aed3SPierre Pronchery 37b077aed3SPierre ProncheryB<OSSL_DEPRECATEDIN_I<version>> and B<OPENSSL_NO_DEPRECATED_I<version>> are 38b077aed3SPierre Proncherydefined in F<< <openssl/macros.h> >>. 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncheryIn those macro names, B<I<version>> corresponds to the OpenSSL release since 41b077aed3SPierre Proncherywhich the deprecation applies, with underscores instead of periods. Because 42b077aed3SPierre Proncheryof the change in version scheme with OpenSSL 3.0, the B<I<version>> for 43b077aed3SPierre Proncheryversions before that are three numbers (such as C<1_1_0>), while they are 44b077aed3SPierre Proncherytwo numbers (such as C<3_0>) from 3.0 and on. 45b077aed3SPierre Pronchery 46b077aed3SPierre ProncheryThe implementation of a deprecated symbol is kept for one of two reasons: 47b077aed3SPierre Pronchery 48b077aed3SPierre Pronchery=over 4 49b077aed3SPierre Pronchery 50b077aed3SPierre Pronchery=item Planned to be removed 51b077aed3SPierre Pronchery 52b077aed3SPierre ProncheryThe symbol and its implementation are planned to be removed some time in the 53b077aed3SPierre Proncheryfuture, but needs to remain available until that time. 54b077aed3SPierre ProncherySuch an implementation needs to be guarded appropriately, as shown in 55b077aed3SPierre ProncheryL</Implementations to be removed> below. 56b077aed3SPierre Pronchery 57b077aed3SPierre Pronchery=item Planned to remain internally 58b077aed3SPierre Pronchery 59b077aed3SPierre ProncheryThe symbol is planned to be removed from public view, but will otherwise 60b077aed3SPierre Proncheryremain for internal purposes. In this case, the implementation doesn't need 61b077aed3SPierre Proncheryto change or be guarded. 62b077aed3SPierre Pronchery 63b077aed3SPierre ProncheryHowever, it's necessary to ensure that the declaration remains available for 64b077aed3SPierre Proncherythe translation unit where the symbol is used or implemented, even when the 65b077aed3SPierre Proncherysymbol is publicly unavailable through simulated removal. That's done by 66b077aed3SPierre Proncheryincluding an internal header file very early in the affected translation 67b077aed3SPierre Proncheryunits. See L</Implementations to remain internally> below. 68b077aed3SPierre Pronchery 69b077aed3SPierre ProncheryIn the future, when the deprecated declaration is to actually be removed 70b077aed3SPierre Proncheryfrom public view, it should be moved to an internal header file, with the 71b077aed3SPierre Proncherydeprecation attribute removed, and the translation units that implement or 72b077aed3SPierre Proncheryuse that symbol should adjust their header inclusions accordingly. 73b077aed3SPierre Pronchery 74b077aed3SPierre Pronchery=back 75b077aed3SPierre Pronchery 76b077aed3SPierre Pronchery=head1 EXAMPLES 77b077aed3SPierre Pronchery 78b077aed3SPierre Pronchery=head2 Header files 79b077aed3SPierre Pronchery 80b077aed3SPierre ProncheryIn public header files (F<< <openssl/*.h> >>), this is what a deprecation is 81b077aed3SPierre Proncheryexpected to look like, including the preprocessor wrapping for simulated 82b077aed3SPierre Proncheryremoval: 83b077aed3SPierre Pronchery 84b077aed3SPierre Pronchery # ifndef OPENSSL_NO_DEPRECATED_3_0 85b077aed3SPierre Pronchery /* ... */ 86b077aed3SPierre Pronchery 87b077aed3SPierre Pronchery OSSL_DEPRECATEDIN_3_0 RSA *RSA_new_method(ENGINE *engine); 88b077aed3SPierre Pronchery 89b077aed3SPierre Pronchery /* ... */ 90b077aed3SPierre Pronchery # endif 91b077aed3SPierre Pronchery 92b077aed3SPierre Pronchery=head2 Implementations to be removed 93b077aed3SPierre Pronchery 94b077aed3SPierre ProncheryFor a deprecated function that we plan to remove in the future, for example 95b077aed3SPierre ProncheryRSA_new_method(), the following should be found very early (before including 96b077aed3SPierre Proncheryany OpenSSL header file) in the translation unit that implements it and in 97b077aed3SPierre Proncheryany translation unit that uses it: 98b077aed3SPierre Pronchery 99b077aed3SPierre Pronchery /* 100b077aed3SPierre Pronchery * Suppress deprecation warnings for RSA low level implementations that are 101b077aed3SPierre Pronchery * kept until removal. 102b077aed3SPierre Pronchery */ 103b077aed3SPierre Pronchery #define OPENSSL_SUPPRESS_DEPRECATED 104b077aed3SPierre Pronchery 105b077aed3SPierre ProncheryThe RSA_new_method() implementation itself must be guarded the same way as 106b077aed3SPierre Proncheryits declaration in the public header file is: 107b077aed3SPierre Pronchery 108b077aed3SPierre Pronchery #ifndef OPENSSL_NO_DEPRECATED_3_0 109b077aed3SPierre Pronchery RSA *RSA_new_method(ENGINE *engine) 110b077aed3SPierre Pronchery { 111b077aed3SPierre Pronchery /* ... */ 112b077aed3SPierre Pronchery } 113b077aed3SPierre Pronchery #endif 114b077aed3SPierre Pronchery 115b077aed3SPierre Pronchery=head2 Implementations to remain internally 116b077aed3SPierre Pronchery 117b077aed3SPierre ProncheryFor a deprecated function that we plan to keep internally, for example 118b077aed3SPierre ProncheryRSA_size(), the following should be found very early (before including any 119b077aed3SPierre Proncheryother OpenSSL header file) in the translation unit that implements it and in 120b077aed3SPierre Proncheryany translation unit that uses it: 121b077aed3SPierre Pronchery 122b077aed3SPierre Pronchery /* 123b077aed3SPierre Pronchery * RSA low level APIs are deprecated for public use, but are kept for 124b077aed3SPierre Pronchery * internal use. 125b077aed3SPierre Pronchery */ 126b077aed3SPierre Pronchery #include "internal/deprecated.h" 127b077aed3SPierre Pronchery 128b077aed3SPierre Pronchery=head1 SEE ALSO 129b077aed3SPierre Pronchery 130b077aed3SPierre ProncheryL<openssl_user_macros(7)> 131b077aed3SPierre Pronchery 132b077aed3SPierre Pronchery=head1 COPYRIGHT 133b077aed3SPierre Pronchery 134b077aed3SPierre ProncheryCopyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 135b077aed3SPierre Pronchery 136b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 137b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 138b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 139b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 140b077aed3SPierre Pronchery 141b077aed3SPierre Pronchery=cut 142