Subject: [Trans] Comments on Section 4

From: Stephen Kent <[email-masked]>
Date: Wed, 02 Jul 2014 10:02:11 -0400

*Section 4*

This section defines the messages sent between clients and logs, thus 
defining the interface to logs.

There is an admonition to ignore fields that may appear in "... JSON 
objects and URL parameters..." that are not specified in this section. 
Ought the "should" be a "SHOULD" or a "MUST"?

The texts says "The <log server> prefix can include a path as well as a 
server name and a port." Should the "can" become a "MAY"?

Since human-readable error messages are to be returned, is the intent 
that people will need to deal with these errors? Shouldn't there be an 
enumerated list of errors for each operation, to enable client software 
to figure out what the log server didn't like about a request, without 
requiring human intervention? Creating a list of errors for each type of 
transaction would make the checks performed by a log server more 
obvious, a concern I note below.

The introduction for this section should note the unusual convention 
adopted here, i.e., putting a version number into the URL for the POST, 
as a way of indicating what version of a data structure is being 
submitted/retrieved. This does mean that a log client has to track this 
information when maintaining a returned data structure, since it is not 
embedded in the structure per se. It would be useful to describe the 
rationale for this design choice, vs. the more conventional approach of 
embedding the version number inthe data structure itself. One could do 
both, to provide redundant means of determining when a server returns 
the one version of a data structure via a URL that indicated a request 
for a different one (or vice versa for a client that is confused).

The subsections of 4 do not specify checks to be performed by the log 
server or the client with respect to message parameters. This seems to 
be an oversight. For example, in 4.1, I would expect the log to verify 
that the certificate chain terminates in one of the TAs it supports, and 
that the certificates do constitute a certificate chain. The text in 4.1 
says what the input is expected to be, but does not indicate that the 
log server actually verifies this.

Why is the log ID base64 encoded?

In *Section 4.1*, it seems a bit odd to specify a base64 extension for 
which no further syntax is defined. Is it defined elsewhere in this 
document?

Is it a good idea for a client to accept an SCT that it cannot parse? If 
the version of the SCT returned to a client is not one a client 
understands, the client has no way of knowing whether a TLS client can 
understand it. This postpones the time when the returned SCT might be 
treated as broken. This doesn't seem like a good idea. It also raises 
the question of how SCT version changes are expected to be coordinated 
among logs, log clients, TLS clients, Monitors, etc. This architectural 
issue should be addressed somewhere in this document.

In *Section 4.3*, the encoding for the timestamp is not specified here.

Why is the instance of a tree specified by the tree size? If a new STH 
is issued before any new entries are added, the tree size will be the 
same. Would it not be clearer to use a serial number or timestamp tree 
instances?

In *Section 4.4*, there is a note that the two trees must (MUST?) be 
from v1 STHs. This raises the question of how the system deals with a 
request to acquire a consistency proof between two STHs that span a log 
version transition. Please address that issue.

There should be a description of what a log server does to satisfy this 
request, and how it replies if one or both of the specified tree sizes 
do not correspond to the specified tree heads according to its records. 
(This raises the question of whether there might be a preferable way to 
refer to STHs, e.g., via a timestamp or serial number, as noted above.)

In *Section 4.5*, there is another reference to a v1 STH. This raises 
the same sort of questions I noted in my comments on Section 4.4 above. 
The terms "leaf index" and "0-base index" are used, but they do not seem 
to have been defined previously.

In *Section 4.6*, the term "0-based" index is used, as in Section 4.5. 
The v1 vs. later versions issue arises here, as in Sections 4.4 and 
4.5.There does not seem to be enough detail in the description of the 
processing to be performed by the client. Perhaps an appendix is needed 
to provide the details. If a client requests more entries than a log 
operator is willing to return, should there be an explicit error 
indication, rather than just returning the server's max size? Should the 
limit on entries be part of the server information that is retrievable, 
like the list of supported TAs (see Section 4.7).

*Section 4.8*Since the tree_size is required to refer to an existing 
STH, this is an example of where a specific error return could be 
defined, to signal that the supplied input parameter is in error.