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