diff options
Diffstat (limited to 'doc/api/ssl.rst')
| -rw-r--r-- | doc/api/ssl.rst | 303 |
1 files changed, 5 insertions, 298 deletions
diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst index d892dbb..8a0bd64 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`. +.. autoclass:: Context - -.. py:class:: 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. - - .. 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 <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. - - -.. 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 - <https://tools.ietf.org/html/draft-agl-tls-nextprotoneg-03>`_ 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: |