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