• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`ssl` --- TLS/SSL wrapper for socket objects
2=================================================
3
4.. module:: ssl
5   :synopsis: TLS/SSL wrapper for socket objects
6
7.. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
8.. sectionauthor::  Bill Janssen <bill.janssen@gmail.com>
9
10**Source code:** :source:`Lib/ssl.py`
11
12.. index:: single: OpenSSL; (use in module ssl)
13
14.. index:: TLS, SSL, Transport Layer Security, Secure Sockets Layer
15
16--------------
17
18This module provides access to Transport Layer Security (often known as "Secure
19Sockets Layer") encryption and peer authentication facilities for network
20sockets, both client-side and server-side.  This module uses the OpenSSL
21library. It is available on all modern Unix systems, Windows, Mac OS X, and
22probably additional platforms, as long as OpenSSL is installed on that platform.
23
24.. note::
25
26   Some behavior may be platform dependent, since calls are made to the
27   operating system socket APIs.  The installed version of OpenSSL may also
28   cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with
29   openssl version 1.0.1.
30
31.. warning::
32   Don't use this module without reading the :ref:`ssl-security`.  Doing so
33   may lead to a false sense of security, as the default settings of the
34   ssl module are not necessarily appropriate for your application.
35
36
37This section documents the objects and functions in the ``ssl`` module; for more
38general information about TLS, SSL, and certificates, the reader is referred to
39the documents in the "See Also" section at the bottom.
40
41This module provides a class, :class:`ssl.SSLSocket`, which is derived from the
42:class:`socket.socket` type, and provides a socket-like wrapper that also
43encrypts and decrypts the data going over the socket with SSL.  It supports
44additional methods such as :meth:`getpeercert`, which retrieves the
45certificate of the other side of the connection, and :meth:`cipher`,which
46retrieves the cipher being used for the secure connection.
47
48For more sophisticated applications, the :class:`ssl.SSLContext` class
49helps manage settings and certificates, which can then be inherited
50by SSL sockets created through the :meth:`SSLContext.wrap_socket` method.
51
52.. versionchanged:: 3.6
53
54   OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.
55   In the future the ssl module will require at least OpenSSL 1.0.2 or
56   1.1.0.
57
58
59Functions, Constants, and Exceptions
60------------------------------------
61
62.. exception:: SSLError
63
64   Raised to signal an error from the underlying SSL implementation
65   (currently provided by the OpenSSL library).  This signifies some
66   problem in the higher-level encryption and authentication layer that's
67   superimposed on the underlying network connection.  This error
68   is a subtype of :exc:`OSError`.  The error code and message of
69   :exc:`SSLError` instances are provided by the OpenSSL library.
70
71   .. versionchanged:: 3.3
72      :exc:`SSLError` used to be a subtype of :exc:`socket.error`.
73
74   .. attribute:: library
75
76      A string mnemonic designating the OpenSSL submodule in which the error
77      occurred, such as ``SSL``, ``PEM`` or ``X509``.  The range of possible
78      values depends on the OpenSSL version.
79
80      .. versionadded:: 3.3
81
82   .. attribute:: reason
83
84      A string mnemonic designating the reason this error occurred, for
85      example ``CERTIFICATE_VERIFY_FAILED``.  The range of possible
86      values depends on the OpenSSL version.
87
88      .. versionadded:: 3.3
89
90.. exception:: SSLZeroReturnError
91
92   A subclass of :exc:`SSLError` raised when trying to read or write and
93   the SSL connection has been closed cleanly.  Note that this doesn't
94   mean that the underlying transport (read TCP) has been closed.
95
96   .. versionadded:: 3.3
97
98.. exception:: SSLWantReadError
99
100   A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
101   <ssl-nonblocking>` when trying to read or write data, but more data needs
102   to be received on the underlying TCP transport before the request can be
103   fulfilled.
104
105   .. versionadded:: 3.3
106
107.. exception:: SSLWantWriteError
108
109   A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
110   <ssl-nonblocking>` when trying to read or write data, but more data needs
111   to be sent on the underlying TCP transport before the request can be
112   fulfilled.
113
114   .. versionadded:: 3.3
115
116.. exception:: SSLSyscallError
117
118   A subclass of :exc:`SSLError` raised when a system error was encountered
119   while trying to fulfill an operation on a SSL socket.  Unfortunately,
120   there is no easy way to inspect the original errno number.
121
122   .. versionadded:: 3.3
123
124.. exception:: SSLEOFError
125
126   A subclass of :exc:`SSLError` raised when the SSL connection has been
127   terminated abruptly.  Generally, you shouldn't try to reuse the underlying
128   transport when this error is encountered.
129
130   .. versionadded:: 3.3
131
132.. exception:: CertificateError
133
134   Raised to signal an error with a certificate (such as mismatching
135   hostname).  Certificate errors detected by OpenSSL, though, raise
136   an :exc:`SSLError`.
137
138
139Socket creation
140^^^^^^^^^^^^^^^
141
142The following function allows for standalone socket creation.  Starting from
143Python 3.2, it can be more flexible to use :meth:`SSLContext.wrap_socket`
144instead.
145
146.. 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)
147
148   Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance
149   of :class:`ssl.SSLSocket`, a subtype of :class:`socket.socket`, which wraps
150   the underlying socket in an SSL context.  ``sock`` must be a
151   :data:`~socket.SOCK_STREAM` socket; other socket types are unsupported.
152
153   For client-side sockets, the context construction is lazy; if the
154   underlying socket isn't connected yet, the context construction will be
155   performed after :meth:`connect` is called on the socket.  For
156   server-side sockets, if the socket has no remote peer, it is assumed
157   to be a listening socket, and the server-side SSL wrapping is
158   automatically performed on client connections accepted via the
159   :meth:`accept` method.  :func:`wrap_socket` may raise :exc:`SSLError`.
160
161   The ``keyfile`` and ``certfile`` parameters specify optional files which
162   contain a certificate to be used to identify the local side of the
163   connection.  See the discussion of :ref:`ssl-certificates` for more
164   information on how the certificate is stored in the ``certfile``.
165
166   The parameter ``server_side`` is a boolean which identifies whether
167   server-side or client-side behavior is desired from this socket.
168
169   The parameter ``cert_reqs`` specifies whether a certificate is required from
170   the other side of the connection, and whether it will be validated if
171   provided.  It must be one of the three values :const:`CERT_NONE`
172   (certificates ignored), :const:`CERT_OPTIONAL` (not required, but validated
173   if provided), or :const:`CERT_REQUIRED` (required and validated).  If the
174   value of this parameter is not :const:`CERT_NONE`, then the ``ca_certs``
175   parameter must point to a file of CA certificates.
176
177   The ``ca_certs`` file contains a set of concatenated "certification
178   authority" certificates, which are used to validate certificates passed from
179   the other end of the connection.  See the discussion of
180   :ref:`ssl-certificates` for more information about how to arrange the
181   certificates in this file.
182
183   The parameter ``ssl_version`` specifies which version of the SSL protocol to
184   use.  Typically, the server chooses a particular protocol version, and the
185   client must adapt to the server's choice.  Most of the versions are not
186   interoperable with the other versions.  If not specified, the default is
187   :data:`PROTOCOL_TLS`; it provides the most compatibility with other
188   versions.
189
190   Here's a table showing which versions in a client (down the side) can connect
191   to which versions in a server (along the top):
192
193     .. table::
194
195       ========================  ============  ============  =============  =========  ===========  ===========
196        *client* / **server**    **SSLv2**     **SSLv3**     **TLS**        **TLSv1**  **TLSv1.1**  **TLSv1.2**
197       ------------------------  ------------  ------------  -------------  ---------  -----------  -----------
198        *SSLv2*                    yes           no            no [1]_        no         no         no
199        *SSLv3*                    no            yes           no [2]_        no         no         no
200        *TLS* (*SSLv23*)           no [1]_       no [2]_       yes            yes        yes        yes
201        *TLSv1*                    no            no            yes            yes        no         no
202        *TLSv1.1*                  no            no            yes            no         yes        no
203        *TLSv1.2*                  no            no            yes            no         no         yes
204       ========================  ============  ============  =============  =========  ===========  ===========
205
206   .. rubric:: Footnotes
207   .. [1] :class:`SSLContext` disables SSLv2 with :data:`OP_NO_SSLv2` by default.
208   .. [2] :class:`SSLContext` disables SSLv3 with :data:`OP_NO_SSLv3` by default.
209
210   .. note::
211
212      Which connections succeed will vary depending on the version of
213      OpenSSL.  For example, before OpenSSL 1.0.0, an SSLv23 client
214      would always attempt SSLv2 connections.
215
216   The *ciphers* parameter sets the available ciphers for this SSL object.
217   It should be a string in the `OpenSSL cipher list format
218   <https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`_.
219
220   The parameter ``do_handshake_on_connect`` specifies whether to do the SSL
221   handshake automatically after doing a :meth:`socket.connect`, or whether the
222   application program will call it explicitly, by invoking the
223   :meth:`SSLSocket.do_handshake` method.  Calling
224   :meth:`SSLSocket.do_handshake` explicitly gives the program control over the
225   blocking behavior of the socket I/O involved in the handshake.
226
227   The parameter ``suppress_ragged_eofs`` specifies how the
228   :meth:`SSLSocket.recv` method should signal unexpected EOF from the other end
229   of the connection.  If specified as :const:`True` (the default), it returns a
230   normal EOF (an empty bytes object) in response to unexpected EOF errors
231   raised from the underlying socket; if :const:`False`, it will raise the
232   exceptions back to the caller.
233
234   .. versionchanged:: 3.2
235      New optional argument *ciphers*.
236
237Context creation
238^^^^^^^^^^^^^^^^
239
240A convenience function helps create :class:`SSLContext` objects for common
241purposes.
242
243.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
244
245   Return a new :class:`SSLContext` object with default settings for
246   the given *purpose*.  The settings are chosen by the :mod:`ssl` module,
247   and usually represent a higher security level than when calling the
248   :class:`SSLContext` constructor directly.
249
250   *cafile*, *capath*, *cadata* represent optional CA certificates to
251   trust for certificate verification, as in
252   :meth:`SSLContext.load_verify_locations`.  If all three are
253   :const:`None`, this function can choose to trust the system's default
254   CA certificates instead.
255
256   The settings are: :data:`PROTOCOL_TLS`, :data:`OP_NO_SSLv2`, and
257   :data:`OP_NO_SSLv3` with high encryption cipher suites without RC4 and
258   without unauthenticated cipher suites. Passing :data:`~Purpose.SERVER_AUTH`
259   as *purpose* sets :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED`
260   and either loads CA certificates (when at least one of *cafile*, *capath* or
261   *cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load
262   default CA certificates.
263
264   .. note::
265      The protocol, options, cipher and other settings may change to more
266      restrictive values anytime without prior deprecation.  The values
267      represent a fair balance between compatibility and security.
268
269      If your application needs specific settings, you should create a
270      :class:`SSLContext` and apply the settings yourself.
271
272   .. note::
273      If you find that when certain older clients or servers attempt to connect
274      with a :class:`SSLContext` created by this function that they get an error
275      stating "Protocol or cipher suite mismatch", it may be that they only
276      support SSL3.0 which this function excludes using the
277      :data:`OP_NO_SSLv3`. SSL3.0 is widely considered to be `completely broken
278      <https://en.wikipedia.org/wiki/POODLE>`_. If you still wish to continue to
279      use this function but still allow SSL 3.0 connections you can re-enable
280      them using::
281
282         ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
283         ctx.options &= ~ssl.OP_NO_SSLv3
284
285   .. versionadded:: 3.4
286
287   .. versionchanged:: 3.4.4
288
289     RC4 was dropped from the default cipher string.
290
291   .. versionchanged:: 3.6
292
293     ChaCha20/Poly1305 was added to the default cipher string.
294
295     3DES was dropped from the default cipher string.
296
297
298Random generation
299^^^^^^^^^^^^^^^^^
300
301.. function:: RAND_bytes(num)
302
303   Return *num* cryptographically strong pseudo-random bytes. Raises an
304   :class:`SSLError` if the PRNG has not been seeded with enough data or if the
305   operation is not supported by the current RAND method. :func:`RAND_status`
306   can be used to check the status of the PRNG and :func:`RAND_add` can be used
307   to seed the PRNG.
308
309   For almost all applications :func:`os.urandom` is preferable.
310
311   Read the Wikipedia article, `Cryptographically secure pseudorandom number
312   generator (CSPRNG)
313   <https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator>`_,
314   to get the requirements of a cryptographically generator.
315
316   .. versionadded:: 3.3
317
318.. function:: RAND_pseudo_bytes(num)
319
320   Return (bytes, is_cryptographic): bytes are *num* pseudo-random bytes,
321   is_cryptographic is ``True`` if the bytes generated are cryptographically
322   strong. Raises an :class:`SSLError` if the operation is not supported by the
323   current RAND method.
324
325   Generated pseudo-random byte sequences will be unique if they are of
326   sufficient length, but are not necessarily unpredictable. They can be used
327   for non-cryptographic purposes and for certain purposes in cryptographic
328   protocols, but usually not for key generation etc.
329
330   For almost all applications :func:`os.urandom` is preferable.
331
332   .. versionadded:: 3.3
333
334   .. deprecated:: 3.6
335
336      OpenSSL has deprecated :func:`ssl.RAND_pseudo_bytes`, use
337      :func:`ssl.RAND_bytes` instead.
338
339.. function:: RAND_status()
340
341   Return ``True`` if the SSL pseudo-random number generator has been seeded
342   with 'enough' randomness, and ``False`` otherwise.  You can use
343   :func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness of
344   the pseudo-random number generator.
345
346.. function:: RAND_egd(path)
347
348   If you are running an entropy-gathering daemon (EGD) somewhere, and *path*
349   is the pathname of a socket connection open to it, this will read 256 bytes
350   of randomness from the socket, and add it to the SSL pseudo-random number
351   generator to increase the security of generated secret keys.  This is
352   typically only necessary on systems without better sources of randomness.
353
354   See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources
355   of entropy-gathering daemons.
356
357   Availability: not available with LibreSSL and OpenSSL > 1.1.0
358
359.. function:: RAND_add(bytes, entropy)
360
361   Mix the given *bytes* into the SSL pseudo-random number generator.  The
362   parameter *entropy* (a float) is a lower bound on the entropy contained in
363   string (so you can always use :const:`0.0`).  See :rfc:`1750` for more
364   information on sources of entropy.
365
366   .. versionchanged:: 3.5
367      Writable :term:`bytes-like object` is now accepted.
368
369Certificate handling
370^^^^^^^^^^^^^^^^^^^^
371
372.. function:: match_hostname(cert, hostname)
373
374   Verify that *cert* (in decoded format as returned by
375   :meth:`SSLSocket.getpeercert`) matches the given *hostname*.  The rules
376   applied are those for checking the identity of HTTPS servers as outlined
377   in :rfc:`2818` and :rfc:`6125`.  In addition to HTTPS, this function
378   should be suitable for checking the identity of servers in various
379   SSL-based protocols such as FTPS, IMAPS, POPS and others.
380
381   :exc:`CertificateError` is raised on failure. On success, the function
382   returns nothing::
383
384      >>> cert = {'subject': ((('commonName', 'example.com'),),)}
385      >>> ssl.match_hostname(cert, "example.com")
386      >>> ssl.match_hostname(cert, "example.org")
387      Traceback (most recent call last):
388        File "<stdin>", line 1, in <module>
389        File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
390      ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'
391
392   .. versionadded:: 3.2
393
394   .. versionchanged:: 3.3.3
395      The function now follows :rfc:`6125`, section 6.4.3 and does neither
396      match multiple wildcards (e.g. ``*.*.com`` or ``*a*.example.org``) nor
397      a wildcard inside an internationalized domain names (IDN) fragment.
398      IDN A-labels such as ``www*.xn--pthon-kva.org`` are still supported,
399      but ``x*.python.org`` no longer matches ``xn--tda.python.org``.
400
401   .. versionchanged:: 3.5
402      Matching of IP addresses, when present in the subjectAltName field
403      of the certificate, is now supported.
404
405.. function:: cert_time_to_seconds(cert_time)
406
407   Return the time in seconds since the Epoch, given the ``cert_time``
408   string representing the "notBefore" or "notAfter" date from a
409   certificate in ``"%b %d %H:%M:%S %Y %Z"`` strptime format (C
410   locale).
411
412   Here's an example:
413
414   .. doctest:: newcontext
415
416      >>> import ssl
417      >>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
418      >>> timestamp
419      1515144883
420      >>> from datetime import datetime
421      >>> print(datetime.utcfromtimestamp(timestamp))
422      2018-01-05 09:34:43
423
424   "notBefore" or "notAfter" dates must use GMT (:rfc:`5280`).
425
426   .. versionchanged:: 3.5
427      Interpret the input time as a time in UTC as specified by 'GMT'
428      timezone in the input string. Local timezone was used
429      previously. Return an integer (no fractions of a second in the
430      input format)
431
432.. function:: get_server_certificate(addr, ssl_version=PROTOCOL_TLS, ca_certs=None)
433
434   Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
435   *port-number*) pair, fetches the server's certificate, and returns it as a
436   PEM-encoded string.  If ``ssl_version`` is specified, uses that version of
437   the SSL protocol to attempt to connect to the server.  If ``ca_certs`` is
438   specified, it should be a file containing a list of root certificates, the
439   same format as used for the same parameter in :func:`wrap_socket`.  The call
440   will attempt to validate the server certificate against that set of root
441   certificates, and will fail if the validation attempt fails.
442
443   .. versionchanged:: 3.3
444      This function is now IPv6-compatible.
445
446   .. versionchanged:: 3.5
447      The default *ssl_version* is changed from :data:`PROTOCOL_SSLv3` to
448      :data:`PROTOCOL_TLS` for maximum compatibility with modern servers.
449
450.. function:: DER_cert_to_PEM_cert(DER_cert_bytes)
451
452   Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
453   string version of the same certificate.
454
455.. function:: PEM_cert_to_DER_cert(PEM_cert_string)
456
457   Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
458   bytes for that same certificate.
459
460.. function:: get_default_verify_paths()
461
462   Returns a named tuple with paths to OpenSSL's default cafile and capath.
463   The paths are the same as used by
464   :meth:`SSLContext.set_default_verify_paths`. The return value is a
465   :term:`named tuple` ``DefaultVerifyPaths``:
466
467   * :attr:`cafile` - resolved path to cafile or ``None`` if the file doesn't exist,
468   * :attr:`capath` - resolved path to capath or ``None`` if the directory doesn't exist,
469   * :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile,
470   * :attr:`openssl_cafile` - hard coded path to a cafile,
471   * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
472   * :attr:`openssl_capath` - hard coded path to a capath directory
473
474   Availability: LibreSSL ignores the environment vars
475   :attr:`openssl_cafile_env` and :attr:`openssl_capath_env`
476
477   .. versionadded:: 3.4
478
479.. function:: enum_certificates(store_name)
480
481   Retrieve certificates from Windows' system cert store. *store_name* may be
482   one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
483   stores, too.
484
485   The function returns a list of (cert_bytes, encoding_type, trust) tuples.
486   The encoding_type specifies the encoding of cert_bytes. It is either
487   :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
488   PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set
489   of OIDS or exactly ``True`` if the certificate is trustworthy for all
490   purposes.
491
492   Example::
493
494      >>> ssl.enum_certificates("CA")
495      [(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
496       (b'data...', 'x509_asn', True)]
497
498   Availability: Windows.
499
500   .. versionadded:: 3.4
501
502.. function:: enum_crls(store_name)
503
504   Retrieve CRLs from Windows' system cert store. *store_name* may be
505   one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
506   stores, too.
507
508   The function returns a list of (cert_bytes, encoding_type, trust) tuples.
509   The encoding_type specifies the encoding of cert_bytes. It is either
510   :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
511   PKCS#7 ASN.1 data.
512
513   Availability: Windows.
514
515   .. versionadded:: 3.4
516
517
518Constants
519^^^^^^^^^
520
521   All constants are now :class:`enum.IntEnum` or :class:`enum.IntFlag` collections.
522
523   .. versionadded:: 3.6
524
525.. data:: CERT_NONE
526
527   Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
528   parameter to :func:`wrap_socket`.  In this mode (the default), no
529   certificates will be required from the other side of the socket connection.
530   If a certificate is received from the other end, no attempt to validate it
531   is made.
532
533   See the discussion of :ref:`ssl-security` below.
534
535.. data:: CERT_OPTIONAL
536
537   Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
538   parameter to :func:`wrap_socket`.  In this mode no certificates will be
539   required from the other side of the socket connection; but if they
540   are provided, validation will be attempted and an :class:`SSLError`
541   will be raised on failure.
542
543   Use of this setting requires a valid set of CA certificates to
544   be passed, either to :meth:`SSLContext.load_verify_locations` or as a
545   value of the ``ca_certs`` parameter to :func:`wrap_socket`.
546
547.. data:: CERT_REQUIRED
548
549   Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
550   parameter to :func:`wrap_socket`.  In this mode, certificates are
551   required from the other side of the socket connection; an :class:`SSLError`
552   will be raised if no certificate is provided, or if its validation fails.
553
554   Use of this setting requires a valid set of CA certificates to
555   be passed, either to :meth:`SSLContext.load_verify_locations` or as a
556   value of the ``ca_certs`` parameter to :func:`wrap_socket`.
557
558.. class:: VerifyMode
559
560   :class:`enum.IntEnum` collection of CERT_* constants.
561
562   .. versionadded:: 3.6
563
564.. data:: VERIFY_DEFAULT
565
566   Possible value for :attr:`SSLContext.verify_flags`. In this mode, certificate
567   revocation lists (CRLs) are not checked. By default OpenSSL does neither
568   require nor verify CRLs.
569
570   .. versionadded:: 3.4
571
572.. data:: VERIFY_CRL_CHECK_LEAF
573
574   Possible value for :attr:`SSLContext.verify_flags`. In this mode, only the
575   peer cert is check but non of the intermediate CA certificates. The mode
576   requires a valid CRL that is signed by the peer cert's issuer (its direct
577   ancestor CA). If no proper has been loaded
578   :attr:`SSLContext.load_verify_locations`, validation will fail.
579
580   .. versionadded:: 3.4
581
582.. data:: VERIFY_CRL_CHECK_CHAIN
583
584   Possible value for :attr:`SSLContext.verify_flags`. In this mode, CRLs of
585   all certificates in the peer cert chain are checked.
586
587   .. versionadded:: 3.4
588
589.. data:: VERIFY_X509_STRICT
590
591   Possible value for :attr:`SSLContext.verify_flags` to disable workarounds
592   for broken X.509 certificates.
593
594   .. versionadded:: 3.4
595
596.. data:: VERIFY_X509_TRUSTED_FIRST
597
598   Possible value for :attr:`SSLContext.verify_flags`. It instructs OpenSSL to
599   prefer trusted certificates when building the trust chain to validate a
600   certificate. This flag is enabled by default.
601
602   .. versionadded:: 3.4.4
603
604.. class:: VerifyFlags
605
606   :class:`enum.IntFlag` collection of VERIFY_* constants.
607
608   .. versionadded:: 3.6
609
610.. data:: PROTOCOL_TLS
611
612   Selects the highest protocol version that both the client and server support.
613   Despite the name, this option can select "TLS" protocols as well as "SSL".
614
615   .. versionadded:: 3.6
616
617.. data:: PROTOCOL_TLS_CLIENT
618
619   Auto-negotiate the highest protocol version like :data:`PROTOCOL_SSLv23`,
620   but only support client-side :class:`SSLSocket` connections. The protocol
621   enables :data:`CERT_REQUIRED` and :attr:`~SSLContext.check_hostname` by
622   default.
623
624   .. versionadded:: 3.6
625
626.. data:: PROTOCOL_TLS_SERVER
627
628   Auto-negotiate the highest protocol version like :data:`PROTOCOL_SSLv23`,
629   but only support server-side :class:`SSLSocket` connections.
630
631   .. versionadded:: 3.6
632
633.. data:: PROTOCOL_SSLv23
634
635   Alias for data:`PROTOCOL_TLS`.
636
637   .. deprecated:: 3.6
638
639      Use :data:`PROTOCOL_TLS` instead.
640
641.. data:: PROTOCOL_SSLv2
642
643   Selects SSL version 2 as the channel encryption protocol.
644
645   This protocol is not available if OpenSSL is compiled with the
646   ``OPENSSL_NO_SSL2`` flag.
647
648   .. warning::
649
650      SSL version 2 is insecure.  Its use is highly discouraged.
651
652   .. deprecated:: 3.6
653
654      OpenSSL has removed support for SSLv2.
655
656.. data:: PROTOCOL_SSLv3
657
658   Selects SSL version 3 as the channel encryption protocol.
659
660   This protocol is not be available if OpenSSL is compiled with the
661   ``OPENSSL_NO_SSLv3`` flag.
662
663   .. warning::
664
665      SSL version 3 is insecure.  Its use is highly discouraged.
666
667   .. deprecated:: 3.6
668
669      OpenSSL has deprecated all version specific protocols. Use the default
670      protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
671
672.. data:: PROTOCOL_TLSv1
673
674   Selects TLS version 1.0 as the channel encryption protocol.
675
676   .. deprecated:: 3.6
677
678      OpenSSL has deprecated all version specific protocols. Use the default
679      protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
680
681.. data:: PROTOCOL_TLSv1_1
682
683   Selects TLS version 1.1 as the channel encryption protocol.
684   Available only with openssl version 1.0.1+.
685
686   .. versionadded:: 3.4
687
688   .. deprecated:: 3.6
689
690      OpenSSL has deprecated all version specific protocols. Use the default
691      protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
692
693.. data:: PROTOCOL_TLSv1_2
694
695   Selects TLS version 1.2 as the channel encryption protocol. This is the
696   most modern version, and probably the best choice for maximum protection,
697   if both sides can speak it.  Available only with openssl version 1.0.1+.
698
699   .. versionadded:: 3.4
700
701   .. deprecated:: 3.6
702
703      OpenSSL has deprecated all version specific protocols. Use the default
704      protocol :data:`PROTOCOL_TLS` with flags like :data:`OP_NO_SSLv3` instead.
705
706.. data:: OP_ALL
707
708   Enables workarounds for various bugs present in other SSL implementations.
709   This option is set by default.  It does not necessarily set the same
710   flags as OpenSSL's ``SSL_OP_ALL`` constant.
711
712   .. versionadded:: 3.2
713
714.. data:: OP_NO_SSLv2
715
716   Prevents an SSLv2 connection.  This option is only applicable in
717   conjunction with :const:`PROTOCOL_TLS`.  It prevents the peers from
718   choosing SSLv2 as the protocol version.
719
720   .. versionadded:: 3.2
721
722   .. deprecated:: 3.6
723
724      SSLv2 is deprecated
725
726
727.. data:: OP_NO_SSLv3
728
729   Prevents an SSLv3 connection.  This option is only applicable in
730   conjunction with :const:`PROTOCOL_TLS`.  It prevents the peers from
731   choosing SSLv3 as the protocol version.
732
733   .. versionadded:: 3.2
734
735   .. deprecated:: 3.6
736
737      SSLv3 is deprecated
738
739.. data:: OP_NO_TLSv1
740
741   Prevents a TLSv1 connection.  This option is only applicable in
742   conjunction with :const:`PROTOCOL_TLS`.  It prevents the peers from
743   choosing TLSv1 as the protocol version.
744
745   .. versionadded:: 3.2
746
747.. data:: OP_NO_TLSv1_1
748
749   Prevents a TLSv1.1 connection. This option is only applicable in conjunction
750   with :const:`PROTOCOL_TLS`. It prevents the peers from choosing TLSv1.1 as
751   the protocol version. Available only with openssl version 1.0.1+.
752
753   .. versionadded:: 3.4
754
755.. data:: OP_NO_TLSv1_2
756
757   Prevents a TLSv1.2 connection. This option is only applicable in conjunction
758   with :const:`PROTOCOL_TLS`. It prevents the peers from choosing TLSv1.2 as
759   the protocol version. Available only with openssl version 1.0.1+.
760
761   .. versionadded:: 3.4
762
763.. data:: OP_CIPHER_SERVER_PREFERENCE
764
765   Use the server's cipher ordering preference, rather than the client's.
766   This option has no effect on client sockets and SSLv2 server sockets.
767
768   .. versionadded:: 3.3
769
770.. data:: OP_SINGLE_DH_USE
771
772   Prevents re-use of the same DH key for distinct SSL sessions.  This
773   improves forward secrecy but requires more computational resources.
774   This option only applies to server sockets.
775
776   .. versionadded:: 3.3
777
778.. data:: OP_SINGLE_ECDH_USE
779
780   Prevents re-use of the same ECDH key for distinct SSL sessions.  This
781   improves forward secrecy but requires more computational resources.
782   This option only applies to server sockets.
783
784   .. versionadded:: 3.3
785
786.. data:: OP_NO_COMPRESSION
787
788   Disable compression on the SSL channel.  This is useful if the application
789   protocol supports its own compression scheme.
790
791   This option is only available with OpenSSL 1.0.0 and later.
792
793   .. versionadded:: 3.3
794
795.. class:: Options
796
797   :class:`enum.IntFlag` collection of OP_* constants.
798
799.. data:: OP_NO_TICKET
800
801   Prevent client side from requesting a session ticket.
802
803   .. versionadded:: 3.6
804
805.. data:: HAS_ALPN
806
807   Whether the OpenSSL library has built-in support for the *Application-Layer
808   Protocol Negotiation* TLS extension as described in :rfc:`7301`.
809
810   .. versionadded:: 3.5
811
812.. data:: HAS_ECDH
813
814   Whether the OpenSSL library has built-in support for Elliptic Curve-based
815   Diffie-Hellman key exchange.  This should be true unless the feature was
816   explicitly disabled by the distributor.
817
818   .. versionadded:: 3.3
819
820.. data:: HAS_SNI
821
822   Whether the OpenSSL library has built-in support for the *Server Name
823   Indication* extension (as defined in :rfc:`4366`).
824
825   .. versionadded:: 3.2
826
827.. data:: HAS_NPN
828
829   Whether the OpenSSL library has built-in support for *Next Protocol
830   Negotiation* as described in the `NPN draft specification
831   <https://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. When true,
832   you can use the :meth:`SSLContext.set_npn_protocols` method to advertise
833   which protocols you want to support.
834
835   .. versionadded:: 3.3
836
837.. data:: CHANNEL_BINDING_TYPES
838
839   List of supported TLS channel binding types.  Strings in this list
840   can be used as arguments to :meth:`SSLSocket.get_channel_binding`.
841
842   .. versionadded:: 3.3
843
844.. data:: OPENSSL_VERSION
845
846   The version string of the OpenSSL library loaded by the interpreter::
847
848    >>> ssl.OPENSSL_VERSION
849    'OpenSSL 1.0.2k  26 Jan 2017'
850
851   .. versionadded:: 3.2
852
853.. data:: OPENSSL_VERSION_INFO
854
855   A tuple of five integers representing version information about the
856   OpenSSL library::
857
858    >>> ssl.OPENSSL_VERSION_INFO
859    (1, 0, 2, 11, 15)
860
861   .. versionadded:: 3.2
862
863.. data:: OPENSSL_VERSION_NUMBER
864
865   The raw version number of the OpenSSL library, as a single integer::
866
867    >>> ssl.OPENSSL_VERSION_NUMBER
868    268443839
869    >>> hex(ssl.OPENSSL_VERSION_NUMBER)
870    '0x100020bf'
871
872   .. versionadded:: 3.2
873
874.. data:: ALERT_DESCRIPTION_HANDSHAKE_FAILURE
875          ALERT_DESCRIPTION_INTERNAL_ERROR
876          ALERT_DESCRIPTION_*
877
878   Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry
879   <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_
880   contains this list and references to the RFCs where their meaning is defined.
881
882   Used as the return value of the callback function in
883   :meth:`SSLContext.set_servername_callback`.
884
885   .. versionadded:: 3.4
886
887.. class:: AlertDescription
888
889   :class:`enum.IntEnum` collection of ALERT_DESCRIPTION_* constants.
890
891   .. versionadded:: 3.6
892
893.. data:: Purpose.SERVER_AUTH
894
895   Option for :func:`create_default_context` and
896   :meth:`SSLContext.load_default_certs`.  This value indicates that the
897   context may be used to authenticate Web servers (therefore, it will
898   be used to create client-side sockets).
899
900   .. versionadded:: 3.4
901
902.. data:: Purpose.CLIENT_AUTH
903
904   Option for :func:`create_default_context` and
905   :meth:`SSLContext.load_default_certs`.  This value indicates that the
906   context may be used to authenticate Web clients (therefore, it will
907   be used to create server-side sockets).
908
909   .. versionadded:: 3.4
910
911.. class:: SSLErrorNumber
912
913   :class:`enum.IntEnum` collection of SSL_ERROR_* constants.
914
915   .. versionadded:: 3.6
916
917
918SSL Sockets
919-----------
920
921.. class:: SSLSocket(socket.socket)
922
923   SSL sockets provide the following methods of :ref:`socket-objects`:
924
925   - :meth:`~socket.socket.accept()`
926   - :meth:`~socket.socket.bind()`
927   - :meth:`~socket.socket.close()`
928   - :meth:`~socket.socket.connect()`
929   - :meth:`~socket.socket.detach()`
930   - :meth:`~socket.socket.fileno()`
931   - :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()`
932   - :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()`
933   - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
934     :meth:`~socket.socket.setblocking()`
935   - :meth:`~socket.socket.listen()`
936   - :meth:`~socket.socket.makefile()`
937   - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
938     (but passing a non-zero ``flags`` argument is not allowed)
939   - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
940     the same limitation)
941   - :meth:`~socket.socket.sendfile()` (but :mod:`os.sendfile` will be used
942     for plain-text sockets only, else :meth:`~socket.socket.send()` will be used)
943   - :meth:`~socket.socket.shutdown()`
944
945   However, since the SSL (and TLS) protocol has its own framing atop
946   of TCP, the SSL sockets abstraction can, in certain respects, diverge from
947   the specification of normal, OS-level sockets.  See especially the
948   :ref:`notes on non-blocking sockets <ssl-nonblocking>`.
949
950   Usually, :class:`SSLSocket` are not created directly, but using the
951   :meth:`SSLContext.wrap_socket` method.
952
953   .. versionchanged:: 3.5
954      The :meth:`sendfile` method was added.
955
956   .. versionchanged:: 3.5
957      The :meth:`shutdown` does not reset the socket timeout each time bytes
958      are received or sent. The socket timeout is now to maximum total duration
959      of the shutdown.
960
961   .. deprecated:: 3.6
962      It is deprecated to create a :class:`SSLSocket` instance directly, use
963      :meth:`SSLContext.wrap_socket` to wrap a socket.
964
965
966SSL sockets also have the following additional methods and attributes:
967
968.. method:: SSLSocket.read(len=1024, buffer=None)
969
970   Read up to *len* bytes of data from the SSL socket and return the result as
971   a ``bytes`` instance. If *buffer* is specified, then read into the buffer
972   instead, and return the number of bytes read.
973
974   Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is
975   :ref:`non-blocking <ssl-nonblocking>` and the read would block.
976
977   As at any time a re-negotiation is possible, a call to :meth:`read` can also
978   cause write operations.
979
980   .. versionchanged:: 3.5
981      The socket timeout is no more reset each time bytes are received or sent.
982      The socket timeout is now to maximum total duration to read up to *len*
983      bytes.
984
985   .. deprecated:: 3.6
986      Use :meth:`~SSLSocket.recv` instead of :meth:`~SSLSocket.read`.
987
988.. method:: SSLSocket.write(buf)
989
990   Write *buf* to the SSL socket and return the number of bytes written. The
991   *buf* argument must be an object supporting the buffer interface.
992
993   Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is
994   :ref:`non-blocking <ssl-nonblocking>` and the write would block.
995
996   As at any time a re-negotiation is possible, a call to :meth:`write` can
997   also cause read operations.
998
999   .. versionchanged:: 3.5
1000      The socket timeout is no more reset each time bytes are received or sent.
1001      The socket timeout is now to maximum total duration to write *buf*.
1002
1003   .. deprecated:: 3.6
1004      Use :meth:`~SSLSocket.send` instead of :meth:`~SSLSocket.write`.
1005
1006.. note::
1007
1008   The :meth:`~SSLSocket.read` and :meth:`~SSLSocket.write` methods are the
1009   low-level methods that read and write unencrypted, application-level data
1010   and decrypt/encrypt it to encrypted, wire-level data. These methods
1011   require an active SSL connection, i.e. the handshake was completed and
1012   :meth:`SSLSocket.unwrap` was not called.
1013
1014   Normally you should use the socket API methods like
1015   :meth:`~socket.socket.recv` and :meth:`~socket.socket.send` instead of these
1016   methods.
1017
1018.. method:: SSLSocket.do_handshake()
1019
1020   Perform the SSL setup handshake.
1021
1022   .. versionchanged:: 3.4
1023      The handshake method also performs :func:`match_hostname` when the
1024      :attr:`~SSLContext.check_hostname` attribute of the socket's
1025      :attr:`~SSLSocket.context` is true.
1026
1027   .. versionchanged:: 3.5
1028      The socket timeout is no more reset each time bytes are received or sent.
1029      The socket timeout is now to maximum total duration of the handshake.
1030
1031.. method:: SSLSocket.getpeercert(binary_form=False)
1032
1033   If there is no certificate for the peer on the other end of the connection,
1034   return ``None``.  If the SSL handshake hasn't been done yet, raise
1035   :exc:`ValueError`.
1036
1037   If the ``binary_form`` parameter is :const:`False`, and a certificate was
1038   received from the peer, this method returns a :class:`dict` instance.  If the
1039   certificate was not validated, the dict is empty.  If the certificate was
1040   validated, it returns a dict with several keys, amongst them ``subject``
1041   (the principal for which the certificate was issued) and ``issuer``
1042   (the principal issuing the certificate).  If a certificate contains an
1043   instance of the *Subject Alternative Name* extension (see :rfc:`3280`),
1044   there will also be a ``subjectAltName`` key in the dictionary.
1045
1046   The ``subject`` and ``issuer`` fields are tuples containing the sequence
1047   of relative distinguished names (RDNs) given in the certificate's data
1048   structure for the respective fields, and each RDN is a sequence of
1049   name-value pairs.  Here is a real-world example::
1050
1051      {'issuer': ((('countryName', 'IL'),),
1052                  (('organizationName', 'StartCom Ltd.'),),
1053                  (('organizationalUnitName',
1054                    'Secure Digital Certificate Signing'),),
1055                  (('commonName',
1056                    'StartCom Class 2 Primary Intermediate Server CA'),)),
1057       'notAfter': 'Nov 22 08:15:19 2013 GMT',
1058       'notBefore': 'Nov 21 03:09:52 2011 GMT',
1059       'serialNumber': '95F0',
1060       'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
1061                   (('countryName', 'US'),),
1062                   (('stateOrProvinceName', 'California'),),
1063                   (('localityName', 'San Francisco'),),
1064                   (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
1065                   (('commonName', '*.eff.org'),),
1066                   (('emailAddress', 'hostmaster@eff.org'),)),
1067       'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
1068       'version': 3}
1069
1070   .. note::
1071
1072      To validate a certificate for a particular service, you can use the
1073      :func:`match_hostname` function.
1074
1075   If the ``binary_form`` parameter is :const:`True`, and a certificate was
1076   provided, this method returns the DER-encoded form of the entire certificate
1077   as a sequence of bytes, or :const:`None` if the peer did not provide a
1078   certificate.  Whether the peer provides a certificate depends on the SSL
1079   socket's role:
1080
1081   * for a client SSL socket, the server will always provide a certificate,
1082     regardless of whether validation was required;
1083
1084   * for a server SSL socket, the client will only provide a certificate
1085     when requested by the server; therefore :meth:`getpeercert` will return
1086     :const:`None` if you used :const:`CERT_NONE` (rather than
1087     :const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`).
1088
1089   .. versionchanged:: 3.2
1090      The returned dictionary includes additional items such as ``issuer``
1091      and ``notBefore``.
1092
1093   .. versionchanged:: 3.4
1094      :exc:`ValueError` is raised when the handshake isn't done.
1095      The returned dictionary includes additional X509v3 extension items
1096        such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
1097
1098.. method:: SSLSocket.cipher()
1099
1100   Returns a three-value tuple containing the name of the cipher being used, the
1101   version of the SSL protocol that defines its use, and the number of secret
1102   bits being used.  If no connection has been established, returns ``None``.
1103
1104.. method:: SSLSocket.shared_ciphers()
1105
1106   Return the list of ciphers shared by the client during the handshake.  Each
1107   entry of the returned list is a three-value tuple containing the name of the
1108   cipher, the version of the SSL protocol that defines its use, and the number
1109   of secret bits the cipher uses.  :meth:`~SSLSocket.shared_ciphers` returns
1110   ``None`` if no connection has been established or the socket is a client
1111   socket.
1112
1113   .. versionadded:: 3.5
1114
1115.. method:: SSLSocket.compression()
1116
1117   Return the compression algorithm being used as a string, or ``None``
1118   if the connection isn't compressed.
1119
1120   If the higher-level protocol supports its own compression mechanism,
1121   you can use :data:`OP_NO_COMPRESSION` to disable SSL-level compression.
1122
1123   .. versionadded:: 3.3
1124
1125.. method:: SSLSocket.get_channel_binding(cb_type="tls-unique")
1126
1127   Get channel binding data for current connection, as a bytes object.  Returns
1128   ``None`` if not connected or the handshake has not been completed.
1129
1130   The *cb_type* parameter allow selection of the desired channel binding
1131   type. Valid channel binding types are listed in the
1132   :data:`CHANNEL_BINDING_TYPES` list.  Currently only the 'tls-unique' channel
1133   binding, defined by :rfc:`5929`, is supported.  :exc:`ValueError` will be
1134   raised if an unsupported channel binding type is requested.
1135
1136   .. versionadded:: 3.3
1137
1138.. method:: SSLSocket.selected_alpn_protocol()
1139
1140   Return the protocol that was selected during the TLS handshake.  If
1141   :meth:`SSLContext.set_alpn_protocols` was not called, if the other party does
1142   not support ALPN, if this socket does not support any of the client's
1143   proposed protocols, or if the handshake has not happened yet, ``None`` is
1144   returned.
1145
1146   .. versionadded:: 3.5
1147
1148.. method:: SSLSocket.selected_npn_protocol()
1149
1150   Return the higher-level protocol that was selected during the TLS/SSL
1151   handshake. If :meth:`SSLContext.set_npn_protocols` was not called, or
1152   if the other party does not support NPN, or if the handshake has not yet
1153   happened, this will return ``None``.
1154
1155   .. versionadded:: 3.3
1156
1157.. method:: SSLSocket.unwrap()
1158
1159   Performs the SSL shutdown handshake, which removes the TLS layer from the
1160   underlying socket, and returns the underlying socket object.  This can be
1161   used to go from encrypted operation over a connection to unencrypted.  The
1162   returned socket should always be used for further communication with the
1163   other side of the connection, rather than the original socket.
1164
1165.. method:: SSLSocket.version()
1166
1167   Return the actual SSL protocol version negotiated by the connection
1168   as a string, or ``None`` is no secure connection is established.
1169   As of this writing, possible return values include ``"SSLv2"``,
1170   ``"SSLv3"``, ``"TLSv1"``, ``"TLSv1.1"`` and ``"TLSv1.2"``.
1171   Recent OpenSSL versions may define more return values.
1172
1173   .. versionadded:: 3.5
1174
1175.. method:: SSLSocket.pending()
1176
1177   Returns the number of already decrypted bytes available for read, pending on
1178   the connection.
1179
1180.. attribute:: SSLSocket.context
1181
1182   The :class:`SSLContext` object this SSL socket is tied to.  If the SSL
1183   socket was created using the top-level :func:`wrap_socket` function
1184   (rather than :meth:`SSLContext.wrap_socket`), this is a custom context
1185   object created for this SSL socket.
1186
1187   .. versionadded:: 3.2
1188
1189.. attribute:: SSLSocket.server_side
1190
1191   A boolean which is ``True`` for server-side sockets and ``False`` for
1192   client-side sockets.
1193
1194   .. versionadded:: 3.2
1195
1196.. attribute:: SSLSocket.server_hostname
1197
1198   Hostname of the server: :class:`str` type, or ``None`` for server-side
1199   socket or if the hostname was not specified in the constructor.
1200
1201   .. versionadded:: 3.2
1202
1203.. attribute:: SSLSocket.session
1204
1205   The :class:`SSLSession` for this SSL connection. The session is available
1206   for client and server side sockets after the TLS handshake has been
1207   performed. For client sockets the session can be set before
1208   :meth:`~SSLSocket.do_handshake` has been called to reuse a session.
1209
1210   .. versionadded:: 3.6
1211
1212.. attribute:: SSLSocket.session_reused
1213
1214   .. versionadded:: 3.6
1215
1216
1217SSL Contexts
1218------------
1219
1220.. versionadded:: 3.2
1221
1222An SSL context holds various data longer-lived than single SSL connections,
1223such as SSL configuration options, certificate(s) and private key(s).
1224It also manages a cache of SSL sessions for server-side sockets, in order
1225to speed up repeated connections from the same clients.
1226
1227.. class:: SSLContext(protocol=PROTOCOL_TLS)
1228
1229   Create a new SSL context.  You may pass *protocol* which must be one
1230   of the ``PROTOCOL_*`` constants defined in this module.
1231   :data:`PROTOCOL_TLS` is currently recommended for maximum
1232   interoperability and default value.
1233
1234   .. seealso::
1235      :func:`create_default_context` lets the :mod:`ssl` module choose
1236      security settings for a given purpose.
1237
1238   .. versionchanged:: 3.6
1239
1240      The context is created with secure default values. The options
1241      :data:`OP_NO_COMPRESSION`, :data:`OP_CIPHER_SERVER_PREFERENCE`,
1242      :data:`OP_SINGLE_DH_USE`, :data:`OP_SINGLE_ECDH_USE`,
1243      :data:`OP_NO_SSLv2` (except for :data:`PROTOCOL_SSLv2`),
1244      and :data:`OP_NO_SSLv3` (except for :data:`PROTOCOL_SSLv3`) are
1245      set by default. The initial cipher suite list contains only ``HIGH``
1246      ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for
1247      :data:`PROTOCOL_SSLv2`).
1248
1249
1250:class:`SSLContext` objects have the following methods and attributes:
1251
1252.. method:: SSLContext.cert_store_stats()
1253
1254   Get statistics about quantities of loaded X.509 certificates, count of
1255   X.509 certificates flagged as CA certificates and certificate revocation
1256   lists as dictionary.
1257
1258   Example for a context with one CA cert and one other cert::
1259
1260      >>> context.cert_store_stats()
1261      {'crl': 0, 'x509_ca': 1, 'x509': 2}
1262
1263   .. versionadded:: 3.4
1264
1265
1266.. method:: SSLContext.load_cert_chain(certfile, keyfile=None, password=None)
1267
1268   Load a private key and the corresponding certificate.  The *certfile*
1269   string must be the path to a single file in PEM format containing the
1270   certificate as well as any number of CA certificates needed to establish
1271   the certificate's authenticity.  The *keyfile* string, if present, must
1272   point to a file containing the private key in.  Otherwise the private
1273   key will be taken from *certfile* as well.  See the discussion of
1274   :ref:`ssl-certificates` for more information on how the certificate
1275   is stored in the *certfile*.
1276
1277   The *password* argument may be a function to call to get the password for
1278   decrypting the private key.  It will only be called if the private key is
1279   encrypted and a password is necessary.  It will be called with no arguments,
1280   and it should return a string, bytes, or bytearray.  If the return value is
1281   a string it will be encoded as UTF-8 before using it to decrypt the key.
1282   Alternatively a string, bytes, or bytearray value may be supplied directly
1283   as the *password* argument.  It will be ignored if the private key is not
1284   encrypted and no password is needed.
1285
1286   If the *password* argument is not specified and a password is required,
1287   OpenSSL's built-in password prompting mechanism will be used to
1288   interactively prompt the user for a password.
1289
1290   An :class:`SSLError` is raised if the private key doesn't
1291   match with the certificate.
1292
1293   .. versionchanged:: 3.3
1294      New optional argument *password*.
1295
1296.. method:: SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)
1297
1298   Load a set of default "certification authority" (CA) certificates from
1299   default locations. On Windows it loads CA certs from the ``CA`` and
1300   ``ROOT`` system stores. On other systems it calls
1301   :meth:`SSLContext.set_default_verify_paths`. In the future the method may
1302   load CA certificates from other locations, too.
1303
1304   The *purpose* flag specifies what kind of CA certificates are loaded. The
1305   default settings :data:`Purpose.SERVER_AUTH` loads certificates, that are
1306   flagged and trusted for TLS web server authentication (client side
1307   sockets). :data:`Purpose.CLIENT_AUTH` loads CA certificates for client
1308   certificate verification on the server side.
1309
1310   .. versionadded:: 3.4
1311
1312.. method:: SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)
1313
1314   Load a set of "certification authority" (CA) certificates used to validate
1315   other peers' certificates when :data:`verify_mode` is other than
1316   :data:`CERT_NONE`.  At least one of *cafile* or *capath* must be specified.
1317
1318   This method can also load certification revocation lists (CRLs) in PEM or
1319   DER format. In order to make use of CRLs, :attr:`SSLContext.verify_flags`
1320   must be configured properly.
1321
1322   The *cafile* string, if present, is the path to a file of concatenated
1323   CA certificates in PEM format. See the discussion of
1324   :ref:`ssl-certificates` for more information about how to arrange the
1325   certificates in this file.
1326
1327   The *capath* string, if present, is
1328   the path to a directory containing several CA certificates in PEM format,
1329   following an `OpenSSL specific layout
1330   <https://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>`_.
1331
1332   The *cadata* object, if present, is either an ASCII string of one or more
1333   PEM-encoded certificates or a :term:`bytes-like object` of DER-encoded
1334   certificates. Like with *capath* extra lines around PEM-encoded
1335   certificates are ignored but at least one certificate must be present.
1336
1337   .. versionchanged:: 3.4
1338      New optional argument *cadata*
1339
1340.. method:: SSLContext.get_ca_certs(binary_form=False)
1341
1342   Get a list of loaded "certification authority" (CA) certificates. If the
1343   ``binary_form`` parameter is :const:`False` each list
1344   entry is a dict like the output of :meth:`SSLSocket.getpeercert`. Otherwise
1345   the method returns a list of DER-encoded certificates. The returned list
1346   does not contain certificates from *capath* unless a certificate was
1347   requested and loaded by a SSL connection.
1348
1349   .. note::
1350      Certificates in a capath directory aren't loaded unless they have
1351      been used at least once.
1352
1353   .. versionadded:: 3.4
1354
1355.. method:: SSLContext.get_ciphers()
1356
1357   Get a list of enabled ciphers. The list is in order of cipher priority.
1358   See :meth:`SSLContext.set_ciphers`.
1359
1360   Example::
1361
1362       >>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
1363       >>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
1364       >>> ctx.get_ciphers()  # OpenSSL 1.0.x
1365       [{'alg_bits': 256,
1366         'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
1367                        'Enc=AESGCM(256) Mac=AEAD',
1368         'id': 50380848,
1369         'name': 'ECDHE-RSA-AES256-GCM-SHA384',
1370         'protocol': 'TLSv1/SSLv3',
1371         'strength_bits': 256},
1372        {'alg_bits': 128,
1373         'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
1374                        'Enc=AESGCM(128) Mac=AEAD',
1375         'id': 50380847,
1376         'name': 'ECDHE-RSA-AES128-GCM-SHA256',
1377         'protocol': 'TLSv1/SSLv3',
1378         'strength_bits': 128}]
1379
1380   On OpenSSL 1.1 and newer the cipher dict contains additional fields::
1381       >>> ctx.get_ciphers()  # OpenSSL 1.1+
1382       [{'aead': True,
1383         'alg_bits': 256,
1384         'auth': 'auth-rsa',
1385         'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
1386                        'Enc=AESGCM(256) Mac=AEAD',
1387         'digest': None,
1388         'id': 50380848,
1389         'kea': 'kx-ecdhe',
1390         'name': 'ECDHE-RSA-AES256-GCM-SHA384',
1391         'protocol': 'TLSv1.2',
1392         'strength_bits': 256,
1393         'symmetric': 'aes-256-gcm'},
1394        {'aead': True,
1395         'alg_bits': 128,
1396         'auth': 'auth-rsa',
1397         'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
1398                        'Enc=AESGCM(128) Mac=AEAD',
1399         'digest': None,
1400         'id': 50380847,
1401         'kea': 'kx-ecdhe',
1402         'name': 'ECDHE-RSA-AES128-GCM-SHA256',
1403         'protocol': 'TLSv1.2',
1404         'strength_bits': 128,
1405         'symmetric': 'aes-128-gcm'}]
1406
1407   Availability: OpenSSL 1.0.2+
1408
1409   .. versionadded:: 3.6
1410
1411.. method:: SSLContext.set_default_verify_paths()
1412
1413   Load a set of default "certification authority" (CA) certificates from
1414   a filesystem path defined when building the OpenSSL library.  Unfortunately,
1415   there's no easy way to know whether this method succeeds: no error is
1416   returned if no certificates are to be found.  When the OpenSSL library is
1417   provided as part of the operating system, though, it is likely to be
1418   configured properly.
1419
1420.. method:: SSLContext.set_ciphers(ciphers)
1421
1422   Set the available ciphers for sockets created with this context.
1423   It should be a string in the `OpenSSL cipher list format
1424   <https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`_.
1425   If no cipher can be selected (because compile-time options or other
1426   configuration forbids use of all the specified ciphers), an
1427   :class:`SSLError` will be raised.
1428
1429   .. note::
1430      when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
1431      give the currently selected cipher.
1432
1433.. method:: SSLContext.set_alpn_protocols(protocols)
1434
1435   Specify which protocols the socket should advertise during the SSL/TLS
1436   handshake. It should be a list of ASCII strings, like ``['http/1.1',
1437   'spdy/2']``, ordered by preference. The selection of a protocol will happen
1438   during the handshake, and will play out according to :rfc:`7301`. After a
1439   successful handshake, the :meth:`SSLSocket.selected_alpn_protocol` method will
1440   return the agreed-upon protocol.
1441
1442   This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is
1443   False.
1444
1445   OpenSSL 1.1.0+ will abort the handshake and raise :exc:`SSLError` when
1446   both sides support ALPN but cannot agree on a protocol.
1447
1448   .. versionadded:: 3.5
1449
1450.. method:: SSLContext.set_npn_protocols(protocols)
1451
1452   Specify which protocols the socket should advertise during the SSL/TLS
1453   handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``,
1454   ordered by preference. The selection of a protocol will happen during the
1455   handshake, and will play out according to the `NPN draft specification
1456   <https://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. After a
1457   successful handshake, the :meth:`SSLSocket.selected_npn_protocol` method will
1458   return the agreed-upon protocol.
1459
1460   This method will raise :exc:`NotImplementedError` if :data:`HAS_NPN` is
1461   False.
1462
1463   .. versionadded:: 3.3
1464
1465.. method:: SSLContext.set_servername_callback(server_name_callback)
1466
1467   Register a callback function that will be called after the TLS Client Hello
1468   handshake message has been received by the SSL/TLS server when the TLS client
1469   specifies a server name indication. The server name indication mechanism
1470   is specified in :rfc:`6066` section 3 - Server Name Indication.
1471
1472   Only one callback can be set per ``SSLContext``.  If *server_name_callback*
1473   is ``None`` then the callback is disabled. Calling this function a
1474   subsequent time will disable the previously registered callback.
1475
1476   The callback function, *server_name_callback*, will be called with three
1477   arguments; the first being the :class:`ssl.SSLSocket`, the second is a string
1478   that represents the server name that the client is intending to communicate
1479   (or :const:`None` if the TLS Client Hello does not contain a server name)
1480   and the third argument is the original :class:`SSLContext`. The server name
1481   argument is the IDNA decoded server name.
1482
1483   A typical use of this callback is to change the :class:`ssl.SSLSocket`'s
1484   :attr:`SSLSocket.context` attribute to a new object of type
1485   :class:`SSLContext` representing a certificate chain that matches the server
1486   name.
1487
1488   Due to the early negotiation phase of the TLS connection, only limited
1489   methods and attributes are usable like
1490   :meth:`SSLSocket.selected_alpn_protocol` and :attr:`SSLSocket.context`.
1491   :meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.getpeercert`,
1492   :meth:`SSLSocket.cipher` and :meth:`SSLSocket.compress` methods require that
1493   the TLS connection has progressed beyond the TLS Client Hello and therefore
1494   will not contain return meaningful values nor can they be called safely.
1495
1496   The *server_name_callback* function must return ``None`` to allow the
1497   TLS negotiation to continue.  If a TLS failure is required, a constant
1498   :const:`ALERT_DESCRIPTION_* <ALERT_DESCRIPTION_INTERNAL_ERROR>` can be
1499   returned.  Other return values will result in a TLS fatal error with
1500   :const:`ALERT_DESCRIPTION_INTERNAL_ERROR`.
1501
1502   If there is an IDNA decoding error on the server name, the TLS connection
1503   will terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS
1504   alert message to the client.
1505
1506   If an exception is raised from the *server_name_callback* function the TLS
1507   connection will terminate with a fatal TLS alert message
1508   :const:`ALERT_DESCRIPTION_HANDSHAKE_FAILURE`.
1509
1510   This method will raise :exc:`NotImplementedError` if the OpenSSL library
1511   had OPENSSL_NO_TLSEXT defined when it was built.
1512
1513   .. versionadded:: 3.4
1514
1515.. method:: SSLContext.load_dh_params(dhfile)
1516
1517   Load the key generation parameters for Diffie-Helman (DH) key exchange.
1518   Using DH key exchange improves forward secrecy at the expense of
1519   computational resources (both on the server and on the client).
1520   The *dhfile* parameter should be the path to a file containing DH
1521   parameters in PEM format.
1522
1523   This setting doesn't apply to client sockets.  You can also use the
1524   :data:`OP_SINGLE_DH_USE` option to further improve security.
1525
1526   .. versionadded:: 3.3
1527
1528.. method:: SSLContext.set_ecdh_curve(curve_name)
1529
1530   Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
1531   exchange.  ECDH is significantly faster than regular DH while arguably
1532   as secure.  The *curve_name* parameter should be a string describing
1533   a well-known elliptic curve, for example ``prime256v1`` for a widely
1534   supported curve.
1535
1536   This setting doesn't apply to client sockets.  You can also use the
1537   :data:`OP_SINGLE_ECDH_USE` option to further improve security.
1538
1539   This method is not available if :data:`HAS_ECDH` is ``False``.
1540
1541   .. versionadded:: 3.3
1542
1543   .. seealso::
1544      `SSL/TLS & Perfect Forward Secrecy <http://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-secrecy.html>`_
1545         Vincent Bernat.
1546
1547.. method:: SSLContext.wrap_socket(sock, server_side=False, \
1548      do_handshake_on_connect=True, suppress_ragged_eofs=True, \
1549      server_hostname=None, session=None)
1550
1551   Wrap an existing Python socket *sock* and return an :class:`SSLSocket`
1552   object.  *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket
1553   types are unsupported.
1554
1555   The returned SSL socket is tied to the context, its settings and
1556   certificates.  The parameters *server_side*, *do_handshake_on_connect*
1557   and *suppress_ragged_eofs* have the same meaning as in the top-level
1558   :func:`wrap_socket` function.
1559
1560   On client connections, the optional parameter *server_hostname* specifies
1561   the hostname of the service which we are connecting to.  This allows a
1562   single server to host multiple SSL-based services with distinct certificates,
1563   quite similarly to HTTP virtual hosts. Specifying *server_hostname* will
1564   raise a :exc:`ValueError` if *server_side* is true.
1565
1566   *session*, see :attr:`~SSLSocket.session`.
1567
1568   .. versionchanged:: 3.5
1569      Always allow a server_hostname to be passed, even if OpenSSL does not
1570      have SNI.
1571
1572   .. versionchanged:: 3.6
1573      *session* argument was added.
1574
1575.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
1576                                server_hostname=None, session=None)
1577
1578   Create a new :class:`SSLObject` instance by wrapping the BIO objects
1579   *incoming* and *outgoing*. The SSL routines will read input data from the
1580   incoming BIO and write data to the outgoing BIO.
1581
1582   The *server_side*, *server_hostname* and *session* parameters have the
1583   same meaning as in :meth:`SSLContext.wrap_socket`.
1584
1585   .. versionchanged:: 3.6
1586      *session* argument was added.
1587
1588.. method:: SSLContext.session_stats()
1589
1590   Get statistics about the SSL sessions created or managed by this context.
1591   A dictionary is returned which maps the names of each `piece of information
1592   <https://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>`_ to their
1593   numeric values.  For example, here is the total number of hits and misses
1594   in the session cache since the context was created::
1595
1596      >>> stats = context.session_stats()
1597      >>> stats['hits'], stats['misses']
1598      (0, 0)
1599
1600.. attribute:: SSLContext.check_hostname
1601
1602   Whether to match the peer cert's hostname with :func:`match_hostname` in
1603   :meth:`SSLSocket.do_handshake`. The context's
1604   :attr:`~SSLContext.verify_mode` must be set to :data:`CERT_OPTIONAL` or
1605   :data:`CERT_REQUIRED`, and you must pass *server_hostname* to
1606   :meth:`~SSLContext.wrap_socket` in order to match the hostname.
1607
1608   Example::
1609
1610      import socket, ssl
1611
1612      context = ssl.SSLContext(ssl.PROTOCOL_TLSv1)
1613      context.verify_mode = ssl.CERT_REQUIRED
1614      context.check_hostname = True
1615      context.load_default_certs()
1616
1617      s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
1618      ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
1619      ssl_sock.connect(('www.verisign.com', 443))
1620
1621   .. versionadded:: 3.4
1622
1623   .. note::
1624
1625     This features requires OpenSSL 0.9.8f or newer.
1626
1627.. attribute:: SSLContext.options
1628
1629   An integer representing the set of SSL options enabled on this context.
1630   The default value is :data:`OP_ALL`, but you can specify other options
1631   such as :data:`OP_NO_SSLv2` by ORing them together.
1632
1633   .. note::
1634      With versions of OpenSSL older than 0.9.8m, it is only possible
1635      to set options, not to clear them.  Attempting to clear an option
1636      (by resetting the corresponding bits) will raise a ``ValueError``.
1637
1638   .. versionchanged:: 3.6
1639      :attr:`SSLContext.options` returns :class:`Options` flags:
1640
1641         >>> ssl.create_default_context().options
1642         <Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
1643
1644.. attribute:: SSLContext.protocol
1645
1646   The protocol version chosen when constructing the context.  This attribute
1647   is read-only.
1648
1649.. attribute:: SSLContext.verify_flags
1650
1651   The flags for certificate verification operations. You can set flags like
1652   :data:`VERIFY_CRL_CHECK_LEAF` by ORing them together. By default OpenSSL
1653   does neither require nor verify certificate revocation lists (CRLs).
1654   Available only with openssl version 0.9.8+.
1655
1656   .. versionadded:: 3.4
1657
1658   .. versionchanged:: 3.6
1659      :attr:`SSLContext.verify_flags` returns :class:`VerifyFlags` flags:
1660
1661         >>> ssl.create_default_context().verify_flags
1662         <VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>
1663
1664.. attribute:: SSLContext.verify_mode
1665
1666   Whether to try to verify other peers' certificates and how to behave
1667   if verification fails.  This attribute must be one of
1668   :data:`CERT_NONE`, :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`.
1669
1670   .. versionchanged:: 3.6
1671      :attr:`SSLContext.verify_mode` returns :class:`VerifyMode` enum:
1672
1673         >>> ssl.create_default_context().verify_mode
1674         <VerifyMode.CERT_REQUIRED: 2>
1675
1676.. index:: single: certificates
1677
1678.. index:: single: X509 certificate
1679
1680.. _ssl-certificates:
1681
1682Certificates
1683------------
1684
1685Certificates in general are part of a public-key / private-key system.  In this
1686system, each *principal*, (which may be a machine, or a person, or an
1687organization) is assigned a unique two-part encryption key.  One part of the key
1688is public, and is called the *public key*; the other part is kept secret, and is
1689called the *private key*.  The two parts are related, in that if you encrypt a
1690message with one of the parts, you can decrypt it with the other part, and
1691**only** with the other part.
1692
1693A certificate contains information about two principals.  It contains the name
1694of a *subject*, and the subject's public key.  It also contains a statement by a
1695second principal, the *issuer*, that the subject is who he claims to be, and
1696that this is indeed the subject's public key.  The issuer's statement is signed
1697with the issuer's private key, which only the issuer knows.  However, anyone can
1698verify the issuer's statement by finding the issuer's public key, decrypting the
1699statement with it, and comparing it to the other information in the certificate.
1700The certificate also contains information about the time period over which it is
1701valid.  This is expressed as two fields, called "notBefore" and "notAfter".
1702
1703In the Python use of certificates, a client or server can use a certificate to
1704prove who they are.  The other side of a network connection can also be required
1705to produce a certificate, and that certificate can be validated to the
1706satisfaction of the client or server that requires such validation.  The
1707connection attempt can be set to raise an exception if the validation fails.
1708Validation is done automatically, by the underlying OpenSSL framework; the
1709application need not concern itself with its mechanics.  But the application
1710does usually need to provide sets of certificates to allow this process to take
1711place.
1712
1713Python uses files to contain certificates.  They should be formatted as "PEM"
1714(see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line
1715and a footer line::
1716
1717      -----BEGIN CERTIFICATE-----
1718      ... (certificate in base64 PEM encoding) ...
1719      -----END CERTIFICATE-----
1720
1721Certificate chains
1722^^^^^^^^^^^^^^^^^^
1723
1724The Python files which contain certificates can contain a sequence of
1725certificates, sometimes called a *certificate chain*.  This chain should start
1726with the specific certificate for the principal who "is" the client or server,
1727and then the certificate for the issuer of that certificate, and then the
1728certificate for the issuer of *that* certificate, and so on up the chain till
1729you get to a certificate which is *self-signed*, that is, a certificate which
1730has the same subject and issuer, sometimes called a *root certificate*.  The
1731certificates should just be concatenated together in the certificate file.  For
1732example, suppose we had a three certificate chain, from our server certificate
1733to the certificate of the certification authority that signed our server
1734certificate, to the root certificate of the agency which issued the
1735certification authority's certificate::
1736
1737      -----BEGIN CERTIFICATE-----
1738      ... (certificate for your server)...
1739      -----END CERTIFICATE-----
1740      -----BEGIN CERTIFICATE-----
1741      ... (the certificate for the CA)...
1742      -----END CERTIFICATE-----
1743      -----BEGIN CERTIFICATE-----
1744      ... (the root certificate for the CA's issuer)...
1745      -----END CERTIFICATE-----
1746
1747CA certificates
1748^^^^^^^^^^^^^^^
1749
1750If you are going to require validation of the other side of the connection's
1751certificate, you need to provide a "CA certs" file, filled with the certificate
1752chains for each issuer you are willing to trust.  Again, this file just contains
1753these chains concatenated together.  For validation, Python will use the first
1754chain it finds in the file which matches.  The platform's certificates file can
1755be used by calling :meth:`SSLContext.load_default_certs`, this is done
1756automatically with :func:`.create_default_context`.
1757
1758Combined key and certificate
1759^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1760
1761Often the private key is stored in the same file as the certificate; in this
1762case, only the ``certfile`` parameter to :meth:`SSLContext.load_cert_chain`
1763and :func:`wrap_socket` needs to be passed.  If the private key is stored
1764with the certificate, it should come before the first certificate in
1765the certificate chain::
1766
1767   -----BEGIN RSA PRIVATE KEY-----
1768   ... (private key in base64 encoding) ...
1769   -----END RSA PRIVATE KEY-----
1770   -----BEGIN CERTIFICATE-----
1771   ... (certificate in base64 PEM encoding) ...
1772   -----END CERTIFICATE-----
1773
1774Self-signed certificates
1775^^^^^^^^^^^^^^^^^^^^^^^^
1776
1777If you are going to create a server that provides SSL-encrypted connection
1778services, you will need to acquire a certificate for that service.  There are
1779many ways of acquiring appropriate certificates, such as buying one from a
1780certification authority.  Another common practice is to generate a self-signed
1781certificate.  The simplest way to do this is with the OpenSSL package, using
1782something like the following::
1783
1784  % openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
1785  Generating a 1024 bit RSA private key
1786  .......++++++
1787  .............................++++++
1788  writing new private key to 'cert.pem'
1789  -----
1790  You are about to be asked to enter information that will be incorporated
1791  into your certificate request.
1792  What you are about to enter is what is called a Distinguished Name or a DN.
1793  There are quite a few fields but you can leave some blank
1794  For some fields there will be a default value,
1795  If you enter '.', the field will be left blank.
1796  -----
1797  Country Name (2 letter code) [AU]:US
1798  State or Province Name (full name) [Some-State]:MyState
1799  Locality Name (eg, city) []:Some City
1800  Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
1801  Organizational Unit Name (eg, section) []:My Group
1802  Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
1803  Email Address []:ops@myserver.mygroup.myorganization.com
1804  %
1805
1806The disadvantage of a self-signed certificate is that it is its own root
1807certificate, and no one else will have it in their cache of known (and trusted)
1808root certificates.
1809
1810
1811Examples
1812--------
1813
1814Testing for SSL support
1815^^^^^^^^^^^^^^^^^^^^^^^
1816
1817To test for the presence of SSL support in a Python installation, user code
1818should use the following idiom::
1819
1820   try:
1821       import ssl
1822   except ImportError:
1823       pass
1824   else:
1825       ...  # do something that requires SSL support
1826
1827Client-side operation
1828^^^^^^^^^^^^^^^^^^^^^
1829
1830This example creates a SSL context with the recommended security settings
1831for client sockets, including automatic certificate verification::
1832
1833   >>> context = ssl.create_default_context()
1834
1835If you prefer to tune security settings yourself, you might create
1836a context from scratch (but beware that you might not get the settings
1837right)::
1838
1839   >>> context = ssl.SSLContext(ssl.PROTOCOL_TLS)
1840   >>> context.verify_mode = ssl.CERT_REQUIRED
1841   >>> context.check_hostname = True
1842   >>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
1843
1844(this snippet assumes your operating system places a bundle of all CA
1845certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an
1846error and have to adjust the location)
1847
1848When you use the context to connect to a server, :const:`CERT_REQUIRED`
1849validates the server certificate: it ensures that the server certificate
1850was signed with one of the CA certificates, and checks the signature for
1851correctness::
1852
1853   >>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
1854   ...                            server_hostname="www.python.org")
1855   >>> conn.connect(("www.python.org", 443))
1856
1857You may then fetch the certificate::
1858
1859   >>> cert = conn.getpeercert()
1860
1861Visual inspection shows that the certificate does identify the desired service
1862(that is, the HTTPS host ``www.python.org``)::
1863
1864   >>> pprint.pprint(cert)
1865   {'OCSP': ('http://ocsp.digicert.com',),
1866    'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
1867    'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
1868                              'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
1869    'issuer': ((('countryName', 'US'),),
1870               (('organizationName', 'DigiCert Inc'),),
1871               (('organizationalUnitName', 'www.digicert.com'),),
1872               (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
1873    'notAfter': 'Sep  9 12:00:00 2016 GMT',
1874    'notBefore': 'Sep  5 00:00:00 2014 GMT',
1875    'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
1876    'subject': ((('businessCategory', 'Private Organization'),),
1877                (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
1878                (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
1879                (('serialNumber', '3359300'),),
1880                (('streetAddress', '16 Allen Rd'),),
1881                (('postalCode', '03894-4801'),),
1882                (('countryName', 'US'),),
1883                (('stateOrProvinceName', 'NH'),),
1884                (('localityName', 'Wolfeboro,'),),
1885                (('organizationName', 'Python Software Foundation'),),
1886                (('commonName', 'www.python.org'),)),
1887    'subjectAltName': (('DNS', 'www.python.org'),
1888                       ('DNS', 'python.org'),
1889                       ('DNS', 'pypi.python.org'),
1890                       ('DNS', 'docs.python.org'),
1891                       ('DNS', 'testpypi.python.org'),
1892                       ('DNS', 'bugs.python.org'),
1893                       ('DNS', 'wiki.python.org'),
1894                       ('DNS', 'hg.python.org'),
1895                       ('DNS', 'mail.python.org'),
1896                       ('DNS', 'packaging.python.org'),
1897                       ('DNS', 'pythonhosted.org'),
1898                       ('DNS', 'www.pythonhosted.org'),
1899                       ('DNS', 'test.pythonhosted.org'),
1900                       ('DNS', 'us.pycon.org'),
1901                       ('DNS', 'id.python.org')),
1902    'version': 3}
1903
1904Now the SSL channel is established and the certificate verified, you can
1905proceed to talk with the server::
1906
1907   >>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
1908   >>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
1909   [b'HTTP/1.1 200 OK',
1910    b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
1911    b'Server: nginx',
1912    b'Content-Type: text/html; charset=utf-8',
1913    b'X-Frame-Options: SAMEORIGIN',
1914    b'Content-Length: 45679',
1915    b'Accept-Ranges: bytes',
1916    b'Via: 1.1 varnish',
1917    b'Age: 2188',
1918    b'X-Served-By: cache-lcy1134-LCY',
1919    b'X-Cache: HIT',
1920    b'X-Cache-Hits: 11',
1921    b'Vary: Cookie',
1922    b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
1923    b'Connection: close',
1924    b'',
1925    b'']
1926
1927See the discussion of :ref:`ssl-security` below.
1928
1929
1930Server-side operation
1931^^^^^^^^^^^^^^^^^^^^^
1932
1933For server operation, typically you'll need to have a server certificate, and
1934private key, each in a file.  You'll first create a context holding the key
1935and the certificate, so that clients can check your authenticity.  Then
1936you'll open a socket, bind it to a port, call :meth:`listen` on it, and start
1937waiting for clients to connect::
1938
1939   import socket, ssl
1940
1941   context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
1942   context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")
1943
1944   bindsocket = socket.socket()
1945   bindsocket.bind(('myaddr.mydomain.com', 10023))
1946   bindsocket.listen(5)
1947
1948When a client connects, you'll call :meth:`accept` on the socket to get the
1949new socket from the other end, and use the context's :meth:`SSLContext.wrap_socket`
1950method to create a server-side SSL socket for the connection::
1951
1952   while True:
1953       newsocket, fromaddr = bindsocket.accept()
1954       connstream = context.wrap_socket(newsocket, server_side=True)
1955       try:
1956           deal_with_client(connstream)
1957       finally:
1958           connstream.shutdown(socket.SHUT_RDWR)
1959           connstream.close()
1960
1961Then you'll read data from the ``connstream`` and do something with it till you
1962are finished with the client (or the client is finished with you)::
1963
1964   def deal_with_client(connstream):
1965       data = connstream.recv(1024)
1966       # empty data means the client is finished with us
1967       while data:
1968           if not do_something(connstream, data):
1969               # we'll assume do_something returns False
1970               # when we're finished with client
1971               break
1972           data = connstream.recv(1024)
1973       # finished with client
1974
1975And go back to listening for new client connections (of course, a real server
1976would probably handle each client connection in a separate thread, or put
1977the sockets in :ref:`non-blocking mode <ssl-nonblocking>` and use an event loop).
1978
1979
1980.. _ssl-nonblocking:
1981
1982Notes on non-blocking sockets
1983-----------------------------
1984
1985SSL sockets behave slightly different than regular sockets in
1986non-blocking mode. When working with non-blocking sockets, there are
1987thus several things you need to be aware of:
1988
1989- Most :class:`SSLSocket` methods will raise either
1990  :exc:`SSLWantWriteError` or :exc:`SSLWantReadError` instead of
1991  :exc:`BlockingIOError` if an I/O operation would
1992  block. :exc:`SSLWantReadError` will be raised if a read operation on
1993  the underlying socket is necessary, and :exc:`SSLWantWriteError` for
1994  a write operation on the underlying socket. Note that attempts to
1995  *write* to an SSL socket may require *reading* from the underlying
1996  socket first, and attempts to *read* from the SSL socket may require
1997  a prior *write* to the underlying socket.
1998
1999  .. versionchanged:: 3.5
2000
2001     In earlier Python versions, the :meth:`!SSLSocket.send` method
2002     returned zero instead of raising :exc:`SSLWantWriteError` or
2003     :exc:`SSLWantReadError`.
2004
2005- Calling :func:`~select.select` tells you that the OS-level socket can be
2006  read from (or written to), but it does not imply that there is sufficient
2007  data at the upper SSL layer.  For example, only part of an SSL frame might
2008  have arrived.  Therefore, you must be ready to handle :meth:`SSLSocket.recv`
2009  and :meth:`SSLSocket.send` failures, and retry after another call to
2010  :func:`~select.select`.
2011
2012- Conversely, since the SSL layer has its own framing, a SSL socket may
2013  still have data available for reading without :func:`~select.select`
2014  being aware of it.  Therefore, you should first call
2015  :meth:`SSLSocket.recv` to drain any potentially available data, and then
2016  only block on a :func:`~select.select` call if still necessary.
2017
2018  (of course, similar provisions apply when using other primitives such as
2019  :func:`~select.poll`, or those in the :mod:`selectors` module)
2020
2021- The SSL handshake itself will be non-blocking: the
2022  :meth:`SSLSocket.do_handshake` method has to be retried until it returns
2023  successfully.  Here is a synopsis using :func:`~select.select` to wait for
2024  the socket's readiness::
2025
2026    while True:
2027        try:
2028            sock.do_handshake()
2029            break
2030        except ssl.SSLWantReadError:
2031            select.select([sock], [], [])
2032        except ssl.SSLWantWriteError:
2033            select.select([], [sock], [])
2034
2035.. seealso::
2036
2037   The :mod:`asyncio` module supports :ref:`non-blocking SSL sockets
2038   <ssl-nonblocking>` and provides a
2039   higher level API. It polls for events using the :mod:`selectors` module and
2040   handles :exc:`SSLWantWriteError`, :exc:`SSLWantReadError` and
2041   :exc:`BlockingIOError` exceptions. It runs the SSL handshake asynchronously
2042   as well.
2043
2044
2045Memory BIO Support
2046------------------
2047
2048.. versionadded:: 3.5
2049
2050Ever since the SSL module was introduced in Python 2.6, the :class:`SSLSocket`
2051class has provided two related but distinct areas of functionality:
2052
2053- SSL protocol handling
2054- Network IO
2055
2056The network IO API is identical to that provided by :class:`socket.socket`,
2057from which :class:`SSLSocket` also inherits. This allows an SSL socket to be
2058used as a drop-in replacement for a regular socket, making it very easy to add
2059SSL support to an existing application.
2060
2061Combining SSL protocol handling and network IO usually works well, but there
2062are some cases where it doesn't. An example is async IO frameworks that want to
2063use a different IO multiplexing model than the "select/poll on a file
2064descriptor" (readiness based) model that is assumed by :class:`socket.socket`
2065and by the internal OpenSSL socket IO routines. This is mostly relevant for
2066platforms like Windows where this model is not efficient. For this purpose, a
2067reduced scope variant of :class:`SSLSocket` called :class:`SSLObject` is
2068provided.
2069
2070.. class:: SSLObject
2071
2072   A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol
2073   instance that does not contain any network IO methods. This class is
2074   typically used by framework authors that want to implement asynchronous IO
2075   for SSL through memory buffers.
2076
2077   This class implements an interface on top of a low-level SSL object as
2078   implemented by OpenSSL. This object captures the state of an SSL connection
2079   but does not provide any network IO itself. IO needs to be performed through
2080   separate "BIO" objects which are OpenSSL's IO abstraction layer.
2081
2082   An :class:`SSLObject` instance can be created using the
2083   :meth:`~SSLContext.wrap_bio` method. This method will create the
2084   :class:`SSLObject` instance and bind it to a pair of BIOs. The *incoming*
2085   BIO is used to pass data from Python to the SSL protocol instance, while the
2086   *outgoing* BIO is used to pass data the other way around.
2087
2088   The following methods are available:
2089
2090   - :attr:`~SSLSocket.context`
2091   - :attr:`~SSLSocket.server_side`
2092   - :attr:`~SSLSocket.server_hostname`
2093   - :attr:`~SSLSocket.session`
2094   - :attr:`~SSLSocket.session_reused`
2095   - :meth:`~SSLSocket.read`
2096   - :meth:`~SSLSocket.write`
2097   - :meth:`~SSLSocket.getpeercert`
2098   - :meth:`~SSLSocket.selected_npn_protocol`
2099   - :meth:`~SSLSocket.cipher`
2100   - :meth:`~SSLSocket.shared_ciphers`
2101   - :meth:`~SSLSocket.compression`
2102   - :meth:`~SSLSocket.pending`
2103   - :meth:`~SSLSocket.do_handshake`
2104   - :meth:`~SSLSocket.unwrap`
2105   - :meth:`~SSLSocket.get_channel_binding`
2106
2107   When compared to :class:`SSLSocket`, this object lacks the following
2108   features:
2109
2110   - Any form of network IO incluging methods such as ``recv()`` and
2111     ``send()``.
2112
2113   - There is no *do_handshake_on_connect* machinery. You must always manually
2114     call :meth:`~SSLSocket.do_handshake` to start the handshake.
2115
2116   - There is no handling of *suppress_ragged_eofs*. All end-of-file conditions
2117     that are in violation of the protocol are reported via the
2118     :exc:`SSLEOFError` exception.
2119
2120   - The method :meth:`~SSLSocket.unwrap` call does not return anything,
2121     unlike for an SSL socket where it returns the underlying socket.
2122
2123   - The *server_name_callback* callback passed to
2124     :meth:`SSLContext.set_servername_callback` will get an :class:`SSLObject`
2125     instance instead of a :class:`SSLSocket` instance as its first parameter.
2126
2127   Some notes related to the use of :class:`SSLObject`:
2128
2129   - All IO on an :class:`SSLObject` is :ref:`non-blocking <ssl-nonblocking>`.
2130     This means that for example :meth:`~SSLSocket.read` will raise an
2131     :exc:`SSLWantReadError` if it needs more data than the incoming BIO has
2132     available.
2133
2134   - There is no module-level ``wrap_bio()`` call like there is for
2135     :meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created
2136     via an :class:`SSLContext`.
2137
2138An SSLObject communicates with the outside world using memory buffers. The
2139class :class:`MemoryBIO` provides a memory buffer that can be used for this
2140purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:
2141
2142.. class:: MemoryBIO
2143
2144   A memory buffer that can be used to pass data between Python and an SSL
2145   protocol instance.
2146
2147   .. attribute:: MemoryBIO.pending
2148
2149      Return the number of bytes currently in the memory buffer.
2150
2151   .. attribute:: MemoryBIO.eof
2152
2153      A boolean indicating whether the memory BIO is current at the end-of-file
2154      position.
2155
2156   .. method:: MemoryBIO.read(n=-1)
2157
2158      Read up to *n* bytes from the memory buffer. If *n* is not specified or
2159      negative, all bytes are returned.
2160
2161   .. method:: MemoryBIO.write(buf)
2162
2163      Write the bytes from *buf* to the memory BIO. The *buf* argument must be an
2164      object supporting the buffer protocol.
2165
2166      The return value is the number of bytes written, which is always equal to
2167      the length of *buf*.
2168
2169   .. method:: MemoryBIO.write_eof()
2170
2171      Write an EOF marker to the memory BIO. After this method has been called, it
2172      is illegal to call :meth:`~MemoryBIO.write`. The attribute :attr:`eof` will
2173      become true after all data currently in the buffer has been read.
2174
2175
2176SSL session
2177-----------
2178
2179.. versionadded:: 3.6
2180
2181.. class:: SSLSession
2182
2183   Session object used by :attr:`~SSLSocket.session`.
2184
2185   .. attribute:: id
2186   .. attribute:: time
2187   .. attribute:: timeout
2188   .. attribute:: ticket_lifetime_hint
2189   .. attribute:: has_ticket
2190
2191
2192.. _ssl-security:
2193
2194Security considerations
2195-----------------------
2196
2197Best defaults
2198^^^^^^^^^^^^^
2199
2200For **client use**, if you don't have any special requirements for your
2201security policy, it is highly recommended that you use the
2202:func:`create_default_context` function to create your SSL context.
2203It will load the system's trusted CA certificates, enable certificate
2204validation and hostname checking, and try to choose reasonably secure
2205protocol and cipher settings.
2206
2207For example, here is how you would use the :class:`smtplib.SMTP` class to
2208create a trusted, secure connection to a SMTP server::
2209
2210   >>> import ssl, smtplib
2211   >>> smtp = smtplib.SMTP("mail.python.org", port=587)
2212   >>> context = ssl.create_default_context()
2213   >>> smtp.starttls(context=context)
2214   (220, b'2.0.0 Ready to start TLS')
2215
2216If a client certificate is needed for the connection, it can be added with
2217:meth:`SSLContext.load_cert_chain`.
2218
2219By contrast, if you create the SSL context by calling the :class:`SSLContext`
2220constructor yourself, it will not have certificate validation nor hostname
2221checking enabled by default.  If you do so, please read the paragraphs below
2222to achieve a good security level.
2223
2224Manual settings
2225^^^^^^^^^^^^^^^
2226
2227Verifying certificates
2228''''''''''''''''''''''
2229
2230When calling the :class:`SSLContext` constructor directly,
2231:const:`CERT_NONE` is the default.  Since it does not authenticate the other
2232peer, it can be insecure, especially in client mode where most of time you
2233would like to ensure the authenticity of the server you're talking to.
2234Therefore, when in client mode, it is highly recommended to use
2235:const:`CERT_REQUIRED`.  However, it is in itself not sufficient; you also
2236have to check that the server certificate, which can be obtained by calling
2237:meth:`SSLSocket.getpeercert`, matches the desired service.  For many
2238protocols and applications, the service can be identified by the hostname;
2239in this case, the :func:`match_hostname` function can be used.  This common
2240check is automatically performed when :attr:`SSLContext.check_hostname` is
2241enabled.
2242
2243In server mode, if you want to authenticate your clients using the SSL layer
2244(rather than using a higher-level authentication mechanism), you'll also have
2245to specify :const:`CERT_REQUIRED` and similarly check the client certificate.
2246
2247   .. note::
2248
2249      In client mode, :const:`CERT_OPTIONAL` and :const:`CERT_REQUIRED` are
2250      equivalent unless anonymous ciphers are enabled (they are disabled
2251      by default).
2252
2253Protocol versions
2254'''''''''''''''''
2255
2256SSL versions 2 and 3 are considered insecure and are therefore dangerous to
2257use.  If you want maximum compatibility between clients and servers, it is
2258recommended to use :const:`PROTOCOL_TLS_CLIENT` or
2259:const:`PROTOCOL_TLS_SERVER` as the protocol version. SSLv2 and SSLv3 are
2260disabled by default.
2261
2262   >>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
2263   >>> client_context.options |= ssl.OP_NO_TLSv1
2264   >>> client_context.options |= ssl.OP_NO_TLSv1_1
2265
2266
2267The SSL context created above will only allow TLSv1.2 and later (if
2268supported by your system) connections to a server. :const:`PROTOCOL_TLS_CLIENT`
2269implies certificate validation and hostname checks by default. You have to
2270load certificates into the context.
2271
2272
2273Cipher selection
2274''''''''''''''''
2275
2276If you have advanced security requirements, fine-tuning of the ciphers
2277enabled when negotiating a SSL session is possible through the
2278:meth:`SSLContext.set_ciphers` method.  Starting from Python 3.2.3, the
2279ssl module disables certain weak ciphers by default, but you may want
2280to further restrict the cipher choice. Be sure to read OpenSSL's documentation
2281about the `cipher list format <https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`_.
2282If you want to check which ciphers are enabled by a given cipher list, use
2283:meth:`SSLContext.get_ciphers` or the ``openssl ciphers`` command on your
2284system.
2285
2286Multi-processing
2287^^^^^^^^^^^^^^^^
2288
2289If using this module as part of a multi-processed application (using,
2290for example the :mod:`multiprocessing` or :mod:`concurrent.futures` modules),
2291be aware that OpenSSL's internal random number generator does not properly
2292handle forked processes.  Applications must change the PRNG state of the
2293parent process if they use any SSL feature with :func:`os.fork`.  Any
2294successful call of :func:`~ssl.RAND_add`, :func:`~ssl.RAND_bytes` or
2295:func:`~ssl.RAND_pseudo_bytes` is sufficient.
2296
2297
2298.. seealso::
2299
2300   Class :class:`socket.socket`
2301       Documentation of underlying :mod:`socket` class
2302
2303   `SSL/TLS Strong Encryption: An Introduction <https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html>`_
2304       Intro from the Apache webserver documentation
2305
2306   `RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management <https://www.ietf.org/rfc/rfc1422>`_
2307       Steve Kent
2308
2309   `RFC 1750: Randomness Recommendations for Security <https://www.ietf.org/rfc/rfc1750>`_
2310       D. Eastlake et. al.
2311
2312   `RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile <https://www.ietf.org/rfc/rfc3280>`_
2313       Housley et. al.
2314
2315   `RFC 4366: Transport Layer Security (TLS) Extensions <https://www.ietf.org/rfc/rfc4366>`_
2316       Blake-Wilson et. al.
2317
2318   `RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <https://tools.ietf.org/html/rfc5246>`_
2319       T. Dierks et. al.
2320
2321   `RFC 6066: Transport Layer Security (TLS) Extensions <https://tools.ietf.org/html/rfc6066>`_
2322       D. Eastlake
2323
2324   `IANA TLS: Transport Layer Security (TLS) Parameters <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_
2325       IANA
2326