Use autofocus for all module documentation/docstrings (#737)
* Use autodoc for OpenSSL.crypto
* Use autodoc for the SSL.Context class
* Use autodoc for SSL.Connection
diff --git a/src/OpenSSL/SSL.py b/src/OpenSSL/SSL.py
index b664254..5def0aa 100644
--- a/src/OpenSSL/SSL.py
+++ b/src/OpenSSL/SSL.py
@@ -632,7 +632,7 @@
"""
Return a string describing the version of OpenSSL in use.
- :param type: One of the SSLEAY_ constants defined in this module.
+ :param type: One of the :const:`SSLEAY_` constants defined in this module.
"""
return _ffi.string(_lib.SSLeay_version(type))
@@ -675,6 +675,13 @@
class Session(object):
+ """
+ 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.
+
+ .. versionadded:: 0.14
+ """
pass
@@ -682,6 +689,9 @@
"""
:class:`OpenSSL.SSL.Context` instances define the parameters for setting
up new SSL connections.
+
+ :param method: One of SSLv2_METHOD, SSLv3_METHOD, SSLv23_METHOD, or
+ TLSv1_METHOD.
"""
_methods = {
SSLv2_METHOD: "SSLv2_method",
@@ -697,10 +707,6 @@
if getattr(_lib, name, None) is not None)
def __init__(self, method):
- """
- :param method: One of SSLv2_METHOD, SSLv3_METHOD, SSLv23_METHOD, or
- TLSv1_METHOD.
- """
if not isinstance(method, integer_types):
raise TypeError("method must be an integer")
@@ -749,7 +755,11 @@
def load_verify_locations(self, cafile, capath=None):
"""
Let SSL know where we can find trusted certificates for the certificate
- chain
+ 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 :data:`None`.
:param cafile: In which file we can find the certificates (``bytes`` or
``unicode``).
@@ -783,9 +793,19 @@
def set_passwd_cb(self, callback, userdata=None):
"""
- Set the passphrase callback
+ Set the passphrase callback. This function will be called
+ when a private key with a passphrase is loaded.
- :param callback: The Python callback to use; must return a byte string
+ :param 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 :meth:`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).
:param userdata: (optional) A Python object which will be given as
argument to the callback
:return: None
@@ -801,7 +821,17 @@
def set_default_verify_paths(self):
"""
- Use the platform-specific CA certificate locations
+ 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 <https://brew.sh>`_ 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.
:return: None
"""
@@ -871,10 +901,10 @@
def use_certificate_chain_file(self, certfile):
"""
- Load a certificate chain from a file
+ Load a certificate chain from a file.
:param certfile: The name of the certificate chain file (``bytes`` or
- ``unicode``).
+ ``unicode``). Must be PEM encoded.
:return: None
"""
@@ -892,7 +922,9 @@
:param certfile: The name of the certificate file (``bytes`` or
``unicode``).
- :param filetype: (optional) The encoding of the file, default is PEM
+ :param filetype: (optional) The encoding of the file, which is either
+ :const:`FILETYPE_PEM` or :const:`FILETYPE_ASN1`. The default is
+ :const:`FILETYPE_PEM`.
:return: None
"""
@@ -948,7 +980,9 @@
Load a private key from a file
:param keyfile: The name of the key file (``bytes`` or ``unicode``)
- :param filetype: (optional) The encoding of the file, default is PEM
+ :param filetype: (optional) The encoding of the file, which is either
+ :const:`FILETYPE_PEM` or :const:`FILETYPE_ASN1`. The default is
+ :const:`FILETYPE_PEM`.
:return: None
"""
@@ -980,9 +1014,10 @@
def check_privatekey(self):
"""
- Check that the private key and certificate match up
+ Check if the private key (loaded with :meth:`use_privatekey`) matches
+ the certificate (loaded with :meth:`use_certificate`)
- :return: None (raises an exception if something's wrong)
+ :return: :data:`None` (raises :exc:`Error` if something's wrong)
"""
if not _lib.SSL_CTX_check_private_key(self._context):
_raise_current_error()
@@ -1024,11 +1059,15 @@
def set_session_cache_mode(self, mode):
"""
- Enable/disable session caching and specify the mode used.
+ Set the behavior of the session cache used by all connections using
+ this Context. The previously set mode is returned. See
+ :const:`SESS_CACHE_*` for details about particular modes.
:param mode: One or more of the SESS_CACHE_* flags (combine using
bitwise or)
:returns: The previously set caching mode.
+
+ .. versionadded:: 0.14
"""
if not isinstance(mode, integer_types):
raise TypeError("mode must be an integer")
@@ -1037,17 +1076,29 @@
def get_session_cache_mode(self):
"""
+ Get the current session cache mode.
+
:returns: The currently used cache mode.
+
+ .. versionadded:: 0.14
"""
return _lib.SSL_CTX_get_session_cache_mode(self._context)
def set_verify(self, mode, callback):
"""
- Set the verify mode and verify callback
+ et the verification flags for this Context object to *mode* and specify
+ that *callback* should be used for verification callbacks.
- :param mode: The verify mode, this is either VERIFY_NONE or
- VERIFY_PEER combined with possible other flags
- :param callback: The Python callback to use
+ :param mode: The verify mode, this should be one of
+ :const:`VERIFY_NONE` and :const:`VERIFY_PEER`. If
+ :const:`VERIFY_PEER` is used, *mode* can be OR:ed with
+ :const:`VERIFY_FAIL_IF_NO_PEER_CERT` and
+ :const:`VERIFY_CLIENT_ONCE` to further control the behaviour.
+ :param callback: The Python 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.
:return: None
See SSL_CTX_set_verify(3SSL) for further details.
@@ -1064,7 +1115,8 @@
def set_verify_depth(self, depth):
"""
- Set the verify depth
+ Set the maximum depth for the certificate chain verification that shall
+ be allowed for this Context object.
:param depth: An integer specifying the verify depth
:return: None
@@ -1076,7 +1128,8 @@
def get_verify_mode(self):
"""
- Get the verify mode
+ Retrieve the Context object's verify mode, as set by
+ :meth:`set_verify`.
:return: The verify mode
"""
@@ -1084,7 +1137,8 @@
def get_verify_depth(self):
"""
- Get the verify depth
+ Retrieve the Context object's verify depth, as set by
+ :meth:`set_verify_depth`.
:return: The verify depth
"""
@@ -1115,8 +1169,8 @@
Select a curve to use for ECDHE key exchange.
:param curve: A curve object to use as returned by either
- :py:meth:`OpenSSL.crypto.get_elliptic_curve` or
- :py:meth:`OpenSSL.crypto.get_elliptic_curves`.
+ :meth:`OpenSSL.crypto.get_elliptic_curve` or
+ :meth:`OpenSSL.crypto.get_elliptic_curves`.
:return: None
"""
@@ -1151,6 +1205,8 @@
:param certificate_authorities: a sequence of X509Names.
:return: None
+
+ .. versionadded:: 0.10
"""
name_stack = _lib.sk_X509_NAME_new_null()
_openssl_assert(name_stack != _ffi.NULL)
@@ -1186,6 +1242,8 @@
:param certificate_authority: certificate authority's X509 certificate.
:return: None
+
+ .. versionadded:: 0.10
"""
if not isinstance(certificate_authority, X509):
raise TypeError("certificate_authority must be an X509 instance")
@@ -1196,9 +1254,11 @@
def set_timeout(self, timeout):
"""
- Set session 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. :manpage:`SSL_CTX_set_timeout(3)`).
- :param timeout: The timeout in seconds
+ :param timeout: The timeout in (whole) seconds
:return: The previous session timeout
"""
if not isinstance(timeout, integer_types):
@@ -1208,7 +1268,8 @@
def get_timeout(self):
"""
- Get the session timeout
+ Retrieve session timeout, as set by :meth:`set_timeout`. The default
+ is 300 seconds.
:return: The session timeout
"""
@@ -1216,9 +1277,14 @@
def set_info_callback(self, callback):
"""
- Set the info callback
+ Set the information callback to *callback*. This function will be
+ called from time to time during SSL handshakes.
- :param callback: The Python callback to use
+ :param 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.
:return: None
"""
@wraps(callback)
@@ -1230,7 +1296,7 @@
def get_app_data(self):
"""
- Get the application data (supplied via set_app_data())
+ Get the application data (supplied via :meth:`set_app_data()`)
:return: The application data
"""
@@ -1247,7 +1313,9 @@
def get_cert_store(self):
"""
- Get the certificate store for the context.
+ Get the certificate store for the context. This can be used to add
+ "trusted" certificates without using the
+ :meth:`load_verify_locations` method.
:return: A X509Store object or None if it does not have one.
"""
@@ -1263,6 +1331,7 @@
def set_options(self, options):
"""
Add options. Options set before are not cleared!
+ This method should be used with the :const:`OP_*` constants.
:param options: The options to add.
:return: The new option bitmask.
@@ -1274,7 +1343,8 @@
def set_mode(self, mode):
"""
- Add modes via bitmask. Modes set before are not cleared!
+ Add modes via bitmask. Modes set before are not cleared! This method
+ should be used with the :const:`MODE_*` constants.
:param mode: The mode to add.
:return: The new mode bitmask.
@@ -1292,6 +1362,8 @@
:param callback: The callback function. It will be invoked with one
argument, the Connection instance.
+
+ .. versionadded:: 0.13
"""
@wraps(callback)
def wrapper(ssl, alert, arg):
@@ -1311,9 +1383,11 @@
<https://technotes.googlecode.com/git/nextprotoneg.html>`_ as a server.
:param callback: The callback function. It will be invoked with one
- argument, the Connection instance. It should return a list of
- bytestrings representing the advertised protocols, like
+ argument, the :class:`Connection` instance. It should return a
+ list of bytestrings representing the advertised protocols, like
``[b'http/1.1', b'spdy/2']``.
+
+ .. versionadded:: 0.15
"""
self._npn_advertise_helper = _NpnAdvertiseHelper(callback)
self._npn_advertise_callback = self._npn_advertise_helper.callback
@@ -1330,6 +1404,8 @@
arguments: the Connection, and a list of offered protocols as
bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``. It should return
one of those bytestrings, the chosen protocol.
+
+ .. versionadded:: 0.15
"""
self._npn_select_helper = _NpnSelectHelper(callback)
self._npn_select_callback = self._npn_select_helper.callback
@@ -1339,9 +1415,9 @@
@_requires_alpn
def set_alpn_protos(self, protos):
"""
- Specify the clients ALPN protocol list.
-
- These protocols are offered to the server during protocol negotiation.
+ Specify the protocols that the client is prepared to speak after the
+ TLS connection has been negotiated using Application Layer Protocol
+ Negotiation.
:param protos: A list of the protocols to be offered to the server.
This list should be a Python list of bytestrings representing the
@@ -1361,7 +1437,8 @@
@_requires_alpn
def set_alpn_select_callback(self, callback):
"""
- Set the callback to handle ALPN protocol choice.
+ Specify a callback function that will be called on the server when a
+ client offers protocols using ALPN.
:param callback: The callback function. It will be invoked with two
arguments: the Connection, and a list of offered protocols as
@@ -1547,15 +1624,16 @@
def get_context(self):
"""
- Get session context
+ Retrieve the :class:`Context` object associated with this
+ :class:`Connection`.
"""
return self._context
def set_context(self, context):
"""
- Switch this connection to a new session context
+ Switch this connection to a new session context.
- :param context: A :py:class:`Context` instance giving the new session
+ :param context: A :class:`Context` instance giving the new session
context to use.
"""
if not isinstance(context, Context):
@@ -1570,7 +1648,9 @@
Retrieve the servername extension value if provided in the client hello
message, or None if there wasn't one.
- :return: A byte string giving the server name or :py:data:`None`.
+ :return: A byte string giving the server name or :data:`None`.
+
+ .. versionadded:: 0.13
"""
name = _lib.SSL_get_servername(
self._ssl, _lib.TLSEXT_NAMETYPE_host_name
@@ -1586,6 +1666,8 @@
Set the value of the servername extension to send in the client hello.
:param name: A byte string giving the name.
+
+ .. versionadded:: 0.13
"""
if not isinstance(name, bytes):
raise TypeError("name must be a byte string")
@@ -1597,7 +1679,8 @@
def pending(self):
"""
- Get the number of bytes that can be safely read from the connection
+ Get the number of bytes that can be safely read from the SSL buffer
+ (**not** the underlying transport buffer).
:return: The number of bytes available in the receive buffer.
"""
@@ -1687,8 +1770,8 @@
def recv_into(self, buffer, nbytes=None, flags=None):
"""
- Receive data on the connection and store the data into a buffer rather
- than creating a new string.
+ Receive data on the connection and copy it directly into the provided
+ buffer, rather than creating a new string.
:param buffer: The buffer to copy into.
:param nbytes: (optional) The maximum number of bytes to read into the
@@ -1746,8 +1829,11 @@
def bio_read(self, bufsiz):
"""
- When using non-socket connections this function reads the "dirty" data
- that would have traveled away on the network.
+ 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.
:param bufsiz: The maximum number of bytes to read
:return: The string read.
@@ -1767,8 +1853,10 @@
def bio_write(self, buf):
"""
- When using non-socket connections this function sends "dirty" data that
- would have traveled in on the network.
+ 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
+ :meth:`recv`).
:param buf: The string to put into the memory BIO.
:return: The number of bytes written
@@ -1797,8 +1885,9 @@
def do_handshake(self):
"""
- Perform an SSL handshake (usually called after renegotiate() or one of
- set_*_state()). This can raise the same exceptions as send and recv.
+ Perform an SSL handshake (usually called after :meth:`renegotiate` or
+ one of :meth:`set_accept_state` or :meth:`set_accept_state`). This can
+ raise the same exceptions as :meth:`send` and :meth:`recv`.
:return: None.
"""
@@ -1826,7 +1915,9 @@
def connect(self, addr):
"""
- Connect to remote host and set up client-side SSL
+ Call the :meth:`connect` method of the underlying socket and set up SSL
+ on the socket, using the :class:`Context` object supplied to this
+ :class:`Connection` object at creation.
:param addr: A remote address
:return: What the socket's connect method returns
@@ -1836,8 +1927,10 @@
def connect_ex(self, addr):
"""
- Connect to remote host and set up client-side SSL. Note that if the
- socket's connect_ex method doesn't return 0, SSL won't be initialized.
+ Call the :meth:`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 :meth:`connect_ex` method of the
+ socket doesn't return 0, SSL won't be initialized.
:param addr: A remove address
:return: What the socket's connect_ex method returns
@@ -1848,10 +1941,13 @@
def accept(self):
"""
- Accept incoming connection and set up SSL on it
+ Call the :meth:`accept` method of the underlying socket and set up SSL
+ on the returned socket, using the Context object supplied to this
+ :class:`Connection` object at creation.
- :return: A (conn,addr) pair where conn is a Connection and addr is an
- address
+ :return: A *(conn, addr)* pair where *conn* is the new
+ :class:`Connection` object created, and *address* is as returned by
+ the socket's :meth:`accept`.
"""
client, addr = self._socket.accept()
conn = Connection(self._context, client)
@@ -1860,8 +1956,9 @@
def bio_shutdown(self):
"""
- When using non-socket connections this function signals end of
- data on the input for this connection.
+ 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.
:return: None
"""
@@ -1872,11 +1969,12 @@
def shutdown(self):
"""
- Send closure alert
+ Send the shutdown message to the Connection.
:return: True if the shutdown completed successfully (i.e. both sides
- have sent closure alerts), false otherwise (i.e. you have to
- wait for a ZeroReturnError on a recv() method call
+ have sent closure alerts), False otherwise (in which case you
+ call :meth:`recv` or :meth:`send` when the connection becomes
+ readable/writeable).
"""
result = _lib.SSL_shutdown(self._ssl)
if result < 0:
@@ -1904,12 +2002,14 @@
"""
Get CAs whose certificates are suggested for client authentication.
- :return: If this is a server connection, a list of X509Names
- representing the acceptable CAs as set by
- :py:meth:`OpenSSL.SSL.Context.set_client_ca_list` or
- :py:meth:`OpenSSL.SSL.Context.add_client_ca`. If this is a client
- connection, the list of such X509Names sent by the server, or an
- empty list if that has not yet happened.
+ :return: 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 :class:`Connection`'s :class:`Context`.
+
+ If this is a client connection, the list will be empty until the
+ connection with the server is established.
+
+ .. versionadded:: 0.10
"""
ca_names = _lib.SSL_get_client_CA_list(self._ssl)
if ca_names == _ffi.NULL:
@@ -1939,7 +2039,7 @@
def get_app_data(self):
"""
- Get application data
+ Retrieve application data as set by :meth:`set_app_data`.
:return: The application data
"""
@@ -1949,14 +2049,14 @@
"""
Set application data
- :param data - The application data
+ :param data: The application data
:return: None
"""
self._app_data = data
def get_shutdown(self):
"""
- Get shutdown state
+ Get the shutdown state of the Connection.
:return: The shutdown state, a bitvector of SENT_SHUTDOWN,
RECEIVED_SHUTDOWN.
@@ -1965,9 +2065,9 @@
def set_shutdown(self, state):
"""
- Set shutdown state
+ Set the shutdown state of the Connection.
- :param state - bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.
+ :param state: bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN.
:return: None
"""
if not isinstance(state, integer_types):
@@ -1986,7 +2086,7 @@
def server_random(self):
"""
- Get a copy of the server hello nonce.
+ Retrieve the random value used with the server hello message.
:return: A string representing the state
"""
@@ -2001,7 +2101,7 @@
def client_random(self):
"""
- Get a copy of the client hello nonce.
+ Retrieve the random value used with the client hello message.
:return: A string representing the state
"""
@@ -2017,7 +2117,7 @@
def master_key(self):
"""
- Get a copy of the master key.
+ Retrieve the value of the master key for this session.
:return: A string representing the state
"""
@@ -2035,10 +2135,10 @@
"""
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
- :return the exported key material bytes or None
+ :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
+ :return: the exported key material bytes or None
"""
outp = _no_zero_allocator("unsigned char[]", olen)
context_buf = _ffi.NULL
@@ -2057,7 +2157,8 @@
def sock_shutdown(self, *args, **kwargs):
"""
- See shutdown(2)
+ Call the :meth:`shutdown` method of the underlying socket.
+ See :manpage:`shutdown(2)`.
:return: What the socket's shutdown() method returns
"""
@@ -2133,8 +2234,10 @@
"""
Returns the Session currently used.
- @return: An instance of :py:class:`OpenSSL.SSL.Session` or
- :py:obj:`None` if no session exists.
+ :return: An instance of :class:`OpenSSL.SSL.Session` or
+ :obj:`None` if no session exists.
+
+ .. versionadded:: 0.14
"""
session = _lib.SSL_get1_session(self._ssl)
if session == _ffi.NULL:
@@ -2150,6 +2253,8 @@
:param session: A Session instance representing the session to use.
:returns: None
+
+ .. versionadded:: 0.14
"""
if not isinstance(session, Session):
raise TypeError("session must be a Session instance")
@@ -2160,15 +2265,15 @@
def _get_finished_message(self, function):
"""
- Helper to implement :py:meth:`get_finished` and
- :py:meth:`get_peer_finished`.
+ Helper to implement :meth:`get_finished` and
+ :meth:`get_peer_finished`.
- :param function: Either :py:data:`SSL_get_finished`: or
- :py:data:`SSL_get_peer_finished`.
+ :param function: Either :data:`SSL_get_finished`: or
+ :data:`SSL_get_peer_finished`.
- :return: :py:data:`None` if the desired message has not yet been
+ :return: :data:`None` if the desired message has not yet been
received, otherwise the contents of the message.
- :rtype: :py:class:`bytes` or :py:class:`NoneType`
+ :rtype: :class:`bytes` or :class:`NoneType`
"""
# The OpenSSL documentation says nothing about what might happen if the
# count argument given is zero. Specifically, it doesn't say whether
@@ -2194,21 +2299,25 @@
def get_finished(self):
"""
- Obtain the latest `handshake finished` message sent to the peer.
+ Obtain the latest TLS Finished message that we sent.
- :return: The contents of the message or :py:obj:`None` if the TLS
+ :return: The contents of the message or :obj:`None` if the TLS
handshake has not yet completed.
- :rtype: :py:class:`bytes` or :py:class:`NoneType`
+ :rtype: :class:`bytes` or :class:`NoneType`
+
+ .. versionadded:: 0.15
"""
return self._get_finished_message(_lib.SSL_get_finished)
def get_peer_finished(self):
"""
- Obtain the latest `handshake finished` message received from the peer.
+ Obtain the latest TLS Finished message that we received from the peer.
- :return: The contents of the message or :py:obj:`None` if the TLS
+ :return: The contents of the message or :obj:`None` if the TLS
handshake has not yet completed.
- :rtype: :py:class:`bytes` or :py:class:`NoneType`
+ :rtype: :class:`bytes` or :class:`NoneType`
+
+ .. versionadded:: 0.15
"""
return self._get_finished_message(_lib.SSL_get_peer_finished)
@@ -2216,9 +2325,11 @@
"""
Obtain the name of the currently used cipher.
- :returns: The name of the currently used cipher or :py:obj:`None`
+ :returns: The name of the currently used cipher or :obj:`None`
if no connection has been established.
- :rtype: :py:class:`unicode` or :py:class:`NoneType`
+ :rtype: :class:`unicode` or :class:`NoneType`
+
+ .. versionadded:: 0.15
"""
cipher = _lib.SSL_get_current_cipher(self._ssl)
if cipher == _ffi.NULL:
@@ -2232,8 +2343,10 @@
Obtain the number of secret bits of the currently used cipher.
:returns: The number of secret bits of the currently used cipher
- or :py:obj:`None` if no connection has been established.
- :rtype: :py:class:`int` or :py:class:`NoneType`
+ or :obj:`None` if no connection has been established.
+ :rtype: :class:`int` or :class:`NoneType`
+
+ .. versionadded:: 0.15
"""
cipher = _lib.SSL_get_current_cipher(self._ssl)
if cipher == _ffi.NULL:
@@ -2246,8 +2359,10 @@
Obtain the protocol version of the currently used cipher.
:returns: The protocol name of the currently used cipher
- or :py:obj:`None` if no connection has been established.
- :rtype: :py:class:`unicode` or :py:class:`NoneType`
+ or :obj:`None` if no connection has been established.
+ :rtype: :class:`unicode` or :class:`NoneType`
+
+ .. versionadded:: 0.15
"""
cipher = _lib.SSL_get_current_cipher(self._ssl)
if cipher == _ffi.NULL:
@@ -2258,23 +2373,23 @@
def get_protocol_version_name(self):
"""
- Obtain the protocol version of the current connection.
+ 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.
- :rtype: :py:class:`unicode`
+ :rtype: :class:`unicode`
"""
version = _ffi.string(_lib.SSL_get_version(self._ssl))
return version.decode("utf-8")
def get_protocol_version(self):
"""
- Obtain the protocol version of the current connection.
+ Retrieve the SSL or TLS protocol version of the current connection.
- :returns: The TLS version of the current connection, for example
- the value for TLS 1 would be 0x769.
- :rtype: :py:class:`int`
+ :returns: The TLS version of the current connection. For example,
+ it will return ``0x769`` for connections made over TLS version 1.
+ :rtype: :class:`int`
"""
version = _lib.SSL_version(self._ssl)
return version
@@ -2283,6 +2398,11 @@
def get_next_proto_negotiated(self):
"""
Get the protocol that was negotiated by NPN.
+
+ :returns: A bytestring of the protocol name. If no protocol has been
+ negotiated yet, returns an empty string.
+
+ .. versionadded:: 0.15
"""
data = _ffi.new("unsigned char **")
data_len = _ffi.new("unsigned int *")
@@ -2317,6 +2437,9 @@
def get_alpn_proto_negotiated(self):
"""
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.
"""
data = _ffi.new("unsigned char **")
data_len = _ffi.new("unsigned int *")