[tor-dev] Stem Sphinx Documentation

[Karsten Loesing]

On 6/6/12 7:32 PM, Damian Johnson wrote:
>> - Why does digest() return the base64-encoded digest, not the
>> hex-formatted one?  Network statuses are the only documents in Tor using
>> base64 (or rather, a variant of it without trailing ='s), so it's easier
>> to convert those to hex than to convert everything else to base64.  Now,
>> if you switch to hex, you'll only have to decide between lower-case and
>> upper-case.  I think Tor and metrics-lib use upper-case hex in most places.
> 
> I went with base64 because I thought that this was only useful for
> comparing with the network status. What uses the hex encoded digest?

The hex-encoded server descriptor digest is used as file name in metrics
tarballs.

The (decoded) descriptor digest is used to verify the descriptor signature.

Other reasons for hex-encoding the digest() result is that the digest()
in extra-info descriptors should return the hex-encoded digest, too, or
you wouldn't be able to compare it to the extra-info-digest line in
server descriptors.  Having both methods return a different encoding
would be confusing.

Oh, and router-digest lines in sanitized bridge descriptors also contain
the hex-encoded digest.  You wouldn't want to convert that to base64
before writing it to the digest variable, nor would you want digest()
and digest to return differently encoded digests.

>> - address_alt is not bridge-specific, but relays are going to list
>> additional OR addresses in their descriptors in the near future.
> 
> Yup, but they don't yet nor is it in the tor spec (last that I
> checked). I was planning to move it up to the ServerDescriptor class
> when it is.

Makes sense.

Thanks,
Karsten