doc/internal/man7/deprecation.pod

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