mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-30 14:01:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

Simplify and clarify doc/internal/man7/deprecation.pod

Browse Source 
doc/internal/man7/deprecation.pod was unclear in some areas, and
included general documentation that has no place there.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13240)
This commit is contained in:
Richard Levitte 2020-10-25 12:20:13 +01:00
parent 908cf7cefb
commit d14e7df852
2 changed files with 118 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
doc/internal/man3/OSSL_DEPRECATED.pod Normal file
View File

@ -0,0 +1,54 @@
=pod
=head1 NAME
OSSL_DEPRECATED, OSSL_DEPRECATED_FOR - General deprecation macros
=head1 SYNOPSIS
#include <openssl/macros.h>
#define OSSL_DEPRECATED(since)
#define OSSL_DEPRECATED_FOR(since, msg)
=head1 DESCRIPTION
OSSL_DEPRECATED() implements the deprecated attribute if the compiler
supports it, otherwise it expands to nothing. It takes one argument
I<since> that should be set to the OpenSSL version where the symbol was
deprecated, and will be displayed with the deprecation warning message,
for compilers that support user specified deprecation messages.
OSSL_DEPRECATED_FOR() does the same as OSSL_DEPRECATED(), but also takes a
second argument I<msg>, which is an additional text messages to be displayed
with the deprecation warning along with the OpenSSL version number, for
compilers that support user specified deprecation messages.
These macros are used to define the version specific deprecation macros
described in L<deprecation(7)>.
=begin comment
[RETURN VALUES isn't relevant for these macros, but find-doc-nits demands
the presence of this section]
=head1 RETURN VALUES
[podchecker doesn't like empty sections]
=end comment
=head1 SEE ALSO
L<deprecation(7)>
=head1 COPYRIGHT
Copyright 2020 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

213
doc/internal/man7/deprecation.pod
View File

@ -2,185 +2,98 @@
=head1 NAME
deprecation - Macros used for deprecating symbols and simulate removal
=head1 SYNOPSIS
#include <openssl/macros.h>
OSSL_DEPRECATED(since)
OSSL_DEPRECATED_FOR(since, msg)
OPENSSL_NO_DEPRECATED_3_0
OSSL_DEPRECATEDIN_3_0
OSSL_DEPRECATEDIN_3_0_FOR(msg)
OPENSSL_NO_DEPRECATED_1_1_1
OSSL_DEPRECATEDIN_1_1_1
OSSL_DEPRECATEDIN_1_1_1_FOR(msg)
OPENSSL_NO_DEPRECATED_1_1_0
OSSL_DEPRECATEDIN_1_1_0
OSSL_DEPRECATEDIN_1_1_0_FOR(msg)
OPENSSL_NO_DEPRECATED_1_0_2
OSSL_DEPRECATEDIN_1_0_2
OSSL_DEPRECATEDIN_1_0_2_FOR(msg)
OPENSSL_NO_DEPRECATED_1_0_1
OSSL_DEPRECATEDIN_1_0_1
OSSL_DEPRECATEDIN_1_0_1_FOR(msg)
OPENSSL_NO_DEPRECATED_1_0_0
OSSL_DEPRECATEDIN_1_0_0
OSSL_DEPRECATEDIN_1_0_0_FOR(msg)
OPENSSL_NO_DEPRECATED_0_9_8
OSSL_DEPRECATEDIN_0_9_8
OSSL_DEPRECATEDIN_0_9_8_FOR(msg)
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 F<< <openssl/*.h> >> header files).
functions in our public header files, F<< <openssl/*.h> >>).
Removal of a symbol is not the same thing as deprecation, as it actually
removes the symbol from public view.
explicitly removes the symbol from public view.
OpenSSL configuration supports deprecation as well as simulating removal of
symbols from public view, and also supports doing this in terms of a
specified OpenSSL version.
symbols from public view (with the configuration option `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 `--api`, or if the user chooses to do so, with
L<OPENSSL_API_COMPAT(7)>).
Deprecation is done using attribute macros having names starting with
B<OSSL_DEPRECATED>, used with any declaration it applies to.
Deprecation is done using attribute macros named
B<OSSL_DEPRECATEDIN_I<version>>, used with any declaration it applies to.
Simulating removal is done with guard macros having names starting with
L<OPENSSL_NO_DEPRECATED(7)>.
Simulating removal is done with C<#ifndef> preprocessor guards using macros
named B<OPENSSL_NO_DEPRECATED_I<version>>.
The implementation of a deprecated symbol is kept for two reasons:
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 Kept as legacy for the deprecation period
=item Planned to be removed
It's implemented only to have it available as long as the symbol isn't
removed entirely (be it by explicitly removing it when it's judged that it
has been deprecated long enough, or because the removal is simulated).
These need to be guarded appropriately, as shown in the L</Implementations
kept as legacy>.
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 Kept for internal purposes
=item Planned to remain internally
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 implementation is located, even when the symbol
is publicly unavailable through simulated removal. That's done by including
an internal header file very early in the translation unit. See
L</Implementations kept for internal purposes>.
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.
In a future cleanup, the declaration should be explicitly moved to an
internal header file, with the deprecation attribute removed, and the
translation unit should adjust its header inclusions accordingly.
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
=head2 General macros
I<Note: none of these macros should be used directly, please use the version
specific macros instead>
OSSL_DEPRECATED() implements the deprecated attribute if the compiler
supports it, otherwise it expands to nothing. It takes one argument
I<since> that should be set to the OpenSSL version where the symbol was
deprecated, and will be displayed with the deprecation warning message,
for compilers that support user specified deprecation messages.
OSSL_DEPRECATED_FOR() does the same as OSSL_DEPRECATED(), but also takes a
second argument I<msg>, which is an additional text messages to be displayed
with the deprecation warning along with the OpenSSL version number, for
compilers that support user specified deprecation messages.
B<OPENSSL_NO_DEPRECATED> is a macro that's generated by OpenSSL
configuration in response to the C<no-deprecated> configuration option.
This macro suppresses the definition of deprecated symbols.
=head2 Version specific macros
OSSL_DEPRECATEDIN_I<major>_I<minor>() macros that are defined to
OSSL_DEPRECATED() with that version number as I<since>, for any version up
to and including the one expressed with L<OPENSSL_API_COMPAT(7)>. For any
known version above the version expressed with L<OPENSSL_API_COMPAT(7)>,
The are defined to nothing.
OSSL_DEPRECATEDIN_I<major>_I<minor>_FOR() macros that are defined to
OSSL_DEPRECATED() with that version number as I<since>, under the same
conditions as OSSL_DEPRECATEDIN_I<major>_I<minor>().
B<OPENSSL_NO_DEPRECATED_I<major>_I<minor>> macros should be used as
guards around declarations that will eventually disappear from the public
header files (F<< <openssl/*.h> >>).
Any set of symbols deprecated with a B<OSSL_DEPRECATEDIN_I<major>_I<minor>>
attribute macro B<must> be wrapped with a guard using the corresponding
B<OPENSSL_NO_DEPRECATED_I<major>_I<minor>> macro, see L</Header files>
example below. This not only affects what the user of the header file will
have available, it's also used to determine the conditions for exporting the
symbol in the shared libraries.
=head1 EXAMPLES
=head2 Header files
In public header files (F<< <openssl/*.h> >>), a deprecated symbol will
always be wrapped with a negative test of the guard:
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_1_1_0
# ifndef OPENSSL_NO_DEPRECATED_3_0
/* ... */
OSSL_DEPRECATEDIN_1_1_0 __owur int
HMAC_Init(HMAC_CTX *ctx, const void *key, int len, const EVP_MD *md);
OSSL_DEPRECATEDIN_3_0 RSA *RSA_new_method(ENGINE *engine);
/* ... */
# endif
=head2 Implementations of deprecated symbols
=head2 Implementations to be removed
At least for the period of deprecation for any symbol, its implementation
needs to be kept, and for symbols that are kept internally, for longer than
that. There are two things to deal with:
=over 4
=item Deprecation warnings
To remedy deprecation warnings, simply define the macro
B<OPENSSL_SUPPRESS_DEPRECATED> at the beginning of the translation unit.
=item Simulated removal
=over 4
=item *
For symbols that are kept as legacy, the simulated removal should be
enforced, by guarding the implementation the exact same way as the
declaration in the public header file.
=item *
For symbols that are planned to be kept internally beyond their deprecation
period, the translation units that implement them must ensure that the
public header files they include to that declare the symbols don't remove
the symbols, even when removal is otherwise simulated.
=back
=back
=head3 Implementations kept as legacy
For a deprecated function that we plan to simply remove, for example
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:
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
@ -188,7 +101,8 @@ any OpenSSL header file) in the translation unit:
*/
#define OPENSSL_SUPPRESS_DEPRECATED
And RSA_new_method() implementation itself should be guarded like this:
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)
@ -197,11 +111,12 @@ And RSA_new_method() implementation itself should be guarded like this:
}
#endif
=head3 Implementations kept for internal purposes
=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:
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