adds full docs

wrapper/python/wolfssl/docs/api.rst

@@ -1,23 +1,21 @@
-API
-===
+API Documentation
+=================
 
 .. module:: wolfssl
 
+wrap_socket
+-----------
+
+.. autofunction:: wrap_socket
+
 SSL/TLS Context
 ---------------
 
-SSLContext
-~~~~~~~~~~
-
 .. autoclass:: SSLContext
     :members:
 
 SSL/TLS Socket
 --------------
 
-
-SSLSocket
-~~~~~~~~~
-
 .. autoclass:: SSLSocket
     :members:

wrapper/python/wolfssl/docs/examples.rst

@@ -0,0 +1,95 @@
+Client and Server Examples
+==========================
+
+SSL/TLS Client Example
+----------------------
+
+.. code-block:: python
+
+    import socket
+    import wolfssl
+    
+    CA_DATA = \
+    """
+    -----BEGIN CERTIFICATE-----
+    MIIDxTCCAq2gAwIBAgIQAqxcJmoLQJuPC3nyrkYldzANBgkqhkiG9w0BAQUFADBs
+    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
+    d3cuZGlnaWNlcnQuY29tMSswKQYDVQQDEyJEaWdpQ2VydCBIaWdoIEFzc3VyYW5j
+    ZSBFViBSb290IENBMB4XDTA2MTExMDAwMDAwMFoXDTMxMTExMDAwMDAwMFowbDEL
+    MAkGA1UEBhMCVVMxFTATBgNVBAoTDERpZ2lDZXJ0IEluYzEZMBcGA1UECxMQd3d3
+    LmRpZ2ljZXJ0LmNvbTErMCkGA1UEAxMiRGlnaUNlcnQgSGlnaCBBc3N1cmFuY2Ug
+    RVYgUm9vdCBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMbM5XPm
+    +9S75S0tMqbf5YE/yc0lSbZxKsPVlDRnogocsF9ppkCxxLeyj9CYpKlBWTrT3JTW
+    PNt0OKRKzE0lgvdKpVMSOO7zSW1xkX5jtqumX8OkhPhPYlG++MXs2ziS4wblCJEM
+    xChBVfvLWokVfnHoNb9Ncgk9vjo4UFt3MRuNs8ckRZqnrG0AFFoEt7oT61EKmEFB
+    Ik5lYYeBQVCmeVyJ3hlKV9Uu5l0cUyx+mM0aBhakaHPQNAQTXKFx01p8VdteZOE3
+    hzBWBOURtCmAEvF5OYiiAhF8J2a3iLd48soKqDirCmTCv2ZdlYTBoSUeh10aUAsg
+    EsxBu24LUTi4S8sCAwEAAaNjMGEwDgYDVR0PAQH/BAQDAgGGMA8GA1UdEwEB/wQF
+    MAMBAf8wHQYDVR0OBBYEFLE+w2kD+L9HAdSYJhoIAu9jZCvDMB8GA1UdIwQYMBaA
+    FLE+w2kD+L9HAdSYJhoIAu9jZCvDMA0GCSqGSIb3DQEBBQUAA4IBAQAcGgaX3Nec
+    nzyIZgYIVyHbIUf4KmeqvxgydkAQV8GK83rZEWWONfqe/EW1ntlMMUu4kehDLI6z
+    eM7b41N5cdblIZQB2lWHmiRk9opmzN6cN82oNLFpmyPInngiK3BD41VHMWEZ71jF
+    hS9OMPagMRYjyOfiZRYzy78aG6A9+MpeizGLYAiJLQwGXFK3xPkKmNEVX58Svnw2
+    Yzi9RKR/5CYrCsSXaQ3pjOLAEFe4yHYSkVXySGnYvCoCWw9E1CAx2/S6cCZdkGCe
+    vEsXCS+0yx5DaMkHJ8HSXPfqIbloEpw8nL+e/IBcm2PN7EeqJSdnoDfzAIJ9VNep
+    +OkuE6N36B9K
+    -----END CERTIFICATE-----
+    """
+    
+    bind_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+    
+    context = wolfssl.SSLContext(wolfssl.PROTOCOL_TLSv1_2)
+    
+    context.verify_mode = wolfssl.CERT_REQUIRED
+    context.load_verify_locations(cadata=CA_DATA)
+    
+    secure_socket = context.wrap_socket(bind_socket)
+    
+    secure_socket.connect(("www.python.org", 443))
+    
+    secure_socket.write(b"GET / HTTP/1.1\n\n")
+    
+    print(secure_socket.read())
+    
+    secure_socket.close()
+
+
+SSL/TLS Server Example
+----------------------
+
+.. code-block:: python
+
+    import socket
+    import wolfssl
+    
+    bind_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+    
+    bind_socket.bind(("", 4433))
+    bind_socket.listen(5)
+    
+    context = wolfssl.SSLContext(wolfssl.PROTOCOL_TLSv1_2, server_side=True)
+    
+    context.load_cert_chain("certs/server-cert.pem", "certs/server-key.pem")
+    
+    while True:
+        try:
+            secure_socket = None
+            
+            new_socket, from_addr = bind_socket.accept()
+            
+            secure_socket = context.wrap_socket(new_socket)
+            
+            print("Connection received from", from_addr)
+            
+            print("\n", secure_socket.read(), "\n")
+            secure_socket.write(b"I hear you fa shizzle!")
+            
+        except KeyboardInterrupt:
+            print()
+            break
+        
+        finally:
+            if secure_socket:
+                secure_socket.close()
+    
+    bind_socket.close()

wrapper/python/wolfssl/docs/index.rst

@@ -1,15 +1,13 @@
 .. include:: ../README.rst
 
 Summary
--------
+=======
 
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 2
 
-   context
-   socket
-
-.. automodule:: wolfssl
-   :members:
+    usage
+    api
+    examples
 
 .. include:: ../LICENSING.rst

wrapper/python/wolfssl/docs/installation.rst

@@ -1 +0,0 @@
-.. include:: ../README.rst

wrapper/python/wolfssl/docs/licensing.rst

@@ -1 +0,0 @@
-.. include:: ../LICENSING.rst

wrapper/python/wolfssl/docs/usage.rst

@@ -1,8 +1,87 @@
-Usage
-=====
+Basic Usage
+===========
 
-SSL/TLS Client
---------------
+The SSL/TLS protocol works securing an underlying TCP connection, this module
+adds the secure layer around the Python standard library 
+`socket <https://docs.python.org/3.6/library/socket.html>`_ module.
 
-SSL/TLS Server
---------------
+There are three different paths to secure a socket in this module:
+
+* Using the top level function wolfssl.wrap_socket();
+* Using the method wrap_socket() from a SSLContext instance;
+* Creating an SSLSocket object from the scratch.
+
+Note 1:
+    It is possible to use the same SSLContext for multiple SSLSockets to save
+    time and resources.
+
+Note 2:
+    Each path provides its own options for fine-tuning the securint parameters.
+    Check them out in the API documentation.
+
+
+Using the top level function wolfssl.wrap_socket()
+--------------------------------------------------
+
+.. code-block:: python
+
+    >>> import socket
+    >>> import wolfssl
+    >>>
+    >>> sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+    >>>
+    >>> secure_socket = wolfssl.wrap_socket(sock)
+    >>>
+    >>> secure_socket.connect(("www.python.org", 443))
+    >>>
+    >>> secure_socket.write(b"GET / HTTP/1.1\n\n")
+    >>>
+    >>> print(secure_socket.read())
+    b'HTTP/1.1 500 Domain Not Found\r\nServer: Varnish\r\nRetry-After: 0\r\ncontent-type: text/html\r\nCache-Control: private, no-cache\r\nconnection: keep-alive\r\nContent-Length: 179\r\nAccept-Ranges: bytes\r\nDate: Sun, 05 Feb 2017 21:26:48 GMT\r\nVia: 1.1 varnish\r\nConnection: keep-alive\r\n\r\n\n<html>\n<head>\n<title>Fastly error: unknown domain </title>\n</head>\n<body>\nFastly error: unknown domain: . Please check that this domain has been added to a service.</body></html>'
+    >>>
+    >>> secure_socket.close()
+
+
+Using the method wrap_socket() from a SSLContext instance
+---------------------------------------------------------
+
+.. code-block:: python
+
+    >>> import socket
+    >>> import wolfssl
+    >>>
+    >>> sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+    >>>
+    >>> context = wolfssl.SSLContext(wolfssl.PROTOCOL_TLSv1_2)
+    >>>
+    >>> secure_socket = context.wrap_socket(sock)
+    >>>
+    >>> secure_socket.connect(("www.python.org", 443))
+    >>>
+    >>> secure_socket.write(b"GET / HTTP/1.1\n\n")
+    >>>
+    >>> print(secure_socket.read())
+    b'HTTP/1.1 500 Domain Not Found\r\nServer: Varnish\r\nRetry-After: 0\r\ncontent-type: text/html\r\nCache-Control: private, no-cache\r\nconnection: keep-alive\r\nContent-Length: 179\r\nAccept-Ranges: bytes\r\nDate: Sun, 05 Feb 2017 21:26:48 GMT\r\nVia: 1.1 varnish\r\nConnection: keep-alive\r\n\r\n\n<html>\n<head>\n<title>Fastly error: unknown domain </title>\n</head>\n<body>\nFastly error: unknown domain: . Please check that this domain has been added to a service.</body></html>'
+    >>>
+    >>> secure_socket.close()
+
+Creating an SSLSocket object from the scratch
+---------------------------------------------
+
+.. code-block:: python
+
+    >>> import socket
+    >>> import wolfssl
+    >>>
+    >>> sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
+    >>>
+    >>> secure_socket = wolfssl.SSLSocket(sock)
+    >>>
+    >>> secure_socket.connect(("www.python.org", 443))
+    >>>
+    >>> secure_socket.write(b"GET / HTTP/1.1\n\n")
+    >>>
+    >>> print(secure_socket.read())
+    b'HTTP/1.1 500 Domain Not Found\r\nServer: Varnish\r\nRetry-After: 0\r\ncontent-type: text/html\r\nCache-Control: private, no-cache\r\nconnection: keep-alive\r\nContent-Length: 179\r\nAccept-Ranges: bytes\r\nDate: Sun, 05 Feb 2017 21:26:48 GMT\r\nVia: 1.1 varnish\r\nConnection: keep-alive\r\n\r\n\n<html>\n<head>\n<title>Fastly error: unknown domain </title>\n</head>\n<body>\nFastly error: unknown domain: . Please check that this domain has been added to a service.</body></html>'
+    >>>
+    >>> secure_socket.close()