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