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