Mercurial > cpython-lru_cache-weakref

annotate Doc/library/ssl.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 44954e6a1353
children f1391442bd0b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
1
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
2 :mod:`ssl` --- SSL wrapper for socket objects
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
3 ====================================================================
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
4
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
5 .. module:: ssl
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
6 :synopsis: SSL wrapper for socket objects
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
7
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
8 .. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
9
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
10 .. versionadded:: 2.6
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
11
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
12 .. sectionauthor:: Bill Janssen <bill.janssen@gmail.com>
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
13
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
14
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
15 .. index:: single: OpenSSL; (use in module ssl)
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
16
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
17 .. index:: TLS, SSL, Transport Layer Security, Secure Sockets Layer
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
18
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
19 This module provides access to Transport Layer Security (often known
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
20 as "Secure Sockets Layer") encryption and peer authentication
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
21 facilities for network sockets, both client-side and server-side.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
22 This module uses the OpenSSL library. It is available on all modern
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
23 Unix systems, Windows, Mac OS X, and probably additional
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
24 platforms, as long as OpenSSL is installed on that platform.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
25
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
26 .. note::
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
27
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
28 Some behavior may be platform dependent, since calls are made to the operating
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
29 system socket APIs. The installed version of OpenSSL may also cause
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
30 variations in behavior.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
31
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
32 This section documents the objects and functions in the ``ssl`` module;
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
33 for more general information about TLS, SSL, and certificates, the
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
34 reader is referred to the documents in the "See Also" section at
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
35 the bottom.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
36
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
37 This module provides a class, :class:`ssl.SSLSocket`, which is
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
38 derived from the :class:`socket.socket` type, and provides
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
39 a socket-like wrapper that also encrypts and decrypts the data
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
40 going over the socket with SSL. It supports additional
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
41 :meth:`read` and :meth:`write` methods, along with a method, :meth:`getpeercert`,
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
42 to retrieve the certificate of the other side of the connection, and
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
43 a method, :meth:`cipher`, to retrieve the cipher being used for the
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
44 secure connection.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
45
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
46 Functions, Constants, and Exceptions
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
47 ------------------------------------
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
48
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
49 .. exception:: SSLError
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
50
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49089
diff changeset
51 Raised to signal an error from the underlying SSL implementation. This
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
52 signifies some problem in the higher-level
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
53 encryption and authentication layer that's superimposed on the underlying
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
54 network connection. This error is a subtype of :exc:`socket.error`, which
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
55 in turn is a subtype of :exc:`IOError`.
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
56
47848
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
57 .. function:: wrap_socket (sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version={see docs}, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True)
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
58
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
59 Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance of :class:`ssl.SSLSocket`, a subtype
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
60 of :class:`socket.socket`, which wraps the underlying socket in an SSL context.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
61 For client-side sockets, the context construction is lazy; if the underlying socket isn't
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
62 connected yet, the context construction will be performed after :meth:`connect` is called
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
63 on the socket. For server-side sockets, if the socket has no remote peer, it is assumed
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
64 to be a listening socket, and the server-side SSL wrapping is automatically performed
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
65 on client connections accepted via the :meth:`accept` method. :func:`wrap_socket` may
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
66 raise :exc:`SSLError`.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
67
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
68 The ``keyfile`` and ``certfile`` parameters specify optional files which contain a certificate
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
69 to be used to identify the local side of the connection. See the discussion of :ref:`ssl-certificates`
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
70 for more information on how the certificate is stored in the ``certfile``.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
71
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
72 Often the private key is stored
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
73 in the same file as the certificate; in this case, only the ``certfile`` parameter need be
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
74 passed. If the private key is stored in a separate file, both parameters must be used.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
75 If the private key is stored in the ``certfile``, it should come before the first certificate
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
76 in the certificate chain::
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
77
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
78 -----BEGIN RSA PRIVATE KEY-----
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
79 ... (private key in base64 encoding) ...
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
80 -----END RSA PRIVATE KEY-----
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
81 -----BEGIN CERTIFICATE-----
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
82 ... (certificate in base64 PEM encoding) ...
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
83 -----END CERTIFICATE-----
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
84
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
85 The parameter ``server_side`` is a boolean which identifies whether server-side or client-side
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
86 behavior is desired from this socket.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
87
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
88 The parameter ``cert_reqs`` specifies whether a certificate is
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
89 required from the other side of the connection, and whether it will
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
90 be validated if provided. It must be one of the three values
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
91 :const:`CERT_NONE` (certificates ignored), :const:`CERT_OPTIONAL` (not required,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
92 but validated if provided), or :const:`CERT_REQUIRED` (required and
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
93 validated). If the value of this parameter is not :const:`CERT_NONE`, then
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
94 the ``ca_certs`` parameter must point to a file of CA certificates.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
95
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
96 The ``ca_certs`` file contains a set of concatenated "certification authority" certificates,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
97 which are used to validate certificates passed from the other end of the connection.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
98 See the discussion of :ref:`ssl-certificates` for more information about how to arrange
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
99 the certificates in this file.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
100
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
101 The parameter ``ssl_version`` specifies which version of the SSL protocol to use.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
102 Typically, the server chooses a particular protocol version, and the client
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
103 must adapt to the server's choice. Most of the versions are not interoperable
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
104 with the other versions. If not specified, for client-side operation, the
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
105 default SSL version is SSLv3; for server-side operation, SSLv23. These
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
106 version selections provide the most compatibility with other versions.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
107
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
108 Here's a table showing which versions in a client (down the side)
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
109 can connect to which versions in a server (along the top):
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
110
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
111 .. table::
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
112
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
113 ======================== ========= ========= ========== =========
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
114 *client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1**
44195
9ad4aedf349b Diverse markup fixes.
Georg Brandl <georg@python.org>
parents: 43619
diff changeset
115 ------------------------ --------- --------- ---------- ---------
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
116 *SSLv2* yes no yes* no
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
117 *SSLv3* yes yes yes no
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
118 *SSLv23* yes no yes no
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
119 *TLSv1* no no yes yes
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
120 ======================== ========= ========= ========== =========
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
121
44195
9ad4aedf349b Diverse markup fixes.
Georg Brandl <georg@python.org>
parents: 43619
diff changeset
122 In some older versions of OpenSSL (for instance, 0.9.7l on OS X 10.4),
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
123 an SSLv2 client could not connect to an SSLv23 server.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
124
47848
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
125 The parameter ``do_handshake_on_connect`` specifies whether to do the SSL
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
126 handshake automatically after doing a :meth:`socket.connect`, or whether the
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
127 application program will call it explicitly, by invoking the :meth:`SSLSocket.do_handshake`
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
128 method. Calling :meth:`SSLSocket.do_handshake` explicitly gives the program control over
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
129 the blocking behavior of the socket I/O involved in the handshake.
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
130
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
131 The parameter ``suppress_ragged_eofs`` specifies how the :meth:`SSLSocket.read`
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
132 method should signal unexpected EOF from the other end of the connection. If specified
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
133 as :const:`True` (the default), it returns a normal EOF in response to unexpected
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
134 EOF errors raised from the underlying socket; if :const:`False`, it will raise
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
135 the exceptions back to the caller.
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
136
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
137 .. function:: RAND_status()
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
138
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
139 Returns True if the SSL pseudo-random number generator has been
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
140 seeded with 'enough' randomness, and False otherwise. You can use
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
141 :func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
142 of the pseudo-random number generator.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
143
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
144 .. function:: RAND_egd(path)
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
145
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
146 If you are running an entropy-gathering daemon (EGD) somewhere, and ``path``
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
147 is the pathname of a socket connection open to it, this will read
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
148 256 bytes of randomness from the socket, and add it to the SSL pseudo-random number generator
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
149 to increase the security of generated secret keys. This is typically only
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
150 necessary on systems without better sources of randomness.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
151
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
152 See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
153 sources of entropy-gathering daemons.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
154
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
155 .. function:: RAND_add(bytes, entropy)
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
156
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
157 Mixes the given ``bytes`` into the SSL pseudo-random number generator.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
158 The parameter ``entropy`` (a float) is a lower bound on the entropy
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
159 contained in string (so you can always use :const:`0.0`).
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
160 See :rfc:`1750` for more information on sources of entropy.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
161
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
162 .. function:: cert_time_to_seconds(timestring)
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
163
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
164 Returns a floating-point value containing a normal seconds-after-the-epoch time
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
165 value, given the time-string representing the "notBefore" or "notAfter" date
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
166 from a certificate.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
167
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
168 Here's an example::
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
169
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
170 >>> import ssl
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
171 >>> ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT")
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
172 1178694000.0
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
173 >>> import time
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
174 >>> time.ctime(ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT"))
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
175 'Wed May 9 00:00:00 2007'
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49089
diff changeset
176 >>>
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
177
43375
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
178 .. function:: get_server_certificate (addr, ssl_version=PROTOCOL_SSLv3, ca_certs=None)
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
179
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
180 Given the address ``addr`` of an SSL-protected server, as a
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
181 (*hostname*, *port-number*) pair, fetches the server's certificate,
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
182 and returns it as a PEM-encoded string. If ``ssl_version`` is
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
183 specified, uses that version of the SSL protocol to attempt to
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
184 connect to the server. If ``ca_certs`` is specified, it should be
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
185 a file containing a list of root certificates, the same format as
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
186 used for the same parameter in :func:`wrap_socket`. The call will
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
187 attempt to validate the server certificate against that set of root
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
188 certificates, and will fail if the validation attempt fails.
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
189
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
190 .. function:: DER_cert_to_PEM_cert (DER_cert_bytes)
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
191
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
192 Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
193 string version of the same certificate.
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
194
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
195 .. function:: PEM_cert_to_DER_cert (PEM_cert_string)
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
196
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
197 Given a certificate as an ASCII PEM string, returns a DER-encoded
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
198 sequence of bytes for that same certificate.
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
199
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
200 .. data:: CERT_NONE
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
201
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
202 Value to pass to the ``cert_reqs`` parameter to :func:`sslobject`
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
203 when no certificates will be required or validated from the other
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
204 side of the socket connection.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
205
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
206 .. data:: CERT_OPTIONAL
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
207
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
208 Value to pass to the ``cert_reqs`` parameter to :func:`sslobject`
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
209 when no certificates will be required from the other side of the
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
210 socket connection, but if they are provided, will be validated.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
211 Note that use of this setting requires a valid certificate
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
212 validation file also be passed as a value of the ``ca_certs``
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
213 parameter.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
214
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
215 .. data:: CERT_REQUIRED
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
216
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
217 Value to pass to the ``cert_reqs`` parameter to :func:`sslobject`
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
218 when certificates will be required from the other side of the
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
219 socket connection. Note that use of this setting requires a valid certificate
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
220 validation file also be passed as a value of the ``ca_certs``
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
221 parameter.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
222
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
223 .. data:: PROTOCOL_SSLv2
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
224
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
225 Selects SSL version 2 as the channel encryption protocol.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
226
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
227 .. data:: PROTOCOL_SSLv23
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
228
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
229 Selects SSL version 2 or 3 as the channel encryption protocol.
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
230 This is a setting to use with servers for maximum compatibility
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
231 with the other end of an SSL connection, but it may cause the
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
232 specific ciphers chosen for the encryption to be of fairly low
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
233 quality.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
234
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
235 .. data:: PROTOCOL_SSLv3
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
236
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
237 Selects SSL version 3 as the channel encryption protocol.
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
238 For clients, this is the maximally compatible SSL variant.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
239
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
240 .. data:: PROTOCOL_TLSv1
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
241
43619
5e42117f9cbc Fix protocol name
Andrew M. Kuchling <amk@amk.ca>
parents: 43375
diff changeset
242 Selects TLS version 1 as the channel encryption protocol. This is
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
243 the most modern version, and probably the best choice for maximum
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
244 protection, if both sides can speak it.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
245
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
246
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
247 SSLSocket Objects
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
248 -----------------
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
249
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
250 .. method:: SSLSocket.read([nbytes=1024])
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
251
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
252 Reads up to ``nbytes`` bytes from the SSL-encrypted channel and returns them.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
253
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
254 .. method:: SSLSocket.write(data)
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
255
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
256 Writes the ``data`` to the other side of the connection, using the
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
257 SSL channel to encrypt. Returns the number of bytes written.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
258
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
259 .. method:: SSLSocket.getpeercert(binary_form=False)
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
260
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
261 If there is no certificate for the peer on the other end of the
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
262 connection, returns ``None``.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
263
52777
44954e6a1353 Fix 'the the' duplication
Andrew M. Kuchling <amk@amk.ca>
parents: 51745
diff changeset
264 If the parameter ``binary_form`` is :const:`False`, and a
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
265 certificate was received from the peer, this method returns a
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
266 :class:`dict` instance. If the certificate was not validated, the
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
267 dict is empty. If the certificate was validated, it returns a dict
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
268 with the keys ``subject`` (the principal for which the certificate
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
269 was issued), and ``notAfter`` (the time after which the certificate
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
270 should not be trusted). The certificate was already validated, so
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
271 the ``notBefore`` and ``issuer`` fields are not returned. If a
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
272 certificate contains an instance of the *Subject Alternative Name*
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
273 extension (see :rfc:`3280`), there will also be a
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
274 ``subjectAltName`` key in the dictionary.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
275
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
276 The "subject" field is a tuple containing the sequence of relative
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
277 distinguished names (RDNs) given in the certificate's data
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
278 structure for the principal, and each RDN is a sequence of
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
279 name-value pairs::
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
280
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
281 {'notAfter': 'Feb 16 16:54:50 2013 GMT',
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
282 'subject': ((('countryName', u'US'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
283 (('stateOrProvinceName', u'Delaware'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
284 (('localityName', u'Wilmington'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
285 (('organizationName', u'Python Software Foundation'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
286 (('organizationalUnitName', u'SSL'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
287 (('commonName', u'somemachine.python.org'),))}
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
288
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
289 If the ``binary_form`` parameter is :const:`True`, and a
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
290 certificate was provided, this method returns the DER-encoded form
43375
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
291 of the entire certificate as a sequence of bytes, or :const:`None` if the
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
292 peer did not provide a certificate. This return
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
293 value is independent of validation; if validation was required
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
294 (:const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`), it will have
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
295 been validated, but if :const:`CERT_NONE` was used to establish the
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
296 connection, the certificate, if present, will not have been validated.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
297
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
298 .. method:: SSLSocket.cipher()
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
299
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
300 Returns a three-value tuple containing the name of the cipher being
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
301 used, the version of the SSL protocol that defines its use, and the
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
302 number of secret bits being used. If no connection has been
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
303 established, returns ``None``.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
304
47848
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
305 .. method:: SSLSocket.do_handshake()
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
306
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
307 Perform a TLS/SSL handshake. If this is used with a non-blocking socket,
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
308 it may raise :exc:`SSLError` with an ``arg[0]`` of :const:`SSL_ERROR_WANT_READ`
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
309 or :const:`SSL_ERROR_WANT_WRITE`, in which case it must be called again until it
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
310 completes successfully. For example, to simulate the behavior of a blocking socket,
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
311 one might write::
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
312
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
313 while True:
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
314 try:
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
315 s.do_handshake()
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
316 break
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
317 except ssl.SSLError, err:
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
318 if err.args[0] == ssl.SSL_ERROR_WANT_READ:
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
319 select.select([s], [], [])
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
320 elif err.args[0] == ssl.SSL_ERROR_WANT_WRITE:
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
321 select.select([], [s], [])
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
322 else:
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
323 raise
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
324
48223
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
325 .. method:: SSLSocket.unwrap()
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
326
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
327 Performs the SSL shutdown handshake, which removes the TLS layer
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
328 from the underlying socket, and returns the underlying socket
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
329 object. This can be used to go from encrypted operation over a
49089
37b70cd4a0f0 incorporate fixes from issue 3162; SSL doc patch
Bill Janssen <janssen@parc.com>
parents: 48223
diff changeset
330 connection to unencrypted. The socket instance returned should always be
48223
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
331 used for further communication with the other side of the
49089
37b70cd4a0f0 incorporate fixes from issue 3162; SSL doc patch
Bill Janssen <janssen@parc.com>
parents: 48223
diff changeset
332 connection, rather than the original socket instance (which may
37b70cd4a0f0 incorporate fixes from issue 3162; SSL doc patch
Bill Janssen <janssen@parc.com>
parents: 48223
diff changeset
333 not function properly after the unwrap).
48223
f0472533bfc9 update ssl documentation
Bill Janssen <janssen@parc.com>
parents: 47848
diff changeset
334
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
335 .. index:: single: certificates
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
336
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
337 .. index:: single: X509 certificate
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
338
43330
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
339 .. _ssl-certificates:
ebdf2c09c189 Fix some documentation bugs.
Bill Janssen <janssen@parc.com>
parents: 43325
diff changeset
340
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
341 Certificates
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
342 ------------
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
343
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
344 Certificates in general are part of a public-key / private-key system. In this system, each *principal*,
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
345 (which may be a machine, or a person, or an organization) is assigned a unique two-part encryption key.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
346 One part of the key is public, and is called the *public key*; the other part is kept secret, and is called
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
347 the *private key*. The two parts are related, in that if you encrypt a message with one of the parts, you can
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
348 decrypt it with the other part, and **only** with the other part.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
349
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
350 A certificate contains information about two principals. It contains
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
351 the name of a *subject*, and the subject's public key. It also
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
352 contains a statement by a second principal, the *issuer*, that the
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
353 subject is who he claims to be, and that this is indeed the subject's
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
354 public key. The issuer's statement is signed with the issuer's
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
355 private key, which only the issuer knows. However, anyone can verify
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
356 the issuer's statement by finding the issuer's public key, decrypting
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
357 the statement with it, and comparing it to the other information in
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
358 the certificate. The certificate also contains information about the
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
359 time period over which it is valid. This is expressed as two fields,
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
360 called "notBefore" and "notAfter".
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
361
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
362 In the Python use of certificates, a client or server
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
363 can use a certificate to prove who they are. The other
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
364 side of a network connection can also be required to produce a certificate,
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
365 and that certificate can be validated to the satisfaction
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
366 of the client or server that requires such validation.
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
367 The connection attempt can be set to raise an exception if
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
368 the validation fails. Validation is done
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
369 automatically, by the underlying OpenSSL framework; the
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
370 application need not concern itself with its mechanics.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
371 But the application does usually need to provide
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
372 sets of certificates to allow this process to take place.
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
373
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
374 Python uses files to contain certificates. They should be formatted
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
375 as "PEM" (see :rfc:`1422`), which is a base-64 encoded form wrapped
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
376 with a header line and a footer line::
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
377
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
378 -----BEGIN CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
379 ... (certificate in base64 PEM encoding) ...
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
380 -----END CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
381
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
382 The Python files which contain certificates can contain a sequence
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
383 of certificates, sometimes called a *certificate chain*. This chain
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
384 should start with the specific certificate for the principal who "is"
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
385 the client or server, and then the certificate for the issuer of that
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
386 certificate, and then the certificate for the issuer of *that* certificate,
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
387 and so on up the chain till you get to a certificate which is *self-signed*,
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49089
diff changeset
388 that is, a certificate which has the same subject and issuer,
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
389 sometimes called a *root certificate*. The certificates should just
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
390 be concatenated together in the certificate file. For example, suppose
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
391 we had a three certificate chain, from our server certificate to the
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
392 certificate of the certification authority that signed our server certificate,
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
393 to the root certificate of the agency which issued the certification authority's
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
394 certificate::
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
395
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
396 -----BEGIN CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
397 ... (certificate for your server)...
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
398 -----END CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
399 -----BEGIN CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
400 ... (the certificate for the CA)...
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
401 -----END CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
402 -----BEGIN CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
403 ... (the root certificate for the CA's issuer)...
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
404 -----END CERTIFICATE-----
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
405
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
406 If you are going to require validation of the other side of the connection's
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
407 certificate, you need to provide a "CA certs" file, filled with the certificate
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
408 chains for each issuer you are willing to trust. Again, this file just
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
409 contains these chains concatenated together. For validation, Python will
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
410 use the first chain it finds in the file which matches.
47848
8a281bfc058d various SSL fixes; issues 1251, 3162, 3212
Bill Janssen <janssen@parc.com>
parents: 46467
diff changeset
411
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
412 Some "standard" root certificates are available from various certification
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
413 authorities:
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
414 `CACert.org <http://www.cacert.org/index.php?id=3>`_,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
415 `Thawte <http://www.thawte.com/roots/>`_,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
416 `Verisign <http://www.verisign.com/support/roots.html>`_,
43375
9041965a92f2 Add support for asyncore server-side SSL support. This requires
Bill Janssen <janssen@parc.com>
parents: 43330
diff changeset
417 `Positive SSL <http://www.PositiveSSL.com/ssl-certificate-support/cert_installation/UTN-USERFirst-Hardware.crt>`_ (used by python.org),
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
418 `Equifax and GeoTrust <http://www.geotrust.com/resources/root_certificates/index.asp>`_.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
419
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
420 In general, if you are using
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
421 SSL3 or TLS1, you don't need to put the full chain in your "CA certs" file;
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
422 you only need the root certificates, and the remote peer is supposed to
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
423 furnish the other certificates necessary to chain from its certificate to
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
424 a root certificate.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49089
diff changeset
425 See :rfc:`4158` for more discussion of the way in which
43243
e2b4fc960830 SSL certificate distinguished names should be represented by tuples
Bill Janssen <janssen@parc.com>
parents: 43095
diff changeset
426 certification chains can be built.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
427
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
428 If you are going to create a server that provides SSL-encrypted
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
429 connection services, you will need to acquire a certificate for that
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
430 service. There are many ways of acquiring appropriate certificates,
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49089
diff changeset
431 such as buying one from a certification authority. Another common
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
432 practice is to generate a self-signed certificate. The simplest
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
433 way to do this is with the OpenSSL package, using something like
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
434 the following::
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
435
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
436 % openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
437 Generating a 1024 bit RSA private key
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
438 .......++++++
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
439 .............................++++++
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
440 writing new private key to 'cert.pem'
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
441 -----
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
442 You are about to be asked to enter information that will be incorporated
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
443 into your certificate request.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
444 What you are about to enter is what is called a Distinguished Name or a DN.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
445 There are quite a few fields but you can leave some blank
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
446 For some fields there will be a default value,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
447 If you enter '.', the field will be left blank.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
448 -----
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
449 Country Name (2 letter code) [AU]:US
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
450 State or Province Name (full name) [Some-State]:MyState
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
451 Locality Name (eg, city) []:Some City
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
452 Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
453 Organizational Unit Name (eg, section) []:My Group
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
454 Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
455 Email Address []:ops@myserver.mygroup.myorganization.com
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
456 %
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
457
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
458 The disadvantage of a self-signed certificate is that it is its
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
459 own root certificate, and no one else will have it in their cache
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
460 of known (and trusted) root certificates.
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
461
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
462
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
463 Examples
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
464 --------
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
465
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
466 Testing for SSL support
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
467 ^^^^^^^^^^^^^^^^^^^^^^^
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
468
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
469 To test for the presence of SSL support in a Python installation, user code should use the following idiom::
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
470
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
471 try:
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
472 import ssl
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
473 except ImportError:
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
474 pass
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
475 else:
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
476 [ do something that requires SSL support ]
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
477
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
478 Client-side operation
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
479 ^^^^^^^^^^^^^^^^^^^^^
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
480
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
481 This example connects to an SSL server, prints the server's address and certificate,
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
482 sends some bytes, and reads part of the response::
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
483
51745
9815da43a1ce revert r69777 since all the experts agree that extra import lines distract from the code
Benjamin Peterson <benjamin@python.org>
parents: 51742
diff changeset
484 import socket, ssl, pprint
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
485
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
486 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
487
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
488 # require a certificate from the server
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
489 ssl_sock = ssl.wrap_socket(s,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
490 ca_certs="/etc/ca_certs_file",
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
491 cert_reqs=ssl.CERT_REQUIRED)
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
492
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
493 ssl_sock.connect(('www.verisign.com', 443))
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
494
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
495 print repr(ssl_sock.getpeername())
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
496 print ssl_sock.cipher()
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
497 print pprint.pformat(ssl_sock.getpeercert())
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
498
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
499 # Set a simple HTTP request -- use httplib in actual code.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
500 ssl_sock.write("""GET / HTTP/1.0\r
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
501 Host: www.verisign.com\r\n\r\n""")
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
502
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
503 # Read a chunk of data. Will not necessarily
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
504 # read all the data returned by the server.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
505 data = ssl_sock.read()
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
506
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
507 # note that closing the SSLSocket will also close the underlying socket
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
508 ssl_sock.close()
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
509
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
510 As of September 6, 2007, the certificate printed by this program
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
511 looked like this::
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
512
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
513 {'notAfter': 'May 8 23:59:59 2009 GMT',
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
514 'subject': ((('serialNumber', u'2497886'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
515 (('1.3.6.1.4.1.311.60.2.1.3', u'US'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
516 (('1.3.6.1.4.1.311.60.2.1.2', u'Delaware'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
517 (('countryName', u'US'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
518 (('postalCode', u'94043'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
519 (('stateOrProvinceName', u'California'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
520 (('localityName', u'Mountain View'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
521 (('streetAddress', u'487 East Middlefield Road'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
522 (('organizationName', u'VeriSign, Inc.'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
523 (('organizationalUnitName',
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
524 u'Production Security Services'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
525 (('organizationalUnitName',
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
526 u'Terms of use at www.verisign.com/rpa (c)06'),),
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
527 (('commonName', u'www.verisign.com'),))}
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
528
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
529 which is a fairly poorly-formed ``subject`` field.
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
530
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
531 Server-side operation
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
532 ^^^^^^^^^^^^^^^^^^^^^
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
533
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
534 For server operation, typically you'd need to have a server certificate, and private key, each in a file.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
535 You'd open a socket, bind it to a port, call :meth:`listen` on it, then start waiting for clients
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
536 to connect::
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
537
51745
9815da43a1ce revert r69777 since all the experts agree that extra import lines distract from the code
Benjamin Peterson <benjamin@python.org>
parents: 51742
diff changeset
538 import socket, ssl
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
539
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
540 bindsocket = socket.socket()
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
541 bindsocket.bind(('myaddr.mydomain.com', 10023))
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
542 bindsocket.listen(5)
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
543
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
544 When one did, you'd call :meth:`accept` on the socket to get the new socket from the other
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
545 end, and use :func:`wrap_socket` to create a server-side SSL context for it::
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
546
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
547 while True:
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
548 newsocket, fromaddr = bindsocket.accept()
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
549 connstream = ssl.wrap_socket(newsocket,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
550 server_side=True,
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
551 certfile="mycertfile",
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
552 keyfile="mykeyfile",
46467
1fef26f89bce Use correct parameter name
Andrew M. Kuchling <amk@amk.ca>
parents: 44195
diff changeset
553 ssl_version=ssl.PROTOCOL_TLSv1)
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
554 deal_with_client(connstream)
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
555
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
556 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)::
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
557
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
558 def deal_with_client(connstream):
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
559
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
560 data = connstream.read()
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
561 # null data means the client is finished with us
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
562 while data:
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
563 if not do_something(connstream, data):
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
564 # we'll assume do_something returns False
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
565 # when we're finished with client
42954
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
566 break
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
567 data = connstream.read()
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
568 # finished with client
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
569 connstream.close()
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
570
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
571 And go back to listening for new client connections.
27f0289b6835 Merge the trunk changes in. Breaks socket.ssl for now.
Thomas Wouters <thomas@python.org>
parents:
diff changeset
572
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 49089
diff changeset
573
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
574 .. seealso::
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
575
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
576 Class :class:`socket.socket`
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
577 Documentation of underlying :mod:`socket` class
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
578
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
579 `Introducing SSL and Certificates using OpenSSL <http://old.pseudonym.org/ssl/wwwj-index.html>`_
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
580 Frederick J. Hirsch
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
581
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
582 `RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management <http://www.ietf.org/rfc/rfc1422>`_
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
583 Steve Kent
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
584
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
585 `RFC 1750: Randomness Recommendations for Security <http://www.ietf.org/rfc/rfc1750>`_
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
586 D. Eastlake et. al.
43095
4a07a288f5c4 Merged revisions 57620-57771 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 42954
diff changeset
587
43325
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
588 `RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile <http://www.ietf.org/rfc/rfc3280>`_
193020bf52dc More work on SSL support.
Bill Janssen <janssen@parc.com>
parents: 43243
diff changeset
589 Housley et. al.