Merge the trunk changes in. Breaks socket.ssl for now.

Merged revisions 57392-57619 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r57395 | georg.brandl | 2007-08-24 19:23:23 +0200 (Fri, 24 Aug 2007) | 2 lines

  Bug #1011: fix rfc822.Message.getheader docs.
........
  r57397 | georg.brandl | 2007-08-24 19:38:49 +0200 (Fri, 24 Aug 2007) | 2 lines

  Patch #1006: port test_winreg to unittest.
........
  r57398 | georg.brandl | 2007-08-24 19:46:54 +0200 (Fri, 24 Aug 2007) | 2 lines

  Fix #1012: wrong URL to :mod:`site` in install/index.rst.
........
  r57399 | georg.brandl | 2007-08-24 20:07:52 +0200 (Fri, 24 Aug 2007) | 2 lines

  Patch #1008: port test_signal to unittest.
........
  r57400 | georg.brandl | 2007-08-24 20:22:54 +0200 (Fri, 24 Aug 2007) | 2 lines

  Port test_frozen to unittest.
........
  r57401 | georg.brandl | 2007-08-24 20:27:43 +0200 (Fri, 24 Aug 2007) | 2 lines

  Document new utility functions in test_support.
........
  r57402 | georg.brandl | 2007-08-24 20:30:06 +0200 (Fri, 24 Aug 2007) | 2 lines

  Remove test_rgbimg output file, there is no test_rgbimg.py.
........
  r57403 | georg.brandl | 2007-08-24 20:35:27 +0200 (Fri, 24 Aug 2007) | 2 lines

  Remove output file for test_ossaudiodev, also properly close the dsp object.
........
  r57404 | georg.brandl | 2007-08-24 20:46:27 +0200 (Fri, 24 Aug 2007) | 2 lines

  Convert test_linuxaudiodev to unittest. Fix a wrong finally clause in test_ossaudiodev.
........
  r57406 | collin.winter | 2007-08-24 21:13:58 +0200 (Fri, 24 Aug 2007) | 1 line

  Convert test_pkg to use unittest.
........
  r57408 | georg.brandl | 2007-08-24 21:22:34 +0200 (Fri, 24 Aug 2007) | 2 lines

  Catch the correct errors.
........
  r57409 | georg.brandl | 2007-08-24 21:33:53 +0200 (Fri, 24 Aug 2007) | 2 lines

  Port test_class to unittest. Patch #1671298.
........
  r57415 | collin.winter | 2007-08-24 23:09:42 +0200 (Fri, 24 Aug 2007) | 1 line

  Make test_structmembers pass when run with regrtests's -R flag.
........
  r57455 | nick.coghlan | 2007-08-25 06:32:07 +0200 (Sat, 25 Aug 2007) | 1 line

  Revert misguided attempt at fixing incompatibility between -m and -i switches (better fix coming soon)
........
  r57456 | nick.coghlan | 2007-08-25 06:35:54 +0200 (Sat, 25 Aug 2007) | 1 line

  Revert compile.c changes that shouldn't have been included in previous checkin
........
  r57461 | nick.coghlan | 2007-08-25 12:50:41 +0200 (Sat, 25 Aug 2007) | 1 line

  Fix bug 1764407 - the -i switch now does the right thing when using the -m switch
........
  r57464 | guido.van.rossum | 2007-08-25 17:08:43 +0200 (Sat, 25 Aug 2007) | 4 lines

  Server-side SSL and certificate validation, by Bill Janssen.
  While cleaning up Bill's C style, I may have cleaned up some code
  he didn't touch as well (in _ssl.c).
........
  r57465 | neal.norwitz | 2007-08-25 18:41:36 +0200 (Sat, 25 Aug 2007) | 3 lines

  Try to get this to build with Visual Studio by moving all the variable
  declarations to the beginning of a scope.
........
  r57466 | neal.norwitz | 2007-08-25 18:54:38 +0200 (Sat, 25 Aug 2007) | 1 line

  Fix test so it is skipped properly if there is no SSL support.
........
  r57467 | neal.norwitz | 2007-08-25 18:58:09 +0200 (Sat, 25 Aug 2007) | 2 lines

  Fix a few more variables to try to get this to compile with Visual Studio.
........
  r57473 | neal.norwitz | 2007-08-25 19:25:17 +0200 (Sat, 25 Aug 2007) | 1 line

  Try to get this test to pass for systems that do not have SO_REUSEPORT
........
  r57482 | gregory.p.smith | 2007-08-26 02:26:00 +0200 (Sun, 26 Aug 2007) | 7 lines

  keep setup.py from listing unneeded hash modules (_md5, _sha*) as
  missing when they were not built because _hashlib with openssl provided
  their functionality instead.

  don't build bsddb185 if bsddb was built.
........
  r57483 | neal.norwitz | 2007-08-26 03:08:16 +0200 (Sun, 26 Aug 2007) | 1 line

  Fix typo in docstring (missing c in reacquire)
........
  r57484 | neal.norwitz | 2007-08-26 03:42:03 +0200 (Sun, 26 Aug 2007) | 2 lines

  Spell check (also americanify behaviour, it's almost 3 times as common)
........
  r57503 | neal.norwitz | 2007-08-26 08:29:57 +0200 (Sun, 26 Aug 2007) | 4 lines

  Reap children before the test starts so hopefully SocketServer
  won't find any old children left around which causes an exception
  in collect_children() and the test to fail.
........
  r57510 | neal.norwitz | 2007-08-26 20:50:39 +0200 (Sun, 26 Aug 2007) | 1 line

  Fail gracefully if the cert files cannot be created
........
  r57513 | guido.van.rossum | 2007-08-26 21:35:09 +0200 (Sun, 26 Aug 2007) | 4 lines

  Bill Janssen wrote:
  Here's a patch which makes test_ssl a better player in the buildbots
  environment.  I deep-ended on "try-except-else" clauses.
........
  r57518 | neal.norwitz | 2007-08-26 23:40:16 +0200 (Sun, 26 Aug 2007) | 1 line

  Get the test passing by commenting out some writes (should they be removed?)
........
  r57522 | neal.norwitz | 2007-08-27 00:16:23 +0200 (Mon, 27 Aug 2007) | 3 lines

  Catch IOError for when the device file doesn't exist or the user doesn't have
  permission to write to the device.
........
  r57524 | neal.norwitz | 2007-08-27 00:20:03 +0200 (Mon, 27 Aug 2007) | 5 lines

  Another patch from Bill Janssen that:
  1)  Fixes the bug that two class names are initial-lower-case.
  2)  Replaces the poll waiting for the server to become ready with
      a threading.Event signal.
........
  r57536 | neal.norwitz | 2007-08-27 02:58:33 +0200 (Mon, 27 Aug 2007) | 1 line

  Stop using string.join (from the module) to ease upgrade to py3k
........
  r57537 | neal.norwitz | 2007-08-27 03:03:18 +0200 (Mon, 27 Aug 2007) | 1 line

  Make a utility function for handling (printing) an error
........
  r57538 | neal.norwitz | 2007-08-27 03:15:33 +0200 (Mon, 27 Aug 2007) | 4 lines

  If we can't create a certificate, print a warning, but don't fail the test.
  Modified patch from what Bill Janssen sent on python-3000.
........
  r57539 | facundo.batista | 2007-08-27 03:15:34 +0200 (Mon, 27 Aug 2007) | 7 lines


  Ignore test failures caused by 'resource temporarily unavailable'
  exceptions raised in the test server thread, since SimpleXMLRPCServer
  does not gracefully handle them.  Changed number of requests handled
  by tests server thread to one (was 2) because no tests require more
  than one request. [GSoC - Alan McIntyre]
........
  r57561 | guido.van.rossum | 2007-08-27 19:19:42 +0200 (Mon, 27 Aug 2007) | 8 lines

  > Regardless, building a fixed test certificate and checking it in sounds like
  > the better option.  Then the openssl command in the test code can be turned
  > into a comment describing how the test data was pregenerated.

  Here's a patch that does that.

  Bill
........
  r57568 | guido.van.rossum | 2007-08-27 20:42:23 +0200 (Mon, 27 Aug 2007) | 26 lines

  > Some of the code sets the error string in this directly before
  > returning NULL, and other pieces of the code call PySSL_SetError,
  > which creates the error string.  I think some of the places which set
  > the string directly probably shouldn't; instead, they should call
  > PySSL_SetError to cons up the error name directly from the err code.
  > However, PySSL_SetError only works after the construction of an ssl
  > object, which means it can't be used there...  I'll take a longer look
  > at it and see if there's a reasonable fix.

  Here's a patch which addresses this.  It also fixes the indentation in
  PySSL_SetError, bringing it into line with PEP 7, fixes a compile warning
  about one of the OpenSSL macros, and makes the namespace a bit more
  consistent.  I've tested it on FC 7 and OS X 10.4.

  % ./python ./Lib/test/regrtest.py -R :1: -u all test_ssl
  test_ssl
  beginning 6 repetitions
  123456
  ......
  1 test OK.
  [29244 refs]
  %

  [GvR: slightly edited to enforce 79-char line length, even if it required
   violating the style guide.]
........
  r57570 | guido.van.rossum | 2007-08-27 21:11:11 +0200 (Mon, 27 Aug 2007) | 2 lines

  Patch 10124 by Bill Janssen, docs for the new ssl code.
........
  r57574 | guido.van.rossum | 2007-08-27 22:51:00 +0200 (Mon, 27 Aug 2007) | 3 lines

  Patch # 1739906 by Christian Heimes -- add reduce to functools (importing
  it from __builtin__).
........
  r57575 | guido.van.rossum | 2007-08-27 22:52:10 +0200 (Mon, 27 Aug 2007) | 2 lines

  News about functools.reduce.
........
  r57611 | georg.brandl | 2007-08-28 10:29:08 +0200 (Tue, 28 Aug 2007) | 2 lines

  Document rev. 57574.
........
  r57612 | sean.reifschneider | 2007-08-28 11:07:54 +0200 (Tue, 28 Aug 2007) | 2 lines

  Adding basic imputil documentation.
........
  r57614 | georg.brandl | 2007-08-28 12:48:18 +0200 (Tue, 28 Aug 2007) | 2 lines

  Fix some glitches.
........
  r57616 | lars.gustaebel | 2007-08-28 14:31:09 +0200 (Tue, 28 Aug 2007) | 5 lines

  TarFile.__init__() no longer fails if no name argument is passed and
  the fileobj argument has no usable name attribute (e.g. StringIO).

  (will backport to 2.5)
........
  r57619 | thomas.wouters | 2007-08-28 17:28:19 +0200 (Tue, 28 Aug 2007) | 22 lines


  Improve extended slicing support in builtin types and classes. Specifically:

   - Specialcase extended slices that amount to a shallow copy the same way as
     is done for simple slices, in the tuple, string and unicode case.

   - Specialcase step-1 extended slices to optimize the common case for all
     involved types.

   - For lists, allow extended slice assignment of differing lengths as long
     as the step is 1. (Previously, 'l[:2:1] = []' failed even though
     'l[:2] = []' and 'l[:2:None] = []' do not.)

   - Implement extended slicing for buffer, array, structseq, mmap and
     UserString.UserString.

   - Implement slice-object support (but not non-step-1 slice assignment) for
     UserString.MutableString.

   - Add tests for all new functionality.
........

1 files changed, 319 insertions, 0 deletions

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
new file mode 100644
index 0000000..8ac7e26
--- /dev/null
+++ b/Doc/library/ssl.rst
@@ -0,0 +1,319 @@
+
+:mod:`ssl` --- SSL wrapper for socket objects, and utility functions
+====================================================================
+
+.. module:: ssl
+   :synopsis: SSL wrapper for socket objects, and utility functions
+
+.. versionadded:: 2.6
+
+
+This module provides access to Transport Layer Security (often known
+as "Secure Sockets Layer") encryption and peer authentication
+facilities for network sockets, both client-side and server-side.
+This module uses the OpenSSL library. It is available on all modern
+Unix systems, Windows, Mac OS X, and probably additional
+platforms, as long as OpenSSL is installed on that platform.
+
+.. note::
+
+   Some behavior may be platform dependent, since calls are made to the operating
+   system socket APIs.
+
+This section documents the objects and functions in the `ssl` module;
+for more general information about TLS, SSL, and certificates, the
+reader is referred to the paper, *Introducing SSL and Certificates using OpenSSL*, by Frederick J. Hirsch, at
+http://old.pseudonym.org/ssl/wwwj-index.html.
+
+This module defines a class, :class:`ssl.sslsocket`, which is
+derived from the :class:`socket.socket` type, and supports additional
+:meth:`read` and :meth:`write` methods, along with a method, :meth:`getpeercert`,
+to retrieve the certificate of the other side of the connection.
+
+This module defines the following functions, exceptions, and constants:
+
+.. function:: cert_time_to_seconds(timestring)
+
+   Returns a floating-point value containing a normal seconds-after-the-epoch time
+   value, given the time-string representing the "notBefore" or "notAfter" date
+   from a certificate.
+
+   Here's an example::
+
+     >>> import ssl
+     >>> ssl.cert_time_to_seconds("May  9 00:00:00 2007 GMT")
+     1178694000.0
+     >>> import time
+     >>> time.ctime(ssl.cert_time_to_seconds("May  9 00:00:00 2007 GMT"))
+     'Wed May  9 00:00:00 2007'
+     >>> 
+
+.. exception:: sslerror
+
+   Raised to signal an error from the underlying SSL implementation.  This 
+   signifies some problem in the higher-level
+   encryption and authentication layer that's superimposed on the underlying
+   network connection.
+
+.. data:: CERT_NONE
+
+   Value to pass to the `cert_reqs` parameter to :func:`sslobject`
+   when no certificates will be required or validated from the other
+   side of the socket connection.
+
+.. data:: CERT_OPTIONAL
+
+   Value to pass to the `cert_reqs` parameter to :func:`sslobject`
+   when no certificates will be required from the other side of the
+   socket connection, but if they are provided, will be validated.
+   Note that use of this setting requires a valid certificate
+   validation file also be passed as a value of the `ca_certs`
+   parameter.
+
+.. data:: CERT_REQUIRED
+
+   Value to pass to the `cert_reqs` parameter to :func:`sslobject`
+   when certificates will be required from the other side of the
+   socket connection.  Note that use of this setting requires a valid certificate
+   validation file also be passed as a value of the `ca_certs`
+   parameter.
+
+.. data:: PROTOCOL_SSLv2
+
+   Selects SSL version 2 as the channel encryption protocol.
+
+.. data:: PROTOCOL_SSLv23
+
+   Selects SSL version 2 or 3 as the channel encryption protocol.  This is a setting to use for maximum compatibility
+   with the other end of an SSL connection, but it may cause the specific ciphers chosen for the encryption to be
+   of fairly low quality.
+
+.. data:: PROTOCOL_SSLv3
+
+   Selects SSL version 3 as the channel encryption protocol.
+
+.. data:: PROTOCOL_TLSv1
+
+   Selects SSL version 2 as the channel encryption protocol.  This is
+   the most modern version, and probably the best choice for maximum
+   protection, if both sides can speak it.
+
+
+Certificates
+------------
+
+Certificates in general are part of a public-key / private-key system.  In this system, each `principal`,
+(which may be a machine, or a person, or an organization) is assigned a unique two-part encryption key.
+One part of the key is public, and is called the *public key*; the other part is kept secret, and is called
+the *private key*.  The two parts are related, in that if you encrypt a message with one of the parts, you can
+decrypt it with the other part, and **only** with the other part.
+
+A certificate contains information about two principals.  It contains
+the name of a *subject*, and the subject's public key.  It also
+contains a statement by a second principal, the *issuer*, that the
+subject is who he claims to be, and that this is indeed the subject's
+public key.  The issuer's statement is signed with the issuer's
+private key, which only the issuer knows.  However, anyone can verify
+the issuer's statement by finding the issuer's public key, decrypting
+the statement with it, and comparing it to the other information in
+the certificate.  The certificate also contains information about the
+time period over which it is valid.  This is expressed as two fields,
+called "notBefore" and "notAfter".
+
+The underlying system which is used in the Python SSL support is
+called "OpenSSL".  It contains facilities for constructing and
+validating certificates.  In the Python use of certificates, the other
+side of a network connection can be required to produce a certificate,
+and that certificate can be validated against a file filled with
+self-signed *root* certificates (so-called because the issuer is the
+same as the subject), and and "CA" (certification authority)
+certificates assured by those root certificates (and by other CA
+certificates).  Either side of a connection, client or server, can
+request certificates and validation, and the connection can be optionally
+set up to fail if a valid certificate is not presented by the other side.
+
+
+sslsocket Objects
+-----------------
+
+.. class:: sslsocket(sock [, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_SSLv23, ca_certs=None])
+
+   Takes an instance *sock* of :class:`socket.socket`, and returns an instance of a subtype
+   of :class:`socket.socket` which wraps the underlying socket in an SSL context.
+   For client-side sockets, the context construction is lazy; if the underlying socket isn't
+   connected yet, the context construction will be performed after :meth:`connect` is called
+   on the socket.
+
+   The `keyfile` and `certfile` parameters specify optional files which contain a certificate
+   to be used to identify the local side of the connection.  Often the private key is stored
+   in the same file as the certificate; in this case, only the `certfile` parameter need be
+   passed.  If the private key is stored in a separate file, both parameters must be used.
+
+   The parameter `server_side` is a boolean which identifies whether server-side or client-side
+   behavior is desired from this socket.
+
+   The parameter `cert_reqs` specifies whether a certificate is
+   required from the other side of the connection, and whether it will
+   be validated if provided.  It must be one of the three values
+   :const:`CERT_NONE` (certificates ignored), :const:`CERT_OPTIONAL` (not required,
+   but validated if provided), or :const:`CERT_REQUIRED` (required and
+   validated).  If the value of this parameter is not :const:`CERT_NONE`, then
+   the `ca_certs` parameter must point to a file of CA certificates.
+
+   The parameter `ssl_version` specifies which version of the SSL protocol to use.  Typically,
+   the server specifies this, and a client connecting to it must use the same protocol.  An
+   SSL server using :const:`PROTOCOL_SSLv23` can understand a client connecting via SSL2, SSL3, or TLS1,
+   but a client using :const:`PROTOCOL_SSLv23` can only connect to an SSL2 server.
+
+   The `ca_certs` file contains a set of concatenated "certification authority" certificates,
+   which are used to validate certificates passed from the other end of the connection.
+   This file
+   contains the certificates in PEM format (IETF RFC 1422) where each certificate is
+   encoded in base64 encoding and surrounded with a header and footer::
+
+      -----BEGIN CERTIFICATE-----
+      ... (CA certificate in base64 encoding) ...
+      -----END CERTIFICATE-----
+
+   The various certificates in the file are just concatenated together::
+
+      -----BEGIN CERTIFICATE-----
+      ... (CA certificate in base64 encoding) ...
+      -----END CERTIFICATE-----
+      -----BEGIN CERTIFICATE-----
+      ... (a second CA certificate in base64 encoding) ...
+      -----END CERTIFICATE-----
+      -----BEGIN CERTIFICATE-----
+      ... (a root certificate in base64 encoding) ...
+      -----END CERTIFICATE-----
+
+   Some "standard" root certificates are available at
+   http://www.thawte.com/roots/  (for Thawte roots) and
+   http://www.verisign.com/support/roots.html  (for Verisign roots).
+
+.. method:: sslsocket.read([nbytes])
+
+   Reads up to `nbytes` bytes from the SSL-encrypted channel and returns them.
+
+.. method:: sslsocket.write(data)
+
+   Writes the `data` to the other side of the connection, using the SSL channel to encrypt.  Returns the number
+   of bytes written.
+
+.. method:: sslsocket.getpeercert()
+
+   If there is no certificate for the peer on the other end of the connection, returns `None`.
+   If a certificate was received from the peer, but not validated, returns an empty `dict` instance.
+   If a certificate was received and validated, returns a `dict` instance with the fields
+   `subject` (the principal for which the certificate was issued), `issuer` (the signer of
+   the certificate), `notBefore` (the time before which the certificate should not be trusted),
+   and `notAfter` (the time after which the certificate should not be trusted) filled in.
+
+   The "subject" and "issuer" fields are themselves dictionaries containing the fields given
+   in the certificate's data structure for each principal::
+
+      {'issuer': {'commonName': u'somemachine.python.org',
+                  'countryName': u'US',
+                  'localityName': u'Wilmington',
+                  'organizationName': u'Python Software Foundation',
+                  'organizationalUnitName': u'SSL',
+                  'stateOrProvinceName': u'Delaware'},
+       'subject': {'commonName': u'somemachine.python.org',
+                   'countryName': u'US',
+                   'localityName': u'Wilmington',
+                   'organizationName': u'Python Software Foundation',
+                   'organizationalUnitName': u'SSL',
+                   'stateOrProvinceName': u'Delaware'},
+       'notAfter': 'Sep  4 21:54:26 2007 GMT',
+       'notBefore': 'Aug 25 21:54:26 2007 GMT',
+       'version': 2}
+
+   This certificate is said to be *self-signed*, because the subject
+   and issuer are the same entity.  The *version* field refers the the X509 version
+   that's used for the certificate.
+
+Examples
+--------
+
+This example connects to an SSL server, prints the server's address and certificate,
+sends some bytes, and reads part of the response::
+
+   import socket, ssl, pprint
+
+   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+   ssl_sock = ssl.sslsocket(s, ca_certs="/etc/ca_certs_file", cert_reqs=ssl.CERT_REQUIRED)
+
+   ssl_sock.connect(('www.verisign.com', 443))
+
+   print repr(ssl_sock.getpeername())
+   print pprint.pformat(ssl_sock.getpeercert())
+
+   # Set a simple HTTP request -- use httplib in actual code.
+   ssl_sock.write("""GET / HTTP/1.0\r
+   Host: www.verisign.com\r\n\r\n""")
+
+   # Read a chunk of data.  Will not necessarily
+   # read all the data returned by the server.
+   data = ssl_sock.read()
+
+   # note that closing the sslsocket will also close the underlying socket
+   ssl_sock.close()
+
+As of August 25, 2007, the certificate printed by this program
+looked like this::
+
+   {'issuer': {'commonName': u'VeriSign Class 3 Extended Validation SSL SGC CA',
+               'countryName': u'US',
+               'organizationName': u'VeriSign, Inc.',
+               'organizationalUnitName': u'Terms of use at https://www.verisign.com/rpa (c)06'},
+    'subject': {'1.3.6.1.4.1.311.60.2.1.2': u'Delaware',
+                '1.3.6.1.4.1.311.60.2.1.3': u'US',
+                'commonName': u'www.verisign.com',
+                'countryName': u'US',
+                'localityName': u'Mountain View',
+                'organizationName': u'VeriSign, Inc.',
+                'organizationalUnitName': u'Terms of use at www.verisign.com/rpa (c)06',
+                'postalCode': u'94043',
+                'serialNumber': u'2497886',
+                'stateOrProvinceName': u'California',
+                'streetAddress': u'487 East Middlefield Road'},
+    'notAfter': 'May  8 23:59:59 2009 GMT',
+    'notBefore': 'May  9 00:00:00 2007 GMT',
+    'version': 2}
+
+For server operation, typically you'd need to have a server certificate, and private key, each in a file.
+You'd open a socket, bind it to a port, call :meth:`listen` on it, then start waiting for clients
+to connect::
+
+   import socket, ssl
+
+   bindsocket = socket.socket()
+   bindsocket.bind(('myaddr.mydomain.com', 10023))
+   bindsocket.listen(5)
+
+When one did, you'd call :meth:`accept` on the socket to get the new socket from the other
+end, and use :func:`sslsocket` to create a server-side SSL context for it::
+
+   while True:
+      newsocket, fromaddr = bindsocket.accept()
+      connstream = ssl.sslsocket(newsocket, server_side=True, certfile="mycertfile",
+                                 keyfile="mykeyfile", ssl_protocol=ssl.PROTOCOL_TLSv1)
+      deal_with_client(connstream)
+
+Then you'd read data from the `connstream` and do something with it till you are finished with the client (or the client is finished with you)::
+
+   def deal_with_client(connstream):
+
+      data = connstream.read()
+      # null data means the client is finished with us
+      while data:
+         if not do_something(connstream, data):
+            # we'll assume do_something returns False when we're finished with client
+            break
+         data = connstream.read()
+      # finished with client
+      connstream.close()
+
+And go back to listening for new client connections.
+
+