Skip to content

Commit bca4c9e

Browse files
pfalconpfalcon
committed
docs/ussl: Add basic description of axTLS-based modussl.
In particular, disclose the fact that server certificates are not validated.
1 parent cb7693b commit bca4c9e

1 file changed

Lines changed: 61 additions & 38 deletions

File tree

‎docs/library/ussl.rst‎

Lines changed: 61 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -8,56 +8,79 @@ This module provides access to Transport Layer Security (often known as
88
“Secure Sockets Layer”) encryption and peer authentication facilities for
99
network sockets, both client-side and server-side.
1010

11-
Functions
12-
---------
11+
.. only:: not port_wipy
1312

14-
.. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None)
13+
Functions
14+
---------
1515

16-
Takes an instance sock of socket.socket, and returns an instance of ssl.SSLSocket, a subtype of
17-
``socket.socket``, which wraps the underlying socket in an SSL context. sock must be a ``SOCK_STREAM``
18-
socket and protocol number ``socket.IPPROTO_SEC``; other socket types are unsupported. Example::
16+
.. function:: ssl.wrap_socket(sock, server_side=False)
1917

20-
import socket
21-
import ssl
22-
s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
23-
ss = ssl.wrap_socket(s)
24-
ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1])
18+
Takes a stream `sock` (usually usocket.socket instance of ``SOCK_STREAM`` type),
19+
and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
20+
an SSL context. Returned object has the usual stream interface methods like
21+
`read()`, `write()`, etc. In MicroPython, the returned object does not expose
22+
socket interface and methods like `recv()`, `send()`. In particular, a
23+
server-side SSL socket should be created from a normal socket returned from
24+
`accept()` on a non-SSL listening server socket.
2525

26-
Certificates must be used in order to validate the other side of the connection, and also to
27-
authenticate ourselves with the other end. Such certificates must be stored as files using the
28-
FTP server, and they must be placed in specific paths with specific names.
26+
.. warning::
2927

30-
- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'**
31-
- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'**
32-
- The key for our own certificate goes in: **'/flash/cert/private.key'**
28+
Currently, this function does NOT validate server certificates, which makes
29+
an SSL connection established prone to man-in-the-middle attacks.
3330

34-
.. note::
3531

36-
When these files are stored, they are placed inside the internal **hidden** file system
37-
(just like firmware updates), and therefore they are never visible.
32+
.. only:: port_wipy
3833

39-
For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located
40-
in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_
41-
and put it in '/flash/cert/'. Then do::
34+
Functions
35+
---------
4236

43-
import socket
44-
import ssl
45-
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
46-
ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem')
47-
ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1])
37+
.. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None)
4838

49-
SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module.
39+
Takes an instance sock of socket.socket, and returns an instance of ssl.SSLSocket, a subtype of
40+
``socket.socket``, which wraps the underlying socket in an SSL context. sock must be a ``SOCK_STREAM``
41+
socket and protocol number ``socket.IPPROTO_SEC``; other socket types are unsupported. Example::
5042

51-
Exceptions
52-
----------
43+
import socket
44+
import ssl
45+
s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
46+
ss = ssl.wrap_socket(s)
47+
ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1])
5348

54-
.. data:: ssl.SSLError
49+
Certificates must be used in order to validate the other side of the connection, and also to
50+
authenticate ourselves with the other end. Such certificates must be stored as files using the
51+
FTP server, and they must be placed in specific paths with specific names.
5552

56-
Constants
57-
---------
53+
- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'**
54+
- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'**
55+
- The key for our own certificate goes in: **'/flash/cert/private.key'**
5856

59-
.. data:: ssl.CERT_NONE
60-
.. data:: ssl.CERT_OPTIONAL
61-
.. data:: ssl.CERT_REQUIRED
57+
.. note::
6258

63-
supported values in ``cert_reqs``
59+
When these files are stored, they are placed inside the internal **hidden** file system
60+
(just like firmware updates), and therefore they are never visible.
61+
62+
For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located
63+
in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_
64+
and put it in '/flash/cert/'. Then do::
65+
66+
import socket
67+
import ssl
68+
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
69+
ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem')
70+
ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1])
71+
72+
SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module.
73+
74+
Exceptions
75+
----------
76+
77+
.. data:: ssl.SSLError
78+
79+
Constants
80+
---------
81+
82+
.. data:: ssl.CERT_NONE
83+
.. data:: ssl.CERT_OPTIONAL
84+
.. data:: ssl.CERT_REQUIRED
85+
86+
supported values in ``cert_reqs``

0 commit comments

Comments
 (0)