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