h9 dZddlZddlZddlZddlZddlZddlZddlZddl Zddl m Z m Z m Z mZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZm Z m!Z!ddlm"Z"m#Z#m$Z$m%Z%dZ&dZ'dZ(dZ)d Z*d Z+d Z,id d dddddddddddddddddddd d!d"d#d$d%d&d'd&d(d&d)d*d*d+d,d-d.d/dd0Z-d1Z.d2Z/d3\Z0Z1id4d5d6d7e1fd8d7e1fd9d7e1fd:d;d d&e1fdd;dd<dd=dd>dd?dd@de0dAfdd&e1fddBe1fd!dCd#dDid%d;d'd;d(d;dEd;dFdGe1fdHdIdJdKdLdMdNdOdPd;dQd&e1fd)dRdSdRdTdUdVdUdWdKdXdYdZd;d[Z2Gd\d]ejfd]gd^Z4Gd_d`ejfd`gdaZ5GdbdcejfdcgddZ6ddedeejnfdfZ8ddgZ9ddhZ:Gdidje Z;dkZdnZ?e`_. Documents can be obtained from a few sources... * The 'cached-consensus' file in Tor's data directory. * Archived descriptors provided by `CollecTor `_. * Directory authorities and mirrors via their DirPort. ... and contain the following sections... * document header * list of :class:`stem.descriptor.networkstatus.DirectoryAuthority` * list of :class:`stem.descriptor.router_status_entry.RouterStatusEntry` * document footer **For a great graphical overview see** `Jordan Wright's chart describing the anatomy of the consensus `_. Of these, the router status entry section can be quite large (on the order of hundreds of kilobytes). As such we provide a couple of methods for reading network status documents through :func:`~stem.descriptor.__init__.parse_file`. For more information see :func:`~stem.descriptor.__init__.DocumentHandler`... :: from stem.descriptor import parse_file, DocumentHandler with open('.tor/cached-consensus', 'rb') as consensus_file: # Processes the routers as we read them in. The routers refer to a document # with an unset 'routers' attribute. for router in parse_file(consensus_file, 'network-status-consensus-3 1.0', document_handler = DocumentHandler.ENTRIES): print router.nickname **Module Overview:** :: NetworkStatusDocument - Network status document |- NetworkStatusDocumentV2 - Version 2 network status document |- NetworkStatusDocumentV3 - Version 3 network status document +- BridgeNetworkStatusDocument - Version 3 network status document for bridges KeyCertificate - Certificate used to authenticate an authority DocumentSignature - Signature of a document by a directory authority DetachedSignature - Stand alone signature used when making the consensus DirectoryAuthority - Directory authority as defined in a v3 network status document N) PGP_BLOCK_END Descriptor DigestHashDigestEncodingTypeAnnotationDocumentHandler_descriptor_content_descriptor_components_read_until_keywords_value_values_parse_simple_line_parse_if_present_parse_timestamp_line_parse_forty_character_hex_parse_protocol_line_parse_key_block _mappings_for_random_nickname_random_fingerprint_random_ipv4_address _random_date_random_crypto_blob)RouterStatusEntryV2RouterStatusEntryBridgeV2RouterStatusEntryV3RouterStatusEntryMicroV3) )network-status-versionT) dir-sourceT fingerprintT)contactTdir-signing-keyT)client-versionsF)server-versionsF) publishedT) dir-optionsF)directory-signatureT))rTTT) vote-statusTTT)consensus-methodsTFF)consensus-methodFTF)r'TFT) valid-afterTTT) fresh-untilTTT) valid-untilTTT) voting-delayTTT)r%TTF)r&TTF)packageTTF) known-flagsTTT)flag-thresholdsTFF)shared-rand-participateTFF)shared-rand-commitTFF)shared-rand-previous-valueTTF)shared-rand-current-valueTTF)bandwidth-file-headersTFF)bandwidth-file-digestTFF)recommended-client-protocolsTTF)recommended-relay-protocolsTTF)required-client-protocolsTTF)required-relay-protocolsTTF)paramsTTF))directory-footerTTF)bandwidth-weightsFTF)r)TTTrrr?r) bwweightscale' cbtdisabled cbtnummodescbtrecentcountcbtmaxtimeouts cbtmincircsd cbtquantilePcbtclosequantile_ cbttestfreq< cbtmintimeouticbtinitialtimeout`cbtlearntimeoutcbtmaxopencircs UseOptimisticDataSupport022HiddenServices usecreatefastz%max-consensuses-age-to-cache-for-diffHP)!try-diff-for-consensus-newer-thanonion-key-rotation-daysonion-key-grace-period-dayshs_service_max_rdv_failurescirc_max_cell_queue_sizecircpad_max_circ_queued_cells"HiddenServiceEnableIntroDoSDefense) )dir-key-certificate-versionT) dir-addressFr )dir-identity-keyT)dir-key-publishedT)dir-key-expiresTr#)dir-key-crosscertF)dir-key-certificationT))consensus-digestTF)r-TF)r.TF)r/TF)additional-digestFT)additional-signatureFT)r)FT)ii circwindow)rLrcCircuitPriorityHalflifeMsec perconnbwrateperconnbwburstrefuseunknownexits)rr[)r[rH)rFrc)rFrC)r[rC)rYcr{i)rYrU)rUseNTorHandshakeFastFlagMinThresholdNumDirectoryGuards)rrYNumEntryGuards)r[rY GuardLifetime)i'iSg NumNTorsPerTAP)r[iAllowNonearlyExtendAuthDirNumSRVAgreements)ri rdre)r[Zrfrgrh)rcl)rrb)rirjceZdZdZy)PackageVersionz Latest recommended version of a package that's available. :var str name: name of the package :var str version: latest recommended version :var str url: package's url :var dict digests: mapping of digest types to their value N__name__ __module__ __qualname____doc__g/var/www/betterdocs.net/sherlock_api/venv/lib/python3.12/site-packages/stem/descriptor/networkstatus.pyrrsrr)nameversionurldigestsceZdZdZy)SharedRandomnessCommitmenta Directory authority's commitment for generating the next shared random value. :var int version: shared randomness protocol version :var str algorithm: hash algorithm used to make the commitment :var str identity: authority's sha1 identity fingerprint :var str commit: base64 encoded commitment hash to the shared random value :var str reveal: base64 encoded commitment to the shared random value, **None** of not provided Nrrrrrrs rr)r algorithmidentitycommitrevealceZdZdZy)DocumentDigestz Digest of a consensus document. .. versionadded:: 1.8.0 :var str flavor: consensus type this digest is for (for example, 'microdesc') :var str algorithm: hash algorithm used to make the digest :var str digest: digest value of the consensus Nrrrrrrsrr)flavorrdigestFc +K|t}|tk(r tt}}n`|tk(r|rtnt}nH|t k(r t t }}n2|tk(r||j|fi|ytd|z|tjk(r||j|fi|yttttf|}|r|dj!dr|dd}|j#}tttf|d|j#} |j%} t&j)d|| z} |tj*k(r || |fi|y|tj,k(rIt/j0j2j4||f|t|| || |fd |} | D]} | ytd |zw) a Parses a network status and iterates over the RouterStatusEntry in it. The document that these instances reference have an empty 'routers' attribute to allow for limited memory usage. :param file document_file: file with network status document content :param class document_type: NetworkStatusDocument subclass :param bool validate: checks the validity of the document's contents if **True**, skips these checks otherwise :param bool is_microdescriptor: **True** if this is for a microdescriptor consensus, **False** otherwise :param stem.descriptor.__init__.DocumentHandler document_handler: method in which to parse :class:`~stem.descriptor.networkstatus.NetworkStatusDocument` :param dict kwargs: additional arguments for the descriptor constructor :returns: :class:`stem.descriptor.networkstatus.NetworkStatusDocument` object :raises: * **ValueError** if the document_version is unrecognized or the contents is malformed and validate is **True** * **IOError** if the file can't be read NzIDocument type %i isn't recognized (only able to parse v2, v3, and bridge)rs@typer[T)skipr) entry_class entry_keywordstart_position end_position extra_argsz!Unrecognized document_handler: %s)NetworkStatusDocumentV3NetworkStatusDocumentV2rrrBridgeNetworkStatusDocumentrDetachedSignatureread ValueErrorrDOCUMENTr ROUTERS_START FOOTER_STARTV2_FOOTER_START startswithtell readlinesbytesjoin BARE_DOCUMENTENTRIESstem descriptorrouter_status_entry _parse_file) document_file document_typevalidateis_microdescriptordocument_handlerkwargs router_typeheader routers_start routers_endfooterdocument_content desc_iteratordescs rrr(s4+M--!8:M;M//.@*FYK33!<>W;M))  **,h A& AA `cpp qq111  **,h A& AA   o NP] ^& q $$X. ABZF$$&- o6 dS""$+  " " $&ZZVf_5666 (( =f ==?222OO77CC  #$ !"2H=?   M j 8;KK LLsGGc#K td|}tjddd}|t||dz }|rBtjj j tjd||ny{w) a Parses a file containing one or more authority key certificates. :param file certificate_file: file with key certificates :param bool validate: checks the validity of the certificate's contents if **True**, skips these checks otherwise :returns: iterator for :class:`stem.descriptor.networkstatus.KeyCertificate` instances in the file :raises: * **ValueError** if the key certificates are invalid and validate is **True** * **IOError** if the file can't be read Trq r[rrrN) r rsplitrr networkstatusKeyCertificaterr)certificate_filerkeycert_contentblock_end_prefixs r_parse_file_key_certsrws *+BDTUO%**3215+,<>NPTUUO OO ) ) 8 8C9Yfn 8 oo  sA=A?c#K td|d}|rBtjjj t j d||nyTw)a Parses a file containing one or more detached signatures. :param file detached_signature_file: file with detached signatures :param bool validate: checks the validity of the detached signature's contents if **True**, skips these checks otherwise :returns: iterator for :class:`stem.descriptor.networkstatus.DetachedSignature` instances in the file :raises: * **ValueError** if the detached signatures are invalid and validate is **True** * **IOError** if the file can't be read Trr) ignore_firstrrN)r rrrrrr)detached_signature_filerdetached_sig_contents r_parse_file_detached_sigsrsU /0BD[lpq OO ) ) ; ;EJJsL`;M;M}rrcfd}|S)Nct|}|jstdd|t|t |t |k7rtd|fzy)Nz$Document has a non-numeric version: rz._parsesb 7G $E ==? guU VV J 3u:. 5z%% UYikpXqq rr&rr)rrrrs``` r_parse_version_liners s -rctd|}|j}t|dkrtd|z|dstd|ztj j j|dstd|dztj j j|dd std |dz|d|_ |d|_ |dd k(rd|_ yt|d|_ y) NrrFz[The 'dir-source' line of a v2 network status document must have three values: dir-source %sr2Authority's hostname can't be blank: dir-source %sr[2Authority's address isn't a valid IPv4 address: %sraT allow_zero"Authority's DirPort is invalid: %s0) r rlenrrutil connectionis_valid_ipv4_address is_valid_porthostnameaddressrdir_portrrrdir_source_comps r_parse_dir_source_liners w '%KKM/A ruzz {{   IEQ RR 99   5 5oa6H I IO\]L^^ __ 99   - -oa.@t - T 9OAD 4y1} CFII JJ NN>48,- .#**rc g}|dD]t\}}}|jd}t|dkrtd|z|r|dk7rtd|z|jt |d|d|d ||d d v||_y) Nrtrrzadditional-signature lines should be of the form 'additional-signature [flavor] [algname] [identity] [signing_key_digest]' but was: %s SIGNATUREzL'additional-signature' should be followed by a SIGNATURE block, but was a %sr[rarFrT)rr)rrrrDocumentSignatureadditional_signatures)rr signaturesr  block_typeblock_contentsr s r_parse_additional_signaturesrs*)01G)Hw%c:~ 99S>D 4y1} `cff gg z[8 ehrr ss'Qa$q'>\`ab\cptuvw&0*"rrrr!r"r$ signing_keyRSA PUBLIC KEYr%client_versionsc$|jdSN,rvs rrhihohopshtr)funcr&server_versionsc$|jdSrrrs rrrrrr'r(optionsc"|jSNrrs rrrsXYX_X_Xar signaturersigning_authority)value_attributerrconsensus_digestceZdZdZdZdefdefdefdefdefdefde fge fge fde fge fdefdefd Zeeeee e e e e ed Zed dZd fd ZdZxZS) ra Version 2 network status document. These have been deprecated and are no longer generated by Tor. :var dict routers: fingerprints to :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` contained in the document :var int version: **\*** document version :var str hostname: **\*** hostname of the authority :var str address: **\*** authority's IP address :var int dir_port: **\*** authority's DirPort :var str fingerprint: **\*** authority's fingerprint :var str contact: **\*** authority's contact information :var str signing_key: **\*** authority's public signing key :var list client_versions: list of recommended client tor version strings :var list server_versions: list of recommended server tor version strings :var datetime published: **\*** time when the document was published :var list options: **\*** list of things that this authority decides :var str signing_authority: **\*** name of the authority signing the document :var str signature: **\*** authority's signature for the document **\*** attribute is either required when we're parsed with validation or has a default value, others are left as **None** if undefined znetwork-status-2N) rrrrr!r"rrr!r'r#r'r) rrr!r"r$r%r&r'r(r)c |rtd|jzt||ddtdtdfdt fddt fd t d ffd d t d zffS)NSigning of %s not implemented)r2rrz 80r!)r"zarma at mit dot edur'r$rr)moria2r)rrr rrrrclsattrexcludesigns rrzNetworkStatusDocumentV2.contentXs  ?#,, N OO tW%#7#9;O;QRS)+,(LN#-.>?@ /h)<[)IIJ  rcNtt| || tj|}t j dtttf|}tjjj||tttf|f}td|D|_t#|dz|j%z|}|rR|j'||j)||d|j*vr d|vrd|vst-d t/|zyy||_y) N lazy_loadrrrsection_end_keywordsrc38K|]}|j|fywr%r!.0rs r z3NetworkStatusDocumentV2.__init__..|IT))40I Versionsr%r&zVersion 2 network status documents must have a 'client-versions' and 'server-versions' when 'Versions' is listed among its dir-options: %s)superr__init__ioBytesIOrrr rrrrrrrdictroutersr r_check_constraintsrr#rstr_entries)r raw_contentrrr router_iterr __class__s rrCz NetworkStatusDocumentV2.__init__hs6 !41+x<1XJJ{+Mzz#';]O<\^k'lm//55AA'#-/7 BKI[IIDL$%5%= @R@R@T%TV^_G g& kk'8$ t|| #->'-IN_cjNjgjmnrjsst tOk #dmrc tDcgc] \}}|s | }}}|D] }||vstd|dt|tDcgc]\}}| }}}|D]>}||vst||dkDstd|t||t|fzdt |j dk7rtdt|zycc}}wcc}}w)Nz*Network status document (v2) must have a '' line: r[zINetwork status document (v2) can only have a single '%s' line, got %i: %srrz[Network status document (v2) are expected to start with a 'network-status-version' line: %s)NETWORK_STATUS_V2_FIELDSrrIrlistkeys)rrfield is_mandatoryrequired_fieldsr_ single_fieldss rrHz*NetworkStatusDocumentV2._check_constraintss8:Rc!6%VbucOc"k  V]_bcg_hijjk .FFzqUFMF U G GG$4 5 9eipruv}FwGsHJMNRJSiTTU UU 4 #7#:: ux{}AyBB CC;d Gs CC CNrFF)rrrrTYPE_ANNOTATION_NAME"_parse_network_status_version_liner_parse_fingerprint_line_parse_contact_line_parse_dir_signing_key_line_parse_client_versions_line_parse_server_versions_line_parse_published_line_parse_dir_options_line_parse_directory_signature_line ATTRIBUTESPARSER_FOR_LINE classmethodrrCrH __classcell__rMs@rrrs8,89-.,--.12)*567878-.+, ?@89*&A(*"222&*: /  "H Crrc$td|}d|vr|jdd\}}n|d}}|jstd|zt ||_||_|dk(|_|j dk7rtd|j zy) Nrrr[nszLNetwork status document has a non-numeric version: network-status-version %s microdescrFzFExpected a version 3 network status document, got version '%s' instead)r rrrrrversion_flavorr)rrrrrs r)_parse_header_network_status_version_linerms )7 3%E\kk#q)OGVTVG   cfkk ll7|*$*"(K"7*1 ]`j`r`rr ssrctd|}|dk(rd\|_|_y|dk(rd\|_|_ytd|z)Nr* consensus)TFvoteFTz`A network status document's vote-status line can only be 'consensus' or 'vote', got '%s' instead)r is_consensusis_voterrrrs r_parse_header_vote_status_linerusW  (% k2=/JZ/ 2=/JZ/ wz AArc |jr|jrdg|_td|g}}|j dD]:}|j st d|z|jt|<||_y)Nr[r+rz\A network status document's consensus-methods must be a list of integer values, but was '%s') _lazy_loadingrsconsensus_methodsr rrrrr)rrrrxentrys r$_parse_header_consensus_methods_linerzs*"4"4$%3J #$7A2 %{{3)e ==? ux}} ~~SZ( ) "3*rc|jr|jrd|_td|}|j st d|zt ||_y)Nr[r,zMA network status document's consensus-method must be an integer, but was '%s')rwrrconsensus_methodr rrrrts r#_parse_header_consensus_method_liner}sQ*"9"9"#J #W -%  dgll mm #E *rctd|}|jd}t|dk(rM|djr:|djr't |d|_t |d|_ytd|z)Nr0rrarr[z^A network status document's 'voting-delay' line must be a pair of integer values, but was '%s')r rrrr vote_delay dist_delayrrrr value_comps r_parse_header_voting_delay_liners|  )%{{3*_jm335*Q-:O:O:Q 1 .J 1 .J ux}} ~~rcfd}|S)Nc t|g}}|jdD]1} |jtjj |3t||y#t $rt dd|dd|wxYw)NrzNetwork status document's 'z ' line had 'z'', which isn't a parsable tor version: r)r rrrr _get_versionrr)rrrryrrs rrz$_parse_versions_line.._parsesGW-r7ES!WWt||0078W  J 7+Wv}@EGNPUVW WWs .A##!Br)rrrs`` r_parse_versions_liners , -rc Ztd|ji}}td|D]^\}} |jdr&t d|ddj dddz||<n!d|vrt |||<nt |||<`||_y#t$rtd|zwxYw) Nr3%z0.rw.r[zjNetwork status document's 'flag-thresholds' line is expected to have float values, got: flag-thresholds %s) r striprendswithfloatreplacerrflag_thresholds)rrr thresholdskeyr s r"_parse_header_flag_thresholds_liners.8>>@"% 159 Mhc3 M c   s3Bx'7'7R'C CD 3 #:* 3c( 3 M ** M DGLL MMMs ABB*c|jr"|jrttni|_t d|}|dk7r#t d|d|_|jyy)Nr>rT)rw_default_paramsrFDEFAULT_PARAMSr>r _parse_int_mappings_check_params_constraintsrts r_parse_header_parameters_linersZ 0:0J0J^,PRJ 7 #% b[+HeTBJ((*rc<td|}|rtd|zy)Nr?ziA network status document's 'directory-footer' line shouldn't have any content, got 'directory-footer %s')r rrts r_parse_directory_footer_liner$s; #W -% ADII JJ rc `g}|dD]\}}}|jddvrtd|z|r|dk7rtd|z|jddk(rd}|jdd\}}n|jdd \}}}|jt ||||d ||_y) Nr)r)r[razAuthority signatures in a network status document are expected to be of the form 'directory-signature [METHOD] FINGERPRINT KEY_DIGEST', received: %srzK'directory-signature' should be followed by a SIGNATURE block, but was a %sr[rraTr)countrrrrr) rrr sig_valuerrmethodr! key_digests r&_parse_footer_directory_signature_liner-s*/67L/M k+i^s6) nqzz {{ Z;6 dgqq rrsq f )Q 7k:(1Q(?%fk:' Zdhij k%*rc 2g}|dD]\}}}|jdd}t|dkrtd|z|dd\}}}i} t|dk(rtd|dD] \} } | | | < |j t |||| ||_y)Nr1rrFz<'package' must at least have a 'PackageName Version URL': %sr)rrrrrrpackages) rrpackage_versionsrrVrrrrrrr s r_parse_package_linerBsY' IkeQS!$J : UX]] ^^#BQD'3G :!#Iz!}=(#s N4#wGH I)*rc Rg}|dD]\}}}|j}t|dkrtd|z|dd\}}}} t|dk\r|dnd} |jstd|z|j t t |||| | ||_y)Nr5rzO'shared-rand-commit' must at least have a 'Version AlgName Identity Commit': %szBThe version on our 'shared-rand-commit' line wasn't an integer: %s)rrrrrrrshared_randomness_commitments) rr commitmentsrrVrrrrrrs r_parsed_shared_rand_commitrWs+12 fkeQJ : hkpp qq+5bq>(GY&!*o2Z]F ??  [^cc dd1#g, 8U[]cde f.9**rctd|}|jd}t|dk(r1|djrt |d|_|d|_ytd|z)Nr6rrarr[zyA network status document's 'shared-rand-previous-value' line must be a pair of values, the first an integer but was '%s')r rrrr'shared_randomness_previous_reveal_count shared_randomness_previous_valuerrs r!_parse_shared_rand_previous_valuermsy -w 7%{{3*_jm3359wxw~w~@CxDdNnsHMdidNdNs##r@bandwidth_weightsctd|dS)Nr@T)rrs rrrs'vIJ]_`bfvgrr4 is_shared_randomness_participater:recommended_client_protocolsr;recommended_relay_protocolsr<required_client_protocolsr=required_relay_protocolsceZdZdZiddefddefddefdd efd d efd gefd defd defdde fdde fdde fdde fdde fdge fdgefdgefdgefiefiefiefiefiefiefdefdefdefdefiefiefgefiefdZidedededed ede de de de d e d!ed"ed#ed$ed%ed&ed'eeeeeeed(Zeeed)Z e!d6d*Z"e!d7d+Z#d8fd, Z$d-Z%d.Z&d/Z'd0Z(fd1Z)d2Z*d3Z+d4Z,d5Z-xZ.S)9ra Version 3 network status document. This could be either a vote or consensus. :var dict routers: fingerprint to :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` mapping for relays contained in the document :var int version: **\*** document version :var str version_flavor: **\*** flavor associated with the document (such as 'ns' or 'microdesc') :var bool is_consensus: **\*** **True** if the document is a consensus :var bool is_vote: **\*** **True** if the document is a vote :var bool is_microdescriptor: **\*** **True** if this is a microdescriptor flavored document, **False** otherwise :var datetime valid_after: **\*** time when the consensus became valid :var datetime fresh_until: **\*** time when the next consensus should be produced :var datetime valid_until: **\*** time when this consensus becomes obsolete :var int vote_delay: **\*** number of seconds allowed for collecting votes from all authorities :var int dist_delay: **\*** number of seconds allowed for collecting signatures from all authorities :var list client_versions: list of recommended client tor versions :var list server_versions: list of recommended server tor versions :var list packages: **\*** list of :data:`~stem.descriptor.networkstatus.PackageVersion` entries :var list known_flags: **\*** list of :data:`~stem.Flag` for the router's flags :var dict params: **\*** dict of parameter(**str**) => value(**int**) mappings :var list directory_authorities: **\*** list of :class:`~stem.descriptor.networkstatus.DirectoryAuthority` objects that have generated this document :var list signatures: **\*** :class:`~stem.descriptor.networkstatus.DocumentSignature` of the authorities that have signed the document **Consensus Attributes:** :var int consensus_method: method version used to generate this consensus :var dict bandwidth_weights: dict of weight(str) => value(int) mappings :var int shared_randomness_current_reveal_count: number of commitments used to generate the current shared random value :var str shared_randomness_current_value: base64 encoded current shared random value :var int shared_randomness_previous_reveal_count: number of commitments used to generate the last shared random value :var str shared_randomness_previous_value: base64 encoded last shared random value **Vote Attributes:** :var list consensus_methods: list of ints for the supported method versions :var datetime published: time when the document was published :var dict flag_thresholds: **\*** mapping of internal performance thresholds used while making the vote, values are **ints** or **floats** :var dict recommended_client_protocols: recommended protocols for clients :var dict recommended_relay_protocols: recommended protocols for relays :var dict required_client_protocols: required protocols for clients :var dict required_relay_protocols: required protocols for relays :var dict bandwidth_file_headers: headers from the bandwidth authority that generated this vote :var dict bandwidth_file_digest: hashes of the bandwidth authority file used to generate this vote, this is a mapping of hash functions to their resulting digest value **\*** attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined .. versionchanged:: 1.4.0 Added the packages attribute. .. versionchanged:: 1.5.0 Added the is_shared_randomness_participate, shared_randomness_commitments, shared_randomness_previous_reveal_count, shared_randomness_previous_value, shared_randomness_current_reveal_count, and shared_randomness_current_value attributes. .. versionchanged:: 1.6.0 Added the recommended_client_protocols, recommended_relay_protocols, required_client_protocols, and required_relay_protocols attributes. .. versionchanged:: 1.6.0 The is_shared_randomness_participate and shared_randomness_commitments were misdocumented in the tor spec and as such never set. They're now an attribute of votes in the **directory_authorities**. .. versionchanged:: 1.7.0 The shared_randomness_current_reveal_count and shared_randomness_previous_reveal_count attributes were undocumented and not provided properly if retrieved before their shred_randomness_*_value counterpart. .. versionchanged:: 1.7.0 Added the bandwidth_file_headers attributbute. .. versionchanged:: 1.8.0 Added the bandwidth_file_digest attributbute. rNrlrjrrTrsFrrxr'r|rrrrrrr!rr)rrrrrr>rrrrrrrrrr*r+r,r-r.r/r0r%r&r1r2r3r:r;r<)r=r>r6r7r8r9)r?r@r)c|rtd|jz|in t|}|jddk(}|rdt d}nddi}|r|t j |g}|jD]\}} |r||vr ||vs| ||<t||d d d d d dt fdt fdt fddddddfdddtdttdff} |rd| vr| jddz} n.d| vr| jd dz} n|r| d!z } t| dz} tjjj!d"j#|D cgc] } t%| c} d"z} | d| | z| | dz} |rd| vr| jddz} n.d| vr| jd dz} n|r| d!z } t| dz} tjjj!d"j#|Dcgc] }t%|c}d"z}| d| |z| | dz} | Scc} wcc}w)#Nr,r*rpz1 9)r+r'r,9)rs)r3)r*ro)r+N)r,N)r'Nr-r.r/)r0z300 300)r%N)r&N)r1N)r2zPAuthority BadExit Exit Fast Guard HSDir Named Running Stable Unnamed V2Dir Valid)r>N)r?r)r@Nr)rrsdirectory-footers directory-footerr[sdirectory-signatures directory-signaturer@ )rrrFgetrDirectoryAuthoritycreateitemsr rrfindrrr str_tools _to_bytesrrI)r0r1r2r3 authoritiesrGrsextra_defaultskr desc_content footer_divaauthority_contentrArouter_contents rrzNetworkStatusDocumentV3.contentSs  ?#,, N OO24:Dhh}%/G-2Pn*C0n;&'...ABk$$&1 Q'\ D=Q  'tW%"! ln%ln%ln%!i7 !+>+@BUBWYlmxYyz{L.  ,!&&'<=A !\ 1!&&'?@1D  % ,&* ))--77 S^B_a3q6B_8`cg8gh!+:.1BB\R\R]E^^l  ,!&&'<=A !\ 1!&&'?@1D  % ,&* yy**44TYYPW?X1A?X5Y\`5`an!+:.?,z{B[[l #C`@Ys 0I I c <||j||||||S)Nrr)r0r1r2rr3rrGs rrzNetworkStatusDocumentV3.creates! s{{4$ WERZ [[rc tt| || tj|}d|_g|_||_|j||ttjjj||ttt t"t$f|j&f|_|rQ|j&rEt+|j(dk7r-t-dt+|j(|j(fztjjj|||j.rt0nt2t t"t$f|f}t5d|D|_|j9||y)a~ Parse a v3 network status document. :param str raw_content: raw network status document data :param bool validate: **True** if the document is to be validated, **False** otherwise :param bool default_params: includes defaults in our params dict, otherwise it just contains values from the document :raises: **ValueError** if the document is invalid r5Fr7r[zPVotes should only have an authority entry for the one that issued it, got %i: %sc38K|]}|j|fywr%r:r;s rr=z3NetworkStatusDocumentV3.__init__..r>r?N)rBrrCrDrErrr_headertuplerrrrr AUTH_STARTrrrrsdirectory_authoritiesrrrrrrFrG_footer)rrKrdefault_paramsrrLrMs rrCz NetworkStatusDocumentV3.__init__sn !41+x<1XJJ{+M -2D))+D&)DLL)!&t'J'J'V'V& +\?KLL? (W("DDLLS)C)C%D%I impqurLrLnMOSOiOimjj kk//55AA040G0G,M`#*O<7 BKI[IIDLLL)rct|tr tdddS|js!t|jsdddSdddStdddS)Nbridge-network-statusr[rznetwork-status-consensus-3znetwork-status-vote-3z$network-status-microdesc-consensus-3) isinstancerrrrsrs rtype_annotationz'NetworkStatusDocumentV3.type_annotations_$34 3Q ::  $ $  8klno ppRiklno pp BAq IIrc|jtjjcxkxr|jkScS)aJ Checks if the current time is between this document's **valid_after** and **valid_until** timestamps. To be valid means the information within this document reflects the current network state. .. versionadded:: 1.8.0 :returns: **True** if this consensus is presently valid and **False** otherwise )rdatetimeutcnowrrs ris_validz NetworkStatusDocumentV3.is_valid5   h//668 K4;K;K KK KKrc|jtjjcxkxr|jkScS)a& Checks if the current time is between this document's **valid_after** and **fresh_until** timestamps. To be fresh means this should be the latest consensus. .. versionadded:: 1.8.0 :returns: **True** if this consensus is presently fresh and **False** otherwise )rrrrrs ris_freshz NetworkStatusDocumentV3.is_freshrrc |jdd}tj|jj }d\}}t |j dz }t|Dcgc]}|j|jfc}}|j D]J} | j|vr|j|| j| j} |dz }| |k(sF|dz }L||krtd|||fzycc}w)a7 Validates we're properly signed by the signing certificates. .. versionadded:: 1.6.0 :param list key_certs: :class:`~stem.descriptor.networkstatus.KeyCertificates` to validate the consensus against :raises: **ValueError** if an insufficient number of valid signatures are present. rzdirectory-signature )rrg@r[zJNetwork Status Document has %i valid signatures out of %i total, needed %iN)rrr hexdigestupperrrrFr!rr_digest_for_signaturer&r) r key_certsdigest_content local_digest valid_digests total_digestsrequired_digestscert signing_keyssig signed_digests rvalidate_signaturesz+NetworkStatusDocumentV3.validate_signaturess(()ACYZN<</99;AACL#' M=4??+c1)T$$**D,<,<=TUL \ )00cll1KS]][mqm , & '' cgtwDFVgWW XX(Us*Dc|jrW|j|jd|j|j|jd|j d|_t t|#S)NFparser_for_line) rwr_header_entries_HEADER_PARSER_FOR_LINE_footer_entries_FOOTER_PARSER_FOR_LINErBrget_unrecognized_lines)rrMs rrz.NetworkStatusDocumentV3.get_unrecognized_linessa  kk$&&A]A]k^ kk$&&A]A]k^ d ($ F HHrc|j|j|k\S|j)t|jDcgc] }||k\s | c}Sycc}w)a8 Checks if we meet the given consensus-method. This works for both votes and consensuses, checking our 'consensus-method' and 'consensus-methods' entries. :param int method: consensus-method to check for :returns: **True** if we meet the given consensus-method, and **False** otherwise F)r|rxbool)rrxs rmeets_consensus_methodz.NetworkStatusDocumentV3.meets_consensus_method%sX (  " "f ,,   + d44DV 1D EE Es AAc>tjdtttt f|}t ||}tDcgc]}|d }}|r"t|jD]=\}}t|dkDs||vs|dk7s |dk7s&td|t|fz|jrtt|_|j!|||j"|j%ds&d t|j'vr td t)||t|j*r|j,sd|_y|j.r|j0s dg|_yyy||_|j4j7|ycc}w) Nrrr[r1r5ANetwork status documents can only have a single '%s' line, got %irr`r>z[A network status document's 'params' line should only appear in consensus-method 7 or later)rrr rrrr HEADER_STATUS_DOCUMENT_FIELDSrQrrrrrFrr>rrr rR(_check_for_missing_and_disallowed_fieldsrrr|rsrxrrJupdate) rrrrrr1 header_fieldsrvaluess rrzNetworkStatusDocumentV3._header7sqjj2J |3\^klmG$Wh7G)FGT!WGMG"'--/2y/'6 v;?w-7Gy*  kk'8t7S7SkT ( ( +D[\   4#8#8 ! << 6 6"#!7<%d mm7#;Hs Fct|j|}tDcgc]}|d }}|rt|j D]C\}}t |dkDs||vs|dk(r |j r,td|t |fz|j|||j|rw|jdr*t|jddk7r5tdt|jddk7r td t||tyy||_ |jj|ycc}w) Nrr[r)r r r?zkNetwork status document's footer should start with a 'directory-footer' line in consensus-method 9 or laterzkNetwork status document's footer should start with a 'directory-signature' line prior to consensus-method 9)r rFOOTER_STATUS_DOCUMENT_FIELDSrQrrrrrrrr rRrrrJr)rrrrr1 footer_fieldsrrs rrzNetworkStatusDocumentV3._footerYsQ$]%7%7%98DG)FGT!WGMG!'--/2{/'6 v;?w-722t7H7H`dkmpqwmxcyyz z { kk'8t7S7SkT   & &q ) ',,. !! $(: :KL L ',,. !! $(= =KL L0w@]^ %d mm7#9Hs E cL|jjD]\}}tj|tt f\}}|dk(r|jjd|}n!|dk(r|jjd|}||ks||kDswt d||||fzy)zR Checks that the params we know about are within their documented ranges. rOrMrTrSzE'%s' value on the params line must be in the range of %i - %i, was %iN)r>r PARAM_RANGEr MIN_PARAM MAX_PARAMr)rrrminimummaximums rrz1NetworkStatusDocumentV3._check_params_constraintsys kk'') C U$y).DEgw " "++//-9 % %++///7; EGO`dgipry|AdBBC C Cr)NrFNN)NrTFNNrq)/rrrrrmrurzrar}_parse_header_valid_after_line_parse_header_fresh_until_line_parse_header_valid_until_liner"_parse_header_client_versions_line"_parse_header_server_versions_liner_parse_header_known_flags_liner(_parse_recommended_client_protocols_line'_parse_recommended_relay_protocols_line%_parse_required_client_protocols_line$_parse_required_relay_protocols_linerrrrrr$_parse_footer_bandwidth_weights_linerdrrrrfrrrCrrrrrr rrrrgrhs@rrrs=]~! ?@!tFG!T9:!56 ! 5"KL ! "BC !$-.!BC!D89!D89!D89!489!489!>?!>?! ()!!"B67#!$>?%')Q$R$&(O#P"$&K!L!#%I J01046W/X)-/P(Q/35U.V(,.N'O!#@A ">?=>BCA!*FG1=;  &  1 11399"19#$L "#J!" !F#$!E+"C!A;9/65=A HHT\\/*b J L L XDI$ $D$@Crrcgg}}|D]\}}}}|rA|jr|s|jr'|r%||jvs9|j|K|jr|r|jsf|ri||jvs||j||rt ddj |z|rt ddj |zy)a# Checks that we have mandatory fields for our type, and that we don't have any fields exclusive to the other (ie, no vote-only fields appear in a consensus or vice versa). :param NetworkStatusDocumentV3 document: network status document :param dict entries: ordered keyword/value mappings of the header or footer :param list fields: expected field attributes (either **HEADER_STATUS_DOCUMENT_FIELDS** or **FOOTER_STATUS_DOCUMENT_FIELDS**) :raises: **ValueError** if we're missing mandatory fields or have fields we shouldn't z6Network status document is missing mandatory field: %sz, z]Network status document has fields that shouldn't appear in this document type or version: %sN)rrrsrRrrr) documentrfieldsmissing_fieldsdisallowed_fieldsrSin_votes in_consensus mandatorys rrrs')"#.28(.eX|Yx,,8CSCSX` glln $e$    (:J:JS[ ',,.   '( MPTPYPYZhPii jj tw{xAxABSxTT UUrc2ig}}d|d|d}t||D]\\}}|r|D]}||kDs t|dz |jdr tt|||<|j |^|S#t$rt|d|zzwxYw)Nz+Unable to parse network status document's 'z ' line (%s): 'z¶meters must be sorted by their key+z'%s' is a non-numeric value)rrrrr) rrrr seen_keyserror_templaterr  prior_keys rrrs 29'W^`ef./hc3 V) s?>,TTU UVO  lXgclS#& . O ~)F)LM NNOs )A;;Bctd|}|jd}t|dkrtd|ztj j j|djdstd|dztj j j|dstd |dz|d std |ztj jj|d std |d ztj jj|ddstd|dztj jj|dstd|dz|d|_ |d|_|d |_|d |_|ddk(rdn t#|d|_t#|d|_|jj)d|_y)NrrzGAuthority entry's 'dir-source' line must have six values: dir-source %sr-legacyz#Authority's nickname is invalid: %sr[z"Authority's v3ident is invalid: %srarrFrrTrrrz!Authority's ORPort is invalid: %sr)r rrrrr tor_toolsis_valid_nicknamerstripis_valid_fingerprintrrrnicknamev3identrrrror_portr is_legacyrs r_parse_dirauth_source_linerAs w '%KK$/A ^aff gg    . .q/A/H/H/S T :_Q=OO PP 99   3 3OA4F G 9OArrrr?r@Fr"rErCrrrrrr)rr"rBrDr4r5r6r7c &|rtd|jz|in t|}|sd|vs|rd|vs t|d<t ||dt dtdt dfdf}|r|dtjzz }|S) Nr,rDrrz no.place.com z 9030 9090)r"zMike Perry r@) rrrFrr rrrr)r0r1r2r3rsrs rrzDirectoryAuthority.contentEs  ?#,, N OO24:D MT1g-SZBZ/1d=!$:J:LNaNceye{|}'2G  //111g Nrc<||j||||||S)N)rrsr)r0r1r2rr3rss rrzDirectoryAuthority.create[s! s{{4$8XY` aarc tt| || tjj j |}|jd}|dk7r t||dzd||_ |d|dz}nd|_ t||}|r-dt|jdk7rtd|z|r9d |jd}}|r(|ddjdj!d }dgg} } |s| d gz } |r!|jstd |z| d gz } n*|s(|jrtd|z|s| d gz } | dgz } | D]} | |vstd| d||D] } | | vs|rdnd} td| d| d|t|j#D]2\} } t%| dkDs| dvstd| t%| |fz|j'||n||_|j*|_y)a Parse a directory authority entry in a v3 network status document. :param str raw_content: raw directory authority entry information :param bool validate: checks the validity of the content if True, skips these checks otherwise :param bool is_vote: True if this is for a vote, False if it's for a consensus :raises: ValueError if the descriptor data is invalid r5z dir-key-certificate-versionrwr[NrrzDAuthority entries are expected to start with a 'dir-source' line: %sFr8r"z/Authority votes must have a key certificate: %srDz@Authority consensus entries shouldn't have a key certificate: %srBzAuthority entries must have a 'rOvoteszconsensus entriesz Authority z shouldn't have a ')rr"rBrDz>Authority entries can only have a single '%s' line, got %i: %s)rBrrCrrr _to_unicoderrkey_certificater rQrRrrrrrrrrJr>r!)rrKrrsrkey_divrr@dir_source_entryrUexcluded_fieldsr type_labelrrMs rrCzDirectoryAuthority.__init___sX d,[(l,Sii!!--k:Gll:;G"}+GGaKL,A8Ld 1%g!d$Wh7GLD$8$;; ^bij kk$)7;;|+D!i $Q'*00215>>yI *6o I;& ##MPWWX XM?*   ^ahhi i m_ ,/,--$`' ' !WV]^_ _`l' o %")w/B*ZY`bijk kl "'--/2@/'6 v;?w*dd\`gilmsitv}_~~ @ kk'8$dm ||Dr)NrFF)NrTFF)FF)rrrrrAr]_parse_vote_digest_line_parse_legacy_dir_key_line#_parse_shared_rand_participate_linerrrrdrerfrrrCrgrhs@rrrs5n12 011201  12  01 %34)*D12t78'0S(T$b*D%E.6W/X'/P(Q-t5U.V &.N'O!*(-"0*B4"C!A /*bbN$N$rrcttd|}d|vrtd|z|jdd\}}tjj j |std|ztjj j|std|z||_t||_ y)Nrl:zZKey certificate's 'dir-address' is expected to be of the form ADDRESS:PORT: dir-address %sr[zDKey certificate's address isn't a valid IPv4 address: dir-address %sz4Key certificate's dirport is invalid: dir-address %s) r rrsplitrrrrrrrr)rrrrdirports r_parse_dir_address_linerXs  (% qtyy zz\\#q)'7    3 3G < [^cc dd 99   - -g 6 KeS TT*G *rrkrnroexpiresrm identity_keyrp crosscertz ID SIGNATURErq certificationc eZdZdZdZdefdefdefdefdefde fde fde fde fde fd Zeeee e ee e e d ZeddZd fd ZxZS) ra Directory key certificate for a v3 network status document. :var int version: **\*** version of the key certificate :var str address: authority's IP address :var int dir_port: authority's DirPort :var str fingerprint: **\*** authority's fingerprint :var str identity_key: **\*** long term authority identity key :var datetime published: **\*** time when this key was generated :var datetime expires: **\*** time after which this key becomes invalid :var str signing_key: **\*** directory server's public signing key :var str crosscert: signature made using certificate's signing key :var str certification: **\*** signature of this key certificate signed with the identity key **\*** mandatory attribute zdir-key-certificate-3N) rrrr!rZr'rYrr[r\) rkrlr!rnrormr$rprqc |rtd|jzt||ddtfdt fdt fdt dfdt dffd t d ffS) Nr,)rkrr!rnrormrr$rqr)rrr rrrr/s rrzKeyCertificate.contents  ?#,, N OO tW*)+,LN+,.)./?@A-.>?@ / 3K @A  rctt| || t||}|rdt |j dk7rt d|zdt |j dk7rt d|ztD]M\}}|r||vrt d|d |t|j|g}|d kDs>t d |||fz|j||y||_ y) Nr5rkrzIKey certificates must start with a 'dir-key-certificate-version' line: %srqrwzAKey certificates must end with a 'dir-key-certification' line: %szKey certificates must have a 'rOr[z=Key certificates can only have a single '%s' line, got %i: %s) rBrrCr rQrRrKEY_CERTIFICATE_PARAMSrrrrJ)rrKrrrrT entry_countrMs rrCzKeyCertificate.__init__ s .$(h,(O$[(;G &$w||~*>q*A Aeituvv "d7<<>&:2&> >]almnn $:C '< G72GU`ab b'++gr23 ?[_fhsvA_BBC C C kk'8$dmrrXrY)rrrrrZ'_parse_dir_key_certificate_version_linerXr\_parse_identity_key_line_parse_dir_key_published_line_parse_dir_key_expires_line_parse_signing_key_line_parse_dir_key_crosscert_line!_parse_dir_key_certification_linerdrerfrrCrgrhs@rrrs$1=>-../123456121256=> *$K**620.6> /  rrc<eZdZdZd dZdZdZdZdZdZ d Z y) ra Directory signature of a v3 network status document. :var str method: algorithm used to make the signature :var str identity: fingerprint of the authority that made the signature :var str key_digest: digest of the signing key :var str signature: document signature :var str flavor: consensus type this signature is for (such as 'microdesc'), **None** if for the standard consensus :param bool validate: checks validity if **True** :raises: **ValueError** if a validity check fails Nc*|rntjjj|st d|ztjjj|st d|z||_||_||_||_||_ y)Nz4Malformed fingerprint (%s) in the document signaturez3Malformed key digest (%s) in the document signature) rrr9r<rrrrr&r)rrrrr&rrs rrCzDocumentSignature.__init__3s~ YY 5 5h ?ORZZ[[ YY 5 5j ANQ[[\\DKDM DODNDKrct|tsydD]:}t||t||k7s|t||t||cS|ddS)NF)rrrr&rT)rrgetattr)rotherrr1s r_comparezDocumentSignature._compareDsa e. / KA t t 4 4gdD)75$+?@@A $ rcFtt|jSr%)hashrIrrs r__hash__zDocumentSignature.__hash__Ns D ! ""rc(|j|dS)Nc ||k(Sr%rsos rrz*DocumentSignature.__eq__..R Q!Vrrnrrms r__eq__zDocumentSignature.__eq__Q == 3 44rc||k( Sr%rrys r__ne__zDocumentSignature.__ne__Tsu} rc(|j|dS)Nc ||kSr%rrts rrz*DocumentSignature.__lt__..Xs QUrrxrys r__lt__zDocumentSignature.__lt__Ws == 2 33rc(|j|dS)Nc ||kSr%rrts rrz*DocumentSignature.__le__..[rwrrxrys r__le__zDocumentSignature.__le__Zr{r)NF) rrrrrCrnrqrzr}rrrrrrr$s* "#545rrc~eZdZdZdZdefdefdefdefge fge fge fdZ eeeee e e dZ eddZd fd ZxZS) raG Stand alone signature of the consensus. These are exchanged between directory authorities when determining the next hour's consensus. Detached signatures are defined in section 3.10 of the dir-spec, and only available to be downloaded for five minutes between minute 55 until the end of the hour. .. versionadded:: 1.8.0 :var str consensus_digest: **\*** digest of the consensus being signed :var datetime valid_after: **\*** time when the consensus became valid :var datetime fresh_until: **\*** time when the next consensus should be produced :var datetime valid_until: **\*** time when this consensus becomes obsolete :var list additional_digests: **\*** :class:`~stem.descriptor.networkstatus.DocumentDigest` for additional consensus flavors :var list additional_signatures: **\*** :class:`~stem.descriptor.networkstatus.DocumentSignature` for additional consensus flavors :var list signatures: **\*** :class:`~stem.descriptor.networkstatus.DocumentSignature` of the authorities that have signed the document **\*** mandatory attribute zdetached-signature-3N)r)rrrr rr)rrr-r.r/rsrtr)c |rtd|jzt||ddtfdtfdtffS)Nr,)rr(6D3CC0EFA408F228410A4A8145E1B0BB0670E442r-r.r/)rrr rr/s rrzDetachedSignature.contentsQ  ?#,, N OO tWFln%ln%ln% / rctt| || t||}|rdt |j dk7rt d|ztD]Q\}}}|r||vrt d|d|t|j|g}|r<|dkDsBt d|||fz|j||y||_ y) Nr5rrrzADetached signatures must start with a 'consensus-digest' line: %sz!Detached signatures must have a 'rOr[z@Detached signatures can only have a single '%s' line, got %i: %s) rBrrCr rQrRrDETACHED_SIGNATURE_PARAMSrrrrJ) rrKrrrrT is_multiplerarMs rrCzDetachedSignature.__init__s T+K\+R$[(;G tGLLN3A6 6]almnn1JF ,'< G72wXcde e'++gr23 {Q^bikvyDbEEF F F kk'8$dmrrXrY)rrrrrZ_parse_consensus_digest_linerrrr rrrdrerfrrCrgrhs@rrr^s40;<89898989 ">?=>*511128A/  rrc(eZdZdZdZdfd ZxZS)ra< Network status document containing bridges. This is only available through the metrics site. :var dict routers: fingerprint to :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` mapping for relays contained in the document :var datetime published: time when the document was published rctt| |d|_t j |}t jjj|j}|jdrS|jdddj} t jjj||_n7|r5tdt jjj|zt j j"j%||t&|f}t)d|D|_y#t$r|rtd|zYewxYw)Nz published rr[zEBridge network status document's 'published' time wasn't parsable: %szFBridge network status documents must start with a 'published' line: %s)rrc38K|]}|j|fywr%r:r;s rr=z7BridgeNetworkStatusDocument.__init__..r>r?)rBrrCr'rDrErrrrKreadlinerrr_parse_timestamprrrrrrFrG)rrKrrpublished_linerLrMs rrCz$BridgeNetworkStatusDocument.__init__sR %t5kBDNJJ{+MYY((44]5K5K5MNN  .%++C3A6<<>nu,,==nM  `cgclclcvcvdCdCDOdPP QQ//55AA'7 BKI[IIDLu besst t us.E E)(E)rY)rrrrrZrCrgrhs@rrrs1JJrrrY){r collectionsrrrD#stem.descriptor.router_status_entryrstem.util.str_toolsstem.util.tor_tools stem.versionstem.descriptorrrrrrrr r r r r rrrrrrrrrrrrrrrrrPrrrrrrrr`rrrr namedtuplerrrrrrrrrrr rr[r\r]r^r_r`rarbrcrrrmrurzr}rrrrrrrrrrrrrrrr r!r"r'rSr#r$r%r&rrrrArRrQrrXrbrdrercrfrgrhrobjectrrrrrrrs4l *4 &!8!   ! '5B  B   b4uSRqa 1!"*2#$(*!"!"##'()1< / 9% %"i%B ?%RO %  % Ay> %%%I%J%%%y"o%!Y%C#% [!%"W#%$v%%&f'%(6)%*f+%,1i.-%./%0G1%2'3%4K5%67%8a^9%:*9;%<&y=%>W?%@ A%B C%D0E%F$.(.I% P+[++,<>cd !7!7!78TWO"P  +[++,<>_` 04\awFwNwNLM^ : 2}J}@ W( * 0 &99QS\^_%`"4]MR(I>./@-Qab01BDU^tu01BDU^tu-k;G,]INab"23H+WbwJ#K12DFXYC3CDt*A"3" +  *. + J%*)*9, Z Y . -"7}m!T!6}m!T!6}m!T%9:KM^%_"%9:KM^%_"!3M=ZN"O'9:MOblg(h$&78QSu&v#+?@^`~+(*>?\^{*|'(<=XZu(v%';>[]fhi*j' 56I; W34EyQ+,>P`a*+