[Python-checkins] r74832 - python/trunk/Doc/library/ssl.rst
georg.brandl
python-checkins at python.org
Wed Sep 16 17:57:46 CEST 2009
Author: georg.brandl
Date: Wed Sep 16 17:57:46 2009
New Revision: 74832
Log:
Rewrap long lines.
Modified:
python/trunk/Doc/library/ssl.rst
Modified: python/trunk/Doc/library/ssl.rst
==============================================================================
--- python/trunk/Doc/library/ssl.rst (original)
+++ python/trunk/Doc/library/ssl.rst Wed Sep 16 17:57:46 2009
@@ -1,6 +1,5 @@
-
:mod:`ssl` --- SSL wrapper for socket objects
-====================================================================
+=============================================
.. module:: ssl
:synopsis: SSL wrapper for socket objects
@@ -16,32 +15,29 @@
.. index:: TLS, SSL, Transport Layer Security, Secure Sockets Layer
-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.
+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. The installed version of OpenSSL may also cause
- variations in behavior.
-
-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 documents in the "See Also" section at
-the bottom.
-
-This module provides a class, :class:`ssl.SSLSocket`, which is
-derived from the :class:`socket.socket` type, and provides
-a socket-like wrapper that also encrypts and decrypts the data
-going over the socket with SSL. It 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, and
-a method, :meth:`cipher`, to retrieve the cipher being used for the
-secure connection.
+ Some behavior may be platform dependent, since calls are made to the
+ operating system socket APIs. The installed version of OpenSSL may also
+ cause variations in behavior.
+
+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 documents in the "See Also" section at the bottom.
+
+This module provides a class, :class:`ssl.SSLSocket`, which is derived from the
+:class:`socket.socket` type, and provides a socket-like wrapper that also
+encrypts and decrypts the data going over the socket with SSL. It 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, and a method, :meth:`cipher`, to retrieve the cipher being used for
+the secure connection.
Functions, Constants, and Exceptions
------------------------------------
@@ -49,31 +45,33 @@
.. 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. This error is a subtype of :exc:`socket.error`, which
- in turn is a subtype of :exc:`IOError`.
+ signifies some problem in the higher-level encryption and authentication
+ layer that's superimposed on the underlying network connection. This error
+ is a subtype of :exc:`socket.error`, which in turn is a subtype of
+ :exc:`IOError`.
.. 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)
- Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance of :class:`ssl.SSLSocket`, 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. For server-side sockets, if the socket has no remote peer, it is assumed
- to be a listening socket, and the server-side SSL wrapping is automatically performed
- on client connections accepted via the :meth:`accept` method. :func:`wrap_socket` may
- raise :exc:`SSLError`.
-
- The ``keyfile`` and ``certfile`` parameters specify optional files which contain a certificate
- to be used to identify the local side of the connection. See the discussion of :ref:`ssl-certificates`
- for more information on how the certificate is stored in the ``certfile``.
-
- 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.
- If the private key is stored in the ``certfile``, it should come before the first certificate
- in the certificate chain::
+ Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance
+ of :class:`ssl.SSLSocket`, 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. For server-side sockets, if the socket has no remote peer, it is
+ assumed to be a listening socket, and the server-side SSL wrapping is
+ automatically performed on client connections accepted via the :meth:`accept`
+ method. :func:`wrap_socket` may raise :exc:`SSLError`.
+
+ The ``keyfile`` and ``certfile`` parameters specify optional files which
+ contain a certificate to be used to identify the local side of the
+ connection. See the discussion of :ref:`ssl-certificates` for more
+ information on how the certificate is stored in the ``certfile``.
+
+ 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. If the private key
+ is stored in the ``certfile``, it should come before the first certificate in
+ the certificate chain::
-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
@@ -82,31 +80,33 @@
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----
- The parameter ``server_side`` is a boolean which identifies whether server-side or client-side
- behavior is desired from this socket.
+ 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 ``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.
- See the discussion of :ref:`ssl-certificates` for more information about how to arrange
- the certificates in this file.
-
- The parameter ``ssl_version`` specifies which version of the SSL protocol to use.
- Typically, the server chooses a particular protocol version, and the client
- must adapt to the server's choice. Most of the versions are not interoperable
- with the other versions. If not specified, for client-side operation, the
- default SSL version is SSLv3; for server-side operation, SSLv23. These
- version selections provide the most compatibility with other versions.
+ 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 ``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. See the discussion of
+ :ref:`ssl-certificates` for more information about how to arrange the
+ certificates in this file.
+
+ The parameter ``ssl_version`` specifies which version of the SSL protocol to
+ use. Typically, the server chooses a particular protocol version, and the
+ client must adapt to the server's choice. Most of the versions are not
+ interoperable with the other versions. If not specified, for client-side
+ operation, the default SSL version is SSLv3; for server-side operation,
+ SSLv23. These version selections provide the most compatibility with other
+ versions.
- Here's a table showing which versions in a client (down the side)
- can connect to which versions in a server (along the top):
+ Here's a table showing which versions in a client (down the side) can connect
+ to which versions in a server (along the top):
.. table::
@@ -119,51 +119,52 @@
*TLSv1* no no yes yes
======================== ========= ========= ========== =========
- In some older versions of OpenSSL (for instance, 0.9.7l on OS X 10.4),
- an SSLv2 client could not connect to an SSLv23 server.
+ In some older versions of OpenSSL (for instance, 0.9.7l on OS X 10.4), an
+ SSLv2 client could not connect to an SSLv23 server.
The parameter ``do_handshake_on_connect`` specifies whether to do the SSL
handshake automatically after doing a :meth:`socket.connect`, or whether the
- application program will call it explicitly, by invoking the :meth:`SSLSocket.do_handshake`
- method. Calling :meth:`SSLSocket.do_handshake` explicitly gives the program control over
- the blocking behavior of the socket I/O involved in the handshake.
-
- The parameter ``suppress_ragged_eofs`` specifies how the :meth:`SSLSocket.read`
- method should signal unexpected EOF from the other end of the connection. If specified
- as :const:`True` (the default), it returns a normal EOF in response to unexpected
- EOF errors raised from the underlying socket; if :const:`False`, it will raise
- the exceptions back to the caller.
+ application program will call it explicitly, by invoking the
+ :meth:`SSLSocket.do_handshake` method. Calling
+ :meth:`SSLSocket.do_handshake` explicitly gives the program control over the
+ blocking behavior of the socket I/O involved in the handshake.
+
+ The parameter ``suppress_ragged_eofs`` specifies how the
+ :meth:`SSLSocket.read` method should signal unexpected EOF from the other end
+ of the connection. If specified as :const:`True` (the default), it returns a
+ normal EOF in response to unexpected EOF errors raised from the underlying
+ socket; if :const:`False`, it will raise the exceptions back to the caller.
.. function:: RAND_status()
- Returns True if the SSL pseudo-random number generator has been
- seeded with 'enough' randomness, and False otherwise. You can use
- :func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness
- of the pseudo-random number generator.
+ Returns True if the SSL pseudo-random number generator has been seeded with
+ 'enough' randomness, and False otherwise. You can use :func:`ssl.RAND_egd`
+ and :func:`ssl.RAND_add` to increase the randomness of the pseudo-random
+ number generator.
.. function:: RAND_egd(path)
If you are running an entropy-gathering daemon (EGD) somewhere, and ``path``
- is the pathname of a socket connection open to it, this will read
- 256 bytes of randomness from the socket, and add it to the SSL pseudo-random number generator
- to increase the security of generated secret keys. This is typically only
- necessary on systems without better sources of randomness.
+ is the pathname of a socket connection open to it, this will read 256 bytes
+ of randomness from the socket, and add it to the SSL pseudo-random number
+ generator to increase the security of generated secret keys. This is
+ typically only necessary on systems without better sources of randomness.
- See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for
- sources of entropy-gathering daemons.
+ See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources
+ of entropy-gathering daemons.
.. function:: RAND_add(bytes, entropy)
- Mixes the given ``bytes`` into the SSL pseudo-random number generator.
- The parameter ``entropy`` (a float) is a lower bound on the entropy
- contained in string (so you can always use :const:`0.0`).
- See :rfc:`1750` for more information on sources of entropy.
+ Mixes the given ``bytes`` into the SSL pseudo-random number generator. The
+ parameter ``entropy`` (a float) is a lower bound on the entropy contained in
+ string (so you can always use :const:`0.0`). See :rfc:`1750` for more
+ information on sources of entropy.
.. 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.
+ 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::
@@ -177,14 +178,13 @@
.. function:: get_server_certificate (addr, ssl_version=PROTOCOL_SSLv3, ca_certs=None)
- Given the address ``addr`` of an SSL-protected server, as a
- (*hostname*, *port-number*) pair, fetches the server's certificate,
- and returns it as a PEM-encoded string. If ``ssl_version`` is
- specified, uses that version of the SSL protocol to attempt to
- connect to the server. If ``ca_certs`` is specified, it should be
- a file containing a list of root certificates, the same format as
- used for the same parameter in :func:`wrap_socket`. The call will
- attempt to validate the server certificate against that set of root
+ Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
+ *port-number*) pair, fetches the server's certificate, and returns it as a
+ PEM-encoded string. If ``ssl_version`` is specified, uses that version of
+ the SSL protocol to attempt to connect to the server. If ``ca_certs`` is
+ specified, it should be a file containing a list of root certificates, the
+ same format as used for the same parameter in :func:`wrap_socket`. The call
+ will attempt to validate the server certificate against that set of root
certificates, and will fail if the validation attempt fails.
.. function:: DER_cert_to_PEM_cert (DER_cert_bytes)
@@ -194,31 +194,29 @@
.. function:: PEM_cert_to_DER_cert (PEM_cert_string)
- Given a certificate as an ASCII PEM string, returns a DER-encoded
- sequence of bytes for that same certificate.
+ Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
+ bytes for that same certificate.
.. 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.
+ 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.
+ 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.
+ 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
@@ -226,22 +224,21 @@
.. data:: PROTOCOL_SSLv23
- Selects SSL version 2 or 3 as the channel encryption protocol.
- This is a setting to use with servers 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.
+ Selects SSL version 2 or 3 as the channel encryption protocol. This is a
+ setting to use with servers 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.
- For clients, this is the maximally compatible SSL variant.
+ Selects SSL version 3 as the channel encryption protocol. For clients, this
+ is the maximally compatible SSL variant.
.. data:: PROTOCOL_TLSv1
- Selects TLS version 1 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.
+ Selects TLS version 1 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.
SSLSocket Objects
@@ -253,30 +250,28 @@
.. 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.
+ 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(binary_form=False)
- If there is no certificate for the peer on the other end of the
- connection, returns ``None``.
+ If there is no certificate for the peer on the other end of the connection,
+ returns ``None``.
- If the parameter ``binary_form`` is :const:`False`, and a
- certificate was received from the peer, this method returns a
- :class:`dict` instance. If the certificate was not validated, the
- dict is empty. If the certificate was validated, it returns a dict
- with the keys ``subject`` (the principal for which the certificate
- was issued), and ``notAfter`` (the time after which the certificate
- should not be trusted). The certificate was already validated, so
- the ``notBefore`` and ``issuer`` fields are not returned. If a
- certificate contains an instance of the *Subject Alternative Name*
- extension (see :rfc:`3280`), there will also be a
- ``subjectAltName`` key in the dictionary.
+ If the parameter ``binary_form`` is :const:`False`, and a certificate was
+ received from the peer, this method returns a :class:`dict` instance. If the
+ certificate was not validated, the dict is empty. If the certificate was
+ validated, it returns a dict with the keys ``subject`` (the principal for
+ which the certificate was issued), and ``notAfter`` (the time after which the
+ certificate should not be trusted). The certificate was already validated,
+ so the ``notBefore`` and ``issuer`` fields are not returned. If a
+ certificate contains an instance of the *Subject Alternative Name* extension
+ (see :rfc:`3280`), there will also be a ``subjectAltName`` key in the
+ dictionary.
The "subject" field is a tuple containing the sequence of relative
- distinguished names (RDNs) given in the certificate's data
- structure for the principal, and each RDN is a sequence of
- name-value pairs::
+ distinguished names (RDNs) given in the certificate's data structure for the
+ principal, and each RDN is a sequence of name-value pairs::
{'notAfter': 'Feb 16 16:54:50 2013 GMT',
'subject': ((('countryName', u'US'),),
@@ -286,29 +281,27 @@
(('organizationalUnitName', u'SSL'),),
(('commonName', u'somemachine.python.org'),))}
- If the ``binary_form`` parameter is :const:`True`, and a
- certificate was provided, this method returns the DER-encoded form
- of the entire certificate as a sequence of bytes, or :const:`None` if the
- peer did not provide a certificate. This return
- value is independent of validation; if validation was required
- (:const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`), it will have
+ If the ``binary_form`` parameter is :const:`True`, and a certificate was
+ provided, this method returns the DER-encoded form of the entire certificate
+ as a sequence of bytes, or :const:`None` if the peer did not provide a
+ certificate. This return value is independent of validation; if validation
+ was required (:const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`), it will have
been validated, but if :const:`CERT_NONE` was used to establish the
connection, the certificate, if present, will not have been validated.
.. method:: SSLSocket.cipher()
- Returns a three-value tuple containing the name of the cipher being
- used, the version of the SSL protocol that defines its use, and the
- number of secret bits being used. If no connection has been
- established, returns ``None``.
+ Returns a three-value tuple containing the name of the cipher being used, the
+ version of the SSL protocol that defines its use, and the number of secret
+ bits being used. If no connection has been established, returns ``None``.
.. method:: SSLSocket.do_handshake()
- Perform a TLS/SSL handshake. If this is used with a non-blocking socket,
- it may raise :exc:`SSLError` with an ``arg[0]`` of :const:`SSL_ERROR_WANT_READ`
- or :const:`SSL_ERROR_WANT_WRITE`, in which case it must be called again until it
- completes successfully. For example, to simulate the behavior of a blocking socket,
- one might write::
+ Perform a TLS/SSL handshake. If this is used with a non-blocking socket, it
+ may raise :exc:`SSLError` with an ``arg[0]`` of :const:`SSL_ERROR_WANT_READ`
+ or :const:`SSL_ERROR_WANT_WRITE`, in which case it must be called again until
+ it completes successfully. For example, to simulate the behavior of a
+ blocking socket, one might write::
while True:
try:
@@ -324,13 +317,12 @@
.. method:: SSLSocket.unwrap()
- Performs the SSL shutdown handshake, which removes the TLS layer
- from the underlying socket, and returns the underlying socket
- object. This can be used to go from encrypted operation over a
- connection to unencrypted. The socket instance returned should always be
- used for further communication with the other side of the
- connection, rather than the original socket instance (which may
- not function properly after the unwrap).
+ Performs the SSL shutdown handshake, which removes the TLS layer from the
+ underlying socket, and returns the underlying socket object. This can be
+ used to go from encrypted operation over a connection to unencrypted. The
+ socket instance returned should always be used for further communication with
+ the other side of the connection, rather than the original socket instance
+ (which may not function properly after the unwrap).
.. index:: single: certificates
@@ -341,57 +333,54 @@
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".
-
-In the Python use of certificates, a client or server
-can use a certificate to prove who they are. The other
-side of a network connection can also be required to produce a certificate,
-and that certificate can be validated to the satisfaction
-of the client or server that requires such validation.
-The connection attempt can be set to raise an exception if
-the validation fails. Validation is done
-automatically, by the underlying OpenSSL framework; the
-application need not concern itself with its mechanics.
-But the application does usually need to provide
-sets of certificates to allow this process to take place.
-
-Python uses files to contain certificates. They should be formatted
-as "PEM" (see :rfc:`1422`), which is a base-64 encoded form wrapped
-with a header line and a footer line::
+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".
+
+In the Python use of certificates, a client or server can use a certificate to
+prove who they are. The other side of a network connection can also be required
+to produce a certificate, and that certificate can be validated to the
+satisfaction of the client or server that requires such validation. The
+connection attempt can be set to raise an exception if the validation fails.
+Validation is done automatically, by the underlying OpenSSL framework; the
+application need not concern itself with its mechanics. But the application
+does usually need to provide sets of certificates to allow this process to take
+place.
+
+Python uses files to contain certificates. They should be formatted as "PEM"
+(see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line
+and a footer line::
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----
-The Python files which contain certificates can contain a sequence
-of certificates, sometimes called a *certificate chain*. This chain
-should start with the specific certificate for the principal who "is"
-the client or server, and then the certificate for the issuer of that
-certificate, and then the certificate for the issuer of *that* certificate,
-and so on up the chain till you get to a certificate which is *self-signed*,
-that is, a certificate which has the same subject and issuer,
-sometimes called a *root certificate*. The certificates should just
-be concatenated together in the certificate file. For example, suppose
-we had a three certificate chain, from our server certificate to the
-certificate of the certification authority that signed our server certificate,
-to the root certificate of the agency which issued the certification authority's
-certificate::
+The Python files which contain certificates can contain a sequence of
+certificates, sometimes called a *certificate chain*. This chain should start
+with the specific certificate for the principal who "is" the client or server,
+and then the certificate for the issuer of that certificate, and then the
+certificate for the issuer of *that* certificate, and so on up the chain till
+you get to a certificate which is *self-signed*, that is, a certificate which
+has the same subject and issuer, sometimes called a *root certificate*. The
+certificates should just be concatenated together in the certificate file. For
+example, suppose we had a three certificate chain, from our server certificate
+to the certificate of the certification authority that signed our server
+certificate, to the root certificate of the agency which issued the
+certification authority's certificate::
-----BEGIN CERTIFICATE-----
... (certificate for your server)...
@@ -405,33 +394,30 @@
If you are going to require validation of the other side of the connection's
certificate, you need to provide a "CA certs" file, filled with the certificate
-chains for each issuer you are willing to trust. Again, this file just
-contains these chains concatenated together. For validation, Python will
-use the first chain it finds in the file which matches.
+chains for each issuer you are willing to trust. Again, this file just contains
+these chains concatenated together. For validation, Python will use the first
+chain it finds in the file which matches.
Some "standard" root certificates are available from various certification
-authorities:
-`CACert.org <http://www.cacert.org/index.php?id=3>`_,
-`Thawte <http://www.thawte.com/roots/>`_,
-`Verisign <http://www.verisign.com/support/roots.html>`_,
-`Positive SSL <http://www.PositiveSSL.com/ssl-certificate-support/cert_installation/UTN-USERFirst-Hardware.crt>`_ (used by python.org),
-`Equifax and GeoTrust <http://www.geotrust.com/resources/root_certificates/index.asp>`_.
-
-In general, if you are using
-SSL3 or TLS1, you don't need to put the full chain in your "CA certs" file;
-you only need the root certificates, and the remote peer is supposed to
-furnish the other certificates necessary to chain from its certificate to
-a root certificate.
-See :rfc:`4158` for more discussion of the way in which
-certification chains can be built.
-
-If you are going to create a server that provides SSL-encrypted
-connection services, you will need to acquire a certificate for that
-service. There are many ways of acquiring appropriate certificates,
-such as buying one from a certification authority. Another common
-practice is to generate a self-signed certificate. The simplest
-way to do this is with the OpenSSL package, using something like
-the following::
+authorities: `CACert.org <http://www.cacert.org/index.php?id=3>`_, `Thawte
+<http://www.thawte.com/roots/>`_, `Verisign
+<http://www.verisign.com/support/roots.html>`_, `Positive SSL
+<http://www.PositiveSSL.com/ssl-certificate-support/cert_installation/UTN-USERFirst-Hardware.crt>`_
+(used by python.org), `Equifax and GeoTrust
+<http://www.geotrust.com/resources/root_certificates/index.asp>`_.
+
+In general, if you are using SSL3 or TLS1, you don't need to put the full chain
+in your "CA certs" file; you only need the root certificates, and the remote
+peer is supposed to furnish the other certificates necessary to chain from its
+certificate to a root certificate. See :rfc:`4158` for more discussion of the
+way in which certification chains can be built.
+
+If you are going to create a server that provides SSL-encrypted connection
+services, you will need to acquire a certificate for that service. There are
+many ways of acquiring appropriate certificates, such as buying one from a
+certification authority. Another common practice is to generate a self-signed
+certificate. The simplest way to do this is with the OpenSSL package, using
+something like the following::
% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
@@ -455,9 +441,9 @@
Email Address []:ops at myserver.mygroup.myorganization.com
%
-The disadvantage of a self-signed certificate is that it is its
-own root certificate, and no one else will have it in their cache
-of known (and trusted) root certificates.
+The disadvantage of a self-signed certificate is that it is its own root
+certificate, and no one else will have it in their cache of known (and trusted)
+root certificates.
Examples
@@ -466,7 +452,8 @@
Testing for SSL support
^^^^^^^^^^^^^^^^^^^^^^^
-To test for the presence of SSL support in a Python installation, user code should use the following idiom::
+To test for the presence of SSL support in a Python installation, user code
+should use the following idiom::
try:
import ssl
@@ -478,8 +465,8 @@
Client-side operation
^^^^^^^^^^^^^^^^^^^^^
-This example connects to an SSL server, prints the server's address and certificate,
-sends some bytes, and reads part of the response::
+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
@@ -507,8 +494,8 @@
# note that closing the SSLSocket will also close the underlying socket
ssl_sock.close()
-As of September 6, 2007, the certificate printed by this program
-looked like this::
+As of September 6, 2007, the certificate printed by this program looked like
+this::
{'notAfter': 'May 8 23:59:59 2009 GMT',
'subject': ((('serialNumber', u'2497886'),),
@@ -531,9 +518,9 @@
Server-side operation
^^^^^^^^^^^^^^^^^^^^^
-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::
+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
@@ -541,8 +528,9 @@
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:`wrap_socket` to create a server-side SSL context for it::
+When one did, you'd call :meth:`accept` on the socket to get the new socket from
+the other end, and use :func:`wrap_socket` to create a server-side SSL context
+for it::
while True:
newsocket, fromaddr = bindsocket.accept()
@@ -553,7 +541,8 @@
ssl_version=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)::
+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):
More information about the Python-checkins
mailing list