[openssl-project] A proposal for an updated OpenSSL version scheme (v2)

[Richard Levitte]

In message <056A59CE-2F19-43AE-B2E8-290ECB3D0D77 at dukhovni.org> on Sat, 22 Sep 2018 01:02:29 -0400, Viktor Dukhovni <openssl-users at dukhovni.org> said:

> 
> 
> > On Sep 22, 2018, at 12:59 AM, Richard Levitte <levitte at openssl.org> wrote:
> > 
> > So in summary, do we agree on this, and that it's a good path forward?
> > 
> > - semantic versioning scheme good, we should adopt it.
> > - we need to agree on how to translate that in code.
> > - we need to stop fighting about history.
> 
> Yes.

Cool.

On to how to translate that in code.  As a basis, it makes sense to
have a base with three macros to express the three numbers of a
semantic version and calculate things from there.  If it were just me,
I'd adopt that as is.

The problematic part of this, as far as I've seen, is how our users
have treated the integer (numeric encoding of the version) that we've
given them, and what we want to say to them going forward.

For the use in pre-processing C, what I've seen treats the number as
an incrementing entity without putting actual meaning into the bits.
If they can check the version with < and >= operators, they should be
fine.  As long as the number we give them continues to be useful in
this manner, we're good.

For checking if they can rely on ABI compatibility between the
application and the library, what I've seen is that they compare
certain bits from the result of calling OpenSSL_version_num() with
the same bits from OPENSSL_VERSION_NUMBER. 
This is where things get tricky and we must ask ourselves how we want
things to be done going forward.

Let me expand on that last bit for a moment.  It's important for some
(those that dlopen libcrypto rather than linking at build time, for
example) to be able to check at run time that they can rely on our
functionality compared to what they built for.  Masking and checking
for equality has been the method to do so, as far as I've seen.

Do we agree so far?

So far, we've basically seen two proposed solutions to the problem:

- one is a method that tries to match what we have done de-facto for
  the last 6 years and how those that check for compatibility have
  used the encoded version number, with specific masks.

- the other goes to the semantics of the encoded version number
  according to documentation in opensslv.h and pod and drops the bits
  that don't correspond to semantic versioning.  This will require
  those that check for compatibility to change their mask to match.
  In essence, openssh will have to introduce something like this:

      if (headerver >= 0x20000000L)
          mask = 0xf0000000L;

  ... and adjust their lfix and hfix masks to match.

A third solution could be to add an API that returns the three
semantic versioning numbers (MAJOR, MINOR, PATCH), to be compared
against Tim's proposed OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR
and OPENSSL_VERSION_PATCH.  That is a solution that, even though
*new*, would solve quite a lot of problems, beginning with all the
masking nonsense...  and OPENSSL_VERSION_NUMBER could still exist for
those using it for pre-processing.

Cheers,
Richard

-- 
Richard Levitte         levitte at openssl.org
OpenSSL Project         http://www.openssl.org/~levitte/