1
:mod:`ssl` --- TLS/SSL wrapper for socket objects
2
=================================================
5
:synopsis: TLS/SSL wrapper for socket objects
7
.. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
8
.. sectionauthor:: Bill Janssen <bill.janssen@gmail.com>
11
.. index:: single: OpenSSL; (use in module ssl)
13
.. index:: TLS, SSL, Transport Layer Security, Secure Sockets Layer
15
**Source code:** :source:`Lib/ssl.py`
19
This module provides access to Transport Layer Security (often known as "Secure
20
Sockets Layer") encryption and peer authentication facilities for network
21
sockets, both client-side and server-side. This module uses the OpenSSL
22
library. It is available on all modern Unix systems, Windows, Mac OS X, and
23
probably additional platforms, as long as OpenSSL is installed on that platform.
27
Some behavior may be platform dependent, since calls are made to the
28
operating system socket APIs. The installed version of OpenSSL may also
29
cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with
30
openssl version 1.0.1.
33
Don't use this module without reading the :ref:`ssl-security`. Doing so
34
may lead to a false sense of security, as the default settings of the
35
ssl module are not necessarily appropriate for your application.
38
This section documents the objects and functions in the ``ssl`` module; for more
39
general information about TLS, SSL, and certificates, the reader is referred to
40
the documents in the "See Also" section at the bottom.
42
This module provides a class, :class:`ssl.SSLSocket`, which is derived from the
43
:class:`socket.socket` type, and provides a socket-like wrapper that also
44
encrypts and decrypts the data going over the socket with SSL. It supports
45
additional methods such as :meth:`getpeercert`, which retrieves the
46
certificate of the other side of the connection, and :meth:`cipher`,which
47
retrieves the cipher being used for the secure connection.
49
For more sophisticated applications, the :class:`ssl.SSLContext` class
50
helps manage settings and certificates, which can then be inherited
51
by SSL sockets created through the :meth:`SSLContext.wrap_socket` method.
54
Functions, Constants, and Exceptions
55
------------------------------------
57
.. exception:: SSLError
59
Raised to signal an error from the underlying SSL implementation
60
(currently provided by the OpenSSL library). This signifies some
61
problem in the higher-level encryption and authentication layer that's
62
superimposed on the underlying network connection. This error
63
is a subtype of :exc:`OSError`. The error code and message of
64
:exc:`SSLError` instances are provided by the OpenSSL library.
66
.. versionchanged:: 3.3
67
:exc:`SSLError` used to be a subtype of :exc:`socket.error`.
69
.. attribute:: library
71
A string mnemonic designating the OpenSSL submodule in which the error
72
occurred, such as ``SSL``, ``PEM`` or ``X509``. The range of possible
73
values depends on the OpenSSL version.
79
A string mnemonic designating the reason this error occurred, for
80
example ``CERTIFICATE_VERIFY_FAILED``. The range of possible
81
values depends on the OpenSSL version.
85
.. exception:: SSLZeroReturnError
87
A subclass of :exc:`SSLError` raised when trying to read or write and
88
the SSL connection has been closed cleanly. Note that this doesn't
89
mean that the underlying transport (read TCP) has been closed.
93
.. exception:: SSLWantReadError
95
A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
96
<ssl-nonblocking>` when trying to read or write data, but more data needs
97
to be received on the underlying TCP transport before the request can be
100
.. versionadded:: 3.3
102
.. exception:: SSLWantWriteError
104
A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
105
<ssl-nonblocking>` when trying to read or write data, but more data needs
106
to be sent on the underlying TCP transport before the request can be
109
.. versionadded:: 3.3
111
.. exception:: SSLSyscallError
113
A subclass of :exc:`SSLError` raised when a system error was encountered
114
while trying to fulfill an operation on a SSL socket. Unfortunately,
115
there is no easy way to inspect the original errno number.
117
.. versionadded:: 3.3
119
.. exception:: SSLEOFError
121
A subclass of :exc:`SSLError` raised when the SSL connection has been
122
terminated abruptly. Generally, you shouldn't try to reuse the underlying
123
transport when this error is encountered.
125
.. versionadded:: 3.3
127
.. exception:: CertificateError
129
Raised to signal an error with a certificate (such as mismatching
130
hostname). Certificate errors detected by OpenSSL, though, raise
137
The following function allows for standalone socket creation. Starting from
138
Python 3.2, it can be more flexible to use :meth:`SSLContext.wrap_socket`
141
.. 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, ciphers=None)
143
Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance
144
of :class:`ssl.SSLSocket`, a subtype of :class:`socket.socket`, which wraps
145
the underlying socket in an SSL context. ``sock`` must be a
146
:data:`~socket.SOCK_STREAM` socket; other socket types are unsupported.
148
For client-side sockets, the context construction is lazy; if the
149
underlying socket isn't connected yet, the context construction will be
150
performed after :meth:`connect` is called on the socket. For
151
server-side sockets, if the socket has no remote peer, it is assumed
152
to be a listening socket, and the server-side SSL wrapping is
153
automatically performed on client connections accepted via the
154
:meth:`accept` method. :func:`wrap_socket` may raise :exc:`SSLError`.
156
The ``keyfile`` and ``certfile`` parameters specify optional files which
157
contain a certificate to be used to identify the local side of the
158
connection. See the discussion of :ref:`ssl-certificates` for more
159
information on how the certificate is stored in the ``certfile``.
161
The parameter ``server_side`` is a boolean which identifies whether
162
server-side or client-side behavior is desired from this socket.
164
The parameter ``cert_reqs`` specifies whether a certificate is required from
165
the other side of the connection, and whether it will be validated if
166
provided. It must be one of the three values :const:`CERT_NONE`
167
(certificates ignored), :const:`CERT_OPTIONAL` (not required, but validated
168
if provided), or :const:`CERT_REQUIRED` (required and validated). If the
169
value of this parameter is not :const:`CERT_NONE`, then the ``ca_certs``
170
parameter must point to a file of CA certificates.
172
The ``ca_certs`` file contains a set of concatenated "certification
173
authority" certificates, which are used to validate certificates passed from
174
the other end of the connection. See the discussion of
175
:ref:`ssl-certificates` for more information about how to arrange the
176
certificates in this file.
178
The parameter ``ssl_version`` specifies which version of the SSL protocol to
179
use. Typically, the server chooses a particular protocol version, and the
180
client must adapt to the server's choice. Most of the versions are not
181
interoperable with the other versions. If not specified, the default is
182
:data:`PROTOCOL_SSLv23`; it provides the most compatibility with other
185
Here's a table showing which versions in a client (down the side) can connect
186
to which versions in a server (along the top):
190
======================== ========= ========= ========== ========= =========== ===========
191
*client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1** **TLSv1.1** **TLSv1.2**
192
------------------------ --------- --------- ---------- --------- ----------- -----------
193
*SSLv2* yes no yes no no no
194
*SSLv3* no yes yes no no no
195
*SSLv23* no yes yes yes yes yes
196
*TLSv1* no no yes yes no no
197
*TLSv1.1* no no yes no yes no
198
*TLSv1.2* no no yes no no yes
199
======================== ========= ========= ========== ========= =========== ===========
203
Which connections succeed will vary depending on the version of
204
OpenSSL. For example, before OpenSSL 1.0.0, an SSLv23 client
205
would always attempt SSLv2 connections.
207
The *ciphers* parameter sets the available ciphers for this SSL object.
208
It should be a string in the `OpenSSL cipher list format
209
<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>`_.
211
The parameter ``do_handshake_on_connect`` specifies whether to do the SSL
212
handshake automatically after doing a :meth:`socket.connect`, or whether the
213
application program will call it explicitly, by invoking the
214
:meth:`SSLSocket.do_handshake` method. Calling
215
:meth:`SSLSocket.do_handshake` explicitly gives the program control over the
216
blocking behavior of the socket I/O involved in the handshake.
218
The parameter ``suppress_ragged_eofs`` specifies how the
219
:meth:`SSLSocket.recv` method should signal unexpected EOF from the other end
220
of the connection. If specified as :const:`True` (the default), it returns a
221
normal EOF (an empty bytes object) in response to unexpected EOF errors
222
raised from the underlying socket; if :const:`False`, it will raise the
223
exceptions back to the caller.
225
.. versionchanged:: 3.2
226
New optional argument *ciphers*.
232
A convenience function helps create :class:`SSLContext` objects for common
235
.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
237
Return a new :class:`SSLContext` object with default settings for
238
the given *purpose*. The settings are chosen by the :mod:`ssl` module,
239
and usually represent a higher security level than when calling the
240
:class:`SSLContext` constructor directly.
242
*cafile*, *capath*, *cadata* represent optional CA certificates to
243
trust for certificate verification, as in
244
:meth:`SSLContext.load_verify_locations`. If all three are
245
:const:`None`, this function can choose to trust the system's default
246
CA certificates instead.
248
The settings are: :data:`PROTOCOL_SSLv23`, :data:`OP_NO_SSLv2`, and
249
:data:`OP_NO_SSLv3` with high encryption cipher suites without RC4 and
250
without unauthenticated cipher suites. Passing :data:`~Purpose.SERVER_AUTH`
251
as *purpose* sets :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED`
252
and either loads CA certificates (when at least one of *cafile*, *capath* or
253
*cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load
254
default CA certificates.
257
The protocol, options, cipher and other settings may change to more
258
restrictive values anytime without prior deprecation. The values
259
represent a fair balance between compatibility and security.
261
If your application needs specific settings, you should create a
262
:class:`SSLContext` and apply the settings yourself.
265
If you find that when certain older clients or servers attempt to connect
266
with a :class:`SSLContext` created by this function that they get an error
267
stating "Protocol or cipher suite mismatch", it may be that they only
268
support SSL3.0 which this function excludes using the
269
:data:`OP_NO_SSLv3`. SSL3.0 is widely considered to be `completely broken
270
<https://en.wikipedia.org/wiki/POODLE>`_. If you still wish to continue to
271
use this function but still allow SSL 3.0 connections you can re-enable
274
ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
275
ctx.options &= ~ssl.OP_NO_SSLv3
277
.. versionadded:: 3.4
279
.. versionchanged:: 3.4.4
281
RC4 was dropped from the default cipher string.
287
.. function:: RAND_bytes(num)
289
Return *num* cryptographically strong pseudo-random bytes. Raises an
290
:class:`SSLError` if the PRNG has not been seeded with enough data or if the
291
operation is not supported by the current RAND method. :func:`RAND_status`
292
can be used to check the status of the PRNG and :func:`RAND_add` can be used
295
For almost all applications :func:`os.urandom` is preferable.
297
Read the Wikipedia article, `Cryptographically secure pseudorandom number
299
<http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator>`_,
300
to get the requirements of a cryptographically generator.
302
.. versionadded:: 3.3
304
.. function:: RAND_pseudo_bytes(num)
306
Return (bytes, is_cryptographic): bytes are *num* pseudo-random bytes,
307
is_cryptographic is ``True`` if the bytes generated are cryptographically
308
strong. Raises an :class:`SSLError` if the operation is not supported by the
311
Generated pseudo-random byte sequences will be unique if they are of
312
sufficient length, but are not necessarily unpredictable. They can be used
313
for non-cryptographic purposes and for certain purposes in cryptographic
314
protocols, but usually not for key generation etc.
316
For almost all applications :func:`os.urandom` is preferable.
318
.. versionadded:: 3.3
320
.. function:: RAND_status()
322
Return ``True`` if the SSL pseudo-random number generator has been seeded
323
with 'enough' randomness, and ``False`` otherwise. You can use
324
:func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness of
325
the pseudo-random number generator.
327
.. function:: RAND_egd(path)
329
If you are running an entropy-gathering daemon (EGD) somewhere, and *path*
330
is the pathname of a socket connection open to it, this will read 256 bytes
331
of randomness from the socket, and add it to the SSL pseudo-random number
332
generator to increase the security of generated secret keys. This is
333
typically only necessary on systems without better sources of randomness.
335
See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources
336
of entropy-gathering daemons.
338
Availability: not available with LibreSSL.
340
.. function:: RAND_add(bytes, entropy)
342
Mix the given *bytes* into the SSL pseudo-random number generator. The
343
parameter *entropy* (a float) is a lower bound on the entropy contained in
344
string (so you can always use :const:`0.0`). See :rfc:`1750` for more
345
information on sources of entropy.
347
.. versionchanged: 3.5
348
Writable :term:`bytes-like object` is now accepted.
353
.. function:: match_hostname(cert, hostname)
355
Verify that *cert* (in decoded format as returned by
356
:meth:`SSLSocket.getpeercert`) matches the given *hostname*. The rules
357
applied are those for checking the identity of HTTPS servers as outlined
358
in :rfc:`2818` and :rfc:`6125`. In addition to HTTPS, this function
359
should be suitable for checking the identity of servers in various
360
SSL-based protocols such as FTPS, IMAPS, POPS and others.
362
:exc:`CertificateError` is raised on failure. On success, the function
365
>>> cert = {'subject': ((('commonName', 'example.com'),),)}
366
>>> ssl.match_hostname(cert, "example.com")
367
>>> ssl.match_hostname(cert, "example.org")
368
Traceback (most recent call last):
369
File "<stdin>", line 1, in <module>
370
File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
371
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'
373
.. versionadded:: 3.2
375
.. versionchanged:: 3.3.3
376
The function now follows :rfc:`6125`, section 6.4.3 and does neither
377
match multiple wildcards (e.g. ``*.*.com`` or ``*a*.example.org``) nor
378
a wildcard inside an internationalized domain names (IDN) fragment.
379
IDN A-labels such as ``www*.xn--pthon-kva.org`` are still supported,
380
but ``x*.python.org`` no longer matches ``xn--tda.python.org``.
382
.. versionchanged:: 3.5
383
Matching of IP addresses, when present in the subjectAltName field
384
of the certificate, is now supported.
386
.. function:: cert_time_to_seconds(cert_time)
388
Return the time in seconds since the Epoch, given the ``cert_time``
389
string representing the "notBefore" or "notAfter" date from a
390
certificate in ``"%b %d %H:%M:%S %Y %Z"`` strptime format (C
395
.. doctest:: newcontext
398
>>> timestamp = ssl.cert_time_to_seconds("Jan 5 09:34:43 2018 GMT")
401
>>> from datetime import datetime
402
>>> print(datetime.utcfromtimestamp(timestamp))
405
"notBefore" or "notAfter" dates must use GMT (:rfc:`5280`).
407
.. versionchanged:: 3.5
408
Interpret the input time as a time in UTC as specified by 'GMT'
409
timezone in the input string. Local timezone was used
410
previously. Return an integer (no fractions of a second in the
413
.. function:: get_server_certificate(addr, ssl_version=PROTOCOL_SSLv23, ca_certs=None)
415
Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
416
*port-number*) pair, fetches the server's certificate, and returns it as a
417
PEM-encoded string. If ``ssl_version`` is specified, uses that version of
418
the SSL protocol to attempt to connect to the server. If ``ca_certs`` is
419
specified, it should be a file containing a list of root certificates, the
420
same format as used for the same parameter in :func:`wrap_socket`. The call
421
will attempt to validate the server certificate against that set of root
422
certificates, and will fail if the validation attempt fails.
424
.. versionchanged:: 3.3
425
This function is now IPv6-compatible.
427
.. versionchanged:: 3.5
428
The default *ssl_version* is changed from :data:`PROTOCOL_SSLv3` to
429
:data:`PROTOCOL_SSLv23` for maximum compatibility with modern servers.
431
.. function:: DER_cert_to_PEM_cert(DER_cert_bytes)
433
Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
434
string version of the same certificate.
436
.. function:: PEM_cert_to_DER_cert(PEM_cert_string)
438
Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
439
bytes for that same certificate.
441
.. function:: get_default_verify_paths()
443
Returns a named tuple with paths to OpenSSL's default cafile and capath.
444
The paths are the same as used by
445
:meth:`SSLContext.set_default_verify_paths`. The return value is a
446
:term:`named tuple` ``DefaultVerifyPaths``:
448
* :attr:`cafile` - resolved path to cafile or None if the file doesn't exist,
449
* :attr:`capath` - resolved path to capath or None if the directory doesn't exist,
450
* :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile,
451
* :attr:`openssl_cafile` - hard coded path to a cafile,
452
* :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
453
* :attr:`openssl_capath` - hard coded path to a capath directory
455
.. versionadded:: 3.4
457
.. function:: enum_certificates(store_name)
459
Retrieve certificates from Windows' system cert store. *store_name* may be
460
one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
463
The function returns a list of (cert_bytes, encoding_type, trust) tuples.
464
The encoding_type specifies the encoding of cert_bytes. It is either
465
:const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
466
PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set
467
of OIDS or exactly ``True`` if the certificate is trustworthy for all
472
>>> ssl.enum_certificates("CA")
473
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
474
(b'data...', 'x509_asn', True)]
476
Availability: Windows.
478
.. versionadded:: 3.4
480
.. function:: enum_crls(store_name)
482
Retrieve CRLs from Windows' system cert store. *store_name* may be
483
one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
486
The function returns a list of (cert_bytes, encoding_type, trust) tuples.
487
The encoding_type specifies the encoding of cert_bytes. It is either
488
:const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
491
Availability: Windows.
493
.. versionadded:: 3.4
501
Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
502
parameter to :func:`wrap_socket`. In this mode (the default), no
503
certificates will be required from the other side of the socket connection.
504
If a certificate is received from the other end, no attempt to validate it
507
See the discussion of :ref:`ssl-security` below.
509
.. data:: CERT_OPTIONAL
511
Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
512
parameter to :func:`wrap_socket`. In this mode no certificates will be
513
required from the other side of the socket connection; but if they
514
are provided, validation will be attempted and an :class:`SSLError`
515
will be raised on failure.
517
Use of this setting requires a valid set of CA certificates to
518
be passed, either to :meth:`SSLContext.load_verify_locations` or as a
519
value of the ``ca_certs`` parameter to :func:`wrap_socket`.
521
.. data:: CERT_REQUIRED
523
Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
524
parameter to :func:`wrap_socket`. In this mode, certificates are
525
required from the other side of the socket connection; an :class:`SSLError`
526
will be raised if no certificate is provided, or if its validation fails.
528
Use of this setting requires a valid set of CA certificates to
529
be passed, either to :meth:`SSLContext.load_verify_locations` or as a
530
value of the ``ca_certs`` parameter to :func:`wrap_socket`.
532
.. data:: VERIFY_DEFAULT
534
Possible value for :attr:`SSLContext.verify_flags`. In this mode, certificate
535
revocation lists (CRLs) are not checked. By default OpenSSL does neither
536
require nor verify CRLs.
538
.. versionadded:: 3.4
540
.. data:: VERIFY_CRL_CHECK_LEAF
542
Possible value for :attr:`SSLContext.verify_flags`. In this mode, only the
543
peer cert is check but non of the intermediate CA certificates. The mode
544
requires a valid CRL that is signed by the peer cert's issuer (its direct
545
ancestor CA). If no proper has been loaded
546
:attr:`SSLContext.load_verify_locations`, validation will fail.
548
.. versionadded:: 3.4
550
.. data:: VERIFY_CRL_CHECK_CHAIN
552
Possible value for :attr:`SSLContext.verify_flags`. In this mode, CRLs of
553
all certificates in the peer cert chain are checked.
555
.. versionadded:: 3.4
557
.. data:: VERIFY_X509_STRICT
559
Possible value for :attr:`SSLContext.verify_flags` to disable workarounds
560
for broken X.509 certificates.
562
.. versionadded:: 3.4
564
.. data:: VERIFY_X509_TRUSTED_FIRST
566
Possible value for :attr:`SSLContext.verify_flags`. It instructs OpenSSL to
567
prefer trusted certificates when building the trust chain to validate a
568
certificate. This flag is enabled by default.
570
.. versionadded:: 3.4.4
572
.. data:: PROTOCOL_SSLv23
574
Selects the highest protocol version that both the client and server support.
575
Despite the name, this option can select "TLS" protocols as well as "SSL".
577
.. data:: PROTOCOL_SSLv2
579
Selects SSL version 2 as the channel encryption protocol.
581
This protocol is not available if OpenSSL is compiled with the
582
``OPENSSL_NO_SSL2`` flag.
586
SSL version 2 is insecure. Its use is highly discouraged.
588
.. data:: PROTOCOL_SSLv3
590
Selects SSL version 3 as the channel encryption protocol.
592
This protocol is not be available if OpenSSL is compiled with the
593
``OPENSSL_NO_SSLv3`` flag.
597
SSL version 3 is insecure. Its use is highly discouraged.
599
.. data:: PROTOCOL_TLSv1
601
Selects TLS version 1.0 as the channel encryption protocol.
603
.. data:: PROTOCOL_TLSv1_1
605
Selects TLS version 1.1 as the channel encryption protocol.
606
Available only with openssl version 1.0.1+.
608
.. versionadded:: 3.4
610
.. data:: PROTOCOL_TLSv1_2
612
Selects TLS version 1.2 as the channel encryption protocol. This is the
613
most modern version, and probably the best choice for maximum protection,
614
if both sides can speak it. Available only with openssl version 1.0.1+.
616
.. versionadded:: 3.4
620
Enables workarounds for various bugs present in other SSL implementations.
621
This option is set by default. It does not necessarily set the same
622
flags as OpenSSL's ``SSL_OP_ALL`` constant.
624
.. versionadded:: 3.2
626
.. data:: OP_NO_SSLv2
628
Prevents an SSLv2 connection. This option is only applicable in
629
conjunction with :const:`PROTOCOL_SSLv23`. It prevents the peers from
630
choosing SSLv2 as the protocol version.
632
.. versionadded:: 3.2
634
.. data:: OP_NO_SSLv3
636
Prevents an SSLv3 connection. This option is only applicable in
637
conjunction with :const:`PROTOCOL_SSLv23`. It prevents the peers from
638
choosing SSLv3 as the protocol version.
640
.. versionadded:: 3.2
642
.. data:: OP_NO_TLSv1
644
Prevents a TLSv1 connection. This option is only applicable in
645
conjunction with :const:`PROTOCOL_SSLv23`. It prevents the peers from
646
choosing TLSv1 as the protocol version.
648
.. versionadded:: 3.2
650
.. data:: OP_NO_TLSv1_1
652
Prevents a TLSv1.1 connection. This option is only applicable in conjunction
653
with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.1 as
654
the protocol version. Available only with openssl version 1.0.1+.
656
.. versionadded:: 3.4
658
.. data:: OP_NO_TLSv1_2
660
Prevents a TLSv1.2 connection. This option is only applicable in conjunction
661
with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.2 as
662
the protocol version. Available only with openssl version 1.0.1+.
664
.. versionadded:: 3.4
666
.. data:: OP_CIPHER_SERVER_PREFERENCE
668
Use the server's cipher ordering preference, rather than the client's.
669
This option has no effect on client sockets and SSLv2 server sockets.
671
.. versionadded:: 3.3
673
.. data:: OP_SINGLE_DH_USE
675
Prevents re-use of the same DH key for distinct SSL sessions. This
676
improves forward secrecy but requires more computational resources.
677
This option only applies to server sockets.
679
.. versionadded:: 3.3
681
.. data:: OP_SINGLE_ECDH_USE
683
Prevents re-use of the same ECDH key for distinct SSL sessions. This
684
improves forward secrecy but requires more computational resources.
685
This option only applies to server sockets.
687
.. versionadded:: 3.3
689
.. data:: OP_NO_COMPRESSION
691
Disable compression on the SSL channel. This is useful if the application
692
protocol supports its own compression scheme.
694
This option is only available with OpenSSL 1.0.0 and later.
696
.. versionadded:: 3.3
700
Whether the OpenSSL library has built-in support for the *Application-Layer
701
Protocol Negotiation* TLS extension as described in :rfc:`7301`.
703
.. versionadded:: 3.5
707
Whether the OpenSSL library has built-in support for Elliptic Curve-based
708
Diffie-Hellman key exchange. This should be true unless the feature was
709
explicitly disabled by the distributor.
711
.. versionadded:: 3.3
715
Whether the OpenSSL library has built-in support for the *Server Name
716
Indication* extension (as defined in :rfc:`4366`).
718
.. versionadded:: 3.2
722
Whether the OpenSSL library has built-in support for *Next Protocol
723
Negotiation* as described in the `NPN draft specification
724
<http://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. When true,
725
you can use the :meth:`SSLContext.set_npn_protocols` method to advertise
726
which protocols you want to support.
728
.. versionadded:: 3.3
730
.. data:: CHANNEL_BINDING_TYPES
732
List of supported TLS channel binding types. Strings in this list
733
can be used as arguments to :meth:`SSLSocket.get_channel_binding`.
735
.. versionadded:: 3.3
737
.. data:: OPENSSL_VERSION
739
The version string of the OpenSSL library loaded by the interpreter::
741
>>> ssl.OPENSSL_VERSION
742
'OpenSSL 0.9.8k 25 Mar 2009'
744
.. versionadded:: 3.2
746
.. data:: OPENSSL_VERSION_INFO
748
A tuple of five integers representing version information about the
751
>>> ssl.OPENSSL_VERSION_INFO
754
.. versionadded:: 3.2
756
.. data:: OPENSSL_VERSION_NUMBER
758
The raw version number of the OpenSSL library, as a single integer::
760
>>> ssl.OPENSSL_VERSION_NUMBER
762
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
765
.. versionadded:: 3.2
767
.. data:: ALERT_DESCRIPTION_HANDSHAKE_FAILURE
768
ALERT_DESCRIPTION_INTERNAL_ERROR
771
Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry
772
<http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_
773
contains this list and references to the RFCs where their meaning is defined.
775
Used as the return value of the callback function in
776
:meth:`SSLContext.set_servername_callback`.
778
.. versionadded:: 3.4
780
.. data:: Purpose.SERVER_AUTH
782
Option for :func:`create_default_context` and
783
:meth:`SSLContext.load_default_certs`. This value indicates that the
784
context may be used to authenticate Web servers (therefore, it will
785
be used to create client-side sockets).
787
.. versionadded:: 3.4
789
.. data:: Purpose.CLIENT_AUTH
791
Option for :func:`create_default_context` and
792
:meth:`SSLContext.load_default_certs`. This value indicates that the
793
context may be used to authenticate Web clients (therefore, it will
794
be used to create server-side sockets).
796
.. versionadded:: 3.4
802
.. class:: SSLSocket(socket.socket)
804
SSL sockets provide the following methods of :ref:`socket-objects`:
806
- :meth:`~socket.socket.accept()`
807
- :meth:`~socket.socket.bind()`
808
- :meth:`~socket.socket.close()`
809
- :meth:`~socket.socket.connect()`
810
- :meth:`~socket.socket.detach()`
811
- :meth:`~socket.socket.fileno()`
812
- :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()`
813
- :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()`
814
- :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
815
:meth:`~socket.socket.setblocking()`
816
- :meth:`~socket.socket.listen()`
817
- :meth:`~socket.socket.makefile()`
818
- :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
819
(but passing a non-zero ``flags`` argument is not allowed)
820
- :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
822
- :meth:`~socket.socket.sendfile()` (but :mod:`os.sendfile` will be used
823
for plain-text sockets only, else :meth:`~socket.socket.send()` will be used)
824
- :meth:`~socket.socket.shutdown()`
826
However, since the SSL (and TLS) protocol has its own framing atop
827
of TCP, the SSL sockets abstraction can, in certain respects, diverge from
828
the specification of normal, OS-level sockets. See especially the
829
:ref:`notes on non-blocking sockets <ssl-nonblocking>`.
831
Usually, :class:`SSLSocket` are not created directly, but using the
832
:func:`wrap_socket` function or the :meth:`SSLContext.wrap_socket` method.
834
.. versionchanged:: 3.5
835
The :meth:`sendfile` method was added.
837
.. versionchanged:: 3.5
838
The :meth:`shutdown` does not reset the socket timeout each time bytes
839
are received or sent. The socket timeout is now to maximum total duration
843
SSL sockets also have the following additional methods and attributes:
845
.. method:: SSLSocket.read(len=0, buffer=None)
847
Read up to *len* bytes of data from the SSL socket and return the result as
848
a ``bytes`` instance. If *buffer* is specified, then read into the buffer
849
instead, and return the number of bytes read.
851
Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is
852
:ref:`non-blocking <ssl-nonblocking>` and the read would block.
854
As at any time a re-negotiation is possible, a call to :meth:`read` can also
855
cause write operations.
857
.. versionchanged:: 3.5
858
The socket timeout is no more reset each time bytes are received or sent.
859
The socket timeout is now to maximum total duration to read up to *len*
862
.. method:: SSLSocket.write(buf)
864
Write *buf* to the SSL socket and return the number of bytes written. The
865
*buf* argument must be an object supporting the buffer interface.
867
Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is
868
:ref:`non-blocking <ssl-nonblocking>` and the write would block.
870
As at any time a re-negotiation is possible, a call to :meth:`write` can
871
also cause read operations.
873
.. versionchanged:: 3.5
874
The socket timeout is no more reset each time bytes are received or sent.
875
The socket timeout is now to maximum total duration to write *buf*.
879
The :meth:`~SSLSocket.read` and :meth:`~SSLSocket.write` methods are the
880
low-level methods that read and write unencrypted, application-level data
881
and decrypt/encrypt it to encrypted, wire-level data. These methods
882
require an active SSL connection, i.e. the handshake was completed and
883
:meth:`SSLSocket.unwrap` was not called.
885
Normally you should use the socket API methods like
886
:meth:`~socket.socket.recv` and :meth:`~socket.socket.send` instead of these
889
.. method:: SSLSocket.do_handshake()
891
Perform the SSL setup handshake.
893
.. versionchanged:: 3.4
894
The handshake method also performs :func:`match_hostname` when the
895
:attr:`~SSLContext.check_hostname` attribute of the socket's
896
:attr:`~SSLSocket.context` is true.
898
.. versionchanged:: 3.5
899
The socket timeout is no more reset each time bytes are received or sent.
900
The socket timeout is now to maximum total duration of the handshake.
902
.. method:: SSLSocket.getpeercert(binary_form=False)
904
If there is no certificate for the peer on the other end of the connection,
905
return ``None``. If the SSL handshake hasn't been done yet, raise
908
If the ``binary_form`` parameter is :const:`False`, and a certificate was
909
received from the peer, this method returns a :class:`dict` instance. If the
910
certificate was not validated, the dict is empty. If the certificate was
911
validated, it returns a dict with several keys, amongst them ``subject``
912
(the principal for which the certificate was issued) and ``issuer``
913
(the principal issuing the certificate). If a certificate contains an
914
instance of the *Subject Alternative Name* extension (see :rfc:`3280`),
915
there will also be a ``subjectAltName`` key in the dictionary.
917
The ``subject`` and ``issuer`` fields are tuples containing the sequence
918
of relative distinguished names (RDNs) given in the certificate's data
919
structure for the respective fields, and each RDN is a sequence of
920
name-value pairs. Here is a real-world example::
922
{'issuer': ((('countryName', 'IL'),),
923
(('organizationName', 'StartCom Ltd.'),),
924
(('organizationalUnitName',
925
'Secure Digital Certificate Signing'),),
927
'StartCom Class 2 Primary Intermediate Server CA'),)),
928
'notAfter': 'Nov 22 08:15:19 2013 GMT',
929
'notBefore': 'Nov 21 03:09:52 2011 GMT',
930
'serialNumber': '95F0',
931
'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
932
(('countryName', 'US'),),
933
(('stateOrProvinceName', 'California'),),
934
(('localityName', 'San Francisco'),),
935
(('organizationName', 'Electronic Frontier Foundation, Inc.'),),
936
(('commonName', '*.eff.org'),),
937
(('emailAddress', 'hostmaster@eff.org'),)),
938
'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
943
To validate a certificate for a particular service, you can use the
944
:func:`match_hostname` function.
946
If the ``binary_form`` parameter is :const:`True`, and a certificate was
947
provided, this method returns the DER-encoded form of the entire certificate
948
as a sequence of bytes, or :const:`None` if the peer did not provide a
949
certificate. Whether the peer provides a certificate depends on the SSL
952
* for a client SSL socket, the server will always provide a certificate,
953
regardless of whether validation was required;
955
* for a server SSL socket, the client will only provide a certificate
956
when requested by the server; therefore :meth:`getpeercert` will return
957
:const:`None` if you used :const:`CERT_NONE` (rather than
958
:const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`).
960
.. versionchanged:: 3.2
961
The returned dictionary includes additional items such as ``issuer``
964
.. versionchanged:: 3.4
965
:exc:`ValueError` is raised when the handshake isn't done.
966
The returned dictionary includes additional X509v3 extension items
967
such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
969
.. method:: SSLSocket.cipher()
971
Returns a three-value tuple containing the name of the cipher being used, the
972
version of the SSL protocol that defines its use, and the number of secret
973
bits being used. If no connection has been established, returns ``None``.
975
.. method:: SSLSocket.shared_ciphers()
977
Return the list of ciphers shared by the client during the handshake. Each
978
entry of the returned list is a three-value tuple containing the name of the
979
cipher, the version of the SSL protocol that defines its use, and the number
980
of secret bits the cipher uses. :meth:`~SSLSocket.shared_ciphers` returns
981
``None`` if no connection has been established or the socket is a client
984
.. versionadded:: 3.5
986
.. method:: SSLSocket.compression()
988
Return the compression algorithm being used as a string, or ``None``
989
if the connection isn't compressed.
991
If the higher-level protocol supports its own compression mechanism,
992
you can use :data:`OP_NO_COMPRESSION` to disable SSL-level compression.
994
.. versionadded:: 3.3
996
.. method:: SSLSocket.get_channel_binding(cb_type="tls-unique")
998
Get channel binding data for current connection, as a bytes object. Returns
999
``None`` if not connected or the handshake has not been completed.
1001
The *cb_type* parameter allow selection of the desired channel binding
1002
type. Valid channel binding types are listed in the
1003
:data:`CHANNEL_BINDING_TYPES` list. Currently only the 'tls-unique' channel
1004
binding, defined by :rfc:`5929`, is supported. :exc:`ValueError` will be
1005
raised if an unsupported channel binding type is requested.
1007
.. versionadded:: 3.3
1009
.. method:: SSLSocket.selected_alpn_protocol()
1011
Return the protocol that was selected during the TLS handshake. If
1012
:meth:`SSLContext.set_alpn_protocols` was not called, if the other party does
1013
not support ALPN, if this socket does not support any of the client's
1014
proposed protocols, or if the handshake has not happened yet, ``None`` is
1017
.. versionadded:: 3.5
1019
.. method:: SSLSocket.selected_npn_protocol()
1021
Return the higher-level protocol that was selected during the TLS/SSL
1022
handshake. If :meth:`SSLContext.set_npn_protocols` was not called, or
1023
if the other party does not support NPN, or if the handshake has not yet
1024
happened, this will return ``None``.
1026
.. versionadded:: 3.3
1028
.. method:: SSLSocket.unwrap()
1030
Performs the SSL shutdown handshake, which removes the TLS layer from the
1031
underlying socket, and returns the underlying socket object. This can be
1032
used to go from encrypted operation over a connection to unencrypted. The
1033
returned socket should always be used for further communication with the
1034
other side of the connection, rather than the original socket.
1036
.. method:: SSLSocket.version()
1038
Return the actual SSL protocol version negotiated by the connection
1039
as a string, or ``None`` is no secure connection is established.
1040
As of this writing, possible return values include ``"SSLv2"``,
1041
``"SSLv3"``, ``"TLSv1"``, ``"TLSv1.1"`` and ``"TLSv1.2"``.
1042
Recent OpenSSL versions may define more return values.
1044
.. versionadded:: 3.5
1046
.. method:: SSLSocket.pending()
1048
Returns the number of already decrypted bytes available for read, pending on
1051
.. attribute:: SSLSocket.context
1053
The :class:`SSLContext` object this SSL socket is tied to. If the SSL
1054
socket was created using the top-level :func:`wrap_socket` function
1055
(rather than :meth:`SSLContext.wrap_socket`), this is a custom context
1056
object created for this SSL socket.
1058
.. versionadded:: 3.2
1060
.. attribute:: SSLSocket.server_side
1062
A boolean which is ``True`` for server-side sockets and ``False`` for
1063
client-side sockets.
1065
.. versionadded:: 3.2
1067
.. attribute:: SSLSocket.server_hostname
1069
Hostname of the server: :class:`str` type, or ``None`` for server-side
1070
socket or if the hostname was not specified in the constructor.
1072
.. versionadded:: 3.2
1078
.. versionadded:: 3.2
1080
An SSL context holds various data longer-lived than single SSL connections,
1081
such as SSL configuration options, certificate(s) and private key(s).
1082
It also manages a cache of SSL sessions for server-side sockets, in order
1083
to speed up repeated connections from the same clients.
1085
.. class:: SSLContext(protocol)
1087
Create a new SSL context. You must pass *protocol* which must be one
1088
of the ``PROTOCOL_*`` constants defined in this module.
1089
:data:`PROTOCOL_SSLv23` is currently recommended for maximum
1093
:func:`create_default_context` lets the :mod:`ssl` module choose
1094
security settings for a given purpose.
1097
:class:`SSLContext` objects have the following methods and attributes:
1099
.. method:: SSLContext.cert_store_stats()
1101
Get statistics about quantities of loaded X.509 certificates, count of
1102
X.509 certificates flagged as CA certificates and certificate revocation
1103
lists as dictionary.
1105
Example for a context with one CA cert and one other cert::
1107
>>> context.cert_store_stats()
1108
{'crl': 0, 'x509_ca': 1, 'x509': 2}
1110
.. versionadded:: 3.4
1113
.. method:: SSLContext.load_cert_chain(certfile, keyfile=None, password=None)
1115
Load a private key and the corresponding certificate. The *certfile*
1116
string must be the path to a single file in PEM format containing the
1117
certificate as well as any number of CA certificates needed to establish
1118
the certificate's authenticity. The *keyfile* string, if present, must
1119
point to a file containing the private key in. Otherwise the private
1120
key will be taken from *certfile* as well. See the discussion of
1121
:ref:`ssl-certificates` for more information on how the certificate
1122
is stored in the *certfile*.
1124
The *password* argument may be a function to call to get the password for
1125
decrypting the private key. It will only be called if the private key is
1126
encrypted and a password is necessary. It will be called with no arguments,
1127
and it should return a string, bytes, or bytearray. If the return value is
1128
a string it will be encoded as UTF-8 before using it to decrypt the key.
1129
Alternatively a string, bytes, or bytearray value may be supplied directly
1130
as the *password* argument. It will be ignored if the private key is not
1131
encrypted and no password is needed.
1133
If the *password* argument is not specified and a password is required,
1134
OpenSSL's built-in password prompting mechanism will be used to
1135
interactively prompt the user for a password.
1137
An :class:`SSLError` is raised if the private key doesn't
1138
match with the certificate.
1140
.. versionchanged:: 3.3
1141
New optional argument *password*.
1143
.. method:: SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)
1145
Load a set of default "certification authority" (CA) certificates from
1146
default locations. On Windows it loads CA certs from the ``CA`` and
1147
``ROOT`` system stores. On other systems it calls
1148
:meth:`SSLContext.set_default_verify_paths`. In the future the method may
1149
load CA certificates from other locations, too.
1151
The *purpose* flag specifies what kind of CA certificates are loaded. The
1152
default settings :data:`Purpose.SERVER_AUTH` loads certificates, that are
1153
flagged and trusted for TLS web server authentication (client side
1154
sockets). :data:`Purpose.CLIENT_AUTH` loads CA certificates for client
1155
certificate verification on the server side.
1157
.. versionadded:: 3.4
1159
.. method:: SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)
1161
Load a set of "certification authority" (CA) certificates used to validate
1162
other peers' certificates when :data:`verify_mode` is other than
1163
:data:`CERT_NONE`. At least one of *cafile* or *capath* must be specified.
1165
This method can also load certification revocation lists (CRLs) in PEM or
1166
DER format. In order to make use of CRLs, :attr:`SSLContext.verify_flags`
1167
must be configured properly.
1169
The *cafile* string, if present, is the path to a file of concatenated
1170
CA certificates in PEM format. See the discussion of
1171
:ref:`ssl-certificates` for more information about how to arrange the
1172
certificates in this file.
1174
The *capath* string, if present, is
1175
the path to a directory containing several CA certificates in PEM format,
1176
following an `OpenSSL specific layout
1177
<http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>`_.
1179
The *cadata* object, if present, is either an ASCII string of one or more
1180
PEM-encoded certificates or a :term:`bytes-like object` of DER-encoded
1181
certificates. Like with *capath* extra lines around PEM-encoded
1182
certificates are ignored but at least one certificate must be present.
1184
.. versionchanged:: 3.4
1185
New optional argument *cadata*
1187
.. method:: SSLContext.get_ca_certs(binary_form=False)
1189
Get a list of loaded "certification authority" (CA) certificates. If the
1190
``binary_form`` parameter is :const:`False` each list
1191
entry is a dict like the output of :meth:`SSLSocket.getpeercert`. Otherwise
1192
the method returns a list of DER-encoded certificates. The returned list
1193
does not contain certificates from *capath* unless a certificate was
1194
requested and loaded by a SSL connection.
1197
Certificates in a capath directory aren't loaded unless they have
1198
been used at least once.
1200
.. versionadded:: 3.4
1202
.. method:: SSLContext.set_default_verify_paths()
1204
Load a set of default "certification authority" (CA) certificates from
1205
a filesystem path defined when building the OpenSSL library. Unfortunately,
1206
there's no easy way to know whether this method succeeds: no error is
1207
returned if no certificates are to be found. When the OpenSSL library is
1208
provided as part of the operating system, though, it is likely to be
1209
configured properly.
1211
.. method:: SSLContext.set_ciphers(ciphers)
1213
Set the available ciphers for sockets created with this context.
1214
It should be a string in the `OpenSSL cipher list format
1215
<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>`_.
1216
If no cipher can be selected (because compile-time options or other
1217
configuration forbids use of all the specified ciphers), an
1218
:class:`SSLError` will be raised.
1221
when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
1222
give the currently selected cipher.
1224
.. method:: SSLContext.set_alpn_protocols(protocols)
1226
Specify which protocols the socket should advertise during the SSL/TLS
1227
handshake. It should be a list of ASCII strings, like ``['http/1.1',
1228
'spdy/2']``, ordered by preference. The selection of a protocol will happen
1229
during the handshake, and will play out according to :rfc:`7301`. After a
1230
successful handshake, the :meth:`SSLSocket.selected_alpn_protocol` method will
1231
return the agreed-upon protocol.
1233
This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is
1236
.. versionadded:: 3.5
1238
.. method:: SSLContext.set_npn_protocols(protocols)
1240
Specify which protocols the socket should advertise during the SSL/TLS
1241
handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``,
1242
ordered by preference. The selection of a protocol will happen during the
1243
handshake, and will play out according to the `NPN draft specification
1244
<http://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. After a
1245
successful handshake, the :meth:`SSLSocket.selected_npn_protocol` method will
1246
return the agreed-upon protocol.
1248
This method will raise :exc:`NotImplementedError` if :data:`HAS_NPN` is
1251
.. versionadded:: 3.3
1253
.. method:: SSLContext.set_servername_callback(server_name_callback)
1255
Register a callback function that will be called after the TLS Client Hello
1256
handshake message has been received by the SSL/TLS server when the TLS client
1257
specifies a server name indication. The server name indication mechanism
1258
is specified in :rfc:`6066` section 3 - Server Name Indication.
1260
Only one callback can be set per ``SSLContext``. If *server_name_callback*
1261
is ``None`` then the callback is disabled. Calling this function a
1262
subsequent time will disable the previously registered callback.
1264
The callback function, *server_name_callback*, will be called with three
1265
arguments; the first being the :class:`ssl.SSLSocket`, the second is a string
1266
that represents the server name that the client is intending to communicate
1267
(or :const:`None` if the TLS Client Hello does not contain a server name)
1268
and the third argument is the original :class:`SSLContext`. The server name
1269
argument is the IDNA decoded server name.
1271
A typical use of this callback is to change the :class:`ssl.SSLSocket`'s
1272
:attr:`SSLSocket.context` attribute to a new object of type
1273
:class:`SSLContext` representing a certificate chain that matches the server
1276
Due to the early negotiation phase of the TLS connection, only limited
1277
methods and attributes are usable like
1278
:meth:`SSLSocket.selected_alpn_protocol` and :attr:`SSLSocket.context`.
1279
:meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.getpeercert`,
1280
:meth:`SSLSocket.cipher` and :meth:`SSLSocket.compress` methods require that
1281
the TLS connection has progressed beyond the TLS Client Hello and therefore
1282
will not contain return meaningful values nor can they be called safely.
1284
The *server_name_callback* function must return ``None`` to allow the
1285
TLS negotiation to continue. If a TLS failure is required, a constant
1286
:const:`ALERT_DESCRIPTION_* <ALERT_DESCRIPTION_INTERNAL_ERROR>` can be
1287
returned. Other return values will result in a TLS fatal error with
1288
:const:`ALERT_DESCRIPTION_INTERNAL_ERROR`.
1290
If there is an IDNA decoding error on the server name, the TLS connection
1291
will terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS
1292
alert message to the client.
1294
If an exception is raised from the *server_name_callback* function the TLS
1295
connection will terminate with a fatal TLS alert message
1296
:const:`ALERT_DESCRIPTION_HANDSHAKE_FAILURE`.
1298
This method will raise :exc:`NotImplementedError` if the OpenSSL library
1299
had OPENSSL_NO_TLSEXT defined when it was built.
1301
.. versionadded:: 3.4
1303
.. method:: SSLContext.load_dh_params(dhfile)
1305
Load the key generation parameters for Diffie-Helman (DH) key exchange.
1306
Using DH key exchange improves forward secrecy at the expense of
1307
computational resources (both on the server and on the client).
1308
The *dhfile* parameter should be the path to a file containing DH
1309
parameters in PEM format.
1311
This setting doesn't apply to client sockets. You can also use the
1312
:data:`OP_SINGLE_DH_USE` option to further improve security.
1314
.. versionadded:: 3.3
1316
.. method:: SSLContext.set_ecdh_curve(curve_name)
1318
Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
1319
exchange. ECDH is significantly faster than regular DH while arguably
1320
as secure. The *curve_name* parameter should be a string describing
1321
a well-known elliptic curve, for example ``prime256v1`` for a widely
1324
This setting doesn't apply to client sockets. You can also use the
1325
:data:`OP_SINGLE_ECDH_USE` option to further improve security.
1327
This method is not available if :data:`HAS_ECDH` is False.
1329
.. versionadded:: 3.3
1332
`SSL/TLS & Perfect Forward Secrecy <http://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-secrecy.html>`_
1335
.. method:: SSLContext.wrap_socket(sock, server_side=False, \
1336
do_handshake_on_connect=True, suppress_ragged_eofs=True, \
1337
server_hostname=None)
1339
Wrap an existing Python socket *sock* and return an :class:`SSLSocket`
1340
object. *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket
1341
types are unsupported.
1343
The returned SSL socket is tied to the context, its settings and
1344
certificates. The parameters *server_side*, *do_handshake_on_connect*
1345
and *suppress_ragged_eofs* have the same meaning as in the top-level
1346
:func:`wrap_socket` function.
1348
On client connections, the optional parameter *server_hostname* specifies
1349
the hostname of the service which we are connecting to. This allows a
1350
single server to host multiple SSL-based services with distinct certificates,
1351
quite similarly to HTTP virtual hosts. Specifying *server_hostname* will
1352
raise a :exc:`ValueError` if *server_side* is true.
1354
.. versionchanged:: 3.5
1355
Always allow a server_hostname to be passed, even if OpenSSL does not
1358
.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
1359
server_hostname=None)
1361
Create a new :class:`SSLObject` instance by wrapping the BIO objects
1362
*incoming* and *outgoing*. The SSL routines will read input data from the
1363
incoming BIO and write data to the outgoing BIO.
1365
The *server_side* and *server_hostname* parameters have the same meaning as
1366
in :meth:`SSLContext.wrap_socket`.
1368
.. method:: SSLContext.session_stats()
1370
Get statistics about the SSL sessions created or managed by this context.
1371
A dictionary is returned which maps the names of each `piece of information
1372
<http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>`_ to their
1373
numeric values. For example, here is the total number of hits and misses
1374
in the session cache since the context was created::
1376
>>> stats = context.session_stats()
1377
>>> stats['hits'], stats['misses']
1380
.. attribute:: SSLContext.check_hostname
1382
Whether to match the peer cert's hostname with :func:`match_hostname` in
1383
:meth:`SSLSocket.do_handshake`. The context's
1384
:attr:`~SSLContext.verify_mode` must be set to :data:`CERT_OPTIONAL` or
1385
:data:`CERT_REQUIRED`, and you must pass *server_hostname* to
1386
:meth:`~SSLContext.wrap_socket` in order to match the hostname.
1392
context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)
1393
context.verify_mode = ssl.CERT_REQUIRED
1394
context.check_hostname = True
1395
context.load_default_certs()
1397
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
1398
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
1399
ssl_sock.connect(('www.verisign.com', 443))
1401
.. versionadded:: 3.4
1405
This features requires OpenSSL 0.9.8f or newer.
1407
.. attribute:: SSLContext.options
1409
An integer representing the set of SSL options enabled on this context.
1410
The default value is :data:`OP_ALL`, but you can specify other options
1411
such as :data:`OP_NO_SSLv2` by ORing them together.
1414
With versions of OpenSSL older than 0.9.8m, it is only possible
1415
to set options, not to clear them. Attempting to clear an option
1416
(by resetting the corresponding bits) will raise a ``ValueError``.
1418
.. attribute:: SSLContext.protocol
1420
The protocol version chosen when constructing the context. This attribute
1423
.. attribute:: SSLContext.verify_flags
1425
The flags for certificate verification operations. You can set flags like
1426
:data:`VERIFY_CRL_CHECK_LEAF` by ORing them together. By default OpenSSL
1427
does neither require nor verify certificate revocation lists (CRLs).
1428
Available only with openssl version 0.9.8+.
1430
.. versionadded:: 3.4
1432
.. attribute:: SSLContext.verify_mode
1434
Whether to try to verify other peers' certificates and how to behave
1435
if verification fails. This attribute must be one of
1436
:data:`CERT_NONE`, :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`.
1439
.. index:: single: certificates
1441
.. index:: single: X509 certificate
1443
.. _ssl-certificates:
1448
Certificates in general are part of a public-key / private-key system. In this
1449
system, each *principal*, (which may be a machine, or a person, or an
1450
organization) is assigned a unique two-part encryption key. One part of the key
1451
is public, and is called the *public key*; the other part is kept secret, and is
1452
called the *private key*. The two parts are related, in that if you encrypt a
1453
message with one of the parts, you can decrypt it with the other part, and
1454
**only** with the other part.
1456
A certificate contains information about two principals. It contains the name
1457
of a *subject*, and the subject's public key. It also contains a statement by a
1458
second principal, the *issuer*, that the subject is who he claims to be, and
1459
that this is indeed the subject's public key. The issuer's statement is signed
1460
with the issuer's private key, which only the issuer knows. However, anyone can
1461
verify the issuer's statement by finding the issuer's public key, decrypting the
1462
statement with it, and comparing it to the other information in the certificate.
1463
The certificate also contains information about the time period over which it is
1464
valid. This is expressed as two fields, called "notBefore" and "notAfter".
1466
In the Python use of certificates, a client or server can use a certificate to
1467
prove who they are. The other side of a network connection can also be required
1468
to produce a certificate, and that certificate can be validated to the
1469
satisfaction of the client or server that requires such validation. The
1470
connection attempt can be set to raise an exception if the validation fails.
1471
Validation is done automatically, by the underlying OpenSSL framework; the
1472
application need not concern itself with its mechanics. But the application
1473
does usually need to provide sets of certificates to allow this process to take
1476
Python uses files to contain certificates. They should be formatted as "PEM"
1477
(see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line
1480
-----BEGIN CERTIFICATE-----
1481
... (certificate in base64 PEM encoding) ...
1482
-----END CERTIFICATE-----
1487
The Python files which contain certificates can contain a sequence of
1488
certificates, sometimes called a *certificate chain*. This chain should start
1489
with the specific certificate for the principal who "is" the client or server,
1490
and then the certificate for the issuer of that certificate, and then the
1491
certificate for the issuer of *that* certificate, and so on up the chain till
1492
you get to a certificate which is *self-signed*, that is, a certificate which
1493
has the same subject and issuer, sometimes called a *root certificate*. The
1494
certificates should just be concatenated together in the certificate file. For
1495
example, suppose we had a three certificate chain, from our server certificate
1496
to the certificate of the certification authority that signed our server
1497
certificate, to the root certificate of the agency which issued the
1498
certification authority's certificate::
1500
-----BEGIN CERTIFICATE-----
1501
... (certificate for your server)...
1502
-----END CERTIFICATE-----
1503
-----BEGIN CERTIFICATE-----
1504
... (the certificate for the CA)...
1505
-----END CERTIFICATE-----
1506
-----BEGIN CERTIFICATE-----
1507
... (the root certificate for the CA's issuer)...
1508
-----END CERTIFICATE-----
1513
If you are going to require validation of the other side of the connection's
1514
certificate, you need to provide a "CA certs" file, filled with the certificate
1515
chains for each issuer you are willing to trust. Again, this file just contains
1516
these chains concatenated together. For validation, Python will use the first
1517
chain it finds in the file which matches. The platform's certificates file can
1518
be used by calling :meth:`SSLContext.load_default_certs`, this is done
1519
automatically with :func:`.create_default_context`.
1521
Combined key and certificate
1522
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1524
Often the private key is stored in the same file as the certificate; in this
1525
case, only the ``certfile`` parameter to :meth:`SSLContext.load_cert_chain`
1526
and :func:`wrap_socket` needs to be passed. If the private key is stored
1527
with the certificate, it should come before the first certificate in
1528
the certificate chain::
1530
-----BEGIN RSA PRIVATE KEY-----
1531
... (private key in base64 encoding) ...
1532
-----END RSA PRIVATE KEY-----
1533
-----BEGIN CERTIFICATE-----
1534
... (certificate in base64 PEM encoding) ...
1535
-----END CERTIFICATE-----
1537
Self-signed certificates
1538
^^^^^^^^^^^^^^^^^^^^^^^^
1540
If you are going to create a server that provides SSL-encrypted connection
1541
services, you will need to acquire a certificate for that service. There are
1542
many ways of acquiring appropriate certificates, such as buying one from a
1543
certification authority. Another common practice is to generate a self-signed
1544
certificate. The simplest way to do this is with the OpenSSL package, using
1545
something like the following::
1547
% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
1548
Generating a 1024 bit RSA private key
1550
.............................++++++
1551
writing new private key to 'cert.pem'
1553
You are about to be asked to enter information that will be incorporated
1554
into your certificate request.
1555
What you are about to enter is what is called a Distinguished Name or a DN.
1556
There are quite a few fields but you can leave some blank
1557
For some fields there will be a default value,
1558
If you enter '.', the field will be left blank.
1560
Country Name (2 letter code) [AU]:US
1561
State or Province Name (full name) [Some-State]:MyState
1562
Locality Name (eg, city) []:Some City
1563
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
1564
Organizational Unit Name (eg, section) []:My Group
1565
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
1566
Email Address []:ops@myserver.mygroup.myorganization.com
1569
The disadvantage of a self-signed certificate is that it is its own root
1570
certificate, and no one else will have it in their cache of known (and trusted)
1577
Testing for SSL support
1578
^^^^^^^^^^^^^^^^^^^^^^^
1580
To test for the presence of SSL support in a Python installation, user code
1581
should use the following idiom::
1588
... # do something that requires SSL support
1590
Client-side operation
1591
^^^^^^^^^^^^^^^^^^^^^
1593
This example creates a SSL context with the recommended security settings
1594
for client sockets, including automatic certificate verification::
1596
>>> context = ssl.create_default_context()
1598
If you prefer to tune security settings yourself, you might create
1599
a context from scratch (but beware that you might not get the settings
1602
>>> context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
1603
>>> context.verify_mode = ssl.CERT_REQUIRED
1604
>>> context.check_hostname = True
1605
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
1607
(this snippet assumes your operating system places a bundle of all CA
1608
certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an
1609
error and have to adjust the location)
1611
When you use the context to connect to a server, :const:`CERT_REQUIRED`
1612
validates the server certificate: it ensures that the server certificate
1613
was signed with one of the CA certificates, and checks the signature for
1616
>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
1617
... server_hostname="www.python.org")
1618
>>> conn.connect(("www.python.org", 443))
1620
You may then fetch the certificate::
1622
>>> cert = conn.getpeercert()
1624
Visual inspection shows that the certificate does identify the desired service
1625
(that is, the HTTPS host ``www.python.org``)::
1627
>>> pprint.pprint(cert)
1628
{'OCSP': ('http://ocsp.digicert.com',),
1629
'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
1630
'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
1631
'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
1632
'issuer': ((('countryName', 'US'),),
1633
(('organizationName', 'DigiCert Inc'),),
1634
(('organizationalUnitName', 'www.digicert.com'),),
1635
(('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
1636
'notAfter': 'Sep 9 12:00:00 2016 GMT',
1637
'notBefore': 'Sep 5 00:00:00 2014 GMT',
1638
'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
1639
'subject': ((('businessCategory', 'Private Organization'),),
1640
(('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
1641
(('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
1642
(('serialNumber', '3359300'),),
1643
(('streetAddress', '16 Allen Rd'),),
1644
(('postalCode', '03894-4801'),),
1645
(('countryName', 'US'),),
1646
(('stateOrProvinceName', 'NH'),),
1647
(('localityName', 'Wolfeboro,'),),
1648
(('organizationName', 'Python Software Foundation'),),
1649
(('commonName', 'www.python.org'),)),
1650
'subjectAltName': (('DNS', 'www.python.org'),
1651
('DNS', 'python.org'),
1652
('DNS', 'pypi.python.org'),
1653
('DNS', 'docs.python.org'),
1654
('DNS', 'testpypi.python.org'),
1655
('DNS', 'bugs.python.org'),
1656
('DNS', 'wiki.python.org'),
1657
('DNS', 'hg.python.org'),
1658
('DNS', 'mail.python.org'),
1659
('DNS', 'packaging.python.org'),
1660
('DNS', 'pythonhosted.org'),
1661
('DNS', 'www.pythonhosted.org'),
1662
('DNS', 'test.pythonhosted.org'),
1663
('DNS', 'us.pycon.org'),
1664
('DNS', 'id.python.org')),
1667
Now the SSL channel is established and the certificate verified, you can
1668
proceed to talk with the server::
1670
>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
1671
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
1672
[b'HTTP/1.1 200 OK',
1673
b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
1675
b'Content-Type: text/html; charset=utf-8',
1676
b'X-Frame-Options: SAMEORIGIN',
1677
b'Content-Length: 45679',
1678
b'Accept-Ranges: bytes',
1679
b'Via: 1.1 varnish',
1681
b'X-Served-By: cache-lcy1134-LCY',
1683
b'X-Cache-Hits: 11',
1685
b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
1686
b'Connection: close',
1690
See the discussion of :ref:`ssl-security` below.
1693
Server-side operation
1694
^^^^^^^^^^^^^^^^^^^^^
1696
For server operation, typically you'll need to have a server certificate, and
1697
private key, each in a file. You'll first create a context holding the key
1698
and the certificate, so that clients can check your authenticity. Then
1699
you'll open a socket, bind it to a port, call :meth:`listen` on it, and start
1700
waiting for clients to connect::
1704
context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
1705
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")
1707
bindsocket = socket.socket()
1708
bindsocket.bind(('myaddr.mydomain.com', 10023))
1709
bindsocket.listen(5)
1711
When a client connects, you'll call :meth:`accept` on the socket to get the
1712
new socket from the other end, and use the context's :meth:`SSLContext.wrap_socket`
1713
method to create a server-side SSL socket for the connection::
1716
newsocket, fromaddr = bindsocket.accept()
1717
connstream = context.wrap_socket(newsocket, server_side=True)
1719
deal_with_client(connstream)
1721
connstream.shutdown(socket.SHUT_RDWR)
1724
Then you'll read data from the ``connstream`` and do something with it till you
1725
are finished with the client (or the client is finished with you)::
1727
def deal_with_client(connstream):
1728
data = connstream.recv(1024)
1729
# empty data means the client is finished with us
1731
if not do_something(connstream, data):
1732
# we'll assume do_something returns False
1733
# when we're finished with client
1735
data = connstream.recv(1024)
1736
# finished with client
1738
And go back to listening for new client connections (of course, a real server
1739
would probably handle each client connection in a separate thread, or put
1740
the sockets in :ref:`non-blocking mode <ssl-nonblocking>` and use an event loop).
1743
.. _ssl-nonblocking:
1745
Notes on non-blocking sockets
1746
-----------------------------
1748
SSL sockets behave slightly different than regular sockets in
1749
non-blocking mode. When working with non-blocking sockets, there are
1750
thus several things you need to be aware of:
1752
- Most :class:`SSLSocket` methods will raise either
1753
:exc:`SSLWantWriteError` or :exc:`SSLWantReadError` instead of
1754
:exc:`BlockingIOError` if an I/O operation would
1755
block. :exc:`SSLWantReadError` will be raised if a read operation on
1756
the underlying socket is necessary, and :exc:`SSLWantWriteError` for
1757
a write operation on the underlying socket. Note that attempts to
1758
*write* to an SSL socket may require *reading* from the underlying
1759
socket first, and attempts to *read* from the SSL socket may require
1760
a prior *write* to the underlying socket.
1762
.. versionchanged:: 3.5
1764
In earlier Python versions, the :meth:`!SSLSocket.send` method
1765
returned zero instead of raising :exc:`SSLWantWriteError` or
1766
:exc:`SSLWantReadError`.
1768
- Calling :func:`~select.select` tells you that the OS-level socket can be
1769
read from (or written to), but it does not imply that there is sufficient
1770
data at the upper SSL layer. For example, only part of an SSL frame might
1771
have arrived. Therefore, you must be ready to handle :meth:`SSLSocket.recv`
1772
and :meth:`SSLSocket.send` failures, and retry after another call to
1773
:func:`~select.select`.
1775
- Conversely, since the SSL layer has its own framing, a SSL socket may
1776
still have data available for reading without :func:`~select.select`
1777
being aware of it. Therefore, you should first call
1778
:meth:`SSLSocket.recv` to drain any potentially available data, and then
1779
only block on a :func:`~select.select` call if still necessary.
1781
(of course, similar provisions apply when using other primitives such as
1782
:func:`~select.poll`, or those in the :mod:`selectors` module)
1784
- The SSL handshake itself will be non-blocking: the
1785
:meth:`SSLSocket.do_handshake` method has to be retried until it returns
1786
successfully. Here is a synopsis using :func:`~select.select` to wait for
1787
the socket's readiness::
1793
except ssl.SSLWantReadError:
1794
select.select([sock], [], [])
1795
except ssl.SSLWantWriteError:
1796
select.select([], [sock], [])
1800
The :mod:`asyncio` module supports :ref:`non-blocking SSL sockets
1801
<ssl-nonblocking>` and provides a
1802
higher level API. It polls for events using the :mod:`selectors` module and
1803
handles :exc:`SSLWantWriteError`, :exc:`SSLWantReadError` and
1804
:exc:`BlockingIOError` exceptions. It runs the SSL handshake asynchronously
1811
.. versionadded:: 3.5
1813
Ever since the SSL module was introduced in Python 2.6, the :class:`SSLSocket`
1814
class has provided two related but distinct areas of functionality:
1816
- SSL protocol handling
1819
The network IO API is identical to that provided by :class:`socket.socket`,
1820
from which :class:`SSLSocket` also inherits. This allows an SSL socket to be
1821
used as a drop-in replacement for a regular socket, making it very easy to add
1822
SSL support to an existing application.
1824
Combining SSL protocol handling and network IO usually works well, but there
1825
are some cases where it doesn't. An example is async IO frameworks that want to
1826
use a different IO multiplexing model than the "select/poll on a file
1827
descriptor" (readiness based) model that is assumed by :class:`socket.socket`
1828
and by the internal OpenSSL socket IO routines. This is mostly relevant for
1829
platforms like Windows where this model is not efficient. For this purpose, a
1830
reduced scope variant of :class:`SSLSocket` called :class:`SSLObject` is
1833
.. class:: SSLObject
1835
A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol
1836
instance that does not contain any network IO methods. This class is
1837
typically used by framework authors that want to implement asynchronous IO
1838
for SSL through memory buffers.
1840
This class implements an interface on top of a low-level SSL object as
1841
implemented by OpenSSL. This object captures the state of an SSL connection
1842
but does not provide any network IO itself. IO needs to be performed through
1843
separate "BIO" objects which are OpenSSL's IO abstraction layer.
1845
An :class:`SSLObject` instance can be created using the
1846
:meth:`~SSLContext.wrap_bio` method. This method will create the
1847
:class:`SSLObject` instance and bind it to a pair of BIOs. The *incoming*
1848
BIO is used to pass data from Python to the SSL protocol instance, while the
1849
*outgoing* BIO is used to pass data the other way around.
1851
The following methods are available:
1853
- :attr:`~SSLSocket.context`
1854
- :attr:`~SSLSocket.server_side`
1855
- :attr:`~SSLSocket.server_hostname`
1856
- :meth:`~SSLSocket.read`
1857
- :meth:`~SSLSocket.write`
1858
- :meth:`~SSLSocket.getpeercert`
1859
- :meth:`~SSLSocket.selected_npn_protocol`
1860
- :meth:`~SSLSocket.cipher`
1861
- :meth:`~SSLSocket.shared_ciphers`
1862
- :meth:`~SSLSocket.compression`
1863
- :meth:`~SSLSocket.pending`
1864
- :meth:`~SSLSocket.do_handshake`
1865
- :meth:`~SSLSocket.unwrap`
1866
- :meth:`~SSLSocket.get_channel_binding`
1868
When compared to :class:`SSLSocket`, this object lacks the following
1871
- Any form of network IO incluging methods such as ``recv()`` and
1874
- There is no *do_handshake_on_connect* machinery. You must always manually
1875
call :meth:`~SSLSocket.do_handshake` to start the handshake.
1877
- There is no handling of *suppress_ragged_eofs*. All end-of-file conditions
1878
that are in violation of the protocol are reported via the
1879
:exc:`SSLEOFError` exception.
1881
- The method :meth:`~SSLSocket.unwrap` call does not return anything,
1882
unlike for an SSL socket where it returns the underlying socket.
1884
- The *server_name_callback* callback passed to
1885
:meth:`SSLContext.set_servername_callback` will get an :class:`SSLObject`
1886
instance instead of a :class:`SSLSocket` instance as its first parameter.
1888
Some notes related to the use of :class:`SSLObject`:
1890
- All IO on an :class:`SSLObject` is :ref:`non-blocking <ssl-nonblocking>`.
1891
This means that for example :meth:`~SSLSocket.read` will raise an
1892
:exc:`SSLWantReadError` if it needs more data than the incoming BIO has
1895
- There is no module-level ``wrap_bio()`` call like there is for
1896
:meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created
1897
via an :class:`SSLContext`.
1899
An SSLObject communicates with the outside world using memory buffers. The
1900
class :class:`MemoryBIO` provides a memory buffer that can be used for this
1901
purpose. It wraps an OpenSSL memory BIO (Basic IO) object:
1903
.. class:: MemoryBIO
1905
A memory buffer that can be used to pass data between Python and an SSL
1908
.. attribute:: MemoryBIO.pending
1910
Return the number of bytes currently in the memory buffer.
1912
.. attribute:: MemoryBIO.eof
1914
A boolean indicating whether the memory BIO is current at the end-of-file
1917
.. method:: MemoryBIO.read(n=-1)
1919
Read up to *n* bytes from the memory buffer. If *n* is not specified or
1920
negative, all bytes are returned.
1922
.. method:: MemoryBIO.write(buf)
1924
Write the bytes from *buf* to the memory BIO. The *buf* argument must be an
1925
object supporting the buffer protocol.
1927
The return value is the number of bytes written, which is always equal to
1928
the length of *buf*.
1930
.. method:: MemoryBIO.write_eof()
1932
Write an EOF marker to the memory BIO. After this method has been called, it
1933
is illegal to call :meth:`~MemoryBIO.write`. The attribute :attr:`eof` will
1934
become true after all data currently in the buffer has been read.
1939
Security considerations
1940
-----------------------
1945
For **client use**, if you don't have any special requirements for your
1946
security policy, it is highly recommended that you use the
1947
:func:`create_default_context` function to create your SSL context.
1948
It will load the system's trusted CA certificates, enable certificate
1949
validation and hostname checking, and try to choose reasonably secure
1950
protocol and cipher settings.
1952
For example, here is how you would use the :class:`smtplib.SMTP` class to
1953
create a trusted, secure connection to a SMTP server::
1955
>>> import ssl, smtplib
1956
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
1957
>>> context = ssl.create_default_context()
1958
>>> smtp.starttls(context=context)
1959
(220, b'2.0.0 Ready to start TLS')
1961
If a client certificate is needed for the connection, it can be added with
1962
:meth:`SSLContext.load_cert_chain`.
1964
By contrast, if you create the SSL context by calling the :class:`SSLContext`
1965
constructor yourself, it will not have certificate validation nor hostname
1966
checking enabled by default. If you do so, please read the paragraphs below
1967
to achieve a good security level.
1972
Verifying certificates
1973
''''''''''''''''''''''
1975
When calling the :class:`SSLContext` constructor directly,
1976
:const:`CERT_NONE` is the default. Since it does not authenticate the other
1977
peer, it can be insecure, especially in client mode where most of time you
1978
would like to ensure the authenticity of the server you're talking to.
1979
Therefore, when in client mode, it is highly recommended to use
1980
:const:`CERT_REQUIRED`. However, it is in itself not sufficient; you also
1981
have to check that the server certificate, which can be obtained by calling
1982
:meth:`SSLSocket.getpeercert`, matches the desired service. For many
1983
protocols and applications, the service can be identified by the hostname;
1984
in this case, the :func:`match_hostname` function can be used. This common
1985
check is automatically performed when :attr:`SSLContext.check_hostname` is
1988
In server mode, if you want to authenticate your clients using the SSL layer
1989
(rather than using a higher-level authentication mechanism), you'll also have
1990
to specify :const:`CERT_REQUIRED` and similarly check the client certificate.
1994
In client mode, :const:`CERT_OPTIONAL` and :const:`CERT_REQUIRED` are
1995
equivalent unless anonymous ciphers are enabled (they are disabled
2001
SSL versions 2 and 3 are considered insecure and are therefore dangerous to
2002
use. If you want maximum compatibility between clients and servers, it is
2003
recommended to use :const:`PROTOCOL_SSLv23` as the protocol version and then
2004
disable SSLv2 and SSLv3 explicitly using the :data:`SSLContext.options`
2007
context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
2008
context.options |= ssl.OP_NO_SSLv2
2009
context.options |= ssl.OP_NO_SSLv3
2011
The SSL context created above will only allow TLSv1 and later (if
2012
supported by your system) connections.
2017
If you have advanced security requirements, fine-tuning of the ciphers
2018
enabled when negotiating a SSL session is possible through the
2019
:meth:`SSLContext.set_ciphers` method. Starting from Python 3.2.3, the
2020
ssl module disables certain weak ciphers by default, but you may want
2021
to further restrict the cipher choice. Be sure to read OpenSSL's documentation
2022
about the `cipher list format <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT>`_.
2023
If you want to check which ciphers are enabled by a given cipher list, use the
2024
``openssl ciphers`` command on your system.
2029
If using this module as part of a multi-processed application (using,
2030
for example the :mod:`multiprocessing` or :mod:`concurrent.futures` modules),
2031
be aware that OpenSSL's internal random number generator does not properly
2032
handle forked processes. Applications must change the PRNG state of the
2033
parent process if they use any SSL feature with :func:`os.fork`. Any
2034
successful call of :func:`~ssl.RAND_add`, :func:`~ssl.RAND_bytes` or
2035
:func:`~ssl.RAND_pseudo_bytes` is sufficient.
2040
Class :class:`socket.socket`
2041
Documentation of underlying :mod:`socket` class
2043
`SSL/TLS Strong Encryption: An Introduction <http://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html>`_
2044
Intro from the Apache webserver documentation
2046
`RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management <http://www.ietf.org/rfc/rfc1422>`_
2049
`RFC 1750: Randomness Recommendations for Security <http://www.ietf.org/rfc/rfc1750>`_
2052
`RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile <http://www.ietf.org/rfc/rfc3280>`_
2055
`RFC 4366: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc/rfc4366>`_
2056
Blake-Wilson et. al.
2058
`RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <http://tools.ietf.org/html/rfc5246>`_
2061
`RFC 6066: Transport Layer Security (TLS) Extensions <http://tools.ietf.org/html/rfc6066>`_
2064
`IANA TLS: Transport Layer Security (TLS) Parameters <http://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_
added
removed
python-3.5.1-docs-html/_sources/library/ssl.txt
