Patch 10124 by Bill Janssen, docs for the new ssl code.
This commit is contained in:
Guido van Rossum
parent
780b80dc08
commit
8ee23bbe7c
|
|
@ -19,6 +19,7 @@ The list of modules described in this chapter is:
|
|||
|
||||
subprocess.rst
|
||||
socket.rst
|
||||
ssl.rst
|
||||
signal.rst
|
||||
popen2.rst
|
||||
asyncore.rst
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
|
||||
|
||||
This module provides access to the BSD *socket* interface. It is available on
|
||||
all modern Unix systems, Windows, MacOS, BeOS, OS/2, and probably additional
|
||||
all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional
|
||||
platforms.
|
||||
|
||||
.. note::
|
||||
|
|
@ -300,17 +300,6 @@ The module :mod:`socket` exports the following constants and functions:
|
|||
omitted in that case.
|
||||
|
||||
|
||||
.. function:: ssl(sock[, keyfile, certfile])
|
||||
|
||||
Initiate a SSL connection over the socket *sock*. *keyfile* is the name of a PEM
|
||||
formatted file that contains your private key. *certfile* is a PEM formatted
|
||||
certificate chain file. On success, a new :class:`SSLObject` is returned.
|
||||
|
||||
.. warning::
|
||||
|
||||
This does not do any certificate verification!
|
||||
|
||||
|
||||
.. function:: socketpair([family[, type[, proto]]])
|
||||
|
||||
Build a pair of connected socket objects using the given address family, socket
|
||||
|
|
@ -752,49 +741,6 @@ values given to the :class:`socket` constructor.
|
|||
.. versionadded:: 2.5
|
||||
|
||||
|
||||
.. _ssl-objects:
|
||||
|
||||
SSL Objects
|
||||
-----------
|
||||
|
||||
SSL objects have the following methods.
|
||||
|
||||
|
||||
.. method:: SSL.write(s)
|
||||
|
||||
Writes the string *s* to the on the object's SSL connection. The return value is
|
||||
the number of bytes written.
|
||||
|
||||
|
||||
.. method:: SSL.read([n])
|
||||
|
||||
If *n* is provided, read *n* bytes from the SSL connection, otherwise read until
|
||||
EOF. The return value is a string of the bytes read.
|
||||
|
||||
|
||||
.. method:: SSL.server()
|
||||
|
||||
Returns a string describing the server's certificate. Useful for
|
||||
debugging purposes; do not parse the content of this string because
|
||||
its format can't be parsed unambiguously. And don't *trust* the
|
||||
content of this string, because certificates aren't validated if you
|
||||
use the function :func:`ssl` to create an SSL binding. If you need to
|
||||
see the content of a peer certificate, you should use the
|
||||
:func:`sslsocket` function in the :mod:`ssl` module to create the SSL
|
||||
object, specifying the parameter `cert_req` as :const:`CERT_REQUIRED`,
|
||||
and passing the name of a file containing a collection of certificates
|
||||
to use to validate the peer certificate as the value of the `ca_certs`
|
||||
parameter. Then use the :meth:`getpeercert` method on that instance
|
||||
to retrieve the contents of the certificate.
|
||||
|
||||
|
||||
.. method:: SSL.issuer()
|
||||
|
||||
Returns a string describing the issuer of the server's certificate. Useful for
|
||||
debugging purposes; do not parse the content of this string because its format
|
||||
can't be parsed unambiguously.
|
||||
|
||||
|
||||
.. _socket-example:
|
||||
|
||||
Example
|
||||
|
|
@ -912,39 +858,3 @@ sends traffic to the first one connected successfully. ::
|
|||
s.close()
|
||||
print 'Received', repr(data)
|
||||
|
||||
This example connects to an SSL server, prints the server and issuer's
|
||||
distinguished names, sends some bytes, and reads part of the response::
|
||||
|
||||
import socket
|
||||
|
||||
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||
s.connect(('www.verisign.com', 443))
|
||||
|
||||
ssl_sock = socket.ssl(s)
|
||||
|
||||
print repr(ssl_sock.server())
|
||||
print repr(ssl_sock.issuer())
|
||||
|
||||
# Set a simple HTTP request -- use httplib in actual code.
|
||||
ssl_sock.write("""GET / HTTP/1.0\r
|
||||
Host: www.verisign.com\r\n\r\n""")
|
||||
|
||||
# Read a chunk of data. Will not necessarily
|
||||
# read all the data returned by the server.
|
||||
data = ssl_sock.read()
|
||||
|
||||
# Note that you need to close the underlying socket, not the SSL object.
|
||||
del ssl_sock
|
||||
s.close()
|
||||
|
||||
At this writing, this SSL example prints the following output (line breaks
|
||||
inserted for readability)::
|
||||
|
||||
'/C=US/ST=California/L=Mountain View/
|
||||
O=VeriSign, Inc./OU=Production Services/
|
||||
OU=Terms of use at www.verisign.com/rpa (c)00/
|
||||
CN=www.verisign.com'
|
||||
'/O=VeriSign Trust Network/OU=VeriSign, Inc./
|
||||
OU=VeriSign International Server CA - Class 3/
|
||||
OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,319 @@
|
|||
|
||||
:mod:`ssl` --- SSL wrapper for socket objects, and utility functions
|
||||
====================================================================
|
||||
|
||||
.. module:: ssl
|
||||
:synopsis: SSL wrapper for socket objects, and utility functions
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
|
||||
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 uses the OpenSSL library. It is available on all modern
|
||||
Unix systems, Windows, Mac OS X, and probably additional
|
||||
platforms, as long as OpenSSL is installed on that platform.
|
||||
|
||||
.. note::
|
||||
|
||||
Some behavior may be platform dependent, since calls are made to the operating
|
||||
system socket APIs.
|
||||
|
||||
This section documents the objects and functions in the `ssl` module;
|
||||
for more general information about TLS, SSL, and certificates, the
|
||||
reader is referred to the paper, *Introducing SSL and Certificates using OpenSSL*, by Frederick J. Hirsch, at
|
||||
http://old.pseudonym.org/ssl/wwwj-index.html.
|
||||
|
||||
This module defines a class, :class:`ssl.sslsocket`, which is
|
||||
derived from the :class:`socket.socket` type, and supports additional
|
||||
:meth:`read` and :meth:`write` methods, along with a method, :meth:`getpeercert`,
|
||||
to retrieve the certificate of the other side of the connection.
|
||||
|
||||
This module defines the following functions, exceptions, and constants:
|
||||
|
||||
.. function:: cert_time_to_seconds(timestring)
|
||||
|
||||
Returns a floating-point value containing a normal seconds-after-the-epoch time
|
||||
value, given the time-string representing the "notBefore" or "notAfter" date
|
||||
from a certificate.
|
||||
|
||||
Here's an example::
|
||||
|
||||
>>> import ssl
|
||||
>>> ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT")
|
||||
1178694000.0
|
||||
>>> import time
|
||||
>>> time.ctime(ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT"))
|
||||
'Wed May 9 00:00:00 2007'
|
||||
>>>
|
||||
|
||||
.. exception:: sslerror
|
||||
|
||||
Raised to signal an error from the underlying SSL implementation. This
|
||||
signifies some problem in the higher-level
|
||||
encryption and authentication layer that's superimposed on the underlying
|
||||
network connection.
|
||||
|
||||
.. data:: CERT_NONE
|
||||
|
||||
Value to pass to the `cert_reqs` parameter to :func:`sslobject`
|
||||
when no certificates will be required or validated from the other
|
||||
side of the socket connection.
|
||||
|
||||
.. data:: CERT_OPTIONAL
|
||||
|
||||
Value to pass to the `cert_reqs` parameter to :func:`sslobject`
|
||||
when no certificates will be required from the other side of the
|
||||
socket connection, but if they are provided, will be validated.
|
||||
Note that use of this setting requires a valid certificate
|
||||
validation file also be passed as a value of the `ca_certs`
|
||||
parameter.
|
||||
|
||||
.. data:: CERT_REQUIRED
|
||||
|
||||
Value to pass to the `cert_reqs` parameter to :func:`sslobject`
|
||||
when certificates will be required from the other side of the
|
||||
socket connection. Note that use of this setting requires a valid certificate
|
||||
validation file also be passed as a value of the `ca_certs`
|
||||
parameter.
|
||||
|
||||
.. data:: PROTOCOL_SSLv2
|
||||
|
||||
Selects SSL version 2 as the channel encryption protocol.
|
||||
|
||||
.. data:: PROTOCOL_SSLv23
|
||||
|
||||
Selects SSL version 2 or 3 as the channel encryption protocol. This is a setting to use for maximum compatibility
|
||||
with the other end of an SSL connection, but it may cause the specific ciphers chosen for the encryption to be
|
||||
of fairly low quality.
|
||||
|
||||
.. data:: PROTOCOL_SSLv3
|
||||
|
||||
Selects SSL version 3 as the channel encryption protocol.
|
||||
|
||||
.. data:: PROTOCOL_TLSv1
|
||||
|
||||
Selects SSL version 2 as the channel encryption protocol. This is
|
||||
the most modern version, and probably the best choice for maximum
|
||||
protection, if both sides can speak it.
|
||||
|
||||
|
||||
Certificates
|
||||
------------
|
||||
|
||||
Certificates in general are part of a public-key / private-key system. In this system, each `principal`,
|
||||
(which may be a machine, or a person, or an organization) is assigned a unique two-part encryption key.
|
||||
One part of the key is public, and is called the *public key*; the other part is kept secret, and is called
|
||||
the *private key*. The two parts are related, in that if you encrypt a message with one of the parts, you can
|
||||
decrypt it with the other part, and **only** with the other part.
|
||||
|
||||
A certificate contains information about two principals. It contains
|
||||
the name of a *subject*, and the subject's public key. It also
|
||||
contains a statement by a second principal, the *issuer*, that the
|
||||
subject is who he claims to be, and that this is indeed the subject's
|
||||
public key. The issuer's statement is signed with the issuer's
|
||||
private key, which only the issuer knows. However, anyone can verify
|
||||
the issuer's statement by finding the issuer's public key, decrypting
|
||||
the statement with it, and comparing it to the other information in
|
||||
the certificate. The certificate also contains information about the
|
||||
time period over which it is valid. This is expressed as two fields,
|
||||
called "notBefore" and "notAfter".
|
||||
|
||||
The underlying system which is used in the Python SSL support is
|
||||
called "OpenSSL". It contains facilities for constructing and
|
||||
validating certificates. In the Python use of certificates, the other
|
||||
side of a network connection can be required to produce a certificate,
|
||||
and that certificate can be validated against a file filled with
|
||||
self-signed *root* certificates (so-called because the issuer is the
|
||||
same as the subject), and and "CA" (certification authority)
|
||||
certificates assured by those root certificates (and by other CA
|
||||
certificates). Either side of a connection, client or server, can
|
||||
request certificates and validation, and the connection can be optionally
|
||||
set up to fail if a valid certificate is not presented by the other side.
|
||||
|
||||
|
||||
sslsocket Objects
|
||||
-----------------
|
||||
|
||||
.. class:: sslsocket(sock [, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_SSLv23, ca_certs=None])
|
||||
|
||||
Takes an instance *sock* of :class:`socket.socket`, and returns an instance of a subtype
|
||||
of :class:`socket.socket` which wraps the underlying socket in an SSL context.
|
||||
For client-side sockets, the context construction is lazy; if the underlying socket isn't
|
||||
connected yet, the context construction will be performed after :meth:`connect` is called
|
||||
on the socket.
|
||||
|
||||
The `keyfile` and `certfile` parameters specify optional files which contain a certificate
|
||||
to be used to identify the local side of the connection. Often the private key is stored
|
||||
in the same file as the certificate; in this case, only the `certfile` parameter need be
|
||||
passed. If the private key is stored in a separate file, both parameters must be used.
|
||||
|
||||
The parameter `server_side` is a boolean which identifies whether server-side or client-side
|
||||
behavior is desired from this socket.
|
||||
|
||||
The parameter `cert_reqs` specifies whether a certificate is
|
||||
required from the other side of the connection, and whether it will
|
||||
be validated if provided. It must be one of the three values
|
||||
:const:`CERT_NONE` (certificates ignored), :const:`CERT_OPTIONAL` (not required,
|
||||
but validated if provided), or :const:`CERT_REQUIRED` (required and
|
||||
validated). If the value of this parameter is not :const:`CERT_NONE`, then
|
||||
the `ca_certs` parameter must point to a file of CA certificates.
|
||||
|
||||
The parameter `ssl_version` specifies which version of the SSL protocol to use. Typically,
|
||||
the server specifies this, and a client connecting to it must use the same protocol. An
|
||||
SSL server using :const:`PROTOCOL_SSLv23` can understand a client connecting via SSL2, SSL3, or TLS1,
|
||||
but a client using :const:`PROTOCOL_SSLv23` can only connect to an SSL2 server.
|
||||
|
||||
The `ca_certs` file contains a set of concatenated "certification authority" certificates,
|
||||
which are used to validate certificates passed from the other end of the connection.
|
||||
This file
|
||||
contains the certificates in PEM format (IETF RFC 1422) where each certificate is
|
||||
encoded in base64 encoding and surrounded with a header and footer::
|
||||
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... (CA certificate in base64 encoding) ...
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
The various certificates in the file are just concatenated together::
|
||||
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... (CA certificate in base64 encoding) ...
|
||||
-----END CERTIFICATE-----
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... (a second CA certificate in base64 encoding) ...
|
||||
-----END CERTIFICATE-----
|
||||
-----BEGIN CERTIFICATE-----
|
||||
... (a root certificate in base64 encoding) ...
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
Some "standard" root certificates are available at
|
||||
http://www.thawte.com/roots/ (for Thawte roots) and
|
||||
http://www.verisign.com/support/roots.html (for Verisign roots).
|
||||
|
||||
.. method:: sslsocket.read([nbytes])
|
||||
|
||||
Reads up to `nbytes` bytes from the SSL-encrypted channel and returns them.
|
||||
|
||||
.. method:: sslsocket.write(data)
|
||||
|
||||
Writes the `data` to the other side of the connection, using the SSL channel to encrypt. Returns the number
|
||||
of bytes written.
|
||||
|
||||
.. method:: sslsocket.getpeercert()
|
||||
|
||||
If there is no certificate for the peer on the other end of the connection, returns `None`.
|
||||
If a certificate was received from the peer, but not validated, returns an empty `dict` instance.
|
||||
If a certificate was received and validated, returns a `dict` instance with the fields
|
||||
`subject` (the principal for which the certificate was issued), `issuer` (the signer of
|
||||
the certificate), `notBefore` (the time before which the certificate should not be trusted),
|
||||
and `notAfter` (the time after which the certificate should not be trusted) filled in.
|
||||
|
||||
The "subject" and "issuer" fields are themselves dictionaries containing the fields given
|
||||
in the certificate's data structure for each principal::
|
||||
|
||||
{'issuer': {'commonName': u'somemachine.python.org',
|
||||
'countryName': u'US',
|
||||
'localityName': u'Wilmington',
|
||||
'organizationName': u'Python Software Foundation',
|
||||
'organizationalUnitName': u'SSL',
|
||||
'stateOrProvinceName': u'Delaware'},
|
||||
'subject': {'commonName': u'somemachine.python.org',
|
||||
'countryName': u'US',
|
||||
'localityName': u'Wilmington',
|
||||
'organizationName': u'Python Software Foundation',
|
||||
'organizationalUnitName': u'SSL',
|
||||
'stateOrProvinceName': u'Delaware'},
|
||||
'notAfter': 'Sep 4 21:54:26 2007 GMT',
|
||||
'notBefore': 'Aug 25 21:54:26 2007 GMT',
|
||||
'version': 2}
|
||||
|
||||
This certificate is said to be *self-signed*, because the subject
|
||||
and issuer are the same entity. The *version* field refers the the X509 version
|
||||
that's used for the certificate.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
This example connects to an SSL server, prints the server's address and certificate,
|
||||
sends some bytes, and reads part of the response::
|
||||
|
||||
import socket, ssl, pprint
|
||||
|
||||
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||
ssl_sock = ssl.sslsocket(s, ca_certs="/etc/ca_certs_file", cert_reqs=ssl.CERT_REQUIRED)
|
||||
|
||||
ssl_sock.connect(('www.verisign.com', 443))
|
||||
|
||||
print repr(ssl_sock.getpeername())
|
||||
print pprint.pformat(ssl_sock.getpeercert())
|
||||
|
||||
# Set a simple HTTP request -- use httplib in actual code.
|
||||
ssl_sock.write("""GET / HTTP/1.0\r
|
||||
Host: www.verisign.com\r\n\r\n""")
|
||||
|
||||
# Read a chunk of data. Will not necessarily
|
||||
# read all the data returned by the server.
|
||||
data = ssl_sock.read()
|
||||
|
||||
# note that closing the sslsocket will also close the underlying socket
|
||||
ssl_sock.close()
|
||||
|
||||
As of August 25, 2007, the certificate printed by this program
|
||||
looked like this::
|
||||
|
||||
{'issuer': {'commonName': u'VeriSign Class 3 Extended Validation SSL SGC CA',
|
||||
'countryName': u'US',
|
||||
'organizationName': u'VeriSign, Inc.',
|
||||
'organizationalUnitName': u'Terms of use at https://www.verisign.com/rpa (c)06'},
|
||||
'subject': {'1.3.6.1.4.1.311.60.2.1.2': u'Delaware',
|
||||
'1.3.6.1.4.1.311.60.2.1.3': u'US',
|
||||
'commonName': u'www.verisign.com',
|
||||
'countryName': u'US',
|
||||
'localityName': u'Mountain View',
|
||||
'organizationName': u'VeriSign, Inc.',
|
||||
'organizationalUnitName': u'Terms of use at www.verisign.com/rpa (c)06',
|
||||
'postalCode': u'94043',
|
||||
'serialNumber': u'2497886',
|
||||
'stateOrProvinceName': u'California',
|
||||
'streetAddress': u'487 East Middlefield Road'},
|
||||
'notAfter': 'May 8 23:59:59 2009 GMT',
|
||||
'notBefore': 'May 9 00:00:00 2007 GMT',
|
||||
'version': 2}
|
||||
|
||||
For server operation, typically you'd need to have a server certificate, and private key, each in a file.
|
||||
You'd open a socket, bind it to a port, call :meth:`listen` on it, then start waiting for clients
|
||||
to connect::
|
||||
|
||||
import socket, ssl
|
||||
|
||||
bindsocket = socket.socket()
|
||||
bindsocket.bind(('myaddr.mydomain.com', 10023))
|
||||
bindsocket.listen(5)
|
||||
|
||||
When one did, you'd call :meth:`accept` on the socket to get the new socket from the other
|
||||
end, and use :func:`sslsocket` to create a server-side SSL context for it::
|
||||
|
||||
while True:
|
||||
newsocket, fromaddr = bindsocket.accept()
|
||||
connstream = ssl.sslsocket(newsocket, server_side=True, certfile="mycertfile",
|
||||
keyfile="mykeyfile", ssl_protocol=ssl.PROTOCOL_TLSv1)
|
||||
deal_with_client(connstream)
|
||||
|
||||
Then you'd read data from the `connstream` and do something with it till you are finished with the client (or the client is finished with you)::
|
||||
|
||||
def deal_with_client(connstream):
|
||||
|
||||
data = connstream.read()
|
||||
# null data means the client is finished with us
|
||||
while data:
|
||||
if not do_something(connstream, data):
|
||||
# we'll assume do_something returns False when we're finished with client
|
||||
break
|
||||
data = connstream.read()
|
||||
# finished with client
|
||||
connstream.close()
|
||||
|
||||
And go back to listening for new client connections.
|
||||
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ The :mod:`urllib2` module defines the following functions:
|
|||
:class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`,
|
||||
:class:`HTTPErrorProcessor`.
|
||||
|
||||
If the Python installation has SSL support (:func:`socket.ssl` exists),
|
||||
If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported),
|
||||
:class:`HTTPSHandler` will also be added.
|
||||
|
||||
Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its
|
||||
|
|
|
|||
Loading…
Reference in New Issue