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
, orTLS_CLIENT_METHOD
. If the underlying OpenSSL build is missing support for any of these protocols, constructing aContext
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()
anduse_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, theOP_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 theOPENSSL_*
names are preferred.Constants used with
OpenSSL_version()
to specify what OpenSSL version information to retrieve. See the man page for theOpenSSL_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 theSSL_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.
- 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 thebio_read()
,bio_write()
, andbio_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()
, orOpenSSL.SSL.Connection.do_handshake()
is prevented or incomplete. You probably want toselect()
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 withuse_certificate()
)
- 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
orunicode
).- 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 beNone
.- Parameters
cafile – In which file we can find the certificates (
bytes
orunicode
).capath – In which directory we can find the certificates (
bytes
orunicode
).
- 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 theNO_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, orFalse
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()
orOpenSSL.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
andVERIFY_PEER
. IfVERIFY_PEER
is used, mode can be OR:ed withVERIFY_FAIL_IF_NO_PEER_CERT
andVERIFY_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
orunicode
). 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
orunicode
).filetype – (optional) The encoding of the file, which is either
FILETYPE_PEM
orFILETYPE_ASN1
. The default isFILETYPE_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
orunicode
)filetype – (optional) The encoding of the file, which is either
FILETYPE_PEM
orFILETYPE_ASN1
. The default isFILETYPE_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 thisConnection
object at creation.- Returns
A (conn, addr) pair where conn is the new
Connection
object created, and address is as returned by the socket’saccept()
.
- 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 theContext
object supplied to thisConnection
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 theconnect_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 ofset_accept_state()
orset_connect_state()
). This can raise the same exceptions assend()
andrecv()
.- 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
orNoneType
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
orNoneType
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
orNoneType
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 toset_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
’sContext
.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 thisConnection
.
- 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
orNoneType
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
orNoneType
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
- 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
orNone
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
- 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
- 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
- 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.
- 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
- 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!