tordir

Documentation

Overview

Package tordir implements parts of the Tor directory protocol.

Index

• Variables
• func SearchAuthorityDirectoryAddresses() ([]string, error)
• type Document
  • func Parse(b []byte) (*Document, error)
  • func (d *Document) AddItem(item *Item)
  • func (d Document) Encode() []byte
• type Item
  • func NewItem(keyword string, args []string) *Item
  • func NewItemKeywordOnly(keyword string) *Item
  • func NewItemWithObject(keyword string, args []string, obj *pem.Block) *Item
  • func (it Item) Encode() []byte
• type ServerDescriptor
  • func NewServerDescriptor() *ServerDescriptor
  • func (d *ServerDescriptor) Document() (*Document, error)
  • func (d *ServerDescriptor) PublishPublic() error
  • func (d *ServerDescriptor) PublishToAuthority(addr string) error
  • func (d *ServerDescriptor) SetBandwidth(avg, burst, observed int)
  • func (d *ServerDescriptor) SetContact(c string)
  • func (d *ServerDescriptor) SetExitPolicy(policy *torexitpolicy.Policy)
  • func (d *ServerDescriptor) SetNtorOnionKey(k *torcrypto.Curve25519KeyPair)
  • func (d *ServerDescriptor) SetOnionKey(k *rsa.PublicKey) error
  • func (d *ServerDescriptor) SetPlatform(platform string)
  • func (d *ServerDescriptor) SetProtocols(p protover.SupportedProtocols)
  • func (d *ServerDescriptor) SetPublishedTime(t time.Time)
  • func (d *ServerDescriptor) SetRouter(nickname string, addr net.IP, orPort, dirPort uint16) error
  • func (d *ServerDescriptor) SetSigningKey(k *rsa.PrivateKey) error
  • func (d *ServerDescriptor) SetUptime(dur time.Duration)
  • func (d *ServerDescriptor) Validate() error
• type ServerDescriptorMissingFieldError
  • func (e ServerDescriptorMissingFieldError) Error() string

Variables

var (
	ErrServerDescriptorBadNickname  = errors.New("invalid nickname")
	ErrServerDescriptorNotIPv4      = errors.New("require ipv4 address")
	ErrServerDescriptorNoExitPolicy = errors.New("missing exit policy")
)

Potential errors when constructing a server descriptor.

var (
	ErrParseBadPEMBlock      = errors.New("bad pem block")
	ErrParseUnrecognizedData = errors.New("document contained unrecognized data")
)

Parsing errors.

var Authorities = []string{
	"193.23.244.244:80",
	"199.58.81.140:80",
	"194.109.206.212:80",
	"131.188.40.189:80",
	"86.59.21.38:80",
	"37.218.247.217:80",
	"154.35.175.225:80",
	"128.31.0.34:9131",
	"171.25.193.9:443",
	"204.13.164.118:80",
}

Authorities is a list of the directory addresses for the Tor directory authorities. This is unlikely to change often, but can be queried with the SearchAuthorityDirectoryAddresses() function. Listed at https://atlas.torproject.org/#search/flag:authority.

var ErrServerDescriptorPublishBadStatus = errors.New("received non-200 on publish")

ErrServerDescriptorPublishBadStatus is returned from a publish operation when a non-200 HTTP response is received.

Functions

func SearchAuthorityDirectoryAddresses

func SearchAuthorityDirectoryAddresses() ([]string, error)

SearchAuthorityDirectoryAddresses queries the onionoo API for the directory addresses of the Tor authorities.

Types

type Document

type Document struct {
	// contains filtered or unexported fields
}

Document represents a Tor directory document.

func Parse

func Parse(b []byte) (*Document, error)

Parse parses a Tor directory document.

func (*Document) AddItem

func (d *Document) AddItem(item *Item)

AddItem adds the item to the Document.

func (Document) Encode

func (d Document) Encode() []byte

Encode converts the document to bytes.

type Item

type Item struct {
	Keyword    string
	Whitespace string
	Arguments  []string
	Object     *pem.Block
}

Item is an entry in a Tor directory document.

func NewItem

func NewItem(keyword string, args []string) *Item

NewItem constructs an item without an object.

func NewItemKeywordOnly

func NewItemKeywordOnly(keyword string) *Item

NewItemKeywordOnly constructs an item that only has a keyword.

func NewItemWithObject

func NewItemWithObject(keyword string, args []string, obj *pem.Block) *Item

NewItemWithObject constructs an item with the given arguments with an associated object.

func (Item) Encode

func (it Item) Encode() []byte

Encode converts the item to bytes.

type ServerDescriptor

type ServerDescriptor struct {
	// contains filtered or unexported fields
}

ServerDescriptor is a builder for a server descriptor to be published to directory servers.

func NewServerDescriptor

func NewServerDescriptor() *ServerDescriptor

NewServerDescriptor constructs an empty server descriptor.

func (*ServerDescriptor) Document

func (d *ServerDescriptor) Document() (*Document, error)

Document generates the Document for this descriptor.

func (*ServerDescriptor) PublishPublic

func (d *ServerDescriptor) PublishPublic() error

PublishPublic publishes the server descriptor to the known public Tor directory authorities.

func (*ServerDescriptor) PublishToAuthority

func (d *ServerDescriptor) PublishToAuthority(addr string) error

PublishToAuthority publishes this server descriptor to the authority with the given address (in host:port format).

func (*ServerDescriptor) SetBandwidth

func (d *ServerDescriptor) SetBandwidth(avg, burst, observed int)

SetBandwidth sets the bandwidth of the server.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L419-L430

"bandwidth" bandwidth-avg bandwidth-burst bandwidth-observed NL

   [Exactly once]

   Estimated bandwidth for this router, in bytes per second.  The
   "average" bandwidth is the volume per second that the OR is willing to
   sustain over long periods; the "burst" bandwidth is the volume that
   the OR is willing to sustain in very short intervals.  The "observed"
   value is an estimate of the capacity this relay can handle.  The
   relay remembers the max bandwidth sustained output over any ten
   second period in the past day, and another sustained input.  The
   "observed" value is the lesser of these two numbers.

func (*ServerDescriptor) SetContact

func (d *ServerDescriptor) SetContact(c string)

SetContact sets contact information for the server administrator.

func (*ServerDescriptor) SetExitPolicy

func (d *ServerDescriptor) SetExitPolicy(policy *torexitpolicy.Policy)

SetExitPolicy adds a specification of the given exit policy to the descriptor.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L554-L564

"accept" exitpattern NL
"reject" exitpattern NL

   [Any number]

   These lines describe an "exit policy": the rules that an OR follows
   when deciding whether to allow a new stream to a given address.  The
   'exitpattern' syntax is described below.  There MUST be at least one
   such entry.  The rules are considered in order; if no rule matches,
   the address will be accepted.  For clarity, the last such entry SHOULD
   be accept *:* or reject *:*.

func (*ServerDescriptor) SetNtorOnionKey

func (d *ServerDescriptor) SetNtorOnionKey(k *torcrypto.Curve25519KeyPair)

SetNtorOnionKey sets the key used for ntor circuit extended handshake.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L513-L522

"ntor-onion-key" base-64-encoded-key

   [At most once]

   A curve25519 public key used for the ntor circuit extended
   handshake.  It's the standard encoding of the OR's curve25519
   public key, encoded in base 64.  The trailing '=' sign MAY be
   omitted from the base64 encoding.  The key MUST be accepted
   for at least 1 week after any new key is published in a
   subsequent descriptor.

func (*ServerDescriptor) SetOnionKey

func (d *ServerDescriptor) SetOnionKey(k *rsa.PublicKey) error

SetOnionKey sets the "onion key" used to encrypt CREATE cells for this router.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L475-L486

"onion-key" NL a public key in PEM format

   [Exactly once]
   [No extra arguments]

   This key is used to encrypt CREATE cells for this OR.  The key MUST be
   accepted for at least 1 week after any new key is published in a
   subsequent descriptor. It MUST be 1024 bits.

   The key encoding is the encoding of the key as a PKCS#1 RSAPublicKey
   structure, encoded in base64, and wrapped in "-----BEGIN RSA PUBLIC
   KEY-----" and "-----END RSA PUBLIC KEY-----".

func (*ServerDescriptor) SetPlatform

func (d *ServerDescriptor) SetPlatform(platform string)

SetPlatform sets the platform (software, version, OS) of the server descriptor.

func (*ServerDescriptor) SetProtocols

func (d *ServerDescriptor) SetProtocols(p protover.SupportedProtocols)

SetProtocols specifies which sub-protocols the router supports.

func (*ServerDescriptor) SetPublishedTime

func (d *ServerDescriptor) SetPublishedTime(t time.Time)

SetPublishedTime sets the time the descriptor was published.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L440-L445

"published" YYYY-MM-DD HH:MM:SS NL

   [Exactly once]

   The time, in UTC, when this descriptor (and its corresponding
   extra-info document if any)  was generated.

func (*ServerDescriptor) SetRouter

func (d *ServerDescriptor) SetRouter(nickname string, addr net.IP, orPort, dirPort uint16) error

SetRouter sets the router description. This is required.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L379-L394

"router" nickname address ORPort SOCKSPort DirPort NL

  [At start, exactly once.]

  Indicates the beginning of a server descriptor.  "nickname" must be a
  valid router nickname as specified in section 2.1.3.  "address" must
  be an IPv4
  address in dotted-quad format.  The last three numbers indicate the
  TCP ports at which this OR exposes functionality. ORPort is a port at
  which this OR accepts TLS connections for the main OR protocol;
  SOCKSPort is deprecated and should always be 0; and DirPort is the
  port at which this OR accepts directory-related HTTP connections.  If
  any port is not supported, the value 0 is given instead of a port
  number.  (At least one of DirPort and ORPort SHOULD be set;
  authorities MAY reject any descriptor with both DirPort and ORPort of
  0.)

func (*ServerDescriptor) SetSigningKey

func (d *ServerDescriptor) SetSigningKey(k *rsa.PrivateKey) error

SetSigningKey sets the router's identity key, used to sign the descriptor document.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L545-L552

"signing-key" NL a public key in PEM format

   [Exactly once]
   [No extra arguments]

   The OR's long-term RSA identity key.  It MUST be 1024 bits.

   The encoding is as for "onion-key" above.

Reference: https://github.com/torproject/torspec/blob/master/dir-spec.txt#L447-L457

"fingerprint" fingerprint NL

   [At most once]

   A fingerprint (a HASH_LEN-byte of asn1 encoded public key, encoded in
   hex, with a single space after every 4 characters) for this router's
   identity key. A descriptor is considered invalid (and MUST be
   rejected) if the fingerprint line does not match the public key.

   [We didn't start parsing this line until Tor 0.1.0.6-rc; it should
    be marked with "opt" until earlier versions of Tor are obsolete.]

func (*ServerDescriptor) SetUptime

func (d *ServerDescriptor) SetUptime(dur time.Duration)

SetUptime sets the uptime of the server.

Reference: https://github.com/torproject/torspec/blob/f66d1826c0b32d307898bba081dbf8ef598d4037/dir-spec.txt#L471-L475

"uptime" number NL

   [At most once]

   The number of seconds that this OR process has been running.

func (*ServerDescriptor) Validate

func (d *ServerDescriptor) Validate() error

Validate checks whether the descriptor is valid.

type ServerDescriptorMissingFieldError

type ServerDescriptorMissingFieldError string

ServerDescriptorMissingFieldError indicates that a required field is missing from a server descriptor.

func (ServerDescriptorMissingFieldError) Error

func (e ServerDescriptorMissingFieldError) Error() string