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