From bb503a306db2eed6c9b714f23992c444b65323a8 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Thu, 19 Jun 2014 12:28:08 +0200 Subject: Use autodoc for PKCS12 --- OpenSSL/crypto.py | 69 ++++++++++++++++++++++++++++++++++-------------------- doc/api/crypto.rst | 55 ++----------------------------------------- 2 files changed, 46 insertions(+), 78 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 34ec98a..fcc89c0 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1970,6 +1970,9 @@ PKCS7Type = PKCS7 class PKCS12(object): + """ + A PKCS #12 archive. + """ def __init__(self): self._pkey = None self._cert = None @@ -1979,19 +1982,21 @@ class PKCS12(object): def get_certificate(self): """ - Return certificate portion of the PKCS12 structure + Get the certificate in the PKCS #12 structure. - :return: X509 object containing the certificate + :return: The certificate, or :py:const:`None` if there is none. + :rtype: :py:class:`X509` or :py:const:`None` """ return self._cert def set_certificate(self, cert): """ - Replace the certificate portion of the PKCS12 structure + Set the certificate in the PKCS #12 structure. - :param cert: The new certificate. + :param cert: The new certificate, or :py:const:`None` to unset it. :type cert: :py:class:`X509` or :py:data:`None` + :return: :py:data:`None` """ if not isinstance(cert, X509): @@ -2001,19 +2006,21 @@ class PKCS12(object): def get_privatekey(self): """ - Return private key portion of the PKCS12 structure + Get the private key in the PKCS #12 structure. - :returns: PKey object containing the private key + :return: The private key, or :py:const:`None` if there is none. + :rtype: :py:class:`PKey` """ return self._pkey def set_privatekey(self, pkey): """ - Replace or set the certificate portion of the PKCS12 structure + Set the certificate portion of the PKCS #12 structure. + + :param pkey: The new private key, or :py:const:`None` to unset it. + :type pkey: :py:class:`PKey` or :py:const:`None` - :param pkey: The new private key. - :type pkey: :py:class:`PKey` :return: :py:data:`None` """ if not isinstance(pkey, PKey): @@ -2023,10 +2030,11 @@ class PKCS12(object): def get_ca_certificates(self): """ - Return CA certificates within of the PKCS12 object + Get the CA certificates in the PKCS #12 structure. - :return: A newly created tuple containing the CA certificates in the chain, - if any are present, or None if no CA certificates are present. + :return: A tuple with the CA certificates in the chain, or + :py:const:`None` if there are none. + :rtype: :py:class:`tuple` of :py:class:`X509` or :py:const:`None` """ if self._cacerts is not None: return tuple(self._cacerts) @@ -2034,10 +2042,12 @@ class PKCS12(object): def set_ca_certificates(self, cacerts): """ - Replace or set the CA certificates withing the PKCS12 object. + Set the CA certificates in the PKCS #12 structure. + + :param cacerts: The new CA certificates, or :py:const:`None` to unset + them. + :type cacerts: An iterable of :py:class:`X509` or :py:data:`None` - :param cacerts: The new CA certificates. - :type cacerts: :py:data:`None` or an iterable of :py:class:`X509` :return: :py:data:`None` """ if cacerts is None: @@ -2052,10 +2062,11 @@ class PKCS12(object): def set_friendlyname(self, name): """ - Replace or set the certificate portion of the PKCS12 structure + Set the friendly name in the PKCS #12 structure. + + :param name: The new friendly name, or :py:const:`None` to unset. + :type name: :py:class:`bytes` or :py:data:`None` - :param name: The new friendly name. - :type name: :py:class:`bytes` :return: :py:data:`None` """ if name is None: @@ -2067,27 +2078,33 @@ class PKCS12(object): def get_friendlyname(self): """ - Return friendly name portion of the PKCS12 structure + Get the friendly name in the PKCS# 12 structure. - :returns: String containing the friendlyname + :returns: The friendly name, or :py:data:`None` if there is none. + :rtype: :py:class:`bytes` or :py:data:`None` """ return self._friendlyname def export(self, passphrase=None, iter=2048, maciter=1): """ - Dump a PKCS12 object as a string. See also "man PKCS12_create". + Dump a PKCS12 object as a string. + + For more information, see the :c:func:`PKCS12_create` man page. - :param passphrase: used to encrypt the PKCS12 + :param passphrase: The passphrase used to encrypt the structure. Unlike + some other passphrase arguments, this *must* be a string, not a + callback. :type passphrase: :py:data:`bytes` - :param iter: How many times to repeat the encryption + :param iter: Number of times to repeat the encryption step. :type iter: :py:data:`int` - :param maciter: How many times to repeat the MAC + :param maciter: Number of times to repeat the MAC step. :type maciter: :py:data:`int` - :return: The string containing the PKCS12 + :return: The string representation of the PKCS #12 structure. + :rtype: """ if self._cacerts is None: cacerts = _ffi.NULL @@ -2127,6 +2144,8 @@ class PKCS12(object): _lib.i2d_PKCS12_bio(bio, pkcs12) return _bio_to_string(bio) + + PKCS12Type = PKCS12 diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 6dd6a43..949f9b2 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -240,59 +240,8 @@ PKCS7 objects have the following methods: PKCS12 objects -------------- -PKCS12 objects have the following methods: - -.. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1]) - - Returns a PKCS12 object as a string. - - The optional *passphrase* must be a string not a callback. - - See also the man page for the C function :py:func:`PKCS12_create`. - - -.. py:method:: PKCS12.get_ca_certificates() - - Return CA certificates within the PKCS12 object as a tuple. Returns - :py:const:`None` if no CA certificates are present. - - -.. py:method:: PKCS12.get_certificate() - - Return certificate portion of the PKCS12 structure. - - -.. py:method:: PKCS12.get_friendlyname() - - Return friendlyName portion of the PKCS12 structure. - - -.. py:method:: PKCS12.get_privatekey() - - Return private key portion of the PKCS12 structure - - -.. py:method:: PKCS12.set_ca_certificates(cacerts) - - Replace or set the CA certificates within the PKCS12 object with the sequence *cacerts*. - - Set *cacerts* to :py:const:`None` to remove all CA certificates. - - -.. py:method:: PKCS12.set_certificate(cert) - - Replace or set the certificate portion of the PKCS12 structure. - - -.. py:method:: PKCS12.set_friendlyname(name) - - Replace or set the friendlyName portion of the PKCS12 structure. - - -.. py:method:: PKCS12.set_privatekey(pkey) - - Replace or set private key portion of the PKCS12 structure - +.. autoclass:: PKCS12 + :members: .. _openssl-509ext: -- cgit v1.2.1