Naming conventions

[Richard Levitte]

On Fri, 19 Jun 2020 09:15:22 +0200,
Tomas Mraz wrote:
> The problem is that there is not really fully consistent convention
> followed currently (even in 1.1.1, not counting the API additions in
> 3.0).
> 
> For example if we would like to follow the convention _fully_ we would
> have to rename these new EVP_MAC functions:
> 
> int EVP_MAC_init(EVP_MAC_CTX *ctx);
>       
> int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
>  
> int EVP_MAC_final(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);
> 
> to something like:
> 
> int EVP_MacInit(EVP_MAC_CTX *ctx);
>       
> int EVP_MacUpdate(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
>  
> int EVP_MacFinal(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);
> 
> or at least
> 
> int EVP_MACInit(EVP_MAC_CTX *ctx);
>       
> int EVP_MACUpdate(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
>  
> int EVP_MACFinal(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);

Someone's walking memory lane ;-)
I had to look back at OpenSSL_0_9_1c to remind myself, 'cause today,
we're quite mixed up, what with the slightly lower level functions
EVP_PKEY_sign_init, EVP_PKEY_sign, etc etc etc...

I would say, thought, that if you want to do the higher level function
thing (which are all CamelCase as far as I can see), there's another
naming convention going on, at least with EVP_PKEY, it seems to be
done according to the higher level operation you want to perform, not
the type of data used to do it...  what do you normally to with a MAC? 
So:

int EVP_AuthenticateInit(EVP_MAC_CTX *ctx);
int EVP_AUthenticateUpdate(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
int EVP_AUthenticateFinal(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);

... or something like that.  Quite frankly, a naming convention that
is about the operation rather than the type of any type is something I
could play along with.

> And I actually hope we could add at least non-CamelCase aliases to the
> existing (non-deprecated) CamelCase functions because they were always
> the worst offender of the API consistency.

I agree with you...  but we have to recognise that would be a bigger
remake, and if we do look at just the CamelCase API, it's actually
fairly consistent (turning a blind eye at DigestSign quirkiness when I
say that).

(I suppose that CamelCase was inspired by the time, it was quite
popular in certain circles in the 90's, and got especially popularised
by Microsoft...  and well, there are quite a few Microsoft ideas that
have infiltrated OpenSSL...  need I mention '_ex'?)

Cheers,
Richard

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