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