Начинаем изучать "Stem is a Python controller library for Tor"

На сайте Tor нашел сылки на библиотеку (здесь A Tor control protocol (Version 1)), обновления свежие... Надо изучать. Сюда соберу все ссылки... Stem is a Python controller library for Tor. Like its predecessor, TorCtl, it uses Tor's control protocol to help developers program against the Tor process, enabling them to build things similar to Vidalia and arm. Stem's latest version is 1.2.2 (released June 7th, 2014).

Ключевой источник "STEM Frequently Asked Questions ". Здесь есть почти все, самое главное ... готовые примеры для смены IP адреса.

Stem is a Python controller library for Tor
Tutorial - Getting started with any new library can be rather daunting, so let's get our feet wet by jumping straight in with some tutorials...
SocksiPy - A Python SOCKS client module

Where is the Tor API documentation?
Socket Secure (SOCKS)
STEM Frequently Asked Questions
TC: A Tor control protocol (Version 1)
gitweb.torproject.org

In [4]:

%load C:\\Users\\kiss\\Desktop\\Tor Browser\\Data\\Tor\\torrc

In []:

# This file was generated by Tor; if you edit it, comments will not be preserved
# The old torrc file was renamed to torrc.orig.1 or similar, and Tor will ignore it

DataDirectory C:\Users\kiss\Desktop\Tor Browser\Data\Tor
DirReqStatistics 0
GeoIPFile C:\Users\kiss\Desktop\Tor Browser\Data\Tor\geoip
GeoIPv6File C:\Users\kiss\Desktop\Tor Browser\Data\Tor\geoip6

In [6]:

%load C:\\Users\\kiss\\Desktop\\Tor Browser\\Data\\Tor\\torrc-defaults

In []:

# If non-zero, try to write to disk less frequently than we would otherwise.
AvoidDiskWrites 1
# Where to send logging messages.  Format is minSeverity[-maxSeverity]
# (stderr|stdout|syslog|file FILENAME).
Log notice stdout
# Bind to this address to listen to connections from SOCKS-speaking
# applications.
SocksPort 9150
ControlPort 9151
CookieAuthentication 1
## fteproxy configuration
ClientTransportPlugin fte exec Tor\PluggableTransports\fteproxy --managed

## obfsproxy configuration
ClientTransportPlugin obfs2,obfs3 exec Tor\PluggableTransports\obfsproxy managed

## flash proxy configuration
#
# Change the second number here (9000) to the number of a port that can
# receive connections from the Internet (the port for which you
# configured port forwarding).
ClientTransportPlugin flashproxy exec Tor\PluggableTransports\flashproxy-client --register :0 :9000

Вот то описание TOR API, которое мне уалось найти control-spec.txt¶

In []:

TC: A Tor control protocol (Version 1)
   3 
   4 0. Scope
   5 
   6   This document describes an implementation-specific protocol that is used
   7   for other programs (such as frontend user-interfaces) to communicate with a
   8   locally running Tor process.  It is not part of the Tor onion routing
   9   protocol.
  10 
  11   This protocol replaces version 0 of TC, which is now deprecated.  For
  12   reference, TC is described in "control-spec-v0.txt".  Implementors are
  13   recommended to avoid using TC directly, but instead to use a library that
  14   can easily be updated to use the newer protocol.  (Version 0 is used by Tor
  15   versions 0.1.0.x; the protocol in this document only works with Tor
  16   versions in the 0.1.1.x series and later.)
  17 
  18       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  19       NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
  20       "OPTIONAL" in this document are to be interpreted as described in
  21       RFC 2119.
  22 
  23 1. Protocol outline
  24 
  25   TC is a bidirectional message-based protocol.  It assumes an underlying
  26   stream for communication between a controlling process (the "client"
  27   or "controller") and a Tor process (or "server").  The stream may be
  28   implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on,
  29   but it must provide reliable in-order delivery.  For security, the
  30   stream should not be accessible by untrusted parties.
  31 
  32   In TC, the client and server send typed messages to each other over the
  33   underlying stream.  The client sends "commands" and the server sends
  34   "replies".
  35 
  36   By default, all messages from the server are in response to messages from
  37   the client.  Some client requests, however, will cause the server to send
  38   messages to the client indefinitely far into the future.  Such
  39   "asynchronous" replies are marked as such.
  40 
  41   Servers respond to messages in the order messages are received.
  42 
  43 1.1. Forward-compatibility
  44 
  45   This is an evolving protocol; new client and server behavior will be
  46   allowed in future versions.  To allow new backward-compatible client
  47   on behalf of the client, we may add new commands and allow existing
  48   commands to take new arguments in future versions.  To allow new
  49   backward-compatible server behavior, we note various places below
  50   where servers speaking a future versions of this protocol may insert
  51   new data, and note that clients should/must "tolerate" unexpected
  52   elements in these places.  There are two ways that we do this:
  53 
  54   * Adding a new field to a message:
  55 
  56     For example, we might say "This message has three space-separated
  57     fields; clients MUST tolerate more fields."  This means that a
  58     client MUST NOT crash or otherwise fail to parse the message or
  59     other subsequent messages when there are more than three fields, and
  60     that it SHOULD function at least as well when more fields are
  61     provided as it does when it only gets the fields it accepts.  The
  62     most obvious way to do this is by ignoring additional fields; the
  63     next-most-obvious way is to report additional fields verbatim to the
  64     user, perhaps as part of an expert UI.
  65 
  66   * Adding a new possible value to a list of alternatives:
  67 
  68     For example, we might say "This field will be OPEN, CLOSED, or
  69     CONNECTED.  Clients MUST tolerate unexpected values."  This means
  70     that a client MUST NOT crash or otherwise fail to parse the message
  71     or other subsequent when there are unexpected values, and that the
  72     client SHOULD try to handle the rest of the message as well as it
  73     can.  The most obvious way to do this is by pretending that each
  74     list of alternatives has an additional "unrecognized value" element,
  75     and mapping any unrecognized values to that element; the
  76     next-most-obvious way is to create a separate "unrecognized value"
  77     element for each unrecognized value.
  78 
  79     Clients SHOULD NOT "tolerate" unrecognized alternatives by
  80     pretending that the message containing them is absent.  For example,
  81     a stream closed for an unrecognized reason is nevertheless closed,
  82     and should be reported as such.
  83 
  84     (If some list of alternatives is given, and there isn't an explicit
  85     statement that clients must tolerate unexpected values, clients still
  86     must tolerate unexpected values. The only exception would be if there
  87     were an explicit statement that no future values will ever be added.)
  88 
  89 2. Message format
  90 
  91 2.1. Description format
  92 
  93   The message formats listed below use ABNF as described in RFC 2234.
  94   The protocol itself is loosely based on SMTP (see RFC 2821).
  95 
  96   We use the following nonterminals from RFC 2822: atom, qcontent
  97 
  98   We define the following general-use nonterminals:
  99 
 100      QuotedString = DQUOTE *qcontent DQUOTE
 101 
 102   There are explicitly no limits on line length.  All 8-bit characters
 103   are permitted unless explicitly disallowed.  In QuotedStrings,
 104   backslashes and quotes must be escaped; other characters need not be
 105   escaped.
 106 
 107   Wherever CRLF is specified to be accepted from the controller, Tor MAY also
 108   accept LF.  Tor, however, MUST NOT generate LF instead of CRLF.
 109   Controllers SHOULD always send CRLF.
 110 
 111 2.2. Commands from controller to Tor
 112 
 113     Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData
 114     Keyword = 1*ALPHA
 115     OptArguments = [ SP *(SP / VCHAR) ]
 116 
 117   A command is either a single line containing a Keyword and arguments, or a
 118   multiline command whose initial keyword begins with +, and whose data
 119   section ends with a single "." on a line of its own.  (We use a special
 120   character to distinguish multiline commands so that Tor can correctly parse
 121   multi-line commands that it does not recognize.) Specific commands and
 122   their arguments are described below in section 3.
 123 
 124 2.3. Replies from Tor to the controller
 125 
 126     Reply = SyncReply / AsyncReply
 127     SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
 128     AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine
 129 
 130     MidReplyLine = StatusCode "-" ReplyLine
 131     DataReplyLine = StatusCode "+" ReplyLine CmdData
 132     EndReplyLine = StatusCode SP ReplyLine
 133     ReplyLine = [ReplyText] CRLF
 134     ReplyText = XXXX
 135     StatusCode = 3DIGIT
 136 
 137   Specific replies are mentioned below in section 3, and described more fully
 138   in section 4.
 139 
 140   [Compatibility note:  versions of Tor before 0.2.0.3-alpha sometimes
 141   generate AsyncReplies of the form "*(MidReplyLine / DataReplyLine)".
 142   This is incorrect, but controllers that need to work with these
 143   versions of Tor should be prepared to get multi-line AsyncReplies with
 144   the final line (usually "650 OK") omitted.]
 145 
 146 2.4. General-use tokens
 147 
 148   ; CRLF means, "the ASCII Carriage Return character (decimal value 13)
 149   ; followed by the ASCII Linefeed character (decimal value 10)."
 150   CRLF = CR LF
 151 
 152   ; How a controller tells Tor about a particular OR.  There are four
 153   ; possible formats:
 154   ;    $Fingerprint -- The router whose identity key hashes to the fingerprint.
 155   ;        This is the preferred way to refer to an OR.
 156   ;    $Fingerprint~Nickname -- The router whose identity key hashes to the
 157   ;        given fingerprint, but only if the router has the given nickname.
 158   ;    $Fingerprint=Nickname -- The router whose identity key hashes to the
 159   ;        given fingerprint, but only if the router is Named and has the given
 160   ;        nickname.
 161   ;    Nickname -- The Named router with the given nickname, or, if no such
 162   ;        router exists, any router whose nickname matches the one given.
 163   ;        This is not a safe way to refer to routers, since Named status
 164   ;        could under some circumstances change over time.
 165   ;
 166   ; The tokens that implement the above follow:
 167 
 168   ServerSpec = LongName / Nickname
 169   LongName   = Fingerprint [ ( "=" / "~" ) Nickname ]
 170 
 171   Fingerprint = "$" 40*HEXDIG
 172   NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
 173   Nickname = 1*19 NicknameChar
 174 
 175   ; What follows is an outdated way to refer to ORs.
 176   ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and
 177   ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version
 178   ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later.
 179   ServerID = Nickname / Fingerprint
 180 
 181 
 182   ; Unique identifiers for streams or circuits.  Currently, Tor only
 183   ; uses digits, but this may change
 184   StreamID = 1*16 IDChar
 185   CircuitID = 1*16 IDChar
 186   ConnID = 1*16 IDChar
 187   QueueID = 1*16 IDChar
 188   IDChar = ALPHA / DIGIT
 189 
 190   Address = ip4-address / ip6-address / hostname   (XXXX Define these)
 191 
 192   ; A "CmdData" section is a sequence of octets concluded by the terminating
 193   ; sequence CRLF "." CRLF.  The terminating sequence may not appear in the
 194   ; body of the data.  Leading periods on lines in the data are escaped with
 195   ; an additional leading period as in RFC 2821 section 4.5.2.
 196   CmdData = *DataLine "." CRLF
 197   DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF
 198   LineItem = NonCR / 1*CR NonCRLF
 199   NonDotItem = NonDotCR / 1*CR NonCRLF
 200 
 201   ; ISOTime, ISOTime2, and ISOTime2Frac are time formats as specified in
 202   ; ISO8601.
 203   ;  example ISOTime:      "2012-01-11 12:15:33"
 204   ;  example ISOTime2:     "2012-01-11T12:15:33"
 205   ;  example ISOTime2Frac: "2012-01-11T12:15:33.51"
 206   IsoDatePart = 4*DIGIT "-" 2*DIGIT "-" 2*DIGIT
 207   IsoTimePart = 2*DIGIT ":" 2*DIGIT ":" 2*DIGIT
 208   ISOTime  = IsoDatePart " " IsoTimePart
 209   ISOTime2 = IsoDatePart "T" IsoTimePart
 210   ISOTime2Frac = IsoTime2 [ "." 1*DIGIT ]
 211 
 212 3. Commands
 213 
 214   All commands are case-insensitive, but most keywords are case-sensitive.
 215 
 216 3.1. SETCONF
 217 
 218   Change the value of one or more configuration variables.  The syntax is:
 219 
 220     "SETCONF" 1*(SP keyword ["=" value]) CRLF
 221     value = String / QuotedString
 222 
 223   Tor behaves as though it had just read each of the key-value pairs
 224   from its configuration file.  Keywords with no corresponding values have
 225   their configuration values reset to 0 or NULL (use RESETCONF if you want
 226   to set it back to its default).  SETCONF is all-or-nothing: if there
 227   is an error in any of the configuration settings, Tor sets none of them.
 228 
 229   Tor responds with a "250 configuration values set" reply on success.
 230   If some of the listed keywords can't be found, Tor replies with a
 231   "552 Unrecognized option" message. Otherwise, Tor responds with a
 232   "513 syntax error in configuration values" reply on syntax error, or a
 233   "553 impossible configuration setting" reply on a semantic error.
 234 
 235   Some configuration options (e.g. "Bridge") take multiple values. Also,
 236   some configuration keys (e.g. for hidden services and for entry
 237   guard lists) form a context-sensitive group where order matters (see
 238   GETCONF below). In these cases, setting _any_ of the options in a
 239   SETCONF command is taken to reset all of the others. For example,
 240   if two ORListenAddress values are configured, and a SETCONF command
 241   arrives containing a single ORListenAddress value, the new command's
 242   value replaces the two old values.
 243 
 244   Sometimes it is not possible to change configuration options solely by
 245   issuing a series of SETCONF commands, because the value of one of the
 246   configuration options depends on the value of another which has not yet
 247   been set. Such situations can be overcome by setting multiple configuration
 248   options with a single SETCONF command (e.g. SETCONF ORPort=443
 249   ORListenAddress=9001).
 250 
 251 3.2. RESETCONF
 252 
 253   Remove all settings for a given configuration option entirely, assign
 254   its default value (if any), and then assign the String provided.
 255   Typically the String is left empty, to simply set an option back to
 256   its default. The syntax is:
 257 
 258     "RESETCONF" 1*(SP keyword ["=" String]) CRLF
 259 
 260   Otherwise it behaves like SETCONF above.
 261 
 262 3.3. GETCONF
 263 
 264   Request the value of a configuration variable.  The syntax is:
 265 
 266     "GETCONF" 1*(SP keyword) CRLF
 267 
 268   If all of the listed keywords exist in the Tor configuration, Tor replies
 269   with a series of reply lines of the form:
 270       250 keyword=value
 271   If any option is set to a 'default' value semantically different from an
 272   empty string, Tor may reply with a reply line of the form:
 273       250 keyword
 274 
 275   Value may be a raw value or a quoted string.  Tor will try to use unquoted
 276   values except when the value could be misinterpreted through not being
 277   quoted. (Right now, Tor supports no such misinterpretable values for
 278   configuration options.)
 279 
 280   If some of the listed keywords can't be found, Tor replies with a
 281   "552 unknown configuration keyword" message.
 282 
 283   If an option appears multiple times in the configuration, all of its
 284   key-value pairs are returned in order.
 285 
 286   Some options are context-sensitive, and depend on other options with
 287   different keywords.  These cannot be fetched directly.  Currently there
 288   is only one such option: clients should use the "HiddenServiceOptions"
 289   virtual keyword to get all HiddenServiceDir, HiddenServicePort,
 290   HiddenServiceVersion, and HiddenserviceAuthorizeClient option settings.
 291 
 292 3.4. SETEVENTS
 293 
 294   Request the server to inform the client about interesting events.  The
 295   syntax is:
 296 
 297      "SETEVENTS" [SP "EXTENDED"] *(SP EventCode) CRLF
 298 
 299      EventCode = 1*(ALPHA / "_")  (see section 4.1.x for event types)
 300 
 301   Any events *not* listed in the SETEVENTS line are turned off; thus, sending
 302   SETEVENTS with an empty body turns off all event reporting.
 303 
 304   The server responds with a "250 OK" reply on success, and a "552
 305   Unrecognized event" reply if one of the event codes isn't recognized.  (On
 306   error, the list of active event codes isn't changed.)
 307 
 308   If the flag string "EXTENDED" is provided, Tor may provide extra
 309   information with events for this connection; see 4.1 for more information.
 310   NOTE: All events on a given connection will be provided in extended format,
 311   or none.
 312   NOTE: "EXTENDED" was first supported in Tor 0.1.1.9-alpha; it is
 313   always-on in Tor 0.2.2.1-alpha and later.
 314 
 315   Each event is described in more detail in Section 4.1.
 316 
 317 3.5. AUTHENTICATE
 318 
 319   Sent from the client to the server.  The syntax is:
 320      "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF
 321 
 322   The server responds with "250 OK" on success or "515 Bad authentication" if
 323   the authentication cookie is incorrect.  Tor closes the connection on an
 324   authentication failure.
 325 
 326   The authentication token can be specified as either a quoted ASCII string,
 327   or as an unquoted hexadecimal encoding of that same string (to avoid escaping
 328   issues).
 329 
 330   For information on how the implementation securely stores authentication
 331   information on disk, see section 5.1.
 332 
 333   Before the client has authenticated, no command other than
 334   PROTOCOLINFO, AUTHCHALLENGE, AUTHENTICATE, or QUIT is valid.  If the
 335   controller sends any other command, or sends a malformed command, or
 336   sends an unsuccessful AUTHENTICATE command, or sends PROTOCOLINFO or
 337   AUTHCHALLENGE more than once, Tor sends an error reply and closes
 338   the connection.
 339 
 340   To prevent some cross-protocol attacks, the AUTHENTICATE command is still
 341   required even if all authentication methods in Tor are disabled.  In this
 342   case, the controller should just send "AUTHENTICATE" CRLF.
 343 
 344   (Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the
 345   connection after an authentication failure.)
 346 
 347 3.6. SAVECONF
 348 
 349   Sent from the client to the server.  The syntax is:
 350      "SAVECONF" CRLF
 351 
 352   Instructs the server to write out its config options into its torrc. Server
 353   returns "250 OK" if successful, or "551 Unable to write configuration
 354   to disk" if it can't write the file or some other error occurs.
 355 
 356   See also the "getinfo config-text" command, if the controller wants
 357   to write the torrc file itself.
 358 
 359 3.7. SIGNAL
 360 
 361   Sent from the client to the server. The syntax is:
 362 
 363      "SIGNAL" SP Signal CRLF
 364 
 365      Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" /
 366               "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" /
 367               "CLEARDNSCACHE"
 368 
 369   The meaning of the signals are:
 370 
 371       RELOAD    -- Reload: reload config items. (like HUP)
 372       SHUTDOWN  -- Controlled shutdown: if server is an OP, exit immediately.
 373                    If it's an OR, close listeners and exit after
 374                    ShutdownWaitLength seconds. (like INT)
 375       DUMP      -- Dump stats: log information about open connections and
 376                    circuits. (like USR1)
 377       DEBUG     -- Debug: switch all open logs to loglevel debug. (like USR2)
 378       HALT      -- Immediate shutdown: clean up and exit now. (like TERM)
 379       CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames.
 380       NEWNYM    -- Switch to clean circuits, so new application requests
 381                    don't share any circuits with old ones.  Also clears
 382                    the client-side DNS cache.  (Tor MAY rate-limit its
 383                    response to this signal.)
 384 
 385   The server responds with "250 OK" if the signal is recognized (or simply
 386   closes the socket if it was asked to close immediately), or "552
 387   Unrecognized signal" if the signal is unrecognized.
 388 
 389 3.8. MAPADDRESS
 390 
 391   Sent from the client to the server.  The syntax is:
 392 
 393     "MAPADDRESS" 1*(Address "=" Address SP) CRLF
 394 
 395   The first address in each pair is an "original" address; the second is a
 396   "replacement" address.  The client sends this message to the server in
 397   order to tell it that future SOCKS requests for connections to the original
 398   address should be replaced with connections to the specified replacement
 399   address.  If the addresses are well-formed, and the server is able to
 400   fulfill the request, the server replies with a 250 message:
 401     250-OldAddress1=NewAddress1
 402     250 OldAddress2=NewAddress2
 403 
 404   containing the source and destination addresses.  If request is
 405   malformed, the server replies with "512 syntax error in command
 406   argument".  If the server can't fulfill the request, it replies with
 407   "451 resource exhausted".
 408 
 409   The client may decline to provide a body for the original address, and
 410   instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or
 411   "." for hostname), signifying that the server should choose the original
 412   address itself, and return that address in the reply.  The server
 413   should ensure that it returns an element of address space that is unlikely
 414   to be in actual use.  If there is already an address mapped to the
 415   destination address, the server may reuse that mapping.
 416 
 417   If the original address is already mapped to a different address, the old
 418   mapping is removed.  If the original address and the destination address
 419   are the same, the server removes any mapping in place for the original
 420   address.
 421 
 422   Example:
 423     C: MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net
 424     S: 250-127.192.10.10=torproject.org
 425     S: 250 1.2.3.4=tor.freehaven.net
 426 
 427   {Note: This feature is designed to be used to help Tor-ify applications
 428   that need to use SOCKS4 or hostname-less SOCKS5.  There are three
 429   approaches to doing this:
 430      1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead.
 431      2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS
 432         feature) to resolve the hostname remotely.  This doesn't work
 433         with special addresses like x.onion or x.y.exit.
 434      3. Use MAPADDRESS to map an IP address to the desired hostname, and then
 435         arrange to fool the application into thinking that the hostname
 436         has resolved to that IP.
 437   This functionality is designed to help implement the 3rd approach.}
 438 
 439   Mappings set by the controller last until the Tor process exits:
 440   they never expire. If the controller wants the mapping to last only
 441   a certain time, then it must explicitly un-map the address when that
 442   time has elapsed.
 443 
 444 3.9. GETINFO
 445 
 446   Sent from the client to the server.  The syntax is as for GETCONF:
 447     "GETINFO" 1*(SP keyword) CRLF
 448   one or more NL-terminated strings.  The server replies with an INFOVALUE
 449   message, or a 551 or 552 error.
 450 
 451   Unlike GETCONF, this message is used for data that are not stored in the Tor
 452   configuration file, and that may be longer than a single line.  On success,
 453   one ReplyLine is sent for each requested value, followed by a final 250 OK
 454   ReplyLine.  If a value fits on a single line, the format is:
 455       250-keyword=value
 456   If a value must be split over multiple lines, the format is:
 457       250+keyword=
 458       value
 459       .
 460   Recognized keys and their values include:
 461 
 462     "version" -- The version of the server's software, including the name
 463       of the software. (example: "Tor 0.0.9.4")
 464 
 465     "config-file" -- The location of Tor's configuration file ("torrc").
 466 
 467     "config-defaults-file" -- The location of Tor's configuration
 468       defaults file ("torrc.defaults").  This file gets parsed before
 469       torrc, and is typically used to replace Tor's default
 470       configuration values. [First implemented in 0.2.3.9-alpha.]

Посты чуть ниже также могут вас заинтересовать