From 47aa00a97351ca04972f362962f50eebfa4add44 Mon Sep 17 00:00:00 2001 From: Alex Chan Date: Tue, 13 Feb 2018 17:17:25 +0000 Subject: Use autodoc for OpenSSL.crypto --- doc/api/crypto.rst | 117 ++++++-------------------------------------------- src/OpenSSL/crypto.py | 40 +++++++++++------ 2 files changed, 42 insertions(+), 115 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/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