`SSL` — An interface to the SSL-specific parts of OpenSSL¶

This module handles things specific to SSL. There are two objects defined: Context, Connection.

OpenSSL.SSL.TLS_METHOD¶
OpenSSL.SSL.TLS_SERVER_METHOD¶
OpenSSL.SSL.TLS_CLIENT_METHOD¶
OpenSSL.SSL.SSLv2_METHOD¶
OpenSSL.SSL.SSLv3_METHOD¶
OpenSSL.SSL.SSLv23_METHOD¶
OpenSSL.SSL.TLSv1_METHOD¶
OpenSSL.SSL.TLSv1_1_METHOD¶
OpenSSL.SSL.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 Context using the corresponding *_METHOD will raise an exception.

OpenSSL.SSL.SSL3_VERSION¶
OpenSSL.SSL.TLS1_VERSION¶
OpenSSL.SSL.TLS1_1_VERSION¶
OpenSSL.SSL.TLS1_2_VERSION¶
OpenSSL.SSL.TLS1_3_VERSION¶: These constants represent the different TLS versions to use when setting the minimum or maximum TLS version.

OpenSSL.SSL.VERIFY_NONE¶
OpenSSL.SSL.VERIFY_PEER¶
OpenSSL.SSL.VERIFY_FAIL_IF_NO_PEER_CERT¶: These constants represent the verification mode used by the Context object’s set_verify() method.

OpenSSL.SSL.FILETYPE_PEM¶
OpenSSL.SSL.FILETYPE_ASN1¶: File type constants used with the use_certificate_file() and use_privatekey_file() methods of Context objects.

OpenSSL.SSL.OP_SINGLE_DH_USE¶

OpenSSL.SSL.OP_SINGLE_ECDH_USE¶

Constants used with set_options() of Context objects.

When these options are used, a new key will always be created when using ephemeral (Elliptic curve) Diffie-Hellman.

OpenSSL.SSL.OP_EPHEMERAL_RSA¶

Constant used with set_options() of Context objects.

When this option is used, ephemeral RSA keys will always be used when doing RSA operations.

OpenSSL.SSL.OP_NO_TICKET¶

Constant used with set_options() of Context objects.

When this option is used, the session ticket extension will not be used.

OpenSSL.SSL.OP_NO_COMPRESSION¶

Constant used with set_options() of Context objects.

When this option is used, compression will not be used.

OpenSSL.SSL.OP_NO_SSLv2¶

OpenSSL.SSL.OP_NO_SSLv3¶

OpenSSL.SSL.OP_NO_TLSv1¶

OpenSSL.SSL.OP_NO_TLSv1_1¶

OpenSSL.SSL.OP_NO_TLSv1_2¶

OpenSSL.SSL.OP_NO_TLSv1_3¶

Constants used with 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. 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 OP_NO_* constant may be undefined.

OpenSSL.SSL.OPENSSL_VERSION¶
OpenSSL.SSL.OPENSSL_CFLAGS¶
OpenSSL.SSL.OPENSSL_BUILT_ON¶
OpenSSL.SSL.OPENSSL_PLATFORM¶
OpenSSL.SSL.OPENSSL_DIR¶: Changed in version 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 OpenSSL_version() to specify what OpenSSL version information to retrieve. See the man page for the OpenSSL_version() C API for details.

OpenSSL.SSL.SESS_CACHE_OFF¶
OpenSSL.SSL.SESS_CACHE_CLIENT¶
OpenSSL.SSL.SESS_CACHE_SERVER¶
OpenSSL.SSL.SESS_CACHE_BOTH¶
OpenSSL.SSL.SESS_CACHE_NO_AUTO_CLEAR¶
OpenSSL.SSL.SESS_CACHE_NO_INTERNAL_LOOKUP¶
OpenSSL.SSL.SESS_CACHE_NO_INTERNAL_STORE¶
OpenSSL.SSL.SESS_CACHE_NO_INTERNAL¶: Constants used with Context.set_session_cache_mode() to specify the behavior of the session cache and potential session reuse. See the man page for the SSL_CTX_set_session_cache_mode() C API for details.

New in version 0.14.

OpenSSL.SSL.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 SSLeay_version() C API for details.

OpenSSL.SSL.NO_OVERLAPPING_PROTOCOLS¶: A sentinel value that can be returned by the callback passed to Context.set_alpn_select_callback() to indicate that the handshake can continue without a specific application protocol.

New in version 19.1.

OpenSSL.SSL.OpenSSL_version(type)¶

Return a string describing the version of OpenSSL in use.

Parameters: type – One of the OPENSSL_ constants defined in this module.

OpenSSL.SSL.ContextType¶: See Context.

class OpenSSL.SSL.Context(method)

OpenSSL.SSL.Context instances define the parameters for setting up new SSL connections.

Parameters: method – One of TLS_METHOD, TLS_CLIENT_METHOD, TLS_SERVER_METHOD, DTLS_METHOD, DTLS_CLIENT_METHOD, or DTLS_SERVER_METHOD. SSLv23_METHOD, TLSv1_METHOD, etc. are deprecated and should not be used.

class OpenSSL.SSL.Session¶: A class representing an SSL session. A session defines certain connection parameters which may be re-used to speed up the setup of subsequent connections.

New in version 0.14.

OpenSSL.SSL.ConnectionType¶: See Connection.

class OpenSSL.SSL.Connection(context, socket): A class representing SSL connections.

context should be an instance of Context and socket should be a socket 1 object. socket may be None; in this case, the Connection is created with a memory BIO: see the bio_read(), bio_write(), and bio_shutdown() methods.

exception OpenSSL.SSL.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 err(3) for more information.

exception OpenSSL.SSL.ZeroReturnError¶

This exception matches the error return code 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 SSL_ERROR code, and is very convenient.

exception OpenSSL.SSL.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 OpenSSL.SSL.Connection.recv(), OpenSSL.SSL.Connection.send(), or OpenSSL.SSL.Connection.do_handshake() is prevented or incomplete. You probably want to select() on the socket before trying again.

exception OpenSSL.SSL.WantWriteError¶: See WantReadError. The socket send buffer may be too full to write more data.

exception OpenSSL.SSL.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.

exception OpenSSL.SSL.SysCallError¶: The 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).

Context objects¶

Context objects have the following methods:

class OpenSSL.SSL.Context(method)¶

OpenSSL.SSL.Context instances define the parameters for setting up new SSL connections.

Parameters: method – One of TLS_METHOD, TLS_CLIENT_METHOD, TLS_SERVER_METHOD, DTLS_METHOD, DTLS_CLIENT_METHOD, or DTLS_SERVER_METHOD. SSLv23_METHOD, TLSv1_METHOD, etc. are deprecated and should not be used.

add_client_ca(certificate_authority)¶

Add the CA certificate to the list of preferred signers for this context.

The list of certificate authorities will be sent to the client when the server requests a client certificate.

Parameters: certificate_authority – certificate authority’s X509 certificate.
Returns: None

New in version 0.10.

add_extra_chain_cert(certobj)¶

Add certificate to chain

Parameters: certobj – The X509 certificate object to add to the chain
Returns: None

check_privatekey()¶

Check if the private key (loaded with use_privatekey()) matches the certificate (loaded with use_certificate())

Returns: None (raises Error if something’s wrong)

get_app_data()¶

Get the application data (supplied via set_app_data())

Returns: The application data

get_cert_store()¶

Get the certificate store for the context. This can be used to add “trusted” certificates without using the load_verify_locations() method.

Returns: A X509Store object or None if it does not have one.

get_session_cache_mode()¶

Get the current session cache mode.

Returns: The currently used cache mode.

New in version 0.14.

get_timeout()¶

Retrieve session timeout, as set by set_timeout(). The default is 300 seconds.

Returns: The session timeout

get_verify_depth()¶

Retrieve the Context object’s verify depth, as set by set_verify_depth().

Returns: The verify depth

get_verify_mode()¶

Retrieve the Context object’s verify mode, as set by set_verify().

Returns: The verify mode

load_client_ca(cafile)¶

Load the trusted certificates that will be sent to the client. Does not actually imply any of the certificates are trusted; that must be configured separately.

Parameters: cafile (bytes) – The path to a certificates file in PEM format.
Returns: None

load_tmp_dh(dhfile)¶

Load parameters for Ephemeral Diffie-Hellman

Parameters: dhfile – The file to load EDH parameters from (bytes or unicode).
Returns: None

load_verify_locations(cafile, capath=None)¶

Let SSL know where we can find trusted certificates for the certificate chain. Note that the certificates have to be in PEM format.

If capath is passed, it must be a directory prepared using the c_rehash tool included with OpenSSL. Either, but not both, of pemfile or capath may be None.

Parameters

cafile – In which file we can find the certificates (bytes or unicode).
capath – In which directory we can find the certificates (bytes or unicode).

Returns

None

set_alpn_protos(protos)¶

Specify the protocols that the client is prepared to speak after the TLS connection has been negotiated using Application Layer Protocol Negotiation.

Parameters: protos – A list of the protocols to be offered to the server. This list should be a Python list of bytestrings representing the protocols to offer, e.g. [b'http/1.1', b'spdy/2'].

set_alpn_select_callback(callback)¶

Specify a callback function that will be called on the server when a client offers protocols using ALPN.

Parameters: callback – The callback function. It will be invoked with two arguments: the Connection, and a list of offered protocols as bytestrings, e.g [b'http/1.1', b'spdy/2']. It can return one of those bytestrings to indicate the chosen protocol, the empty bytestring to terminate the TLS connection, or the NO_OVERLAPPING_PROTOCOLS to indicate that no offered protocol was selected, but that the connection should not be aborted.

set_app_data(data)¶

Set the application data (will be returned from get_app_data())

Parameters: data – Any Python object
Returns: None

set_cipher_list(cipher_list)¶

Set the list of ciphers to be used in this context.

See the OpenSSL manual for more information (e.g. ciphers(1)).

Parameters: cipher_list (bytes) – An OpenSSL cipher string.
Returns: None

set_client_ca_list(certificate_authorities)¶

Set the list of preferred client certificate signers for this server context.

This list of certificate authorities will be sent to the client when the server requests a client certificate.

Parameters: certificate_authorities – a sequence of X509Names.
Returns: None

New in version 0.10.

set_default_verify_paths()¶

Specify that the platform provided CA certificates are to be used for verification purposes. This method has some caveats related to the binary wheels that cryptography (pyOpenSSL’s primary dependency) ships:

macOS will only load certificates using this method if the user has the openssl@1.1 Homebrew formula installed in the default location.
Windows will not work.
manylinux1 cryptography wheels will work on most common Linux distributions in pyOpenSSL 17.1.0 and above. pyOpenSSL detects the manylinux1 wheel and attempts to load roots via a fallback path.

Returns: None

set_info_callback(callback)¶

Set the information callback to callback. This function will be called from time to time during SSL handshakes.

Parameters: callback – The Python callback to use. This should take three arguments: a Connection object and two integers. The first integer specifies where in the SSL handshake the function was called, and the other the return code from a (possibly failed) internal function call.
Returns: None

set_keylog_callback(callback)¶

Set the TLS key logging callback to callback. This function will be called whenever TLS key material is generated or received, in order to allow applications to store this keying material for debugging purposes.

Parameters: callback – The Python callback to use. This should take two arguments: a Connection object and a bytestring that contains the key material in the format used by NSS for its SSLKEYLOGFILE debugging output.
Returns: None

set_max_proto_version(version)¶

Set the maximum supported protocol version. Setting the maximum version to 0 will enable protocol versions up to the highest version supported by the library.

If the underlying OpenSSL build is missing support for the selected version, this method will raise an exception.

set_min_proto_version(version)¶

Set the minimum supported protocol version. Setting the minimum version to 0 will enable protocol versions down to the lowest version supported by the library.

If the underlying OpenSSL build is missing support for the selected version, this method will raise an exception.

set_mode(mode)¶

Add modes via bitmask. Modes set before are not cleared! This method should be used with the MODE_* constants.

Parameters: mode – The mode to add.
Returns: The new mode bitmask.

set_ocsp_client_callback(callback, data=None)¶

Set a callback to validate OCSP data stapled to the TLS handshake on the client side.

Parameters

callback – The callback function. It will be invoked with three arguments: the Connection, a bytestring containing the stapled OCSP assertion, and the optional arbitrary data you have provided. The callback must return a boolean that indicates the result of validating the OCSP data: True if the OCSP data is valid and the certificate can be trusted, or False if either the OCSP data is invalid or the certificate has been revoked.
data – Some opaque data that will be passed into the callback function when called. This can be used to avoid needing to do complex data lookups or to keep track of what context is being used. This parameter is optional.

set_ocsp_server_callback(callback, data=None)¶

Set a callback to provide OCSP data to be stapled to the TLS handshake on the server side.

Parameters

callback – The callback function. It will be invoked with two arguments: the Connection, and the optional arbitrary data you have provided. The callback must return a bytestring that contains the OCSP data to staple to the handshake. If no OCSP data is available for this connection, return the empty bytestring.
data – Some opaque data that will be passed into the callback function when called. This can be used to avoid needing to do complex data lookups or to keep track of what context is being used. This parameter is optional.

set_options(options)¶

Add options. Options set before are not cleared! This method should be used with the OP_* constants.

Parameters: options – The options to add.
Returns: The new option bitmask.

set_passwd_cb(callback, userdata=None)¶

Set the passphrase callback. This function will be called when a private key with a passphrase is loaded.

Parameters

callback – The Python callback to use. This must accept three positional arguments. First, an integer giving the maximum length of the passphrase it may return. If the returned passphrase is longer than this, it will be truncated. Second, a boolean value which will be true if the user should be prompted for the passphrase twice and the callback should verify that the two values supplied are equal. Third, the value given as the userdata parameter to set_passwd_cb(). The callback must return a byte string. If an error occurs, callback should return a false value (e.g. an empty string).
userdata – (optional) A Python object which will be given as argument to the callback

Returns

None

set_session_cache_mode(mode)¶

Set the behavior of the session cache used by all connections using this Context. The previously set mode is returned. See SESS_CACHE_* for details about particular modes.

Parameters: mode – One or more of the SESS_CACHE_* flags (combine using bitwise or)
Returns: The previously set caching mode.

New in version 0.14.

set_session_id(buf)¶

Set the session id to buf within which a session can be reused for this Context object. This is needed when doing session resumption, because there is no way for a stored session to know which Context object it is associated with.

Parameters: buf (bytes) – The session id.
Returns: None

set_timeout(timeout)¶

Set the timeout for newly created sessions for this Context object to timeout. The default value is 300 seconds. See the OpenSSL manual for more information (e.g. SSL_CTX_set_timeout(3)).

Parameters: timeout – The timeout in (whole) seconds
Returns: The previous session timeout

set_tlsext_servername_callback(callback)¶

Specify a callback function to be called when clients specify a server name.

Parameters: callback – The callback function. It will be invoked with one argument, the Connection instance.

New in version 0.13.

set_tlsext_use_srtp(profiles)¶

Enable support for negotiating SRTP keying material.

Parameters: profiles (bytes) – A colon delimited list of protection profile names, like b'SRTP_AES128_CM_SHA1_80:SRTP_AES128_CM_SHA1_32'.
Returns: None

set_tmp_ecdh(curve)¶

Select a curve to use for ECDHE key exchange.

Parameters: curve – A curve object to use as returned by either OpenSSL.crypto.get_elliptic_curve() or OpenSSL.crypto.get_elliptic_curves().
Returns: None

set_verify(mode, callback=None)¶

Set the verification flags for this Context object to mode and specify that callback should be used for verification callbacks.

Parameters

mode – The verify mode, this should be one of VERIFY_NONE and VERIFY_PEER. If VERIFY_PEER is used, mode can be OR:ed with VERIFY_FAIL_IF_NO_PEER_CERT and VERIFY_CLIENT_ONCE to further control the behaviour.
callback – The optional Python verification callback to use. This should take five arguments: A Connection object, an X509 object, and three integer variables, which are in turn potential error number, error depth and return code. callback should return True if verification passes and False otherwise. If omitted, OpenSSL’s default verification is used.

Returns

None

See SSL_CTX_set_verify(3SSL) for further details.

set_verify_depth(depth)¶

Set the maximum depth for the certificate chain verification that shall be allowed for this Context object.

Parameters: depth – An integer specifying the verify depth
Returns: None

use_certificate(cert)¶

Load a certificate from a X509 object

Parameters: cert – The X509 object
Returns: None

use_certificate_chain_file(certfile)¶

Load a certificate chain from a file.

Parameters: certfile – The name of the certificate chain file (bytes or unicode). Must be PEM encoded.
Returns: None

use_certificate_file(certfile, filetype=1)¶

Load a certificate from a file

Parameters

certfile – The name of the certificate file (bytes or unicode).
filetype – (optional) The encoding of the file, which is either FILETYPE_PEM or FILETYPE_ASN1. The default is FILETYPE_PEM.

Returns

None

use_privatekey(pkey)¶

Load a private key from a PKey object

Parameters: pkey – The PKey object
Returns: None

use_privatekey_file(keyfile, filetype=<object object>)¶

Load a private key from a file

Parameters

keyfile – The name of the key file (bytes or unicode)
filetype – (optional) The encoding of the file, which is either FILETYPE_PEM or FILETYPE_ASN1. The default is FILETYPE_PEM.

Returns

None

Session objects¶

Session objects have no methods.

Connection objects¶

Connection objects have the following methods:

class OpenSSL.SSL.Connection(context, socket=None)¶

DTLSv1_listen()¶

Call the OpenSSL function DTLSv1_listen on this connection. See the OpenSSL manual for more details.

Returns: None

accept()¶

Call the accept() method of the underlying socket and set up SSL on the returned socket, using the Context object supplied to this Connection object at creation.

Returns: A (conn, addr) pair where conn is the new Connection object created, and address is as returned by the socket’s accept().

bio_read(bufsiz)¶

If the Connection was created with a memory BIO, this method can be used to read bytes from the write end of that memory BIO. Many Connection methods will add bytes which must be read in this manner or the buffer will eventually fill up and the Connection will be able to take no further actions.

Parameters: bufsiz – The maximum number of bytes to read
Returns: The string read.

bio_shutdown()¶

If the Connection was created with a memory BIO, this method can be used to indicate that end of file has been reached on the read end of that memory BIO.

Returns: None

bio_write(buf)¶

If the Connection was created with a memory BIO, this method can be used to add bytes to the read end of that memory BIO. The Connection can then read the bytes (for example, in response to a call to recv()).

Parameters: buf – The string to put into the memory BIO.
Returns: The number of bytes written

client_random()¶

Retrieve the random value used with the client hello message.

Returns: A string representing the state

connect(addr)¶

Call the connect() method of the underlying socket and set up SSL on the socket, using the Context object supplied to this Connection object at creation.

Parameters: addr – A remote address
Returns: What the socket’s connect method returns

connect_ex(addr)¶

Call the connect_ex() method of the underlying socket and set up SSL on the socket, using the Context object supplied to this Connection object at creation. Note that if the connect_ex() method of the socket doesn’t return 0, SSL won’t be initialized.

Parameters: addr – A remove address
Returns: What the socket’s connect_ex method returns

do_handshake()¶

Perform an SSL handshake (usually called after renegotiate() or one of set_accept_state() or set_connect_state()). This can raise the same exceptions as send() and recv().

Returns: None.

export_keying_material(label, olen, context=None)¶

Obtain keying material for application use.

Param: label - a disambiguating label string as described in RFC 5705
Param: olen - the length of the exported key material in bytes
Param: context - a per-association context value
Returns: the exported key material bytes or None

get_alpn_proto_negotiated()¶

Get the protocol that was negotiated by ALPN.

Returns: A bytestring of the protocol name. If no protocol has been negotiated yet, returns an empty bytestring.

get_app_data()¶

Retrieve application data as set by set_app_data().

Returns: The application data

get_certificate()¶

Retrieve the local certificate (if any)

Returns: The local certificate

get_cipher_bits()¶

Obtain the number of secret bits of the currently used cipher.

Returns: The number of secret bits of the currently used cipher or None if no connection has been established.
Return type: int or NoneType

New in version 0.15.

get_cipher_list()¶

Retrieve the list of ciphers used by the Connection object.

Returns: A list of native cipher strings.

get_cipher_name()¶

Obtain the name of the currently used cipher.

Returns: The name of the currently used cipher or None if no connection has been established.
Return type: unicode or NoneType

New in version 0.15.

get_cipher_version()¶

Obtain the protocol version of the currently used cipher.

Returns: The protocol name of the currently used cipher or None if no connection has been established.
Return type: unicode or NoneType

New in version 0.15.

get_cleartext_mtu()¶

For DTLS, get the maximum size of unencrypted data you can pass to write() without exceeding the MTU (as passed to set_ciphertext_mtu()).

Returns: The effective MTU as an integer.

New in version 21.1.

get_client_ca_list()¶

Get CAs whose certificates are suggested for client authentication.

Returns

If this is a server connection, the list of certificate authorities that will be sent or has been sent to the client, as controlled by this Connection’s Context.

If this is a client connection, the list will be empty until the connection with the server is established.

New in version 0.10.

get_context()¶: Retrieve the Context object associated with this Connection.

get_finished()¶

Obtain the latest TLS Finished message that we sent.

Returns: The contents of the message or None if the TLS handshake has not yet completed.
Return type: bytes or NoneType

New in version 0.15.

get_peer_cert_chain()¶

Retrieve the other side’s certificate (if any)

Returns: A list of X509 instances giving the peer’s certificate chain, or None if it does not have one.

get_peer_certificate()¶

Retrieve the other side’s certificate (if any)

Returns: The peer’s certificate

get_peer_finished()¶

Obtain the latest TLS Finished message that we received from the peer.

Returns: The contents of the message or None if the TLS handshake has not yet completed.
Return type: bytes or NoneType

New in version 0.15.

get_protocol_version()¶

Retrieve the SSL or TLS protocol version of the current connection.

Returns: The TLS version of the current connection. For example, it will return 0x769 for connections made over TLS version 1.
Return type: int

get_protocol_version_name()¶

Retrieve the protocol version of the current connection.

Returns: The TLS version of the current connection, for example the value for TLS 1.2 would be TLSv1.2``or ``Unknown for connections that were not successfully established.
Return type: unicode

get_servername()¶

Retrieve the servername extension value if provided in the client hello message, or None if there wasn’t one.

Returns: A byte string giving the server name or None.

New in version 0.13.

get_session()¶

Returns the Session currently used.

Returns: An instance of OpenSSL.SSL.Session or None if no session exists.

New in version 0.14.

get_shutdown()¶

Get the shutdown state of the Connection.

Returns: The shutdown state, a bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.

get_state_string()¶

Retrieve a verbose string detailing the state of the Connection.

Returns: A string representing the state
Return type: bytes

get_verified_chain()¶

Retrieve the verified certificate chain of the peer including the peer’s end entity certificate. It must be called after a session has been successfully established. If peer verification was not successful the chain may be incomplete, invalid, or None.

Returns: A list of X509 instances giving the peer’s verified certificate chain, or None if it does not have one.

New in version 20.0.

get_verify_mode()¶

Retrieve the Connection object’s verify mode, as set by set_verify().

Returns: The verify mode

makefile(*args, **kwargs)¶

The makefile() method is not implemented, since there is no dup semantics for SSL connections

Raise: NotImplementedError

master_key()¶

Retrieve the value of the master key for this session.

Returns: A string representing the state

pending()¶

Get the number of bytes that can be safely read from the SSL buffer (not the underlying transport buffer).

Returns: The number of bytes available in the receive buffer.

read(bufsiz, flags=None)¶

Receive data on the connection.

Parameters

bufsiz – The maximum number of bytes to read
flags – (optional) The only supported flag is MSG_PEEK, all other flags are ignored.

Returns

The string read from the Connection

recv(bufsiz, flags=None)¶

Receive data on the connection.

Parameters

bufsiz – The maximum number of bytes to read
flags – (optional) The only supported flag is MSG_PEEK, all other flags are ignored.

Returns

The string read from the Connection

recv_into(buffer, nbytes=None, flags=None)¶

Receive data on the connection and copy it directly into the provided buffer, rather than creating a new string.

Parameters

buffer – The buffer to copy into.
nbytes – (optional) The maximum number of bytes to read into the buffer. If not present, defaults to the size of the buffer. If larger than the size of the buffer, is reduced to the size of the buffer.
flags – (optional) The only supported flag is MSG_PEEK, all other flags are ignored.

Returns

The number of bytes read into the buffer.

renegotiate()¶

Renegotiate the session.

Returns: True if the renegotiation can be started, False otherwise
Return type: bool

renegotiate_pending()¶

Check if there’s a renegotiation in progress, it will return False once a renegotiation is finished.

Returns: Whether there’s a renegotiation in progress
Return type: bool

request_ocsp()¶: Called to request that the server sends stapled OCSP data, if available. If this is not called on the client side then the server will not send OCSP data. Should be used in conjunction with Context.set_ocsp_client_callback().

send(buf, flags=0)¶

Send data on the connection. NOTE: If you get one of the WantRead, WantWrite or WantX509Lookup exceptions on this, you have to call the method again with the SAME buffer.

Parameters

buf – The string, buffer or memoryview to send
flags – (optional) Included for compatibility with the socket API, the value is ignored

Returns

The number of bytes written

sendall(buf, flags=0)¶

Send “all” data on the connection. This calls send() repeatedly until all data is sent. If an error occurs, it’s impossible to tell how much data has been sent.

Parameters

buf – The string, buffer or memoryview to send
flags – (optional) Included for compatibility with the socket API, the value is ignored

Returns

The number of bytes written

server_random()¶

Retrieve the random value used with the server hello message.

Returns: A string representing the state

set_accept_state()¶

Set the connection to work in server mode. The handshake will be handled automatically by read/write.

Returns: None

set_alpn_protos(protos)¶

Specify the client’s ALPN protocol list.

These protocols are offered to the server during protocol negotiation.

Parameters: protos – A list of the protocols to be offered to the server. This list should be a Python list of bytestrings representing the protocols to offer, e.g. [b'http/1.1', b'spdy/2'].

set_app_data(data)¶

Set application data

Parameters: data – The application data
Returns: None

set_ciphertext_mtu(mtu)¶

For DTLS, set the maximum UDP payload size (not including IP/UDP overhead).

Note that you might have to set OP_NO_QUERY_MTU to prevent OpenSSL from spontaneously clearing this.

Parameters: mtu – An integer giving the maximum transmission unit.

New in version 21.1.

set_connect_state()¶

Set the connection to work in client mode. The handshake will be handled automatically by read/write.

Returns: None

set_context(context)¶

Switch this connection to a new session context.

Parameters: context – A Context instance giving the new session context to use.

set_session(session)¶

Set the session to be used when the TLS/SSL connection is established.

Parameters: session – A Session instance representing the session to use.
Returns: None

New in version 0.14.

set_shutdown(state)¶

Set the shutdown state of the Connection.

Parameters: state – bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.
Returns: None

set_tlsext_host_name(name)¶

Set the value of the servername extension to send in the client hello.

Parameters: name – A byte string giving the name.

New in version 0.13.

set_verify(mode, callback=None)¶: Override the Context object’s verification flags for this specific connection. See Context.set_verify() for details.

shutdown()¶

Send the shutdown message to the Connection.

Returns: True if the shutdown completed successfully (i.e. both sides have sent closure alerts), False otherwise (in which case you call recv() or send() when the connection becomes readable/writeable).

sock_shutdown(*args, **kwargs)¶

Call the shutdown() method of the underlying socket. See shutdown(2).

Returns: What the socket’s shutdown() method returns

total_renegotiations()¶

Find out the total number of renegotiations.

Returns: The number of renegotiations.
Return type: int

use_certificate(cert)¶

Load a certificate from a X509 object

Parameters: cert – The X509 object
Returns: None

use_privatekey(pkey)¶

Load a private key from a PKey object

Parameters: pkey – The PKey object
Returns: None

want_read()¶

Checks if more data has to be read from the transport layer to complete an operation.

Returns: True iff more data has to be read

want_write()¶

Checks if there is data to write to the transport layer to complete an operation.

Returns: True iff there is data to write

write(buf, flags=0)¶

Send data on the connection. NOTE: If you get one of the WantRead, WantWrite or WantX509Lookup exceptions on this, you have to call the method again with the SAME buffer.

Parameters

buf – The string, buffer or memoryview to send
flags – (optional) Included for compatibility with the socket API, the value is ignored

Returns

The number of bytes written

Footnotes

1: 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!

SSL — An interface to the SSL-specific parts of OpenSSL¶

Context objects¶

Session objects¶

Connection objects¶

`SSL` — An interface to the SSL-specific parts of OpenSSL¶