ssl —- TLS/SSL wrapper for socket objects

源代码:Lib/ssl.py

This module provides access to Transport Layer Security (often known as "SecureSockets Layer") encryption and peer authentication facilities for networksockets, both client-side and server-side. This module uses the OpenSSLlibrary. It is available on all modern Unix systems, Windows, Mac OS X, andprobably additional platforms, as long as OpenSSL is installed on that platform.

注解

Some behavior may be platform dependent, since calls are made to theoperating system socket APIs. The installed version of OpenSSL may alsocause variations in behavior. For example, TLSv1.1 and TLSv1.2 come withopenssl version 1.0.1.

警告

Don't use this module without reading the Security considerations. Doing somay lead to a false sense of security, as the default settings of thessl module are not necessarily appropriate for your application.

This section documents the objects and functions in the ssl module; for moregeneral information about TLS, SSL, and certificates, the reader is referred tothe documents in the "See Also" section at the bottom.

This module provides a class, ssl.SSLSocket, which is derived from thesocket.socket type, and provides a socket-like wrapper that alsoencrypts and decrypts the data going over the socket with SSL. It supportsadditional methods such as getpeercert(), which retrieves thecertificate of the other side of the connection, and cipher(),whichretrieves the cipher being used for the secure connection.

For more sophisticated applications, the ssl.SSLContext classhelps manage settings and certificates, which can then be inheritedby SSL sockets created through the SSLContext.wrap_socket() method.

在 3.5.3 版更改: Updated to support linking with OpenSSL 1.1.0

在 3.6 版更改: OpenSSL 0.9.8, 1.0.0 and 1.0.1 are deprecated and no longer supported.In the future the ssl module will require at least OpenSSL 1.0.2 or1.1.0.

Functions, Constants, and Exceptions

Socket creation

Since Python 3.2 and 2.7.9, it is recommended to use theSSLContext.wrap_socket() of an SSLContext instance to wrapsockets as SSLSocket objects. The helper functionscreate_default_context() returns a new context with secure defaultsettings. The old wrap_socket() function is deprecated since it isboth inefficient and has no support for server name indication (SNI) andhostname matching.

Client socket example with default context and IPv4/IPv6 dual stack:

  1. import socket
  2. import ssl
  3.  
  4. hostname = 'www.python.org'
  5. context = ssl.create_default_context()
  6.  
  7. with socket.create_connection((hostname, 443)) as sock:
  8.     with context.wrap_socket(sock, server_hostname=hostname) as ssock:
  9.         print(ssock.version())

Client socket example with custom context and IPv4:

  1. hostname = 'www.python.org'
  2. # PROTOCOL_TLS_CLIENT requires valid cert chain and hostname
  3. context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
  4. context.load_verify_locations('path/to/cabundle.pem')
  5.  
  6. with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
  7.     with context.wrap_socket(sock, server_hostname=hostname) as ssock:
  8.         print(ssock.version())

Server socket example listening on localhost IPv4:

  1. context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
  2. context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')
  3.  
  4. with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:
  5.     sock.bind(('127.0.0.1', 8443))
  6.     sock.listen(5)
  7.     with context.wrap_socket(sock, server_side=True) as ssock:
  8.         conn, addr = ssock.accept()
  9.         ...

上下文创建

A convenience function helps create SSLContext objects for commonpurposes.

  • ssl.createdefault_context(_purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
  • Return a new SSLContext object with default settings forthe given purpose. The settings are chosen by the ssl module,and usually represent a higher security level than when calling theSSLContext constructor directly.

cafile, capath, cadata represent optional CA certificates totrust for certificate verification, as inSSLContext.load_verify_locations(). If all three areNone, this function can choose to trust the system's defaultCA certificates instead.

The settings are: PROTOCOL_TLS, OP_NO_SSLv2, andOP_NO_SSLv3 with high encryption cipher suites without RC4 andwithout unauthenticated cipher suites. Passing SERVER_AUTHas purpose sets verify_mode to CERT_REQUIREDand either loads CA certificates (when at least one of cafile, capath orcadata is given) or uses SSLContext.load_default_certs() to loaddefault CA certificates.

When keylog_filename is supported and the environmentvariable SSLKEYLOGFILE is set, create_default_context()enables key logging.

注解

The protocol, options, cipher and other settings may change to morerestrictive values anytime without prior deprecation. The valuesrepresent a fair balance between compatibility and security.

If your application needs specific settings, you should create aSSLContext and apply the settings yourself.

注解

If you find that when certain older clients or servers attempt to connectwith a SSLContext created by this function that they get an errorstating "Protocol or cipher suite mismatch", it may be that they onlysupport SSL3.0 which this function excludes using theOP_NO_SSLv3. SSL3.0 is widely considered to be completely broken. If you still wish to continue touse this function but still allow SSL 3.0 connections you can re-enablethem using:

  1. ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
  2. ctx.options &= ~ssl.OP_NO_SSLv3

3.4 新版功能.

在 3.4.4 版更改: RC4 was dropped from the default cipher string.

在 3.6 版更改: ChaCha20/Poly1305 was added to the default cipher string.

3DES was dropped from the default cipher string.

在 3.8 版更改: Support for key logging to SSLKEYLOGFILE was added.

异常

  • exception ssl.SSLError
  • Raised to signal an error from the underlying SSL implementation(currently provided by the OpenSSL library). This signifies someproblem in the higher-level encryption and authentication layer that'ssuperimposed on the underlying network connection. This erroris a subtype of OSError. The error code and message ofSSLError instances are provided by the OpenSSL library.

在 3.3 版更改: SSLError used to be a subtype of socket.error.

  • library
  • A string mnemonic designating the OpenSSL submodule in which the erroroccurred, such as SSL, PEM or X509. The range of possiblevalues depends on the OpenSSL version.

3.3 新版功能.

  • reason
  • A string mnemonic designating the reason this error occurred, forexample CERTIFICATE_VERIFY_FAILED. The range of possiblevalues depends on the OpenSSL version.

3.3 新版功能.

  • exception ssl.SSLZeroReturnError
  • A subclass of SSLError raised when trying to read or write andthe SSL connection has been closed cleanly. Note that this doesn'tmean that the underlying transport (read TCP) has been closed.

3.3 新版功能.

  • exception ssl.SSLWantReadError
  • A subclass of SSLError raised by a non-blocking SSL socket when trying to read or write data, but more data needsto be received on the underlying TCP transport before the request can befulfilled.

3.3 新版功能.

  • exception ssl.SSLWantWriteError
  • A subclass of SSLError raised by a non-blocking SSL socket when trying to read or write data, but more data needsto be sent on the underlying TCP transport before the request can befulfilled.

3.3 新版功能.

  • exception ssl.SSLSyscallError
  • A subclass of SSLError raised when a system error was encounteredwhile trying to fulfill an operation on a SSL socket. Unfortunately,there is no easy way to inspect the original errno number.

3.3 新版功能.

  • exception ssl.SSLEOFError
  • A subclass of SSLError raised when the SSL connection has beenterminated abruptly. Generally, you shouldn't try to reuse the underlyingtransport when this error is encountered.

3.3 新版功能.

  • exception ssl.SSLCertVerificationError
  • A subclass of SSLError raised when certificate validation hasfailed.

3.7 新版功能.

  • verify_code

  • A numeric error number that denotes the verification error.

  • verify_message

  • A human readable string of the verification error.

在 3.7 版更改: The exception is now an alias for SSLCertVerificationError.

Random generation

  • ssl.RANDbytes(_num)
  • Return num cryptographically strong pseudo-random bytes. Raises anSSLError if the PRNG has not been seeded with enough data or if theoperation is not supported by the current RAND method. RAND_status()can be used to check the status of the PRNG and RAND_add() can be usedto seed the PRNG.

For almost all applications os.urandom() is preferable.

Read the Wikipedia article, Cryptographically secure pseudorandom numbergenerator (CSPRNG),to get the requirements of a cryptographically generator.

3.3 新版功能.

  • ssl.RANDpseudo_bytes(_num)
  • Return (bytes, iscryptographic): bytes are _num pseudo-random bytes,is_cryptographic is True if the bytes generated are cryptographicallystrong. Raises an SSLError if the operation is not supported by thecurrent RAND method.

Generated pseudo-random byte sequences will be unique if they are ofsufficient length, but are not necessarily unpredictable. They can be usedfor non-cryptographic purposes and for certain purposes in cryptographicprotocols, but usually not for key generation etc.

For almost all applications os.urandom() is preferable.

3.3 新版功能.

3.6 版后已移除: OpenSSL has deprecated ssl.RAND_pseudo_bytes(), usessl.RAND_bytes() instead.

  • ssl.RAND_status()

  • Return True if the SSL pseudo-random number generator has been seededwith 'enough' randomness, and False otherwise. You can usessl.RAND_egd() and ssl.RAND_add() to increase the randomness ofthe pseudo-random number generator.

  • ssl.RANDegd(_path)

  • If you are running an entropy-gathering daemon (EGD) somewhere, and _path_is the pathname of a socket connection open to it, this will read 256 bytesof randomness from the socket, and add it to the SSL pseudo-random numbergenerator to increase the security of generated secret keys. This istypically only necessary on systems without better sources of randomness.

See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sourcesof entropy-gathering daemons.

Availability: not available with LibreSSL and OpenSSL > 1.1.0.

  • ssl.RANDadd(_bytes, entropy)
  • Mix the given bytes into the SSL pseudo-random number generator. Theparameter entropy (a float) is a lower bound on the entropy contained instring (so you can always use 0.0). See RFC 1750 for moreinformation on sources of entropy.

在 3.5 版更改: 现在支持可写的 字节类对象。

Certificate handling

  • ssl.matchhostname(_cert, hostname)
  • Verify that cert (in decoded format as returned bySSLSocket.getpeercert()) matches the given hostname. The rulesapplied are those for checking the identity of HTTPS servers as outlinedin RFC 2818, RFC 5280 and RFC 6125. In addition to HTTPS, thisfunction should be suitable for checking the identity of servers invarious SSL-based protocols such as FTPS, IMAPS, POPS and others.

CertificateError is raised on failure. On success, the functionreturns nothing:

  1. >>> cert = {'subject': ((('commonName', 'example.com'),),)}
  2. >>> ssl.match_hostname(cert, "example.com")
  3. >>> ssl.match_hostname(cert, "example.org")
  4. Traceback (most recent call last):
  5.   File "<stdin>", line 1, in <module>
  6.   File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
  7. ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

3.2 新版功能.

在 3.3.3 版更改: The function now follows RFC 6125, section 6.4.3 and does neithermatch multiple wildcards (e.g. ..com or a.example.org) nora wildcard inside an internationalized domain names (IDN) fragment.IDN A-labels such as www.xn—pthon-kva.org are still supported,but x.python.org no longer matches xn—tda.python.org.

在 3.5 版更改: Matching of IP addresses, when present in the subjectAltName fieldof the certificate, is now supported.

在 3.7 版更改: The function is no longer used to TLS connections. Hostname matchingis now performed by OpenSSL.

Allow wildcard when it is the leftmost and the only characterin that segment. Partial wildcards like www*.example.com are nolonger supported.

3.7 版后已移除.

  • ssl.certtime_to_seconds(_cert_time)
  • Return the time in seconds since the Epoch, given the cert_timestring representing the "notBefore" or "notAfter" date from acertificate in "%b %d %H:%M:%S %Y %Z" strptime format (Clocale).

Here's an example:

  1. >>> import ssl
  2. >>> timestamp = ssl.cert_time_to_seconds("Jan  5 09:34:43 2018 GMT")
  3. >>> timestamp  
  4. 1515144883
  5. >>> from datetime import datetime
  6. >>> print(datetime.utcfromtimestamp(timestamp))  
  7. 2018-01-05 09:34:43

"notBefore" or "notAfter" dates must use GMT (RFC 5280).

在 3.5 版更改: Interpret the input time as a time in UTC as specified by 'GMT'timezone in the input string. Local timezone was usedpreviously. Return an integer (no fractions of a second in theinput format)

  • ssl.getserver_certificate(_addr, ssl_version=PROTOCOL_TLS, ca_certs=None)
  • Given the address addr of an SSL-protected server, as a (hostname,port-number) pair, fetches the server's certificate, and returns it as aPEM-encoded string. If ssl_version is specified, uses that version ofthe SSL protocol to attempt to connect to the server. If ca_certs isspecified, it should be a file containing a list of root certificates, thesame format as used for the same parameter inSSLContext.wrap_socket(). The call will attempt to validate theserver certificate against that set of root certificates, and will failif the validation attempt fails.

在 3.3 版更改: This function is now IPv6-compatible.

在 3.5 版更改: The default ssl_version is changed from PROTOCOL_SSLv3 toPROTOCOL_TLS for maximum compatibility with modern servers.

  • ssl.DERcert_to_PEM_cert(_DER_cert_bytes)

  • Given a certificate as a DER-encoded blob of bytes, returns a PEM-encodedstring version of the same certificate.

  • ssl.PEMcert_to_DER_cert(_PEM_cert_string)

  • Given a certificate as an ASCII PEM string, returns a DER-encoded sequence ofbytes for that same certificate.

  • ssl.get_default_verify_paths()

  • Returns a named tuple with paths to OpenSSL's default cafile and capath.The paths are the same as used bySSLContext.set_default_verify_paths(). The return value is anamed tuple DefaultVerifyPaths:

    • cafile - resolved path to cafile or None if the file doesn't exist,

    • capath - resolved path to capath or None if the directory doesn't exist,

    • openssl_cafile_env - OpenSSL's environment key that points to a cafile,

    • openssl_cafile - hard coded path to a cafile,

    • openssl_capath_env - OpenSSL's environment key that points to a capath,

    • openssl_capath - hard coded path to a capath directory

Availability: LibreSSL ignores the environment varsopenssl_cafile_env and openssl_capath_env.

3.4 新版功能.

  • ssl.enumcertificates(_store_name)
  • Retrieve certificates from Windows' system cert store. store_name may beone of CA, ROOT or MY. Windows may provide additional certstores, too.

The function returns a list of (cert_bytes, encoding_type, trust) tuples.The encoding_type specifies the encoding of cert_bytes. It is eitherx509_asn for X.509 ASN.1 data or pkcs_7_asn forPKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a setof OIDS or exactly True if the certificate is trustworthy for allpurposes.

示例:

  1. >>> ssl.enum_certificates("CA")
  2. [(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
  3.  (b'data...', 'x509_asn', True)]

可用性: Windows。

3.4 新版功能.

  • ssl.enumcrls(_store_name)
  • Retrieve CRLs from Windows' system cert store. store_name may beone of CA, ROOT or MY. Windows may provide additional certstores, too.

The function returns a list of (cert_bytes, encoding_type, trust) tuples.The encoding_type specifies the encoding of cert_bytes. It is eitherx509_asn for X.509 ASN.1 data or pkcs_7_asn forPKCS#7 ASN.1 data.

可用性: Windows。

3.4 新版功能.

  • ssl.wrapsocket(_sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)
  • Takes an instance sock of socket.socket, and returns an instanceof ssl.SSLSocket, a subtype of socket.socket, which wrapsthe underlying socket in an SSL context. sock must be aSOCK_STREAM socket; other socket types are unsupported.

Internally, function creates a SSLContext with protocolssl_version and SSLContext.options set to cert_reqs. Ifparameters keyfile, certfile, ca_certs or ciphers are set, thenthe values are passed to SSLContext.load_cert_chain(),SSLContext.load_verify_locations(), andSSLContext.set_ciphers().

The arguments server_side, do_handshake_on_connect, andsuppress_ragged_eofs have the same meaning asSSLContext.wrap_socket().

3.7 版后已移除: Since Python 3.2 and 2.7.9, it is recommended to use theSSLContext.wrap_socket() instead of wrap_socket(). Thetop-level function is limited and creates an insecure client socketwithout server name indication or hostname matching.

常数

All constants are now enum.IntEnum or enum.IntFlag collections.

3.6 新版功能.

  • ssl.CERT_NONE
  • Possible value for SSLContext.verify_mode, or the cert_reqsparameter to wrap_socket(). Except for PROTOCOL_TLS_CLIENT,it is the default mode. With client-side sockets, just about anycert is accepted. Validation errors, such as untrusted or expired cert,are ignored and do not abort the TLS/SSL handshake.

In server mode, no certificate is requested from the client, so the clientdoes not send any for client cert authentication.

See the discussion of Security considerations below.

In server mode, a client certificate request is sent to the client. Theclient may either ignore the request or send a certificate in orderperform TLS client cert authentication. If the client chooses to senda certificate, it is verified. Any verification error immediately abortsthe TLS handshake.

Use of this setting requires a valid set of CA certificates tobe passed, either to SSLContext.load_verify_locations() or as avalue of the ca_certs parameter to wrap_socket().

  • ssl.CERT_REQUIRED
  • Possible value for SSLContext.verify_mode, or the cert_reqsparameter to wrap_socket(). In this mode, certificates arerequired from the other side of the socket connection; an SSLErrorwill be raised if no certificate is provided, or if its validation fails.This mode is not sufficient to verify a certificate in client mode asit does not match hostnames. check_hostname must beenabled as well to verify the authenticity of a cert.PROTOCOL_TLS_CLIENT uses CERT_REQUIRED andenables check_hostname by default.

With server socket, this mode provides mandatory TLS client certauthentication. A client certificate request is sent to the client andthe client must provide a valid and trusted certificate.

Use of this setting requires a valid set of CA certificates tobe passed, either to SSLContext.load_verify_locations() or as avalue of the ca_certs parameter to wrap_socket().

  • class ssl.VerifyMode
  • enum.IntEnum collection of CERT_* constants.

3.6 新版功能.

  • ssl.VERIFY_DEFAULT
  • Possible value for SSLContext.verify_flags. In this mode, certificaterevocation lists (CRLs) are not checked. By default OpenSSL does neitherrequire nor verify CRLs.

3.4 新版功能.

  • ssl.VERIFY_CRL_CHECK_LEAF
  • Possible value for SSLContext.verify_flags. In this mode, only thepeer cert is checked but none of the intermediate CA certificates. The moderequires a valid CRL that is signed by the peer cert's issuer (its directancestor CA). If no proper CRL has has been loaded withSSLContext.load_verify_locations, validation will fail.

3.4 新版功能.

  • ssl.VERIFY_CRL_CHECK_CHAIN
  • Possible value for SSLContext.verify_flags. In this mode, CRLs ofall certificates in the peer cert chain are checked.

3.4 新版功能.

  • ssl.VERIFY_X509_STRICT
  • Possible value for SSLContext.verify_flags to disable workaroundsfor broken X.509 certificates.

3.4 新版功能.

  • ssl.VERIFY_X509_TRUSTED_FIRST
  • Possible value for SSLContext.verify_flags. It instructs OpenSSL toprefer trusted certificates when building the trust chain to validate acertificate. This flag is enabled by default.

3.4.4 新版功能.

  • class ssl.VerifyFlags
  • enum.IntFlag collection of VERIFY_* constants.

3.6 新版功能.

  • ssl.PROTOCOL_TLS
  • Selects the highest protocol version that both the client and server support.Despite the name, this option can select both "SSL" and "TLS" protocols.

3.6 新版功能.

3.6 新版功能.

  • ssl.PROTOCOL_TLS_SERVER
  • Auto-negotiate the highest protocol version like PROTOCOL_TLS,but only support server-side SSLSocket connections.

3.6 新版功能.

3.6 版后已移除: Use PROTOCOL_TLS instead.

  • ssl.PROTOCOL_SSLv2
  • Selects SSL version 2 as the channel encryption protocol.

This protocol is not available if OpenSSL is compiled with theOPENSSL_NO_SSL2 flag.

警告

SSL version 2 is insecure. Its use is highly discouraged.

3.6 版后已移除: OpenSSL has removed support for SSLv2.

  • ssl.PROTOCOL_SSLv3
  • Selects SSL version 3 as the channel encryption protocol.

This protocol is not be available if OpenSSL is compiled with theOPENSSL_NO_SSLv3 flag.

警告

SSL version 3 is insecure. Its use is highly discouraged.

3.6 版后已移除: OpenSSL has deprecated all version specific protocols. Use the defaultprotocol PROTOCOL_TLS with flags like OP_NO_SSLv3 instead.

  • ssl.PROTOCOL_TLSv1
  • Selects TLS version 1.0 as the channel encryption protocol.

3.6 版后已移除: OpenSSL has deprecated all version specific protocols. Use the defaultprotocol PROTOCOL_TLS with flags like OP_NO_SSLv3 instead.

  • ssl.PROTOCOL_TLSv1_1
  • Selects TLS version 1.1 as the channel encryption protocol.Available only with openssl version 1.0.1+.

3.4 新版功能.

3.6 版后已移除: OpenSSL has deprecated all version specific protocols. Use the defaultprotocol PROTOCOL_TLS with flags like OP_NO_SSLv3 instead.

  • ssl.PROTOCOL_TLSv1_2
  • Selects TLS version 1.2 as the channel encryption protocol. This is themost modern version, and probably the best choice for maximum protection,if both sides can speak it. Available only with openssl version 1.0.1+.

3.4 新版功能.

3.6 版后已移除: OpenSSL has deprecated all version specific protocols. Use the defaultprotocol PROTOCOL_TLS with flags like OP_NO_SSLv3 instead.

  • ssl.OP_ALL
  • Enables workarounds for various bugs present in other SSL implementations.This option is set by default. It does not necessarily set the sameflags as OpenSSL's SSL_OP_ALL constant.

3.2 新版功能.

  • ssl.OP_NO_SSLv2
  • Prevents an SSLv2 connection. This option is only applicable inconjunction with PROTOCOL_TLS. It prevents the peers fromchoosing SSLv2 as the protocol version.

3.2 新版功能.

3.6 版后已移除: SSLv2 is deprecated

  • ssl.OP_NO_SSLv3
  • Prevents an SSLv3 connection. This option is only applicable inconjunction with PROTOCOL_TLS. It prevents the peers fromchoosing SSLv3 as the protocol version.

3.2 新版功能.

3.6 版后已移除: SSLv3 is deprecated

  • ssl.OP_NO_TLSv1
  • Prevents a TLSv1 connection. This option is only applicable inconjunction with PROTOCOL_TLS. It prevents the peers fromchoosing TLSv1 as the protocol version.

3.2 新版功能.

3.7 版后已移除: The option is deprecated since OpenSSL 1.1.0, use the newSSLContext.minimum_version andSSLContext.maximum_version instead.

  • ssl.OP_NO_TLSv1_1
  • Prevents a TLSv1.1 connection. This option is only applicable in conjunctionwith PROTOCOL_TLS. It prevents the peers from choosing TLSv1.1 asthe protocol version. Available only with openssl version 1.0.1+.

3.4 新版功能.

3.7 版后已移除: The option is deprecated since OpenSSL 1.1.0.

  • ssl.OP_NO_TLSv1_2
  • Prevents a TLSv1.2 connection. This option is only applicable in conjunctionwith PROTOCOL_TLS. It prevents the peers from choosing TLSv1.2 asthe protocol version. Available only with openssl version 1.0.1+.

3.4 新版功能.

3.7 版后已移除: The option is deprecated since OpenSSL 1.1.0.

  • ssl.OP_NO_TLSv1_3
  • Prevents a TLSv1.3 connection. This option is only applicable in conjunctionwith PROTOCOL_TLS. It prevents the peers from choosing TLSv1.3 asthe protocol version. TLS 1.3 is available with OpenSSL 1.1.1 or later.When Python has been compiled against an older version of OpenSSL, theflag defaults to 0.

3.7 新版功能.

3.7 版后已移除: The option is deprecated since OpenSSL 1.1.0. It was added to 2.7.15,3.6.3 and 3.7.0 for backwards compatibility with OpenSSL 1.0.2.

  • ssl.OP_NO_RENEGOTIATION
  • Disable all renegotiation in TLSv1.2 and earlier. Do not sendHelloRequest messages, and ignore renegotiation requests via ClientHello.

This option is only available with OpenSSL 1.1.0h and later.

3.7 新版功能.

  • ssl.OP_CIPHER_SERVER_PREFERENCE
  • Use the server's cipher ordering preference, rather than the client's.This option has no effect on client sockets and SSLv2 server sockets.

3.3 新版功能.

  • ssl.OP_SINGLE_DH_USE
  • Prevents re-use of the same DH key for distinct SSL sessions. Thisimproves forward secrecy but requires more computational resources.This option only applies to server sockets.

3.3 新版功能.

  • ssl.OP_SINGLE_ECDH_USE
  • Prevents re-use of the same ECDH key for distinct SSL sessions. Thisimproves forward secrecy but requires more computational resources.This option only applies to server sockets.

3.3 新版功能.

  • ssl.OP_ENABLE_MIDDLEBOX_COMPAT
  • Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake to makea TLS 1.3 connection look more like a TLS 1.2 connection.

This option is only available with OpenSSL 1.1.1 and later.

3.8 新版功能.

  • ssl.OP_NO_COMPRESSION
  • Disable compression on the SSL channel. This is useful if the applicationprotocol supports its own compression scheme.

This option is only available with OpenSSL 1.0.0 and later.

3.3 新版功能.

  • class ssl.Options

  • enum.IntFlag collection of OP_* constants.

  • ssl.OP_NO_TICKET

  • Prevent client side from requesting a session ticket.

3.6 新版功能.

  • ssl.HAS_ALPN
  • Whether the OpenSSL library has built-in support for the Application-LayerProtocol Negotiation TLS extension as described in RFC 7301.

3.5 新版功能.

3.7 新版功能.

  • ssl.HAS_ECDH
  • Whether the OpenSSL library has built-in support for the Elliptic Curve-basedDiffie-Hellman key exchange. This should be true unless the feature wasexplicitly disabled by the distributor.

3.3 新版功能.

  • ssl.HAS_SNI
  • Whether the OpenSSL library has built-in support for the Server NameIndication extension (as defined in RFC 6066).

3.2 新版功能.

3.3 新版功能.

  • ssl.HAS_SSLv2
  • Whether the OpenSSL library has built-in support for the SSL 2.0 protocol.

3.7 新版功能.

  • ssl.HAS_SSLv3
  • Whether the OpenSSL library has built-in support for the SSL 3.0 protocol.

3.7 新版功能.

  • ssl.HAS_TLSv1
  • Whether the OpenSSL library has built-in support for the TLS 1.0 protocol.

3.7 新版功能.

  • ssl.HAS_TLSv1_1
  • Whether the OpenSSL library has built-in support for the TLS 1.1 protocol.

3.7 新版功能.

  • ssl.HAS_TLSv1_2
  • Whether the OpenSSL library has built-in support for the TLS 1.2 protocol.

3.7 新版功能.

  • ssl.HAS_TLSv1_3
  • Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.

3.7 新版功能.

3.3 新版功能.

  • ssl.OPENSSL_VERSION
  • The version string of the OpenSSL library loaded by the interpreter:
  1. >>> ssl.OPENSSL_VERSION
  2. 'OpenSSL 1.0.2k  26 Jan 2017'

3.2 新版功能.

  • ssl.OPENSSL_VERSION_INFO
  • A tuple of five integers representing version information about theOpenSSL library:
  1. >>> ssl.OPENSSL_VERSION_INFO
  2. (1, 0, 2, 11, 15)

3.2 新版功能.

  • ssl.OPENSSL_VERSION_NUMBER
  • The raw version number of the OpenSSL library, as a single integer:
  1. >>> ssl.OPENSSL_VERSION_NUMBER
  2. 268443839
  3. >>> hex(ssl.OPENSSL_VERSION_NUMBER)
  4. '0x100020bf'

3.2 新版功能.

  • ssl.ALERT_DESCRIPTION_HANDSHAKE_FAILURE
  • ssl.ALERT_DESCRIPTION_INTERNAL_ERROR
  • ALERTDESCRIPTION*
  • Alert Descriptions from RFC 5246 and others. The IANA TLS Alert Registrycontains this list and references to the RFCs where their meaning is defined.

Used as the return value of the callback function inSSLContext.set_servername_callback().

3.4 新版功能.

  • class ssl.AlertDescription
  • enum.IntEnum collection of ALERTDESCRIPTION* constants.

3.6 新版功能.

3.4 新版功能.

3.4 新版功能.

  • class ssl.SSLErrorNumber
  • enum.IntEnum collection of SSLERROR* constants.

3.6 新版功能.

3.7 新版功能.

  • TLSVersion.MINIMUM_SUPPORTED
  • TLSVersion.MAXIMUM_SUPPORTED

  • The minimum or maximum supported SSL or TLS version. These are magicconstants. Their values don't reflect the lowest and highest availableTLS/SSL versions.

  • TLSVersion.SSLv3

  • TLSVersion.TLSv1
  • TLSVersion.TLSv1_1
  • TLSVersion.TLSv1_2
  • TLSVersion.TLSv1_3
  • SSL 3.0 to TLS 1.3.

SSL Sockets

However, since the SSL (and TLS) protocol has its own framing atopof TCP, the SSL sockets abstraction can, in certain respects, diverge fromthe specification of normal, OS-level sockets. See especially thenotes on non-blocking sockets.

Instances of SSLSocket must be created using theSSLContext.wrap_socket() method.

在 3.5 版更改: The sendfile() method was added.

在 3.5 版更改: The shutdown() does not reset the socket timeout each time bytesare received or sent. The socket timeout is now to maximum total durationof the shutdown.

3.6 版后已移除: It is deprecated to create a SSLSocket instance directly, useSSLContext.wrap_socket() to wrap a socket.

在 3.7 版更改: SSLSocket instances must to created withwrap_socket(). In earlier versions, it was possibleto create instances directly. This was never documented or officiallysupported.

SSL sockets also have the following additional methods and attributes:

  • SSLSocket.read(len=1024, buffer=None)
  • Read up to len bytes of data from the SSL socket and return the result asa bytes instance. If buffer is specified, then read into the bufferinstead, and return the number of bytes read.

Raise SSLWantReadError or SSLWantWriteError if the socket isnon-blocking and the read would block.

As at any time a re-negotiation is possible, a call to read() can alsocause write operations.

在 3.5 版更改: The socket timeout is no more reset each time bytes are received or sent.The socket timeout is now to maximum total duration to read up to _len_bytes.

3.6 版后已移除: Use recv() instead of read().

  • SSLSocket.write(buf)
  • Write buf to the SSL socket and return the number of bytes written. Thebuf argument must be an object supporting the buffer interface.

Raise SSLWantReadError or SSLWantWriteError if the socket isnon-blocking and the write would block.

As at any time a re-negotiation is possible, a call to write() canalso cause read operations.

在 3.5 版更改: The socket timeout is no more reset each time bytes are received or sent.The socket timeout is now to maximum total duration to write buf.

3.6 版后已移除: Use send() instead of write().

注解

The read() and write() methods are thelow-level methods that read and write unencrypted, application-level dataand decrypt/encrypt it to encrypted, wire-level data. These methodsrequire an active SSL connection, i.e. the handshake was completed andSSLSocket.unwrap() was not called.

Normally you should use the socket API methods likerecv() and send() instead of thesemethods.

  • SSLSocket.do_handshake()
  • Perform the SSL setup handshake.

在 3.4 版更改: The handshake method also performs match_hostname() when thecheck_hostname attribute of the socket'scontext is true.

在 3.5 版更改: The socket timeout is no more reset each time bytes are received or sent.The socket timeout is now to maximum total duration of the handshake.

在 3.7 版更改: Hostname or IP address is matched by OpenSSL during handshake. Thefunction match_hostname() is no longer used. In case OpenSSLrefuses a hostname or IP address, the handshake is aborted early anda TLS alert message is send to the peer.

  • SSLSocket.getpeercert(binary_form=False)
  • If there is no certificate for the peer on the other end of the connection,return None. If the SSL handshake hasn't been done yet, raiseValueError.

If the binaryform parameter is False, and a certificate wasreceived from the peer, this method returns a dict instance. If thecertificate was not validated, the dict is empty. If the certificate wasvalidated, it returns a dict with several keys, amongst them subject(the principal for which the certificate was issued) and issuer(the principal issuing the certificate). If a certificate contains aninstance of the _Subject Alternative Name extension (see RFC 3280),there will also be a subjectAltName key in the dictionary.

The subject and issuer fields are tuples containing the sequenceof relative distinguished names (RDNs) given in the certificate's datastructure for the respective fields, and each RDN is a sequence ofname-value pairs. Here is a real-world example:

  1. {'issuer': ((('countryName', 'IL'),),
  2.             (('organizationName', 'StartCom Ltd.'),),
  3.             (('organizationalUnitName',
  4.               'Secure Digital Certificate Signing'),),
  5.             (('commonName',
  6.               'StartCom Class 2 Primary Intermediate Server CA'),)),
  7.  'notAfter': 'Nov 22 08:15:19 2013 GMT',
  8.  'notBefore': 'Nov 21 03:09:52 2011 GMT',
  9.  'serialNumber': '95F0',
  10.  'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
  11.              (('countryName', 'US'),),
  12.              (('stateOrProvinceName', 'California'),),
  13.              (('localityName', 'San Francisco'),),
  14.              (('organizationName', 'Electronic Frontier Foundation, Inc.'),),
  15.              (('commonName', '*.eff.org'),),
  16.              (('emailAddress', 'hostmaster@eff.org'),)),
  17.  'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
  18.  'version': 3}

注解

To validate a certificate for a particular service, you can use thematch_hostname() function.

If the binary_form parameter is True, and a certificate wasprovided, this method returns the DER-encoded form of the entire certificateas a sequence of bytes, or None if the peer did not provide acertificate. Whether the peer provides a certificate depends on the SSLsocket's role:

  • for a client SSL socket, the server will always provide a certificate,regardless of whether validation was required;

  • for a server SSL socket, the client will only provide a certificatewhen requested by the server; therefore getpeercert() will returnNone if you used CERT_NONE (rather thanCERT_OPTIONAL or CERT_REQUIRED).

在 3.2 版更改: The returned dictionary includes additional items such as issuerand notBefore.

在 3.4 版更改: ValueError is raised when the handshake isn't done.The returned dictionary includes additional X509v3 extension items such as crlDistributionPoints, caIssuers and OCSP URIs.

  • SSLSocket.cipher()

  • Returns a three-value tuple containing the name of the cipher being used, theversion of the SSL protocol that defines its use, and the number of secretbits being used. If no connection has been established, returns None.

  • SSLSocket.shared_ciphers()

  • Return the list of ciphers shared by the client during the handshake. Eachentry of the returned list is a three-value tuple containing the name of thecipher, the version of the SSL protocol that defines its use, and the numberof secret bits the cipher uses. shared_ciphers() returnsNone if no connection has been established or the socket is a clientsocket.

3.5 新版功能.

  • SSLSocket.compression()
  • Return the compression algorithm being used as a string, or Noneif the connection isn't compressed.

If the higher-level protocol supports its own compression mechanism,you can use OP_NO_COMPRESSION to disable SSL-level compression.

3.3 新版功能.

  • SSLSocket.getchannel_binding(_cb_type="tls-unique")
  • Get channel binding data for current connection, as a bytes object. ReturnsNone if not connected or the handshake has not been completed.

The cb_type parameter allow selection of the desired channel bindingtype. Valid channel binding types are listed in theCHANNEL_BINDING_TYPES list. Currently only the 'tls-unique' channelbinding, defined by RFC 5929, is supported. ValueError will beraised if an unsupported channel binding type is requested.

3.3 新版功能.

  • SSLSocket.selected_alpn_protocol()
  • Return the protocol that was selected during the TLS handshake. IfSSLContext.set_alpn_protocols() was not called, if the other party doesnot support ALPN, if this socket does not support any of the client'sproposed protocols, or if the handshake has not happened yet, None isreturned.

3.5 新版功能.

  • SSLSocket.selected_npn_protocol()
  • Return the higher-level protocol that was selected during the TLS/SSLhandshake. If SSLContext.set_npn_protocols() was not called, orif the other party does not support NPN, or if the handshake has not yethappened, this will return None.

3.3 新版功能.

  • SSLSocket.unwrap()

  • Performs the SSL shutdown handshake, which removes the TLS layer from theunderlying socket, and returns the underlying socket object. This can beused to go from encrypted operation over a connection to unencrypted. Thereturned socket should always be used for further communication with theother side of the connection, rather than the original socket.

  • SSLSocket.verify_client_post_handshake()

  • Requests post-handshake authentication (PHA) from a TLS 1.3 client. PHAcan only be initiated for a TLS 1.3 connection from a server-side socket,after the initial TLS handshake and with PHA enabled on both sides, seeSSLContext.post_handshake_auth.

The method does not perform a cert exchange immediately. The server-sidesends a CertificateRequest during the next write event and expects theclient to respond with a certificate on the next read event.

If any precondition isn't met (e.g. not TLS 1.3, PHA not enabled), anSSLError is raised.

注解

Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3support, the method raises NotImplementedError.

3.8 新版功能.

  • SSLSocket.version()
  • Return the actual SSL protocol version negotiated by the connectionas a string, or None is no secure connection is established.As of this writing, possible return values include "SSLv2","SSLv3", "TLSv1", "TLSv1.1" and "TLSv1.2".Recent OpenSSL versions may define more return values.

3.5 新版功能.

  • SSLSocket.pending()

  • Returns the number of already decrypted bytes available for read, pending onthe connection.

  • SSLSocket.context

  • The SSLContext object this SSL socket is tied to. If the SSLsocket was created using the deprecated wrap_socket() function(rather than SSLContext.wrap_socket()), this is a custom contextobject created for this SSL socket.

3.2 新版功能.

  • SSLSocket.server_side
  • A boolean which is True for server-side sockets and False forclient-side sockets.

3.2 新版功能.

  • SSLSocket.server_hostname
  • Hostname of the server: str type, or None for server-sidesocket or if the hostname was not specified in the constructor.

3.2 新版功能.

在 3.7 版更改: The attribute is now always ASCII text. When server_hostname isan internationalized domain name (IDN), this attribute now stores theA-label form ("xn—pythn-mua.org"), rather than the U-label form("pythön.org").

  • SSLSocket.session
  • The SSLSession for this SSL connection. The session is availablefor client and server side sockets after the TLS handshake has beenperformed. For client sockets the session can be set beforedo_handshake() has been called to reuse a session.

3.6 新版功能.

  • SSLSocket.session_reused

3.6 新版功能.

SSL Contexts

3.2 新版功能.

An SSL context holds various data longer-lived than single SSL connections,such as SSL configuration options, certificate(s) and private key(s).It also manages a cache of SSL sessions for server-side sockets, in orderto speed up repeated connections from the same clients.

  • class ssl.SSLContext(protocol=PROTOCOL_TLS)
  • Create a new SSL context. You may pass protocol which must be oneof the PROTOCOL_* constants defined in this module. The parameterspecifies which version of the SSL protocol to use. Typically, theserver chooses a particular protocol version, and the client must adaptto the server's choice. Most of the versions are not interoperablewith the other versions. If not specified, the default isPROTOCOL_TLS; it provides the most compatibility with otherversions.

Here's a table showing which versions in a client (down the side) can connectto which versions in a server (along the top):

客户端 / 服务器

SSLv2

SSLv3

TLS 3

TLSv1

TLSv1.1

TLSv1.2

SSLv2

是

否

否 1

否

否

否

SSLv3

否

是

否 2

否

否

否

TLS (SSLv23) 3

否 1

否 2

是

是

是

是

TLSv1

否

否

是

是

否

否

TLSv1.1

否

否

是

否

是

否

TLSv1.2

否

否

是

否

否

是

脚注

参见

create_default_context() lets the ssl module choosesecurity settings for a given purpose.

在 3.6 版更改: The context is created with secure default values. The optionsOP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE,OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE,OP_NO_SSLv2 (except for PROTOCOL_SSLv2),and OP_NO_SSLv3 (except for PROTOCOL_SSLv3) areset by default. The initial cipher suite list contains only HIGHciphers, no NULL ciphers and no MD5 ciphers (except forPROTOCOL_SSLv2).

SSLContext objects have the following methods and attributes:

  • SSLContext.cert_store_stats()
  • Get statistics about quantities of loaded X.509 certificates, count ofX.509 certificates flagged as CA certificates and certificate revocationlists as dictionary.

Example for a context with one CA cert and one other cert:

  1. >>> context.cert_store_stats()
  2. {'crl': 0, 'x509_ca': 1, 'x509': 2}

3.4 新版功能.

  • SSLContext.loadcert_chain(_certfile, keyfile=None, password=None)
  • Load a private key and the corresponding certificate. The certfile_string must be the path to a single file in PEM format containing thecertificate as well as any number of CA certificates needed to establishthe certificate's authenticity. The _keyfile string, if present, mustpoint to a file containing the private key in. Otherwise the privatekey will be taken from certfile as well. See the discussion ofCertificates for more information on how the certificateis stored in the certfile.

The password argument may be a function to call to get the password fordecrypting the private key. It will only be called if the private key isencrypted and a password is necessary. It will be called with no arguments,and it should return a string, bytes, or bytearray. If the return value isa string it will be encoded as UTF-8 before using it to decrypt the key.Alternatively a string, bytes, or bytearray value may be supplied directlyas the password argument. It will be ignored if the private key is notencrypted and no password is needed.

If the password argument is not specified and a password is required,OpenSSL's built-in password prompting mechanism will be used tointeractively prompt the user for a password.

An SSLError is raised if the private key doesn'tmatch with the certificate.

在 3.3 版更改: New optional argument password.

  • SSLContext.loaddefault_certs(_purpose=Purpose.SERVER_AUTH)
  • Load a set of default "certification authority" (CA) certificates fromdefault locations. On Windows it loads CA certs from the CA andROOT system stores. On other systems it callsSSLContext.set_default_verify_paths(). In the future the method mayload CA certificates from other locations, too.

The purpose flag specifies what kind of CA certificates are loaded. Thedefault settings Purpose.SERVER_AUTH loads certificates, that areflagged and trusted for TLS web server authentication (client sidesockets). Purpose.CLIENT_AUTH loads CA certificates for clientcertificate verification on the server side.

3.4 新版功能.

  • SSLContext.loadverify_locations(_cafile=None, capath=None, cadata=None)
  • Load a set of "certification authority" (CA) certificates used to validateother peers' certificates when verify_mode is other thanCERT_NONE. At least one of cafile or capath must be specified.

This method can also load certification revocation lists (CRLs) in PEM orDER format. In order to make use of CRLs, SSLContext.verify_flagsmust be configured properly.

The cafile string, if present, is the path to a file of concatenatedCA certificates in PEM format. See the discussion ofCertificates for more information about how to arrange thecertificates in this file.

The capath string, if present, isthe path to a directory containing several CA certificates in PEM format,following an OpenSSL specific layout.

The cadata object, if present, is either an ASCII string of one or morePEM-encoded certificates or a bytes-like object of DER-encodedcertificates. Like with capath extra lines around PEM-encodedcertificates are ignored but at least one certificate must be present.

在 3.4 版更改: New optional argument cadata

  • SSLContext.getca_certs(_binary_form=False)
  • Get a list of loaded "certification authority" (CA) certificates. If thebinaryform parameter is False each listentry is a dict like the output of SSLSocket.getpeercert(). Otherwisethe method returns a list of DER-encoded certificates. The returned listdoes not contain certificates from _capath unless a certificate wasrequested and loaded by a SSL connection.

注解

Certificates in a capath directory aren't loaded unless they havebeen used at least once.

3.4 新版功能.

  • SSLContext.get_ciphers()
  • Get a list of enabled ciphers. The list is in order of cipher priority.See SSLContext.set_ciphers().

示例:

  1. >>> ctx = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
  2. >>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
  3. >>> ctx.get_ciphers()  # OpenSSL 1.0.x
  4. [{'alg_bits': 256,
  5.   'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
  6.                  'Enc=AESGCM(256) Mac=AEAD',
  7.   'id': 50380848,
  8.   'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  9.   'protocol': 'TLSv1/SSLv3',
  10.   'strength_bits': 256},
  11.  {'alg_bits': 128,
  12.   'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
  13.                  'Enc=AESGCM(128) Mac=AEAD',
  14.   'id': 50380847,
  15.   'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  16.   'protocol': 'TLSv1/SSLv3',
  17.   'strength_bits': 128}]

On OpenSSL 1.1 and newer the cipher dict contains additional fields:

  1. >>> ctx.get_ciphers()  # OpenSSL 1.1+
  2. [{'aead': True,
  3.   'alg_bits': 256,
  4.   'auth': 'auth-rsa',
  5.   'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
  6.                  'Enc=AESGCM(256) Mac=AEAD',
  7.   'digest': None,
  8.   'id': 50380848,
  9.   'kea': 'kx-ecdhe',
  10.   'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  11.   'protocol': 'TLSv1.2',
  12.   'strength_bits': 256,
  13.   'symmetric': 'aes-256-gcm'},
  14.  {'aead': True,
  15.   'alg_bits': 128,
  16.   'auth': 'auth-rsa',
  17.   'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
  18.                  'Enc=AESGCM(128) Mac=AEAD',
  19.   'digest': None,
  20.   'id': 50380847,
  21.   'kea': 'kx-ecdhe',
  22.   'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  23.   'protocol': 'TLSv1.2',
  24.   'strength_bits': 128,
  25.   'symmetric': 'aes-128-gcm'}]

Availability: OpenSSL 1.0.2+.

3.6 新版功能.

  • SSLContext.set_default_verify_paths()

  • Load a set of default "certification authority" (CA) certificates froma filesystem path defined when building the OpenSSL library. Unfortunately,there's no easy way to know whether this method succeeds: no error isreturned if no certificates are to be found. When the OpenSSL library isprovided as part of the operating system, though, it is likely to beconfigured properly.

  • SSLContext.setciphers(_ciphers)

  • Set the available ciphers for sockets created with this context.It should be a string in the OpenSSL cipher list format.If no cipher can be selected (because compile-time options or otherconfiguration forbids use of all the specified ciphers), anSSLError will be raised.

注解

when connected, the SSLSocket.cipher() method of SSL sockets willgive the currently selected cipher.

OpenSSL 1.1.1 has TLS 1.3 cipher suites enabled by default. The suitescannot be disabled with set_ciphers().

  • SSLContext.setalpn_protocols(_protocols)
  • Specify which protocols the socket should advertise during the SSL/TLShandshake. It should be a list of ASCII strings, like ['http/1.1','spdy/2'], ordered by preference. The selection of a protocol will happenduring the handshake, and will play out according to RFC 7301. After asuccessful handshake, the SSLSocket.selected_alpn_protocol() method willreturn the agreed-upon protocol.

This method will raise NotImplementedError if HAS_ALPN isFalse.

OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise SSLErrorwhen both sides support ALPN but cannot agree on a protocol. 1.1.0f+behaves like 1.0.2, SSLSocket.selected_alpn_protocol() returns None.

3.5 新版功能.

  • SSLContext.setnpn_protocols(_protocols)
  • Specify which protocols the socket should advertise during the SSL/TLShandshake. It should be a list of strings, like ['http/1.1', 'spdy/2'],ordered by preference. The selection of a protocol will happen during thehandshake, and will play out according to the Application Layer Protocol Negotiation. After asuccessful handshake, the SSLSocket.selected_npn_protocol() method willreturn the agreed-upon protocol.

This method will raise NotImplementedError if HAS_NPN isFalse.

3.3 新版功能.

  • SSLContext.sni_callback
  • Register a callback function that will be called after the TLS Client Hellohandshake message has been received by the SSL/TLS server when the TLS clientspecifies a server name indication. The server name indication mechanismis specified in RFC 6066 section 3 - Server Name Indication.

Only one callback can be set per SSLContext. If _sni_callback_is set to None then the callback is disabled. Calling this function asubsequent time will disable the previously registered callback.

The callback function will be called with threearguments; the first being the ssl.SSLSocket, the second is a stringthat represents the server name that the client is intending to communicate(or None if the TLS Client Hello does not contain a server name)and the third argument is the original SSLContext. The server nameargument is text. For internationalized domain name, the servername is an IDN A-label ("xn—pythn-mua.org").

A typical use of this callback is to change the ssl.SSLSocket'sSSLSocket.context attribute to a new object of typeSSLContext representing a certificate chain that matches the servername.

Due to the early negotiation phase of the TLS connection, only limitedmethods and attributes are usable likeSSLSocket.selected_alpn_protocol() and SSLSocket.context.SSLSocket.getpeercert(), SSLSocket.getpeercert(),SSLSocket.cipher() and SSLSocket.compress() methods require thatthe TLS connection has progressed beyond the TLS Client Hello and thereforewill not contain return meaningful values nor can they be called safely.

The sni_callback function must return None to allow theTLS negotiation to continue. If a TLS failure is required, a constantALERTDESCRIPTION* can bereturned. Other return values will result in a TLS fatal error withALERT_DESCRIPTION_INTERNAL_ERROR.

If an exception is raised from the sni_callback function the TLSconnection will terminate with a fatal TLS alert messageALERT_DESCRIPTION_HANDSHAKE_FAILURE.

This method will raise NotImplementedError if the OpenSSL libraryhad OPENSSL_NO_TLSEXT defined when it was built.

3.7 新版功能.

  • SSLContext.setservername_callback(_server_name_callback)
  • This is a legacy API retained for backwards compatibility. When possible,you should use sni_callback instead. The given server_name_callback_is similar to _sni_callback, except that when the server hostname is anIDN-encoded internationalized domain name, the _server_name_callback_receives a decoded U-label ("pythön.org").

If there is an decoding error on the server name, the TLS connection willterminate with an ALERT_DESCRIPTION_INTERNAL_ERROR fatal TLSalert message to the client.

3.4 新版功能.

  • SSLContext.loaddh_params(_dhfile)
  • Load the key generation parameters for Diffie-Hellman (DH) key exchange.Using DH key exchange improves forward secrecy at the expense ofcomputational resources (both on the server and on the client).The dhfile parameter should be the path to a file containing DHparameters in PEM format.

This setting doesn't apply to client sockets. You can also use theOP_SINGLE_DH_USE option to further improve security.

3.3 新版功能.

  • SSLContext.setecdh_curve(_curve_name)
  • Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) keyexchange. ECDH is significantly faster than regular DH while arguablyas secure. The curve_name parameter should be a string describinga well-known elliptic curve, for example prime256v1 for a widelysupported curve.

This setting doesn't apply to client sockets. You can also use theOP_SINGLE_ECDH_USE option to further improve security.

This method is not available if HAS_ECDH is False.

3.3 新版功能.

参见

  • SSLContext.wrapsocket(_sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)
  • Wrap an existing Python socket sock and return an instance ofSSLContext.sslsocket_class (default SSLSocket). Thereturned SSL socket is tied to the context, its settings and certificates.sock must be a SOCK_STREAM socket; othersocket types are unsupported.

The parameter server_side is a boolean which identifies whetherserver-side or client-side behavior is desired from this socket.

For client-side sockets, the context construction is lazy; if theunderlying socket isn't connected yet, the context construction will beperformed after connect() is called on the socket. Forserver-side sockets, if the socket has no remote peer, it is assumedto be a listening socket, and the server-side SSL wrapping isautomatically performed on client connections accepted via theaccept() method. The method may raise SSLError.

On client connections, the optional parameter server_hostname specifiesthe hostname of the service which we are connecting to. This allows asingle server to host multiple SSL-based services with distinct certificates,quite similarly to HTTP virtual hosts. Specifying server_hostname willraise a ValueError if server_side is true.

The parameter do_handshake_on_connect specifies whether to do the SSLhandshake automatically after doing a socket.connect(), or whether theapplication program will call it explicitly, by invoking theSSLSocket.do_handshake() method. CallingSSLSocket.do_handshake() explicitly gives the program control over theblocking behavior of the socket I/O involved in the handshake.

The parameter suppress_ragged_eofs specifies how theSSLSocket.recv() method should signal unexpected EOF from the other endof the connection. If specified as True (the default), it returns anormal EOF (an empty bytes object) in response to unexpected EOF errorsraised from the underlying socket; if False, it will raise theexceptions back to the caller.

session, see session.

在 3.5 版更改: Always allow a server_hostname to be passed, even if OpenSSL does nothave SNI.

在 3.6 版更改: session argument was added.

在 3.7 版更改: The method returns on instance of SSLContext.sslsocket_classinstead of hard-coded SSLSocket.

3.7 新版功能.

  • SSLContext.wrapbio(_incoming, outgoing, server_side=False, server_hostname=None, session=None)
  • Wrap the BIO objects incoming and outgoing and return an instance ofSSLContext.sslobject_class (default SSLObject). The SSLroutines will read input data from the incoming BIO and write data to theoutgoing BIO.

The server_side, server_hostname and session parameters have thesame meaning as in SSLContext.wrap_socket().

在 3.6 版更改: session argument was added.

在 3.7 版更改: The method returns on instance of SSLContext.sslobject_classinstead of hard-coded SSLObject.

3.7 新版功能.

  • SSLContext.session_stats()
  • Get statistics about the SSL sessions created or managed by this context.A dictionary is returned which maps the names of each piece of information to theirnumeric values. For example, here is the total number of hits and missesin the session cache since the context was created:
  1. >>> stats = context.session_stats()
  2. >>> stats['hits'], stats['misses']
  3. (0, 0)

示例:

  1. import socket, ssl
  2.  
  3. context = ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
  4. context.verify_mode = ssl.CERT_REQUIRED
  5. context.check_hostname = True
  6. context.load_default_certs()
  7.  
  8. s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
  9. ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
  10. ssl_sock.connect(('www.verisign.com', 443))

3.4 新版功能.

在 3.7 版更改: verify_mode is now automatically changedto CERT_REQUIRED when hostname checking is enabled andverify_mode is CERT_NONE. Previouslythe same operation would have failed with a ValueError.

注解

This features requires OpenSSL 0.9.8f or newer.

  • SSLContext.keylog_filename
  • Write TLS keys to a keylog file, whenever key material is generated orreceived. The keylog file is designed for debugging purposes only. Thefile format is specified by NSS and used by many traffic analyzers suchas Wireshark. The log file is opened in append-only mode. Writes aresynchronized between threads, but not between processes.

3.8 新版功能.

注解

This features requires OpenSSL 1.1.1 or newer.

The attributes maximum_version,minimum_version andSSLContext.options all affect the supported SSLand TLS versions of the context. The implementation does not preventinvalid combination. For example a context withOP_NO_TLSv1_2 in options andmaximum_version set to TLSVersion.TLSv1_2will not be able to establish a TLS 1.2 connection.

注解

This attribute is not available unless the ssl module is compiledwith OpenSSL 1.1.0g or newer.

3.7 新版功能.

注解

This attribute is not available unless the ssl module is compiledwith OpenSSL 1.1.0g or newer.

3.7 新版功能.

  • SSLContext.num_tickets
  • Control the number of TLS 1.3 session tickets of aTLS_PROTOCOL_SERVER context. The setting has no impact on TLS1.0 to 1.2 connections.

注解

This attribute is not available unless the ssl module is compiledwith OpenSSL 1.1.1 or newer.

3.8 新版功能.

  • SSLContext.options
  • An integer representing the set of SSL options enabled on this context.The default value is OP_ALL, but you can specify other optionssuch as OP_NO_SSLv2 by ORing them together.

注解

With versions of OpenSSL older than 0.9.8m, it is only possibleto set options, not to clear them. Attempting to clear an option(by resetting the corresponding bits) will raise a ValueError.

在 3.6 版更改: SSLContext.options returns Options flags:

  1. >>> ssl.create_default_context().options  # doctest: +SKIP
  2. <Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
  • SSLContext.post_handshake_auth
  • Enable TLS 1.3 post-handshake client authentication. Post-handshake authis disabled by default and a server can only request a TLS clientcertificate during the initial handshake. When enabled, a server mayrequest a TLS client certificate at any time after the handshake.

When enabled on client-side sockets, the client signals the server thatit supports post-handshake authentication.

When enabled on server-side sockets, SSLContext.verify_mode mustbe set to CERT_OPTIONAL or CERT_REQUIRED, too. Theactual client cert exchange is delayed untilSSLSocket.verify_client_post_handshake() is called and some I/O isperformed.

注解

Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3support, the property value is None and can't be modified

3.8 新版功能.

  • SSLContext.protocol

  • The protocol version chosen when constructing the context. This attributeis read-only.

  • SSLContext.hostname_checks_common_name

  • Whether check_hostname falls back to verify the cert'ssubject common name in the absence of a subject alternative nameextension (default: true).

注解

Only writeable with OpenSSL 1.1.0 or higher.

3.7 新版功能.

  • SSLContext.verify_flags
  • The flags for certificate verification operations. You can set flags likeVERIFY_CRL_CHECK_LEAF by ORing them together. By default OpenSSLdoes neither require nor verify certificate revocation lists (CRLs).Available only with openssl version 0.9.8+.

3.4 新版功能.

在 3.6 版更改: SSLContext.verify_flags returns VerifyFlags flags:

  1. >>> ssl.create_default_context().verify_flags  # doctest: +SKIP
  2. <VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>
  • SSLContext.verify_mode
  • Whether to try to verify other peers' certificates and how to behaveif verification fails. This attribute must be one ofCERT_NONE, CERT_OPTIONAL or CERT_REQUIRED.

在 3.6 版更改: SSLContext.verify_mode returns VerifyMode enum:

  1. >>> ssl.create_default_context().verify_mode
  2. <VerifyMode.CERT_REQUIRED: 2>

Certificates

Certificates in general are part of a public-key / private-key system. In thissystem, each principal, (which may be a machine, or a person, or anorganization) is assigned a unique two-part encryption key. One part of the keyis public, and is called the public key; the other part is kept secret, and iscalled the private key. The two parts are related, in that if you encrypt amessage with one of the parts, you can decrypt it with the other part, andonly with the other part.

A certificate contains information about two principals. It contains the nameof a subject, and the subject's public key. It also contains a statement by asecond principal, the issuer, that the subject is who they claim to be, andthat this is indeed the subject's public key. The issuer's statement is signedwith the issuer's private key, which only the issuer knows. However, anyone canverify the issuer's statement by finding the issuer's public key, decrypting thestatement with it, and comparing it to the other information in the certificate.The certificate also contains information about the time period over which it isvalid. This is expressed as two fields, called "notBefore" and "notAfter".

In the Python use of certificates, a client or server can use a certificate toprove who they are. The other side of a network connection can also be requiredto produce a certificate, and that certificate can be validated to thesatisfaction of the client or server that requires such validation. Theconnection attempt can be set to raise an exception if the validation fails.Validation is done automatically, by the underlying OpenSSL framework; theapplication need not concern itself with its mechanics. But the applicationdoes usually need to provide sets of certificates to allow this process to takeplace.

Python uses files to contain certificates. They should be formatted as "PEM"(see RFC 1422), which is a base-64 encoded form wrapped with a header lineand a footer line:

  1. -----BEGIN CERTIFICATE-----
  2. ... (certificate in base64 PEM encoding) ...
  3. -----END CERTIFICATE-----

Certificate chains

The Python files which contain certificates can contain a sequence ofcertificates, sometimes called a certificate chain. This chain should startwith the specific certificate for the principal who "is" the client or server,and then the certificate for the issuer of that certificate, and then thecertificate for the issuer of that certificate, and so on up the chain tillyou get to a certificate which is self-signed, that is, a certificate whichhas the same subject and issuer, sometimes called a root certificate. Thecertificates should just be concatenated together in the certificate file. Forexample, suppose we had a three certificate chain, from our server certificateto the certificate of the certification authority that signed our servercertificate, to the root certificate of the agency which issued thecertification authority's certificate:

  1. -----BEGIN CERTIFICATE-----
  2. ... (certificate for your server)...
  3. -----END CERTIFICATE-----
  4. -----BEGIN CERTIFICATE-----
  5. ... (the certificate for the CA)...
  6. -----END CERTIFICATE-----
  7. -----BEGIN CERTIFICATE-----
  8. ... (the root certificate for the CA's issuer)...
  9. -----END CERTIFICATE-----

CA certificates

If you are going to require validation of the other side of the connection'scertificate, you need to provide a "CA certs" file, filled with the certificatechains for each issuer you are willing to trust. Again, this file just containsthese chains concatenated together. For validation, Python will use the firstchain it finds in the file which matches. The platform's certificates file canbe used by calling SSLContext.load_default_certs(), this is doneautomatically with create_default_context().

Combined key and certificate

Often the private key is stored in the same file as the certificate; in thiscase, only the certfile parameter to SSLContext.load_cert_chain()and wrap_socket() needs to be passed. If the private key is storedwith the certificate, it should come before the first certificate inthe certificate chain:

  1. -----BEGIN RSA PRIVATE KEY-----
  2. ... (private key in base64 encoding) ...
  3. -----END RSA PRIVATE KEY-----
  4. -----BEGIN CERTIFICATE-----
  5. ... (certificate in base64 PEM encoding) ...
  6. -----END CERTIFICATE-----

Self-signed certificates

If you are going to create a server that provides SSL-encrypted connectionservices, you will need to acquire a certificate for that service. There aremany ways of acquiring appropriate certificates, such as buying one from acertification authority. Another common practice is to generate a self-signedcertificate. The simplest way to do this is with the OpenSSL package, usingsomething like the following:

  1. % openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
  2. Generating a 1024 bit RSA private key
  3. .......++++++
  4. .............................++++++
  5. writing new private key to 'cert.pem'
  6. -----
  7. You are about to be asked to enter information that will be incorporated
  8. into your certificate request.
  9. What you are about to enter is what is called a Distinguished Name or a DN.
  10. There are quite a few fields but you can leave some blank
  11. For some fields there will be a default value,
  12. If you enter '.', the field will be left blank.
  13. -----
  14. Country Name (2 letter code) [AU]:US
  15. State or Province Name (full name) [Some-State]:MyState
  16. Locality Name (eg, city) []:Some City
  17. Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
  18. Organizational Unit Name (eg, section) []:My Group
  19. Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
  20. Email Address []:ops@myserver.mygroup.myorganization.com
  21. %

The disadvantage of a self-signed certificate is that it is its own rootcertificate, and no one else will have it in their cache of known (and trusted)root certificates.

示例

Testing for SSL support

To test for the presence of SSL support in a Python installation, user codeshould use the following idiom:

  1. try:
  2.     import ssl
  3. except ImportError:
  4.     pass
  5. else:
  6.     ...  # do something that requires SSL support

Client-side operation

This example creates a SSL context with the recommended security settingsfor client sockets, including automatic certificate verification:

  1. >>> context = ssl.create_default_context()

If you prefer to tune security settings yourself, you might createa context from scratch (but beware that you might not get the settingsright):

  1. >>> context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
  2. >>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

(this snippet assumes your operating system places a bundle of all CAcertificates in /etc/ssl/certs/ca-bundle.crt; if not, you'll get anerror and have to adjust the location)

The PROTOCOL_TLS_CLIENT protocol configures the context for certvalidation and hostname verification. verify_mode isset to CERT_REQUIRED and check_hostname is setto True. All other protocols create SSL contexts with insecure defaults.

When you use the context to connect to a server, CERT_REQUIREDand check_hostname validate the server certificate: itensures that the server certificate was signed with one of the CAcertificates, checks the signature for correctness, and verifies otherproperties like validity and identity of the hostname:

  1. >>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
  2. ...                            server_hostname="www.python.org")
  3. >>> conn.connect(("www.python.org", 443))

You may then fetch the certificate:

  1. >>> cert = conn.getpeercert()

Visual inspection shows that the certificate does identify the desired service(that is, the HTTPS host www.python.org):

  1. >>> pprint.pprint(cert)
  2. {'OCSP': ('http://ocsp.digicert.com',),
  3.  'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
  4.  'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
  5.                            'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
  6.  'issuer': ((('countryName', 'US'),),
  7.             (('organizationName', 'DigiCert Inc'),),
  8.             (('organizationalUnitName', 'www.digicert.com'),),
  9.             (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
  10.  'notAfter': 'Sep  9 12:00:00 2016 GMT',
  11.  'notBefore': 'Sep  5 00:00:00 2014 GMT',
  12.  'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
  13.  'subject': ((('businessCategory', 'Private Organization'),),
  14.              (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
  15.              (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
  16.              (('serialNumber', '3359300'),),
  17.              (('streetAddress', '16 Allen Rd'),),
  18.              (('postalCode', '03894-4801'),),
  19.              (('countryName', 'US'),),
  20.              (('stateOrProvinceName', 'NH'),),
  21.              (('localityName', 'Wolfeboro,'),),
  22.              (('organizationName', 'Python Software Foundation'),),
  23.              (('commonName', 'www.python.org'),)),
  24.  'subjectAltName': (('DNS', 'www.python.org'),
  25.                     ('DNS', 'python.org'),
  26.                     ('DNS', 'pypi.org'),
  27.                     ('DNS', 'docs.python.org'),
  28.                     ('DNS', 'testpypi.org'),
  29.                     ('DNS', 'bugs.python.org'),
  30.                     ('DNS', 'wiki.python.org'),
  31.                     ('DNS', 'hg.python.org'),
  32.                     ('DNS', 'mail.python.org'),
  33.                     ('DNS', 'packaging.python.org'),
  34.                     ('DNS', 'pythonhosted.org'),
  35.                     ('DNS', 'www.pythonhosted.org'),
  36.                     ('DNS', 'test.pythonhosted.org'),
  37.                     ('DNS', 'us.pycon.org'),
  38.                     ('DNS', 'id.python.org')),
  39.  'version': 3}

Now the SSL channel is established and the certificate verified, you canproceed to talk with the server:

  1. >>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
  2. >>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
  3. [b'HTTP/1.1 200 OK',
  4.  b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
  5.  b'Server: nginx',
  6.  b'Content-Type: text/html; charset=utf-8',
  7.  b'X-Frame-Options: SAMEORIGIN',
  8.  b'Content-Length: 45679',
  9.  b'Accept-Ranges: bytes',
  10.  b'Via: 1.1 varnish',
  11.  b'Age: 2188',
  12.  b'X-Served-By: cache-lcy1134-LCY',
  13.  b'X-Cache: HIT',
  14.  b'X-Cache-Hits: 11',
  15.  b'Vary: Cookie',
  16.  b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
  17.  b'Connection: close',
  18.  b'',
  19.  b'']

See the discussion of Security considerations below.

Server-side operation

For server operation, typically you'll need to have a server certificate, andprivate key, each in a file. You'll first create a context holding the keyand the certificate, so that clients can check your authenticity. Thenyou'll open a socket, bind it to a port, call listen() on it, and startwaiting for clients to connect:

  1. import socket, ssl
  2.  
  3. context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
  4. context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")
  5.  
  6. bindsocket = socket.socket()
  7. bindsocket.bind(('myaddr.mydomain.com', 10023))
  8. bindsocket.listen(5)

When a client connects, you'll call accept() on the socket to get thenew socket from the other end, and use the context's SSLContext.wrap_socket()method to create a server-side SSL socket for the connection:

  1. while True:
  2.     newsocket, fromaddr = bindsocket.accept()
  3.     connstream = context.wrap_socket(newsocket, server_side=True)
  4.     try:
  5.         deal_with_client(connstream)
  6.     finally:
  7.         connstream.shutdown(socket.SHUT_RDWR)
  8.         connstream.close()

Then you'll read data from the connstream and do something with it till youare finished with the client (or the client is finished with you):

  1. def deal_with_client(connstream):
  2.     data = connstream.recv(1024)
  3.     # empty data means the client is finished with us
  4.     while data:
  5.         if not do_something(connstream, data):
  6.             # we'll assume do_something returns False
  7.             # when we're finished with client
  8.             break
  9.         data = connstream.recv(1024)
  10.     # finished with client

And go back to listening for new client connections (of course, a real serverwould probably handle each client connection in a separate thread, or putthe sockets in non-blocking mode and use an event loop).

Notes on non-blocking sockets

SSL sockets behave slightly different than regular sockets innon-blocking mode. When working with non-blocking sockets, there arethus several things you need to be aware of:

  • Most SSLSocket methods will raise eitherSSLWantWriteError or SSLWantReadError instead ofBlockingIOError if an I/O operation wouldblock. SSLWantReadError will be raised if a read operation onthe underlying socket is necessary, and SSLWantWriteError fora write operation on the underlying socket. Note that attempts towrite to an SSL socket may require reading from the underlyingsocket first, and attempts to read from the SSL socket may requirea prior write to the underlying socket.

在 3.5 版更改: In earlier Python versions, the SSLSocket.send() methodreturned zero instead of raising SSLWantWriteError orSSLWantReadError.

  • Calling select() tells you that the OS-level socket can beread from (or written to), but it does not imply that there is sufficientdata at the upper SSL layer. For example, only part of an SSL frame mighthave arrived. Therefore, you must be ready to handle SSLSocket.recv()and SSLSocket.send() failures, and retry after another call toselect().

  • Conversely, since the SSL layer has its own framing, a SSL socket maystill have data available for reading without select()being aware of it. Therefore, you should first callSSLSocket.recv() to drain any potentially available data, and thenonly block on a select() call if still necessary.

(of course, similar provisions apply when using other primitives such aspoll(), or those in the selectors module)

  • The SSL handshake itself will be non-blocking: theSSLSocket.do_handshake() method has to be retried until it returnssuccessfully. Here is a synopsis using select() to wait forthe socket's readiness:
  1. while True:
  2.     try:
  3.         sock.do_handshake()
  4.         break
  5.     except ssl.SSLWantReadError:
  6.         select.select([sock], [], [])
  7.     except ssl.SSLWantWriteError:
  8.         select.select([], [sock], [])

参见

The asyncio module supports non-blocking SSL sockets and provides ahigher level API. It polls for events using the selectors module andhandles SSLWantWriteError, SSLWantReadError andBlockingIOError exceptions. It runs the SSL handshake asynchronouslyas well.

Memory BIO Support

3.5 新版功能.

Ever since the SSL module was introduced in Python 2.6, the SSLSocketclass has provided two related but distinct areas of functionality:

  • SSL protocol handling

  • Network IO

The network IO API is identical to that provided by socket.socket,from which SSLSocket also inherits. This allows an SSL socket to beused as a drop-in replacement for a regular socket, making it very easy to addSSL support to an existing application.

Combining SSL protocol handling and network IO usually works well, but thereare some cases where it doesn't. An example is async IO frameworks that want touse a different IO multiplexing model than the "select/poll on a filedescriptor" (readiness based) model that is assumed by socket.socketand by the internal OpenSSL socket IO routines. This is mostly relevant forplatforms like Windows where this model is not efficient. For this purpose, areduced scope variant of SSLSocket called SSLObject isprovided.

  • class ssl.SSLObject
  • A reduced-scope variant of SSLSocket representing an SSL protocolinstance that does not contain any network IO methods. This class istypically used by framework authors that want to implement asynchronous IOfor SSL through memory buffers.

This class implements an interface on top of a low-level SSL object asimplemented by OpenSSL. This object captures the state of an SSL connectionbut does not provide any network IO itself. IO needs to be performed throughseparate "BIO" objects which are OpenSSL's IO abstraction layer.

This class has no public constructor. An SSLObject instancemust be created using the wrap_bio() method. Thismethod will create the SSLObject instance and bind it to apair of BIOs. The incoming BIO is used to pass data from Python to theSSL protocol instance, while the outgoing BIO is used to pass data theother way around.

可以使用以下方法：

When compared to SSLSocket, this object lacks the followingfeatures:

  • Any form of network IO; recv() and send() read and write only tothe underlying MemoryBIO buffers.

  • There is no do_handshake_on_connect machinery. You must always manuallycall do_handshake() to start the handshake.

  • There is no handling of suppress_ragged_eofs. All end-of-file conditionsthat are in violation of the protocol are reported via theSSLEOFError exception.

  • The method unwrap() call does not return anything,unlike for an SSL socket where it returns the underlying socket.

  • The server_name_callback callback passed toSSLContext.set_servername_callback() will get an SSLObjectinstance instead of a SSLSocket instance as its first parameter.

Some notes related to the use of SSLObject:

在 3.7 版更改: SSLObject instances must to created withwrap_bio(). In earlier versions, it was possible tocreate instances directly. This was never documented or officiallysupported.

An SSLObject communicates with the outside world using memory buffers. Theclass MemoryBIO provides a memory buffer that can be used for thispurpose. It wraps an OpenSSL memory BIO (Basic IO) object:

  • class ssl.MemoryBIO

  • A memory buffer that can be used to pass data between Python and an SSLprotocol instance.

    • pending

    • Return the number of bytes currently in the memory buffer.

    • eof

    • A boolean indicating whether the memory BIO is current at the end-of-fileposition.

    • read(n=-1)

    • Read up to n bytes from the memory buffer. If n is not specified ornegative, all bytes are returned.

    • write(buf)

    • Write the bytes from buf to the memory BIO. The buf argument must be anobject supporting the buffer protocol.

The return value is the number of bytes written, which is always equal tothe length of buf.

  • write_eof()
  • Write an EOF marker to the memory BIO. After this method has been called, itis illegal to call write(). The attribute eof willbecome true after all data currently in the buffer has been read.

SSL session

3.6 新版功能.

  • class ssl.SSLSession

  • Session object used by session.

    • id
    • time
    • timeout
    • ticket_lifetime_hint
    • has_ticket

Security considerations

Best defaults

For client use, if you don't have any special requirements for yoursecurity policy, it is highly recommended that you use thecreate_default_context() function to create your SSL context.It will load the system's trusted CA certificates, enable certificatevalidation and hostname checking, and try to choose reasonably secureprotocol and cipher settings.

For example, here is how you would use the smtplib.SMTP class tocreate a trusted, secure connection to a SMTP server:

  1. >>> import ssl, smtplib
  2. >>> smtp = smtplib.SMTP("mail.python.org", port=587)
  3. >>> context = ssl.create_default_context()
  4. >>> smtp.starttls(context=context)
  5. (220, b'2.0.0 Ready to start TLS')

If a client certificate is needed for the connection, it can be added withSSLContext.load_cert_chain().

By contrast, if you create the SSL context by calling the SSLContextconstructor yourself, it will not have certificate validation nor hostnamechecking enabled by default. If you do so, please read the paragraphs belowto achieve a good security level.

Manual settings

Verifying certificates

When calling the SSLContext constructor directly,CERT_NONE is the default. Since it does not authenticate the otherpeer, it can be insecure, especially in client mode where most of time youwould like to ensure the authenticity of the server you're talking to.Therefore, when in client mode, it is highly recommended to useCERT_REQUIRED. However, it is in itself not sufficient; you alsohave to check that the server certificate, which can be obtained by callingSSLSocket.getpeercert(), matches the desired service. For manyprotocols and applications, the service can be identified by the hostname;in this case, the match_hostname() function can be used. This commoncheck is automatically performed when SSLContext.check_hostname isenabled.

在 3.7 版更改: Hostname matchings is now performed by OpenSSL. Python no longer usesmatch_hostname().

In server mode, if you want to authenticate your clients using the SSL layer(rather than using a higher-level authentication mechanism), you'll also haveto specify CERT_REQUIRED and similarly check the client certificate.

Protocol versions

SSL versions 2 and 3 are considered insecure and are therefore dangerous touse. If you want maximum compatibility between clients and servers, it isrecommended to use PROTOCOL_TLS_CLIENT orPROTOCOL_TLS_SERVER as the protocol version. SSLv2 and SSLv3 aredisabled by default.

  1. >>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
  2. >>> client_context.options |= ssl.OP_NO_TLSv1
  3. >>> client_context.options |= ssl.OP_NO_TLSv1_1

The SSL context created above will only allow TLSv1.2 and later (ifsupported by your system) connections to a server. PROTOCOL_TLS_CLIENTimplies certificate validation and hostname checks by default. You have toload certificates into the context.

Cipher selection

If you have advanced security requirements, fine-tuning of the ciphersenabled when negotiating a SSL session is possible through theSSLContext.set_ciphers() method. Starting from Python 3.2.3, thessl module disables certain weak ciphers by default, but you may wantto further restrict the cipher choice. Be sure to read OpenSSL's documentationabout the cipher list format.If you want to check which ciphers are enabled by a given cipher list, useSSLContext.get_ciphers() or the openssl ciphers command on yoursystem.

Multi-processing

If using this module as part of a multi-processed application (using,for example the multiprocessing or concurrent.futures modules),be aware that OpenSSL's internal random number generator does not properlyhandle forked processes. Applications must change the PRNG state of theparent process if they use any SSL feature with os.fork(). Anysuccessful call of RAND_add(), RAND_bytes() orRAND_pseudo_bytes() is sufficient.

TLS 1.3

3.7 新版功能.

Python has provisional and experimental support for TLS 1.3 with OpenSSL1.1.1. The new protocol behaves slightly differently than previous versionof TLS/SSL. Some new TLS 1.3 features are not yet available.

  • TLS 1.3 uses a disjunct set of cipher suites. All AES-GCM andChaCha20 cipher suites are enabled by default. The methodSSLContext.set_ciphers() cannot enable or disable any TLS 1.3ciphers yet, but SSLContext.get_ciphers() returns them.

  • Session tickets are no longer sent as part of the initial handshake andare handled differently. SSLSocket.session and SSLSessionare not compatible with TLS 1.3.

  • Client-side certificates are also no longer verified during the initialhandshake. A server can request a certificate at any time. Clientsprocess certificate requests while they send or receive application datafrom the server.

  • TLS 1.3 features like early data, deferred TLS client cert request,signature algorithm configuration, and rekeying are not supported yet.

LibreSSL support

LibreSSL is a fork of OpenSSL 1.0.1. The ssl module has limited support forLibreSSL. Some features are not available when the ssl module is compiledwith LibreSSL.

参见