Add mechanism for deprecated declarations.

This allows us to mark functions as deprecated
declarations with OPENSSL_DEPRECATED.

We also add an OPENSSL_BEGIN_ALLOW_DEPRECATED and an
OPENSSL_END_ALLOW_DEPRECATED for testing use to
test deprecated functions.

The purpose of this is to allow us to mark things
people should not be using as deprecated, and force some
inconvenience on the user of such things to notice them
(as opposed to a only a warning to not use it that they
may not see or read without something tripping them up.)

The intent is to still allow use, with some effort,
before removing the function, or moving it to
libdecrepit.

We initially mark X509V3_EXT_add and X509V3_EXT_add_alias
as deprecated.

Update-Note: We are starting to mark some functions in
boringssl as deprecated declarations which will cause the
compiler to emit warnings if they are used. The intention
is both to prevent accidental use in new code, and to to call
attention to call sites in existing code so that the documentation
for the deprecated function can be revisted and appropriate action
taken.

Bug: 584
Change-Id: Ia9ff386f0d22588e8a5999eda1a48b8c28dca2de
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/58405
Reviewed-by: Adam Langley <agl@google.com>
Commit-Queue: Bob Beck <bbe@google.com>

crypto/crypto_test.cc

@@ -158,3 +158,12 @@ TEST(Crypto, OnDemandIntegrityTest) {
   BORINGSSL_integrity_test();
 }
 #endif
+
+OPENSSL_DEPRECATED static void DeprecatedFunction() {}
+
+OPENSSL_BEGIN_ALLOW_DEPRECATED
+TEST(CryptoTest, DeprecatedFunction) {
+  // This is deprecated, but should not trigger any warnings.
+  DeprecatedFunction();
+}
+OPENSSL_END_ALLOW_DEPRECATED

crypto/x509v3/v3_lib.c

@@ -141,6 +141,7 @@ int X509V3_EXT_free(int nid, void *ext_data) {
 }
 
 int X509V3_EXT_add_alias(int nid_to, int nid_from) {
+OPENSSL_BEGIN_ALLOW_DEPRECATED
   const X509V3_EXT_METHOD *ext;
   X509V3_EXT_METHOD *tmpext;
 
@@ -159,6 +160,7 @@ int X509V3_EXT_add_alias(int nid_to, int nid_from) {
     return 0;
   }
   return 1;
+OPENSSL_END_ALLOW_DEPRECATED
 }
 
 // Legacy function: we don't need to add standard extensions any more because

include/openssl/base.h

@@ -221,6 +221,33 @@ extern "C" {
 
 #endif  // defined(BORINGSSL_SHARED_LIBRARY)
 
+#if defined(_MSC_VER)
+
+// OPENSSL_DEPRECATED is used to mark a function as deprecated. Use
+// of any functions so marked in caller code will produce a warning.
+// OPENSSL_BEGIN_ALLOW_DEPRECATED and OPENSSL_END_ALLOW_DEPRECATED
+// can be used to suppress the warning in regions of caller code.
+#define OPENSSL_DEPRECATED __declspec(deprecated)
+#define OPENSSL_BEGIN_ALLOW_DEPRECATED \
+  __pragma(warning(push)) __pragma(warning(disable : 4996))
+#define OPENSSL_END_ALLOW_DEPRECATED __pragma(warning(pop))
+
+#elif defined(__GNUC__) || defined(__clang__)
+
+#define OPENSSL_DEPRECATED __attribute__((__deprecated__))
+#define OPENSSL_BEGIN_ALLOW_DEPRECATED \
+  _Pragma("GCC diagnostic push")       \
+      _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
+#define OPENSSL_END_ALLOW_DEPRECATED _Pragma("GCC diagnostic pop")
+
+#else
+
+#define OPENSSL_DEPRECATED
+#define OPENSSL_BEGIN_ALLOW_DEPRECATED
+#define OPENSSL_END_ALLOW_DEPRECATED
+
+#endif
+
 
 #if defined(__GNUC__) || defined(__clang__)
 // MinGW has two different printf implementations. Ensure the format macro

include/openssl/x509v3.h

@@ -688,14 +688,15 @@ OPENSSL_EXPORT char *i2s_ASN1_ENUMERATED(const X509V3_EXT_METHOD *meth,
 // callers should simply handle the custom extension with the byte-based
 // |X509_EXTENSION| APIs directly. Registering |ext| with the library has little
 // practical value.
-OPENSSL_EXPORT int X509V3_EXT_add(X509V3_EXT_METHOD *ext);
+OPENSSL_EXPORT OPENSSL_DEPRECATED int X509V3_EXT_add(X509V3_EXT_METHOD *ext);
 
 // X509V3_EXT_add_alias registers a custom extension with NID |nid_to|. The
 // corresponding ASN.1 type is copied from |nid_from|. It returns one on success
 // and zero on error.
 //
 // WARNING: Do not use this function. See |X509V3_EXT_add|.
-OPENSSL_EXPORT int X509V3_EXT_add_alias(int nid_to, int nid_from);
+OPENSSL_EXPORT OPENSSL_DEPRECATED int X509V3_EXT_add_alias(int nid_to,
+                                                           int nid_from);
 
 OPENSSL_EXPORT const X509V3_EXT_METHOD *X509V3_EXT_get(
     const X509_EXTENSION *ext);