torspec/proposals/217-ext-orport-auth.txt

Filename: 217-ext-orport-auth.txt
Title: Tor Extended ORPort Authentication
Author: George Kadianakis
Created: 28-11-2012
Status: Closed
Target: 0.2.5.x

1. Overview

  This proposal defines a scheme for Tor components to authenticate to
  each other using a shared-secret.

2. Motivation

  Proposal 196 introduced new ways for pluggable transport proxies to
  communicate with Tor. The communication happens using TCP in the same
  fashion that controllers speak to the ControlPort.

  To defend against cross-protocol attacks [0] on the transport ports,
  we need to define an authentication scheme that will restrict passage
  to unknown clients.

  Tor's ControlPort uses an authentication scheme called safe-cookie
  authentication [1]. Unfortunately, the design of the safe-cookie
  authentication was influenced by the protocol structure of the
  ControlPort and the need for backwards compatibility of the
  cookie-file and can't be easily reused in other use cases.

3. Goals

  The general goal of Extended ORPort authentication is to authenticate
  the client based on a shared-secret that only authorized clients
  should know.

  Furthermore, its implementation should be flexible and easy to reuse,
  so that it can be used as the authentication mechanism in front of
  future Tor helper ports (for example, in proposal 199).

  Finally, the protocol is able to support multiple authentication
  schemes and each of them has different goals.

4. Protocol Specification

4.1. Initial handshake

  When a client connects to the Extended ORPort, the server sends:

    AuthTypes                                   [variable]
    EndAuthTypes                                [1 octet]

  Where,

  + AuthTypes are the authentication schemes that the server supports
    for this session. They are multiple concatenated 1-octet values that
    take values from 1 to 255.
  + EndAuthTypes is the special value 0.

  The client reads the list of supported authentication schemes and
  replies with the one he prefers to use:

    AuthType                                    [1 octet]

  Where,

  + AuthType is the authentication scheme that the client wants to use
    for this session. A valid authentication type takes values from 1 to
    255. A value of 0 means that the client did not like the
    authentication types offered by the server.

  If the client sent an AuthType of value 0, or an AuthType that the
  server does not support, the server MUST close the connection.

4.2. Authentication types

4.2.1 SAFE_COOKIE handshake

  Authentication type 1 is called SAFE_COOKIE.

4.2.1.1. Motivation and goals

  The SAFE_COOKIE scheme is pretty-much identical to the authentication
  scheme that was introduced for the ControlPort in proposal 193.

  An additional goal of the SAFE_COOKIE authentication scheme (apart
  from the goals of section 2), is that it should not leak the contents
  of the cookie-file to untrusted parties.

  Specifically, the SAFE_COOKIE protocol will never leak the actual
  contents of the file. Instead, it uses a challenge-response protocol
  (similar to the HTTP digest authentication of RFC2617) to ensure that
  both parties know the cookie without leaking it.

4.2.1.2. Cookie-file format

  The format of the cookie-file is:

     StaticHeader                                [32 octets]
     Cookie                                      [32 octets]

  Where,
  + StaticHeader is the following string:
    "! Extended ORPort Auth Cookie !\x0a"
  + Cookie is the shared-secret. During the SAFE_COOKIE protocol, the
    cookie is called CookieString.

  Extended ORPort clients MUST make sure that the StaticHeader is
  present in the cookie file, before proceeding with the
  authentication protocol.

  Details on how Tor locates the cookie file can be found in section 5
  of proposal 196. Details on how transport proxies locate the cookie
  file can be found in pt-spec.txt.

4.2.1.3. Protocol specification

  A client that performs the SAFE_COOKIE handshake begins by sending:

     ClientNonce                                 [32 octets]

  Where,
  + ClientNonce is 32 octets of random data.

  Then, the server replies with:

     ServerHash                                  [32 octets]
     ServerNonce                                 [32 octets]

  Where,
  + ServerHash is computed as:
      HMAC-SHA256(CookieString,
        "ExtORPort authentication server-to-client hash" | ClientNonce | ServerNonce)
  + ServerNonce is 32 random octets.

  Upon receiving that data, the client computes ServerHash herself and
  validates it against the ServerHash provided by the server.

  If the server-provided ServerHash is invalid, the client MUST
  terminate the connection.

  Otherwise the client replies with:

     ClientHash                                  [32 octets]

  Where,
  + ClientHash is computed as:
      HMAC-SHA256(CookieString,
        "ExtORPort authentication client-to-server hash" | ClientNonce | ServerNonce)

  Upon receiving that data, the server computes ClientHash herself and
  validates it against the ClientHash provided by the client.

  Finally, the server replies with:

     Status                                      [1 octet]

  Where,
  + Status is 1 if the authentication was successfull. If the
    authentication failed, Status is 0.

4.3. Post-authentication

  After completing the Extended ORPort authentication successfully, the
  two parties should proceed with the Extended ORPort protocol on the
  same TCP connection.

5. Acknowledgments

  Thanks to Robert Ransom for helping with the proposal and designing
  the original safe-cookie authentication scheme. Thanks to Nick
  Mathewson for advices and reviews of the proposal.

[0]:
http://archives.seul.org/or/announce/Sep-2007/msg00000.html

[1]:
https://gitweb.torproject.org/torspec.git/blob/79f488c32c43562522e5592f2c19952dc7681a65:/control-spec.txt#l1069