.. _openssl-ssl: :py:mod:`SSL` --- An interface to the SSL-specific parts of OpenSSL =================================================================== .. py:module:: OpenSSL.SSL :synopsis: An interface to the SSL-specific parts of OpenSSL This module handles things specific to SSL. There are two objects defined: Context, Connection. .. py:data:: TLS_METHOD TLS_SERVER_METHOD TLS_CLIENT_METHOD SSLv2_METHOD SSLv3_METHOD SSLv23_METHOD TLSv1_METHOD TLSv1_1_METHOD TLSv1_2_METHOD These constants represent the different SSL methods to use when creating a context object. New code should only use ``TLS_METHOD``, ``TLS_SERVER_METHOD``, or ``TLS_CLIENT_METHOD``. If the underlying OpenSSL build is missing support for any of these protocols, constructing a :py:class:`Context` using the corresponding :py:const:`*_METHOD` will raise an exception. .. py:data:: SSL3_VERSION TLS1_VERSION TLS1_1_VERSION TLS1_2_VERSION TLS1_3_VERSION These constants represent the different TLS versions to use when setting the minimum or maximum TLS version. .. py:data:: VERIFY_NONE VERIFY_PEER VERIFY_FAIL_IF_NO_PEER_CERT These constants represent the verification mode used by the Context object's :py:meth:`set_verify` method. .. py:data:: FILETYPE_PEM FILETYPE_ASN1 File type constants used with the :py:meth:`use_certificate_file` and :py:meth:`use_privatekey_file` methods of Context objects. .. py:data:: OP_SINGLE_DH_USE OP_SINGLE_ECDH_USE Constants used with :py:meth:`set_options` of Context objects. When these options are used, a new key will always be created when using ephemeral (Elliptic curve) Diffie-Hellman. .. py:data:: OP_EPHEMERAL_RSA Constant used with :py:meth:`set_options` of Context objects. When this option is used, ephemeral RSA keys will always be used when doing RSA operations. .. py:data:: OP_NO_TICKET Constant used with :py:meth:`set_options` of Context objects. When this option is used, the session ticket extension will not be used. .. py:data:: OP_NO_COMPRESSION Constant used with :py:meth:`set_options` of Context objects. When this option is used, compression will not be used. .. py:data:: OP_NO_SSLv2 OP_NO_SSLv3 OP_NO_TLSv1 OP_NO_TLSv1_1 OP_NO_TLSv1_2 OP_NO_TLSv1_3 Constants used with :py:meth:`set_options` of Context objects. Each of these options disables one version of the SSL/TLS protocol. This is interesting if you're using e.g. :py:const:`SSLv23_METHOD` to get an SSLv2-compatible handshake, but don't want to use SSLv2. If the underlying OpenSSL build is missing support for any of these protocols, the :py:const:`OP_NO_*` constant may be undefined. .. py:data:: OPENSSL_VERSION OPENSSL_CFLAGS OPENSSL_BUILT_ON OPENSSL_PLATFORM OPENSSL_DIR .. versionchanged:: 22.1.0 Previously these were all named ``SSLEAY_*``. Those names are still available for backwards compatibility, but the ``OPENSSL_*`` names are preferred. Constants used with :py:meth:`OpenSSL_version` to specify what OpenSSL version information to retrieve. See the man page for the :py:func:`OpenSSL_version` C API for details. .. py:data:: SESS_CACHE_OFF SESS_CACHE_CLIENT SESS_CACHE_SERVER SESS_CACHE_BOTH SESS_CACHE_NO_AUTO_CLEAR SESS_CACHE_NO_INTERNAL_LOOKUP SESS_CACHE_NO_INTERNAL_STORE SESS_CACHE_NO_INTERNAL Constants used with :py:meth:`Context.set_session_cache_mode` to specify the behavior of the session cache and potential session reuse. See the man page for the :py:func:`SSL_CTX_set_session_cache_mode` C API for details. .. versionadded:: 0.14 .. py:data:: OPENSSL_VERSION_NUMBER An integer giving the version number of the OpenSSL library used to build this version of pyOpenSSL. See the man page for the :py:func:`SSLeay_version` C API for details. .. py:data:: NO_OVERLAPPING_PROTOCOLS A sentinel value that can be returned by the callback passed to :py:meth:`Context.set_alpn_select_callback` to indicate that the handshake can continue without a specific application protocol. .. versionadded:: 19.1 .. autofunction:: OpenSSL_version .. py:data:: ContextType See :py:class:`Context`. .. autoclass:: Context :noindex: .. autoclass:: Session .. py:data:: ConnectionType See :py:class:`Connection`. .. py:class:: Connection(context, socket) :noindex: A class representing SSL connections. *context* should be an instance of :py:class:`Context` and *socket* should be a socket [#connection-context-socket]_ object. *socket* may be *None*; in this case, the Connection is created with a memory BIO: see the :py:meth:`bio_read`, :py:meth:`bio_write`, and :py:meth:`bio_shutdown` methods. .. py:exception:: Error This exception is used as a base class for the other SSL-related exceptions, but may also be raised directly. Whenever this exception is raised directly, it has a list of error messages from the OpenSSL error queue, where each item is a tuple *(lib, function, reason)*. Here *lib*, *function* and *reason* are all strings, describing where and what the problem is. See :manpage:`err(3)` for more information. .. py:exception:: ZeroReturnError This exception matches the error return code :py:data:`SSL_ERROR_ZERO_RETURN`, and is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this only occurs if a closure alert has occurred in the protocol, i.e. the connection has been closed cleanly. Note that this does not necessarily mean that the transport layer (e.g. a socket) has been closed. It may seem a little strange that this is an exception, but it does match an :py:data:`SSL_ERROR` code, and is very convenient. .. py:exception:: WantReadError The operation did not complete; the same I/O method should be called again later, with the same arguments. Any I/O method can lead to this since new handshakes can occur at any time. The wanted read is for **dirty** data sent over the network, not the **clean** data inside the tunnel. For a socket based SSL connection, **read** means data coming at us over the network. Until that read succeeds, the attempted :py:meth:`OpenSSL.SSL.Connection.recv`, :py:meth:`OpenSSL.SSL.Connection.send`, or :py:meth:`OpenSSL.SSL.Connection.do_handshake` is prevented or incomplete. You probably want to :py:meth:`select()` on the socket before trying again. .. py:exception:: WantWriteError See :py:exc:`WantReadError`. The socket send buffer may be too full to write more data. .. py:exception:: WantX509LookupError The operation did not complete because an application callback has asked to be called again. The I/O method should be called again later, with the same arguments. .. note:: This won't occur in this version, as there are no such callbacks in this version. .. py:exception:: SysCallError The :py:exc:`SysCallError` occurs when there's an I/O error and OpenSSL's error queue does not contain any information. This can mean two things: An error in the transport protocol, or an end of file that violates the protocol. The parameter to the exception is always a pair *(errnum, errstr)*. .. _openssl-context: Context objects --------------- Context objects have the following methods: .. autoclass:: OpenSSL.SSL.Context :members: .. _openssl-session: Session objects --------------- Session objects have no methods. .. _openssl-connection: Connection objects ------------------ Connection objects have the following methods: .. autoclass:: OpenSSL.SSL.Connection :members: .. Rubric:: Footnotes .. [#connection-context-socket] Actually, all that is required is an object that **behaves** like a socket, you could even use files, even though it'd be tricky to get the handshakes right!