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

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 <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.
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 <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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~