Change the logic and behaviour surrounding '--api' and 'no-deprecated'

At some point in time, there was a 'no-deprecated' configuration
option, which had the effect of hiding all declarations of deprecated
stuff, i.e. make the public API look like they were all removed.

At some point in time, there was a '--api' configuration option, which
had the effect of having the public API look like it did in the version
given as value, on a best effort basis.  In practice, this was used to
get different implementations of BN_zero(), depending on the desired
API compatibility level.

At some later point in time, '--api' was changed to mean the same as
'no-deprecated', but only for the deprecations up to and including the
desired API compatibility level.  BN_zero() has been set to the
pre-1.0.0 implementation ever since, unless 'no-deprecation' has been
given.

This change turns these options back to their original meaning, but
with the slight twist that when combined, i.e. both '--api' and
'no-deprecated' is given, the declarations that are marked deprecated
up to an including the desired API compatibility level are hidden,
simulating that they have been removed.

If no desired API compatibility level has been given, then
configuration sets the current OpenSSL version by default.

Furthermore, the macro OPENSSL_API_LEVEL is now used exclusively to
check what API compatibility level is desired.  For checking in code
if `no-deprecated` has been configured for the desired API
compatibility level, macros for each supported level is generated,
such as OPENSSL_NO_DEPRECATED_1_1_1, corresponding to the use of
DEPRECATEDIN_ macros, such as DEPRECATEDIN_1_1_1().

Just like before, to set an API compatibility level when building an
application, define OPENSSL_API_COMPAT with an appropriate value.  If
it's desirable to hide deprecated functions up to and including that
level, additionally define OPENSSL_NO_DEPRECATED (the value is
ignored).

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10364)

CHANGES

@@ -9,6 +9,32 @@
 
  Changes between 1.1.1 and 3.0.0 [xx XXX xxxx]
 
+  *) Change the interpretation of the '--api' configuration option to
+     mean that this is a desired API compatibility level with no
+     further meaning.  The previous interpretation, that this would
+     also mean to remove all deprecated symbols up to and including
+     the given version, no requires that 'no-deprecated' is also used
+     in the configuration.
+
+     When building applications, the desired API compatibility level
+     can be set with the OPENSSL_API_COMPAT macro like before.  For
+     API compatibility version below 3.0, the old style numerical
+     value is valid as before, such as -DOPENSSL_API_COMPAT=0x10100000L.
+     For version 3.0 and on, the value is expected to be the decimal
+     value calculated from the major and minor version like this:
+
+         MAJOR * 10000 + MINOR * 100
+
+     Examples:
+
+         -DOPENSSL_API_COMPAT=30000             For 3.0
+         -DOPENSSL_API_COMPAT=30200             For 3.2
+
+     To hide declarations that are deprecated up to and including the
+     given API compatibility level, -DOPENSSL_NO_DEPRECATED must be
+     given when building the application as well.
+     [Richard Levitte]
+
   *) Added the X509_LOOKUP_METHOD called X509_LOOKUP_store, to allow
      access to certificate and CRL stores via URIs and OSSL_STORE
      loaders.
@@ -360,15 +386,6 @@
   *) Change the license to the Apache License v2.0.
      [Richard Levitte]
 
-  *) Change the possible version information given with OPENSSL_API_COMPAT.
-     It may be a pre-3.0.0 style numerical version number as it was defined
-     in 1.1.0, and it may also simply take the major version number.
-
-     Because of the version numbering of pre-3.0.0 releases, the values 0,
-     1 and 2 are equivalent to 0x00908000L (0.9.8), 0x10000000L (1.0.0) and
-     0x10100000L (1.1.0), respectively.
-     [Richard Levitte]
-
   *) Switch to a new version scheme using three numbers MAJOR.MINOR.PATCH.
 
      o Major releases (indicated by incrementing the MAJOR release number)