:mod:`ssl`
==========

.. py:module:: ssl

.. autoapi-nested-parse::

   The `ssl` module provides SSL contexts to wrap sockets in.



.. raw:: html

    <p>
    <details>
    <summary>Available on these boards</summary>
    <ul>
    <li> AITHinker ESP32-C3S_Kit
    <li> ATMegaZero ESP32-S2
    <li> Adafruit Feather ESP32-S2 TFT
    <li> Adafruit Feather ESP32S2
    <li> Adafruit FunHouse
    <li> Adafruit MagTag
    <li> Adafruit Metro ESP32S2
    <li> Adafruit QT Py ESP32S2
    <li> Artisense Reference Design RD00
    <li> BastWiFi
    <li> CrumpS2
    <li> ESP 12k NodeMCU
    <li> Feather ESP32S2 without PSRAM
    <li> FeatherS2
    <li> FeatherS2 Neo
    <li> FeatherS2 PreRelease
    <li> Franzininho WIFI w/Wroom
    <li> Franzininho WIFI w/Wrover
    <li> Gravitech Cucumber M
    <li> Gravitech Cucumber MS
    <li> Gravitech Cucumber R
    <li> Gravitech Cucumber RS
    <li> HMI-DevKit-1.1
    <li> Kaluga 1
    <li> LILYGO TTGO T8 ESP32-S2 w/Display
    <li> MORPHEANS MorphESP-240
    <li> MicroDev microC3
    <li> MicroDev microS2
    <li> Oak Dev Tech PixelWing ESP32S2
    <li> S2Mini
    <li> S2Pico
    <li> Saola 1 w/Wroom
    <li> Saola 1 w/Wrover
    <li> Targett Module Clip w/Wroom
    <li> Targett Module Clip w/Wrover
    <li> Thingz - Galaxia
    <li> TinyS2
    <li> nanoESP32-S2  w/Wrover
    <li> nanoESP32-S2 w/Wroom
    </ul>
    </details>
    </p>




.. py:function:: create_default_context() -> SSLContext

   Return the default SSLContext.


.. py:class:: SSLContext

   Settings related to SSL that can be applied to a socket by wrapping it.
   This is useful to provide SSL certificates to specific connections
   rather than all of them.


.. py:function:: wrap_socket(sock: socketpool.Socket, *, server_side: bool = False, server_hostname: Optional[str] = None) -> SSLSocket

   Wraps the socket into a socket-compatible class that handles SSL negotiation.
   The socket must be of type SOCK_STREAM.


.. py:class:: SSLSocket

   Implements TLS security on a subset of `socketpool.Socket` functions. Cannot be created
   directly. Instead, call `wrap_socket` on an existing socket object.

   Provides a subset of CPython's `ssl.SSLSocket` API. It only implements the versions of
   recv that do not allocate bytes objects.

   .. py:method:: __enter__() -> SSLSocket

      No-op used by Context Managers.


   .. py:method:: __exit__() -> None

      Automatically closes the Socket when exiting a context. See
      :ref:`lifetime-and-contextmanagers` for more info.


   .. py:method:: accept() -> Tuple[SSLSocket, Tuple[str, int]]

      Accept a connection on a listening socket of type SOCK_STREAM,
      creating a new socket of type SOCK_STREAM.
      Returns a tuple of (new_socket, remote_address)


   .. py:method:: bind(address: Tuple[str, int]) -> None

      Bind a socket to an address

      :param ~tuple address: tuple of (remote_address, remote_port)


   .. py:method:: close() -> None

      Closes this Socket


   .. py:method:: connect(address: Tuple[str, int]) -> None

      Connect a socket to a remote address

      :param ~tuple address: tuple of (remote_address, remote_port)


   .. py:method:: listen(backlog: int) -> None

      Set socket to listen for incoming connections

      :param ~int backlog: length of backlog queue for waiting connetions


   .. py:method:: recv_into(buffer: _typing.WriteableBuffer, bufsize: int) -> int

      Reads some bytes from the connected remote address, writing
      into the provided buffer. If bufsize <= len(buffer) is given,
      a maximum of bufsize bytes will be read into the buffer. If no
      valid value is given for bufsize, the default is the length of
      the given buffer.

      Suits sockets of type SOCK_STREAM
      Returns an int of number of bytes read.

      :param bytearray buffer: buffer to receive into
      :param int bufsize: optionally, a maximum number of bytes to read.


   .. py:method:: send(bytes: _typing.ReadableBuffer) -> int

      Send some bytes to the connected remote address.
      Suits sockets of type SOCK_STREAM

      :param ~bytes bytes: some bytes to send


   .. py:method:: settimeout(value: int) -> None

      Set the timeout value for this socket.

      :param ~int value: timeout in seconds.  0 means non-blocking.  None means block indefinitely.


   .. py:method:: setblocking(flag: bool) -> Optional[int]

      Set the blocking behaviour of this socket.

      :param ~bool flag: False means non-blocking, True means block indefinitely.


   .. py:method:: __hash__() -> int

      Returns a hash for the Socket.