Subject: RE: pseudo-code vs narative in specifications

From: Yaakov Stein <[email-masked]>
Date: Wed, 1 Aug 2018 08:19:00 +0000

If real (non-pseudo) code is authoritative, and this code is readable and well commented,  
then text is not only unnecessary, it is distracting.

This raises the issue of a slippery slope between the IETF being a standards organization and its becoming an Open Source community.

Y(J)S

-----Original Message-----
From: WGChairs [mailto:[email-masked]] On Behalf Of Michael Richardson
Sent: יום ג 31 יולי 2018 23:24
To: WG Chairs <[email-masked]>
Subject: pseudo-code vs narative in specifications

When a specification has pseudo-code, there is sometimes a desire to have a narative.  This leads to the question of which is authoritative, and how to validate the "as-read" narative.

Are there some examples that have worked out well that you are aware of that we can follow the structure of?

This relates to https://datatracker.ietf.org/doc/draft-ietf-cellar-ffv1/

RFC6716 https://tools.ietf.org/html/rfc6716 has specified that the source code is authoritative, but this has been not well received.

--
Michael Richardson <[email-masked]>, Sandelman Software Works  -= IPv6 IoT consulting =-

---

From: "John G. Scudder" <[email-masked]>
Date: Wed, 1 Aug 2018 11:46:30 +0300

On Jul 31, 2018, at 11:37 PM, Job Snijders <[email-masked]> wrote:
> 
> The pseudo code here is an example that has led to considerable debate and confusion in the operator community 
> https://tools.ietf.org/html/rfc6811#section-2.1

Did the accompanying text not help?

“The following pseudo-code illustrates the procedure above. In case
of ambiguity, the procedure above, rather than the pseudo-code, should be taken as authoritative.”

—John

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 1 Aug 2018 11:11:01 +0200

> of ambiguity, the procedure above, rather than the pseudo-code, should be taken as authoritative.”

I read this as “If the text is ambiguous, use the text and not the code”.
Not sure this is what you mean :-)
Code is actually quite useful to resolve the unavoidable ambiguities in the text.

But I think you really wanted to address contradictions/inconsistencies/disagreements/mismatches between the two, not ambiguity in either.

(Which does not always help, because the disagreement may be ambiguous.)

Grüße, Carsten

---

From: Job Snijders <[email-masked]>
Date: Wed, 1 Aug 2018 17:38:37 +0200

On Wed, Aug 01, 2018 at 11:46:30AM +0300, John G. Scudder wrote:
> > The pseudo code here is an example that has led to considerable
> > debate and confusion in the operator community 
> “The following pseudo-code illustrates the procedure above. In case of
> ambiguity, the procedure above, rather than the pseudo-code, should be
> taken as authoritative.”

Not entirely. The procedure text was accompanied with the pseudo-code to
help illustrate/clarify. If one of the two leads to confusion, both
components suffer a bit.

Kind regards,

Job

---

From: Tim Hollebeek <[email-masked]>
Date: Wed, 1 Aug 2018 21:36:30 +0000

Different SDO, but I wrote the python code for ANSI ASC X9.24 part 3, AES DUKPT:

https://x9.org/standards/x9-24-part-3-test-vectors/

The standard itself had pseudocode.  It worked out relatively well having both.  If you look at them side by side, there’s a pretty straightforward correspondence.

The python has the advantage that it can be executed and can recreate the test vectors on the fly as the standard evolves.

The pseudocode had the advantage of being slightly simpler syntactically, and not having to deal with various I/O issues, and quirks of python syntax.  It also used mathematical syntax for various crypto operations, which is friendlier to cryptographers who don’t know python.

It was pretty easy to keep both versions in sync because python is so syntactically close to being pseudocode.

-Tim

From: WGChairs <[email-masked]> On Behalf Of John G. Scudder
Sent: Wednesday, August 1, 2018 4:47 AM
To: Job Snijders <[email-masked]>
Cc: Michael Richardson <[email-masked]>; WG Chairs <[email-masked]>
Subject: Re: pseudo-code vs narative in specifications

On Jul 31, 2018, at 11:37 PM, Job Snijders <[email-masked] <mailto:[email-masked]> > wrote:

—John

---

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 2 Aug 2018 08:34:05 -0500

FWIW, I did put real code into RFC7546 (and the actual code that I ran for
testing is at https://github.com/kaduk/gssdoc/blob/master/gss-sample.c).
But I don't know that we've gotten much feedback yet on that one as to
whether it should be considered as "working well".

-Ben

---

From: Eliot Lear <[email-masked]>
Date: Thu, 2 Aug 2018 15:57:59 +0200

> This raises the issue of a slippery slope between the IETF being a standards organization and its becoming an Open Source community.

It also raises a serious security concern around monocultures.  Let's
not forget the Morris worm, how far it traveled, and what stopped it
from going further.

Eliot

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Thu, 2 Aug 2018 14:57:49 +0000

In other orgs, I have made the results or output of pseudo-code or logic diagrams normative, but not the exact pseudo-code/flow.
As long as something external to the code sees behavior consistent with what is expected, that should be sufficient.

Example of language used: "... MUST execute logic that achieves the same results as ..."

> > If real (non-pseudo) code is authoritative, and this code is readable
> > and well commented, then text is not only unnecessary, it is distracting.

I agree with this statement and that desired logical outcomes are much easier to express and understand through the use of pseudo-code or logic diagrams. But the focus really needs to be on requiring the same outcome or results, and not the requiring identical form or flow. It's all in the language used to make it normative.

Barbara

---

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 2 Aug 2018 10:21:35 -0500

> I agree with this statement and that desired logical outcomes are much easier to express and understand through the use of pseudo-code or logic diagrams. But the focus really needs to be on requiri…

In this vein, we recently had some extended discussions in openssl that
spilled over to the TLS list, that were effectively about whether the spec
mandated a certain processing order from implementations (the question was
about which alert code to use for an error condition).  The conclusion is
effectively that TLS does not specify implementation behavior at that level
of precision, though I suppose that property does not need to be
universally true of all protocols.

-Ben