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