docs/library/ussl: Deconditionalize, wipy notes moved to its documentation.

This commit is contained in:
Paul Sokolovsky 2017-04-16 09:41:32 +03:00
parent a0fb360f1b
commit ac8843ceec
2 changed files with 53 additions and 70 deletions

View File

@ -1,86 +1,46 @@
:mod:`ussl` -- ssl module
===============================
:mod:`ussl` -- SSL/TLS module
=============================
.. module:: ussl
:synopsis: TLS/SSL wrapper for socket objects
This module provides access to Transport Layer Security (often known as
“Secure Sockets Layer”) encryption and peer authentication facilities for
network sockets, both client-side and server-side.
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.
.. only:: not port_wipy
Functions
---------
Functions
---------
.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None)
.. function:: ssl.wrap_socket(sock, server_side=False)
Takes a stream `sock` (usually usocket.socket instance of ``SOCK_STREAM`` type),
and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
an SSL context. Returned object has the usual stream interface methods like
`read()`, `write()`, etc. In MicroPython, the returned object does not expose
socket interface and methods like `recv()`, `send()`. In particular, a
server-side SSL socket should be created from a normal socket returned from
`accept()` on a non-SSL listening server socket.
Takes a stream `sock` (usually usocket.socket instance of ``SOCK_STREAM`` type),
and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
an SSL context. Returned object has the usual stream interface methods like
`read()`, `write()`, etc. In MicroPython, the returned object does not expose
socket interface and methods like `recv()`, `send()`. In particular, a
server-side SSL socket should be created from a normal socket returned from
`accept()` on a non-SSL listening server socket.
Depending on the underlying module implementation for a particular board,
some or all keyword arguments above may be not supported.
.. warning::
.. warning::
Currently, this function does NOT validate server certificates, which makes
an SSL connection established prone to man-in-the-middle attacks.
Some implementations of ``ssl`` module do NOT validate server certificates,
which makes an SSL connection established prone to man-in-the-middle attacks.
Exceptions
----------
.. only:: port_wipy
.. data:: ssl.SSLError
Functions
---------
This exception does NOT exist. Instead its base class, OSError, is used.
.. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None)
Constants
---------
Takes an instance sock of socket.socket, and returns an instance of ssl.SSLSocket, a subtype of
``socket.socket``, which wraps the underlying socket in an SSL context. sock must be a ``SOCK_STREAM``
socket and protocol number ``socket.IPPROTO_SEC``; other socket types are unsupported. Example::
.. data:: ssl.CERT_NONE
ssl.CERT_OPTIONAL
ssl.CERT_REQUIRED
import socket
import ssl
s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
ss = ssl.wrap_socket(s)
ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1])
Certificates must be used in order to validate the other side of the connection, and also to
authenticate ourselves with the other end. Such certificates must be stored as files using the
FTP server, and they must be placed in specific paths with specific names.
- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'**
- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'**
- The key for our own certificate goes in: **'/flash/cert/private.key'**
.. note::
When these files are stored, they are placed inside the internal **hidden** file system
(just like firmware updates), and therefore they are never visible.
For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located
in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_
and put it in '/flash/cert/'. Then do::
import socket
import ssl
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem')
ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1])
SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module.
Exceptions
----------
.. data:: ssl.SSLError
Constants
---------
.. data:: ssl.CERT_NONE
.. data:: ssl.CERT_OPTIONAL
.. data:: ssl.CERT_REQUIRED
supported values in ``cert_reqs``
Supported values for `cert_reqs` parameter.

View File

@ -254,6 +254,29 @@ SSL sockets need to be created the following way before wrapping them with.
s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
ss = ssl.wrap_socket(s)
Certificates must be used in order to validate the other side of the connection, and also to
authenticate ourselves with the other end. Such certificates must be stored as files using the
FTP server, and they must be placed in specific paths with specific names.
- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'**
- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'**
- The key for our own certificate goes in: **'/flash/cert/private.key'**
.. note::
When these files are stored, they are placed inside the internal **hidden** file system
(just like firmware updates), and therefore they are never visible.
For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located
in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_.
and put it in '/flash/cert/'. Then do::
import socket
import ssl
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem')
ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1])
Incompatibilities in uhashlib module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~