Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Rewrap long lines.

This commit is contained in:
Georg Brandl 2009-09-16 15:57:46 +00:00
parent 2e85f503b1
commit a50d20a5b1
1 changed files with 234 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

479
Doc/library/ssl.rst
View File

@ -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 <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>`_.
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.
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):