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.SSLEAY_VERSION
OpenSSL.SSL.SSLEAY_CFLAGS
OpenSSL.SSL.SSLEAY_BUILT_ON
OpenSSL.SSL.SSLEAY_PLATFORM
OpenSSL.SSL.SSLEAY_DIR

Constants used with SSLeay_version() to specify what OpenSSL version information to retrieve. See the man page for the SSLeay_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.SSLeay_version(type)

Return a string describing the version of OpenSSL in use.

Parameters

type – One of the SSLEAY_ 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, or TLS_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, or TLS_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
Returns

None

Session objects

Session objects have no methods.

Connection objects

Connection objects have the following methods:

class OpenSSL.SSL.Connection(context, socket=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 string.

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_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.

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_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.

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

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!