RFC6962-bis: Tree and leaf versioning

RFC6962-bis: Tree and leaf versioning.
Since we've added the extensions field to the STH, we need to increase its version. Might as well create a separate versioning scheme for it and the tree leaves so each can be changed independently.

[Rob Stradling, 2014-05-09 11:01:06]

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml
File doc/rfc6962-bis.xml (right):

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml#newcode717
doc/rfc6962-bis.xml:717: Here, <spanx style="verb">version</spanx> is the
version of the protocol to which the MerkleTreeLeaf corresponds. This version is
v1.
I think "v1...of the protocol" is unclear.  What is "the protocol"?  Is it
RFC6962 in its entirety?
I suggest that we scrap "of the protocol" now that we're using different
versioning schemes for different data structures.

How about...
"...</spanx> is the version of the MerkleTreeLeaf structure. This version is
v1."

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml#newcode760
doc/rfc6962-bis.xml:760: which the TreeHeadSignature conforms. This version is
v2.
Again, I think "of the protocol" no longer seems clear.  I suggest:
"...</spanx> is the version of the TreeHeadSignature structure. This version is
v2."

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml#newcode772
doc/rfc6962-bis.xml:772: <spanx style="verb">extensions</spanx> are future
extensions to this protocol version (v2). Currently, no extensions are
specified. Note that the v1 of the Signed Tree Head, as defined in <xref
target="RFC6962">RFC 6962</xref>, does not include this field.
Again, I think v2 is the data structure's version, not the "protocol version".

How about...
'...</spanx> are future extensions to TreeHeadSignature v2. Currently, no
extensions are specified. Note that <xref target="RFC6962">TreeHeadSignature
v1</xref> does not include this field.'

Perhaps it would also be worth mentioning that the point of the extensions field
is to make it possible to add new/optional fields without having to bump the
TreeHeadSignature version number each time.

[Eran, 2014-05-09 12:43:47]

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml
File doc/rfc6962-bis.xml (right):

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml#newcode717
doc/rfc6962-bis.xml:717: Here, <spanx style="verb">version</spanx> is the
version of the protocol to which the MerkleTreeLeaf corresponds. This version is
v1.
On 2014/05/09 11:01:05, Rob Stradling wrote:
> I think "v1...of the protocol" is unclear.  What is "the protocol"?  Is it
> RFC6962 in its entirety?
> I suggest that we scrap "of the protocol" now that we're using different
> versioning schemes for different data structures.
> 
> How about...
> "...</spanx> is the version of the MerkleTreeLeaf structure. This version is
> v1."

Done. Good point, since we now version each structure independently of others.

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml#newcode760
doc/rfc6962-bis.xml:760: which the TreeHeadSignature conforms. This version is
v2.
On 2014/05/09 11:01:05, Rob Stradling wrote:
> Again, I think "of the protocol" no longer seems clear.  I suggest:
> "...</spanx> is the version of the TreeHeadSignature structure. This version
is
> v2."

Done.

https://codereview.appspot.com/95150044/diff/1/doc/rfc6962-bis.xml#newcode772
doc/rfc6962-bis.xml:772: <spanx style="verb">extensions</spanx> are future
extensions to this protocol version (v2). Currently, no extensions are
specified. Note that the v1 of the Signed Tree Head, as defined in <xref
target="RFC6962">RFC 6962</xref>, does not include this field.
On 2014/05/09 11:01:05, Rob Stradling wrote:
> Again, I think v2 is the data structure's version, not the "protocol version".
> 
> How about...
> '...</spanx> are future extensions to TreeHeadSignature v2. Currently, no
> extensions are specified. Note that <xref target="RFC6962">TreeHeadSignature
> v1</xref> does not include this field.'
> 
Done

> Perhaps it would also be worth mentioning that the point of the extensions
field
> is to make it possible to add new/optional fields without having to bump the
> TreeHeadSignature version number each time.

Done.

[Rob Stradling, 2014-05-12 12:53:54]

https://codereview.appspot.com/95150044/diff/20001/doc/rfc6962-bis.xml
File doc/rfc6962-bis.xml (right):

https://codereview.appspot.com/95150044/diff/20001/doc/rfc6962-bis.xml#newcod...
doc/rfc6962-bis.xml:759: <spanx style="verb">version</spanx> is the version of
the TreeHeadSignature signature. This version is v2.
s/signature/structure

https://codereview.appspot.com/95150044/diff/20001/doc/rfc6962-bis.xml#newcod...
doc/rfc6962-bis.xml:771: <spanx style="verb">extensions</spanx> are future
extensions to TreeHeadSignature v2. Currently, no extensions are specified. Note
that <xref target="RFC6962">TreeHeadSignature v1</xref> does not include this
field. The <spanx style="verb">extensions</spanx> field goal is to allow
augmenting the TreeHeadSignature without increasing its version.
"The extensions field goal is..." doesn't quite make sense.

How about "The purpose of this field is..." ?

[Eran, 2014-05-21 16:22:25]

Done, PTAL.

https://codereview.appspot.com/95150044/diff/20001/doc/rfc6962-bis.xml
File doc/rfc6962-bis.xml (right):

https://codereview.appspot.com/95150044/diff/20001/doc/rfc6962-bis.xml#newcod...
doc/rfc6962-bis.xml:759: <spanx style="verb">version</spanx> is the version of
the TreeHeadSignature signature. This version is v2.
On 2014/05/12 12:53:54, Rob Stradling wrote:
> s/signature/structure

Done.

https://codereview.appspot.com/95150044/diff/20001/doc/rfc6962-bis.xml#newcod...
doc/rfc6962-bis.xml:771: <spanx style="verb">extensions</spanx> are future
extensions to TreeHeadSignature v2. Currently, no extensions are specified. Note
that <xref target="RFC6962">TreeHeadSignature v1</xref> does not include this
field. The <spanx style="verb">extensions</spanx> field goal is to allow
augmenting the TreeHeadSignature without increasing its version.
On 2014/05/12 12:53:54, Rob Stradling wrote:
> "The extensions field goal is..." doesn't quite make sense.
> 
> How about "The purpose of this field is..." ?

Done.

[Rob Stradling, 2014-05-23 09:43:24]

LGTM

[Eran, 2014-06-11 12:46:21]

On 2014/05/23 09:43:24, Rob Stradling wrote:
> LGTM

Committed as
https://github.com/google/certificate-transparency-rfcs/commit/5bb9a5487c93f4...