From ac8843ceecb645b11737ea42d0f4248d742383cd Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 09:41:32 +0300 Subject: [PATCH] docs/library/ussl: Deconditionalize, wipy notes moved to its documentation. --- docs/library/ussl.rst | 100 +++++++++++++----------------------------- docs/wipy/general.rst | 23 ++++++++++ 2 files changed, 53 insertions(+), 70 deletions(-) diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index 5371ed1290..36f6d65a4a 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -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 `_ - 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. diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index eca9bbe459..024f789660 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -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 `_. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~