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 levi...@openssl.org OpenSSL Project http://www.openssl.org/~levitte/