o u]j@sdZddlZddlZddlZddlZddlZddlZddlmZddl m Z m Z m Z m Z mZmZmZmZmZddlmZmZdZdZejZejZejZejejejej ej!ej"ej#fZ$ej%ej&ej'ej(ej)ej*ej+fZ,Gdd d e-Z.Gd d d e.Z/Gd d d e.Z0Gddde/Z1Gddde/Z2Gddde/Z3Gddde/Z4Gddde/Z5Gddde/Z6Gddde.Z7Gddde.Z8Gddde/Z9Gd d!d!e/Z:Gd"d#d#e.Z;Gd$d%d%e.ZGd*d+d+e.Z?Gd,d-d-e.Z@Gd.d/d/e.ZAdS)0a Messages communicated over a Tor relay's ORPort. .. versionadded:: 1.7.0 **Module Overview:** :: Cell - Base class for ORPort messages. |- CircuitCell - Circuit management. | |- CreateCell - Create a circuit. (section 5.1) | |- CreatedCell - Acknowledge create. (section 5.1) | |- RelayCell - End-to-end data. (section 6.1) | |- DestroyCell - Stop using a circuit. (section 5.4) | |- CreateFastCell - Create a circuit, no PK. (section 5.1) | |- CreatedFastCell - Circuit created, no PK. (section 5.1) | |- RelayEarlyCell - End-to-end data; limited. (section 5.6) | |- Create2Cell - Extended CREATE cell. (section 5.1) | +- Created2Cell - Extended CREATED cell. (section 5.1) | |- PaddingCell - Padding negotiation. (section 7.2) |- VersionsCell - Negotiate proto version. (section 4) |- NetinfoCell - Time and address info. (section 4.5) |- PaddingNegotiateCell - Padding negotiation. (section 7.2) |- VPaddingCell - Variable-length padding. (section 7.2) |- CertsCell - Relay certificates. (section 4.2) |- AuthChallengeCell - Challenge value. (section 4.3) |- AuthenticateCell - Client authentication. (section 4.5) |- AuthorizeCell - Client authorization. (not yet used) | |- pack - encodes cell into bytes |- unpack - decodes series of cells +- pop - decodes cell with remainder N) UNDEFINED) HASH_LENZERO LinkProtocolAddress Certificate CloseReason RelayCommandSizesplit)datetime_to_unix str_toolsi cseZdZdZdZdZdZdfdd Zedd Z ed d Z d d Z eddZ eddZ edddZeddZddZddZZS)Cella Metadata for ORPort cells. Unused padding are **not** used in equality checks or hashing. If two cells differ only in their *unused* attribute they are functionally equal. The following cell types explicitly don't have *unused* content: * PaddingCell (we consider all content part of payload) * VersionsCell (all content is unpacked and treated as a version specification) * VPaddingCell (we consider all content part of payload) :var bytes unused: unused filler that padded the cell to the expected size ZUNKNOWNFctt|||_dSN)superr__init__unused)selfr __class__2/usr/lib/python3/dist-packages/stem/client/cell.pyrc z Cell.__init__cC>ttjtD]\}}|t|dtkr|Sqtd|)z Provides cell attributes by its name. :param str name: cell command to fetch :raises: **ValueError** if cell type is invalid NAMEz'%s' isn't a valid cell typeinspectZ getmemberssysmodules__name__getattrr ValueError)name_clsrrrby_nameg   z Cell.by_namecCr)z Provides cell attributes by its value. :param int value: cell value to fetch :raises: **ValueError** if cell type is invalid VALUEz'%s' isn't a valid cell valuer)valuer'r(rrrby_valuewr*z Cell.by_valuecCstdt|j)Nz(Packing not yet implemented for %s cells)NotImplementedErrortyperr link_protocolrrrpackz Cell.packccs(|rt||\}}|V|sdSdS)aE Unpacks all cells from a response. :param bytes content: payload to decode :param int link_protocol: link protocol version :returns: :class:`~stem.client.cell.Cell` generator :raises: * ValueError if content is malformed * NotImplementedError if unable to unpack any of the cell types N)rpop)contentr1cellrrrunpacks  z Cell.unpackcCst|}|j|\}}t|\}}t|}|jrt}nt|\}}t ||kr7t d|j |t |ft ||\}}| ||||fS)a< Unpacks the first cell. :param bytes content: payload to decode :param int link_protocol: link protocol version :returns: (:class:`~stem.client.cell.Cell`, remainder) tuple :raises: * ValueError if content is malformed * NotImplementedError if unable to unpack this cell type z:%s cell should have a payload of %i bytes, but only had %i)r circ_id_sizer4CELL_TYPE_SIZErr- IS_FIXED_SIZEFIXED_PAYLOAD_LENPAYLOAD_LEN_SIZElenr%rr _unpack)r5r1circ_idcommandr(Z payload_lenpayloadrrrr4s  zCell.popNcCst|tr|durtd|j|dkrtd|n |dur&td|jd}t|}t}||j|7}|tj |j 7}||j rFdn tj t |t |7}||7}||7}|j rt ||jkrutd|jt ||jt |f|t|jt |7}t|S) ab Provides bytes that can be used on the wire for these cell attributes. Format of a properly packed cell depends on if it's fixed or variable sized... :: Fixed: [ CircuitID ][ Command ][ Payload ][ Padding ] Variable: [ CircuitID ][ Command ][ Size ][ Payload ] :param str name: cell command :param int link_protocol: link protocol version :param bytes payload: cell payload :param int circ_id: circuit id, if a CircuitCell :returns: **bytes** with the encoded payload :raises: **ValueError** if cell type invalid or payload makes cell too large Nz%%s cells require a circuit identifierz3Circuit identifiers must a positive integer, not %sz0%s cells should not specify a circuit identifierrrzdCell of type %s is too large (%i bytes), must not be more than %i. Check payload size (was %i bytes)) issubclass CircuitCellr%rr bytearrayr8r2r CHARr+r:SHORTr=fixed_cell_lengthrbytes)r(r1rArr?r6rrr_packs*  & z Cell._packcCstd|j)aJ Subclass implementation for unpacking cell content. :param bytes content: payload to decode :param stem.client.datatype.LinkProtocol link_protocol: link protocol version :param int circ_id: circuit id cell is for :returns: instance of this cell type :raises: **ValueError** if content is malformed z*Unpacking not yet implemented for %s cells)r.rr(r5r?r1rrrr>sz Cell._unpackcCst|tr t|t|kSdS)NF) isinstancerhashrotherrrr__eq__z Cell.__eq__cCs ||k SrrrNrrr__ne__s z Cell.__ne__r)rN)r# __module__ __qualname____doc__rr+r:r staticmethodr)r-r2r7r4 classmethodrJr>rPrR __classcell__rrrrrPs*     5 rcs"eZdZdZdfdd ZZS)rDz? Cell concerning circuits. :var int circ_id: circuit id rctt||||_dSr)rrDrr?)rr?rrrrr zCircuitCell.__init__rS)r#rTrUrVrrYrrrrrD srDcJeZdZdZdZdZdZdfdd Zdd Ze d d Z d d Z Z S) PaddingCellzn Randomized content to either keep activity going on a circuit. :var bytes payload: randomized payload ZPADDINGrTNcsH|stt}nt|tkrtdtt|ftt|||_dS)Nz.Padding payload should be %i bytes, but was %i) osurandomr;r=r%rr]rrA)rrArrrr!s    zPaddingCell.__init__cCt||jSr)r]rJrAr0rrrr2*zPaddingCell.packcCst|Sr)r]rKrrrr>-szPaddingCell._unpackcCtjj|dddSNrATcachestemutilZ _hash_attrrrrr__hash__1r3zPaddingCell.__hash__r r#rTrUrVrr+r:rr2rXr>rjrYrrrrr]s  r]c(eZdZdZdZdZfddZZS) CreateCellZCREATErBTctt|dSr)rrmrrirrrr:r3zCreateCell.__init__r#rTrUrr+r:rrYrrrrrm5 rmcrl) CreatedCellZCREATEDTcrnr)rrqrrirrrrCr3zCreatedCell.__init__rorrrrrq>rprqcs^eZdZdZdZdZdZdfdd Zd d Ze d d Z d dZ e ddZ ddZZS) RelayCella Command concerning a relay circuit. Our 'recognized' attribute provides a cheap (but incomplete) check for if our cell payload is encrypted. If non-zero our payload *IS* encrypted, but if zero we're *PROBABLY* fully decrypted. This uncertainty is because encrypted cells have a small chance of coincidently producing zero for this value as well. :var stem.client.RelayCommand command: command to be issued :var int command_int: integer value of our command :var bytes data: payload of the cell :var int recognized: non-zero if payload is encrypted :var int digest: running digest held with the relay :var int stream_id: specific stream this concerns ZRELAYTrrc sdtt|vr|dtj}t|}n#tj |r,|dtj}t|}ntj |r3n t dt|j t t|||t|\|_|_||_||_||_t||_|dkr}|so|jtvrot d|j|r|jtvrt d|jdSdSdS)NrMz=RELAY cell digest must be a hash, string, or int but was a %srz"%s relay cells require a stream idzE%s relay cells concern the circuit itself and cannot have a stream id)strr/lowerdigestRELAY_DIGEST_SIZEsizer7rgrhZ_is_strZ_is_intr%r#rrsrr getr@ command_int recognized stream_idr Z _to_bytesdataSTREAM_ID_REQUIREDSTREAM_ID_DISALLOWED) rr?r@r~rwr}r|rZ digest_packedrrrr]s,     zRelayCell.__init__cCst}|tj|j7}|tj|j7}|tj|j7}|tj|j 7}|tjt |j 7}||j 7}t |t||j|jSr)rEr rFr2r{rGr|r}LONGrwr=r~rsrJrIrr?rr1rArrrr2zs zRelayCell.packc Cst|}|}t||jkrtd|jt|f|j|\}}tj|\}}|t j kr8td|| |} t | ||} | ||fS)a Decrypts content as a relay cell addressed to us. This provides back a tuple of the form... :: (cell (RelayCell), new_key (CipherContext), new_digest (HASH)) :param int link_protocol: link protocol version :param bytes content: cell content to be decrypted :param cryptography.hazmat.primitives.ciphers.CipherContext key: key established with the relay we received this cell from :param hashlib.HASH digest: running digest held with the relay :returns: **tuple** with our decrypted cell and updated key/digest :raises: :class:`stem.ProtocolError` if content doesn't belong to a relay cell z/RELAY cells should be %i bytes, but received %iz) r1r5keyrwnew_key new_digestr?r@Zencrypted_payloadrAr6rrrdecrypts    zRelayCell.decryptc Cst|}|}|jjd}|||d}||t|j|j|j||j |j |j }t |||\} } | || ||fS)a Encrypts our cell content to be sent with the given key. This provides back a tuple of the form... :: (payload (bytes), new_key (CipherContext), new_digest (HASH)) :param int link_protocol: link protocol version :param cryptography.hazmat.primitives.ciphers.CipherContext key: key established with the relay we're sending this cell to :param hashlib.HASH digest: running digest held with the relay :returns: **tuple** with our encrypted payload and updated key/digest rBN) rr8ryr2rrsr?r@r~r}r|rr ) rr1rrwrr header_sizeZpayload_without_digestr6headerrArrrencrypts    zRelayCell.encryptc Cstj|\}}tj|\}}tj|\}}tj|\}}tj|\}}t||\} } t| |krAtd|j|t| ft ||| |||| S)Nz5%s cell said it had %i bytes of data, but only had %i) r rFr4rGrr r=r%rrs) r(r5r?r1r@r|r}rwZdata_lenr~rrrrr>s zRelayCell._unpackcCstjj|ddddddS)Nr{r}rwr~TrdrfrirrrrjszRelayCell.__hash__)rrrr)r#rTrUrVrr+r:rr2rWrrrXr>rjrYrrrrrsGs 6#  rscsPeZdZdZdZdZdZejdffdd Z dd Z e d d Z d d Z ZS) DestroyCellz Closes the given circuit. :var stem.client.CloseReason reason: reason the circuit is being closed :var int reason_int: integer value of our closure reason ZDESTROYTrcs(tt|||t|\|_|_dSr)rrrrrzreason reason_int)rr?rrrrrrszDestroyCell.__init__cCst|tj|j|j|jSr)rrJr rFr2rrr?r0rrrr2rQzDestroyCell.packcCstj|\}}t|||Sr)r rFr4r)r(r5r?r1rrrrrr>s zDestroyCell._unpackcCtjj|ddddS)Nr?rTrdrfrirrrrj zDestroyCell.__hash__)r#rTrUrVrr+r:rZNONErr2rXr>rjrYrrrrrs rcJeZdZdZdZdZdZdfdd Zd d Ze d d Z d dZ Z S)CreateFastCellz Create a circuit with our first hop. This is lighter weight than further hops because we've already established the relay's identity and secret key. :var bytes key_material: randomized key material Z CREATE_FASTTNrcsL|stt}nt|tkrtdtt|ftt|||||_dSN+Key material should be %i bytes, but was %i) r^r_rr=r%rrr key_material)rr?rrrrrrs    zCreateFastCell.__init__cCst||j|j|jSr)rrJrrr?r0rrrr2"zCreateFastCell.packcCs:t|t\}}t|tkrtdtt|ft|||Sr)r rr=r%r)r(r5r?r1rrrrrr>%s  zCreateFastCell._unpackcCr)Nr?rTrdrfrirrrrj.rzCreateFastCell.__hash__Nrrkrrrrr s  rcr)CreatedFastCellz CREATE_FAST reply. :var bytes key_material: randomized key material :var bytes derivative_key: hash proving the relay knows our shared key Z CREATED_FASTTNrcsr|stt}nt|tkrtdtt|ft|tkr(tdtt|ftt|||||_||_ dS)Nrz.Derivatived key should be %i bytes, but was %i) r^r_rr=r%rrrrderivative_key)rr?rrrrrrr>s    zCreatedFastCell.__init__cCst||j|j|j|jSr)rrJrrrr?r0rrrr2KszCreatedFastCell.packcCsRt|tdkrtdtdt|ft|t\}}t|t\}}t||||S)Nrrz?Key material and derivatived key should be %i bytes, but was %i)r=rr%r r)r(r5r?r1rrrrrr>Ns zCreatedFastCell._unpackcCtjj|dddddS)Nr?rrTrdrfrirrrrjXrzCreatedFastCell.__hash__rrkrrrrr2s   rcsHeZdZdZdZdZdZfddZddZe d d Z d d Z Z S) VersionsCellzI Link version negotiation cell. :var list versions: link versions VERSIONSFcrr)rrrversions)rrrrrrgrzVersionsCell.__init__cCs"ddd|jD}t||S)NrcSsg|]}tj|qSr)r rGr2).0vrrr lsz%VersionsCell.pack..)joinrrrJrrrrr2ks zVersionsCell.packcCs.g}|rtj|\}}|||st|Sr)r rGr4appendr)r(r5r?r1Zlink_protocolsversionrrrr>os  zVersionsCell._unpackcCrb)NrTrdrfrirrrrjyr3zVersionsCell.__hash__rkrrrrr\s   rcr) NetinfoCellz Information relays exchange about each other. :var datetime timestamp: current time :var stem.client.datatype.Address receiver_address: receiver's OR address :var list sender_addresses: sender's OR addresses ZNETINFOTNrcs4tt|||r |ntj|_||_||_dSr)rrrdatetimeZnow timestampreceiver_addresssender_addresses)rrrrrrrrrs zNetinfoCell.__init__cCspt}|tjtt|j7}||j7}|tjt |j 7}|j D]}||7}q%t |t ||jSr)rEr rr2intr rrrFr=rrrJrIr)rr1rAaddrrrrr2s zNetinfoCell.packc Csptj|\}}t|\}}g}tj|\}}t|D]}t|\} }|| qt||tj ||dS)Nr) r rr4rrFrangerrrZutcfromtimestamp) r(r5r?r1rrrZsender_addr_countirrrrr>s  zNetinfoCell._unpackcCr)NrrrTrdrfrirrrrjrzNetinfoCell.__hash__rrkrrrrr}s  rcrl)RelayEarlyCellZ RELAY_EARLY Tcrnr)rrrrirrrrr3zRelayEarlyCell.__init__rorrrrrrprcrl) Create2CellZCREATE2 Tcrnr)rrrrirrrrr3zCreate2Cell.__init__rorrrrrrprcrl) Created2CellZCREATED2 Tcrnr)rrrrirrrrr3zCreated2Cell.__init__rorrrrrrprcrl)PaddingNegotiateCellZPADDING_NEGOTIATE Tcrnr)rrrrirrrrr3zPaddingNegotiateCell.__init__rorrrrrrprcr\) VPaddingCellz~ Variable length randomized content to either keep activity going on a circuit. :var bytes payload: randomized payload ZVPADDINGFNcs|dur |dur td|dur|dkrtd||dur2|dur2|t|kr2td|t|ftt||durB||_dSt||_dS)Nz5VPaddingCell constructor must specify payload or sizerz)VPaddingCell size (%s) cannot be negativezRVPaddingCell constructor specified both a size of %i bytes and payload of %i bytes)r%r=rrrr^r_rA)rryrArrrrs "zVPaddingCell.__init__cCr`r)rrJrAr0rrrr2razVPaddingCell.packcCs t|dS)N)rA)rrKrrrr>s zVPaddingCell._unpackcCrbrcrfrirrrrjr3zVPaddingCell.__hash__)NNrkrrrrrs  rcr\) CertsCellz Certificate held by the relay we're communicating with. :var list certificates: :class:`~stem.client.Certificate` of the relay ZCERTSFrcrZr)rrr certificates)rcertsrrrrrr[zCertsCell.__init__cCs4t|tjt|jddd|jD|jS)NrcSsg|]}|qSr)r2)rcertrrrrsz"CertsCell.pack..) rrJr rFr2r=rrrr0rrrr2s4zCertsCell.packcCs^tj|\}}g}t|D]}|std|t|ft|\}}||qt||dS)NzJCERTS cell indicates it should have %i certificates, but only contained %ir) r rFr4rr%r=rrr)r(r5r?r1Z cert_countrrrrrrr>s   zCertsCell._unpackcCrb)NrTrdrfrirrrrjr3zCertsCell.__hash__rSrkrrrrrs  rcr)AuthChallengeCellz First step of the authentication handshake. :var bytes challenge: random bytes for us to sign to authenticate :var list methods: authentication methods supported by the relay we're communicating with ZAUTH_CHALLENGEFNrcsP|stt}nt|tkrtdtt|ftt||||_||_ dS)Nz+AUTH_CHALLENGE must be %i bytes, but was %i) r^r_AUTH_CHALLENGE_SIZEr=r%rrr challengemethods)rrrrrrrr#s   zAuthChallengeCell.__init__cCsVt}||j7}|tjt|j7}|jD] }|tj|7}qt|t ||j Sr) rErr rGr2r=rrrJrIr)rr1rAmethodrrrr2-s   zAuthChallengeCell.packc Csttjj}t||krtd|t|ft|t\}}tj|\}}t||tjjkr9td|t|fg}t|D]}tj|\} }| | q?t |||dS)Nz>AUTH_CHALLENGE payload should be at least %i bytes, but was %izCAUTH_CHALLENGE should have %i methods, but only had %i bytes for itr) rr rGryr=r%r r4rrr) r(r5r?r1Zmin_sizerZ method_countrrrrrrr>7s    zAuthChallengeCell._unpackcCr)NrrTrdrfrirrrrjKrzAuthChallengeCell.__hash__rrkrrrrrs  rcrl)AuthenticateCellZ AUTHENTICATEFcrnr)rrrrirrrrTr3zAuthenticateCell.__init__rorrrrrOrprcrl) AuthorizeCellZ AUTHORIZEFcrnr)rrrrirrrr]r3zAuthorizeCell.__init__rorrrrrXrpr)BrVrrr r^r!Z stem.utilrgrZstem.client.datatyperrrrrrr r r r r r;rrFr9rGr<rrxZBEGINZDATAZENDZ CONNECTEDZRESOLVEZRESOLVEDZ BEGIN_DIRrZEXTENDZEXTENDEDZTRUNCATEZ TRUNCATEDZDROPZEXTEND2Z EXTENDED2robjectrrDr]rmrqrsrrrrrrrrrrrrrrrrrrsj$ ,  ;   +%*!0    !$9