U
|
Z ±d ã @ sÆ d dl Zd dlZd dlmZ d dlZddlm Z m
|
Z
|
ddl m Z ddl mZ ddlmZmZ dZd d
|
ZG d d d eZG d d dZeddddgZG dd de edZG dd de
|
e edZdS )é N)ÚEnumé )ÚStreamÚListener)Úaclose_forcefully)Ú_sync)ÚConflictDetectorÚFinali @ c C s t | tjp t| do d| jkS )NÚstrerrorZ UNEXPECTED_EOF_WHILE_READING)Ú
|
isinstanceÚ _stdlib_sslÚ SSLEOFErrorÚhasattrr
|
)Úexc© r ú@d:\z\workplace\vscode\pyvenv\venv\Lib\site-packages\trio/_ssl.pyÚ_is_eofÁ s ÿr c @ s e Zd ZdZdS )ÚNeedHandshakeErrorz§Some :class:`SSLStream` methods can't return any meaningful data until
|
after the handshake. If you call them before the handshake, they raise
|
this error.
|
|
N)Ú__name__Ú
|
__module__Ú __qualname__Ú__doc__r r r r r Ë s r c @ s( e Zd Zdd Zdd Zedd ZdS )Ú_Oncec G s || _ || _d| _t ¡ | _d S ©NF)Ú_afnÚ_argsÚstartedr ÚEventÚ_done)ÚselfZafnÚargsr r r Ú__init__Ô s z_Once.__init__c à sP | j s*d| _ | j| j I d H | j ¡ n"|s<| j ¡ r<d S | j ¡ I d H d S )NT)r r r r ÚsetÚis_setÚwait)r Ú
|
checkpointr r r ÚensureÚ s z _Once.ensurec C s
|
| j ¡ S ©N)r r# ©r r r r Údoneä s z
|
_Once.doneN)r r r r! r& Úpropertyr) r r r r r Ó s
|
r Ú_StateÚOKÚBROKENÚCLOSEDc sÎ e Zd ZdZddddddZddd d
|
d d d dddddddhZd d d ddddddh Zdd Z fddZ fddZ dd Z
|
ddd d d Z d d! Z d"d# Z d.d$d%Zd&d' Zd(d) Zd*d+ Zd,d- Z ZS )/Ú SSLStreama Encrypted communication using SSL/TLS.
|
|
:class:`SSLStream` wraps an arbitrary :class:`~trio.abc.Stream`, and
|
allows you to perform encrypted communication over it using the usual
|
:class:`~trio.abc.Stream` interface. You pass regular data to
|
:meth:`send_all`, then it encrypts it and sends the encrypted data on the
|
underlying :class:`~trio.abc.Stream`; :meth:`receive_some` takes encrypted
|
data out of the underlying :class:`~trio.abc.Stream` and decrypts it
|
before returning it.
|
|
You should read the standard library's :mod:`ssl` documentation carefully
|
before attempting to use this class, and probably other general
|
documentation on SSL/TLS as well. SSL/TLS is subtle and quick to
|
anger. Really. I'm not kidding.
|
|
Args:
|
transport_stream (~trio.abc.Stream): The stream used to transport
|
encrypted data. Required.
|
|
ssl_context (~ssl.SSLContext): The :class:`~ssl.SSLContext` used for
|
this connection. Required. Usually created by calling
|
:func:`ssl.create_default_context`.
|
|
server_hostname (str or None): The name of the server being connected
|
to. Used for `SNI
|
<https://en.wikipedia.org/wiki/Server_Name_Indication>`__ and for
|
validating the server's certificate (if hostname checking is
|
enabled). This is effectively mandatory for clients, and actually
|
mandatory if ``ssl_context.check_hostname`` is ``True``.
|
|
server_side (bool): Whether this stream is acting as a client or
|
server. Defaults to False, i.e. client mode.
|
|
https_compatible (bool): There are two versions of SSL/TLS commonly
|
encountered in the wild: the standard version, and the version used
|
for HTTPS (HTTP-over-SSL/TLS).
|
|
Standard-compliant SSL/TLS implementations always send a
|
cryptographically signed ``close_notify`` message before closing the
|
connection. This is important because if the underlying transport
|
were simply closed, then there wouldn't be any way for the other
|
side to know whether the connection was intentionally closed by the
|
peer that they negotiated a cryptographic connection to, or by some
|
`man-in-the-middle
|
<https://en.wikipedia.org/wiki/Man-in-the-middle_attack>`__ attacker
|
who can't manipulate the cryptographic stream, but can manipulate
|
the transport layer (a so-called "truncation attack").
|
|
However, this part of the standard is widely ignored by real-world
|
HTTPS implementations, which means that if you want to interoperate
|
with them, then you NEED to ignore it too.
|
|
Fortunately this isn't as bad as it sounds, because the HTTP
|
protocol already includes its own equivalent of ``close_notify``, so
|
doing this again at the SSL/TLS level is redundant. But not all
|
protocols do! Therefore, by default Trio implements the safer
|
standard-compliant version (``https_compatible=False``). But if
|
you're speaking HTTPS or some other protocol where
|
``close_notify``\s are commonly skipped, then you should set
|
``https_compatible=True``; with this setting, Trio will neither
|
expect nor send ``close_notify`` messages.
|
|
If you have code that was written to use :class:`ssl.SSLSocket` and
|
now you're porting it to Trio, then it may be useful to know that a
|
difference between :class:`SSLStream` and :class:`ssl.SSLSocket` is
|
that :class:`~ssl.SSLSocket` implements the
|
``https_compatible=True`` behavior by default.
|
|
Attributes:
|
transport_stream (trio.abc.Stream): The underlying transport stream
|
that was passed to ``__init__``. An example of when this would be
|
useful is if you're using :class:`SSLStream` over a
|
:class:`~trio.SocketStream` and want to call the
|
:class:`~trio.SocketStream`'s :meth:`~trio.SocketStream.setsockopt`
|
method.
|
|
Internally, this class is implemented using an instance of
|
:class:`ssl.SSLObject`, and all of :class:`~ssl.SSLObject`'s methods and
|
attributes are re-exported as methods and attributes on this class.
|
However, there is one difference: :class:`~ssl.SSLObject` has several
|
methods that return information about the encrypted connection, like
|
:meth:`~ssl.SSLSocket.cipher` or
|
:meth:`~ssl.SSLSocket.selected_alpn_protocol`. If you call them before the
|
handshake, when they can't possibly return useful data, then
|
:class:`ssl.SSLObject` returns None, but :class:`trio.SSLStream`
|
raises :exc:`NeedHandshakeError`.
|
|
This also means that if you register a SNI callback using
|
`~ssl.SSLContext.sni_callback`, then the first argument your callback
|
receives will be a :class:`ssl.SSLObject`.
|
|
NF)Úserver_hostnameÚ server_sideÚhttps_compatiblec C s || _ tj| _|| _t ¡ | _d | _t ¡ | _ |j
|
| j | j||d| _ t | j | _t ¡ | _d| _t ¡ | _td| _td| _t| _d S )N)r1 r0 r z8another task is currently sending data on this SSLStreamz:another task is currently receiving data on this SSLStream)Útransport_streamr+ r, Ú_stateÚ_https_compatibler Ú MemoryBIOÚ _outgoingÚ_delayed_outgoingÚ _incomingÚwrap_bioÚ _ssl_objectr Ú _do_handshakeÚ
|
_handshookr ZStrictFIFOLockÚ_inner_send_lockÚ_inner_recv_countÚLockÚ_inner_recv_lockr Ú _outer_send_conflict_detectorÚ _outer_recv_conflict_detectorÚSTARTING_RECEIVE_SIZEÚ_estimated_receive_size)r r3 Ú ssl_contextr0 r1 r2 r r r r! L s.
|
|
ü
|
|
ÿÿzSSLStream.__init__Úcontextr1 r0 ÚsessionÚsession_reusedÚ getpeercertÚselected_npn_protocolÚcipherÚshared_ciphersÚ compressionÚpendingÚget_channel_bindingÚselected_alpn_protocolÚversionc C sB || j kr6|| jkr*| jjs*td |¡t| j|S t|d S )Nz'call do_handshake() before calling {!r}) Ú
|
_forwardedÚ_after_handshaker= r) r ÚformatÚgetattrr; ÚAttributeError)r Únamer r r Ú __getattr__ s
|
ÿ zSSLStream.__getattr__c s, || j krt| j|| nt ||¡ d S r' )rS Úsetattrr; ÚsuperÚ __setattr__)r rX Úvalue©Ú __class__r r r\ s
|
zSSLStream.__setattr__c s t ¡ t| j S r' )r[ Ú__dir__ÚlistrS r( r^ r r r` £ s zSSLStream.__dir__c C sD | j tjkrd S | j tjkr$tjn | j tjkr8tjnds@td S r ) r4 r+ r, r- ÚtrioÚBrokenResourceErrorr. ZClosedResourceErrorÚAssertionErrorr( r r r Ú _check_status¦ s zSSLStream._check_status)Úignore_want_readÚ is_handshakec
|
Ç sð t j ¡ I d H d}d}|sÖd}d }z || }W nR tjk
|
rL d}Y n> tjtjfk
|
r } ztj| _ t j
|
| W 5 d } ~ X Y nX d}|rd}d}| j ¡ }
|
|rÖ|sÖ| j jrÖ| j ¡ dkrÖ| jd ksÌt|
|
| _d}
|
|
|
rL| j4 I d H T d}z2| jd k r| j|
|
}
|
d | _| j |
|
¡I d H W n tj| _ Y nX W 5 Q I d H R X q|r| j} | j4 I d H d d}| | jkrÄ| j ¡ I d H } | s| j ¡ n t| jt | | _| j | ¡ | jd7 _W 5 Q I d H R X q|sìt j ¡ I d H |S )NFTzTLSv1.3ó r ) rb ÚlowlevelZcheckpoint_if_cancelledr ÚSSLWantReadErrorÚSSLErrorÚCertificateErrorr+ r- r4 rc r7 Úreadr; r1 rR r8 rd r> r3 Úsend_allr? rA Ú receive_somer9 Ú write_eofÚmaxrE ÚlenÚwriteZcancel_shielded_checkpoint) r Úfnrf rg r ÚyieldedÚfinishedZ want_readÚretr Zto_sendZ
|
recv_countÚdatar r r Ú_retry´ sr
|
ÿþý ü;
|
ÿ zSSLStream._retryc à s8 z | j | jjddI d H W n tj| _ Y nX d S )NT)rg )ry r; Ú do_handshaker+ r- r4 r( r r r r< ` s
|
zSSLStream._do_handshakec à s | ¡ | jjddI dH dS )u Ensure that the initial handshake has completed.
|
|
The SSL protocol requires an initial handshake to exchange
|
certificates, select cryptographic keys, and so forth, before any
|
actual data can be sent or received. You don't have to call this
|
method; if you don't, then :class:`SSLStream` will automatically
|
perform the handshake as needed, the first time you try to send or
|
receive data. But if you want to trigger it manually â for example,
|
because you want to look at the peer's certificate before you start
|
talking to them â then you can call this method.
|
|
If the initial handshake is already in progress in another task, this
|
waits for it to complete and then returns.
|
|
If the initial handshake has already completed, this returns
|
immediately without doing anything (except executing a checkpoint).
|
|
.. warning:: If this method is cancelled, then it may leave the
|
:class:`SSLStream` in an unusable state. If this happens then any
|
future attempt to use the object will raise
|
:exc:`trio.BrokenResourceError`.
|
|
T©r% N)re r= r& r( r r r rz g s zSSLStream.do_handshakec à s\ | j J | ¡ z| jjddI dH W nh tjk
|
r } zH| jrt|jt j
|
s\t |jrtj ¡ I dH W Y ¢W 5 Q R £ dS W 5 d}~X Y nX |dkr®t| j| jj}nt |¡}|dk rÈtdz$| | jj|¡I dH W W 5 Q R £ S tjk
|
rL } z>| jr:t |jr:tj ¡ I dH W Y ¢W 5 Q R £ dS W 5 d}~X Y nX W 5 Q R X dS )aã Read some data from the underlying transport, decrypt it, and
|
return it.
|
|
See :meth:`trio.abc.ReceiveStream.receive_some` for details.
|
|
.. warning:: If this method is cancelled while the initial handshake
|
or a renegotiation are in progress, then it may leave the
|
:class:`SSLStream` in an unusable state. If this happens then any
|
future attempt to use the object will raise
|
:exc:`trio.BrokenResourceError`.
|
|
Fr{ Nrh r zmax_bytes must be >= 1)rC re r= r& rb rc r5 r Ú __cause__r ÚSSLSyscallErrorr ri r% rq rE r9 rO Ú _operatorÚindexÚ
|
ValueErrorry r; rm )r Z max_bytesr r r r ro s2
|
ÿþ
|
$zSSLStream.receive_somec à sj | j Z | ¡ | jjddI dH |sFtj ¡ I dH W 5 Q R £ dS | | jj |¡I dH W 5 Q R X dS )az Encrypt some data and then send it on the underlying transport.
|
|
See :meth:`trio.abc.SendStream.send_all` for details.
|
|
.. warning:: If this method is cancelled, then it may leave the
|
:class:`SSLStream` in an unusable state. If this happens then any
|
attempt to use the object will raise
|
:exc:`trio.BrokenResourceError`.
|
|
Fr{ N)
|
rB re r= r& rb ri r% ry r; rs )r rx r r r rn ¿ s zSSLStream.send_allc à s | j ~ | jl | ¡ | jjddI dH | | jj¡I dH | j}d| _t j
|
| _ || j ¡ fW 5 Q R £ W 5 Q R £ S Q R X W 5 Q R X dS )að Cleanly close down the SSL/TLS encryption layer, allowing the
|
underlying stream to be used for unencrypted communication.
|
|
You almost certainly don't need this.
|
|
Returns:
|
A pair ``(transport_stream, trailing_bytes)``, where
|
``transport_stream`` is the underlying transport stream, and
|
``trailing_bytes`` is a byte string. Since :class:`SSLStream`
|
doesn't necessarily know where the end of the encrypted data will
|
be, it can happen that it accidentally reads too much from the
|
underlying stream. ``trailing_bytes`` contains this extra data; you
|
should process it as if it was returned from a call to
|
``transport_stream.receive_some(...)``.
|
|
Fr{ N)rC rB re r= r& ry r; Úunwrapr3 r+ r. r4 r9 rm ©r r3 r r r r Ô s zSSLStream.unwrapc à sä | j tjkr tj ¡ I dH dS | j tjks2| jrNtj| _ | j ¡ I dH dS zzR| j
|
j ddI dH z | j | j jddI dH W n tjtjfk
|
r Y nX W n t| jI dH Y nX | j ¡ I dH W 5 tj| _ X dS )aà Gracefully shut down this connection, and close the underlying
|
transport.
|
|
If ``https_compatible`` is False (the default), then this attempts to
|
first send a ``close_notify`` and then close the underlying stream by
|
calling its :meth:`~trio.abc.AsyncResource.aclose` method.
|
|
If ``https_compatible`` is set to True, then this simply closes the
|
underlying stream and marks this stream as closed.
|
|
NFr{ T)rf )r4 r+ r. rb ri r% r- r5 r3 Úacloser= r& ry r; r rc ZBusyResourceErrorr r( r r r r î s$ 0
|
zSSLStream.aclosec à sN | j > | ¡ | j4 I dH | j ¡ I dH W 5 Q I dH R X W 5 Q R X dS )z>See :meth:`trio.abc.SendStream.wait_send_all_might_not_block`.N)rB re r> r3 Ú wait_send_all_might_not_blockr( r r r r E s z'SSLStream.wait_send_all_might_not_block)N)r r r r r! rS rT rY r\ r` re ry r< rz ro rn r r r Ú __classcell__r r r^ r r/ ì sV dù *ò÷ -#
|
5Wr/ )Ú metaclassc @ s. e Zd ZdZddddZdd Zdd Zd
|
S ) Ú SSLListenera» A :class:`~trio.abc.Listener` for SSL/TLS-encrypted servers.
|
|
:class:`SSLListener` wraps around another Listener, and converts
|
all incoming connections to encrypted connections by wrapping them
|
in a :class:`SSLStream`.
|
|
Args:
|
transport_listener (~trio.abc.Listener): The listener whose incoming
|
connections will be wrapped in :class:`SSLStream`.
|
|
ssl_context (~ssl.SSLContext): The :class:`~ssl.SSLContext` that will be
|
used for incoming connections.
|
|
https_compatible (bool): Passed on to :class:`SSLStream`.
|
|
Attributes:
|
transport_listener (trio.abc.Listener): The underlying listener that was
|
passed to ``__init__``.
|
|
F)r2 c C s || _ || _|| _d S r' )Útransport_listenerÚ _ssl_contextr5 )r r rF r2 r r r r! s zSSLListener.__init__c à s$ | j ¡ I dH }t|| jd| jdS )z
Accept the next connection and wrap it in an :class:`SSLStream`.
|
|
See :meth:`trio.abc.Listener.accept` for details.
|
|
NT)r1 r2 )r Úacceptr/ r r5 r r r r r s üzSSLListener.acceptc à s | j ¡ I dH dS )z Close the transport listener.N)r r r( r r r r s zSSLListener.acloseN)r r r r r! r r r r r r r n s
|
û r )Úoperatorr~ Ússlr Úenumr Ú_Enumrb Úabcr r Z_highlevel_genericr Ú r Z_utilr r rD r Ú Exceptionr r r+ r/ r r r r r Ú<module> s&
|
|
