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 strong 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:: HAS_ALPN 890 891 Whether the OpenSSL library has built-in support for the *Application-Layer 892 Protocol Negotiation* TLS extension as described in :rfc:`7301`. 893 894 .. versionadded:: 3.5 895 896.. data:: HAS_NEVER_CHECK_COMMON_NAME 897 898 Whether the OpenSSL library has built-in support not checking subject 899 common name and :attr:`SSLContext.hostname_checks_common_name` is 900 writeable. 901 902 .. versionadded:: 3.7 903 904.. data:: HAS_ECDH 905 906 Whether the OpenSSL library has built-in support for the Elliptic Curve-based 907 Diffie-Hellman key exchange. This should be true unless the feature was 908 explicitly disabled by the distributor. 909 910 .. versionadded:: 3.3 911 912.. data:: HAS_SNI 913 914 Whether the OpenSSL library has built-in support for the *Server Name 915 Indication* extension (as defined in :rfc:`6066`). 916 917 .. versionadded:: 3.2 918 919.. data:: HAS_NPN 920 921 Whether the OpenSSL library has built-in support for the *Next Protocol 922 Negotiation* as described in the `Application Layer Protocol 923 Negotiation <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_. 924 When true, you can use the :meth:`SSLContext.set_npn_protocols` method to advertise 925 which protocols you want to support. 926 927 .. versionadded:: 3.3 928 929.. data:: HAS_SSLv2 930 931 Whether the OpenSSL library has built-in support for the SSL 2.0 protocol. 932 933 .. versionadded:: 3.7 934 935.. data:: HAS_SSLv3 936 937 Whether the OpenSSL library has built-in support for the SSL 3.0 protocol. 938 939 .. versionadded:: 3.7 940 941.. data:: HAS_TLSv1 942 943 Whether the OpenSSL library has built-in support for the TLS 1.0 protocol. 944 945 .. versionadded:: 3.7 946 947.. data:: HAS_TLSv1_1 948 949 Whether the OpenSSL library has built-in support for the TLS 1.1 protocol. 950 951 .. versionadded:: 3.7 952 953.. data:: HAS_TLSv1_2 954 955 Whether the OpenSSL library has built-in support for the TLS 1.2 protocol. 956 957 .. versionadded:: 3.7 958 959.. data:: HAS_TLSv1_3 960 961 Whether the OpenSSL library has built-in support for the TLS 1.3 protocol. 962 963 .. versionadded:: 3.7 964 965.. data:: CHANNEL_BINDING_TYPES 966 967 List of supported TLS channel binding types. Strings in this list 968 can be used as arguments to :meth:`SSLSocket.get_channel_binding`. 969 970 .. versionadded:: 3.3 971 972.. data:: OPENSSL_VERSION 973 974 The version string of the OpenSSL library loaded by the interpreter:: 975 976 >>> ssl.OPENSSL_VERSION 977 'OpenSSL 1.0.2k 26 Jan 2017' 978 979 .. versionadded:: 3.2 980 981.. data:: OPENSSL_VERSION_INFO 982 983 A tuple of five integers representing version information about the 984 OpenSSL library:: 985 986 >>> ssl.OPENSSL_VERSION_INFO 987 (1, 0, 2, 11, 15) 988 989 .. versionadded:: 3.2 990 991.. data:: OPENSSL_VERSION_NUMBER 992 993 The raw version number of the OpenSSL library, as a single integer:: 994 995 >>> ssl.OPENSSL_VERSION_NUMBER 996 268443839 997 >>> hex(ssl.OPENSSL_VERSION_NUMBER) 998 '0x100020bf' 999 1000 .. versionadded:: 3.2 1001 1002.. data:: ALERT_DESCRIPTION_HANDSHAKE_FAILURE 1003 ALERT_DESCRIPTION_INTERNAL_ERROR 1004 ALERT_DESCRIPTION_* 1005 1006 Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry 1007 <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_ 1008 contains this list and references to the RFCs where their meaning is defined. 1009 1010 Used as the return value of the callback function in 1011 :meth:`SSLContext.set_servername_callback`. 1012 1013 .. versionadded:: 3.4 1014 1015.. class:: AlertDescription 1016 1017 :class:`enum.IntEnum` collection of ALERT_DESCRIPTION_* constants. 1018 1019 .. versionadded:: 3.6 1020 1021.. data:: Purpose.SERVER_AUTH 1022 1023 Option for :func:`create_default_context` and 1024 :meth:`SSLContext.load_default_certs`. This value indicates that the 1025 context may be used to authenticate Web servers (therefore, it will 1026 be used to create client-side sockets). 1027 1028 .. versionadded:: 3.4 1029 1030.. data:: Purpose.CLIENT_AUTH 1031 1032 Option for :func:`create_default_context` and 1033 :meth:`SSLContext.load_default_certs`. This value indicates that the 1034 context may be used to authenticate Web clients (therefore, it will 1035 be used to create server-side sockets). 1036 1037 .. versionadded:: 3.4 1038 1039.. class:: SSLErrorNumber 1040 1041 :class:`enum.IntEnum` collection of SSL_ERROR_* constants. 1042 1043 .. versionadded:: 3.6 1044 1045.. class:: TLSVersion 1046 1047 :class:`enum.IntEnum` collection of SSL and TLS versions for 1048 :attr:`SSLContext.maximum_version` and :attr:`SSLContext.minimum_version`. 1049 1050 .. versionadded:: 3.7 1051 1052.. attribute:: TLSVersion.MINIMUM_SUPPORTED 1053.. attribute:: TLSVersion.MAXIMUM_SUPPORTED 1054 1055 The minimum or maximum supported SSL or TLS version. These are magic 1056 constants. Their values don't reflect the lowest and highest available 1057 TLS/SSL versions. 1058 1059.. attribute:: TLSVersion.SSLv3 1060.. attribute:: TLSVersion.TLSv1 1061.. attribute:: TLSVersion.TLSv1_1 1062.. attribute:: TLSVersion.TLSv1_2 1063.. attribute:: TLSVersion.TLSv1_3 1064 1065 SSL 3.0 to TLS 1.3. 1066 1067 1068SSL Sockets 1069----------- 1070 1071.. class:: SSLSocket(socket.socket) 1072 1073 SSL sockets provide the following methods of :ref:`socket-objects`: 1074 1075 - :meth:`~socket.socket.accept()` 1076 - :meth:`~socket.socket.bind()` 1077 - :meth:`~socket.socket.close()` 1078 - :meth:`~socket.socket.connect()` 1079 - :meth:`~socket.socket.detach()` 1080 - :meth:`~socket.socket.fileno()` 1081 - :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()` 1082 - :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()` 1083 - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`, 1084 :meth:`~socket.socket.setblocking()` 1085 - :meth:`~socket.socket.listen()` 1086 - :meth:`~socket.socket.makefile()` 1087 - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()` 1088 (but passing a non-zero ``flags`` argument is not allowed) 1089 - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with 1090 the same limitation) 1091 - :meth:`~socket.socket.sendfile()` (but :mod:`os.sendfile` will be used 1092 for plain-text sockets only, else :meth:`~socket.socket.send()` will be used) 1093 - :meth:`~socket.socket.shutdown()` 1094 1095 However, since the SSL (and TLS) protocol has its own framing atop 1096 of TCP, the SSL sockets abstraction can, in certain respects, diverge from 1097 the specification of normal, OS-level sockets. See especially the 1098 :ref:`notes on non-blocking sockets <ssl-nonblocking>`. 1099 1100 Instances of :class:`SSLSocket` must be created using the 1101 :meth:`SSLContext.wrap_socket` method. 1102 1103 .. versionchanged:: 3.5 1104 The :meth:`sendfile` method was added. 1105 1106 .. versionchanged:: 3.5 1107 The :meth:`shutdown` does not reset the socket timeout each time bytes 1108 are received or sent. The socket timeout is now to maximum total duration 1109 of the shutdown. 1110 1111 .. deprecated:: 3.6 1112 It is deprecated to create a :class:`SSLSocket` instance directly, use 1113 :meth:`SSLContext.wrap_socket` to wrap a socket. 1114 1115 .. versionchanged:: 3.7 1116 :class:`SSLSocket` instances must to created with 1117 :meth:`~SSLContext.wrap_socket`. In earlier versions, it was possible 1118 to create instances directly. This was never documented or officially 1119 supported. 1120 1121SSL sockets also have the following additional methods and attributes: 1122 1123.. method:: SSLSocket.read(len=1024, buffer=None) 1124 1125 Read up to *len* bytes of data from the SSL socket and return the result as 1126 a ``bytes`` instance. If *buffer* is specified, then read into the buffer 1127 instead, and return the number of bytes read. 1128 1129 Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is 1130 :ref:`non-blocking <ssl-nonblocking>` and the read would block. 1131 1132 As at any time a re-negotiation is possible, a call to :meth:`read` can also 1133 cause write operations. 1134 1135 .. versionchanged:: 3.5 1136 The socket timeout is no more reset each time bytes are received or sent. 1137 The socket timeout is now to maximum total duration to read up to *len* 1138 bytes. 1139 1140 .. deprecated:: 3.6 1141 Use :meth:`~SSLSocket.recv` instead of :meth:`~SSLSocket.read`. 1142 1143.. method:: SSLSocket.write(buf) 1144 1145 Write *buf* to the SSL socket and return the number of bytes written. The 1146 *buf* argument must be an object supporting the buffer interface. 1147 1148 Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is 1149 :ref:`non-blocking <ssl-nonblocking>` and the write would block. 1150 1151 As at any time a re-negotiation is possible, a call to :meth:`write` can 1152 also cause read operations. 1153 1154 .. versionchanged:: 3.5 1155 The socket timeout is no more reset each time bytes are received or sent. 1156 The socket timeout is now to maximum total duration to write *buf*. 1157 1158 .. deprecated:: 3.6 1159 Use :meth:`~SSLSocket.send` instead of :meth:`~SSLSocket.write`. 1160 1161.. note:: 1162 1163 The :meth:`~SSLSocket.read` and :meth:`~SSLSocket.write` methods are the 1164 low-level methods that read and write unencrypted, application-level data 1165 and decrypt/encrypt it to encrypted, wire-level data. These methods 1166 require an active SSL connection, i.e. the handshake was completed and 1167 :meth:`SSLSocket.unwrap` was not called. 1168 1169 Normally you should use the socket API methods like 1170 :meth:`~socket.socket.recv` and :meth:`~socket.socket.send` instead of these 1171 methods. 1172 1173.. method:: SSLSocket.do_handshake() 1174 1175 Perform the SSL setup handshake. 1176 1177 .. versionchanged:: 3.4 1178 The handshake method also performs :func:`match_hostname` when the 1179 :attr:`~SSLContext.check_hostname` attribute of the socket's 1180 :attr:`~SSLSocket.context` is true. 1181 1182 .. versionchanged:: 3.5 1183 The socket timeout is no more reset each time bytes are received or sent. 1184 The socket timeout is now to maximum total duration of the handshake. 1185 1186 .. versionchanged:: 3.7 1187 Hostname or IP address is matched by OpenSSL during handshake. The 1188 function :func:`match_hostname` is no longer used. In case OpenSSL 1189 refuses a hostname or IP address, the handshake is aborted early and 1190 a TLS alert message is send to the peer. 1191 1192.. method:: SSLSocket.getpeercert(binary_form=False) 1193 1194 If there is no certificate for the peer on the other end of the connection, 1195 return ``None``. If the SSL handshake hasn't been done yet, raise 1196 :exc:`ValueError`. 1197 1198 If the ``binary_form`` parameter is :const:`False`, and a certificate was 1199 received from the peer, this method returns a :class:`dict` instance. If the 1200 certificate was not validated, the dict is empty. If the certificate was 1201 validated, it returns a dict with several keys, amongst them ``subject`` 1202 (the principal for which the certificate was issued) and ``issuer`` 1203 (the principal issuing the certificate). If a certificate contains an 1204 instance of the *Subject Alternative Name* extension (see :rfc:`3280`), 1205 there will also be a ``subjectAltName`` key in the dictionary. 1206 1207 The ``subject`` and ``issuer`` fields are tuples containing the sequence 1208 of relative distinguished names (RDNs) given in the certificate's data 1209 structure for the respective fields, and each RDN is a sequence of 1210 name-value pairs. Here is a real-world example:: 1211 1212 {'issuer': ((('countryName', 'IL'),), 1213 (('organizationName', 'StartCom Ltd.'),), 1214 (('organizationalUnitName', 1215 'Secure Digital Certificate Signing'),), 1216 (('commonName', 1217 'StartCom Class 2 Primary Intermediate Server CA'),)), 1218 'notAfter': 'Nov 22 08:15:19 2013 GMT', 1219 'notBefore': 'Nov 21 03:09:52 2011 GMT', 1220 'serialNumber': '95F0', 1221 'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),), 1222 (('countryName', 'US'),), 1223 (('stateOrProvinceName', 'California'),), 1224 (('localityName', 'San Francisco'),), 1225 (('organizationName', 'Electronic Frontier Foundation, Inc.'),), 1226 (('commonName', '*.eff.org'),), 1227 (('emailAddress', 'hostmaster@eff.org'),)), 1228 'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')), 1229 'version': 3} 1230 1231 .. note:: 1232 1233 To validate a certificate for a particular service, you can use the 1234 :func:`match_hostname` function. 1235 1236 If the ``binary_form`` parameter is :const:`True`, and a certificate was 1237 provided, this method returns the DER-encoded form of the entire certificate 1238 as a sequence of bytes, or :const:`None` if the peer did not provide a 1239 certificate. Whether the peer provides a certificate depends on the SSL 1240 socket's role: 1241 1242 * for a client SSL socket, the server will always provide a certificate, 1243 regardless of whether validation was required; 1244 1245 * for a server SSL socket, the client will only provide a certificate 1246 when requested by the server; therefore :meth:`getpeercert` will return 1247 :const:`None` if you used :const:`CERT_NONE` (rather than 1248 :const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`). 1249 1250 .. versionchanged:: 3.2 1251 The returned dictionary includes additional items such as ``issuer`` 1252 and ``notBefore``. 1253 1254 .. versionchanged:: 3.4 1255 :exc:`ValueError` is raised when the handshake isn't done. 1256 The returned dictionary includes additional X509v3 extension items 1257 such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs. 1258 1259 .. versionchanged:: 3.9 1260 IPv6 address strings no longer have a trailing new line. 1261 1262.. method:: SSLSocket.cipher() 1263 1264 Returns a three-value tuple containing the name of the cipher being used, the 1265 version of the SSL protocol that defines its use, and the number of secret 1266 bits being used. If no connection has been established, returns ``None``. 1267 1268.. method:: SSLSocket.shared_ciphers() 1269 1270 Return the list of ciphers shared by the client during the handshake. Each 1271 entry of the returned list is a three-value tuple containing the name of the 1272 cipher, the version of the SSL protocol that defines its use, and the number 1273 of secret bits the cipher uses. :meth:`~SSLSocket.shared_ciphers` returns 1274 ``None`` if no connection has been established or the socket is a client 1275 socket. 1276 1277 .. versionadded:: 3.5 1278 1279.. method:: SSLSocket.compression() 1280 1281 Return the compression algorithm being used as a string, or ``None`` 1282 if the connection isn't compressed. 1283 1284 If the higher-level protocol supports its own compression mechanism, 1285 you can use :data:`OP_NO_COMPRESSION` to disable SSL-level compression. 1286 1287 .. versionadded:: 3.3 1288 1289.. method:: SSLSocket.get_channel_binding(cb_type="tls-unique") 1290 1291 Get channel binding data for current connection, as a bytes object. Returns 1292 ``None`` if not connected or the handshake has not been completed. 1293 1294 The *cb_type* parameter allow selection of the desired channel binding 1295 type. Valid channel binding types are listed in the 1296 :data:`CHANNEL_BINDING_TYPES` list. Currently only the 'tls-unique' channel 1297 binding, defined by :rfc:`5929`, is supported. :exc:`ValueError` will be 1298 raised if an unsupported channel binding type is requested. 1299 1300 .. versionadded:: 3.3 1301 1302.. method:: SSLSocket.selected_alpn_protocol() 1303 1304 Return the protocol that was selected during the TLS handshake. If 1305 :meth:`SSLContext.set_alpn_protocols` was not called, if the other party does 1306 not support ALPN, if this socket does not support any of the client's 1307 proposed protocols, or if the handshake has not happened yet, ``None`` is 1308 returned. 1309 1310 .. versionadded:: 3.5 1311 1312.. method:: SSLSocket.selected_npn_protocol() 1313 1314 Return the higher-level protocol that was selected during the TLS/SSL 1315 handshake. If :meth:`SSLContext.set_npn_protocols` was not called, or 1316 if the other party does not support NPN, or if the handshake has not yet 1317 happened, this will return ``None``. 1318 1319 .. versionadded:: 3.3 1320 1321.. method:: SSLSocket.unwrap() 1322 1323 Performs the SSL shutdown handshake, which removes the TLS layer from the 1324 underlying socket, and returns the underlying socket object. This can be 1325 used to go from encrypted operation over a connection to unencrypted. The 1326 returned socket should always be used for further communication with the 1327 other side of the connection, rather than the original socket. 1328 1329.. method:: SSLSocket.verify_client_post_handshake() 1330 1331 Requests post-handshake authentication (PHA) from a TLS 1.3 client. PHA 1332 can only be initiated for a TLS 1.3 connection from a server-side socket, 1333 after the initial TLS handshake and with PHA enabled on both sides, see 1334 :attr:`SSLContext.post_handshake_auth`. 1335 1336 The method does not perform a cert exchange immediately. The server-side 1337 sends a CertificateRequest during the next write event and expects the 1338 client to respond with a certificate on the next read event. 1339 1340 If any precondition isn't met (e.g. not TLS 1.3, PHA not enabled), an 1341 :exc:`SSLError` is raised. 1342 1343 .. note:: 1344 Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3 1345 support, the method raises :exc:`NotImplementedError`. 1346 1347 .. versionadded:: 3.8 1348 1349.. method:: SSLSocket.version() 1350 1351 Return the actual SSL protocol version negotiated by the connection 1352 as a string, or ``None`` is no secure connection is established. 1353 As of this writing, possible return values include ``"SSLv2"``, 1354 ``"SSLv3"``, ``"TLSv1"``, ``"TLSv1.1"`` and ``"TLSv1.2"``. 1355 Recent OpenSSL versions may define more return values. 1356 1357 .. versionadded:: 3.5 1358 1359.. method:: SSLSocket.pending() 1360 1361 Returns the number of already decrypted bytes available for read, pending on 1362 the connection. 1363 1364.. attribute:: SSLSocket.context 1365 1366 The :class:`SSLContext` object this SSL socket is tied to. If the SSL 1367 socket was created using the deprecated :func:`wrap_socket` function 1368 (rather than :meth:`SSLContext.wrap_socket`), this is a custom context 1369 object created for this SSL socket. 1370 1371 .. versionadded:: 3.2 1372 1373.. attribute:: SSLSocket.server_side 1374 1375 A boolean which is ``True`` for server-side sockets and ``False`` for 1376 client-side sockets. 1377 1378 .. versionadded:: 3.2 1379 1380.. attribute:: SSLSocket.server_hostname 1381 1382 Hostname of the server: :class:`str` type, or ``None`` for server-side 1383 socket or if the hostname was not specified in the constructor. 1384 1385 .. versionadded:: 3.2 1386 1387 .. versionchanged:: 3.7 1388 The attribute is now always ASCII text. When ``server_hostname`` is 1389 an internationalized domain name (IDN), this attribute now stores the 1390 A-label form (``"xn--pythn-mua.org"``), rather than the U-label form 1391 (``"pythön.org"``). 1392 1393.. attribute:: SSLSocket.session 1394 1395 The :class:`SSLSession` for this SSL connection. The session is available 1396 for client and server side sockets after the TLS handshake has been 1397 performed. For client sockets the session can be set before 1398 :meth:`~SSLSocket.do_handshake` has been called to reuse a session. 1399 1400 .. versionadded:: 3.6 1401 1402.. attribute:: SSLSocket.session_reused 1403 1404 .. versionadded:: 3.6 1405 1406 1407SSL Contexts 1408------------ 1409 1410.. versionadded:: 3.2 1411 1412An SSL context holds various data longer-lived than single SSL connections, 1413such as SSL configuration options, certificate(s) and private key(s). 1414It also manages a cache of SSL sessions for server-side sockets, in order 1415to speed up repeated connections from the same clients. 1416 1417.. class:: SSLContext(protocol=PROTOCOL_TLS) 1418 1419 Create a new SSL context. You may pass *protocol* which must be one 1420 of the ``PROTOCOL_*`` constants defined in this module. The parameter 1421 specifies which version of the SSL protocol to use. Typically, the 1422 server chooses a particular protocol version, and the client must adapt 1423 to the server's choice. Most of the versions are not interoperable 1424 with the other versions. If not specified, the default is 1425 :data:`PROTOCOL_TLS`; it provides the most compatibility with other 1426 versions. 1427 1428 Here's a table showing which versions in a client (down the side) can connect 1429 to which versions in a server (along the top): 1430 1431 .. table:: 1432 1433 ======================== ============ ============ ============= ========= =========== =========== 1434 *client* / **server** **SSLv2** **SSLv3** **TLS** [3]_ **TLSv1** **TLSv1.1** **TLSv1.2** 1435 ------------------------ ------------ ------------ ------------- --------- ----------- ----------- 1436 *SSLv2* yes no no [1]_ no no no 1437 *SSLv3* no yes no [2]_ no no no 1438 *TLS* (*SSLv23*) [3]_ no [1]_ no [2]_ yes yes yes yes 1439 *TLSv1* no no yes yes no no 1440 *TLSv1.1* no no yes no yes no 1441 *TLSv1.2* no no yes no no yes 1442 ======================== ============ ============ ============= ========= =========== =========== 1443 1444 .. rubric:: Footnotes 1445 .. [1] :class:`SSLContext` disables SSLv2 with :data:`OP_NO_SSLv2` by default. 1446 .. [2] :class:`SSLContext` disables SSLv3 with :data:`OP_NO_SSLv3` by default. 1447 .. [3] TLS 1.3 protocol will be available with :data:`PROTOCOL_TLS` in 1448 OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just 1449 TLS 1.3. 1450 1451 .. seealso:: 1452 :func:`create_default_context` lets the :mod:`ssl` module choose 1453 security settings for a given purpose. 1454 1455 .. versionchanged:: 3.6 1456 1457 The context is created with secure default values. The options 1458 :data:`OP_NO_COMPRESSION`, :data:`OP_CIPHER_SERVER_PREFERENCE`, 1459 :data:`OP_SINGLE_DH_USE`, :data:`OP_SINGLE_ECDH_USE`, 1460 :data:`OP_NO_SSLv2` (except for :data:`PROTOCOL_SSLv2`), 1461 and :data:`OP_NO_SSLv3` (except for :data:`PROTOCOL_SSLv3`) are 1462 set by default. The initial cipher suite list contains only ``HIGH`` 1463 ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for 1464 :data:`PROTOCOL_SSLv2`). 1465 1466 1467:class:`SSLContext` objects have the following methods and attributes: 1468 1469.. method:: SSLContext.cert_store_stats() 1470 1471 Get statistics about quantities of loaded X.509 certificates, count of 1472 X.509 certificates flagged as CA certificates and certificate revocation 1473 lists as dictionary. 1474 1475 Example for a context with one CA cert and one other cert:: 1476 1477 >>> context.cert_store_stats() 1478 {'crl': 0, 'x509_ca': 1, 'x509': 2} 1479 1480 .. versionadded:: 3.4 1481 1482 1483.. method:: SSLContext.load_cert_chain(certfile, keyfile=None, password=None) 1484 1485 Load a private key and the corresponding certificate. The *certfile* 1486 string must be the path to a single file in PEM format containing the 1487 certificate as well as any number of CA certificates needed to establish 1488 the certificate's authenticity. The *keyfile* string, if present, must 1489 point to a file containing the private key in. Otherwise the private 1490 key will be taken from *certfile* as well. See the discussion of 1491 :ref:`ssl-certificates` for more information on how the certificate 1492 is stored in the *certfile*. 1493 1494 The *password* argument may be a function to call to get the password for 1495 decrypting the private key. It will only be called if the private key is 1496 encrypted and a password is necessary. It will be called with no arguments, 1497 and it should return a string, bytes, or bytearray. If the return value is 1498 a string it will be encoded as UTF-8 before using it to decrypt the key. 1499 Alternatively a string, bytes, or bytearray value may be supplied directly 1500 as the *password* argument. It will be ignored if the private key is not 1501 encrypted and no password is needed. 1502 1503 If the *password* argument is not specified and a password is required, 1504 OpenSSL's built-in password prompting mechanism will be used to 1505 interactively prompt the user for a password. 1506 1507 An :class:`SSLError` is raised if the private key doesn't 1508 match with the certificate. 1509 1510 .. versionchanged:: 3.3 1511 New optional argument *password*. 1512 1513.. method:: SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH) 1514 1515 Load a set of default "certification authority" (CA) certificates from 1516 default locations. On Windows it loads CA certs from the ``CA`` and 1517 ``ROOT`` system stores. On other systems it calls 1518 :meth:`SSLContext.set_default_verify_paths`. In the future the method may 1519 load CA certificates from other locations, too. 1520 1521 The *purpose* flag specifies what kind of CA certificates are loaded. The 1522 default settings :data:`Purpose.SERVER_AUTH` loads certificates, that are 1523 flagged and trusted for TLS web server authentication (client side 1524 sockets). :data:`Purpose.CLIENT_AUTH` loads CA certificates for client 1525 certificate verification on the server side. 1526 1527 .. versionadded:: 3.4 1528 1529.. method:: SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None) 1530 1531 Load a set of "certification authority" (CA) certificates used to validate 1532 other peers' certificates when :data:`verify_mode` is other than 1533 :data:`CERT_NONE`. At least one of *cafile* or *capath* must be specified. 1534 1535 This method can also load certification revocation lists (CRLs) in PEM or 1536 DER format. In order to make use of CRLs, :attr:`SSLContext.verify_flags` 1537 must be configured properly. 1538 1539 The *cafile* string, if present, is the path to a file of concatenated 1540 CA certificates in PEM format. See the discussion of 1541 :ref:`ssl-certificates` for more information about how to arrange the 1542 certificates in this file. 1543 1544 The *capath* string, if present, is 1545 the path to a directory containing several CA certificates in PEM format, 1546 following an `OpenSSL specific layout 1547 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_load_verify_locations.html>`_. 1548 1549 The *cadata* object, if present, is either an ASCII string of one or more 1550 PEM-encoded certificates or a :term:`bytes-like object` of DER-encoded 1551 certificates. Like with *capath* extra lines around PEM-encoded 1552 certificates are ignored but at least one certificate must be present. 1553 1554 .. versionchanged:: 3.4 1555 New optional argument *cadata* 1556 1557.. method:: SSLContext.get_ca_certs(binary_form=False) 1558 1559 Get a list of loaded "certification authority" (CA) certificates. If the 1560 ``binary_form`` parameter is :const:`False` each list 1561 entry is a dict like the output of :meth:`SSLSocket.getpeercert`. Otherwise 1562 the method returns a list of DER-encoded certificates. The returned list 1563 does not contain certificates from *capath* unless a certificate was 1564 requested and loaded by a SSL connection. 1565 1566 .. note:: 1567 Certificates in a capath directory aren't loaded unless they have 1568 been used at least once. 1569 1570 .. versionadded:: 3.4 1571 1572.. method:: SSLContext.get_ciphers() 1573 1574 Get a list of enabled ciphers. The list is in order of cipher priority. 1575 See :meth:`SSLContext.set_ciphers`. 1576 1577 Example:: 1578 1579 >>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23) 1580 >>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA') 1581 >>> ctx.get_ciphers() # OpenSSL 1.0.x 1582 [{'alg_bits': 256, 1583 'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA ' 1584 'Enc=AESGCM(256) Mac=AEAD', 1585 'id': 50380848, 1586 'name': 'ECDHE-RSA-AES256-GCM-SHA384', 1587 'protocol': 'TLSv1/SSLv3', 1588 'strength_bits': 256}, 1589 {'alg_bits': 128, 1590 'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA ' 1591 'Enc=AESGCM(128) Mac=AEAD', 1592 'id': 50380847, 1593 'name': 'ECDHE-RSA-AES128-GCM-SHA256', 1594 'protocol': 'TLSv1/SSLv3', 1595 'strength_bits': 128}] 1596 1597 On OpenSSL 1.1 and newer the cipher dict contains additional fields:: 1598 1599 >>> ctx.get_ciphers() # OpenSSL 1.1+ 1600 [{'aead': True, 1601 'alg_bits': 256, 1602 'auth': 'auth-rsa', 1603 'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH Au=RSA ' 1604 'Enc=AESGCM(256) Mac=AEAD', 1605 'digest': None, 1606 'id': 50380848, 1607 'kea': 'kx-ecdhe', 1608 'name': 'ECDHE-RSA-AES256-GCM-SHA384', 1609 'protocol': 'TLSv1.2', 1610 'strength_bits': 256, 1611 'symmetric': 'aes-256-gcm'}, 1612 {'aead': True, 1613 'alg_bits': 128, 1614 'auth': 'auth-rsa', 1615 'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA ' 1616 'Enc=AESGCM(128) Mac=AEAD', 1617 'digest': None, 1618 'id': 50380847, 1619 'kea': 'kx-ecdhe', 1620 'name': 'ECDHE-RSA-AES128-GCM-SHA256', 1621 'protocol': 'TLSv1.2', 1622 'strength_bits': 128, 1623 'symmetric': 'aes-128-gcm'}] 1624 1625 .. availability:: OpenSSL 1.0.2+. 1626 1627 .. versionadded:: 3.6 1628 1629.. method:: SSLContext.set_default_verify_paths() 1630 1631 Load a set of default "certification authority" (CA) certificates from 1632 a filesystem path defined when building the OpenSSL library. Unfortunately, 1633 there's no easy way to know whether this method succeeds: no error is 1634 returned if no certificates are to be found. When the OpenSSL library is 1635 provided as part of the operating system, though, it is likely to be 1636 configured properly. 1637 1638.. method:: SSLContext.set_ciphers(ciphers) 1639 1640 Set the available ciphers for sockets created with this context. 1641 It should be a string in the `OpenSSL cipher list format 1642 <https://www.openssl.org/docs/manmaster/man1/ciphers.html>`_. 1643 If no cipher can be selected (because compile-time options or other 1644 configuration forbids use of all the specified ciphers), an 1645 :class:`SSLError` will be raised. 1646 1647 .. note:: 1648 when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will 1649 give the currently selected cipher. 1650 1651 OpenSSL 1.1.1 has TLS 1.3 cipher suites enabled by default. The suites 1652 cannot be disabled with :meth:`~SSLContext.set_ciphers`. 1653 1654.. method:: SSLContext.set_alpn_protocols(protocols) 1655 1656 Specify which protocols the socket should advertise during the SSL/TLS 1657 handshake. It should be a list of ASCII strings, like ``['http/1.1', 1658 'spdy/2']``, ordered by preference. The selection of a protocol will happen 1659 during the handshake, and will play out according to :rfc:`7301`. After a 1660 successful handshake, the :meth:`SSLSocket.selected_alpn_protocol` method will 1661 return the agreed-upon protocol. 1662 1663 This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is 1664 ``False``. 1665 1666 OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise :exc:`SSLError` 1667 when both sides support ALPN but cannot agree on a protocol. 1.1.0f+ 1668 behaves like 1.0.2, :meth:`SSLSocket.selected_alpn_protocol` returns None. 1669 1670 .. versionadded:: 3.5 1671 1672.. method:: SSLContext.set_npn_protocols(protocols) 1673 1674 Specify which protocols the socket should advertise during the SSL/TLS 1675 handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``, 1676 ordered by preference. The selection of a protocol will happen during the 1677 handshake, and will play out according to the `Application Layer Protocol Negotiation 1678 <https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation>`_. After a 1679 successful handshake, the :meth:`SSLSocket.selected_npn_protocol` method will 1680 return the agreed-upon protocol. 1681 1682 This method will raise :exc:`NotImplementedError` if :data:`HAS_NPN` is 1683 ``False``. 1684 1685 .. versionadded:: 3.3 1686 1687.. attribute:: SSLContext.sni_callback 1688 1689 Register a callback function that will be called after the TLS Client Hello 1690 handshake message has been received by the SSL/TLS server when the TLS client 1691 specifies a server name indication. The server name indication mechanism 1692 is specified in :rfc:`6066` section 3 - Server Name Indication. 1693 1694 Only one callback can be set per ``SSLContext``. If *sni_callback* 1695 is set to ``None`` then the callback is disabled. Calling this function a 1696 subsequent time will disable the previously registered callback. 1697 1698 The callback function will be called with three 1699 arguments; the first being the :class:`ssl.SSLSocket`, the second is a string 1700 that represents the server name that the client is intending to communicate 1701 (or :const:`None` if the TLS Client Hello does not contain a server name) 1702 and the third argument is the original :class:`SSLContext`. The server name 1703 argument is text. For internationalized domain name, the server 1704 name is an IDN A-label (``"xn--pythn-mua.org"``). 1705 1706 A typical use of this callback is to change the :class:`ssl.SSLSocket`'s 1707 :attr:`SSLSocket.context` attribute to a new object of type 1708 :class:`SSLContext` representing a certificate chain that matches the server 1709 name. 1710 1711 Due to the early negotiation phase of the TLS connection, only limited 1712 methods and attributes are usable like 1713 :meth:`SSLSocket.selected_alpn_protocol` and :attr:`SSLSocket.context`. 1714 :meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.getpeercert`, 1715 :meth:`SSLSocket.cipher` and :meth:`SSLSocket.compress` methods require that 1716 the TLS connection has progressed beyond the TLS Client Hello and therefore 1717 will not contain return meaningful values nor can they be called safely. 1718 1719 The *sni_callback* function must return ``None`` to allow the 1720 TLS negotiation to continue. If a TLS failure is required, a constant 1721 :const:`ALERT_DESCRIPTION_* <ALERT_DESCRIPTION_INTERNAL_ERROR>` can be 1722 returned. Other return values will result in a TLS fatal error with 1723 :const:`ALERT_DESCRIPTION_INTERNAL_ERROR`. 1724 1725 If an exception is raised from the *sni_callback* function the TLS 1726 connection will terminate with a fatal TLS alert message 1727 :const:`ALERT_DESCRIPTION_HANDSHAKE_FAILURE`. 1728 1729 This method will raise :exc:`NotImplementedError` if the OpenSSL library 1730 had OPENSSL_NO_TLSEXT defined when it was built. 1731 1732 .. versionadded:: 3.7 1733 1734.. attribute:: SSLContext.set_servername_callback(server_name_callback) 1735 1736 This is a legacy API retained for backwards compatibility. When possible, 1737 you should use :attr:`sni_callback` instead. The given *server_name_callback* 1738 is similar to *sni_callback*, except that when the server hostname is an 1739 IDN-encoded internationalized domain name, the *server_name_callback* 1740 receives a decoded U-label (``"pythön.org"``). 1741 1742 If there is an decoding error on the server name, the TLS connection will 1743 terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS 1744 alert message to the client. 1745 1746 .. versionadded:: 3.4 1747 1748.. method:: SSLContext.load_dh_params(dhfile) 1749 1750 Load the key generation parameters for Diffie-Hellman (DH) key exchange. 1751 Using DH key exchange improves forward secrecy at the expense of 1752 computational resources (both on the server and on the client). 1753 The *dhfile* parameter should be the path to a file containing DH 1754 parameters in PEM format. 1755 1756 This setting doesn't apply to client sockets. You can also use the 1757 :data:`OP_SINGLE_DH_USE` option to further improve security. 1758 1759 .. versionadded:: 3.3 1760 1761.. method:: SSLContext.set_ecdh_curve(curve_name) 1762 1763 Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key 1764 exchange. ECDH is significantly faster than regular DH while arguably 1765 as secure. The *curve_name* parameter should be a string describing 1766 a well-known elliptic curve, for example ``prime256v1`` for a widely 1767 supported curve. 1768 1769 This setting doesn't apply to client sockets. You can also use the 1770 :data:`OP_SINGLE_ECDH_USE` option to further improve security. 1771 1772 This method is not available if :data:`HAS_ECDH` is ``False``. 1773 1774 .. versionadded:: 3.3 1775 1776 .. seealso:: 1777 `SSL/TLS & Perfect Forward Secrecy <https://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-secrecy>`_ 1778 Vincent Bernat. 1779 1780.. method:: SSLContext.wrap_socket(sock, server_side=False, \ 1781 do_handshake_on_connect=True, suppress_ragged_eofs=True, \ 1782 server_hostname=None, session=None) 1783 1784 Wrap an existing Python socket *sock* and return an instance of 1785 :attr:`SSLContext.sslsocket_class` (default :class:`SSLSocket`). The 1786 returned SSL socket is tied to the context, its settings and certificates. 1787 *sock* must be a :data:`~socket.SOCK_STREAM` socket; other 1788 socket types are unsupported. 1789 1790 The parameter ``server_side`` is a boolean which identifies whether 1791 server-side or client-side behavior is desired from this socket. 1792 1793 For client-side sockets, the context construction is lazy; if the 1794 underlying socket isn't connected yet, the context construction will be 1795 performed after :meth:`connect` is called on the socket. For 1796 server-side sockets, if the socket has no remote peer, it is assumed 1797 to be a listening socket, and the server-side SSL wrapping is 1798 automatically performed on client connections accepted via the 1799 :meth:`accept` method. The method may raise :exc:`SSLError`. 1800 1801 On client connections, the optional parameter *server_hostname* specifies 1802 the hostname of the service which we are connecting to. This allows a 1803 single server to host multiple SSL-based services with distinct certificates, 1804 quite similarly to HTTP virtual hosts. Specifying *server_hostname* will 1805 raise a :exc:`ValueError` if *server_side* is true. 1806 1807 The parameter ``do_handshake_on_connect`` specifies whether to do the SSL 1808 handshake automatically after doing a :meth:`socket.connect`, or whether the 1809 application program will call it explicitly, by invoking the 1810 :meth:`SSLSocket.do_handshake` method. Calling 1811 :meth:`SSLSocket.do_handshake` explicitly gives the program control over the 1812 blocking behavior of the socket I/O involved in the handshake. 1813 1814 The parameter ``suppress_ragged_eofs`` specifies how the 1815 :meth:`SSLSocket.recv` method should signal unexpected EOF from the other end 1816 of the connection. If specified as :const:`True` (the default), it returns a 1817 normal EOF (an empty bytes object) in response to unexpected EOF errors 1818 raised from the underlying socket; if :const:`False`, it will raise the 1819 exceptions back to the caller. 1820 1821 *session*, see :attr:`~SSLSocket.session`. 1822 1823 .. versionchanged:: 3.5 1824 Always allow a server_hostname to be passed, even if OpenSSL does not 1825 have SNI. 1826 1827 .. versionchanged:: 3.6 1828 *session* argument was added. 1829 1830 .. versionchanged:: 3.7 1831 The method returns on instance of :attr:`SSLContext.sslsocket_class` 1832 instead of hard-coded :class:`SSLSocket`. 1833 1834.. attribute:: SSLContext.sslsocket_class 1835 1836 The return type of :meth:`SSLContext.wrap_socket`, defaults to 1837 :class:`SSLSocket`. The attribute can be overridden on instance of class 1838 in order to return a custom subclass of :class:`SSLSocket`. 1839 1840 .. versionadded:: 3.7 1841 1842.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \ 1843 server_hostname=None, session=None) 1844 1845 Wrap the BIO objects *incoming* and *outgoing* and return an instance of 1846 :attr:`SSLContext.sslobject_class` (default :class:`SSLObject`). The SSL 1847 routines will read input data from the incoming BIO and write data to the 1848 outgoing BIO. 1849 1850 The *server_side*, *server_hostname* and *session* parameters have the 1851 same meaning as in :meth:`SSLContext.wrap_socket`. 1852 1853 .. versionchanged:: 3.6 1854 *session* argument was added. 1855 1856 .. versionchanged:: 3.7 1857 The method returns on instance of :attr:`SSLContext.sslobject_class` 1858 instead of hard-coded :class:`SSLObject`. 1859 1860.. attribute:: SSLContext.sslobject_class 1861 1862 The return type of :meth:`SSLContext.wrap_bio`, defaults to 1863 :class:`SSLObject`. The attribute can be overridden on instance of class 1864 in order to return a custom subclass of :class:`SSLObject`. 1865 1866 .. versionadded:: 3.7 1867 1868.. method:: SSLContext.session_stats() 1869 1870 Get statistics about the SSL sessions created or managed by this context. 1871 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 1872 numeric values. For example, here is the total number of hits and misses 1873 in the session cache since the context was created:: 1874 1875 >>> stats = context.session_stats() 1876 >>> stats['hits'], stats['misses'] 1877 (0, 0) 1878 1879.. attribute:: SSLContext.check_hostname 1880 1881 Whether to match the peer cert's hostname with :func:`match_hostname` in 1882 :meth:`SSLSocket.do_handshake`. The context's 1883 :attr:`~SSLContext.verify_mode` must be set to :data:`CERT_OPTIONAL` or 1884 :data:`CERT_REQUIRED`, and you must pass *server_hostname* to 1885 :meth:`~SSLContext.wrap_socket` in order to match the hostname. Enabling 1886 hostname checking automatically sets :attr:`~SSLContext.verify_mode` from 1887 :data:`CERT_NONE` to :data:`CERT_REQUIRED`. It cannot be set back to 1888 :data:`CERT_NONE` as long as hostname checking is enabled. The 1889 :data:`PROTOCOL_TLS_CLIENT` protocol enables hostname checking by default. 1890 With other protocols, hostname checking must be enabled explicitly. 1891 1892 Example:: 1893 1894 import socket, ssl 1895 1896 context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2) 1897 context.verify_mode = ssl.CERT_REQUIRED 1898 context.check_hostname = True 1899 context.load_default_certs() 1900 1901 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) 1902 ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com') 1903 ssl_sock.connect(('www.verisign.com', 443)) 1904 1905 .. versionadded:: 3.4 1906 1907 .. versionchanged:: 3.7 1908 1909 :attr:`~SSLContext.verify_mode` is now automatically changed 1910 to :data:`CERT_REQUIRED` when hostname checking is enabled and 1911 :attr:`~SSLContext.verify_mode` is :data:`CERT_NONE`. Previously 1912 the same operation would have failed with a :exc:`ValueError`. 1913 1914 .. note:: 1915 1916 This features requires OpenSSL 0.9.8f or newer. 1917 1918.. attribute:: SSLContext.keylog_filename 1919 1920 Write TLS keys to a keylog file, whenever key material is generated or 1921 received. The keylog file is designed for debugging purposes only. The 1922 file format is specified by NSS and used by many traffic analyzers such 1923 as Wireshark. The log file is opened in append-only mode. Writes are 1924 synchronized between threads, but not between processes. 1925 1926 .. versionadded:: 3.8 1927 1928 .. note:: 1929 1930 This features requires OpenSSL 1.1.1 or newer. 1931 1932.. attribute:: SSLContext.maximum_version 1933 1934 A :class:`TLSVersion` enum member representing the highest supported 1935 TLS version. The value defaults to :attr:`TLSVersion.MAXIMUM_SUPPORTED`. 1936 The attribute is read-only for protocols other than :attr:`PROTOCOL_TLS`, 1937 :attr:`PROTOCOL_TLS_CLIENT`, and :attr:`PROTOCOL_TLS_SERVER`. 1938 1939 The attributes :attr:`~SSLContext.maximum_version`, 1940 :attr:`~SSLContext.minimum_version` and 1941 :attr:`SSLContext.options` all affect the supported SSL 1942 and TLS versions of the context. The implementation does not prevent 1943 invalid combination. For example a context with 1944 :attr:`OP_NO_TLSv1_2` in :attr:`~SSLContext.options` and 1945 :attr:`~SSLContext.maximum_version` set to :attr:`TLSVersion.TLSv1_2` 1946 will not be able to establish a TLS 1.2 connection. 1947 1948 .. note:: 1949 1950 This attribute is not available unless the ssl module is compiled 1951 with OpenSSL 1.1.0g or newer. 1952 1953 .. versionadded:: 3.7 1954 1955.. attribute:: SSLContext.minimum_version 1956 1957 Like :attr:`SSLContext.maximum_version` except it is the lowest 1958 supported version or :attr:`TLSVersion.MINIMUM_SUPPORTED`. 1959 1960 .. note:: 1961 1962 This attribute is not available unless the ssl module is compiled 1963 with OpenSSL 1.1.0g or newer. 1964 1965 .. versionadded:: 3.7 1966 1967.. attribute:: SSLContext.num_tickets 1968 1969 Control the number of TLS 1.3 session tickets of a 1970 :attr:`TLS_PROTOCOL_SERVER` context. The setting has no impact on TLS 1971 1.0 to 1.2 connections. 1972 1973 .. note:: 1974 1975 This attribute is not available unless the ssl module is compiled 1976 with OpenSSL 1.1.1 or newer. 1977 1978 .. versionadded:: 3.8 1979 1980.. attribute:: SSLContext.options 1981 1982 An integer representing the set of SSL options enabled on this context. 1983 The default value is :data:`OP_ALL`, but you can specify other options 1984 such as :data:`OP_NO_SSLv2` by ORing them together. 1985 1986 .. note:: 1987 With versions of OpenSSL older than 0.9.8m, it is only possible 1988 to set options, not to clear them. Attempting to clear an option 1989 (by resetting the corresponding bits) will raise a :exc:`ValueError`. 1990 1991 .. versionchanged:: 3.6 1992 :attr:`SSLContext.options` returns :class:`Options` flags: 1993 1994 >>> ssl.create_default_context().options # doctest: +SKIP 1995 <Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391> 1996 1997.. attribute:: SSLContext.post_handshake_auth 1998 1999 Enable TLS 1.3 post-handshake client authentication. Post-handshake auth 2000 is disabled by default and a server can only request a TLS client 2001 certificate during the initial handshake. When enabled, a server may 2002 request a TLS client certificate at any time after the handshake. 2003 2004 When enabled on client-side sockets, the client signals the server that 2005 it supports post-handshake authentication. 2006 2007 When enabled on server-side sockets, :attr:`SSLContext.verify_mode` must 2008 be set to :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`, too. The 2009 actual client cert exchange is delayed until 2010 :meth:`SSLSocket.verify_client_post_handshake` is called and some I/O is 2011 performed. 2012 2013 .. note:: 2014 Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3 2015 support, the property value is None and can't be modified 2016 2017 .. versionadded:: 3.8 2018 2019.. attribute:: SSLContext.protocol 2020 2021 The protocol version chosen when constructing the context. This attribute 2022 is read-only. 2023 2024.. attribute:: SSLContext.hostname_checks_common_name 2025 2026 Whether :attr:`~SSLContext.check_hostname` falls back to verify the cert's 2027 subject common name in the absence of a subject alternative name 2028 extension (default: true). 2029 2030 .. note:: 2031 Only writeable with OpenSSL 1.1.0 or higher. 2032 2033 .. versionadded:: 3.7 2034 2035.. attribute:: SSLContext.verify_flags 2036 2037 The flags for certificate verification operations. You can set flags like 2038 :data:`VERIFY_CRL_CHECK_LEAF` by ORing them together. By default OpenSSL 2039 does neither require nor verify certificate revocation lists (CRLs). 2040 Available only with openssl version 0.9.8+. 2041 2042 .. versionadded:: 3.4 2043 2044 .. versionchanged:: 3.6 2045 :attr:`SSLContext.verify_flags` returns :class:`VerifyFlags` flags: 2046 2047 >>> ssl.create_default_context().verify_flags # doctest: +SKIP 2048 <VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768> 2049 2050.. attribute:: SSLContext.verify_mode 2051 2052 Whether to try to verify other peers' certificates and how to behave 2053 if verification fails. This attribute must be one of 2054 :data:`CERT_NONE`, :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`. 2055 2056 .. versionchanged:: 3.6 2057 :attr:`SSLContext.verify_mode` returns :class:`VerifyMode` enum: 2058 2059 >>> ssl.create_default_context().verify_mode 2060 <VerifyMode.CERT_REQUIRED: 2> 2061 2062.. index:: single: certificates 2063 2064.. index:: single: X509 certificate 2065 2066.. _ssl-certificates: 2067 2068Certificates 2069------------ 2070 2071Certificates in general are part of a public-key / private-key system. In this 2072system, each *principal*, (which may be a machine, or a person, or an 2073organization) is assigned a unique two-part encryption key. One part of the key 2074is public, and is called the *public key*; the other part is kept secret, and is 2075called the *private key*. The two parts are related, in that if you encrypt a 2076message with one of the parts, you can decrypt it with the other part, and 2077**only** with the other part. 2078 2079A certificate contains information about two principals. It contains the name 2080of a *subject*, and the subject's public key. It also contains a statement by a 2081second principal, the *issuer*, that the subject is who they claim to be, and 2082that this is indeed the subject's public key. The issuer's statement is signed 2083with the issuer's private key, which only the issuer knows. However, anyone can 2084verify the issuer's statement by finding the issuer's public key, decrypting the 2085statement with it, and comparing it to the other information in the certificate. 2086The certificate also contains information about the time period over which it is 2087valid. This is expressed as two fields, called "notBefore" and "notAfter". 2088 2089In the Python use of certificates, a client or server can use a certificate to 2090prove who they are. The other side of a network connection can also be required 2091to produce a certificate, and that certificate can be validated to the 2092satisfaction of the client or server that requires such validation. The 2093connection attempt can be set to raise an exception if the validation fails. 2094Validation is done automatically, by the underlying OpenSSL framework; the 2095application need not concern itself with its mechanics. But the application 2096does usually need to provide sets of certificates to allow this process to take 2097place. 2098 2099Python uses files to contain certificates. They should be formatted as "PEM" 2100(see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line 2101and a footer line:: 2102 2103 -----BEGIN CERTIFICATE----- 2104 ... (certificate in base64 PEM encoding) ... 2105 -----END CERTIFICATE----- 2106 2107Certificate chains 2108^^^^^^^^^^^^^^^^^^ 2109 2110The Python files which contain certificates can contain a sequence of 2111certificates, sometimes called a *certificate chain*. This chain should start 2112with the specific certificate for the principal who "is" the client or server, 2113and then the certificate for the issuer of that certificate, and then the 2114certificate for the issuer of *that* certificate, and so on up the chain till 2115you get to a certificate which is *self-signed*, that is, a certificate which 2116has the same subject and issuer, sometimes called a *root certificate*. The 2117certificates should just be concatenated together in the certificate file. For 2118example, suppose we had a three certificate chain, from our server certificate 2119to the certificate of the certification authority that signed our server 2120certificate, to the root certificate of the agency which issued the 2121certification authority's certificate:: 2122 2123 -----BEGIN CERTIFICATE----- 2124 ... (certificate for your server)... 2125 -----END CERTIFICATE----- 2126 -----BEGIN CERTIFICATE----- 2127 ... (the certificate for the CA)... 2128 -----END CERTIFICATE----- 2129 -----BEGIN CERTIFICATE----- 2130 ... (the root certificate for the CA's issuer)... 2131 -----END CERTIFICATE----- 2132 2133CA certificates 2134^^^^^^^^^^^^^^^ 2135 2136If you are going to require validation of the other side of the connection's 2137certificate, you need to provide a "CA certs" file, filled with the certificate 2138chains for each issuer you are willing to trust. Again, this file just contains 2139these chains concatenated together. For validation, Python will use the first 2140chain it finds in the file which matches. The platform's certificates file can 2141be used by calling :meth:`SSLContext.load_default_certs`, this is done 2142automatically with :func:`.create_default_context`. 2143 2144Combined key and certificate 2145^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2146 2147Often the private key is stored in the same file as the certificate; in this 2148case, only the ``certfile`` parameter to :meth:`SSLContext.load_cert_chain` 2149and :func:`wrap_socket` needs to be passed. If the private key is stored 2150with the certificate, it should come before the first certificate in 2151the certificate chain:: 2152 2153 -----BEGIN RSA PRIVATE KEY----- 2154 ... (private key in base64 encoding) ... 2155 -----END RSA PRIVATE KEY----- 2156 -----BEGIN CERTIFICATE----- 2157 ... (certificate in base64 PEM encoding) ... 2158 -----END CERTIFICATE----- 2159 2160Self-signed certificates 2161^^^^^^^^^^^^^^^^^^^^^^^^ 2162 2163If you are going to create a server that provides SSL-encrypted connection 2164services, you will need to acquire a certificate for that service. There are 2165many ways of acquiring appropriate certificates, such as buying one from a 2166certification authority. Another common practice is to generate a self-signed 2167certificate. The simplest way to do this is with the OpenSSL package, using 2168something like the following:: 2169 2170 % openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem 2171 Generating a 1024 bit RSA private key 2172 .......++++++ 2173 .............................++++++ 2174 writing new private key to 'cert.pem' 2175 ----- 2176 You are about to be asked to enter information that will be incorporated 2177 into your certificate request. 2178 What you are about to enter is what is called a Distinguished Name or a DN. 2179 There are quite a few fields but you can leave some blank 2180 For some fields there will be a default value, 2181 If you enter '.', the field will be left blank. 2182 ----- 2183 Country Name (2 letter code) [AU]:US 2184 State or Province Name (full name) [Some-State]:MyState 2185 Locality Name (eg, city) []:Some City 2186 Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc. 2187 Organizational Unit Name (eg, section) []:My Group 2188 Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com 2189 Email Address []:ops@myserver.mygroup.myorganization.com 2190 % 2191 2192The disadvantage of a self-signed certificate is that it is its own root 2193certificate, and no one else will have it in their cache of known (and trusted) 2194root certificates. 2195 2196 2197Examples 2198-------- 2199 2200Testing for SSL support 2201^^^^^^^^^^^^^^^^^^^^^^^ 2202 2203To test for the presence of SSL support in a Python installation, user code 2204should use the following idiom:: 2205 2206 try: 2207 import ssl 2208 except ImportError: 2209 pass 2210 else: 2211 ... # do something that requires SSL support 2212 2213Client-side operation 2214^^^^^^^^^^^^^^^^^^^^^ 2215 2216This example creates a SSL context with the recommended security settings 2217for client sockets, including automatic certificate verification:: 2218 2219 >>> context = ssl.create_default_context() 2220 2221If you prefer to tune security settings yourself, you might create 2222a context from scratch (but beware that you might not get the settings 2223right):: 2224 2225 >>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) 2226 >>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt") 2227 2228(this snippet assumes your operating system places a bundle of all CA 2229certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an 2230error and have to adjust the location) 2231 2232The :data:`PROTOCOL_TLS_CLIENT` protocol configures the context for cert 2233validation and hostname verification. :attr:`~SSLContext.verify_mode` is 2234set to :data:`CERT_REQUIRED` and :attr:`~SSLContext.check_hostname` is set 2235to ``True``. All other protocols create SSL contexts with insecure defaults. 2236 2237When you use the context to connect to a server, :const:`CERT_REQUIRED` 2238and :attr:`~SSLContext.check_hostname` validate the server certificate: it 2239ensures that the server certificate was signed with one of the CA 2240certificates, checks the signature for correctness, and verifies other 2241properties like validity and identity of the hostname:: 2242 2243 >>> conn = context.wrap_socket(socket.socket(socket.AF_INET), 2244 ... server_hostname="www.python.org") 2245 >>> conn.connect(("www.python.org", 443)) 2246 2247You may then fetch the certificate:: 2248 2249 >>> cert = conn.getpeercert() 2250 2251Visual inspection shows that the certificate does identify the desired service 2252(that is, the HTTPS host ``www.python.org``):: 2253 2254 >>> pprint.pprint(cert) 2255 {'OCSP': ('http://ocsp.digicert.com',), 2256 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',), 2257 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl', 2258 'http://crl4.digicert.com/sha2-ev-server-g1.crl'), 2259 'issuer': ((('countryName', 'US'),), 2260 (('organizationName', 'DigiCert Inc'),), 2261 (('organizationalUnitName', 'www.digicert.com'),), 2262 (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)), 2263 'notAfter': 'Sep 9 12:00:00 2016 GMT', 2264 'notBefore': 'Sep 5 00:00:00 2014 GMT', 2265 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26', 2266 'subject': ((('businessCategory', 'Private Organization'),), 2267 (('1.3.6.1.4.1.311.60.2.1.3', 'US'),), 2268 (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),), 2269 (('serialNumber', '3359300'),), 2270 (('streetAddress', '16 Allen Rd'),), 2271 (('postalCode', '03894-4801'),), 2272 (('countryName', 'US'),), 2273 (('stateOrProvinceName', 'NH'),), 2274 (('localityName', 'Wolfeboro'),), 2275 (('organizationName', 'Python Software Foundation'),), 2276 (('commonName', 'www.python.org'),)), 2277 'subjectAltName': (('DNS', 'www.python.org'), 2278 ('DNS', 'python.org'), 2279 ('DNS', 'pypi.org'), 2280 ('DNS', 'docs.python.org'), 2281 ('DNS', 'testpypi.org'), 2282 ('DNS', 'bugs.python.org'), 2283 ('DNS', 'wiki.python.org'), 2284 ('DNS', 'hg.python.org'), 2285 ('DNS', 'mail.python.org'), 2286 ('DNS', 'packaging.python.org'), 2287 ('DNS', 'pythonhosted.org'), 2288 ('DNS', 'www.pythonhosted.org'), 2289 ('DNS', 'test.pythonhosted.org'), 2290 ('DNS', 'us.pycon.org'), 2291 ('DNS', 'id.python.org')), 2292 'version': 3} 2293 2294Now the SSL channel is established and the certificate verified, you can 2295proceed to talk with the server:: 2296 2297 >>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n") 2298 >>> pprint.pprint(conn.recv(1024).split(b"\r\n")) 2299 [b'HTTP/1.1 200 OK', 2300 b'Date: Sat, 18 Oct 2014 18:27:20 GMT', 2301 b'Server: nginx', 2302 b'Content-Type: text/html; charset=utf-8', 2303 b'X-Frame-Options: SAMEORIGIN', 2304 b'Content-Length: 45679', 2305 b'Accept-Ranges: bytes', 2306 b'Via: 1.1 varnish', 2307 b'Age: 2188', 2308 b'X-Served-By: cache-lcy1134-LCY', 2309 b'X-Cache: HIT', 2310 b'X-Cache-Hits: 11', 2311 b'Vary: Cookie', 2312 b'Strict-Transport-Security: max-age=63072000; includeSubDomains', 2313 b'Connection: close', 2314 b'', 2315 b''] 2316 2317See the discussion of :ref:`ssl-security` below. 2318 2319 2320Server-side operation 2321^^^^^^^^^^^^^^^^^^^^^ 2322 2323For server operation, typically you'll need to have a server certificate, and 2324private key, each in a file. You'll first create a context holding the key 2325and the certificate, so that clients can check your authenticity. Then 2326you'll open a socket, bind it to a port, call :meth:`listen` on it, and start 2327waiting for clients to connect:: 2328 2329 import socket, ssl 2330 2331 context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) 2332 context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile") 2333 2334 bindsocket = socket.socket() 2335 bindsocket.bind(('myaddr.mydomain.com', 10023)) 2336 bindsocket.listen(5) 2337 2338When a client connects, you'll call :meth:`accept` on the socket to get the 2339new socket from the other end, and use the context's :meth:`SSLContext.wrap_socket` 2340method to create a server-side SSL socket for the connection:: 2341 2342 while True: 2343 newsocket, fromaddr = bindsocket.accept() 2344 connstream = context.wrap_socket(newsocket, server_side=True) 2345 try: 2346 deal_with_client(connstream) 2347 finally: 2348 connstream.shutdown(socket.SHUT_RDWR) 2349 connstream.close() 2350 2351Then you'll read data from the ``connstream`` and do something with it till you 2352are finished with the client (or the client is finished with you):: 2353 2354 def deal_with_client(connstream): 2355 data = connstream.recv(1024) 2356 # empty data means the client is finished with us 2357 while data: 2358 if not do_something(connstream, data): 2359 # we'll assume do_something returns False 2360 # when we're finished with client 2361 break 2362 data = connstream.recv(1024) 2363 # finished with client 2364 2365And go back to listening for new client connections (of course, a real server 2366would probably handle each client connection in a separate thread, or put 2367the sockets in :ref:`non-blocking mode <ssl-nonblocking>` and use an event loop). 2368 2369 2370.. _ssl-nonblocking: 2371 2372Notes on non-blocking sockets 2373----------------------------- 2374 2375SSL sockets behave slightly different than regular sockets in 2376non-blocking mode. When working with non-blocking sockets, there are 2377thus several things you need to be aware of: 2378 2379- Most :class:`SSLSocket` methods will raise either 2380 :exc:`SSLWantWriteError` or :exc:`SSLWantReadError` instead of 2381 :exc:`BlockingIOError` if an I/O operation would 2382 block. :exc:`SSLWantReadError` will be raised if a read operation on 2383 the underlying socket is necessary, and :exc:`SSLWantWriteError` for 2384 a write operation on the underlying socket. Note that attempts to 2385 *write* to an SSL socket may require *reading* from the underlying 2386 socket first, and attempts to *read* from the SSL socket may require 2387 a prior *write* to the underlying socket. 2388 2389 .. versionchanged:: 3.5 2390 2391 In earlier Python versions, the :meth:`!SSLSocket.send` method 2392 returned zero instead of raising :exc:`SSLWantWriteError` or 2393 :exc:`SSLWantReadError`. 2394 2395- Calling :func:`~select.select` tells you that the OS-level socket can be 2396 read from (or written to), but it does not imply that there is sufficient 2397 data at the upper SSL layer. For example, only part of an SSL frame might 2398 have arrived. Therefore, you must be ready to handle :meth:`SSLSocket.recv` 2399 and :meth:`SSLSocket.send` failures, and retry after another call to 2400 :func:`~select.select`. 2401 2402- Conversely, since the SSL layer has its own framing, a SSL socket may 2403 still have data available for reading without :func:`~select.select` 2404 being aware of it. Therefore, you should first call 2405 :meth:`SSLSocket.recv` to drain any potentially available data, and then 2406 only block on a :func:`~select.select` call if still necessary. 2407 2408 (of course, similar provisions apply when using other primitives such as 2409 :func:`~select.poll`, or those in the :mod:`selectors` module) 2410 2411- The SSL handshake itself will be non-blocking: the 2412 :meth:`SSLSocket.do_handshake` method has to be retried until it returns 2413 successfully. Here is a synopsis using :func:`~select.select` to wait for 2414 the socket's readiness:: 2415 2416 while True: 2417 try: 2418 sock.do_handshake() 2419 break 2420 except ssl.SSLWantReadError: 2421 select.select([sock], [], []) 2422 except ssl.SSLWantWriteError: 2423 select.select([], [sock], []) 2424 2425.. seealso:: 2426 2427 The :mod:`asyncio` module supports :ref:`non-blocking SSL sockets 2428 <ssl-nonblocking>` and provides a 2429 higher level API. It polls for events using the :mod:`selectors` module and 2430 handles :exc:`SSLWantWriteError`, :exc:`SSLWantReadError` and 2431 :exc:`BlockingIOError` exceptions. It runs the SSL handshake asynchronously 2432 as well. 2433 2434 2435Memory BIO Support 2436------------------ 2437 2438.. versionadded:: 3.5 2439 2440Ever since the SSL module was introduced in Python 2.6, the :class:`SSLSocket` 2441class has provided two related but distinct areas of functionality: 2442 2443- SSL protocol handling 2444- Network IO 2445 2446The network IO API is identical to that provided by :class:`socket.socket`, 2447from which :class:`SSLSocket` also inherits. This allows an SSL socket to be 2448used as a drop-in replacement for a regular socket, making it very easy to add 2449SSL support to an existing application. 2450 2451Combining SSL protocol handling and network IO usually works well, but there 2452are some cases where it doesn't. An example is async IO frameworks that want to 2453use a different IO multiplexing model than the "select/poll on a file 2454descriptor" (readiness based) model that is assumed by :class:`socket.socket` 2455and by the internal OpenSSL socket IO routines. This is mostly relevant for 2456platforms like Windows where this model is not efficient. For this purpose, a 2457reduced scope variant of :class:`SSLSocket` called :class:`SSLObject` is 2458provided. 2459 2460.. class:: SSLObject 2461 2462 A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol 2463 instance that does not contain any network IO methods. This class is 2464 typically used by framework authors that want to implement asynchronous IO 2465 for SSL through memory buffers. 2466 2467 This class implements an interface on top of a low-level SSL object as 2468 implemented by OpenSSL. This object captures the state of an SSL connection 2469 but does not provide any network IO itself. IO needs to be performed through 2470 separate "BIO" objects which are OpenSSL's IO abstraction layer. 2471 2472 This class has no public constructor. An :class:`SSLObject` instance 2473 must be created using the :meth:`~SSLContext.wrap_bio` method. This 2474 method will create the :class:`SSLObject` instance and bind it to a 2475 pair of BIOs. The *incoming* BIO is used to pass data from Python to the 2476 SSL protocol instance, while the *outgoing* BIO is used to pass data the 2477 other way around. 2478 2479 The following methods are available: 2480 2481 - :attr:`~SSLSocket.context` 2482 - :attr:`~SSLSocket.server_side` 2483 - :attr:`~SSLSocket.server_hostname` 2484 - :attr:`~SSLSocket.session` 2485 - :attr:`~SSLSocket.session_reused` 2486 - :meth:`~SSLSocket.read` 2487 - :meth:`~SSLSocket.write` 2488 - :meth:`~SSLSocket.getpeercert` 2489 - :meth:`~SSLSocket.selected_alpn_protocol` 2490 - :meth:`~SSLSocket.selected_npn_protocol` 2491 - :meth:`~SSLSocket.cipher` 2492 - :meth:`~SSLSocket.shared_ciphers` 2493 - :meth:`~SSLSocket.compression` 2494 - :meth:`~SSLSocket.pending` 2495 - :meth:`~SSLSocket.do_handshake` 2496 - :meth:`~SSLSocket.verify_client_post_handshake` 2497 - :meth:`~SSLSocket.unwrap` 2498 - :meth:`~SSLSocket.get_channel_binding` 2499 - :meth:`~SSLSocket.version` 2500 2501 When compared to :class:`SSLSocket`, this object lacks the following 2502 features: 2503 2504 - Any form of network IO; ``recv()`` and ``send()`` read and write only to 2505 the underlying :class:`MemoryBIO` buffers. 2506 2507 - There is no *do_handshake_on_connect* machinery. You must always manually 2508 call :meth:`~SSLSocket.do_handshake` to start the handshake. 2509 2510 - There is no handling of *suppress_ragged_eofs*. All end-of-file conditions 2511 that are in violation of the protocol are reported via the 2512 :exc:`SSLEOFError` exception. 2513 2514 - The method :meth:`~SSLSocket.unwrap` call does not return anything, 2515 unlike for an SSL socket where it returns the underlying socket. 2516 2517 - The *server_name_callback* callback passed to 2518 :meth:`SSLContext.set_servername_callback` will get an :class:`SSLObject` 2519 instance instead of a :class:`SSLSocket` instance as its first parameter. 2520 2521 Some notes related to the use of :class:`SSLObject`: 2522 2523 - All IO on an :class:`SSLObject` is :ref:`non-blocking <ssl-nonblocking>`. 2524 This means that for example :meth:`~SSLSocket.read` will raise an 2525 :exc:`SSLWantReadError` if it needs more data than the incoming BIO has 2526 available. 2527 2528 - There is no module-level ``wrap_bio()`` call like there is for 2529 :meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created 2530 via an :class:`SSLContext`. 2531 2532 .. versionchanged:: 3.7 2533 :class:`SSLObject` instances must to created with 2534 :meth:`~SSLContext.wrap_bio`. In earlier versions, it was possible to 2535 create instances directly. This was never documented or officially 2536 supported. 2537 2538An SSLObject communicates with the outside world using memory buffers. The 2539class :class:`MemoryBIO` provides a memory buffer that can be used for this 2540purpose. It wraps an OpenSSL memory BIO (Basic IO) object: 2541 2542.. class:: MemoryBIO 2543 2544 A memory buffer that can be used to pass data between Python and an SSL 2545 protocol instance. 2546 2547 .. attribute:: MemoryBIO.pending 2548 2549 Return the number of bytes currently in the memory buffer. 2550 2551 .. attribute:: MemoryBIO.eof 2552 2553 A boolean indicating whether the memory BIO is current at the end-of-file 2554 position. 2555 2556 .. method:: MemoryBIO.read(n=-1) 2557 2558 Read up to *n* bytes from the memory buffer. If *n* is not specified or 2559 negative, all bytes are returned. 2560 2561 .. method:: MemoryBIO.write(buf) 2562 2563 Write the bytes from *buf* to the memory BIO. The *buf* argument must be an 2564 object supporting the buffer protocol. 2565 2566 The return value is the number of bytes written, which is always equal to 2567 the length of *buf*. 2568 2569 .. method:: MemoryBIO.write_eof() 2570 2571 Write an EOF marker to the memory BIO. After this method has been called, it 2572 is illegal to call :meth:`~MemoryBIO.write`. The attribute :attr:`eof` will 2573 become true after all data currently in the buffer has been read. 2574 2575 2576SSL session 2577----------- 2578 2579.. versionadded:: 3.6 2580 2581.. class:: SSLSession 2582 2583 Session object used by :attr:`~SSLSocket.session`. 2584 2585 .. attribute:: id 2586 .. attribute:: time 2587 .. attribute:: timeout 2588 .. attribute:: ticket_lifetime_hint 2589 .. attribute:: has_ticket 2590 2591 2592.. _ssl-security: 2593 2594Security considerations 2595----------------------- 2596 2597Best defaults 2598^^^^^^^^^^^^^ 2599 2600For **client use**, if you don't have any special requirements for your 2601security policy, it is highly recommended that you use the 2602:func:`create_default_context` function to create your SSL context. 2603It will load the system's trusted CA certificates, enable certificate 2604validation and hostname checking, and try to choose reasonably secure 2605protocol and cipher settings. 2606 2607For example, here is how you would use the :class:`smtplib.SMTP` class to 2608create a trusted, secure connection to a SMTP server:: 2609 2610 >>> import ssl, smtplib 2611 >>> smtp = smtplib.SMTP("mail.python.org", port=587) 2612 >>> context = ssl.create_default_context() 2613 >>> smtp.starttls(context=context) 2614 (220, b'2.0.0 Ready to start TLS') 2615 2616If a client certificate is needed for the connection, it can be added with 2617:meth:`SSLContext.load_cert_chain`. 2618 2619By contrast, if you create the SSL context by calling the :class:`SSLContext` 2620constructor yourself, it will not have certificate validation nor hostname 2621checking enabled by default. If you do so, please read the paragraphs below 2622to achieve a good security level. 2623 2624Manual settings 2625^^^^^^^^^^^^^^^ 2626 2627Verifying certificates 2628'''''''''''''''''''''' 2629 2630When calling the :class:`SSLContext` constructor directly, 2631:const:`CERT_NONE` is the default. Since it does not authenticate the other 2632peer, it can be insecure, especially in client mode where most of time you 2633would like to ensure the authenticity of the server you're talking to. 2634Therefore, when in client mode, it is highly recommended to use 2635:const:`CERT_REQUIRED`. However, it is in itself not sufficient; you also 2636have to check that the server certificate, which can be obtained by calling 2637:meth:`SSLSocket.getpeercert`, matches the desired service. For many 2638protocols and applications, the service can be identified by the hostname; 2639in this case, the :func:`match_hostname` function can be used. This common 2640check is automatically performed when :attr:`SSLContext.check_hostname` is 2641enabled. 2642 2643.. versionchanged:: 3.7 2644 Hostname matchings is now performed by OpenSSL. Python no longer uses 2645 :func:`match_hostname`. 2646 2647In server mode, if you want to authenticate your clients using the SSL layer 2648(rather than using a higher-level authentication mechanism), you'll also have 2649to specify :const:`CERT_REQUIRED` and similarly check the client certificate. 2650 2651 2652Protocol versions 2653''''''''''''''''' 2654 2655SSL versions 2 and 3 are considered insecure and are therefore dangerous to 2656use. If you want maximum compatibility between clients and servers, it is 2657recommended to use :const:`PROTOCOL_TLS_CLIENT` or 2658:const:`PROTOCOL_TLS_SERVER` as the protocol version. SSLv2 and SSLv3 are 2659disabled by default. 2660 2661:: 2662 2663 >>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT) 2664 >>> client_context.options |= ssl.OP_NO_TLSv1 2665 >>> client_context.options |= ssl.OP_NO_TLSv1_1 2666 2667 2668The SSL context created above will only allow TLSv1.2 and later (if 2669supported by your system) connections to a server. :const:`PROTOCOL_TLS_CLIENT` 2670implies certificate validation and hostname checks by default. You have to 2671load certificates into the context. 2672 2673 2674Cipher selection 2675'''''''''''''''' 2676 2677If you have advanced security requirements, fine-tuning of the ciphers 2678enabled when negotiating a SSL session is possible through the 2679:meth:`SSLContext.set_ciphers` method. Starting from Python 3.2.3, the 2680ssl module disables certain weak ciphers by default, but you may want 2681to further restrict the cipher choice. Be sure to read OpenSSL's documentation 2682about the `cipher list format <https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`_. 2683If you want to check which ciphers are enabled by a given cipher list, use 2684:meth:`SSLContext.get_ciphers` or the ``openssl ciphers`` command on your 2685system. 2686 2687Multi-processing 2688^^^^^^^^^^^^^^^^ 2689 2690If using this module as part of a multi-processed application (using, 2691for example the :mod:`multiprocessing` or :mod:`concurrent.futures` modules), 2692be aware that OpenSSL's internal random number generator does not properly 2693handle forked processes. Applications must change the PRNG state of the 2694parent process if they use any SSL feature with :func:`os.fork`. Any 2695successful call of :func:`~ssl.RAND_add`, :func:`~ssl.RAND_bytes` or 2696:func:`~ssl.RAND_pseudo_bytes` is sufficient. 2697 2698 2699.. _ssl-tlsv1_3: 2700 2701TLS 1.3 2702------- 2703 2704.. versionadded:: 3.7 2705 2706Python has provisional and experimental support for TLS 1.3 with OpenSSL 27071.1.1. The new protocol behaves slightly differently than previous version 2708of TLS/SSL. Some new TLS 1.3 features are not yet available. 2709 2710- TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM and 2711 ChaCha20 cipher suites are enabled by default. The method 2712 :meth:`SSLContext.set_ciphers` cannot enable or disable any TLS 1.3 2713 ciphers yet, but :meth:`SSLContext.get_ciphers` returns them. 2714- Session tickets are no longer sent as part of the initial handshake and 2715 are handled differently. :attr:`SSLSocket.session` and :class:`SSLSession` 2716 are not compatible with TLS 1.3. 2717- Client-side certificates are also no longer verified during the initial 2718 handshake. A server can request a certificate at any time. Clients 2719 process certificate requests while they send or receive application data 2720 from the server. 2721- TLS 1.3 features like early data, deferred TLS client cert request, 2722 signature algorithm configuration, and rekeying are not supported yet. 2723 2724 2725.. _ssl-libressl: 2726 2727LibreSSL support 2728---------------- 2729 2730LibreSSL is a fork of OpenSSL 1.0.1. The ssl module has limited support for 2731LibreSSL. Some features are not available when the ssl module is compiled 2732with LibreSSL. 2733 2734* LibreSSL >= 2.6.1 no longer supports NPN. The methods 2735 :meth:`SSLContext.set_npn_protocols` and 2736 :meth:`SSLSocket.selected_npn_protocol` are not available. 2737* :meth:`SSLContext.set_default_verify_paths` ignores the env vars 2738 :envvar:`SSL_CERT_FILE` and :envvar:`SSL_CERT_PATH` although 2739 :func:`get_default_verify_paths` still reports them. 2740 2741 2742.. seealso:: 2743 2744 Class :class:`socket.socket` 2745 Documentation of underlying :mod:`socket` class 2746 2747 `SSL/TLS Strong Encryption: An Introduction <https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html>`_ 2748 Intro from the Apache HTTP Server documentation 2749 2750 :rfc:`RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management <1422>` 2751 Steve Kent 2752 2753 :rfc:`RFC 4086: Randomness Requirements for Security <4086>` 2754 Donald E., Jeffrey I. Schiller 2755 2756 :rfc:`RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile <5280>` 2757 D. Cooper 2758 2759 :rfc:`RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <5246>` 2760 T. Dierks et. al. 2761 2762 :rfc:`RFC 6066: Transport Layer Security (TLS) Extensions <6066>` 2763 D. Eastlake 2764 2765 `IANA TLS: Transport Layer Security (TLS) Parameters <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_ 2766 IANA 2767 2768 :rfc:`RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) <7525>` 2769 IETF 2770 2771 `Mozilla's Server Side TLS recommendations <https://wiki.mozilla.org/Security/Server_Side_TLS>`_ 2772 Mozilla 2773