[openssl-dev] [openssl.org #4343] master: EC_KEY_priv2buf (): check parameter sanity

[Kurt Roeckx]

On Sun, Feb 28, 2016 at 12:17:41PM -0500, Jeffrey Walton wrote:
> On Sun, Feb 28, 2016 at 12:18 AM, Viktor Dukhovni
> <openssl-users at dukhovni.org> wrote:
> >
> >> On Feb 27, 2016, at 7:42 PM, Jeffrey Walton <noloader at gmail.com> wrote:
> >>
> >> Please ensure this is documented somewhere. I'm having trouble finding
> >> information on the new rules.
> >>
> >> There's 15 or 20 years of using capitol and lower case identifiers to
> >> denote public and private APIs with OpenSSL. For example, see
> >> https://marc.info/?l=openssl-users&m=102683340223621 .
> >>
> >> I'm happy to tell folks that no longer applies, but we need to know
> >> what the new rules are is and when the cut-over occured.
> >
> > There are no new *rules*, just new goals I'm promoting in this thread.
> > If it is not documented it is not a fully implemented public interface.
> > The documentation is part of what it takes to be a first-class
> > public interface.  New code must be documented, and patches to
> > existing code should bring the documentation up to date.  In good
> > part because it is hard to know whether a patch is correct when
> > updating undocumented code, and the exercise of documenting it makes
> > one think harder about the requisite semantics.
> >
> > The upper-case lower-case thing is a legacy crutch, that is likely
> > to continue to be adhered to for some time, but increasingly it is
> > the documentation that must delineate between public and internal
> > interfaces.
> 
> Thanks Viktor.
> 
> Here's the practical problem I am trying to solve. Its a policy and
> procedure problem.
> 
> Suppose an organization has a rule that says, "no private APIs shall
> be used". How do I tell an organization to differentiate between
> public and private APIs to ensure compliance with the policy? What do
> I tell QA to verify compliance with the policy?
> 
> In the past, we knew from the upper-case lower-case thing. I'm
> guessing that held until OpenSSL 1.0.2. I'm also guessing that's is
> going to change at 1.1.x.
> 
> What do we use now? What are the actionable items or prescriptive
> items we can pivot on?

Those that are in the public headers files are the ones that are
(probably) meant to be public.  They also end up in the .num files
and are now the only exported functions on platforms that support
that.

But before you use those functions that are meant to be public
check that they are actually documented.  If they're not
documented, try to get them documented before you use them.  If
you already use them but they're not documented, try to get them
documented or avoid using them.


Kurt