From a50d20a5b1d73f32641d976aa6d066516d642d12 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 16 Sep 2009 15:57:46 +0000 Subject: [PATCH] Rewrap long lines. --- Doc/library/ssl.rst | 479 ++++++++++++++++++++++---------------------- 1 file changed, 234 insertions(+), 245 deletions(-) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 1804fcf34f6..a4f911f5f54 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -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. + 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 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. +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 @@ Functions, Constants, and Exceptions .. 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`. + 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``. + 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:: + 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 @@ Functions, Constants, and Exceptions ... (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 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 ``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 ``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 @@ Functions, Constants, and Exceptions *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. + 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. + 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 @@ Functions, Constants, and Exceptions .. 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 @@ Functions, Constants, and Exceptions .. 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 @@ Functions, Constants, and Exceptions .. 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 @@ SSLSocket Objects .. 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 @@ SSLSocket Objects (('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 @@ SSLSocket Objects .. 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 @@ SSLSocket Objects 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. +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". +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. +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:: +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 @@ certificate:: 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 `_, -`Thawte `_, -`Verisign `_, -`Positive SSL `_ (used by python.org), -`Equifax and GeoTrust `_. +authorities: `CACert.org `_, `Thawte +`_, `Verisign +`_, `Positive SSL +`_ +(used by python.org), `Equifax and GeoTrust +`_. -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. +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:: +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 @@ the following:: Email Address []:ops@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 @@ Examples 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 @@ To test for the presence of SSL support in a Python installation, user code shou 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 @@ sends some bytes, and reads part of the response:: # 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 @@ which is a fairly poorly-formed ``subject`` field. 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 @@ to connect:: 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 @@ end, and use :func:`wrap_socket` to create a server-side SSL context for it:: 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):