Naming conventions

[Richard Levitte]

On Thu, 18 Jun 2020 12:36:52 +0200,
Matt Caswell wrote:
> 
> EVP_MAC_CTX_new -> EVP_MAC_new_ctx
> EVP_MAC_CTX_free -> EVP_MAC_free_ctx
> EVP_MAC_CTX_dup -> EVP_MAC_dup_ctx
> EVP_MAC_CTX_mac -> EVP_MAC_get_ctx_mac
> EVP_MAC_CTX_get_params -> EVP_MAC_get_ctx_params
> EVP_MAC_CTX_set_params -> EVP_MAC_set_ctx_params
> 
> There are similar renamings for the KDF APIs.
> 
> I am opposed to this renaming on the basis that it is inconsistent with
> what we do elsewhere.

Okie, if we're going to start this discussion with taking a stand, I
guess I'll declare that while I initially had the exact same concern,
I now see this change in a positive light.  This comment from #11997
got me to change my mind:

    The already established patterns is a furphy. I'll reword it more
    precisely: we've done things badly in the past, thus we should do
    them badly moving forwards. We've always been at war with
    Eurasia.....oh wrong context, it's Eastasia.

Ref: https://github.com/openssl/openssl/pull/11997#issuecomment-636658901

For historical background, changing the function name pattern isn't a
new discussion, it's even been brought up on this list more than a
year ago: https://mta.openssl.org/pipermail/openssl-project/2019-March/001280.html
Unfortunately, those discussion never got much traction.  I'm not at
all surprised that #11996 and #11997 came to be, it follows a fairly
human pattern that when talking leads nowhere and someone is still
engaged enough, action will happen.

When it comes to EVP_MAC and EVP_KDF, those sub-APIs already break
with existing patterns, albeit more subtly.  They have a _dup
function, where previous sub-APIs have a _copy function.  But that's
perhaps small enough to be acceptable.

> For example, except for the MAC/KDF APIs I see
> there are 26 functions of the form:
> 
> FOO_CTX_new
> 
> The case is similar for FOO_CTX_free. Aside from the newly introduced
> MAC/KDF names there are no other instances of FOO_new_ctx or
> FOO_free_ctx. This is totally inconsistent and, IMO, will cause
> significant confusion for our users.

Sure, but it counters the confusion with when to use FOO and when to
use FOO_CTX as a prefix.  You and I seem to be pretty clear on this,
but I've seen enough questions on the matter to see the benefit with
this change, even though it breaks the old pattern.

> "If we want to change the naming conventions then we should do so only
> after agreeing what those conventions should be, and agreeing a strategy
> for how we are going to apply them. It should not be done piecemeal (and
> hidden away in a PR that supposedly made things more consistent but in
> reality did the opposite)."

I agree that it would have been good to discuss it further first.
However, those discussion have been met with utter silence before, so
that wasn't very fruitful.  I guess that #11996 and #11997 was enough
of a slap to wake us up.

As for not doing something piecemeal, I actually disagree, I see
benefit in more than just one person getting their hands dirty (plus
changing everything in one go may be overwhelming, and would make for
another huge PR that takes overly much time to get through).  However,
as strategies go, and if we agree on making the change, we could very
well create an issue for each affected sub-API and have it point at a
common page that describes what we agreed upon...  this could be a
good use of the github wiki tab, for example.

> There *are* inconsistencies and quirks in our current naming
> conventions. I am skeptical that now is the time to resolve them given
> the number of other changes we are already introducing into 3.0.

When do you see that time being, then?  3.1 (we've talked about it
being a "cleanup" release)?  4.0?

Each choice has its pros and cons:

- Pros for 3.1: we get the added API variants out fairly early.
- Cons for 3.1: because of ABI compatibility concerns, the old
  functions will have to be preserved as is and the new will have to
  be implemented as macros or new functions, making for a bigger
  libcrypto.num.

- Pros for 4.0: ABI concerns aren't a factor, so the old functions can
  be renamed, and we can preserve the old names as macros.  No need
  for double entries in libcrypto.num.
- Cons for 4.0: Booooy that's far away, which means that we solidify
  the old pattern even more before remaking it.


Side note: if we get through a rename fest, can we get rid of
CamelCase?

Cheers,
Richard

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