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

[Richard Levitte]

In message <CAHEJ-S4s+=iRUzZHgV9dmWoXUN+pNZJ=y=g9UqGwjZZgafyQMA at mail.gmail.com> on Sat, 22 Sep 2018 00:07:47 +1000, Tim Hudson <tjh at cryptsoft.com> said:

> In semantic versioning terms this is what it would mean.
> And if you want to check release/alpha/beta status you look at the
> OPENSSL_VERSION_PRE_RELEASE macro and we stop the release+alpha+beta
> indicator usage in the OPENSSL_VERSION_NUMBER macro.
> It was rather limiting in its encoding format. That more rightly
> belongs in the semantic version string format.
> 
> #include <stdio.h>
> 
> #define OPENSSL_MSTR_HELPER(x) #x
> #define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)
> 
> #define OPENSSL_VERSION_MAJOR 1
> #define OPENSSL_VERSION_MINOR 1
> #define OPENSSL_VERSION_PATCH 2
> #define OPENSSL_VERSION_PRE_RELEASE "-beta1.special"
> #define OPENSSL_VERSION_BUILD_METADATA "+21Sep2018.optbuild.arm"

I like this.  This makes everything very clear to me

> #define OPENSSL_VERSION_NUMBER (long)((OPENSSL_VERSION_MAJOR<<28)|
> (OPENSSL_VERSION_MINOR<<20)|(OPENSSL_VERSION_PATCH<<12))

I think we need to get rid of OPENSSL_VERSION_NUMBER.  It's very
obvious that there are different and quite confusing view of what that
number represents.  It makes the number rubbish...

I've heard your arguments for your view, and you've been hammered with
my view, so here's the summary as I see it:

1. There's how we have acted and what we have told our users.  That
   corresponds to the FAQ entry that was introduced in April 2012 and
   the spelled out how things were from 1.0.0, which was released in
   March 2010.  This part supports the view that our versions are
   1.MAJOR.MINORpatch (where 'patch' is a letter).

2. There's a comment in opensslv.h and documentation in
   OPENSSL_VERSIO_NUMBER.pod that both stipulates that the version
   number is in fact MAJOR.MINOR.FIXpatch (where 'patch' is a letter).
   Just for reference, I'll point out that the last updates that
   affected the encoded version number format was in July 2001 (which
   is between releases 0.9.7 and 0.9.8) and September 2000 (by yours
   truly, somewhere between 0.9.5 and 0.9.6).

In both descriptions, and with the way we have encoded the version as
a number turns out to be the same, if we stop looking too hard at the
labels.  For clarity, I'll just rename them to X.Y.Zp ('p' for the
patch letter), so whether you interpret 1.0.2a according to the first
or the second interpretation, it has numerically been translated to
the same, 0x1000201fL (*).  I hope we can all agree so far.

So in essence, we have two competting views on the current semantics
of our versioning, where one is about the documentation in opensslv.h
comment and in pod, while the other is about an FAQ entry and how we
actually acted.

Neither of these two views are untrue per se, however one is more
current than the other (frankly, considering when they were last
updated and that we didn't follow that form in practice, I consider
the documentation in opensslv.h and pod outdated).

I wouldn't mind going back to acting according to the docs, not in the
least!  The only thing that troubles me there is that the mask people
used to compare the "major" part of the numeric encoding of the
version will have to change, i.e. it's in fact going to break what we
have told everyone since at least 2012.  And it seems to be quite
controversial to try and adapt to current usage, so perhaps the wiser
thing is to get rid of OPENSSL_VERSION_NUMBER and start over with a
differently named macro.  The three macro solution Tim presented is
good enough in my view.

Cheers,
Richard

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