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

docs/library/ussl.rst

-: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.
-
-.. only:: not port_wipy
+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
 ---------
 
-    .. function:: ssl.wrap_socket(sock, server_side=False)
+.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None)
 
    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
@@ -23,64 +21,26 @@ network sockets, both client-side and server-side.
    server-side SSL socket should be created from a normal socket returned from
    `accept()` on a non-SSL listening server socket.
 
-    .. warning::
-
-       Currently, this function does NOT validate server certificates, which makes
-       an SSL connection established prone to man-in-the-middle attacks.
-
-
-.. only:: port_wipy
-
-    Functions
-    ---------
-
-    .. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None)
+   Depending on the underlying module implementation for a particular board,
+   some or all keyword arguments above may be not supported.
 
-       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::
-
-          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])
+.. warning::
 
-       SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module.
+   Some implementations of ``ssl`` module do NOT validate server certificates,
+   which makes an SSL connection established prone to man-in-the-middle attacks.
 
 Exceptions
 ----------
 
 .. data:: ssl.SSLError
 
+   This exception does NOT exist. Instead its base class, OSError, is used.
+
 Constants
 ---------
 
 .. data:: ssl.CERT_NONE
-    .. data:: ssl.CERT_OPTIONAL
-    .. data:: ssl.CERT_REQUIRED
+          ssl.CERT_OPTIONAL
+          ssl.CERT_REQUIRED
 
-        supported values in ``cert_reqs``
+    Supported values for `cert_reqs` parameter.

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