doc words

irmen · Aug 6, 2017 · 9fb0db6 · 9fb0db6
1 parent afe939d
commit 9fb0db6
Show file tree

Hide file tree

Showing 6 changed files with 15 additions and 8 deletions.
diff --git a/certs/readme.txt b/certs/readme.txt
@@ -7,3 +7,6 @@ https://docs.python.org/3/library/ssl.html#self-signed-certificates
 
 $ openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout key.pem
 
+
+It's also possible to make your own CA certs and sign your client and server certs
+with them, but that is a lot more elaborate.
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -5,7 +5,7 @@ Change Log
 **Pyro 4.62**
 
 - **SSL/TLS support added** - a handful of new config items ('SSL' prefixed), supports
-  server-only certificate and also 2-way-ssl (client certificates).
+  server-only certificate and also 2-way-ssl (server+client certificates).
   For testing purposes, self-signed server and client certificates are available in the 'certs' directory.
   SSL/TLS in Pyro is supported on Python 2.7.9+ or Python 3.4.3+
 - added SSL example that shows how to configure 2-way-SSL in Pyro and how to do certificate verification on both sides.

diff --git a/docs/source/config.rst b/docs/source/config.rst
@@ -116,11 +116,11 @@ MAX_RETRIES               int     0                       Automatically retry ne
 ITER_STREAMING            bool    True                    Should iterator item streaming support be enabled in the server (default=True)
 ITER_STREAM_LIFETIME      float   0.0                     Maximum lifetime in seconds for item streams (default=0, no limit - iterator only stops when exhausted or client disconnects)
 ITER_STREAM_LINGER        float   30.0                    Linger time in seconds to keep an item stream alive after proxy disconnects (allows to reconnect to stream)
-SSL                       bool    False                   Should SSL/TSL encryption be used
+SSL                       bool    False                   Should SSL/TSL communication security be used
 SSL_SERVERCERT            str     certs/server_cert.pem   Location of the server's certificate file
 SSL_SERVERKEY             str     certs/server_key.pem    Location of the server's private key file
 SSL_SERVERKEYPASSWD       str     *empty str*             Password for the server's private key
-SSL_REQUIRECLIENTCERT     bool    False                   Should the server require clients to connect with a certificate (2-way-ssl)
+SSL_REQUIRECLIENTCERT     bool    False                   Should the server require clients to connect with their own certificate (2-way-ssl)
 SSL_CLIENTCERT            str     *empty str*             Location of the client's certificate file
 SSL_CLIENTKEY             str     *empty str*             Location of the client's private key file
 SSL_CLIENTKEYPASSWD       str     *empty str*             Password for the client's private key

diff --git a/docs/source/intro.rst b/docs/source/intro.rst
@@ -30,7 +30,7 @@ Here's a quick overview of Pyro's features:
 - supports different serializers (serpent, json, marshal, msgpack, pickle, dill).
 - support for all Python data types that are serializable when using the 'pickle' or 'dill' serializers [1]_.
 - can use IPv4, IPv6 and Unix domain sockets.
-- optional encryped connections via SSL/TLS, including certificate validation on both ends (2-way ssl).
+- optional secure connections via SSL/TLS (encryption, authentication and integrity), including certificate validation on both ends (2-way ssl).
 - lightweight client library available for .NET and Java native code ('Pyrolite', provided separately).
 - designed to be very easy to use and get out of your way as much as possible, but still provide a lot of flexibility when you do need it.
 - name server that keeps track of your object's actual locations so you can move them around transparently.

diff --git a/docs/source/security.rst b/docs/source/security.rst
@@ -58,15 +58,16 @@ You may need additional security measures to prevent random users from calling y
 .. index:: SSL, TLS
     double: security; encryption
 
-Protocol encryption via SSL/TLS
-===============================
+Secure communication via SSL/TLS
+================================
 Pyro itself doesn't encrypt the data it sends over the network. This means if you use the default
 configuration, you must never transfer sensitive data on untrusted networks
 (especially user data, passwords, and such) because eavesdropping is possible.
 
 You can run Pyro over a secure network (VPN, ssl/ssh tunnel) where the encryption
 is taken care of externally. It is also possible however to enable SSL/TLS in Pyro itself,
-so that all communication is encrypted.
+so that all communication is secured via this industry standard that
+provides encryption, authentication, and anti-tampering (message integrity).
 
 **Using SSL/TLS**
 

diff --git a/examples/diffie-hellman/Readme.txt b/examples/diffie-hellman/Readme.txt
@@ -15,7 +15,10 @@ This shared secret key is then used as Pyro HMAC key to authenticate the message
 
 A few IMPORTANT notes:
 
-- there is NO ENCRYPTION done whatsoever, that's something else! Which Pyro doesn't provide by itself.
+- in this particular example there is NO ENCRYPTION done whatsoever. Encryption is a different topic!
+  If you want, you can enable SSL/TLS in Pyro as well to provide this. However, if you use 2-way-ssl,
+  this makes the use of the HMAC key somewhat obsolete, because mutual verification of the SSL certificates
+  essentially then does the same thing. See the SSL example for more details.
 - this example shows an approach on a safe way to agree on a shared secret key. It then uses this
   for Pyro's HMAC key but that's just for the sake of example.
 - it's a rather silly example because in Pyro, the HMAC key is a per-daemon setting. ALL calls to objects