doc/internal/man7/deprecation.pod

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