Proposal for a libcrypto module style guide / policy

2020-09-28 Thread Richard Levitte
The code style proposal that we had before didn't fare well and was
deemed incomplete or contradictory.  Still, we need something for a
more overall view on how we should design an new API as well as how we
should treat existing APIs.

Here's a proposal for something that I/we hope have grasped all the
diverse feedback that's come our way and can become a good enough
guide.

I currently have it as a separate file, and not committed anywhere,
because I wasn't sure where it should end up, and need ideas.
Something to be noted is the current coding style policy doesn't
have a natural space for higher level items such as whole APIs (as
opposed to individual functions) or modules.  My proposal would be to
have a separate document for API / module design (the name of the
attached text is a possible name).

Ideas, thoughts, constructive criticism, acclamations, etc welcome.

Cheers,
Richard

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

OpenSSL modules
===

A module in the sense described here is a part of OpenSSL functionality, in
particular in libcrypto, not a dynamically loadable module.

A module is recognised by its upper case beginning of public function names.
For example, "RAND_bytes" is a function in the RAND module.

In the rest of this text, '{NAME}' is used to represent the module name.

For working with entire modules, we have three cases to consider:

1.  Existing modules
2.  New modules
3.  Function arguments in new modules

[
  note: there are core "modules" as well, which aren't quite the same.
  CRYPTO and OSSL_PROVIDER come to mind.
]

Existing modules


>From time to time it is necessary to extend an existing module with new
functions.  To make such functions consistent with the API of that module,
look at similar or related functions in the same module, otherwise follow
the general rules for adding functions in a new module as described below.

New modules
===

OpenSSL modules may have different levels of complexity:

1.  Simple
2.  Class
3.  Class, dynamic

Simple
--

The absolutely simplest don't have an associated type, and simply have
functions of this form:

rettype {NAME}_do_something([args])

Otherwise, still fairly simple are those with an associated type that has
the same name as the module, but nothing more:

{NAME} *{NAME}_new([args])
rettype {NAME}_get_something({NAME} *,[args])
rettype {NAME}_set_something({NAME} *,[args])
rettype {NAME}_do_something({NAME} *,[args])
void {NAME}_free({NAME} *)

Class
-

Somewhat more complex modules have multiple backend implementations, much
like C++ classes have virtual methods.  For those, there are two types,
{NAME} and {NAME}_METHOD, where {NAME} holds execution data, while
{NAME}_METHOD holds function pointers to a backend implementation.

Such modules should use the following pattern:

{NAME} *{NAME}_new({NAME}_METHOD *, [args])
rettype {NAME}_get_something({NAME} *,[args])
rettype {NAME}_set_something({NAME} *,[args])
rettype {NAME}_do_something({NAME} *,[args])
void {NAME}_free({NAME} *)

Class, dynamic
--

Some more complex modules are also dynamic, in that they get their
implementation from diverse places, and referring to those implementations
isn't as simple as using a method structure pointer directly.  It's often
more suitable that the constructor finds the method structure implicitly,
from a given implementation name or an object that can be used to derive a
suitable name from.

The constructor for such a module typically relies on a factory pool, such
as OPENSSL_CTX (OPENSSL_CTX is a bag of diverse core library things, and is
generally seen as the libcrypto library state.  With constructors, it is
used in the role of a factory pool).

The constructor pattern should look like this:

{NAME} *{NAME}_new(OPENSSL_CTX *libctx, const char *name, [args])
{NAME} *{NAME}_new(OPENSSL_CTX *libctx, OBJTYPE *object, [args])

The first variant is a straightforward construct by name, the second would
rather derive the name from another related type.

The rest of such a module's API should like as in "Class" above.

Function arguments in new modules
=

For all of the above patterns, the remaining argument list (seen as '[args]'
above) should be put into order of importance. Deciding the relative
importance of arguments is necessarily somewhat subjective, but the
following guideline ordering of the arguments should be considered:

1)  additional context arguments

If multiple contexts are necessary then they should be in order of most
general to most specific. In some cases (typically with an OPENSSL_CTX),
a context may be NULL to indicate a default context should be used.

[ This should be *very* rare ]

2)  Data transfer parameters (these are parameters used to convert or copy
some sort of input data to some kind of output 

Re: Add 'OpenSSL Technical Policies' page to openssl.org?

2020-09-28 Thread Matt Caswell
Works for me.

Matt

On 28/09/2020 16:53, Dr. Matthias St. Pierre wrote:
> Hi,
> 
> Pauli added the following action item for me to the OTC vF2F spreadsheet:
> 
>> Matthias: create web PR for OTC voting policy.
> 
> I wouldn't mind to add the content, but currently there seems to be no
> appropriate place yet to put it. The voting process is currently described
> only in the OMC bylaws,
> 
>OpenSSL Bylaws
>openssl/web:policies/omc-bylaws.html
> 
> and there is no specific document for implementary regulations, or more 
> generally,
> technical policies decided by the OTC.  The web page needs a name and an URL,
> something like
> 
> OpenSSL Technical Policies
> openssl/web:policies/otc-policies.html
> 
> and it needs to be referenced by the Policies page 
> .
> If you agree with the name and URL, I can add that part to the web PR as well.
> 
> Matthias
> 
> 


Add 'OpenSSL Technical Policies' page to openssl.org?

2020-09-28 Thread Dr. Matthias St. Pierre
Hi,

Pauli added the following action item for me to the OTC vF2F spreadsheet:

> Matthias: create web PR for OTC voting policy.

I wouldn't mind to add the content, but currently there seems to be no
appropriate place yet to put it. The voting process is currently described
only in the OMC bylaws,

   OpenSSL Bylaws
   openssl/web:policies/omc-bylaws.html

and there is no specific document for implementary regulations, or more 
generally,
technical policies decided by the OTC.  The web page needs a name and an URL,
something like

OpenSSL Technical Policies
openssl/web:policies/otc-policies.html

and it needs to be referenced by the Policies page 
.
If you agree with the name and URL, I can add that part to the web PR as well.

Matthias




RE: VOTE: Accept the OTC voting policy as defined:

2020-09-28 Thread Dr. Matthias St. Pierre
Now with the votes already cast filled in :-)

topic: Accept the OTC voting policy as defined:

   The proposer of a vote is ultimately responsible for updating the 
votes.txt
   file in the repository.  Outside of a face to face meeting, voters MUST 
reply
   to the vote email indicating their preference and optionally their 
reasoning.
   Voters MAY update the votes.txt file in addition.

   The proposed vote text SHOULD be raised for discussion before calling 
the vote.

   Public votes MUST be called on the project list, not the OTC list and the
   subject MUST begin with "VOTE:".  Private votes MUST be called on the
   OTC list with "PRIVATE VOTE:" beginning subject.

Proposed by Matthias St. Pierre (on behalf of the OTC)
Public: yes
opened: 2020-09-28
closed: 2020-mm-dd
accepted:  yes/no  (for: X, against: Y, abstained: Z, not voted: T)

  Matt   [+1]
  Mark   [+1]
  Pauli  [+1]
  Viktor [  ]
  Tim[+1]
  Richard[+1]
  Shane  [+1]
  Tomas  [+1]
  Kurt   [  ]
  Matthias   [+1]
  Nicola [+1]

From: openssl-project  On Behalf Of Dr. 
Matthias St. Pierre
Sent: Monday, September 28, 2020 2:17 PM
To: Dr Paul Dale ; Nicola Tuveri (nic@gmail.com) 
; openssl-project@openssl.org
Subject: RE: VOTE: Accept the OTC voting policy as defined:

Oh, sorry, you are right! The participants of the face to face already voted, 
but I forgot to fill in the votes. Apologies, I'll make up for it in a minute!

Matthias


From: openssl-project 
mailto:openssl-project-boun...@openssl.org>>
 On Behalf Of Dr Paul Dale
Sent: Monday, September 28, 2020 2:10 PM
To: openssl-project@openssl.org
Subject: Re: VOTE: Accept the OTC voting policy as defined:

+1

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





On 28 Sep 2020, at 10:02 pm, Dr. Matthias St. Pierre 
mailto:matthias.st.pie...@ncp-e.com>> wrote:

topic: Accept the OTC voting policy as defined:

  The proposer of a vote is ultimately responsible for updating the 
votes.txt
  file in the repository.  Outside of a face to face meeting, voters MUST 
reply
  to the vote email indicating their preference and optionally their 
reasoning.
  Voters MAY update the votes.txt file in addition.

  The proposed vote text SHOULD be raised for discussion before calling the 
vote.

  Public votes MUST be called on the project list, not the OTC list and the
  subject MUST begin with "VOTE:".  Private votes MUST be called on the
  OTC list with "PRIVATE VOTE:" beginning subject.

Proposed by Matthias St. Pierre (on behalf of the OTC)
Public: yes
opened: 2020-09-28
closed: 2020-mm-dd
accepted:  yes/no  (for: X, against: Y, abstained: Z, not voted: T)

 Matt   [  ]
 Mark   [  ]
 Pauli  [  ]
 Viktor [  ]
 Tim[  ]
 Richard[  ]
 Shane  [  ]
 Tomas  [  ]
 Kurt   [  ]
 Matthias   [+1]
 Nicola [  ]



RE: VOTE: Accept the OTC voting policy as defined:

2020-09-28 Thread Dr. Matthias St. Pierre
Oh, sorry, you are right! The participants of the face to face already voted, 
but I forgot to fill in the votes. Apologies, I'll make up for it in a minute!

Matthias


From: openssl-project  On Behalf Of Dr 
Paul Dale
Sent: Monday, September 28, 2020 2:10 PM
To: openssl-project@openssl.org
Subject: Re: VOTE: Accept the OTC voting policy as defined:

+1

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





On 28 Sep 2020, at 10:02 pm, Dr. Matthias St. Pierre 
mailto:matthias.st.pie...@ncp-e.com>> wrote:

topic: Accept the OTC voting policy as defined:

  The proposer of a vote is ultimately responsible for updating the 
votes.txt
  file in the repository.  Outside of a face to face meeting, voters MUST 
reply
  to the vote email indicating their preference and optionally their 
reasoning.
  Voters MAY update the votes.txt file in addition.

  The proposed vote text SHOULD be raised for discussion before calling the 
vote.

  Public votes MUST be called on the project list, not the OTC list and the
  subject MUST begin with "VOTE:".  Private votes MUST be called on the
  OTC list with "PRIVATE VOTE:" beginning subject.

Proposed by Matthias St. Pierre (on behalf of the OTC)
Public: yes
opened: 2020-09-28
closed: 2020-mm-dd
accepted:  yes/no  (for: X, against: Y, abstained: Z, not voted: T)

 Matt   [  ]
 Mark   [  ]
 Pauli  [  ]
 Viktor [  ]
 Tim[  ]
 Richard[  ]
 Shane  [  ]
 Tomas  [  ]
 Kurt   [  ]
 Matthias   [+1]
 Nicola [  ]



Re: VOTE: Accept the OTC voting policy as defined:

2020-09-28 Thread Dr Paul Dale
+1

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




> On 28 Sep 2020, at 10:02 pm, Dr. Matthias St. Pierre 
>  wrote:
> 
> topic: Accept the OTC voting policy as defined:
> 
>   The proposer of a vote is ultimately responsible for updating the 
> votes.txt
>   file in the repository.  Outside of a face to face meeting, voters MUST 
> reply
>   to the vote email indicating their preference and optionally their 
> reasoning.
>   Voters MAY update the votes.txt file in addition.
> 
>   The proposed vote text SHOULD be raised for discussion before calling 
> the vote.
> 
>   Public votes MUST be called on the project list, not the OTC list and 
> the
>   subject MUST begin with "VOTE:".  Private votes MUST be called on the
>   OTC list with "PRIVATE VOTE:" beginning subject.
> 
> Proposed by Matthias St. Pierre (on behalf of the OTC)
> Public: yes
> opened: 2020-09-28
> closed: 2020-mm-dd
> accepted:  yes/no  (for: X, against: Y, abstained: Z, not voted: T)
> 
>  Matt   [  ]
>  Mark   [  ]
>  Pauli  [  ]
>  Viktor [  ]
>  Tim[  ]
>  Richard[  ]
>  Shane  [  ]
>  Tomas  [  ]
>  Kurt   [  ]
>  Matthias   [+1]
>  Nicola [  ]
> 



Re: VOTE: Accept the OTC voting policy as defined:

2020-09-28 Thread Nicola Tuveri
+1, as expressed during the f2f meeting.

Nicola

On Mon, Sep 28, 2020, 15:02 Dr. Matthias St. Pierre <
matthias.st.pie...@ncp-e.com> wrote:

> topic: Accept the OTC voting policy as defined:
>
>The proposer of a vote is ultimately responsible for updating the
> votes.txt
>file in the repository.  Outside of a face to face meeting, voters
> MUST reply
>to the vote email indicating their preference and optionally their
> reasoning.
>Voters MAY update the votes.txt file in addition.
>
>The proposed vote text SHOULD be raised for discussion before
> calling the vote.
>
>Public votes MUST be called on the project list, not the OTC list
> and the
>subject MUST begin with "VOTE:".  Private votes MUST be called on
> the
>OTC list with "PRIVATE VOTE:" beginning subject.
>
> Proposed by Matthias St. Pierre (on behalf of the OTC)
> Public: yes
> opened: 2020-09-28
> closed: 2020-mm-dd
> accepted:  yes/no  (for: X, against: Y, abstained: Z, not voted: T)
>
>   Matt   [  ]
>   Mark   [  ]
>   Pauli  [  ]
>   Viktor [  ]
>   Tim[  ]
>   Richard[  ]
>   Shane  [  ]
>   Tomas  [  ]
>   Kurt   [  ]
>   Matthias   [+1]
>   Nicola [  ]
>
>


VOTE: Accept the OTC voting policy as defined:

2020-09-28 Thread Dr. Matthias St. Pierre
topic: Accept the OTC voting policy as defined:

   The proposer of a vote is ultimately responsible for updating the 
votes.txt
   file in the repository.  Outside of a face to face meeting, voters MUST 
reply
   to the vote email indicating their preference and optionally their 
reasoning.
   Voters MAY update the votes.txt file in addition.

   The proposed vote text SHOULD be raised for discussion before calling 
the vote.

   Public votes MUST be called on the project list, not the OTC list and the
   subject MUST begin with "VOTE:".  Private votes MUST be called on the
   OTC list with "PRIVATE VOTE:" beginning subject.

Proposed by Matthias St. Pierre (on behalf of the OTC)
Public: yes
opened: 2020-09-28
closed: 2020-mm-dd
accepted:  yes/no  (for: X, against: Y, abstained: Z, not voted: T)

  Matt   [  ]
  Mark   [  ]
  Pauli  [  ]
  Viktor [  ]
  Tim[  ]
  Richard[  ]
  Shane  [  ]
  Tomas  [  ]
  Kurt   [  ]
  Matthias   [+1]
  Nicola [  ]