clarify the hybrid encryption in our spec

svn:r1736

3 files changed, 25 insertions, 33 deletions

diff --git a/doc/TODO b/doc/TODO
index e8bd43df62..90a7fa1cc3 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -11,21 +11,6 @@ ARMA    - arma claims
         D Deferred
         X Abandoned
 
-Flag-day changes: (things which are backward incompatible)
-        o remove link key from directories, from connection_t.
-          (just get it from the tls cert)
-        o Generate link keys on startup; don't store them to disk.
-        o make onion keys include oaep padding, so you can tell
-          if you decrypted it correctly
-        o Rotate onion keys as needed
-        D Rotate TLS connections [arma]
-        o Set expiration times on X509 certs [nickm]
-        o add bandwidthrate and bandwidthburst to server descriptor [nickm]
-        o directories need to say who signed them. [nickm]
-        - remove assumption that 0.0.5 doesn't do rendezvous?
-        D what other pieces of the descriptors need to change?
-          maybe add a section for who's connected to a given router?
-          add a flexible section for reputation info?
 
 For September:
         - Windows port
@@ -69,6 +54,9 @@ For September:
             - allow non-clique topology
 
 Other details and small things:
+        - hidserv offerers shouldn't need to define a SocksPort
+        - when the client fails to pick an intro point for a hidserv,
+          it should refetch the hidserv desc.
         . should maybe make clients exit(1) when bad things happen?
           e.g. clock skew.
         - should retry exitpolicy end streams even if the end cell didn't
diff --git a/doc/rend-spec.txt b/doc/rend-spec.txt
index c428864d8d..ac2b0aca8f 100644
--- a/doc/rend-spec.txt
+++ b/doc/rend-spec.txt
@@ -255,12 +255,10 @@ Tor Rendezvous Spec
 
    PK_ID is the hash of Bob's public key.  RP is NUL-padded.
 
-   The data is encrypted to Bob's PK as follows: Suppose Bob's PK is L octets
-   long.  If the data to be encrypted is shorter than L-42, then it is
-   encrypted directly (with OAEP padding).  If the data is at least as long
-   as L-42, then a randomly generated 16-byte symmetric key is prepended to
-   the data, after which the first L-16-42 bytes of the data are encrypted with
-   Bob's PK; and the rest of the data is encrypted with the symmetric key.
+   The hybrid encryption to Bob's PK works just like the hybrid
+   encryption in CREATE cells (see main spec). Thus the payload of the
+   RELAY_INTRODUCE1 cell on the wire will contain 20+42+16+20+20+128=246
+   bytes.
 
 1.9. Introduction: From the Introduction Point to Bob's OP
 
diff --git a/doc/tor-spec.txt b/doc/tor-spec.txt
index 7c02974292..5536ef0007 100644
--- a/doc/tor-spec.txt
+++ b/doc/tor-spec.txt
@@ -98,7 +98,7 @@ TODO: (very soon)
    proxies is a fixed-width "cell".  Each cell contains the following
    fields:
 
-        CircID                               [2 bytes]
+        CircID                                [2 bytes]
         Command                               [1 byte]
         Payload (padded with 0 bytes)         [509 bytes]
                                          [Total size: 512 bytes]
@@ -146,23 +146,29 @@ TODO: (very soon)
    which instructs the last node in the circuit to send a CREATE cell
    to extend the circuit.
 
-   The payload for a CREATE cell is an 'onion skin', consisting of:
-         RSA-encrypted data            [128 bytes]
-         Symmetrically-encrypted data  [16 bytes]
+   The payload for a CREATE cell is an 'onion skin', which consists
+   of the first step of the DH handshake data (also known as g^x).
 
-   The RSA-encrypted portion contains:
-         Symmetric key                 [16 bytes]
-         First part of DH data (g^x)   [112 bytes]
-   The symmetrically encrypted portion contains:
-         Second part of DH data (g^x)  [16 bytes]
+   The data is encrypted to Bob's PK as follows: Suppose Bob's PK is
+   L octets long.  If the data to be encrypted is shorter than L-42,
+   then it is encrypted directly (with OAEP padding).  If the data is at
+   least as long as L-42, then a randomly generated 16-byte symmetric
+   key is prepended to the data, after which the first L-16-42 bytes
+   of the data are encrypted with Bob's PK; and the rest of the data is
+   encrypted with the symmetric key.
 
-   The two parts of DH data, once decrypted and concatenated, form
-   g^x as calculated by the client.
+   So in this case, the onion skin on the wire looks like:
+       RSA-encrypted:
+         OAEP padding                  [42 bytes]
+         Symmetric key                 [16 bytes]
+         First part of g^x             [70 bytes]
+       Symmetrically encrypted:
+         Second part of g^x            [58 bytes]
 
    The relay payload for an EXTEND relay cell consists of:
          Address                       [4 bytes]
          Port                          [2 bytes]
-         Onion skin                    [144 bytes]
+         Onion skin                    [186 bytes]
 
    The port and address field denote the IPV4 address and port of the
    next onion router in the circuit.