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