o
fX]Ģ @ s d Z ddlZddlZddlZddlZddlZddlZddlZddlZddl Zddl
Zddl Zddl Zddl
ZddlZddlmZmZ zddlmZ W n
eyW ddlZY nw ejjddddZejjj ejjj ejjj ejjj dZ d Z!d
Z"da#d Z$d Z%d
d Z&dd Z'd,ddZ(d,ddZ)dd Z*d-ddZ+dd Z,d d Z-G d d d e.Z/G d d! d!e.Z0d"d# Z1d$d% Z2d&d' Z3d(d) Z4d*d+ Z5ej6j7Z7ej6j8Z9ej6j:Z;dS ).a
Module for remotely retrieving descriptors from directory authorities and
mirrors. This is the simplest method for getting current tor descriptor
information...
::
import stem.descriptor.remote
for desc in stem.descriptor.remote.get_server_descriptors():
if desc.exit_policy.is_exiting_allowed():
print(' %s (%s)' % (desc.nickname, desc.fingerprint))
More custom downloading behavior can be done through the
:class:`~stem.descriptor.remote.DescriptorDownloader` class, which issues
:class:`~stem.descriptor.remote.Query` instances to get you descriptor
content. For example...
::
from stem.descriptor.remote import DescriptorDownloader
downloader = DescriptorDownloader(
use_mirrors = True,
timeout = 10,
)
query = downloader.get_server_descriptors()
print('Exit Relays:')
try:
for desc in query.run():
if desc.exit_policy.is_exiting_allowed():
print(' %s (%s)' % (desc.nickname, desc.fingerprint))
print
print('Query took %0.2f seconds' % query.runtime)
except Exception as exc:
print('Unable to retrieve the server descriptors: %s' % exc)
::
get_instance - Provides a singleton DescriptorDownloader used for...
|- their_server_descriptor - provides the server descriptor of the relay we download from
|- get_server_descriptors - provides present server descriptors
|- get_extrainfo_descriptors - provides present extrainfo descriptors
|- get_microdescriptors - provides present microdescriptors with the given digests
|- get_consensus - provides the present consensus or router status entries
|- get_bandwidth_file - provides bandwidth heuristics used to make the next consensus
+- get_detached_signatures - authority signatures used to make the next consensus
Query - Asynchronous request to download tor descriptors
|- start - issues the query if it isn't already running
+- run - blocks until the request is finished and provides the results
DescriptorDownloader - Configurable class for issuing queries
|- use_directory_mirrors - use directory mirrors to download future descriptors
|- their_server_descriptor - provides the server descriptor of the relay we download from
|- get_server_descriptors - provides present server descriptors
|- get_extrainfo_descriptors - provides present extrainfo descriptors
|- get_microdescriptors - provides present microdescriptors with the given digests
|- get_consensus - provides the present consensus or router status entries
|- get_vote - provides an authority's vote for the next consensus
|- get_key_certificates - provides present authority key certificates
|- get_bandwidth_file - provides bandwidth heuristics used to make the next consensus
|- get_detached_signatures - authority signatures used to make the next consensus
+- query - request an arbitrary descriptor resource
.. versionadded:: 1.1.0
.. data:: MAX_FINGERPRINTS
Maximum number of descriptors that can requested at a time by their
fingerprints.
.. data:: MAX_MICRODESCRIPTOR_HASHES
Maximum number of microdescriptors that can requested at a time by their
hashes.
.. data:: Compression (enum)
Compression when downloading descriptors.
.. versionadded:: 1.7.0
=============== ===========
Compression Description
=============== ===========
**PLAINTEXT** Uncompressed data.
**GZIP** `GZip compression `_.
**ZSTD** `Zstandard compression `_, this requires the `zstandard module `_.
**LZMA** `LZMA compression `_, this requires the 'lzma module `_.
=============== ===========
N)log str_tools) PLAINTEXTidentity)GZIPgzip)ZSTDx-zstd)LZMA
x-tor-lzma)r r r r ` Z zdetached-signature)Ztor26ZSergec C s t du rt a t S )z
Provides the singleton :class:`~stem.descriptor.remote.DescriptorDownloader`
used for this module's shorthand functions.
.. versionadded:: 1.5.0
:returns: singleton :class:`~stem.descriptor.remote.DescriptorDownloader` instance
N)SINGLETON_DOWNLOADERDescriptorDownloader r r 8/usr/lib/python3/dist-packages/stem/descriptor/remote.py get_instance s r c K t jdi | S )a
Provides the server descriptor of the relay we're downloading from.
.. versionadded:: 1.7.0
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the server descriptors
Nr )r their_server_descriptor
query_argsr r r r s r c K t j| fi |S )z
Shorthand for
:func:`~stem.descriptor.remote.DescriptorDownloader.get_server_descriptors`
on our singleton instance.
.. versionadded:: 1.5.0
)r get_server_descriptors fingerprintsr r r r r r c K r )z
Shorthand for
:func:`~stem.descriptor.remote.DescriptorDownloader.get_extrainfo_descriptors`
on our singleton instance.
.. versionadded:: 1.5.0
)r get_extrainfo_descriptorsr r r r r r r c K r )z
Shorthand for
:func:`~stem.descriptor.remote.DescriptorDownloader.get_microdescriptors`
on our singleton instance.
.. versionadded:: 1.8.0
)r get_microdescriptors)hashesr r r r r r r Fc K s t j| |fi |S )z
Shorthand for
:func:`~stem.descriptor.remote.DescriptorDownloader.get_consensus`
on our singleton instance.
.. versionadded:: 1.5.0
)r
get_consensus)authority_v3identmicrodescriptorr r r r r s r c K r )z
Shorthand for
:func:`~stem.descriptor.remote.DescriptorDownloader.get_bandwidth_file`
on our singleton instance.
.. versionadded:: 1.8.0
Nr )r get_bandwidth_filer r r r r" r" c K r )z
Shorthand for
:func:`~stem.descriptor.remote.DescriptorDownloader.get_detached_signatures`
on our singleton instance.
.. versionadded:: 1.8.0
Nr )r get_detached_signaturesr r r r r$ r# r$ c
@ sl e Zd ZdZddejfddddddejjj f
ddZ
dd Z dd
d Z d d
Z
dd ZdddZdd ZdS )Querya
Asynchronous request for descriptor content from a directory authority or
mirror. These can either be made through the
:class:`~stem.descriptor.remote.DescriptorDownloader` or directly for more
advanced usage.
To block on the response and get results either call
:func:`~stem.descriptor.remote.Query.run` or iterate over the Query. The
:func:`~stem.descriptor.remote.Query.run` method pass along any errors that
arise...
::
from stem.descriptor.remote import Query
query = Query(
'/tor/server/all',
timeout = 30,
)
print('Current relays:')
try:
for desc in Query('/tor/server/all', 'server-descriptor 1.0').run():
print(desc.fingerprint)
except Exception as exc:
print('Unable to retrieve the server descriptors: %s' % exc)
... while iterating fails silently...
::
print('Current relays:')
for desc in Query('/tor/server/all', 'server-descriptor 1.0'):
print(desc.fingerprint)
In either case exceptions are available via our 'error' attribute.
Tor provides quite a few different descriptor resources via its directory
protocol (see section 4.2 and later of the `dir-spec
`_).
Commonly useful ones include...
=============================================== ===========
Resource Description
=============================================== ===========
/tor/server/all all present server descriptors
/tor/server/fp/++ server descriptors with the given fingerprints
/tor/extra/all all present extrainfo descriptors
/tor/extra/fp/++ extrainfo descriptors with the given fingerprints
/tor/micro/d/- microdescriptors with the given hashes
/tor/status-vote/current/consensus present consensus
/tor/status-vote/current/consensus-microdesc present microdescriptor consensus
/tor/status-vote/next/bandwidth bandwidth authority heuristics for the next consenus
/tor/status-vote/next/consensus-signatures detached signature, used for making the next consenus
/tor/keys/all key certificates for the authorities
/tor/keys/fp/+ key certificates for specific authorities
=============================================== ===========
**ZSTD** compression requires `zstandard
`_, and **LZMA** requires the `lzma
module `_.
For legacy reasons if our resource has a '.z' suffix then our **compression**
argument is overwritten with Compression.GZIP.
.. versionchanged:: 1.7.0
Added support for downloading from ORPorts.
.. versionchanged:: 1.7.0
Added the compression argument.
.. versionchanged:: 1.7.0
Added the reply_headers attribute.
The class this provides changed between Python versions. In python2
this was called httplib.HTTPMessage, whereas in python3 the class was
renamed to http.client.HTTPMessage.
.. versionchanged:: 1.7.0
Endpoints are now expected to be :class:`~stem.DirPort` or
:class:`~stem.ORPort` instances. Usage of tuples for this
argument is deprecated and will be removed in the future.
.. versionchanged:: 1.7.0
Avoid downloading from tor26. This directory authority throttles its
DirPort to such an extent that requests either time out or take on the
order of minutes.
.. versionchanged:: 1.7.0
Avoid downloading from Bifroest. This is the bridge authority so it
doesn't vote in the consensus, and apparently times out frequently.
.. versionchanged:: 1.8.0
Serge has replaced Bifroest as our bridge authority. Avoiding descriptor
downloads from it instead.
.. versionchanged:: 1.8.0
Defaulting to gzip compression rather than plaintext downloads.
.. versionchanged:: 1.8.0
Using :class:`~stem.descriptor.__init__.Compression` for our compression
argument, usage of strings or this module's Compression enum is deprecated
and will be removed in stem 2.x.
:var str resource: resource being fetched, such as '/tor/server/all'
:var str descriptor_type: type of descriptors being fetched (for options see
:func:`~stem.descriptor.__init__.parse_file`), this is guessed from the
resource if **None**
:var list endpoints: :class:`~stem.DirPort` or :class:`~stem.ORPort` of the
authority or mirror we're querying, this uses authorities if undefined
:var list compression: list of :data:`stem.descriptor.Compression`
we're willing to accept, when none are mutually supported downloads fall
back to Compression.PLAINTEXT
:var int retries: number of times to attempt the request if downloading it
fails
:var bool fall_back_to_authority: when retrying request issues the last
request to a directory authority if **True**
:var str content: downloaded descriptor content
:var Exception error: exception if a problem occured
:var bool is_done: flag that indicates if our request has finished
:var float start_time: unix timestamp when we first started running
:var http.client.HTTPMessage reply_headers: headers provided in the response,
**None** if we haven't yet made our request
:var float runtime: time our query took, this is **None** if it's not yet
finished
:var bool validate: checks the validity of the descriptor's content if
**True**, skips these checks otherwise
:var stem.descriptor.__init__.DocumentHandler document_handler: method in
which to parse a :class:`~stem.descriptor.networkstatus.NetworkStatusDocument`
:var dict kwargs: additional arguments for the descriptor constructor
Following are only applicable when downloading from a
:class:`~stem.DirPort`...
:var float timeout: duration before we'll time out our request
:var str download_url: last url used to download the descriptor, this is
unset until we've actually made a download attempt
:param bool start: start making the request when constructed (default is **True**)
:param bool block: only return after the request has been completed, this is
the same as running **query.run(True)** (default is **False**)
N FTc K s | ds td| |drtjg}|d d }n5|s"tjg}n.t|tr*|g}tj|v r:t j
s:| tj tj
|v rJt j
sJ| tj
|sPtjg}g }
|D ]%}t|t jjrc|
| qT|tv ro|
t| qTtd|t|jf |r|| _nt|| _g | _|r|D ]6}t|trt|dkr| jt |d |d qt|t jt jfr| j| qtd |t|jf || _ |
| _ || _ || _ d | _ d | _!d
| _"d | _#d | _$|| _%d | _&|
| _'| | _(d | _)| | _*d | _+t,- | _.|r| / | r| 0d d S d S ) N/z%Resources should start with a '/': %sz.zz1'%s' (%s) is not a recognized type of compressionr& r zQEndpoints must be an stem.ORPort, stem.DirPort, or two value tuple. '%s' is a %s.FT)1
startswith
ValueErrorendswith Compressionr r
isinstancestrr stemprereqZis_zstd_availableremover
Zis_lzma_available
descriptorZ _CompressionappendCOMPRESSION_MIGRATIONtype__name__descriptor_type_guess_descriptor_type endpointstuplelenDirPortORPortresource compressionretriesfall_back_to_authoritycontenterroris_done download_url
start_timetimeoutruntimevalidatedocument_handler
reply_headerskwargs_downloader_thread threadingRLock_downloader_thread_lockstartrun)selfr? r8 r: r@ rA rB rH rR blockrJ rK rM Znew_compressionZlegacy_compressionendpointr r r __init__ sn
zQuery.__init__c C sx | j / | jdu r*tjd| j| j| jfd| _| jd | j W d dS W d dS 1 s5w Y dS )zI
Starts downloading the scriptors if we haven't started already.
NzDescriptor query)nametargetargsT) rQ rN rO ZThread_download_descriptorsrA rH Z setDaemonrR )rT r r r rR s
"z Query.startc C s t | |S )aS
Blocks until our request is complete then provides the descriptors. If we
haven't yet started our request then this does so.
:param bool suppress: avoids raising exceptions if **True**
:returns: list for the requested :class:`~stem.descriptor.__init__.Descriptor` instances
:raises:
Using the iterator can fail with the following if **suppress** is
**False**...
* **ValueError** if the descriptor contents is malformed
* :class:`~stem.DownloadTimeout` if our request timed out
* :class:`~stem.DownloadFailed` if our request fails
)list_run)rT suppressr r r rS s z Query.runc c s8 | j | | j | jr |r W d d S | j| jd u r3|r/ W d d S tdz5| jt rIt
j j j
t| j| jd}nt
j jt| j| jf| j| jd| j}|D ]}|V qaW n! ty } z|| _|rW Y d }~W d d S | jd }~ww W d d S 1 sw Y d S )NzHBUG: _download_descriptors() finished without either results or an error)rJ )rJ rK )rQ rR rN joinrD rC r+ r8 r* DETACHED_SIGNATURE_TYPEr0 r3 Z
networkstatusZ_parse_file_detached_sigsioBytesIOrJ Z
parse_filerK rM )rT r^ resultsdescexcr r r r] sT
,"z
Query._runc c s | dD ]}|V qd S )NT)r] )rT rd r r r __iter__I s zQuery.__iter__c C sF |s| j s tdd tjj D }t|j |j
S t| j S )a.
Provides an endpoint to query. If we have multiple endpoints then one
is picked at random.
:param bool use_authority: ignores our endpoints and uses a directory
authority instead
:returns: :class:`stem.Endpoint` for the location to be downloaded
from by this request
c S g | ] }|j tvr|qS r ZnicknameDIR_PORT_BLACKLIST.0Zauthr r r
Z z(Query._pick_endpoint..) r: randomchoicer0 directory Authority
from_cachevaluesr= addressdir_port)rT
use_authorityZpickedr r r _pick_endpointM s
zQuery._pick_endpointc C s zzpt | _| j|dko| jd}t|tjr/d|j|j| j f }t
|| j | j \| _ | _
n/t|tjrSd|j|j| j df | _| j}t| j| j |\| _ | _
n td|t|jf t | j | _td|| jf W nO t d }|d ur|t | j 8 }|dkr|d u s|dkrtd | j||f | |d | Y W d
| _ S td | j|f || _ Y W d
| _ d S W d
| _ d S d
| _ w ) Nr )rv zORPort %s:%s (resource %s)zhttp://%s:%i/%sr' z=BUG: endpoints can only be ORPorts or DirPorts, '%s' was a %sz'Descriptors retrieved from %s in %0.2fsr) zCUnable to download descriptors from '%s' (%i retries remaining): %sTz,Unable to download descriptors from '%s': %s) timerG rw rB r. r0 r> rt portr? _download_from_orportr@ rC rL r= lstriprF _download_from_dirportr+ r6 r7 rI r Ztracesysexc_infodebugr[ rE rD )rT rA rH rV Zdownloaded_fromre r r r r[ _ s4
zQuery._download_descriptorsF)r7
__module__ __qualname____doc__r- r r0 r3 DocumentHandlerZENTRIESrW rR rS r] rf rw r[ r r r r r% s (O
/
r% c @ sz e Zd ZdZd ddZdd Zdd Zd d
d Zd d d
Zdd Z d ddZ
dd Z d ddZ dd Z
dd Zdd Zd S ) r a
Configurable class that issues :class:`~stem.descriptor.remote.Query`
instances on your behalf.
:param bool use_mirrors: downloads the present consensus and uses the directory
mirrors to fetch future requests, this fails silently if the consensus
cannot be downloaded
:param default_args: default arguments for the
:class:`~stem.descriptor.remote.Query` constructor
Fc
K sv || _ d | _|r9zt }| tdt | W d S ty8 } ztd| W Y d }~d S d }~ww d S )Nz)Retrieved directory mirrors (took %0.2fs)z(Unable to retrieve directory mirrors: %s)
_default_args
_endpointsrx use_directory_mirrorsr r Exception)rT Z use_mirrorsZ default_argsrG re r r r rW s z DescriptorDownloader.__init__c C s dd t jj D }tdd |D }t| jt jj j
d d }|j D ]}t j
j|jv r?|jr?||j|jf q*t|| _|S )aB
Downloads the present consensus and configures ourselves to use directory
mirrors, in addition to authorities.
:returns: :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`
from which we got the directory mirrors
:raises: **Exception** if unable to determine the directory mirrors
c S rg r rh rj r r r rl rm z>DescriptorDownloader.use_directory_mirrors..c S s g | ]}|j |jfqS r )rt ru )rk rp r r r rl s )rK r )r0 rp rq rr rs setr\ r r3 r DOCUMENTrS ZroutersFlagZV2DIRflagsru addrt r )rT Z directoriesZ
new_endpoints consensusrd r r r r s
z*DescriptorDownloader.use_directory_mirrorsc K | j di |S )a)
Provides the server descriptor of the relay we're downloading from.
.. versionadded:: 1.7.0
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the server descriptors
/tor/server/authorityN)r queryrT r r r r r s z,DescriptorDownloader.their_server_descriptorNc K P d}t |tr
|g}|r t|tkrtdt dd| }| j|fi |S )a~
Provides the server descriptors with the given fingerprints. If no
fingerprints are provided then this returns all descriptors known
by the relay.
:param str,list fingerprints: fingerprint or list of fingerprints to be
retrieved, gets all descriptors if **None**
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the server descriptors
:raises: **ValueError** if we request more than 96 descriptors by their
fingerprints (this is due to a limit on the url length by squid proxies).
z/tor/server/allJUnable to request more than %i descriptors at a time by their fingerprintsz/tor/server/fp/%s+r. r/ r< MAX_FINGERPRINTSr+ r_ r rT r r r? r r r r
z+DescriptorDownloader.get_server_descriptorsc K r )a
Provides the extrainfo descriptors with the given fingerprints. If no
fingerprints are provided then this returns all descriptors in the present
consensus.
:param str,list fingerprints: fingerprint or list of fingerprints to be
retrieved, gets all descriptors if **None**
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the extrainfo descriptors
:raises: **ValueError** if we request more than 96 descriptors by their
fingerprints (this is due to a limit on the url length by squid proxies).
z/tor/extra/allr z/tor/extra/fp/%sr r r r r r r r z.DescriptorDownloader.get_extrainfo_descriptorsc K sD t |tr|g}t|tkrtdt | jdd| fi |S )a
Provides the microdescriptors with the given hashes. To get these see the
**microdescriptor_digest** attribute of
:class:`~stem.descriptor.router_status_entry.RouterStatusEntryMicroV3`.
Note that these are only provided via the **microdescriptor consensus**.
For exampe...
::
>>> import stem.descriptor.remote
>>> consensus = stem.descriptor.remote.get_consensus(microdescriptor = True).run()
>>> my_router_status_entry = list(filter(lambda desc: desc.nickname == 'caersidi', consensus))[0]
>>> print(my_router_status_entry.microdescriptor_digest)
IQI5X2A5p0WVN/MgwncqOaHF2f0HEGFEaxSON+uKRhU
>>> my_microdescriptor = stem.descriptor.remote.get_microdescriptors([my_router_status_entry.microdescriptor_digest]).run()[0]
>>> print(my_microdescriptor)
onion-key
-----BEGIN RSA PUBLIC KEY-----
MIGJAoGBAOJo9yyVgG8ksEHQibqPIEbLieI6rh1EACRPiDiV21YObb+9QEHaR3Cf
FNAzDbGhbvADLBB7EzuViL8w+eXQUOaIsJRdymh/wuUJ78bv5oEIJhthKq/Uqa4P
wKHXSZixwAHfy8NASTX3kxu9dAHWU3Owb+4W4lR2hYM0ZpoYYkThAgMBAAE=
-----END RSA PUBLIC KEY-----
ntor-onion-key kWOHNd+2uBlMpcIUbbpFLiq/rry66Ep6MlwmNpwzcBg=
id ed25519 xE/GeYImYAIB0RbzJXFL8kDLpDrj/ydCuCdvOgC4F/4
:param str,list hashes: microdescriptor hash or list of hashes to be
retrieved
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the microdescriptors
:raises: **ValueError** if we request more than 92 microdescriptors by their
hashes (this is due to a limit on the url length by squid proxies).
zIUnable to request more than %i microdescriptors at a time by their hashesz/tor/micro/d/%s-)r. r/ r< MAX_MICRODESCRIPTOR_HASHESr+ r r_ )rT r r r r r r s
& z)DescriptorDownloader.get_microdescriptorsc K s |rd}nd}|r|d| 7 }| j |fi |}|jr?|jtjjjkr?tj r?t |
d }| j di |
}| | |S )a
Provides the present router status entries.
.. versionchanged:: 1.5.0
Added the microdescriptor argument.
:param str authority_v3ident: fingerprint of the authority key for which
to get the consensus, see `'v3ident' in tor's config.c
`_
for the values.
:param bool microdescriptor: provides the microdescriptor consensus if
**True**, standard consensus otherwise
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the router status
entries
z,/tor/status-vote/current/consensus-microdescz"/tor/status-vote/current/consensusz/%sr Nr )
r rJ rK r0 r3 r r r1 Zis_crypto_availabler\ rS get_key_certificatesZvalidate_signatures)rT r r! r r? Zconsensus_queryr Z key_certsr r r r + s
z"DescriptorDownloader.get_consensusc K s0 d}d|vr|j |jfg|d< | j|fi |S )af
Provides the present vote for a given directory authority.
:param stem.directory.Authority authority: authority for which to retrieve a vote for
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the router status
entries
z"/tor/status-vote/current/authorityrV r: )rt ru r )rT Z authorityr r? r r r get_voteS s z DescriptorDownloader.get_votec K r )a
Provides the key certificates for authorities with the given fingerprints.
If no fingerprints are provided then this returns all present key
certificates.
:param str authority_v3idents: fingerprint or list of fingerprints of the
authority keys, see `'v3ident' in tor's config.c
`_
for the values.
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the key certificates
:raises: **ValueError** if we request more than 96 key certificates by
their identity fingerprints (this is due to a limit on the url length by
squid proxies).
z
/tor/keys/allzXUnable to request more than %i key certificates at a time by their identity fingerprintsz/tor/keys/fp/%sr r )rT Zauthority_v3identsr r? r r r r f s
z)DescriptorDownloader.get_key_certificatesc K r )aH
Provides the bandwidth authority heuristics used to make the next
consensus.
.. versionadded:: 1.8.0
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the bandwidth
authority heuristics
/tor/status-vote/next/bandwidthN)r r r r r r r" s z'DescriptorDownloader.get_bandwidth_filec K r )a
Provides the detached signatures that will be used to make the next
consensus. Please note that **these are only available during minutes 55-60
each hour**. If requested during minutes 0-55 tor will not service these
requests, and this will fail with a 404.
For example...
::
import stem.descriptor.remote
detached_sigs = stem.descriptor.remote.get_detached_signatures().run()[0]
for i, sig in enumerate(detached_sigs.signatures):
print('Signature %i is from %s' % (i + 1, sig.identity))
**When available (minutes 55-60 of the hour)**
::
% python demo.py
Signature 1 is from 0232AF901C31A04EE9848595AF9BB7620D4C5B2E
Signature 2 is from 14C131DFC5C6F93646BE72FA1401C02A8DF2E8B4
Signature 3 is from 23D15D965BC35114467363C165C4F724B64B4F66
...
**When unavailable (minutes 0-55 of the hour)**
::
% python demo.py
Traceback (most recent call last):
File "demo.py", line 3, in
detached_sigs = stem.descriptor.remote.get_detached_signatures().run()[0]
File "/home/atagar/Desktop/stem/stem/descriptor/remote.py", line 533, in run
return list(self._run(suppress))
File "/home/atagar/Desktop/stem/stem/descriptor/remote.py", line 544, in _run
raise self.error
stem.DownloadFailed: Failed to download from http://154.35.175.225:80/tor/status-vote/next/consensus-signatures (HTTPError): Not found
.. versionadded:: 1.8.0
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the detached
signatures
*/tor/status-vote/next/consensus-signaturesN)r r r r r r r$ s 3z,DescriptorDownloader.get_detached_signaturesc K s6 t | j}|| d|vr| j|d< t|fi |S )ar
Issues a request for the given resource.
.. versionchanged:: 1.7.0
The **fall_back_to_authority** default when using this method is now
**False**, like the :class:`~stem.descriptor.Query` class.
:param str resource: resource being fetched, such as '/tor/server/all'
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
:returns: :class:`~stem.descriptor.remote.Query` for the descriptors
:raises: **ValueError** if resource is clearly invalid or the descriptor
type can't be determined when 'descriptor_type' is **None**
r: )dictr updater r% )rT r? r rZ r r r r s
zDescriptorDownloader.queryr NNF)r7 r r r rW r r r r r r r r r" r$ r r r r r r s
.(
! 5r c C s\ | j r| j ndg}tjj| j| j|}| {}dd| ddt dd | dtj
fd }|j |d
d }| d d
\}} | d
d
\}
} |
dsYtdt| i } t|
D ]}
d|
vrotd|
|
dd
\}}|| |< qbt| | d| fW d W d S 1 sw Y W d dS 1 sw Y dS )a1
Downloads descriptors from the given orport. Payload is just like an http
response (headers and all)...
::
HTTP/1.0 200 OK
Date: Mon, 23 Apr 2018 18:43:47 GMT
Content-Type: text/plain
X-Your-Address-Is: 216.161.254.25
Content-Encoding: identity
Expires: Wed, 25 Apr 2018 18:43:47 GMT
router dannenberg 193.23.244.244 443 0 80
identity-ed25519
... rest of the descriptor content...
:param stem.ORPort endpoint: endpoint to download from
:param list compression: compression methods for the request
:param str resource: descriptor resource to download
:returns: two value tuple of the form (data, reply_headers)
:raises:
* :class:`stem.ProtocolError` if not a valid descriptor response
* :class:`stem.SocketError` if unable to establish a connection
z
zGET %s HTTP/1.0zAccept-Encoding: %s, c S | j S r encodingcr r r
z'_download_from_orport..zUser-Agent: %sz
r) )Z stream_ids
s
s
HTTP/1.0 2z5Response should begin with HTTP success, but was '%s'z: z '%s' is not a HTTP header:
%sContent-EncodingN)link_protocolsr0 ZclientZRelayZconnectrt ry Zcreate_circuitr_ map
USER_AGENTrp splitr* Z
ProtocolErrorr Z _to_unicode
splitlines _decompressget)rV r@ r? r ZrelayZcircrequestresponseZ
first_linedataZ header_dataZ body_dataheaderslinekeyvaluer r r rz s4
"rz c
C s zt jt j| dtdd |tjdd|d}W n, tjy3 } z t | |t
d |d}~w t
d d
\}}t | ||t
| |jd |jfS ) a
Downloads descriptors from the given url.
:param str url: dirport url from which to download from
:param list compression: compression methods for the request
:param float timeout: duration before we'll time out our request
:returns: two value tuple of the form (data, reply_headers)
:raises:
* :class:`~stem.DownloadTimeout` if our request timed out
* :class:`~stem.DownloadFailed` if our request fails
r c S r r r r r r r r 5 r z(_download_from_dirport..)zAccept-Encodingz
User-Agent)r )rH r& Nr) r r )urllibZurlopenZRequestr_ r r0 r socketrH ZDownloadTimeoutr} r~ ZDownloadFailedr readr r )Zurlr@ rH r re Z
stacktracer r r r| ! s"
r| c C sJ |dkr t jjj| S t jjD ]}||jkr || S qtd| )a:
Decompresses descriptor data.
Tor doesn't include compression headers. As such when using gzip we
need to include '32' for automatic header detection...
https://stackoverflow.com/questions/3122145/zlib-error-error-3-while-decompressing-incorrect-header-check/22310760#22310760
... and with zstd we need to use the streaming API.
:param bytes data: data we received
:param str encoding: 'Content-Encoding' header of the response
:raises:
* **ValueError** if encoding is unrecognized
* **ImportError** if missing the decompression module
Zdeflatez('%s' isn't a recognized type of encoding)r0 r3 r- r
decompressr r+ )r r r@ r r r r D s
r c C s | drdS | drdS | drdS | dr dS | d rR| d
s+| d r-d S | d
r4dS | dr=dt S tjj| dd rKd S | drRdS td| )Nz /tor/server/zserver-descriptor 1.0z /tor/extra/zextra-info 1.0z /tor/micro/zmicrodescriptor 1.0z
/tor/keys/zdir-key-certificate-3 1.0z/tor/status-vote/z
/consensusz
/authorityz network-status-consensus-3 1.0z/consensus-microdescz(network-status-microdesc-consensus-3 1.0z/consensus-signaturesz%s 1.0r' z
/bandwidthzbandwidth-file 1.0z0Unable to determine the descriptor type for '%s') r* r, r` r0 utilZ tor_toolsZis_valid_fingerprintr r+ )r? r r r r9 a s(
r9 c C s t S )a
Provides cached Tor directory authority information. The directory
information hardcoded into Tor and occasionally changes, so the information
this provides might not necessarily match your version of tor.
.. deprecated:: 1.7.0
Use stem.directory.Authority.from_cache() instead.
:returns: **dict** of **str** nicknames to :class:`~stem.directory.Authority` instances
)DirectoryAuthorityrr r r r r get_authorities s r r r ) sv a
q i:#