From d072cae3a4e0d41602ffd0730a838fa12657ed4a Mon Sep 17 00:00:00 2001 From: Alex Chan Date: Thu, 15 Feb 2018 09:57:59 +0000 Subject: 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 --- doc/api/crypto.rst | 117 ++------- doc/api/ssl.rst | 663 +------------------------------------------------- src/OpenSSL/SSL.py | 343 +++++++++++++++++--------- src/OpenSSL/crypto.py | 40 ++- 4 files changed, 282 insertions(+), 881 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 7b21d4f..5cd7fd9 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -16,27 +16,9 @@ Elliptic curves --------------- -.. py:function:: get_elliptic_curves - - Return a set of objects representing the elliptic curves supported in the - OpenSSL build in use. - - The curve objects have a :py:class:`unicode` ``name`` attribute by which - they identify themselves. - - The curve objects are useful as values for the argument accepted by - :py:meth:`Context.set_tmp_ecdh` to specify which elliptical curve should be - used for ECDHE key exchange. - - -.. py:function:: get_elliptic_curve(name) - - Return a single curve object selected by *name*. - - See :py:func:`get_elliptic_curves` for information about curve objects. - - If the named curve is not supported then :py:class:`ValueError` is raised. +.. autofunction:: get_elliptic_curves +.. autofunction:: get_elliptic_curve Serialization and deserialization --------------------------------- @@ -54,42 +36,23 @@ The following serialization functions take one of these constants to determine t Certificates ~~~~~~~~~~~~ -.. py:function:: dump_certificate(type, cert) - - Dump the certificate *cert* into a buffer string encoded with the type - *type*. - -.. py:function:: load_certificate(type, buffer) +.. autofunction:: dump_certificate - Load a certificate (X509) from the string *buffer* encoded with the - type *type*. +.. autofunction:: load_certificate Certificate signing requests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. py:function:: dump_certificate_request(type, req) +.. autofunction:: dump_certificate_request - Dump the certificate request *req* into a buffer string encoded with the - type *type*. - -.. py:function:: load_certificate_request(type, buffer) - - Load a certificate request (X509Req) from the string *buffer* encoded with - the type *type*. +.. autofunction:: load_certificate_request Private keys ~~~~~~~~~~~~ .. autofunction:: dump_privatekey -.. py:function:: load_privatekey(type, buffer[, passphrase]) - - Load a private key (PKey) from the string *buffer* encoded with the type - *type* (must be one of :py:const:`FILETYPE_PEM` and - :py:const:`FILETYPE_ASN1`). - - *passphrase* must be either a string or a callback for providing the pass - phrase. +.. autofunction:: load_privatekey Public keys ~~~~~~~~~~~ @@ -103,53 +66,18 @@ Certificate revocation lists .. autofunction:: dump_crl -.. py:function:: load_crl(type, buffer) - - Load Certificate Revocation List (CRL) data from a string *buffer*. - *buffer* encoded with the type *type*. The type *type* must either - :py:const:`FILETYPE_PEM` or :py:const:`FILETYPE_ASN1`). - - -.. py:function:: load_pkcs7_data(type, buffer) - - Load pkcs7 data from the string *buffer* encoded with the type - *type*. The type *type* must either :py:const:`FILETYPE_PEM` or - :py:const:`FILETYPE_ASN1`). - +.. autofunction:: load_crl -.. py:function:: load_pkcs12(buffer[, passphrase]) +.. autofunction:: load_pkcs7_data - Load pkcs12 data from the string *buffer*. If the pkcs12 structure is - encrypted, a *passphrase* must be included. The MAC is always - checked and thus required. - - See also the man page for the C function :py:func:`PKCS12_parse`. +.. autofunction:: load_pkcs12 Signing and verifying signatures -------------------------------- -.. py:function:: sign(key, data, digest) - - Sign a data string using the given key and message digest. - - *key* is a :py:class:`PKey` instance. *data* is a ``str`` instance. - *digest* is a ``str`` naming a supported message digest type, for example - :py:const:`b"sha256"`. - - .. versionadded:: 0.11 - +.. autofunction:: sign -.. py:function:: verify(certificate, signature, data, digest) - - Verify the signature for a data string. - - *certificate* is a :py:class:`X509` instance corresponding to the private - key which generated the signature. *signature* is a *str* instance giving - the signature itself. *data* is a *str* instance giving the data to which - the signature applies. *digest* is a *str* instance naming the message - digest type of the signature, for example :py:const:`b"sha256"`. - - .. versionadded:: 0.11 +.. autofunction:: verify .. _openssl-x509: @@ -243,25 +171,8 @@ PKCS7 objects PKCS7 objects have the following methods: -.. py:method:: PKCS7.type_is_signed() - - FIXME - -.. py:method:: PKCS7.type_is_enveloped() - - FIXME - -.. py:method:: PKCS7.type_is_signedAndEnveloped() - - FIXME - -.. py:method:: PKCS7.type_is_data() - - FIXME - -.. py:method:: PKCS7.get_type_name() - - Get the type name of the PKCS7. +.. autoclass:: PKCS7 + :members: .. _openssl-pkcs12: diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst index d892dbb..c678b28 100644 --- a/doc/api/ssl.rst +++ b/doc/api/ssl.rst @@ -118,11 +118,7 @@ Context, Connection. for details. -.. py:function:: SSLeay_version(type) - - Retrieve a string describing some aspect of the underlying OpenSSL version. The - type passed in should be one of the :py:const:`SSLEAY_*` constants defined in - this module. +.. autofunction:: SSLeay_version .. py:data:: ContextType @@ -130,23 +126,9 @@ Context, Connection. See :py:class:`Context`. -.. py:class:: Context(method) - - A class representing SSL contexts. Contexts define the parameters of one or - more SSL connections. - - *method* should be :py:const:`SSLv2_METHOD`, :py:const:`SSLv3_METHOD`, - :py:const:`SSLv23_METHOD`, :py:const:`TLSv1_METHOD`, :py:const:`TLSv1_1_METHOD`, - or :py:const:`TLSv1_2_METHOD`. - - -.. py:class:: Session() +.. autoclass:: Context - 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 +.. autoclass:: Session .. py:data:: ConnectionType @@ -236,283 +218,8 @@ Context objects Context objects have the following methods: -.. :py:class:: OpenSSL.SSL.Context - -.. py:method:: Context.check_privatekey() - - Check if the private key (loaded with :py:meth:`use_privatekey`) matches the - certificate (loaded with :py:meth:`use_certificate`). Returns - :py:data:`None` if they match, raises :py:exc:`Error` otherwise. - - -.. py:method:: Context.get_app_data() - - Retrieve application data as set by :py:meth:`set_app_data`. - - -.. py:method:: Context.get_cert_store() - - Retrieve the certificate store (a X509Store object) that the context uses. - This can be used to add "trusted" certificates without using the - :py:meth:`load_verify_locations` method. - - -.. py:method:: Context.get_timeout() - - Retrieve session timeout, as set by :py:meth:`set_timeout`. The default is 300 - seconds. - - -.. py:method:: Context.get_verify_depth() - - Retrieve the Context object's verify depth, as set by - :py:meth:`set_verify_depth`. - - -.. py:method:: Context.get_verify_mode() - - Retrieve the Context object's verify mode, as set by :py:meth:`set_verify`. - - -.. automethod:: Context.load_client_ca - - -.. py:method:: Context.set_client_ca_list(certificate_authorities) - - Replace the current list of preferred certificate signers that would be - sent to the client when requesting a client certificate with the - *certificate_authorities* sequence of :py:class:`OpenSSL.crypto.X509Name`'s. - - .. versionadded:: 0.10 - - -.. py:method:: Context.add_client_ca(certificate_authority) - - Extract a :py:class:`OpenSSL.crypto.X509Name` from the *certificate_authority* - :py:class:`OpenSSL.crypto.X509` certificate and add it to the list of preferred - certificate signers sent to the client when requesting a client certificate. - - .. versionadded:: 0.10 - - -.. py:method:: Context.load_verify_locations(pemfile, capath) - - Specify where CA certificates for verification purposes are located. These - are trusted certificates. 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 :py:data:`None`. - - -.. py:method:: Context.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. - - -.. py:method:: Context.load_tmp_dh(dhfile) - - Load parameters for Ephemeral Diffie-Hellman from *dhfile*. - - -.. py:method:: Context.set_tmp_ecdh(curve) - - Select a curve to use for ECDHE key exchange. - - The valid values of *curve* are the objects returned by - :py:func:`OpenSSL.crypto.get_elliptic_curves` or - :py:func:`OpenSSL.crypto.get_elliptic_curve`. - - -.. py:method:: Context.set_app_data(data) - - Associate *data* with this Context object. *data* can be retrieved - later using the :py:meth:`get_app_data` method. - - -.. automethod:: Context.set_cipher_list - -.. py:method:: Context.set_info_callback(callback) - - Set the information callback to *callback*. This function will be called - from time to time during SSL handshakes. - - *callback* 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. - - -.. py:method:: Context.set_options(options) - - Add SSL options. Options you have set before are not cleared! - This method should be used with the :py:const:`OP_*` constants. - - -.. py:method:: Context.set_mode(mode) - - Add SSL mode. Modes you have set before are not cleared! This method should - be used with the :py:const:`MODE_*` constants. - - -.. py:method:: Context.set_passwd_cb(callback[, userdata]) - - Set the passphrase callback to *callback*. This function will be called - when a private key with a passphrase is loaded. *callback* 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 :py: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). - - -.. py:method:: Context.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 :py:const:`SESS_CACHE_*` - for details about particular modes. - - .. versionadded:: 0.14 - - -.. py:method:: Context.get_session_cache_mode() - - Get the current session cache mode. - - .. versionadded:: 0.14 - - -.. automethod:: Context.set_session_id - - -.. py:method:: Context.set_timeout(timeout) - - Set the timeout for newly created sessions for this Context object to - *timeout*. *timeout* must be given in (whole) seconds. The default - value is 300 seconds. See the OpenSSL manual for more information (e.g. - :manpage:`SSL_CTX_set_timeout(3)`). - - -.. py:method:: Context.set_verify(mode, callback) - - Set the verification flags for this Context object to *mode* and specify - that *callback* should be used for verification callbacks. *mode* should be - one of :py:const:`VERIFY_NONE` and :py:const:`VERIFY_PEER`. If - :py:const:`VERIFY_PEER` is used, *mode* can be OR:ed with - :py:const:`VERIFY_FAIL_IF_NO_PEER_CERT` and :py:const:`VERIFY_CLIENT_ONCE` - to further control the behaviour. - - *callback* 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. - - -.. py:method:: Context.set_verify_depth(depth) - - Set the maximum depth for the certificate chain verification that shall be - allowed for this Context object. - - -.. py:method:: Context.use_certificate(cert) - - Use the certificate *cert* which has to be a X509 object. - - -.. py:method:: Context.add_extra_chain_cert(cert) - - Adds the certificate *cert*, which has to be a X509 object, to the - certificate chain presented together with the certificate. - - -.. py:method:: Context.use_certificate_chain_file(file) - - Load a certificate chain from *file* which must be PEM encoded. - - -.. py:method:: Context.use_privatekey(pkey) - - Use the private key *pkey* which has to be a PKey object. - - -.. py:method:: Context.use_certificate_file(file[, format]) - - Load the first certificate found in *file*. The certificate must be in the - format specified by *format*, which is either :py:const:`FILETYPE_PEM` or - :py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`. - - -.. py:method:: Context.use_privatekey_file(file[, format]) - - Load the first private key found in *file*. The private key must be in the - format specified by *format*, which is either :py:const:`FILETYPE_PEM` or - :py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`. - - -.. py:method:: Context.set_tlsext_servername_callback(callback) - - Specify a one-argument callable to use as the TLS extension server name - callback. When a connection using the server name extension is made using - this context, the callback will be invoked with the :py:class:`Connection` - instance. - - .. versionadded:: 0.13 - - -.. py:method:: Context.set_npn_advertise_callback(callback) - - Specify a callback function that will be called when offering `Next - Protocol Negotiation - `_ as a server. - - *callback* should be the callback function. It will be invoked with one - argument, the :py: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 - - -.. py:method:: Context.set_npn_select_callback(callback): - - Specify a callback function that will be called when a server offers Next - Protocol Negotiation options. - - *callback* should be the callback function. It will be invoked with two - arguments: the :py:class:`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 - -.. py:method:: Context.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. - - *protos* should be a list of protocols that the client is offering, each - as a bytestring. For example, ``[b'http/1.1', b'spdy/2']``. - - -.. py:method:: Context.set_alpn_select_callback(callback) - - Specify a callback function that will be called on the server when a client - offers protocols using Application Layer Protocol Negotiation. - - *callback* should be the callback function. It will be invoked with two - arguments: the :py:class:`Connection` and a list of offered protocols as - bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``. It should return one of - these bytestrings, the chosen protocol. - +.. autoclass:: OpenSSL.SSL.Context + :members: .. _openssl-session: @@ -529,364 +236,8 @@ Connection objects Connection objects have the following methods: -.. py:method:: Connection.accept() - - Call the :py:meth:`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 pair *(conn, address)*. where *conn* is the new - Connection object created, and *address* is as returned by the socket's - :py:meth:`accept`. - - -.. py:method:: Connection.bind(address) - - Call the :py:meth:`bind` method of the underlying socket. - - -.. py:method:: Connection.close() - - Call the :py:meth:`close` method of the underlying socket. Note: If you want - correct SSL closure, you need to call the :py:meth:`shutdown` method first. - - -.. py:method:: Connection.connect(address) - - Call the :py:meth:`connect` method of the underlying socket and set up SSL on the - socket, using the Context object supplied to this Connection object at - creation. - - -.. py:method:: Connection.connect_ex(address) - - Call the :py: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 :py:meth:`connect_ex` method of the socket doesn't - return 0, SSL won't be initialized. - - -.. py:method:: Connection.do_handshake() - - Perform an SSL handshake (usually called after :py:meth:`renegotiate` or one of - :py:meth:`set_accept_state` or :py:meth:`set_accept_state`). This can raise the - same exceptions as :py:meth:`send` and :py:meth:`recv`. - - -.. py:method:: Connection.fileno() - - Retrieve the file descriptor number for the underlying socket. - - -.. py:method:: Connection.listen(backlog) - - Call the :py:meth:`listen` method of the underlying socket. - - -.. py:method:: Connection.get_app_data() - - Retrieve application data as set by :py:meth:`set_app_data`. - - -.. automethod:: Connection.get_cipher_list - - -.. py:method:: Connection.get_protocol_version() - - Retrieve the version of the SSL or TLS protocol used by the Connection. - For example, it will return ``0x769`` for connections made over TLS - version 1. - - -.. py:method:: Connection.get_protocol_version_name() - - Retrieve the version of the SSL or TLS protocol used by the Connection as - a unicode string. For example, it will return ``TLSv1`` for connections - made over TLS version 1, or ``Unknown`` for connections that were not - successfully established. - - -.. py:method:: Connection.get_client_ca_list() - - Retrieve the list of preferred client certificate issuers sent by the server - as :py:class:`OpenSSL.crypto.X509Name` objects. - - If this is a client :py:class:`Connection`, the list will be empty until the - connection with the server is established. - - If this is a server :py:class:`Connection`, return the list of certificate - authorities that will be sent or has been sent to the client, as controlled - by this :py:class:`Connection`'s :py:class:`Context`. - - .. versionadded:: 0.10 - - -.. py:method:: Connection.get_context() - - Retrieve the Context object associated with this Connection. - - -.. py:method:: Connection.set_context(context) - - Specify a replacement Context object for this Connection. - - -.. py:method:: Connection.get_peer_certificate() - - Retrieve the other side's certificate (if any) - - -.. py:method:: Connection.get_peer_cert_chain() - - Retrieve the tuple of the other side's certificate chain (if any) - - -.. py:method:: Connection.getpeername() - - Call the :py:meth:`getpeername` method of the underlying socket. - - -.. py:method:: Connection.getsockname() - - Call the :py:meth:`getsockname` method of the underlying socket. - - -.. py:method:: Connection.getsockopt(level, optname[, buflen]) - - Call the :py:meth:`getsockopt` method of the underlying socket. - - -.. py:method:: Connection.pending() - - Retrieve the number of bytes that can be safely read from the SSL buffer - (**not** the underlying transport buffer). - - -.. py:method:: Connection.recv(bufsize[, flags]) - - Receive data from the Connection. The return value is a string representing the - data received. The maximum amount of data to be received at once, is specified - by *bufsize*. The only supported flag is ``MSG_PEEK``, all other flags are - ignored. - - -.. py:method:: Connection.recv_into(buffer[, nbytes[, flags]]) - - Receive data from the Connection and copy it directly into the provided - buffer. The return value is the number of bytes read from the connection. - The maximum amount of data to be received at once is specified by *nbytes*. - The only supported flag is ``MSG_PEEK``, all other flags are ignored. - -.. py:method:: Connection.bio_write(bytes) - - 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 :py:meth:`recv`). - - -.. automethod:: Connection.renegotiate - -.. automethod:: Connection.renegotiate_pending - -.. automethod:: Connection.total_renegotiations - -.. py:method:: Connection.send(string) - - Send the *string* data to the Connection. - - -.. py:method:: Connection.bio_read(bufsize) - - 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. - - -.. py:method:: Connection.sendall(string) - - Send all of the *string* data to the Connection. This calls :py:meth:`send` - repeatedly until all data is sent. If an error occurs, it's impossible to tell - how much data has been sent. - - -.. py:method:: Connection.set_accept_state() - - Set the connection to work in server mode. The handshake will be handled - automatically by read/write. - - -.. py:method:: Connection.set_app_data(data) - - Associate *data* with this Connection object. *data* can be retrieved - later using the :py:meth:`get_app_data` method. - - -.. py:method:: Connection.set_connect_state() - - Set the connection to work in client mode. The handshake will be handled - automatically by read/write. - - -.. py:method:: Connection.setblocking(flag) - - Call the :py:meth:`setblocking` method of the underlying socket. - - -.. py:method:: Connection.setsockopt(level, optname, value) - - Call the :py:meth:`setsockopt` method of the underlying socket. - - -.. py:method:: Connection.shutdown() - - Send the shutdown message to the Connection. Returns true if the shutdown - message exchange is completed and false otherwise (in which case you call - :py:meth:`recv` or :py:meth:`send` when the connection becomes - readable/writeable. - - -.. py:method:: Connection.get_shutdown() - - Get the shutdown state of the Connection. Returns a bitvector of either or - both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*. - - -.. py:method:: Connection.set_shutdown(state) - - Set the shutdown state of the Connection. *state* is a bitvector of - either or both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*. - - -.. py:method:: Connection.sock_shutdown(how) - - Call the :py:meth:`shutdown` method of the underlying socket. - - -.. py:method:: Connection.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. - - -.. automethod:: Connection.get_state_string - -.. py:method:: Connection.client_random() - - Retrieve the random value used with the client hello message. - - -.. py:method:: Connection.server_random() - - Retrieve the random value used with the server hello message. - - -.. py:method:: Connection.master_key() - - Retrieve the value of the master key for this session. - - -.. py:method:: Connection.want_read() - - Checks if more data has to be read from the transport layer to complete an - operation. - - -.. py:method:: Connection.want_write() - - Checks if there is data to write to the transport layer to complete an - operation. - - -.. py:method:: Connection.set_tlsext_host_name(name) - - Specify the byte string to send as the server name in the client hello message. - - .. versionadded:: 0.13 - - -.. py:method:: Connection.get_servername() - - Get the value of the server name received in the client hello message. - - .. versionadded:: 0.13 - - -.. py:method:: Connection.get_session() - - Get a :py:class:`Session` instance representing the SSL session in use by - the connection, or :py:obj:`None` if there is no session. - - .. versionadded:: 0.14 - - -.. py:method:: Connection.set_session(session) - - Set a new SSL session (using a :py:class:`Session` instance) to be used by - the connection. - - .. versionadded:: 0.14 - - -.. py:method:: Connection.get_finished() - - Obtain latest TLS Finished message that we sent, or :py:obj:`None` if - handshake is not completed. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_peer_finished() - - Obtain latest TLS Finished message that we expected from peer, or - :py:obj:`None` if handshake is not completed. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_cipher_name() - - Obtain the name of the currently used cipher. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_cipher_bits() - - Obtain the number of secret bits of the currently used cipher. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_cipher_version() - - Obtain the protocol name of the currently used cipher. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_next_proto_negotiated(): - - Get the protocol that was negotiated by Next Protocol Negotiation. Returns - a bytestring of the protocol name. If no protocol has been negotiated yet, - returns an empty string. - - .. versionadded:: 0.15 - -.. py:method:: Connection.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. - - *protos* should be a list of protocols that the client is offering, each - as a bytestring. For example, ``[b'http/1.1', b'spdy/2']``. - - -.. py:method:: Connection.get_alpn_proto_negotiated() - - Get the protocol that was negotiated by Application Layer Protocol - Negotiation. Returns a bytestring of the protocol name. If no protocol has - been negotiated yet, returns an empty string. +.. autoclass:: OpenSSL.SSL.Connection + :members: .. Rubric:: Footnotes 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 @@ def SSLeay_version(type): """ 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 @@ _requires_sni = _make_requires( 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 Context(object): """ :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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): def set_passwd_cb(self, callback, userdata=None): """ - Set the passphrase callback - - :param callback: The Python callback to use; must return a byte string + 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. 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 @@ class Context(object): 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 `_ 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 @@ class Context(object): 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 @@ class Context(object): :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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 - - :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 + 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 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): :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 @@ class Context(object): :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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): 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 @@ class Context(object): :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 @@ class Context(object): `_ 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 @@ class Context(object): 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 @@ class Context(object): @_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 @@ class Context(object): @_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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): """ 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 @@ class Connection(object): 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 @@ class Connection(object): """ 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): """ 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 @@ class Connection(object): 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 @@ class Connection(object): """ 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 @@ class Connection(object): :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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): """ 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 @@ class Connection(object): 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 *") diff --git a/src/OpenSSL/crypto.py b/src/OpenSSL/crypto.py index 12b4db0..adf03b4 100644 --- a/src/OpenSSL/crypto.py +++ b/src/OpenSSL/crypto.py @@ -1799,7 +1799,8 @@ class X509StoreContext(object): def load_certificate(type, buffer): """ - Load a certificate from a buffer + Load a certificate (X509) from the string *buffer* encoded with the + type *type*. :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1) @@ -1828,7 +1829,8 @@ def load_certificate(type, buffer): def dump_certificate(type, cert): """ - Dump a certificate to a buffer + Dump the certificate *cert* into a buffer string encoded with the type + *type*. :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1, or FILETYPE_TEXT) @@ -2766,7 +2768,8 @@ def load_publickey(type, buffer): def load_privatekey(type, buffer, passphrase=None): """ - Load a private key from a buffer + Load a private key (PKey) from the string *buffer* encoded with the type + *type*. :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1) :param buffer: The buffer the key is stored in @@ -2801,7 +2804,8 @@ def load_privatekey(type, buffer, passphrase=None): def dump_certificate_request(type, req): """ - Dump a certificate request to a buffer + Dump the certificate request *req* into a buffer string encoded with the + type *type*. :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1) :param req: The certificate request to dump @@ -2828,7 +2832,8 @@ def dump_certificate_request(type, req): def load_certificate_request(type, buffer): """ - Load a certificate request from a buffer + Load a certificate request (X509Req) from the string *buffer* encoded with + the type *type*. :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1) :param buffer: The buffer the certificate request is stored in @@ -2855,12 +2860,14 @@ def load_certificate_request(type, buffer): def sign(pkey, data, digest): """ - Sign data with a digest + Sign a data string using the given key and message digest. - :param pkey: Pkey to sign with + :param pkey: PKey to sign with :param data: data to be signed :param digest: message digest to use :return: signature + + .. versionadded:: 0.11 """ data = _text_to_bytes_and_warn("data", data) @@ -2887,13 +2894,16 @@ def sign(pkey, data, digest): def verify(cert, signature, data, digest): """ - Verify a signature. + Verify the signature for a data string. - :param cert: signing certificate (X509 object) + :param cert: signing certificate (X509 object) corresponding to the + private key which generated the signature. :param signature: signature returned by sign function :param data: data to be verified :param digest: message digest to use :return: ``None`` if the signature is correct, raise exception otherwise. + + .. versionadded:: 0.11 """ data = _text_to_bytes_and_warn("data", data) @@ -2948,7 +2958,8 @@ def dump_crl(type, crl): def load_crl(type, buffer): """ - Load a certificate revocation list from a buffer + Load Certificate Revocation List (CRL) data from a string *buffer*. + *buffer* encoded with the type *type*. :param type: The file type (one of FILETYPE_PEM, FILETYPE_ASN1) :param buffer: The buffer the CRL is stored in @@ -2977,7 +2988,8 @@ def load_crl(type, buffer): def load_pkcs7_data(type, buffer): """ - Load pkcs7 data from a buffer + Load pkcs7 data from the string *buffer* encoded with the type + *type*. :param type: The file type (one of FILETYPE_PEM or FILETYPE_ASN1) :param buffer: The buffer with the pkcs7 data. @@ -3005,7 +3017,11 @@ def load_pkcs7_data(type, buffer): def load_pkcs12(buffer, passphrase=None): """ - Load a PKCS12 object from a buffer + Load pkcs12 data from the string *buffer*. If the pkcs12 structure is + encrypted, a *passphrase* must be included. The MAC is always + checked and thus required. + + See also the man page for the C function :py:func:`PKCS12_parse`. :param buffer: The buffer the certificate is stored in :param passphrase: (Optional) The password to decrypt the PKCS12 lump -- cgit v1.2.1