[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[or-cvs] r10642: added specification for v2 rendezvous service descriptors to (tor/branches/114-dist-storage/doc/spec)



Author: kloesing
Date: 2007-06-17 12:41:07 -0400 (Sun, 17 Jun 2007)
New Revision: 10642

Modified:
   tor/branches/114-dist-storage/doc/spec/rend-spec.txt
Log:
added specification for v2 rendezvous service descriptors to rend-spec

Modified: tor/branches/114-dist-storage/doc/spec/rend-spec.txt
===================================================================
--- tor/branches/114-dist-storage/doc/spec/rend-spec.txt	2007-06-17 15:59:27 UTC (rev 10641)
+++ tor/branches/114-dist-storage/doc/spec/rend-spec.txt	2007-06-17 16:41:07 UTC (rev 10642)
@@ -124,7 +124,148 @@
    The first time the OP provides an advertised service, it generates
    a public/private keypair (stored locally).  Periodically, the OP
    generates a pair of service descriptors, one "V1" and one "V0".
+   If configured, the OP also generates a "V2" service descriptor.
 
+   The "V2" descriptor in branch 114-dist-storage contains:
+
+     "rendezvous-service-descriptor" descriptor-id NL
+
+       [At start, exactly once]
+
+       Indicates the beginning of the descriptor. "descriptor-id" is a
+       temporary identifier of 160 bits formatted as 32 base32 chars that can
+       only be calculated by the hidden service and its clients, i.e. by
+       everyone who is aware of a secret "cookie". (Further, everyone can
+       verify that this "descriptor-id" belongs to the rest of the descriptor,
+       even without knowing "cookie", as described below.) The "descriptor-id"
+       is calculated by performing the following operation:
+
+         descriptor-id = h(permanent-id, h(time-period, cookie))
+
+       "h" denotes the cryptographically secure hash function SHA1 that takes
+       an ordered sequence of one or more byte arrays as arguments and returns
+       a digest of 160 bits.
+
+       "permanent-id" is the permanent identifier of the hidden service
+       consisting of 80 bits. It can be calculated by computing the hash value
+       of the public hidden service key and truncating after the first 80 bits:
+
+         permanent-id = h(public-key)
+
+       "h(time-period, cookie)" is the secret id part that is necessary to
+       verify that the hidden service is the true originator of this
+       descriptor. It can only be created by the hidden service and its
+       clients, but the "signature" below can only be created by the service.
+
+       "cookie" is a secret password of 120 bits that is shared between the
+       hidden service provider and its clients.
+
+       The "time-period" changes periodically depending on the global time and
+       as a function of "permanent-id". The current value for "time-period" can
+       be calculated using the following formula:
+
+         time-period = floor(current-time / period-length
+                             + permanent-id / (max-id + 1))
+
+       "current-time" is the current system time in seconds since 1970-01-01
+       00:00. "period-length" is a system-wide constant in seconds that
+       determines how often "descriptor-id" changes, e.g. one day. "max-id"
+       denotes the theoretical value of the maximum possible "permanent-id" ---
+       it is used to normalize "permanent-id" to a [0.0..1.0[ range so that
+       "time-period" does not change for all descriptors at the same time. All
+       operations have double floating-point precision. "floor" truncates all
+       decimal places.
+
+     "version" version-number NL
+
+       [Exactly once]
+
+       The version number of this descriptor's format, e.g. 2.
+     
+     "permanent-key" NL a public key in PEM format
+   
+       [Exactly once]
+
+       The public key of the hidden service which is required to verify the
+       "descriptor-id" and the "signature".
+     
+     "secret-id-part" secret-id-part NL
+   
+       [Exactly once]
+
+       The result of the following operation as explained above, formatted as
+       32 base32 chars. Using this secret id part, everyone can verify that
+       the signed descriptor belongs to "descriptor-id".
+
+         secret-id-part = h(time-period, cookie)
+   
+     "publication-time" YYYY-MM-DD HH:MM:SS NL
+   
+       [Exactly once]
+
+       A timestamp when this descriptor has been created.
+
+     "protocol-versions" version-string NL
+
+       [Exactly once]
+
+       A bitmask of allowed rendezvous protocols.
+
+     "introduction-points" NL encrypted-string
+
+       [Exactly once]
+
+       A (possibly empty) list of introduction points that is encrypted with
+       AES in CBC mode using a random initialization vector of 128 bits, that
+       is written to the beginning of the encrypted string, and the secret key
+       "cookie", that is 120 bits long and padded with zeros to be 128 bits
+       long. In unencrypted form, every list entry contains the following
+       data:
+
+         "introduction-point" identifier NL
+
+           [At start, exactly once]
+           
+           The identifier of this introduction point.
+           
+         "ip-address" ip-address NL
+         
+           [Exactly once]
+
+           The IP address of this introduction point.
+         
+         "onion-port" port NL
+         
+           [Exactly once]
+           
+           The TCP port on which the introduction point is listening for
+           incoming onion requests.
+         
+         "onion-key" NL a public key in PEM format
+
+           [Exactly once]
+
+           The public key that can be used to encrypt messages to this
+           introduction point.
+                    
+         "service-key" NL a public key in PEM format
+
+           [Exactly once]
+
+           The public key that can be used to encrypt messages to the hidden
+           service.
+
+[TODO is it necessary to include a digest of the list of introduction points
+(plus some service-specific data to make digests incomparable) to allow any
+node to decide whether changes are cosmetic?! -KL]
+
+     "signature" NL signature-string
+
+       [At end, exactly once]
+
+       A signature of all fields above with the private key of the hidden
+       service.
+  
    The "V1" descriptor in 0.1.1.6-alpha contains:
 
          V     Format byte: set to 255               [1 octet]