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

Sat Sep 22 01:28:44 UTC 2018

On Sat, 22 Sep. 2018, 3:24 am Viktor Dukhovni, <openssl-users at dukhovni.org>
wrote:

> > On Sep 21, 2018, at 12:50 PM, Tim Hudson <tjh at cryptsoft.com> wrote:
> > If that is the case then our current practice of allowing ABI breakage
> with
> > minor release changes (the middle number we document as the minor
> release number)
> > has to change.
> CORRECTION:  As advertised when 1.0.0 first came out, and repeated in our
> release
>              policy:
>           As of release 1.0.0 the OpenSSL versioning scheme was improved
>           to better meet developers' and vendors' expectations. Letter
>           releases, such as 1.0.2a, exclusively contain bug and security
>           fixes and no new features. Minor releases that change the
>           last digit, e.g. 1.1.0 vs. 1.1.1, can and are likely to
>           contain new features, but in a way that does not break binary
>           compatibility. This means that an application compiled and
>           dynamically linked with 1.1.0 does not need to be recompiled
>           when the shared library is updated to 1.1.1. It should be
>           noted that some features are transparent to the application
>           such as the maximum negotiated TLS version and cipher suites,
>           performance improvements and so on. There is no need to
>           recompile applications to benefit from these features.
>

I have to disagree here. We said things about *minor releases* and *major
releases* but we didn't say things about the version numbers or change the
documentation or code comments to say the first digit was meaningless and
that we have shifted the definition of what X.Y.Z means.

That parsing of history I think is at best a stretch and not supportable
and also not what our *users* think.

Our users don't call 1.0.2 the 0.2 release of OpenSSL. Our users don't call
1.0.0 the 0.0 release. There isn't a short hand or acceptance or a decision
communicated to conceptually drop the 1. off the front of our versioning.
Your logic and practice is saying you see the first two digits as the major
version number - that's fine - you are welcome to take an ABI compatible
short hand to refer to version - but that doesn't mean we changed the
definition of our versioning system.
What you are tracking there is effectively the SHLIB version.

So if our users don't think that, and our code comments don't stay that,
and our pod documentation doesn't say that and users have the first part in
their masks and don't just ignore it then I don't think it is supportable
to claim we told everyone it was a meaningless first digit and changed our
definition of our versioning scheme back at the 1.0.0 release.

Currently when we make minor API changes that aren't breaking we update the
fix version number. When we make major API changes which we expect to be
breaking we update the minor version number.
Now think about the transition from 1.1.0 to 1.1.1 - that is by any
reasonable definition *a major release* - but we don't update the major
version number by either definition of the major version number.
We call it in our website a "feature release" - yet more terminology to
dance around our version numbering scheme.
Read the actual blog post
<https://www.openssl.org/blog/blog/2018/09/11/release111/> and try to parse
that as *a minor release* - it isn't - it is *a major release* - but we did
not change the *major release number *even if we accepted the theory and
your definition that the first number is meaningless and it is only the
second number that is the real major version and the third number isn't a
fix version is it actually the minor version. The implications of that view
point aren't supported by our actions.

We did not say we are redefining the concept of our release numbering
scheme - we just defined what API impacts there were and we used "major"
and "minor" about *release efforts and impacts* - not about changing the
definition of the parts of the OPENSSL_VERSION_NUMBER macro and the
corresponding meaning of what SSLeay_version_num() and now
OpenSSL_version_num() returns. This is a core part of our API.

Remember that SSLeay_version_num() was only renamed OpenSSL_version_num()
in 2015 in commit b0700d2c8de79252ba605748a075cf2e5d670da1
<https://github.com/openssl/openssl/commit/b0700d2c8de79252ba605748a075cf2e5d670da1>
as part of 1.1.0
The first update for the top nibble indicating the major version number had
changed was back in 2009 in commit 093f5d2c152489dd7733dcbb68cbf654988a496c
<https://github.com/openssl/openssl/commit/093f5d2c152489dd7733dcbb68cbf654988a496c>
which
is when 1.0.0 started.

Saying that our documentation in doc/crypto/OPENSSL_VERSION_NUMBER.pod
<https://github.com/openssl/openssl/blob/master/doc/man3/OPENSSL_VERSION_NUMBER.pod>
was just forgotten to be updated and happens to be wrong (in order to
support that view point) isn't matched by the actual update history - it
was updated in 2014 in commit 9208640a36228b10fcdf75c8853d9410aaff19a3
<https://github.com/openssl/openssl/commit/9208640a36228b10fcdf75c8853d9410aaff19a3>
and it actually changed the documentation of what the major version number
encoding is - from the top two nibbles to just the top nibble. If your
assertions about the history were accurate then I would expect to see a
comment there that the top nibble is a meaningless epoch and the major
version is encoded elsewhere. But what was done there was to *bring the
documentation in line with the code comment* and also in line with reality
and what our users perceive things as.

> The 2nd/3rd nibbles in OPENSSL_VERSION_NUMBER are not "the minor version
> number",
> they are just some bits in an ordinal.

Our documentation says otherwise. Our code comments say otherwise. Our
users (I assert) say otherwise.
And your rationale for this in the website statements in their plain
reading also support that - you have to insert "number" in quite a few
places in order to read the context of those posts as meaning we have a
change in the encoding scheme for numbers.
We didn't do that.

So in summary, don't mix major and minor in the sense of the scope of a
change in with the major version number and minor version number - that is
I think where the confusion comes from in terms of your interpretation (and
Richard's proposal).
We did not explicitly disconnect those concepts from their encoding in
OPENSSL_VERSION_NUMBER, we did not redefine what we meant by version.
We also did not say the first two digits are the major version number and
the next digit is the minor version number.

One of those two leaps has to be made to support your view point and I see
no evidence to actually support that without inserting meaning into the release
strategy <https://www.openssl.org/policies/releasestrat.html> that isn't
actually there and conflicts with multiple other sources of information.
Remember our users read the code and sometimes the documentation when using
OpenSSL - a user doesn't go and read our release strategy to see if there
is some wording that happens to have updated meaning.

And for amusement value, I reference the "ultimate source of truth" - our
entry on Wikipedia  <https://en.wikipedia.org/wiki/OpenSSL> which lists our
"major version releases" using the same sort of loose release effort scope
definition with no connection to the major version number.
For wikipedia, all major.minor.fix releases are "major version releases" -
and that I think actually matches our users view point.

Tim.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mta.openssl.org/pipermail/openssl-project/attachments/20180922/59f96460/attachment.html>