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