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