Skip to content

Commit cd61c8b

Browse files
alexwlchanalexwlchan
committed
Use autodoc for the SSL.Context class
1 parent 47aa00a commit cd61c8b

File tree

2 files changed

+119
-335
lines changed

2 files changed

+119
-335
lines changed

‎doc/api/ssl.rst‎

Lines changed: 5 additions & 298 deletions
Original file line numberDiff line numberDiff line change
@@ -118,35 +118,17 @@ Context, Connection.
118118
for details.
119119

120120

121-
.. py:function:: SSLeay_version(type)
122-
123-
Retrieve a string describing some aspect of the underlying OpenSSL version. The
124-
type passed in should be one of the :py:const:`SSLEAY_*` constants defined in
125-
this module.
121+
.. autofunction:: SSLeay_version
126122

127123

128124
.. py:data:: ContextType
129125
130126
See :py:class:`Context`.
131127

132128

133-
.. py:class:: Context(method)
134-
135-
A class representing SSL contexts. Contexts define the parameters of one or
136-
more SSL connections.
137-
138-
*method* should be :py:const:`SSLv2_METHOD`, :py:const:`SSLv3_METHOD`,
139-
:py:const:`SSLv23_METHOD`, :py:const:`TLSv1_METHOD`, :py:const:`TLSv1_1_METHOD`,
140-
or :py:const:`TLSv1_2_METHOD`.
129+
.. autoclass:: Context
141130

142-
143-
.. py:class:: Session()
144-
145-
A class representing an SSL session. A session defines certain connection
146-
parameters which may be re-used to speed up the setup of subsequent
147-
connections.
148-
149-
.. versionadded:: 0.14
131+
.. autoclass:: Session
150132

151133

152134
.. py:data:: ConnectionType
@@ -236,283 +218,8 @@ Context objects
236218

237219
Context objects have the following methods:
238220

239-
.. :py:class:: OpenSSL.SSL.Context
240-
241-
.. py:method:: Context.check_privatekey()
242-
243-
Check if the private key (loaded with :py:meth:`use_privatekey`) matches the
244-
certificate (loaded with :py:meth:`use_certificate`). Returns
245-
:py:data:`None` if they match, raises :py:exc:`Error` otherwise.
246-
247-
248-
.. py:method:: Context.get_app_data()
249-
250-
Retrieve application data as set by :py:meth:`set_app_data`.
251-
252-
253-
.. py:method:: Context.get_cert_store()
254-
255-
Retrieve the certificate store (a X509Store object) that the context uses.
256-
This can be used to add "trusted" certificates without using the
257-
:py:meth:`load_verify_locations` method.
258-
259-
260-
.. py:method:: Context.get_timeout()
261-
262-
Retrieve session timeout, as set by :py:meth:`set_timeout`. The default is 300
263-
seconds.
264-
265-
266-
.. py:method:: Context.get_verify_depth()
267-
268-
Retrieve the Context object's verify depth, as set by
269-
:py:meth:`set_verify_depth`.
270-
271-
272-
.. py:method:: Context.get_verify_mode()
273-
274-
Retrieve the Context object's verify mode, as set by :py:meth:`set_verify`.
275-
276-
277-
.. automethod:: Context.load_client_ca
278-
279-
280-
.. py:method:: Context.set_client_ca_list(certificate_authorities)
281-
282-
Replace the current list of preferred certificate signers that would be
283-
sent to the client when requesting a client certificate with the
284-
*certificate_authorities* sequence of :py:class:`OpenSSL.crypto.X509Name`'s.
285-
286-
.. versionadded:: 0.10
287-
288-
289-
.. py:method:: Context.add_client_ca(certificate_authority)
290-
291-
Extract a :py:class:`OpenSSL.crypto.X509Name` from the *certificate_authority*
292-
:py:class:`OpenSSL.crypto.X509` certificate and add it to the list of preferred
293-
certificate signers sent to the client when requesting a client certificate.
294-
295-
.. versionadded:: 0.10
296-
297-
298-
.. py:method:: Context.load_verify_locations(pemfile, capath)
299-
300-
Specify where CA certificates for verification purposes are located. These
301-
are trusted certificates. Note that the certificates have to be in PEM
302-
format. If capath is passed, it must be a directory prepared using the
303-
``c_rehash`` tool included with OpenSSL. Either, but not both, of
304-
*pemfile* or *capath* may be :py:data:`None`.
305-
306-
307-
.. py:method:: Context.set_default_verify_paths()
308-
309-
Specify that the platform provided CA certificates are to be used for verification purposes.
310-
This method has some caveats related to the binary wheels that cryptography (pyOpenSSL's primary dependency) ships:
311-
312-
* macOS will only load certificates using this method if the user has the ``[email protected]`` `Homebrew <https://brew.sh>`_ formula installed in the default location.
313-
* Windows will not work.
314-
* manylinux1 cryptography wheels will work on most common Linux distributions in pyOpenSSL 17.1.0 and above.
315-
pyOpenSSL detects the manylinux1 wheel and attempts to load roots via a fallback path.
316-
317-
318-
.. py:method:: Context.load_tmp_dh(dhfile)
319-
320-
Load parameters for Ephemeral Diffie-Hellman from *dhfile*.
321-
322-
323-
.. py:method:: Context.set_tmp_ecdh(curve)
324-
325-
Select a curve to use for ECDHE key exchange.
326-
327-
The valid values of *curve* are the objects returned by
328-
:py:func:`OpenSSL.crypto.get_elliptic_curves` or
329-
:py:func:`OpenSSL.crypto.get_elliptic_curve`.
330-
331-
332-
.. py:method:: Context.set_app_data(data)
333-
334-
Associate *data* with this Context object. *data* can be retrieved
335-
later using the :py:meth:`get_app_data` method.
336-
337-
338-
.. automethod:: Context.set_cipher_list
339-
340-
.. py:method:: Context.set_info_callback(callback)
341-
342-
Set the information callback to *callback*. This function will be called
343-
from time to time during SSL handshakes.
344-
345-
*callback* should take three arguments: a Connection object and two integers.
346-
The first integer specifies where in the SSL handshake the function was
347-
called, and the other the return code from a (possibly failed) internal
348-
function call.
349-
350-
351-
.. py:method:: Context.set_options(options)
352-
353-
Add SSL options. Options you have set before are not cleared!
354-
This method should be used with the :py:const:`OP_*` constants.
355-
356-
357-
.. py:method:: Context.set_mode(mode)
358-
359-
Add SSL mode. Modes you have set before are not cleared! This method should
360-
be used with the :py:const:`MODE_*` constants.
361-
362-
363-
.. py:method:: Context.set_passwd_cb(callback[, userdata])
364-
365-
Set the passphrase callback to *callback*. This function will be called
366-
when a private key with a passphrase is loaded. *callback* must accept
367-
three positional arguments. First, an integer giving the maximum length of
368-
the passphrase it may return. If the returned passphrase is longer than
369-
this, it will be truncated. Second, a boolean value which will be true if
370-
the user should be prompted for the passphrase twice and the callback should
371-
verify that the two values supplied are equal. Third, the value given as the
372-
*userdata* parameter to :py:meth:`set_passwd_cb`. The *callback* must return
373-
a byte string. If an error occurs, *callback* should return a false value
374-
(e.g. an empty string).
375-
376-
377-
.. py:method:: Context.set_session_cache_mode(mode)
378-
379-
Set the behavior of the session cache used by all connections using this
380-
Context. The previously set mode is returned. See :py:const:`SESS_CACHE_*`
381-
for details about particular modes.
382-
383-
.. versionadded:: 0.14
384-
385-
386-
.. py:method:: Context.get_session_cache_mode()
387-
388-
Get the current session cache mode.
389-
390-
.. versionadded:: 0.14
391-
392-
393-
.. automethod:: Context.set_session_id
394-
395-
396-
.. py:method:: Context.set_timeout(timeout)
397-
398-
Set the timeout for newly created sessions for this Context object to
399-
*timeout*. *timeout* must be given in (whole) seconds. The default
400-
value is 300 seconds. See the OpenSSL manual for more information (e.g.
401-
:manpage:`SSL_CTX_set_timeout(3)`).
402-
403-
404-
.. py:method:: Context.set_verify(mode, callback)
405-
406-
Set the verification flags for this Context object to *mode* and specify
407-
that *callback* should be used for verification callbacks. *mode* should be
408-
one of :py:const:`VERIFY_NONE` and :py:const:`VERIFY_PEER`. If
409-
:py:const:`VERIFY_PEER` is used, *mode* can be OR:ed with
410-
:py:const:`VERIFY_FAIL_IF_NO_PEER_CERT` and :py:const:`VERIFY_CLIENT_ONCE`
411-
to further control the behaviour.
412-
413-
*callback* should take five arguments: A Connection object, an X509 object,
414-
and three integer variables, which are in turn potential error number, error
415-
depth and return code. *callback* should return true if verification passes
416-
and false otherwise.
417-
418-
419-
.. py:method:: Context.set_verify_depth(depth)
420-
421-
Set the maximum depth for the certificate chain verification that shall be
422-
allowed for this Context object.
423-
424-
425-
.. py:method:: Context.use_certificate(cert)
426-
427-
Use the certificate *cert* which has to be a X509 object.
428-
429-
430-
.. py:method:: Context.add_extra_chain_cert(cert)
431-
432-
Adds the certificate *cert*, which has to be a X509 object, to the
433-
certificate chain presented together with the certificate.
434-
435-
436-
.. py:method:: Context.use_certificate_chain_file(file)
437-
438-
Load a certificate chain from *file* which must be PEM encoded.
439-
440-
441-
.. py:method:: Context.use_privatekey(pkey)
442-
443-
Use the private key *pkey* which has to be a PKey object.
444-
445-
446-
.. py:method:: Context.use_certificate_file(file[, format])
447-
448-
Load the first certificate found in *file*. The certificate must be in the
449-
format specified by *format*, which is either :py:const:`FILETYPE_PEM` or
450-
:py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`.
451-
452-
453-
.. py:method:: Context.use_privatekey_file(file[, format])
454-
455-
Load the first private key found in *file*. The private key must be in the
456-
format specified by *format*, which is either :py:const:`FILETYPE_PEM` or
457-
:py:const:`FILETYPE_ASN1`. The default is :py:const:`FILETYPE_PEM`.
458-
459-
460-
.. py:method:: Context.set_tlsext_servername_callback(callback)
461-
462-
Specify a one-argument callable to use as the TLS extension server name
463-
callback. When a connection using the server name extension is made using
464-
this context, the callback will be invoked with the :py:class:`Connection`
465-
instance.
466-
467-
.. versionadded:: 0.13
468-
469-
470-
.. py:method:: Context.set_npn_advertise_callback(callback)
471-
472-
Specify a callback function that will be called when offering `Next
473-
Protocol Negotiation
474-
<https://tools.ietf.org/html/draft-agl-tls-nextprotoneg-03>`_ as a server.
475-
476-
*callback* should be the callback function. It will be invoked with one
477-
argument, the :py:class:`Connection` instance. It should return a list of
478-
bytestrings representing the advertised protocols, like
479-
``[b'http/1.1', b'spdy/2']``.
480-
481-
.. versionadded:: 0.15
482-
483-
484-
.. py:method:: Context.set_npn_select_callback(callback):
485-
486-
Specify a callback function that will be called when a server offers Next
487-
Protocol Negotiation options.
488-
489-
*callback* should be the callback function. It will be invoked with two
490-
arguments: the :py:class:`Connection`, and a list of offered protocols as
491-
bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``. It should return one of
492-
those bytestrings, the chosen protocol.
493-
494-
.. versionadded:: 0.15
495-
496-
.. py:method:: Context.set_alpn_protos(protos)
497-
498-
Specify the protocols that the client is prepared to speak after the TLS
499-
connection has been negotiated using Application Layer Protocol
500-
Negotiation.
501-
502-
*protos* should be a list of protocols that the client is offering, each
503-
as a bytestring. For example, ``[b'http/1.1', b'spdy/2']``.
504-
505-
506-
.. py:method:: Context.set_alpn_select_callback(callback)
507-
508-
Specify a callback function that will be called on the server when a client
509-
offers protocols using Application Layer Protocol Negotiation.
510-
511-
*callback* should be the callback function. It will be invoked with two
512-
arguments: the :py:class:`Connection` and a list of offered protocols as
513-
bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``. It should return one of
514-
these bytestrings, the chosen protocol.
515-
221+
.. autoclass:: OpenSSL.SSL.Context
222+
:members:
516223

517224
.. _openssl-session:
518225

0 commit comments

Comments
 (0)