ussl
– SSL/TLS module¶
This module implements a subset of the corresponding CPython
module,
as described below. For more information, refer to the original
CPython documentation: ssl
.
This module provides access to Transport Layer Security (previously and widely known as “Secure Sockets Layer”) encryption and peer authentication facilities for network sockets, both client-side and server-side.
Functions¶
-
ussl.
wrap_socket
(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None, server_hostname=None, do_handshake=True)¶ Takes a
stream
sock (usually usocket.socket instance ofSOCK_STREAM
type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in an SSL context. The returned object has the usualstream
interface methods likeread()
,write()
, as well asrecv()
andsend()
. A server-side SSL socket should be created from a normal socket returned fromaccept()
on a non-SSL listening server socket.Parameters:
server_side
: creates a server connection if True, else client connection. A server connection requires akeyfile
and acertfile
.cert_reqs
: specifies the level of certificate checking to be performed.ca_certs
: root certificates to use for certificate checking.server_hostname
: specifies the hostname of the server for verification purposes as well for SNI (Server Name Identification).do_handshake
: determines whether the handshake is done as part of thewrap_socket
or whether it is deferred to be done as part of the initial reads or writes (there is nodo_handshake
method as in CPython). For blocking sockets doing the handshake immediately is standard. For non-blocking sockets (i.e. when the sock passed intowrap_socket
is in non-blocking mode) the handshake should generally be deferred because otherwisewrap_socket
blocks until it completes. Note that in AXTLS the handshake can be deferred until the first read or write but it then blocks until completion.
Depending on the underlying module implementation in a particular
MicroPython port
, some or all keyword arguments above may be not supported.
Warning
Some implementations of ussl
module do NOT validate server certificates,
which makes an SSL connection established prone to man-in-the-middle attacks.
Constants¶
-
ussl.
CERT_NONE
¶ -
ussl.
CERT_OPTIONAL
¶ -
ussl.
CERT_REQUIRED
¶ Supported values for cert_reqs parameter.
- CERT_NONE: in client mode accept just about any cert, in server mode do not request a cert from the client.
- CERT_OPTIONAL: in client mode behaves the same as CERT_REQUIRED and in server mode requests an optional cert from the client for authentication.
- CERT_REQUIRED: in client mode validates the server’s cert and in server mode requires the client to send a cert for authentication. Note that ussl does not actually support client authentication.