Commit 3a1aea4ff3 for openssl.org

commit 3a1aea4ff3eb1eacedc82e8698456f1b3b69b43e
Author: Bob Beck <beck@openssl.org>
Date:   Fri May 22 01:19:04 2026 -0600

    Document OSSL_BEGIN_ALLOW_DEPRECATED OSSL_END_ALLOW_DEPRECATED

    As these are public by necessity, we may as well allow folks
    to use them to selectively disable deprecation warnings if they
    wish to temporarily use deprecated functions in limited locations
    in their code.

    Complements: 4036f4b0e324 "Add new public API for checking certificate times."

    Reviewed-by: Paul Dale <paul.dale@oracle.com>
    Reviewed-by: Nikola Pajkovsky <nikolap@openssl.org>
    Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
    MergeDate: Tue May 26 09:22:58 2026
    (Merged from https://github.com/openssl/openssl/pull/31270)

diff --git a/doc/man3/OPENSSL_FILE.pod b/doc/man3/OPENSSL_FILE.pod
index 7d9dc2b3b8..22128a5c5b 100644
--- a/doc/man3/OPENSSL_FILE.pod
+++ b/doc/man3/OPENSSL_FILE.pod
@@ -3,6 +3,7 @@
 =head1 NAME

 OPENSSL_FILE, OPENSSL_LINE, OPENSSL_FUNC,
+OSSL_BEGIN_ALLOW_DEPRECATED, OSSL_END_ALLOW_DEPRECATED,
 OPENSSL_MSTR, OPENSSL_MSTR_HELPER
 - generic C programming utility macros

@@ -17,6 +18,9 @@ OPENSSL_MSTR, OPENSSL_MSTR_HELPER
  #define OPENSSL_MSTR_HELPER(x) #x
  #define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)

+ #define OSSL_BEGIN_ALLOW_DEPRECATED /* compiler specific */
+ #define OSSL_END_ALLOW_DEPRECATED /* compiler specific */
+
 =head1 DESCRIPTION

 The macros B<OPENSSL_FILE> and B<OPENSSL_LINE>
@@ -31,6 +35,17 @@ The macro B<OPENSSL_MSTR> yields the expansion of the macro given as argument,
 which is useful for concatenation with string constants.
 The macro B<OPENSSL_MSTR_HELPER> is an auxiliary macro for this purpose.

+The macros B<OSSL_BEGIN_ALLOW_DEPRECATED> and
+B<OSSL_END_ALLOW_DEPRECATED> respectively disable and then
+re-enable compiler warnings for deprecated functions within a source
+file, for compilers which OpenSSL supports. They are equivalent to
+disabling the warnings with compiler-specific options, but may be
+convenient when you wish to use deprecated OpenSSL functions
+temporarily in limited areas of code without turning off warnings more
+globally. It is nevertheless important to remember to eventually
+transition such code to replacement functions, as deprecated functions
+may be removed in later major OpenSSL releases.
+
 =head1 RETURN VALUES

 see above
@@ -44,9 +59,12 @@ L<crypto(7)>
 B<OPENSSL_FUNC>, B<OPENSSL_MSTR>, and B<OPENSSL_MSTR_HELPER>
 were added in OpenSSL 3.0.

+B<OSSL_BEGIN_ALLOW_DEPRECATED> and B<OSSL_END_ALLOW_DEPRECATED> were
+added in OpenSSL 4.0, inspired by BoringSSL.
+
 =head1 COPYRIGHT

-Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2018-2026 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
diff --git a/util/other.syms b/util/other.syms
index b61353ff32..efed22cca8 100644
--- a/util/other.syms
+++ b/util/other.syms
@@ -897,3 +897,5 @@ OPENSSL_load_u64_be                     inline
 OPENSSL_load_u64_le                     inline
 OPENSSL_store_u64_be                    inline
 OPENSSL_store_u64_le                    inline
+OSSL_BEGIN_ALLOW_DEPRECATED             define
+OSSL_END_ALLOW_DEPRECATED               define