Inverted OPENSSL_API_COMPAT test in <openssl/macros.h> regarding to --api= version set

[ydroneaud]

I have hard time figuring how to use --api=x.y.z regarding OPENSSL_API_COMPAT define.

• https://github.com/openssl/openssl/blob/openssl-3.0.1/INSTALL.md#api-level
• https://www.openssl.org/docs/man3.0/man7/OPENSSL_API_COMPAT.html

Say I have #define OPENSSL_API_COMPAT 0x010101000L in one file and want to compile it against OpenSSL 3.0.1 configured with --api=1.1.0, I would have expected OPENSSL_API_COMPAT to ask for API 1.1.1 to be available, and --api=1.1.0 to ask for APIs 1.1.0, 1.1.1, and 3.0 to be built in OpenSSL.

But this doesn't work as I expected:

$ git describe
openssl-3.0.1

• Configure OpenSSL with --api=3.0 and preprocess code asking for 1.1.1 compatibility:

$ ./Configure --banner= --api=3.0 && make -s build_generated && gcc -E -x c /dev/null -I include -DOPENSSL_API_COMPAT=0x010101000L -include "include/openssl/opensslconf.h" -o /dev/null  && echo "*** SUCCESS ***"
Configuring OpenSSL version 3.0.1 for target linux-x86_64
Using os-specific seed configuration
Creating configdata.pm
Running configdata.pm
Creating Makefile.in
Creating Makefile

*** SUCCESS ***

• Configure OpenSSL with --api=1.1.1 and preprocess code asking for 1.1.1 compatibility:

$ ./Configure --banner= --api=1.1.1 && make -s build_generated && gcc -E -x c /dev/null -I include -DOPENSSL_API_COMPAT=0x010101000L -include "include/openssl/opensslconf.h" -o /dev/null && echo "*** SUCCESS ***"
Configuring OpenSSL version 3.0.1 for target linux-x86_64
Using os-specific seed configuration
Creating configdata.pm
Running configdata.pm
Creating Makefile.in
Creating Makefile

*** SUCCESS ***

• Configure OpenSSL with --api=1.1.0 and preprocess code asking for 1.1.1 compatibility:

$ ./Configure --banner= --api=1.1.0 && make -s build_generated && gcc -E -x c /dev/null -I include -DOPENSSL_API_COMPAT=0x010101000L -include "include/openssl/opensslconf.h" -o /dev/null && echo "*** SUCCESS ***"
Configuring OpenSSL version 3.0.1 for target linux-x86_64
Using os-specific seed configuration
Creating configdata.pm
Running configdata.pm
Creating Makefile.in
Creating Makefile

In file included from ./include/openssl/opensslconf.h:15,
                  from <command-line>:
include/openssl/macros.h:139:4: error: #error "The requested API level higher than the configured API compatibility level"
   139 | #  error "The requested API level higher than the configured API compatibility level"
       |    ^~~~~

It makes no sense to me that building OpenSSL with --api=3.0 provides 1.1.1 OPENSSL_API_COMPAT, while OpenSSL configured with --api=1.1.0 doesn't provide 1.1.1 OPENSSL_API_COMPAT, as --api should set the oldest API supported.

In

openssl/include/openssl/macros.h

Line 138 in 1bf649b

# if OPENSSL_API_LEVEL > OPENSSL_CONFIGURED_API

# if OPENSSL_API_LEVEL > OPENSSL_CONFIGURED_API
#  error "The requested API level higher than the configured API compatibility level"
# endif

I believe the test should be inverted

# if OPENSSL_API_LEVEL < OPENSSL_CONFIGURED_API
#  error "The requested API level lower than the configured API compatibility level"
# endif

Especially as requesting higher OPENSSL_API_COMPAT is prevented

openssl/include/openssl/macros.h

Line 145 in 1bf649b

/* Can't go higher than the current version. */

/* Can't go higher than the current version. */
# if OPENSSL_API_LEVEL > (OPENSSL_VERSION_MAJOR * 10000 + OPENSSL_VERSION_MINOR * 100)
#  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
# endif

Issue reported on openssl-users@openssl.org, see https://mta.openssl.org/pipermail/openssl-users/2022-March/014960.html

[levitte]

@ydroneaud spoke thusly:

It makes no sense to me that building OpenSSL with --api=3.0 provides 1.1.1 OPENSSL_API_COMPAT, while OpenSSL configured with --api=1.1.0 doesn't provide 1.1.1 OPENSSL_API_COMPAT, as --api should set the oldest API supported.

Here lies the misunderstanding. By design, --api= designates the newest that the OpenSSL build will support. Therefore, any application linking with OpenSSL can only ask (via OPENSSL_API_COMPAT) for supported API levels up to what OpenSSL was built for.

Note that this is only really applicable for deprecations, as they are tied to specific OpenSSL versions, so whatever --api= or OPENSSL_API_COMPAT you choose, newer functions are available no matter what.

This was made specifically for the sake of applications that were made for a specific version of OpenSSL (i.e. that's the version they are compatible with) and that want to avoid lots of deprecation warnings, they can simply announce that with OPENSSL_API_COMPAT set to an appropriate version.

I would recommend simply not using --api= for production, as it's meant for very specific and rather uncommon scenarios, and just use OPENSSL_API_COMPAT with other programs that need it.

[ydroneaud]

@levitte thanks for your explanation. With regard to your answer, I really feel https://github.com/openssl/openssl/blob/openssl-3.0.2/INSTALL.md#api-level wording confusing.

And it makes no-deprecated inapplicable to my use case, as using no-deprecated alone seems to remove too many APIs

If you just intend to remove all deprecated APIs up to the current version entirely, just specify no-deprecated

I wanted to remove all deprecated APIs below 1.1.0, not all deprecated APIs below 3.0 ...

[ydroneaud]

With OpenSSL 1.1.1, I'm using no-deprecated alone, and my legacy code build fine.

Switching to OpenSSL 3.0.x, no-deprecated had to be removed for the same code to build. I was hoping using --api would lower the deprecation cutoff.