tor-fw-helper-spec.txt

                          Tor's (little) Firewall Helper specification
                                      Jacob Appelbaum

0. Preface

 This document describes issues faced by Tor users who are behind NAT devices
 and wish to share their resources with the rest of the Tor network. It also
 explains a possible solution for some NAT devices.

1. Overview

 Tor users often wish to relay traffic for the Tor network and their upstream
 firewall thwarts their attempted generosity.  Automatic port forwarding
 configuration for many consumer NAT devices is often available with two common
 protocols NAT-PMP[0] and UPnP[1].

2. Implementation

 tor-fw-helper is a program that implements basic port forwarding requests; it
 may be used alone or called from Tor itself.

2.1 Output format

 When tor-fw-helper has completed the requested action successfully, it will
 report the following message to standard output:

    tor-fw-helper: SUCCESS

 If tor-fw-helper was unable to complete the requested action successfully, it
 will report the following message to standard error:

    tor-fw-helper: FAILURE

 All informational messages are printed to standard output; all error messages
 are printed to standard error. Messages other than SUCCESS and FAILURE
 may be printed by any compliant tor-fw-helper.

2.2 Output format stability

 The above SUCCESS and FAILURE messages are the only stable output formats
 provided by this specification. tor-fw-helper-spec compliant implementations
 must return SUCCESS or FAILURE as defined above.

3. Security Concerns

 It is probably best to hand configure port forwarding and in the process, we
 suggest disabling NAT-PMP and/or UPnP. This is of course absolutely confusing
 to users and so we support automatic, non-authenticated NAT port mapping
 protocols with compliant tor-fw-helper applications.

 NAT should not be considered a security boundary. NAT-PMP and UPnP are hacks
 to deal with the shortcomings of user education about TCP/IP, IPv4 shortages,
 and of course, NAT devices that suffer from horrible user interface design.

[0] http://en.wikipedia.org/wiki/NAT_Port_Mapping_Protocol
[1] http://en.wikipedia.org/wiki/Universal_Plug_and_Play