Clarify ambiguity in security properties (section 6.3 DISCUSS from Roman Danyliw)

[britram]

For security properties in section 6.3:

• Define the highest usable level of abstraction for these parameters
• Reiterate the principle that the exact set of values for available enumerations and the exact data formats for each security parameter are platform-dependent.

[britram]

from email discussion with Roman:

I do think we need to make some changes to the doc to address these points.
I’d suggest the following:

• Define the highest usable level of abstraction for these parameters
• Reiterate the principle that the exact set of values for available enumerations
  and the exact data formats for each security parameter are platform-
  dependent.

If this would be an acceptable resolution to the DISCUSS, I’ll file the issue and
put together the PR.

The above plan makes sense. Thanks for laying out. I would also recommend that the text calibrate the expectations of an "abstract API" and degree of expected interoperability. Inspirationally, the abstract notes that this API is "intended to replace the BSD sockets API as the common interface to the transport layer, in an environment where endpoints could select from multiple interfaces and potential transport protocols." That's a very helpful touchstone. If I squint at the BSD socket API, I see two key differences from what's presented in the current text. Because one could read the .h file, the BSD sockets interface was clear on:

(a) data structures and data types. This draft introduces complicated abstractions with limited definition or underlying representation (e.g., "identity", "ciphersuite"). Additionally, there is no sense of where enumerated values would come from.

(b) function prototypes. This draft has illustrative examples of pseudo-code, but the canonical list of functions and their associated prototypes isn't clear.

Per the goals you outlined in (1) and (2) above, it is clear how this ambiguity serves goals (1), but it seems to impede (2).

[britram]

the rest of my bit of the email:

This is an artifact of trying to balance between two sometimes-opposing goals with the TAPS interface work:

(1) The interface specification has to be malleable enough to fit with the existing “built environment” of the platforms that will implement it; concepts that are ancillary to a transport services implementation should be left undefined so that system implementors can build TAPS into their platforms without completely changing how the platform works. IOW we’re not going to define your PKI for you, or your interfaces for managing protocol selection policy, because you should already have these things, because it’s not useful for the purposes of application interoperability to do so, and because we need to set the boundaries of scope somewhere if we want to be done in the ‘20s.

(2) The interface specification has to be rigid enough to be usefully interoperable; i.e., two different applications of TAPS on the same platform using the interface in the same way should result in indistinguishably-equivalent communications, while an application using TAPS on one platform that is minimally ported to a different platform should result in unsurprisingly-equivalent communications (the distinction here being that different Transport Services system implementations might differ in meaningful-to-the-platform ways, i.e. in terms of the policy priorities in racing or indeed in the set of underlying stacks implemented).

Basically what we’re doing here is guessing (educatedly, but still) about the minimum-interference shape with how existing systems do X (in this case, security property management), under the assumption that these platforms get it right. I think we got this balance mostly right everywhere, but security is the hardest place to do so, precisely because of the rigidity and the formality required in the security space pushes toward an imbalance on the latter.

All of that said, to the details:

A few examples of this ambiguity:

“SecurityParameters.Set(identity, myIdentity)”: What is the “identity”
parameter? What would be passed here?

This is intended as an abstraction around the entire set of information needed to identify and authenticate an endpoint — the server or client certificate (chain) as well as the associated keys.

Per “SecurityParameters.Set(server-certificate, myCertificate)” and
“SecurityParameters.Set(client-certificate, myCertificate)”, assuming
myCertificate is an X.509 certificate, what format would that be passed in
(e.g., PEM, DER)?

This is explicitly left undefined (see point 1 above).

What is in “myCertficate”:

Excellent question.

can it be a certificate chain?

Almost certainly, in that I can’t think of an implementation of this interface that would forbid chains being useful. Let’s say yes.

in the case of client-auth or a server, is this a bundle with both an X.509
and a private key?

Bundle would be most useful. Which actually makes “myCertificate” (which itself encapsulates an identity) the same thing as identity above. i.e. here I think you found a point where we changed the level of abstraction in the middle of the document.

The parameters “supported-group”, “ciphersuite” and “signature-algorithm”
all appear to be enumerated values. Where do those come from?

From the groups, ciphers, and signatures supported by the platform, with the enumerations they already support.