Re: API renaming

[Richard Levitte]

Why?  Just because some of us used such variable names when there was
a need to distinguish it from other contexts that are sometimes
juggled with at the time time?

(and yeah, I've made that a habit...  but why that would determine the
type name, I cannot understand)

Cheers,
Richard

On Fri, 24 Jul 2020 09:42:59 +0200,
SHANE LONTIS wrote:
> 
> I was thinking OSSL_LIBCTX?
> 
> > On 24 Jul 2020, at 5:38 pm, Dr. Matthias St. Pierre 
> >  wrote:
> > 
> > I like the OSSL_ prefix for new APIs as proposed by Richard. And I agree 
> > with Shane
> > that we should go for a single prefix and not have two alternatives. 
> > Existing prefixes
> > for things like feature macros should remain as they are, but if the OSSL_ 
> > prefix is
> > our choice for the future, we should start using it consistently for _all_ 
> > new APIs in 3.0.
> > And not make it a random choice (pun intended) depending on whether the API 
> > went
> > into master early or late. So my favorite choice is a consistent renaming, 
> > i.e.
> > 
> > OSSL_MAC, OSSL_KDF, OSSL_RAND, OSSL_CTX, ...
> > 
> > OTOH, it would be ok for me if we would make an exception for EVP_MAC and 
> > EVP_KDF,
> > because they have a long EVP history, as Matt pointed out. But using the 
> > EVP_ prefix
> > for the new RAND interface never made sense to me.
> > 
> > What bothers me about OPENSSL_CTX in particular is the fact that it is a 
> > mixture of
> > a non-abbreviated and an abbreviated word. IMHO it should be either 
> > OSSL_CTX or
> > OPENSSL_CONTEXT, and the former is obviously preferrable for its length.
> > 
> > Matthias
> > 
> > 
> >> -Original Message-
> >> From: openssl-project  On Behalf Of 
> >> Richard Levitte
> >> Sent: Friday, July 24, 2020 8:34 AM
> >> To: openssl-project@openssl.org
> >> Subject: Re: API renaming
> >> 
> >> I'm fine with that, really.
> >> 
> >> I have a preference for OSSL_, but if we look through the source,
> >> there's reason for either.  So far, we've majorly used OPENSSL_ for
> >> things like feature macros (disabling macros, really), environment
> >> variables, that sort of thing, while OSSL_ has become the primary
> >> choice for new APIs ("less klunky", I think the judgement was in that
> >> past discussion I keep referring to).
> >> 
> >> And yeah, I hear you from all the way around the planet, there are
> >> some recent name choice that were made that give pause and are
> >> arguably a mistake in this regard.  EVP_MAC and EVP_KDF could have
> >> been OSSL_MAC and OSSL_KDF.  OPENSSL_CTX could have been OSSL_CTX.
> >> I have no problem recognising that.  But, they are there, even though
> >> only in master (*).  This is question of what we do going forward (a
> >> yet unmerged PR with a new API is as good a target as any).
> >> 
> >> Cheers,
> >> Richard
> >> 
> >> (*) I'm not sure I see master as something untouchable in this regard,
> >> as the development is still not frozen (alpha), so I for one could
> >> easily see a rename fest happening, should we decide for it.  That
> >> must happen before we enter the beta phase, though...
> >> 
> 
-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/

Re: API renaming

[Richard Levitte]

We're talking APIs (*), that includes the types.  So yes, that's a
safe assumption.

Cheers,
Richard

(*) if people stopped using "API" when they mean "function", that
would save the world from a pile of confusion.

On Thu, 23 Jul 2020 18:45:49 +0200,
Short, Todd wrote:
> 
> 
> They also correspond directly to EVP_MAC and EVP_KDF types. Would the types 
> change as well?
> --
> -Todd Short
> // tsh...@akamai.com
> // “One if by land, two if by sea, three if by the Internet."
> 
> On Jul 23, 2020, at 11:56 AM, Matt Caswell  wrote:
> 
> On 23/07/2020 16:52, Richard Levitte wrote:
>
> On Thu, 23 Jul 2020 12:18:10 +0200,
> Dr Paul Dale wrote:
>
> There has been a suggestion to rename EVP_RAND to OSSL_RAND.  
> This seems reasonable.
>  Would it
> also make sense to rename the other new APIs similarly.
> More specifically, EVP_MAC and EVP_KDF to OSSL_MAC and OSSL_KDF 
> respectively?
> 
> This is a good question...
>
> Historically speaking, even though EVP_MAC and EVP_KDF are indeed new
> APIs, they have a previous history of EVP APIs, through EVP_PKEY.  The
> impact of relocating them outside of the EVP "family" may be small,
> but still, history gives me pause.
>
> RAND doesn't carry the same sort of history, which makes it much
> easier for me to think "just do it and get it over with"...
> 
> I have the same pause - so  I'm thinking just RAND for now.
>
> Matt
> 
> 
> No public key for CFC553A2BA1A0ED1 created at 2020-07-23T18:45:49+0200 using 
> RSA
-- 
Richard Levitte levi...@openssl.org
OpenSSL Project http://www.openssl.org/~levitte/

Re: API renaming

[Dr Paul Dale]

I think the types should change to match any function name changes.


Pauli
-- 
Dr Paul Dale | Distinguished Architect | Cryptographic Foundations 
Phone +61 7 3031 7217
Oracle Australia




> On 24 Jul 2020, at 2:45 am, Short, Todd  wrote:
> 
> They also correspond directly to EVP_MAC and EVP_KDF types. Would the types 
> change as well?
> --
> -Todd Short
> // tsh...@akamai.com 
> // “One if by land, two if by sea, three if by the Internet."
> 
>> On Jul 23, 2020, at 11:56 AM, Matt Caswell > > wrote:
>> 
>> 
>> 
>> On 23/07/2020 16:52, Richard Levitte wrote:
>>> On Thu, 23 Jul 2020 12:18:10 +0200,
>>> Dr Paul Dale wrote:
 There has been a suggestion to rename EVP_RAND to OSSL_RAND.  This seems 
 reasonable.  Would it
 also make sense to rename the other new APIs similarly.
 More specifically, EVP_MAC and EVP_KDF to OSSL_MAC and OSSL_KDF 
 respectively?
>>> 
>>> This is a good question...
>>> 
>>> Historically speaking, even though EVP_MAC and EVP_KDF are indeed new
>>> APIs, they have a previous history of EVP APIs, through EVP_PKEY.  The
>>> impact of relocating them outside of the EVP "family" may be small,
>>> but still, history gives me pause.
>>> 
>>> RAND doesn't carry the same sort of history, which makes it much
>>> easier for me to think "just do it and get it over with"...
>> 
>> I have the same pause - so  I'm thinking just RAND for now.
>> 
>> Matt
>> 
> 

Re: API renaming

[Dr Paul Dale]

Adherence to the code style will also be required (indentation will change).  
This will be harder to automate.

Changing EVP_RAND -> OSSL_RAND is worse because it will change line breaks as 
well as indentation.  OSSL_RNG avoids this, if we accept not using RAND in the 
name.
KDF and MAC also get longer and would have the same issue.


Then there are the inevitable merge conflicts….


Pauli
-- 
Dr Paul Dale | Distinguished Architect | Cryptographic Foundations 
Phone +61 7 3031 7217
Oracle Australia




> On 24 Jul 2020, at 6:15 pm, Dr. Matthias St. Pierre 
>  wrote:
> 
>> I was thinking OSSL_LIBCTX?
> 
> That's a good choice and consistent with how we name the variable in most 
> (but not all) places:
> 
>   OPENSSL_CTX *libctx;
> 
> I volunteer to raise a pull request which does a scripted bulk rename, as 
> soon as we have made
> a decision. Ideally, the bulk renaming should go in shortly before the next 
> alpha. Having it
> automated by a script would ease rebasing of other still unmerged pull 
> requests over the change.
> 
> Matthias
> 
>> -Original Message-
>> From: SHANE LONTIS 
>> Sent: Friday, July 24, 2020 9:43 AM
>> To: Dr. Matthias St. Pierre 
>> Cc: Richard Levitte ; openssl-project@openssl.org
>> Subject: Re: API renaming
>> 
>> I was thinking OSSL_LIBCTX?
>> 
> 

RE: API renaming

[Dr. Matthias St. Pierre]

> They also correspond directly to EVP_MAC and EVP_KDF types. Would the types 
> change as well?

Yes, if we would decide to change the EVP_MAC and EVP_KDF prefix, then this 
would not only
apply to the functions, but to the types as well.

Matthias

Re: API renaming

[Short, Todd]

They also correspond directly to EVP_MAC and EVP_KDF types. Would the types 
change as well?
--
-Todd Short
// tsh...@akamai.com
// “One if by land, two if by sea, three if by the Internet."

> On Jul 23, 2020, at 11:56 AM, Matt Caswell  wrote:
> 
> 
> 
> On 23/07/2020 16:52, Richard Levitte wrote:
>> On Thu, 23 Jul 2020 12:18:10 +0200,
>> Dr Paul Dale wrote:
>>> There has been a suggestion to rename EVP_RAND to OSSL_RAND.  This seems 
>>> reasonable.  Would it
>>> also make sense to rename the other new APIs similarly.
>>> More specifically, EVP_MAC and EVP_KDF to OSSL_MAC and OSSL_KDF 
>>> respectively?
>> 
>> This is a good question...
>> 
>> Historically speaking, even though EVP_MAC and EVP_KDF are indeed new
>> APIs, they have a previous history of EVP APIs, through EVP_PKEY.  The
>> impact of relocating them outside of the EVP "family" may be small,
>> but still, history gives me pause.
>> 
>> RAND doesn't carry the same sort of history, which makes it much
>> easier for me to think "just do it and get it over with"...
> 
> I have the same pause - so  I'm thinking just RAND for now.
> 
> Matt
> 



signature.asc
Description: Message signed with OpenPGP

RE: API renaming

[Dr. Matthias St. Pierre]

> I was thinking OSSL_LIBCTX?

That's a good choice and consistent with how we name the variable in most (but 
not all) places:

OPENSSL_CTX *libctx;

I volunteer to raise a pull request which does a scripted bulk rename, as soon 
as we have made
a decision. Ideally, the bulk renaming should go in shortly before the next 
alpha. Having it
automated by a script would ease rebasing of other still unmerged pull requests 
over the change.

Matthias

> -Original Message-
> From: SHANE LONTIS 
> Sent: Friday, July 24, 2020 9:43 AM
> To: Dr. Matthias St. Pierre 
> Cc: Richard Levitte ; openssl-project@openssl.org
> Subject: Re: API renaming
> 
> I was thinking OSSL_LIBCTX?
> 

Re: API renaming

[SHANE LONTIS]

As @levitte pointed out - it was not back ported (not sure why I thought it 
was) 

> On 24 Jul 2020, at 5:40 pm, Dr. Matthias St. Pierre 
>  wrote:
> 
> > I think the KDF and MAC got back ported also...
>  
> In this case it would be no question that we should keep the names EVP_KDF 
> and EVP_MAC.
>  
>  
>Dr. Matthias 
> St. Pierre 
> 
> Senior Software Engineer 
> matthias.st.pie...@ncp-e.com  
> Phone: +49 911 9968-0
> www.ncp-e.com 
> 
> 
> Follow us on: Facebook 
> 
>  | Twitter 
> 
>  | Xing 
> 
>  | YouTube 
> 
>  | LinkedIn 
> 
> 
> Headquarters Germany: NCP engineering GmbH • Dombuehler Str. 2 • 90449 • 
> Nuremberg 
> North American HQ: NCP engineering Inc. • 601 Cleveland Str., Suite 501-25 • 
> Clearwater, FL 33755 
> 
> Authorized representatives: Peter Soell, Patrick Oliver Graf, Beate Dietrich 
> Registry Court: Lower District Court of Nuremberg 
> Commercial register No.: HRB 7786 Nuremberg, VAT identification No.: DE 
> 133557619
> 
> This e-mail message including any attachments is for the sole use of the 
> intended recipient(s) and may contain privileged or confidential information. 
> Any unauthorized review, use, disclosure or distribution is prohibited. If 
> you are not the intended recipient, please immediately contact the sender by 
> reply e-mail and delete the original message and destroy all copies thereof.
> 
> 

Re: API renaming

[SHANE LONTIS]

I was thinking OSSL_LIBCTX?

> On 24 Jul 2020, at 5:38 pm, Dr. Matthias St. Pierre 
>  wrote:
> 
> I like the OSSL_ prefix for new APIs as proposed by Richard. And I agree with 
> Shane
> that we should go for a single prefix and not have two alternatives. Existing 
> prefixes
> for things like feature macros should remain as they are, but if the OSSL_ 
> prefix is
> our choice for the future, we should start using it consistently for _all_ 
> new APIs in 3.0.
> And not make it a random choice (pun intended) depending on whether the API 
> went
> into master early or late. So my favorite choice is a consistent renaming, 
> i.e.
> 
>   OSSL_MAC, OSSL_KDF, OSSL_RAND, OSSL_CTX, ...
> 
> OTOH, it would be ok for me if we would make an exception for EVP_MAC and 
> EVP_KDF,
> because they have a long EVP history, as Matt pointed out. But using the EVP_ 
> prefix
> for the new RAND interface never made sense to me.
> 
> What bothers me about OPENSSL_CTX in particular is the fact that it is a 
> mixture of
> a non-abbreviated and an abbreviated word. IMHO it should be either OSSL_CTX 
> or
> OPENSSL_CONTEXT, and the former is obviously preferrable for its length.
> 
> Matthias
> 
> 
>> -Original Message-
>> From: openssl-project  On Behalf Of 
>> Richard Levitte
>> Sent: Friday, July 24, 2020 8:34 AM
>> To: openssl-project@openssl.org
>> Subject: Re: API renaming
>> 
>> I'm fine with that, really.
>> 
>> I have a preference for OSSL_, but if we look through the source,
>> there's reason for either.  So far, we've majorly used OPENSSL_ for
>> things like feature macros (disabling macros, really), environment
>> variables, that sort of thing, while OSSL_ has become the primary
>> choice for new APIs ("less klunky", I think the judgement was in that
>> past discussion I keep referring to).
>> 
>> And yeah, I hear you from all the way around the planet, there are
>> some recent name choice that were made that give pause and are
>> arguably a mistake in this regard.  EVP_MAC and EVP_KDF could have
>> been OSSL_MAC and OSSL_KDF.  OPENSSL_CTX could have been OSSL_CTX.
>> I have no problem recognising that.  But, they are there, even though
>> only in master (*).  This is question of what we do going forward (a
>> yet unmerged PR with a new API is as good a target as any).
>> 
>> Cheers,
>> Richard
>> 
>> (*) I'm not sure I see master as something untouchable in this regard,
>> as the development is still not frozen (alpha), so I for one could
>> easily see a rename fest happening, should we decide for it.  That
>> must happen before we enter the beta phase, though...
>> 

RE: API renaming

[Dr. Matthias St. Pierre]

> I think the KDF and MAC got back ported also...

In this case it would be no question that we should keep the names EVP_KDF and 
EVP_MAC.

RE: API renaming

[Dr. Matthias St. Pierre]

I like the OSSL_ prefix for new APIs as proposed by Richard. And I agree with 
Shane
that we should go for a single prefix and not have two alternatives. Existing 
prefixes
for things like feature macros should remain as they are, but if the OSSL_ 
prefix is
our choice for the future, we should start using it consistently for _all_ new 
APIs in 3.0.
And not make it a random choice (pun intended) depending on whether the API went
into master early or late. So my favorite choice is a consistent renaming, i.e.

OSSL_MAC, OSSL_KDF, OSSL_RAND, OSSL_CTX, ...

OTOH, it would be ok for me if we would make an exception for EVP_MAC and 
EVP_KDF,
because they have a long EVP history, as Matt pointed out. But using the EVP_ 
prefix
for the new RAND interface never made sense to me.

What bothers me about OPENSSL_CTX in particular is the fact that it is a 
mixture of
a non-abbreviated and an abbreviated word. IMHO it should be either OSSL_CTX or
OPENSSL_CONTEXT, and the former is obviously preferrable for its length.

Matthias


> -Original Message-
> From: openssl-project  On Behalf Of 
> Richard Levitte
> Sent: Friday, July 24, 2020 8:34 AM
> To: openssl-project@openssl.org
> Subject: Re: API renaming
> 
> I'm fine with that, really.
> 
> I have a preference for OSSL_, but if we look through the source,
> there's reason for either.  So far, we've majorly used OPENSSL_ for
> things like feature macros (disabling macros, really), environment
> variables, that sort of thing, while OSSL_ has become the primary
> choice for new APIs ("less klunky", I think the judgement was in that
> past discussion I keep referring to).
> 
> And yeah, I hear you from all the way around the planet, there are
> some recent name choice that were made that give pause and are
> arguably a mistake in this regard.  EVP_MAC and EVP_KDF could have
> been OSSL_MAC and OSSL_KDF.  OPENSSL_CTX could have been OSSL_CTX.
> I have no problem recognising that.  But, they are there, even though
> only in master (*).  This is question of what we do going forward (a
> yet unmerged PR with a new API is as good a target as any).
> 
> Cheers,
> Richard
> 
> (*) I'm not sure I see master as something untouchable in this regard,
> as the development is still not frozen (alpha), so I for one could
> easily see a rename fest happening, should we decide for it.  That
> must happen before we enter the beta phase, though...
>