Opened 2 years ago

Closed 2 years ago

#23391 closed enhancement (fixed)

Add changes section to Tor bridge descriptors specification

Reported by: karsten Owned by: metrics-team
Priority: Medium Milestone:
Component: Metrics/Website Version:
Severity: Normal Keywords:
Cc: atagar, iwakeh Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

atagar suggest on tor-project@ to add a changes section to our new Tor bridge descriptors specification:

One quick thing: when we next change sanitization would you mind adding a 'changes' section with the date of the change and what the modification was? I keep an eye on the tor-spec git changes to know when the dir-spec changes but a webpage like this is harder to track. A list to answer the question of "Last time I checked this was August. Has anything changed?" would be handy.

Sounds useful to me. Let's start with such a changes section now, so that it doesn't appear out of the blue whenever we next make a change. I dug through Git history and found the following changes affecting @type annotations.

Dates are Git's "committer dates" rather than "author dates". In the future we could switch to release dates as an even better approximation of when changes became effective, but past changes were usually deployed whenever they arrived in master. In the end the exact timing doesn't matter as much, though.

  • May 30, 2012: "@type" annotations were first added to sanitized descriptors to indicate descriptor type and version: "@type bridge-server-descriptor 1.0", "@type bridge-extra-info 1.0", and "@type bridge-network-status 1.0".
  • June 29, 2012: "@type bridge-extra-info 1.1" added sanitized "transport" lines.
  • February 1, 2013: "@type bridge-extra-info 1.2" was supposed to indicate added "ntor-onion-key" lines, but those changes only affected bridge server descriptors, not extra-info descriptors. So, nothing has changed as compared to "@type bridge-extra-info 1.1", and there may be "@type bridge-server-descriptor 1.0" descriptors with and without those lines.
  • June 19, 2015: "@type bridge-server-descriptor 1.1" and "@type bridge-extra-info 1.3" added "master-key-ed25519" and "router-digest-sha256" lines to descriptors published by bridges using an ed25519 master key.
  • September 18, 2016: "@type bridge-server-descriptor 1.2" and "@type bridge-network-status 1.1" introduced sanitized TCP ports.
  • July 10, 2017: "@type bridge-network-status 1.2" introduced the "fingerprint" line, containing the fingerprint of the bridge authority which produced the document, to the header.

Please, somebody (probably atagar or iwakeh), review this list. If it looks good, I'll put it on the page early next week.

Child Tickets

Change History (5)

comment:1 Changed 2 years ago by karsten

Status: newneeds_review

comment:2 Changed 2 years ago by atagar

Looks good to me. Thanks Karsten!

comment:3 Changed 2 years ago by iwakeh

Yes, it is important to have such a change description/listing.

To have a more complete changelog more items should be included. From the simple git search:

  • Retain padding-counts lines when sanitizing descriptors. Karsten Loesing 2017-05-11
  • Retain hidserv-* lines when sanitizing descriptors. Karsten Loesing 2016-11-23
  • Sanitize TCP ports in bridge descriptors. Karsten Loesing 2016-09-18
  • Sanitize bridge descriptors with ed25519 lines. Karsten Loesing 2015-06-13
  • Parse "published" lines from bridge statuses. Karsten Loesing 2014-10-13
  • Clarify ntor-onion-key lines and @type versions. Karsten Loesing 2014-06-10
  • ...

CollecTor's changelog is also a source for change info.
Maybe, there's a way to automate the list? All bridge desc sanitation related changes in a release tag without test related commits ...
Well, at least a source for adding historical changes manually.

comment:4 in reply to:  3 Changed 2 years ago by karsten

Replying to iwakeh:

Yes, it is important to have such a change description/listing.

To have a more complete changelog more items should be included. From the simple git search:

Ah, I guess we'll first have to decide what should go into this changes section. My plan was to only include changes to the specification, that is, changes to the way how we're modifying original bridge descriptors when sanitizing them. Now, some of the changes you suggest don't affect the specification but only the implementation. Let me explain using the first example:

  • Retain padding-counts lines when sanitizing descriptors. Karsten Loesing 2017-05-11

These "padding-counts" lines never showed up in bridge descriptors until a few days before this commit. And when they first showed up, CollecTor rejected the entire descriptor, printed out a warning, and continued with the next descriptor. After we checked that these lines can go in without change, this commit simply made sure they're copied over.

In summary, whenever an original bridge descriptors did not contain such a line, the sanitized descriptor didn't either. And if the original descriptor contained this line, the sanitized one did as well. That's also why we didn't bump the version number. There was no change to the specification.

This is different for changes where we're modifying line contents, adding lines that didn't exist before, truncating lines, or even removing lines entirely. Those are all changes that would require a version number bump and probably an entry in this new changes section.

Maybe think of it in a different way: If our implementation would default to accepting unknown lines and only touch lines that we modify in the sanitizing process, these new lines in original descriptors would not even produce a Git commit. I'm not saying it's a better approach, it's just an attempt to distinguish the two types of changes.

  • Retain hidserv-* lines when sanitizing descriptors. Karsten Loesing 2016-11-23

Same.

  • Sanitize TCP ports in bridge descriptors. Karsten Loesing 2016-09-18

This one is in my list, too.

  • Sanitize bridge descriptors with ed25519 lines. Karsten Loesing 2015-06-13

In my list, too.

  • Parse "published" lines from bridge statuses. Karsten Loesing 2014-10-13

This one is tricky. We did write such a line ourselves before, and with this change we're copying that line from the original descriptor. I guess we should add it, even though it didn't lead to a version number bump.

  • Clarify ntor-onion-key lines and @type versions. Karsten Loesing 2014-06-10

That's just a documentation patch.

  • ...

CollecTor's changelog is also a source for change info.
Maybe, there's a way to automate the list? All bridge desc sanitation related changes in a release tag without test related commits ...
Well, at least a source for adding historical changes manually.

Maybe we can use this list as source for discussion what should go into changes and what should not? Some of these changes are tricky and require per-case inspection and possibly discussion.

Would you want to create such a list?

comment:5 Changed 2 years ago by karsten

Resolution: fixed
Status: needs_reviewclosed

Let's not make this more complicated than it has to be and only include changes that resulted in raising the "@type" version number. That seems to resolve the original issue, and it will be easy to decide in the future which changes need to be listed. Merged to master and deployed. Closing. Thanks, all!

Note: See TracTickets for help on using tickets.