[tor-bugs] #8036 [Stem]: Tweak Stem's documentation

[Tor Bug Tracker & Wiki]

#8036: Tweak Stem's documentation
--------------------+-------------------------------------------------------
 Reporter:  amj703  |          Owner:  atagar
     Type:  defect  |         Status:  new   
 Priority:  normal  |      Milestone:        
Component:  Stem    |        Version:        
 Keywords:          |         Parent:        
   Points:          |   Actualpoints:        
--------------------+-------------------------------------------------------

Comment(by amj703):

 > > > All fingerprints and digests, which are in most cases 160 bit value
 strings, should state exactly whether they're base64 or lower-case hex or
 upper-case hex encoded.
 > >
 > > Mind writing a patch for this? Personally I scratched my head for
 quite a while trying to figure out what format users would find the most
 convenient for these values.
 >
 > Personally, I find hex most useful, but anything works as long as it's
 clearly documented.  Yes, I can write a patch.  But before I do that: we
 discussed in private mail that it's still break-the-API time.  It would be
 convenient if those fields that are used as references between descriptors
 (e.g., from status entry to server descriptor) used the same encoding.  If
 you agree, I'd submit a patch that documents encodings more clearly and
 that converts fingerprint and server descriptor digest in status entries
 from base64 to upper-case hex.

 I totally agree with Karsten here. I had to investigate how the various
 fingerprints (which, I believe, are encoded in Base64 in the consensus but
 in hex in the descriptors) were stored. As a related issue, the family
 field of descriptors contains fingerprints as a hex string but prepended
 with a '$' (as described in dir-spec.txt).
 stem.descriptor.server_descriptor.ServerDescriptor just reads these in,
 and thus includes the '$'. That may be reasonable behavior, but it would
 be very helpful to document that these fingerprint won't exactly match the
 values in stem.descriptor.server_descriptor.ServerDescriptor.fingerprint.

-- 
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/8036#comment:4>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online