From c105a550666cdeb3ce35970fbf4e1ad31bae9edb Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Tue, 17 Jun 2014 15:31:46 +0200 Subject: Add autodoc to sphinx extensions --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index d9c9a67..5dc2bd9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,7 +28,7 @@ needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ["sphinx.ext.autodoc"] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -- cgit v1.2.1 From ef5c83dccfcc71f4d1ea6bde132ab1c1d5f4c947 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Tue, 17 Jun 2014 15:32:27 +0200 Subject: Add docstrings for X509Store --- OpenSSL/crypto.py | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 54569ea..06b7422 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1334,17 +1334,38 @@ class X509(object): ext._extension = _ffi.gc(extension, _lib.X509_EXTENSION_free) return ext + + X509Type = X509 class X509Store(object): + """ + An X509 certificate store. + + .. note:: The type of :py:class:`X509Store` objects was formerly + :py:class:`X509StoreType`. This name is maintained for + backwards compatibility, although you can just use + :py:class:`X509Store` now. + + """ def __init__(self): store = _lib.X509_STORE_new() self._store = _ffi.gc(store, _lib.X509_STORE_free) def add_cert(self, cert): + """ + Adds the certificate :py:data:`cert` to this store. + + This is the Python equivalent of OpenSSL's X509_STORE_add_cert. + + :param X509 cert: The certificate to add to this store. + :raises TypeError: If the certificate is not an :py:class:`X509`. + :raises Error: If OpenSSL was unhappy with your certificate. + :return: py:data:`None` if the certificate was added successfully. + """ if not isinstance(cert, X509): raise TypeError() -- cgit v1.2.1 From 8aeafdd5f3e3232d462f8ca0d7633daae1e94381 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Tue, 17 Jun 2014 15:33:42 +0200 Subject: Use autoclass for X509Store --- doc/api/crypto.rst | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index b360e89..5637ea3 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -40,11 +40,6 @@ A class representing X.509 certificate requests. -.. py:data:: X509StoreType - - A Python type object representing the X509Store object type. - - .. py:data:: PKeyType See :py:class:`PKey`. @@ -519,12 +514,8 @@ X509Req objects have the following methods: X509Store objects ----------------- -The X509Store object has currently just one method: - -.. py:method:: X509Store.add_cert(cert) - - Add the certificate *cert* to the certificate store. - +.. autoclass:: X509Store + :members: .. _openssl-pkey: -- cgit v1.2.1 From 13d56ba07833d424885dd5b8afb26bb8125ffc3c Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Tue, 17 Jun 2014 16:00:26 +0200 Subject: Pre-type/class unification Pythons are old Old enough that their artifacts in PyOpenSSL can be shipped off to a table somewhere... --- OpenSSL/crypto.py | 6 ---- doc/api/crypto.rst | 80 +++++++++++++++++++++++------------------------------- 2 files changed, 34 insertions(+), 52 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 06b7422..3a69bea 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1343,12 +1343,6 @@ X509Type = X509 class X509Store(object): """ An X509 certificate store. - - .. note:: The type of :py:class:`X509Store` objects was formerly - :py:class:`X509StoreType`. This name is maintained for - backwards compatibility, although you can just use - :py:class:`X509Store` now. - """ def __init__(self): store = _lib.X509_STORE_new() diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 5637ea3..028ddd8 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -7,21 +7,11 @@ :synopsis: Generic cryptographic module -.. py:data:: X509Type - - See :py:class:`X509`. - - .. py:class:: X509() A class representing X.509 certificates. -.. py:data:: X509NameType - - See :py:class:`X509Name`. - - .. py:class:: X509Name(x509name) A class representing X.509 Distinguished Names. @@ -30,41 +20,10 @@ instance of :py:class:`X509Name`. -.. py:data:: X509ReqType - - See :py:class:`X509Req`. - - .. py:class:: X509Req() A class representing X.509 certificate requests. - -.. py:data:: PKeyType - - See :py:class:`PKey`. - - -.. py:class:: PKey() - - A class representing DSA or RSA keys. - - -.. py:data:: PKCS7Type - - A Python type object representing the PKCS7 object type. - - -.. py:data:: PKCS12Type - - A Python type object representing the PKCS12 object type. - - -.. py:data:: X509ExtensionType - - See :py:class:`X509Extension`. - - .. py:class:: X509Extension(typename, critical, value[, subject][, issuer]) A class representing an X.509 v3 certificate extensions. See @@ -73,11 +32,6 @@ *issuer* must be X509 objects. -.. py:data:: NetscapeSPKIType - - See :py:class:`NetscapeSPKI`. - - .. py:class:: NetscapeSPKI([enc]) A class representing Netscape SPKI objects. @@ -771,3 +725,37 @@ Revoked objects have the following methods: .. py:method:: Revoked.set_serial(serial) *serial* is a string containing a hex number of the serial of the revoked certificate. + +Backwards compatible type names +------------------------------- + +When PyOpenSSL was originally written, the most current version of +Python was 2.1. It made a distinction between classes and types. None +of the versions of Python currently supported by PyOpenSSL still +enforce that distinction: the type of an instance of an +:py:class:`X509` object is now simply :py:class:`X509`. Originally, +the type would have been :py:class:`X509Type`. These days, +:py:class:`X509Type` and :py:class:`X509` are literally the same +object. PyOpenSSL maintains these old names for backwards +compatibility. + +Here's a table of these backwards-compatible names: + +========================= ============================= +Type name Backwards-compatible name +========================= ============================= +:py:class:`X509` :py:class:`X509Type` +:py:class:`X509Name` :py:class:`X509NameType` +:py:class:`X509Req` :py:class:`X509ReqType` +:py:class:`X509Store` :py:class:`X509StoreType` +:py:class:`X509Extension` :py:class:`X509ExtensionType` +:py:class:`PKey` :py:class:`PKeyType` +:py:class:`PKCS7` :py:class:`PKCS7Type` +:py:class:`PKCS12` :py:class:`PKCS12Type` +:py:class:`NetscapeSPKI` :py:class:`NetscapeSPKIType` +:py:class:`CRL` :py:class:`CRLType` +========================= ============================= + +Soem objects, such as py:class`Revoked`, don't have ``Type`` +equivalents, because they were added after the restriction had been +lifted. -- cgit v1.2.1 From 6e7dd43914bc3dafccba03d4dd2866c38e7000b8 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Tue, 17 Jun 2014 16:10:57 +0200 Subject: Use autoclass for PKey --- OpenSSL/crypto.py | 22 +++++++++++++++++----- doc/api/crypto.rst | 26 ++------------------------ 2 files changed, 19 insertions(+), 29 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 3a69bea..6cc5ff2 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -152,6 +152,9 @@ def _get_asn1_time(timestamp): class PKey(object): + """ + A class representing an DSA or RSA public key or key pair. + """ _only_public = False _initialized = True @@ -163,12 +166,19 @@ class PKey(object): def generate_key(self, type, bits): """ - Generate a key of a given type, with a given number of a bits + Generate a key pair of the given type, with the given number of a bits. - :param type: The key type (TYPE_RSA or TYPE_DSA) - :param bits: The number of bits + This generates a key "into" the this object. - :return: None + :param type: The key type. + :type type: :py:data:`TYPE_RSA` or :py:data:`TYPE_DSA` + :param bits: The number of bits. + :type bits: :py:data:`int` ``>= 0`` + :raises TypeError: If :py:data:`type` or :py:data:`bits` isn't + of the appropriate type. + :raises ValueError: If the number of bits isn't an integer of + the appropriate size. + :return: :py:data:`None` """ if not isinstance(type, int): raise TypeError("type must be an integer") @@ -225,6 +235,8 @@ class PKey(object): """ Check the consistency of an RSA private key. + This is the Python equivalent of OpenSSL's ``RSA_check_key``. + :return: True if key is consistent. :raise Error: if the key is inconsistent. :raise TypeError: if the key is of a type which cannot be checked. @@ -1353,7 +1365,7 @@ class X509Store(object): """ Adds the certificate :py:data:`cert` to this store. - This is the Python equivalent of OpenSSL's X509_STORE_add_cert. + This is the Python equivalent of OpenSSL's ``X509_STORE_add_cert``. :param X509 cert: The certificate to add to this store. :raises TypeError: If the certificate is not an :py:class:`X509`. diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 028ddd8..e3d4f14 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -476,30 +476,8 @@ X509Store objects PKey objects ------------ -The PKey object has the following methods: - -.. py:method:: PKey.bits() - - Return the number of bits of the key. - - -.. py:method:: PKey.generate_key(type, bits) - - Generate a public/private key pair of the type *type* (one of - :py:const:`TYPE_RSA` and :py:const:`TYPE_DSA`) with the size *bits*. - - -.. py:method:: PKey.type() - - Return the type of the key. - - -.. py:method:: PKey.check() - - Check the consistency of this key, returning True if it is consistent and - raising an exception otherwise. This is only valid for RSA keys. See the - OpenSSL RSA_check_key man page for further limitations. - +.. autoclass:: PKey + :members: .. _openssl-pkcs7: -- cgit v1.2.1 From 196195b794d11ca69055fa99cf01d71ec623dd5f Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Tue, 17 Jun 2014 17:06:34 +0200 Subject: Use autodoc for X509Name --- OpenSSL/crypto.py | 45 +++++++++++++++++++++++++++------ doc/api/crypto.rst | 74 +++--------------------------------------------------- 2 files changed, 41 insertions(+), 78 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 6cc5ff2..9af7927 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -427,11 +427,35 @@ def get_elliptic_curve(name): class X509Name(object): + """ + An X.509 Distinguished Name. + + :ivar countryName: The country of the entity. + :ivar C: Alias for :py:attr:`countryName`. + + :ivar stateOrProvinceName: The state or province of the entity. + :ivar ST: Alias for :py:attr:`stateOrProvinceName`. + + :ivar localityName: The locality of the entity. + :ivar L: Alias for :py:attr:`localityName`. + + :ivar organizationName: The organization name of the entity. + :ivar O: Alias for :py:attr:`organizationName`. + + :ivar organizationalUnitName: The organizational unit of the entity. + :ivar OU: Alias for :py:attr:`organizationalUnitName` + + :ivar commonName: The common name of the entity. + :ivar CN: Alias for :py:attr:`commonName`. + + :ivar emailAddress: The e-mail address of the entity. + """ def __init__(self, name): """ Create a new X509Name, copying the given X509Name instance. - :param name: An X509Name object to copy + :param name: The name to copy. + :type name: :py:class:`X509Name` """ name = _lib.X509_NAME_dup(name._name) self._name = _ffi.gc(name, _lib.X509_NAME_free) @@ -550,19 +574,23 @@ class X509Name(object): def hash(self): """ - Return the hash value of this name + Return an integer representation of the first four bytes of the + MD5 digest of the DER representation of the name. - :return: None + This is the Python equivalent of OpenSSL's ``X509_NAME_hash``. + + :return: The (integer) hash of this name. + :rtype: :py:class:`int` """ return _lib.X509_NAME_hash(self._name) def der(self): """ - Return the DER encoding of this name + Return the DER encoding of this name. - :return: A :py:class:`bytes` instance giving the DER encoded form of - this name. + :return: The DER encoded form of this name. + :rtype: :py:class:`bytes` """ result_buffer = _ffi.new('unsigned char**') encode_result = _lib.i2d_X509_NAME(self._name, result_buffer) @@ -577,9 +605,10 @@ class X509Name(object): def get_components(self): """ - Returns the split-up components of this name. + Returns the components of this name, as a sequence of 2-tuples. - :return: List of tuples (name, value). + :return: The components of this name. + :rtype: :py:class:`list` of ``name, value`` tuples. """ result = [] for i in range(_lib.X509_NAME_entry_count(self._name)): diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index e3d4f14..9beadce 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,15 +11,6 @@ A class representing X.509 certificates. - -.. py:class:: X509Name(x509name) - - A class representing X.509 Distinguished Names. - - This constructor creates a copy of *x509name* which should be an - instance of :py:class:`X509Name`. - - .. py:class:: X509Req() A class representing X.509 certificate requests. @@ -322,7 +313,6 @@ X509 objects have the following methods: by OpenSSL (by EVP_get_digestbyname, specifically). For example, :py:const:`"md5"` or :py:const:`"sha1"`. - .. py:method:: X509.add_extensions(extensions) Add the extensions in the sequence *extensions* to the certificate. @@ -351,66 +341,10 @@ X509 objects have the following methods: X509Name objects ---------------- -X509Name objects have the following methods: - -.. py:method:: X509Name.hash() - - Return an integer giving the first four bytes of the MD5 digest of the DER - representation of the name. - - -.. py:method:: X509Name.der() - - Return a string giving the DER representation of the name. - - -.. py:method:: X509Name.get_components() - - Return a list of two-tuples of strings giving the components of the name. - - -X509Name objects have the following members: - -.. py:attribute:: X509Name.countryName - - The country of the entity. :py:attr:`C` may be used as an alias for - :py:attr:`countryName`. - - -.. py:attribute:: X509Name.stateOrProvinceName - - The state or province of the entity. :py:attr:`ST` may be used as an alias for - :py:attr:`stateOrProvinceName`. - - -.. py:attribute:: X509Name.localityName - - The locality of the entity. :py:attr:`L` may be used as an alias for - :py:attr:`localityName`. - - -.. py:attribute:: X509Name.organizationName - - The organization name of the entity. :py:attr:`O` may be used as an alias for - :py:attr:`organizationName`. - - -.. py:attribute:: X509Name.organizationalUnitName - - The organizational unit of the entity. :py:attr:`OU` may be used as an alias for - :py:attr:`organizationalUnitName`. - - -.. py:attribute:: X509Name.commonName - - The common name of the entity. :py:attr:`CN` may be used as an alias for - :py:attr:`commonName`. - - -.. py:attribute:: X509Name.emailAddress - - The e-mail address of the entity. - +.. autoclass:: X509Name + :members: + :special-members: + :exclude-members: __repr__, __getattr__, __weakref__ .. _openssl-x509req: -- cgit v1.2.1 From 2650de5db6d2a10d2fb81037f91ea9bdeffa765b Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Wed, 18 Jun 2014 13:47:47 +0200 Subject: Use autodoc for X509Extension --- OpenSSL/crypto.py | 39 +++++++++++++++++++++++++++++---------- doc/api/crypto.rst | 36 ++++-------------------------------- 2 files changed, 33 insertions(+), 42 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 9af7927..de00905 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -627,27 +627,35 @@ class X509Name(object): _lib.ASN1_STRING_length(fval)))) return result + + + X509NameType = X509Name + class X509Extension(object): + """ + An X.509 v3 certificate extension. + """ def __init__(self, type_name, critical, value, subject=None, issuer=None): """ - :param typename: The name of the extension to create. + Initializes an X509 extension. + + :param typename: The name of the type of extension to create. See + http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS :type typename: :py:data:`str` - :param critical: A flag indicating whether this is a critical extension. + :param bool critical: A flag indicating whether this is a critical extension. :param value: The value of the extension. :type value: :py:data:`str` - :param subject: Optional X509 cert to use as subject. + :param subject: Optional X509 certificate to use as subject. :type subject: :py:class:`X509` - :param issuer: Optional X509 cert to use as issuer. + :param issuer: Optional X509 certificate to use as issuer. :type issuer: :py:class:`X509` - - :return: The X509Extension object """ ctx = _ffi.new("X509V3_CTX*") @@ -752,7 +760,7 @@ class X509Extension(object): def get_critical(self): """ - Returns the critical field of the X509Extension + Returns the critical field of this X.509 extension. :return: The critical field. """ @@ -761,9 +769,14 @@ class X509Extension(object): def get_short_name(self): """ - Returns the short version of the type name of the X509Extension + Returns the short type name of this X.509 extension. + + The result is a byte string such as :py:const:`b"basicConstraints"`. :return: The short type name. + :rtype: :py:data:`bytes` + + .. versionadded:: 0.12 """ obj = _lib.X509_EXTENSION_get_object(self._extension) nid = _lib.OBJ_obj2nid(obj) @@ -772,9 +785,12 @@ class X509Extension(object): def get_data(self): """ - Returns the data of the X509Extension + Returns the data of the X509 extension, encoded as ASN.1. + + :return: The ASN.1 encoded data of this X509 extension. + :rtype: :py:data:`bytes` - :return: A :py:data:`str` giving the X509Extension's ASN.1 encoded data. + .. versionadded:: 0.12 """ octet_result = _lib.X509_EXTENSION_get_data(self._extension) string_result = _ffi.cast('ASN1_STRING*', octet_result) @@ -782,9 +798,12 @@ class X509Extension(object): result_length = _lib.ASN1_STRING_length(string_result) return _ffi.buffer(char_result, result_length)[:] + + X509ExtensionType = X509Extension + class X509Req(object): def __init__(self): req = _lib.X509_REQ_new() diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 9beadce..ab2b90a 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -15,14 +15,6 @@ A class representing X.509 certificate requests. -.. py:class:: X509Extension(typename, critical, value[, subject][, issuer]) - - A class representing an X.509 v3 certificate extensions. See - http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for - *typename* strings and their options. Optional parameters *subject* and - *issuer* must be X509 objects. - - .. py:class:: NetscapeSPKI([enc]) A class representing Netscape SPKI objects. @@ -509,30 +501,10 @@ PKCS12 objects have the following methods: X509Extension objects --------------------- -X509Extension objects have several methods: - -.. py:method:: X509Extension.get_critical() - - Return the critical field of the extension object. - - -.. py:method:: X509Extension.get_short_name() - - Retrieve the short descriptive name for this extension. - - The result is a byte string like :py:const:`basicConstraints`. - - .. versionadded:: 0.12 - - -.. py:method:: X509Extension.get_data() - - Retrieve the data for this extension. - - The result is the ASN.1 encoded form of the extension data as a byte string. - - .. versionadded:: 0.12 - +.. autoclass:: X509Extension + :members: + :special-members: + :exclude-members: __weakref__ .. _openssl-netscape-spki: -- cgit v1.2.1 From 3e83d24aed04ef0a8c0e8d89f3a48a5cd568b0b2 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Wed, 18 Jun 2014 14:29:47 +0200 Subject: Use autodoc for X509Req --- OpenSSL/crypto.py | 68 +++++++++++++++++++++++++++++++++++------------------- doc/api/crypto.rst | 54 ++++--------------------------------------- 2 files changed, 48 insertions(+), 74 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index de00905..8722a9f 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -805,6 +805,9 @@ X509ExtensionType = X509Extension class X509Req(object): + """ + An X.509 certificate signing requests. + """ def __init__(self): req = _lib.X509_REQ_new() self._req = _ffi.gc(req, _lib.X509_REQ_free) @@ -812,10 +815,12 @@ class X509Req(object): def set_pubkey(self, pkey): """ - Set the public key of the certificate request + Set the public key of the certificate signing request. - :param pkey: The public key to use - :return: None + :param pkey: The public key to use. + :type pkey: :py:class:`PKey` + + :return: :py:data:`None` """ set_result = _lib.X509_REQ_set_pubkey(self._req, pkey._pkey) if not set_result: @@ -825,9 +830,10 @@ class X509Req(object): def get_pubkey(self): """ - Get the public key from the certificate request + Get the public key of the certificate signing request. - :return: The public key + :return: The public key. + :rtype: :py:class:`PKey` """ pkey = PKey.__new__(PKey) pkey._pkey = _lib.X509_REQ_get_pubkey(self._req) @@ -844,8 +850,8 @@ class X509Req(object): Set the version subfield (RFC 2459, section 4.1.2.1) of the certificate request. - :param version: The version number - :return: None + :param int version: The version number. + :return: :py:data:`None` """ set_result = _lib.X509_REQ_set_version(self._req, version) if not set_result: @@ -857,16 +863,21 @@ class X509Req(object): Get the version subfield (RFC 2459, section 4.1.2.1) of the certificate request. - :return: an integer giving the value of the version subfield + :return: The value of the version subfield. + :rtype: :py:class:`int` """ return _lib.X509_REQ_get_version(self._req) def get_subject(self): """ - Create an X509Name object for the subject of the certificate request + Return the subject of this certificate signing request. - :return: An X509Name object + This creates a new :py:class:`X509Name`: modifying it does not affect + this request. + + :return: The subject of this certificate signing request. + :rtype: :py:class:`X509Name` """ name = X509Name.__new__(X509Name) name._name = _lib.X509_REQ_get_subject_name(self._req) @@ -883,10 +894,11 @@ class X509Req(object): def add_extensions(self, extensions): """ - Add extensions to the request. + Add extensions to the certificate signing request. - :param extensions: a sequence of X509Extension objects - :return: None + :param extensions: The X.509 extensions to add. + :type extensions: iterable of :py:class:`X509Extension` + :return: :py:data:`None` """ stack = _lib.sk_X509_EXTENSION_new_null() if stack == _ffi.NULL: @@ -910,9 +922,12 @@ class X509Req(object): def get_extensions(self): """ - Get extensions to the request. + Get X.509 extensions in the certificate signing request. + + :return: The X.509 extensions in this request. + :rtype: :py:class:`list` of :py:class:`X509Extension` objects. - :return: A :py:class:`list` of :py:class:`X509Extension` objects. + .. versionadded:: 0.15 """ exts = [] native_exts_obj = _lib.X509_REQ_get_extensions(self._req) @@ -925,11 +940,14 @@ class X509Req(object): def sign(self, pkey, digest): """ - Sign the certificate request using the supplied key and digest + Sign the certificate signing request using the supplied key and digest. - :param pkey: The key to sign with - :param digest: The message digest to use - :return: None + :param pkey: The key pair to sign with. + :type pkey: :py:class:`PKey` + :param digest: The name of the message digest to use for the signature, + e.g. :py:data:`b"sha1"`. + :type digest: :py:class:`bytes` + :return: :py:data:`None` """ if pkey._only_public: raise ValueError("Key has only public part") @@ -949,12 +967,13 @@ class X509Req(object): def verify(self, pkey): """ - Verifies a certificate request using the supplied public key + Verifies the signature on this certificate signing request. - :param key: a public key - :return: True if the signature is correct. - - :raise OpenSSL.crypto.Error: If the signature is invalid or there is a + :param key: A public key. + :type key: :py:class:`PKey` + :return: :py:data:`True` if the signature is correct. + :rtype: :py:class:`bool` + :raises Error: If the signature is invalid or there is a problem verifying the signature. """ if not isinstance(pkey, PKey): @@ -967,6 +986,7 @@ class X509Req(object): return result + X509ReqType = X509Req diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index ab2b90a..194857a 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -6,15 +6,10 @@ .. py:module:: OpenSSL.crypto :synopsis: Generic cryptographic module - .. py:class:: X509() A class representing X.509 certificates. -.. py:class:: X509Req() - - A class representing X.509 certificate requests. - .. py:class:: NetscapeSPKI([enc]) A class representing Netscape SPKI objects. @@ -343,51 +338,10 @@ X509Name objects X509Req objects --------------- -X509Req objects have the following methods: - -.. py:method:: X509Req.get_pubkey() - - Return a :py:class:`PKey` object representing the public key of the certificate request. - - -.. py:method:: X509Req.get_subject() - - Return an :py:class:`X509Name` object representing the subject of the certificate. - - -.. py:method:: X509Req.set_pubkey(pkey) - - Set the public key of the certificate request to *pkey*. - - -.. py:method:: X509Req.sign(pkey, digest) - - Sign the certificate request, using the key *pkey* and the message digest - algorithm identified by the string *digest*. - - -.. py:method:: X509Req.verify(pkey) - - Verify a certificate request using the public key *pkey*. - - -.. py:method:: X509Req.set_version(version) - - Set the version (RFC 2459, 4.1.2.1) of the certificate request to - *version*. - - -.. py:method:: X509Req.get_version() - - Get the version (RFC 2459, 4.1.2.1) of the certificate request. - - -.. py:method:: X509Req.get_extensions() - - Get extensions to the request. - - .. versionadded:: 0.15 - +.. autoclass:: X509Req + :members: + :special-members: + :exclude-members: __weakref__ .. _openssl-x509store: -- cgit v1.2.1 From c3baa7bd59508aabc560a4145c25e2d460cce77d Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Wed, 18 Jun 2014 22:06:56 +0200 Subject: Use autodoc for X509 --- OpenSSL/crypto.py | 218 ++++++++++++++++++++++++++++++++--------------------- doc/api/crypto.rst | 179 ++++--------------------------------------- 2 files changed, 145 insertions(+), 252 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 8722a9f..34ec98a 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -992,6 +992,9 @@ X509ReqType = X509Req class X509(object): + """ + An X.509 certificate. + """ def __init__(self): # TODO Allocation failure? And why not __new__ instead of __init__? x509 = _lib.X509_new() @@ -1000,12 +1003,12 @@ class X509(object): def set_version(self, version): """ - Set version number of the certificate + Set the version number of the certificate. - :param version: The version number + :param version: The version number of the certificate. :type version: :py:class:`int` - :return: None + :return: :py:data:`None` """ if not isinstance(version, int): raise TypeError("version must be an integer") @@ -1015,18 +1018,20 @@ class X509(object): def get_version(self): """ - Return version number of the certificate + Return the version number of the certificate. - :return: Version number as a Python integer + :return: The version number of the certificate. + :rtype: :py:class:`int` """ return _lib.X509_get_version(self._x509) def get_pubkey(self): """ - Get the public key of the certificate + Get the public key of the certificate. - :return: The public key + :return: The public key. + :rtype: :py:class:`PKey` """ pkey = PKey.__new__(PKey) pkey._pkey = _lib.X509_get_pubkey(self._x509) @@ -1039,11 +1044,12 @@ class X509(object): def set_pubkey(self, pkey): """ - Set the public key of the certificate + Set the public key of the certificate. - :param pkey: The public key + :param pkey: The public key. + :type pkey: :py:class:`PKey` - :return: None + :return: :py:data`None` """ if not isinstance(pkey, PKey): raise TypeError("pkey must be a PKey instance") @@ -1055,11 +1061,15 @@ class X509(object): def sign(self, pkey, digest): """ - Sign the certificate using the supplied key and digest + Sign the certificate using the supplied key and digest type. - :param pkey: The key to sign with - :param digest: The message digest to use - :return: None + :param pkey: The key to sign with. + :type pkey: :py:class:`PKey` + + :param digest: The name of the message digest to use. + :type digest: :py:class:`bytes` + + :return: :py:data`None` """ if not isinstance(pkey, PKey): raise TypeError("pkey must be a PKey instance") @@ -1081,11 +1091,14 @@ class X509(object): def get_signature_algorithm(self): """ - Retrieve the signature algorithm used in the certificate + Return the signature algorithm used in the certificate. + + :return: The name of the algorithm. + :rtype: :py:class:`bytes` + + :raises ValueError: If the signature algorithm is undefined. - :return: A byte string giving the name of the signature algorithm used in - the certificate. - :raise ValueError: If the signature algorithm is undefined. + ..versionadded:: 0.13 """ alg = self._x509.cert_info.signature.algorithm nid = _lib.OBJ_obj2nid(alg) @@ -1101,7 +1114,9 @@ class X509(object): :param digest_name: The name of the digest algorithm to use. :type digest_name: :py:class:`bytes` - :return: The digest of the object + :return: The digest of the object, formatted as + :py:const:`b":"`-delimited hex pairs. + :rtype: :py:class:`bytes` """ digest = _lib.EVP_get_digestbyname(_byte_string(digest_name)) if digest == _ffi.NULL: @@ -1128,18 +1143,19 @@ class X509(object): Return the hash of the X509 subject. :return: The hash of the subject. + :rtype: :py:class:`bytes` """ return _lib.X509_subject_name_hash(self._x509) def set_serial_number(self, serial): """ - Set serial number of the certificate + Set the serial number of the certificate. - :param serial: The serial number + :param serial: The new serial number. :type serial: :py:class:`int` - :return: None + :return: :py:data`None` """ if not isinstance(serial, _integer_types): raise TypeError("serial must be an integer") @@ -1176,9 +1192,10 @@ class X509(object): def get_serial_number(self): """ - Return serial number of the certificate + Return the serial number of this certificate. - :return: Serial number as a Python integer + :return: The serial number. + :rtype: :py:class:`int` """ asn1_serial = _lib.X509_get_serialNumber(self._x509) bignum_serial = _lib.ASN1_INTEGER_to_BN(asn1_serial, _ffi.NULL) @@ -1196,13 +1213,12 @@ class X509(object): def gmtime_adj_notAfter(self, amount): """ - Adjust the time stamp for when the certificate stops being valid + Adjust the time stamp on which the certificate stops being valid. - :param amount: The number of seconds by which to adjust the ending - validity time. + :param amount: The number of seconds by which to adjust the timestamp. :type amount: :py:class:`int` - :return: None + :return: :py:data:`None` """ if not isinstance(amount, int): raise TypeError("amount must be an integer") @@ -1213,12 +1229,10 @@ class X509(object): def gmtime_adj_notBefore(self, amount): """ - Change the timestamp for when the certificate starts being valid to the current - time plus an offset. + Adjust the timestamp on which the certificate starts being valid. - :param amount: The number of seconds by which to adjust the starting validity - time. - :return: None + :param amount: The number of seconds by which to adjust the timestamp. + :return: :py:data:`None` """ if not isinstance(amount, int): raise TypeError("amount must be an integer") @@ -1231,7 +1245,9 @@ class X509(object): """ Check whether the certificate has expired. - :return: True if the certificate has expired, false otherwise + :return: :py:const:`True` if the certificate has expired, + :py:const:`False` otherwise. + :rtype: :py:class:`bool` """ now = int(time()) notAfter = _lib.X509_get_notAfter(self._x509) @@ -1245,15 +1261,16 @@ class X509(object): def get_notBefore(self): """ - Retrieve the time stamp for when the certificate starts being valid + Get the timestamp at which the certificate starts being valid. - :return: A string giving the timestamp, in the format:: + The timestamp is formatted as an ASN.1 GENERALIZEDTIME:: - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm + YYYYMMDDhhmmssZ + YYYYMMDDhhmmss+hhmm + YYYYMMDDhhmmss-hhmm - or None if there is no value set. + :return: A timestamp string, or :py:const:`None` if there is none. + :rtype: :py:class:`bytes` or :py:const:`None` """ return self._get_boundary_time(_lib.X509_get_notBefore) @@ -1264,47 +1281,52 @@ class X509(object): def set_notBefore(self, when): """ - Set the time stamp for when the certificate starts being valid + Set the timestamp at which the certificate starts being valid. - :param when: A string giving the timestamp, in the format: + The timestamp is formatted as an ASN.1 GENERALIZEDTIME:: - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm + YYYYMMDDhhmmssZ + YYYYMMDDhhmmss+hhmm + YYYYMMDDhhmmss-hhmm + + :param when: A timestamp string. :type when: :py:class:`bytes` - :return: None + :return: :py:data:`None` """ return self._set_boundary_time(_lib.X509_get_notBefore, when) def get_notAfter(self): """ - Retrieve the time stamp for when the certificate stops being valid + Get the timestamp at which the certificate stops being valid. - :return: A string giving the timestamp, in the format:: + The timestamp is formatted as an ASN.1 GENERALIZEDTIME:: - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm + YYYYMMDDhhmmssZ + YYYYMMDDhhmmss+hhmm + YYYYMMDDhhmmss-hhmm - or None if there is no value set. + :return: A timestamp string, or :py:const:`None` if there is none. + :rtype: :py:class:`bytes` or :py:const:`None` """ return self._get_boundary_time(_lib.X509_get_notAfter) def set_notAfter(self, when): """ - Set the time stamp for when the certificate stops being valid + Set the timestamp at which the certificate stops being valid. - :param when: A string giving the timestamp, in the format: + The timestamp is formatted as an ASN.1 GENERALIZEDTIME:: - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm + YYYYMMDDhhmmssZ + YYYYMMDDhhmmss+hhmm + YYYYMMDDhhmmss-hhmm + + :param when: A timestamp string. :type when: :py:class:`bytes` - :return: None + :return: :py:data:`None` """ return self._set_boundary_time(_lib.X509_get_notAfter, when) @@ -1334,50 +1356,62 @@ class X509(object): def get_issuer(self): """ - Create an X509Name object for the issuer of the certificate + Return the issuer of this certificate. + + This creates a new :py:class:`X509Name`: modifying it does not affect + this certificate. - :return: An X509Name object + :return: The issuer of this certificate. + :rtype: :py:class:`X509Name` """ return self._get_name(_lib.X509_get_issuer_name) def set_issuer(self, issuer): """ - Set the issuer of the certificate + Set the issuer of this certificate. - :param issuer: The issuer name + :param issuer: The issuer. :type issuer: :py:class:`X509Name` - :return: None + :return: :py:data:`None` """ return self._set_name(_lib.X509_set_issuer_name, issuer) def get_subject(self): """ - Create an X509Name object for the subject of the certificate + Return the subject of this certificate. + + This creates a new :py:class:`X509Name`: modifying it does not affect + this certificate. - :return: An X509Name object + :return: The subject of this certificate. + :rtype: :py:class:`X509Name` """ return self._get_name(_lib.X509_get_subject_name) def set_subject(self, subject): """ - Set the subject of the certificate + Set the subject of this certificate. - :param subject: The subject name + :param subject: The subject. :type subject: :py:class:`X509Name` - :return: None + + :return: :py:data:`None` """ return self._set_name(_lib.X509_set_subject_name, subject) def get_extension_count(self): """ - Get the number of extensions on the certificate. + Get the number of extensions on this certificate. - :return: The number of extensions as an integer. + :return: The number of extensions. + :rtype: :py:class:`int` + + .. versionadded:: 0.12 """ return _lib.X509_get_ext_count(self._x509) @@ -1386,8 +1420,9 @@ class X509(object): """ Add extensions to the certificate. - :param extensions: a sequence of X509Extension objects - :return: None + :param extensions: The extensions to add. + :type extensions: An iterable of :py:class:`X509Extension` objects. + :return: :py:data:`None` """ for ext in extensions: if not isinstance(ext, X509Extension): @@ -1402,8 +1437,15 @@ class X509(object): """ Get a specific extension of the certificate by index. - :param index: The index of the extension to retrieve. - :return: The X509Extension object at the specified index. + Extensions on a certificate are kept in order. The index + parameter selects which extension will be returned. + + :param int index: The index of the extension to retrieve. + :return: The extension at the specified index. + :rtype: :py:class:`X509Extension` + :raises IndexError: If the extension index was out of bounds. + + .. versionadded:: 0.12 """ ext = X509Extension.__new__(X509Extension) ext._extension = _lib.X509_get_ext(self._x509, index) @@ -1616,7 +1658,7 @@ class Revoked(object): :param hex_str: The new serial number. :type hex_str: :py:data:`str` - :return: None + :return: :py:data:`None` """ bignum_serial = _ffi.gc(_lib.BN_new(), _lib.BN_free) bignum_ptr = _ffi.new("BIGNUM**") @@ -1665,7 +1707,7 @@ class Revoked(object): :param reason: The reason string. :type reason: :py:class:`str` or :py:class:`NoneType` - :return: None + :return: :py:data:`None` """ if reason is None: self._delete_reason() @@ -1736,7 +1778,7 @@ class Revoked(object): YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm - :return: None + :return: :py:data:`None` """ return _set_asn1_time(self._revoked.revocationDate, when) @@ -1789,7 +1831,7 @@ class CRL(object): :param revoked: The new revoked. :type revoked: :class:`X509` - :return: None + :return: :py:data:`None` """ copy = _X509_REVOKED_dup(revoked._revoked) if copy == _ffi.NULL: @@ -1950,7 +1992,7 @@ class PKCS12(object): :param cert: The new certificate. :type cert: :py:class:`X509` or :py:data:`None` - :return: None + :return: :py:data:`None` """ if not isinstance(cert, X509): raise TypeError("cert must be an X509 instance") @@ -1972,7 +2014,7 @@ class PKCS12(object): :param pkey: The new private key. :type pkey: :py:class:`PKey` - :return: None + :return: :py:data:`None` """ if not isinstance(pkey, PKey): raise TypeError("pkey must be a PKey instance") @@ -1996,7 +2038,7 @@ class PKCS12(object): :param cacerts: The new CA certificates. :type cacerts: :py:data:`None` or an iterable of :py:class:`X509` - :return: None + :return: :py:data:`None` """ if cacerts is None: self._cacerts = None @@ -2014,7 +2056,7 @@ class PKCS12(object): :param name: The new friendly name. :type name: :py:class:`bytes` - :return: None + :return: :py:data:`None` """ if name is None: self._friendlyname = None @@ -2101,7 +2143,7 @@ class NetscapeSPKI(object): :param pkey: The key to sign with :param digest: The message digest to use - :return: None + :return: :py:data:`None` """ if pkey._only_public: raise ValueError("Key has only public part") @@ -2125,8 +2167,8 @@ class NetscapeSPKI(object): :param key: a public key :return: True if the signature is correct. - :raise OpenSSL.crypto.Error: If the signature is invalid or there is a - problem verifying the signature. + :raises Error: If the signature is invalid, or there was a problem + verifying the signature. """ answer = _lib.NETSCAPE_SPKI_verify(self._spki, key._pkey) if answer <= 0: @@ -2167,7 +2209,7 @@ class NetscapeSPKI(object): Set the public key of the certificate :param pkey: The public key - :return: None + :return: :py:data:`None` """ set_result = _lib.NETSCAPE_SPKI_set_pubkey(self._spki, pkey._pkey) if not set_result: @@ -2370,13 +2412,13 @@ def sign(pkey, data, digest): def verify(cert, signature, data, digest): """ - Verify a signature + Verify a signature. :param cert: signing certificate (X509 object) :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 + :return: :py:data:`None` if the signature is correct, raise exception otherwise """ digest_obj = _lib.EVP_get_digestbyname(_byte_string(digest)) if digest_obj == _ffi.NULL: diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 194857a..293a8a3 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -6,10 +6,6 @@ .. py:module:: OpenSSL.crypto :synopsis: Generic cryptographic module -.. py:class:: X509() - - A class representing X.509 certificates. - .. py:class:: NetscapeSPKI([enc]) A class representing Netscape SPKI objects. @@ -162,166 +158,8 @@ X509 objects ------------ -X509 objects have the following methods: - -.. py:method:: X509.get_issuer() - - Return an X509Name object representing the issuer of the certificate. - - -.. py:method:: X509.get_pubkey() - - Return a :py:class:`PKey` object representing the public key of the certificate. - - -.. py:method:: X509.get_serial_number() - - Return the certificate serial number. - - -.. py:method:: X509.get_signature_algorithm() - - Return the signature algorithm used in the certificate. If the algorithm is - undefined, raise :py:data:`ValueError`. - - ..versionadded:: 0.13 - - -.. py:method:: X509.get_subject() - - Return an :py:class:`X509Name` object representing the subject of the certificate. - - -.. py:method:: X509.get_version() - - Return the certificate version. - - -.. py:method:: X509.get_notBefore() - - Return a string giving the time before which the certificate is not valid. The - string is formatted as an ASN1 GENERALIZEDTIME:: - - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm - - If no value exists for this field, :py:data:`None` is returned. - - -.. py:method:: X509.get_notAfter() - - Return a string giving the time after which the certificate is not valid. The - string is formatted as an ASN1 GENERALIZEDTIME:: - - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm - - If no value exists for this field, :py:data:`None` is returned. - - -.. py:method:: X509.set_notBefore(when) - - Change the time before which the certificate is not valid. *when* is a - string formatted as an ASN1 GENERALIZEDTIME:: - - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm - - -.. py:method:: X509.set_notAfter(when) - - Change the time after which the certificate is not valid. *when* is a - string formatted as an ASN1 GENERALIZEDTIME:: - - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm - - - -.. py:method:: X509.gmtime_adj_notBefore(time) - - Adjust the timestamp (in GMT) when the certificate starts being valid. - - -.. py:method:: X509.gmtime_adj_notAfter(time) - - Adjust the timestamp (in GMT) when the certificate stops being valid. - - -.. py:method:: X509.has_expired() - - Checks the certificate's time stamp against current time. Returns true if the - certificate has expired and false otherwise. - - -.. py:method:: X509.set_issuer(issuer) - - Set the issuer of the certificate to *issuer*. - - -.. py:method:: X509.set_pubkey(pkey) - - Set the public key of the certificate to *pkey*. - - -.. py:method:: X509.set_serial_number(serialno) - - Set the serial number of the certificate to *serialno*. - - -.. py:method:: X509.set_subject(subject) - - Set the subject of the certificate to *subject*. - - -.. py:method:: X509.set_version(version) - - Set the certificate version to *version*. - - -.. py:method:: X509.sign(pkey, digest) - - Sign the certificate, using the key *pkey* and the message digest algorithm - identified by the string *digest*. - - -.. py:method:: X509.subject_name_hash() - - Return the hash of the certificate subject. - -.. py:method:: X509.digest(digest_name) - - Return a digest of the certificate, using the *digest_name* method. - *digest_name* must be a string describing a digest algorithm supported - by OpenSSL (by EVP_get_digestbyname, specifically). For example, - :py:const:`"md5"` or :py:const:`"sha1"`. - -.. py:method:: X509.add_extensions(extensions) - - Add the extensions in the sequence *extensions* to the certificate. - - -.. py:method:: X509.get_extension_count() - - Return the number of extensions on this certificate. - - .. versionadded:: 0.12 - - -.. py:method:: X509.get_extension(index) - - Retrieve the extension on this certificate at the given index. - - Extensions on a certificate are kept in order. The index parameter selects - which extension will be returned. The returned object will be an - :py:class:`X509Extension` instance. - - .. versionadded:: 0.12 - +.. autoclass:: X509 + :members: .. _openssl-x509name: @@ -564,6 +402,19 @@ Revoked objects have the following methods: *serial* is a string containing a hex number of the serial of the revoked certificate. +Digest names +------------ + +Several of the functions and methods in this module take a digest +name. These must be strings describing a digest algorithm supported by +OpenSSL (by ``EVP_get_digestbyname``, specifically). For example, +:py:const:`b"md5"` or :py:const:`b"sha1"`. + +More information and a list of these digest names can be found in the +``EVP_DigestInit(3)`` man page of your OpenSSL installation. This page +can be found online for the latest version of OpenSSL: +https://www.openssl.org/docs/crypto/EVP_DigestInit.html + Backwards compatible type names ------------------------------- -- cgit v1.2.1 From 07051d3b186dc7b63807e0777f2d5321d66ee81a Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Thu, 19 Jun 2014 12:00:30 +0200 Subject: Generic structural cleanups --- doc/api/crypto.rst | 64 +++++++++++++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 293a8a3..6dd6a43 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -24,23 +24,17 @@ A class representing Revocation objects of CRL. - -.. py:data:: FILETYPE_PEM - FILETYPE_ASN1 - - File type constants. - - .. py:data:: TYPE_RSA TYPE_DSA Key type constants. - .. py:exception:: Error Generic exception used in the :py:mod:`.crypto` module. +Elliptic curves +--------------- .. py:function:: get_elliptic_curves @@ -64,17 +58,43 @@ If the named curve is not supported then :py:class:`ValueError` is raised. +Serialization and deserialization +--------------------------------- + +The following serialization functions take one of these constants to +determine the format: + +.. py:data:: FILETYPE_PEM + FILETYPE_ASN1 + +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) + + Load a certificate (X509) from the string *buffer* encoded with the + type *type*. + +Certificate signing requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. py:function:: dump_certificate_request(type, req) 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*. + +Private keys +~~~~~~~~~~~~ .. py:function:: dump_privatekey(type, pkey[, cipher, passphrase]) @@ -85,19 +105,6 @@ *passphrase* must be either a string or a callback for providing the pass phrase. - -.. py:function:: load_certificate(type, buffer) - - Load a certificate (X509) from the string *buffer* 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*. - - .. py:function:: load_privatekey(type, buffer[, passphrase]) Load a private key (PKey) from the string *buffer* encoded with the type @@ -107,6 +114,8 @@ *passphrase* must be either a string or a callback for providing the pass phrase. +Certificate revocation lists +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. py:function:: load_crl(type, buffer) @@ -128,6 +137,8 @@ See also the man page for the C function :py:func:`PKCS12_parse`. +Signing and verifying signatures +-------------------------------- .. py:function:: sign(key, data, digest) @@ -208,27 +219,22 @@ PKCS7 objects have the following methods: 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. - .. _openssl-pkcs12: PKCS12 objects @@ -309,17 +315,14 @@ NetscapeSPKI objects have the following methods: Return a base64-encoded string representation of the object. - .. py:method:: NetscapeSPKI.get_pubkey() Return the public key of object. - .. py:method:: NetscapeSPKI.set_pubkey(key) Set the public key of the object to *key*. - .. py:method:: NetscapeSPKI.sign(key, digest_name) Sign the NetscapeSPKI object using the given *key* and *digest_name*. @@ -327,12 +330,10 @@ NetscapeSPKI objects have the following methods: OpenSSL (by EVP_get_digestbyname, specifically). For example, :py:const:`"md5"` or :py:const:`"sha1"`. - .. py:method:: NetscapeSPKI.verify(key) Verify the NetscapeSPKI object using the given *key*. - .. _crl: CRL objects @@ -367,7 +368,6 @@ Revoked objects have the following methods: Return a list of all supported reasons. - .. py:method:: Revoked.get_reason() Return the revocation reason as a str. Can be -- cgit v1.2.1 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 From a790458cabcd5db1eea94526d49868ec08c8bb51 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Thu, 19 Jun 2014 12:33:04 +0200 Subject: Use :py:const:`None` consistently --- OpenSSL/crypto.py | 60 +++++++++++++++++++++++++++---------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index fcc89c0..6b92ca5 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -178,7 +178,7 @@ class PKey(object): of the appropriate type. :raises ValueError: If the number of bits isn't an integer of the appropriate size. - :return: :py:data:`None` + :return: :py:const:`None` """ if not isinstance(type, int): raise TypeError("type must be an integer") @@ -820,7 +820,7 @@ class X509Req(object): :param pkey: The public key to use. :type pkey: :py:class:`PKey` - :return: :py:data:`None` + :return: :py:const:`None` """ set_result = _lib.X509_REQ_set_pubkey(self._req, pkey._pkey) if not set_result: @@ -851,7 +851,7 @@ class X509Req(object): request. :param int version: The version number. - :return: :py:data:`None` + :return: :py:const:`None` """ set_result = _lib.X509_REQ_set_version(self._req, version) if not set_result: @@ -898,7 +898,7 @@ class X509Req(object): :param extensions: The X.509 extensions to add. :type extensions: iterable of :py:class:`X509Extension` - :return: :py:data:`None` + :return: :py:const:`None` """ stack = _lib.sk_X509_EXTENSION_new_null() if stack == _ffi.NULL: @@ -947,7 +947,7 @@ class X509Req(object): :param digest: The name of the message digest to use for the signature, e.g. :py:data:`b"sha1"`. :type digest: :py:class:`bytes` - :return: :py:data:`None` + :return: :py:const:`None` """ if pkey._only_public: raise ValueError("Key has only public part") @@ -1008,7 +1008,7 @@ class X509(object): :param version: The version number of the certificate. :type version: :py:class:`int` - :return: :py:data:`None` + :return: :py:const:`None` """ if not isinstance(version, int): raise TypeError("version must be an integer") @@ -1218,7 +1218,7 @@ class X509(object): :param amount: The number of seconds by which to adjust the timestamp. :type amount: :py:class:`int` - :return: :py:data:`None` + :return: :py:const:`None` """ if not isinstance(amount, int): raise TypeError("amount must be an integer") @@ -1232,7 +1232,7 @@ class X509(object): Adjust the timestamp on which the certificate starts being valid. :param amount: The number of seconds by which to adjust the timestamp. - :return: :py:data:`None` + :return: :py:const:`None` """ if not isinstance(amount, int): raise TypeError("amount must be an integer") @@ -1292,7 +1292,7 @@ class X509(object): :param when: A timestamp string. :type when: :py:class:`bytes` - :return: :py:data:`None` + :return: :py:const:`None` """ return self._set_boundary_time(_lib.X509_get_notBefore, when) @@ -1326,7 +1326,7 @@ class X509(object): :param when: A timestamp string. :type when: :py:class:`bytes` - :return: :py:data:`None` + :return: :py:const:`None` """ return self._set_boundary_time(_lib.X509_get_notAfter, when) @@ -1374,7 +1374,7 @@ class X509(object): :param issuer: The issuer. :type issuer: :py:class:`X509Name` - :return: :py:data:`None` + :return: :py:const:`None` """ return self._set_name(_lib.X509_set_issuer_name, issuer) @@ -1399,7 +1399,7 @@ class X509(object): :param subject: The subject. :type subject: :py:class:`X509Name` - :return: :py:data:`None` + :return: :py:const:`None` """ return self._set_name(_lib.X509_set_subject_name, subject) @@ -1422,7 +1422,7 @@ class X509(object): :param extensions: The extensions to add. :type extensions: An iterable of :py:class:`X509Extension` objects. - :return: :py:data:`None` + :return: :py:const:`None` """ for ext in extensions: if not isinstance(ext, X509Extension): @@ -1658,7 +1658,7 @@ class Revoked(object): :param hex_str: The new serial number. :type hex_str: :py:data:`str` - :return: :py:data:`None` + :return: :py:const:`None` """ bignum_serial = _ffi.gc(_lib.BN_new(), _lib.BN_free) bignum_ptr = _ffi.new("BIGNUM**") @@ -1703,11 +1703,11 @@ class Revoked(object): """ Set the reason of a Revoked object. - If :py:data:`reason` is :py:data:`None`, delete the reason instead. + If :py:data:`reason` is :py:const:`None`, delete the reason instead. :param reason: The reason string. :type reason: :py:class:`str` or :py:class:`NoneType` - :return: :py:data:`None` + :return: :py:const:`None` """ if reason is None: self._delete_reason() @@ -1778,7 +1778,7 @@ class Revoked(object): YYYYMMDDhhmmss+hhmm YYYYMMDDhhmmss-hhmm - :return: :py:data:`None` + :return: :py:const:`None` """ return _set_asn1_time(self._revoked.revocationDate, when) @@ -1831,7 +1831,7 @@ class CRL(object): :param revoked: The new revoked. :type revoked: :class:`X509` - :return: :py:data:`None` + :return: :py:const:`None` """ copy = _X509_REVOKED_dup(revoked._revoked) if copy == _ffi.NULL: @@ -1995,9 +1995,9 @@ class PKCS12(object): Set the certificate in the PKCS #12 structure. :param cert: The new certificate, or :py:const:`None` to unset it. - :type cert: :py:class:`X509` or :py:data:`None` + :type cert: :py:class:`X509` or :py:const:`None` - :return: :py:data:`None` + :return: :py:const:`None` """ if not isinstance(cert, X509): raise TypeError("cert must be an X509 instance") @@ -2021,7 +2021,7 @@ class PKCS12(object): :param pkey: The new private key, or :py:const:`None` to unset it. :type pkey: :py:class:`PKey` or :py:const:`None` - :return: :py:data:`None` + :return: :py:const:`None` """ if not isinstance(pkey, PKey): raise TypeError("pkey must be a PKey instance") @@ -2046,9 +2046,9 @@ class PKCS12(object): :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` + :type cacerts: An iterable of :py:class:`X509` or :py:const:`None` - :return: :py:data:`None` + :return: :py:const:`None` """ if cacerts is None: self._cacerts = None @@ -2065,9 +2065,9 @@ class PKCS12(object): 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` + :type name: :py:class:`bytes` or :py:const:`None` - :return: :py:data:`None` + :return: :py:const:`None` """ if name is None: self._friendlyname = None @@ -2080,8 +2080,8 @@ class PKCS12(object): """ Get the friendly name in the PKCS# 12 structure. - :returns: The friendly name, or :py:data:`None` if there is none. - :rtype: :py:class:`bytes` or :py:data:`None` + :returns: The friendly name, or :py:const:`None` if there is none. + :rtype: :py:class:`bytes` or :py:const:`None` """ return self._friendlyname @@ -2162,7 +2162,7 @@ class NetscapeSPKI(object): :param pkey: The key to sign with :param digest: The message digest to use - :return: :py:data:`None` + :return: :py:const:`None` """ if pkey._only_public: raise ValueError("Key has only public part") @@ -2228,7 +2228,7 @@ class NetscapeSPKI(object): Set the public key of the certificate :param pkey: The public key - :return: :py:data:`None` + :return: :py:const:`None` """ set_result = _lib.NETSCAPE_SPKI_set_pubkey(self._spki, pkey._pkey) if not set_result: @@ -2437,7 +2437,7 @@ def verify(cert, signature, data, digest): :param signature: signature returned by sign function :param data: data to be verified :param digest: message digest to use - :return: :py:data:`None` if the signature is correct, raise exception otherwise + :return: :py:const:`None` if the signature is correct, raise exception otherwise """ digest_obj = _lib.EVP_get_digestbyname(_byte_string(digest)) if digest_obj == _ffi.NULL: -- cgit v1.2.1 From 59152b5767eceefd508e5b3886431d0607de3ad0 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Thu, 19 Jun 2014 16:42:30 +0200 Subject: Use autodoc for NetscapeSPKI This uncovered an issue in the documentation. Issue filed: Refs #124. --- OpenSSL/crypto.py | 37 +++++++++++++++++++++++++++---------- doc/api/crypto.rst | 37 ++++--------------------------------- 2 files changed, 31 insertions(+), 43 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 6b92ca5..99b9691 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -2151,6 +2151,9 @@ PKCS12Type = PKCS12 class NetscapeSPKI(object): + """ + A Netscape SPKI object. + """ def __init__(self): spki = _lib.NETSCAPE_SPKI_new() self._spki = _ffi.gc(spki, _lib.NETSCAPE_SPKI_free) @@ -2158,10 +2161,14 @@ class NetscapeSPKI(object): def sign(self, pkey, digest): """ - Sign the certificate request using the supplied key and digest + Sign the certificate request with this key and digest type. + + :param pkey: The private key to sign with. + :type pkey: :py:class:`PKey` + + :param digest: The message digest to use. + :type digest: :py:class:`bytes` - :param pkey: The key to sign with - :param digest: The message digest to use :return: :py:const:`None` """ if pkey._only_public: @@ -2182,10 +2189,14 @@ class NetscapeSPKI(object): def verify(self, key): """ - Verifies a certificate request using the supplied public key + Verifies a signature on a certificate request. + + :param key: The public key that signature is supposedly from. + :type pkey: :py:class:`PKey` + + :return: :py:const:`True` if the signature is correct. + :rtype: :py:class:`bool` - :param key: a public key - :return: True if the signature is correct. :raises Error: If the signature is invalid, or there was a problem verifying the signature. """ @@ -2197,9 +2208,10 @@ class NetscapeSPKI(object): def b64_encode(self): """ - Generate a base64 encoded string from an SPKI + Generate a base64 encoded representation of this SPKI object. - :return: The base64 encoded string + :return: The base64 encoded string. + :rtype: :py:class:`bytes` """ encoded = _lib.NETSCAPE_SPKI_b64_encode(self._spki) result = _ffi.string(encoded) @@ -2209,9 +2221,10 @@ class NetscapeSPKI(object): def get_pubkey(self): """ - Get the public key of the certificate + Get the public key of this certificate. - :return: The public key + :return: The public key. + :rtype: :py:class:`PKey` """ pkey = PKey.__new__(PKey) pkey._pkey = _lib.NETSCAPE_SPKI_get_pubkey(self._spki) @@ -2234,9 +2247,13 @@ class NetscapeSPKI(object): if not set_result: # TODO: This is untested. _raise_current_error() + + + NetscapeSPKIType = NetscapeSPKI + class _PassphraseHelper(object): def __init__(self, type, passphrase, more_args=False, truncate=False): if type != FILETYPE_PEM and passphrase is not None: diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 949f9b2..b5636a7 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -6,15 +6,6 @@ .. py:module:: OpenSSL.crypto :synopsis: Generic cryptographic module -.. py:class:: NetscapeSPKI([enc]) - - A class representing Netscape SPKI objects. - - If the *enc* argument is present, it should be a base64-encoded string - representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode` - method. - - .. py:class:: CRL() A class representing Certifcate Revocation List objects. @@ -258,30 +249,10 @@ X509Extension objects NetscapeSPKI objects -------------------- -NetscapeSPKI objects have the following methods: - -.. py:method:: NetscapeSPKI.b64_encode() - - Return a base64-encoded string representation of the object. - -.. py:method:: NetscapeSPKI.get_pubkey() - - Return the public key of object. - -.. py:method:: NetscapeSPKI.set_pubkey(key) - - Set the public key of the object to *key*. - -.. py:method:: NetscapeSPKI.sign(key, digest_name) - - Sign the NetscapeSPKI object using the given *key* and *digest_name*. - *digest_name* must be a string describing a digest algorithm supported by - OpenSSL (by EVP_get_digestbyname, specifically). For example, - :py:const:`"md5"` or :py:const:`"sha1"`. - -.. py:method:: NetscapeSPKI.verify(key) - - Verify the NetscapeSPKI object using the given *key*. +.. autoclass:: NetscapeSPKI + :members: + :special-members: + :exclude-members: __weakref__ .. _crl: -- cgit v1.2.1 From d92f55c93beefa489a07b8b1db35be27210edc2a Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Thu, 19 Jun 2014 17:08:41 +0200 Subject: Use autodoc for Revoked --- OpenSSL/crypto.py | 62 ++++++++++++++++++++++++++++++++++++------------------ doc/api/crypto.rst | 47 ++--------------------------------------- 2 files changed, 43 insertions(+), 66 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 99b9691..90c57a7 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1632,6 +1632,9 @@ def _X509_REVOKED_dup(original): class Revoked(object): + """ + A certificate revocation. + """ # http://www.openssl.org/docs/apps/x509v3_config.html#CRL_distribution_points_ # which differs from crl_reasons of crypto/x509v3/v3_enum.c that matches # OCSP_crl_reason_str. We use the latter, just like the command line @@ -1654,10 +1657,14 @@ class Revoked(object): def set_serial(self, hex_str): """ - Set the serial number of a revoked Revoked structure + Set the serial number. + + The serial number is formatted as a hexadecimal number encoded in + ASCII. :param hex_str: The new serial number. - :type hex_str: :py:data:`str` + :type hex_str: :py:class:`bytes` + :return: :py:const:`None` """ bignum_serial = _ffi.gc(_lib.BN_new(), _lib.BN_free) @@ -1675,9 +1682,13 @@ class Revoked(object): def get_serial(self): """ - Return the serial number of a Revoked structure + Get the serial number. + + The serial number is formatted as a hexadecimal number encoded in + ASCII. - :return: The serial number as a string + :return: The serial number. + :rtype: :py:class:`bytes` """ bio = _new_mem_buf() @@ -1701,13 +1712,19 @@ class Revoked(object): def set_reason(self, reason): """ - Set the reason of a Revoked object. + Set the reason of this revocation. If :py:data:`reason` is :py:const:`None`, delete the reason instead. :param reason: The reason string. - :type reason: :py:class:`str` or :py:class:`NoneType` + :type reason: :py:class:`bytes` or :py:class:`NoneType` + :return: :py:const:`None` + + .. seealso:: + + :py:meth:`all_reasons`, which gives you a list of all supported + reasons which you might pass to this method. """ if reason is None: self._delete_reason() @@ -1739,9 +1756,15 @@ class Revoked(object): def get_reason(self): """ - Return the reason of a Revoked object. + Set the reason of this revocation. + + :return: The reason, or :py:const:`None` if there is none. + :rtype: :py:class:`bytes` or :py:class:`NoneType` + + .. seealso:: - :return: The reason as a string + :py:meth:`all_reasons`, which gives you a list of all supported + reasons this method might return. """ extensions = self._revoked.extensions for i in range(_lib.sk_X509_EXTENSION_num(extensions)): @@ -1763,21 +1786,21 @@ class Revoked(object): """ Return a list of all the supported reason strings. + This list is a copy; modifying it does not change the supported reason + strings. + :return: A list of reason strings. + :rtype: :py:class:`list` of :py:class:`bytes` """ return self._crl_reasons[:] def set_rev_date(self, when): """ - Set the revocation timestamp - - :param when: A string giving the timestamp, in the format: - - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm + Set the revocation timestamp. + :param when: The timestamp of the revocation, as ASN.1 GENERALIZEDTIME. + :type when: :py:class:`bytes` :return: :py:const:`None` """ return _set_asn1_time(self._revoked.revocationDate, when) @@ -1785,13 +1808,10 @@ class Revoked(object): def get_rev_date(self): """ - Retrieve the revocation date + Get the revocation timestamp. - :return: A string giving the timestamp, in the format: - - YYYYMMDDhhmmssZ - YYYYMMDDhhmmss+hhmm - YYYYMMDDhhmmss-hhmm + :return: The timestamp of the revocation, as ASN.1 GENERALIZEDTIME. + :rtype: :py:class:`bytes` """ return _get_asn1_time(self._revoked.revocationDate) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index b5636a7..8033805 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -10,11 +10,6 @@ A class representing Certifcate Revocation List objects. - -.. py:class:: Revoked() - - A class representing Revocation objects of CRL. - .. py:data:: TYPE_RSA TYPE_DSA @@ -276,51 +271,13 @@ CRL objects have the following methods: Return a tuple of Revoked objects, by value not reference. - .. _revoked: Revoked objects --------------- -Revoked objects have the following methods: - -.. py:method:: Revoked.all_reasons() - - Return a list of all supported reasons. - -.. py:method:: Revoked.get_reason() - - Return the revocation reason as a str. Can be - None, which differs from "Unspecified". - - -.. py:method:: Revoked.get_rev_date() - - Return the revocation date as a str. - The string is formatted as an ASN1 GENERALIZEDTIME. - - -.. py:method:: Revoked.get_serial() - - Return a str containing a hex number of the serial of the revoked certificate. - - -.. py:method:: Revoked.set_reason(reason) - - Set the revocation reason. *reason* must be None or a string, but the - values are limited. Spaces and case are ignored. See - :py:meth:`all_reasons`. - - -.. py:method:: Revoked.set_rev_date(date) - - Set the revocation date. - The string is formatted as an ASN1 GENERALIZEDTIME. - - -.. py:method:: Revoked.set_serial(serial) - - *serial* is a string containing a hex number of the serial of the revoked certificate. +.. autoclass:: Revoked + :members: Digest names ------------ -- cgit v1.2.1 From cb32e855390476f04a1abe8eff793ad5ec15de6d Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.cc> Date: Thu, 19 Jun 2014 17:36:28 +0200 Subject: Use autodoc for CRL Closes #125. --- OpenSSL/crypto.py | 34 +++++++++++++++++++++++----------- doc/api/crypto.rst | 24 ++++-------------------- 2 files changed, 27 insertions(+), 31 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 90c57a7..678c048 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1818,9 +1818,12 @@ class Revoked(object): class CRL(object): + """ + A certificate revocation list. + """ def __init__(self): """ - Create a new empty CRL object. + Create a new empty certificate revocation list. """ crl = _lib.X509_CRL_new() self._crl = _ffi.gc(crl, _lib.X509_CRL_free) @@ -1828,9 +1831,13 @@ class CRL(object): def get_revoked(self): """ - Return revoked portion of the CRL structure (by value not reference). + Return the revocations in this certificate revocation list. + + These revocations will be provided by value, not by reference. + That means it's okay to mutate them: it won't affect this CRL. - :return: A tuple of Revoked objects. + :return: The revocations in this CRL. + :rtype: :py:class:`tuple` of :py:class:`Revocation` """ results = [] revoked_stack = self._crl.crl.revoked @@ -1848,8 +1855,12 @@ class CRL(object): """ Add a revoked (by value not reference) to the CRL structure - :param revoked: The new revoked. - :type revoked: :class:`X509` + This revocation will be added by value, not by reference. That + means it's okay to mutate it after adding: it won't affect + this CRL. + + :param revoked: The new revocation. + :type revoked: :class:`Revoked` :return: :py:const:`None` """ @@ -1866,15 +1877,16 @@ class CRL(object): def export(self, cert, key, type=FILETYPE_PEM, days=100): """ - export a CRL as a string + Export a CRL as a string. - :param cert: Used to sign CRL. - :type cert: :class:`X509` + :param cert: The certificate used to sign the CRL. + :type cert: :py:class:`X509` - :param key: Used to sign CRL. - :type key: :class:`PKey` + :param key: The key used to sign the CRL. + :type key: :py:class:`PKey` - :param type: The export format, either :py:data:`FILETYPE_PEM`, :py:data:`FILETYPE_ASN1`, or :py:data:`FILETYPE_TEXT`. + :param type: The export format, either :py:data:`FILETYPE_PEM`, + :py:data:`FILETYPE_ASN1`, or :py:data:`FILETYPE_TEXT`. :param days: The number of days until the next update of this CRL. :type days: :py:data:`int` diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 8033805..237c7ae 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -6,10 +6,6 @@ .. py:module:: OpenSSL.crypto :synopsis: Generic cryptographic module -.. py:class:: CRL() - - A class representing Certifcate Revocation List objects. - .. py:data:: TYPE_RSA TYPE_DSA @@ -254,22 +250,10 @@ NetscapeSPKI objects CRL objects ----------- -CRL objects have the following methods: - -.. py:method:: CRL.add_revoked(revoked) - - Add a Revoked object to the CRL, by value not reference. - - -.. py:method:: CRL.export(cert, key[, type=FILETYPE_PEM][, days=100]) - - Use *cert* and *key* to sign the CRL and return the CRL as a string. - *days* is the number of days before the next CRL is due. - - -.. py:method:: CRL.get_revoked() - - Return a tuple of Revoked objects, by value not reference. +.. autoclass:: CRL + :members: + :special-members: + :exclude-members: __weakref__ .. _revoked: -- cgit v1.2.1 From d81b1c05c8e39409918183c1af97b0c5fdd48732 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:01:48 -0700 Subject: Remove X509Type reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 43860ea..3a55c1a 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -7,11 +7,6 @@ :synopsis: Generic cryptographic module -.. py:data:: X509Type - - See :py:class:`X509`. - - .. py:class:: X509() A class representing X.509 certificates. -- cgit v1.2.1 From 0c6629f489b6e138c2a4a9deb6a6de3144a71796 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:03:14 -0700 Subject: Remove X509NameType reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 3a55c1a..8f64efd 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -12,11 +12,6 @@ A class representing X.509 certificates. -.. py:data:: X509NameType - - See :py:class:`X509Name`. - - .. py:class:: X509Name(x509name) A class representing X.509 Distinguished Names. -- cgit v1.2.1 From 502fae87e852c13761a7b9577d36821098d33ac6 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:03:34 -0700 Subject: Remove X509ReqType reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 8f64efd..c68f3d8 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -20,11 +20,6 @@ instance of :py:class:`X509Name`. -.. py:data:: X509ReqType - - See :py:class:`X509Req`. - - .. py:class:: X509Req() A class representing X.509 certificate requests. -- cgit v1.2.1 From 59e3ab92adf21b12e94b846aa5742072b830c544 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:03:45 -0700 Subject: Remove X509StoreType reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index c68f3d8..c0626c2 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -25,11 +25,6 @@ A class representing X.509 certificate requests. -.. py:data:: X509StoreType - - See :py:class:`X509Store` - - .. py:data:: X509Store A class representing the X.509 store. -- cgit v1.2.1 From 01d54174ab88126f2b5162186262145ba4c39480 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:03:56 -0700 Subject: Remove PKeyType reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index c0626c2..ffeae11 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -35,11 +35,6 @@ A class representing the X.509 store context. -.. py:data:: PKeyType - - See :py:class:`PKey`. - - .. py:class:: PKey() A class representing DSA or RSA keys. -- cgit v1.2.1 From 555c83dd874e5ed95ae4fa2cdc01ecc717f3ed7a Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:21:29 -0700 Subject: Remove X509ExtensionType reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index ffeae11..73e70e3 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -49,11 +49,6 @@ A Python type object representing the PKCS12 object type. -.. py:data:: X509ExtensionType - - See :py:class:`X509Extension`. - - .. py:class:: X509Extension(typename, critical, value[, subject][, issuer]) A class representing an X.509 v3 certificate extensions. See -- cgit v1.2.1 From c6a30d9d4ab7d16e1a83fa34cbeaa14df91ed2af Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:21:57 -0700 Subject: File type constants appear somewhere else too --- doc/api/crypto.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 73e70e3..185db9d 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -81,12 +81,6 @@ A class representing Revocation objects of CRL. -.. py:data:: FILETYPE_PEM - FILETYPE_ASN1 - - File type constants. - - .. py:data:: TYPE_RSA TYPE_DSA -- cgit v1.2.1 From 0f82087eca7cb9e38c855f2108dfd7d10492705c Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:25:57 -0700 Subject: X509 appears later --- doc/api/crypto.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 185db9d..fc5619c 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -7,11 +7,6 @@ :synopsis: Generic cryptographic module -.. py:class:: X509() - - A class representing X.509 certificates. - - .. py:class:: X509Name(x509name) A class representing X.509 Distinguished Names. @@ -183,7 +178,9 @@ Certificate revocation lists .. py:function:: load_pkcs7_data(type, buffer) - Load pkcs7 data from the string *buffer* encoded with the type *type*. + 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`). .. py:function:: load_pkcs12(buffer[, passphrase]) -- cgit v1.2.1 From 0387f8f229b3aad9b625186db490999ef3c1e71a Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:26:18 -0700 Subject: X509Name appears later --- doc/api/crypto.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index fc5619c..e4b7173 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -7,14 +7,6 @@ :synopsis: Generic cryptographic module -.. py:class:: X509Name(x509name) - - A class representing X.509 Distinguished Names. - - This constructor creates a copy of *x509name* which should be an - instance of :py:class:`X509Name`. - - .. py:class:: X509Req() A class representing X.509 certificate requests. -- cgit v1.2.1 From e5625641bb9f34041f9d8ba79d441cd7a5c4d806 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:26:35 -0700 Subject: X509Req appears later --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index e4b7173..cfa84f3 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -7,11 +7,6 @@ :synopsis: Generic cryptographic module -.. py:class:: X509Req() - - A class representing X.509 certificate requests. - - .. py:data:: X509Store A class representing the X.509 store. -- cgit v1.2.1 From 9313a4efd80a00c4bbf554076a739b34a10096c1 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:27:28 -0700 Subject: Reflow --- doc/api/crypto.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index cfa84f3..0118cbf 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -252,8 +252,8 @@ The certificate for which the verification error was detected is given by the ``certificate`` attribute of the exception instance as a :class:`X509` instance. -Details about the verification error are given in the exception's ``args`` attribute. - +Details about the verification error are given in the exception's +``args`` attribute. X509StoreContext objects ------------------------ -- cgit v1.2.1 From 1bc15757ab1e835960354a82354479278dc4cddd Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:47:24 -0700 Subject: X509 is down there --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 0118cbf..02b45ac 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -7,11 +7,6 @@ :synopsis: Generic cryptographic module -.. py:data:: X509Store - - A class representing the X.509 store. - - .. py:data:: X509StoreContext A class representing the X.509 store context. -- cgit v1.2.1 From 98a328b1c4042d0f1021bb411bfe0849d72eb638 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:47:34 -0700 Subject: PKey is down there --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 02b45ac..d6b587a 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,11 +11,6 @@ A class representing the X.509 store context. - -.. py:class:: PKey() - - A class representing DSA or RSA keys. - .. py:data:: PKCS7Type A Python type object representing the PKCS7 object type. -- cgit v1.2.1 From 2ec1fba2062cf4caa55d4bde3467bcfff7cb78a3 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:48:12 -0700 Subject: Fix typo --- doc/api/crypto.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index d6b587a..8cf4573 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -384,6 +384,6 @@ Type name Backwards-compatible name :py:class:`CRL` :py:class:`CRLType` ========================= ============================= -Soem objects, such as py:class`Revoked`, don't have ``Type`` +Some objects, such as py:class`Revoked`, don't have ``Type`` equivalents, because they were added after the restriction had been lifted. -- cgit v1.2.1 From 8d917bfff53039eb6dbd4e56d19a38163c645444 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:58:31 -0700 Subject: Remove PKCS7Type --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 8cf4573..588e26a 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,11 +11,6 @@ A class representing the X.509 store context. -.. py:data:: PKCS7Type - - A Python type object representing the PKCS7 object type. - - .. py:data:: PKCS12Type A Python type object representing the PKCS12 object type. -- cgit v1.2.1 From 9d4c0746e7df2ef541113ed1dc6e02e6ad60a21f Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:58:39 -0700 Subject: Move key type constants --- doc/api/crypto.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 588e26a..23d8521 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -47,12 +47,6 @@ A class representing Revocation objects of CRL. - -.. py:data:: TYPE_RSA - TYPE_DSA - - Key type constants. - .. py:exception:: Error Generic exception used in the :py:mod:`.crypto` module. @@ -265,6 +259,11 @@ PKey objects .. _openssl-pkcs7: +.. py:data:: TYPE_RSA + TYPE_DSA + + Key type constants. + PKCS7 objects ------------- -- cgit v1.2.1 From 1302781390c0097d91523cd3bd5363736f8bf72d Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 11:59:28 -0700 Subject: Remove PKCS12Type reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 23d8521..64a4762 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,11 +11,6 @@ A class representing the X.509 store context. -.. py:data:: PKCS12Type - - A Python type object representing the PKCS12 object type. - - .. py:class:: X509Extension(typename, critical, value[, subject][, issuer]) A class representing an X.509 v3 certificate extensions. See -- cgit v1.2.1 From b9421153dae7d056067968f3cdfaf7c50d592155 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:12:39 -0700 Subject: Remove superfluous X509Extension reference --- doc/api/crypto.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 64a4762..c1970a9 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,14 +11,6 @@ A class representing the X.509 store context. -.. py:class:: X509Extension(typename, critical, value[, subject][, issuer]) - - A class representing an X.509 v3 certificate extensions. See - http://openssl.org/docs/apps/x509v3_config.html#STANDARD_EXTENSIONS for - *typename* strings and their options. Optional parameters *subject* and - *issuer* must be X509 objects. - - .. py:data:: NetscapeSPKIType See :py:class:`NetscapeSPKI`. -- cgit v1.2.1 From 82704b976baa48ba0508c15ec4a085d2a45237bf Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:13:04 -0700 Subject: Remove NetscapeSPKIType reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index c1970a9..b2ee9ec 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,11 +11,6 @@ A class representing the X.509 store context. -.. py:data:: NetscapeSPKIType - - See :py:class:`NetscapeSPKI`. - - .. py:class:: NetscapeSPKI([enc]) A class representing Netscape SPKI objects. -- cgit v1.2.1 From f5831fc786a8682ea146a4da454f11f50f8274e5 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:13:20 -0700 Subject: Remove NetscapeSPKI duplicate docs --- doc/api/crypto.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index b2ee9ec..9226af5 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,15 +11,6 @@ A class representing the X.509 store context. -.. py:class:: NetscapeSPKI([enc]) - - A class representing Netscape SPKI objects. - - If the *enc* argument is present, it should be a base64-encoded string - representing a NetscapeSPKI object, as returned by the :py:meth:`b64_encode` - method. - - .. py:class:: CRL() A class representing Certifcate Revocation List objects. -- cgit v1.2.1 From fe7d8d516eaa780f2f53412b8cce9319a49f38f8 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:15:34 -0700 Subject: Remove CRL reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 9226af5..503e2cf 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,11 +11,6 @@ A class representing the X.509 store context. -.. py:class:: CRL() - - A class representing Certifcate Revocation List objects. - - .. py:class:: Revoked() A class representing Revocation objects of CRL. -- cgit v1.2.1 From a0a9bc32350a5b5f595fc05a6ca822a090225961 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:16:17 -0700 Subject: Remove Revoked reference --- doc/api/crypto.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 503e2cf..8a31da5 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,10 +11,6 @@ A class representing the X.509 store context. -.. py:class:: Revoked() - - A class representing Revocation objects of CRL. - .. py:exception:: Error Generic exception used in the :py:mod:`.crypto` module. -- cgit v1.2.1 From 287abd1526ec931ec249ddbfb459af6dd6e419e7 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:17:35 -0700 Subject: Merge CRL, Revoked into certificate revocation section --- doc/api/crypto.rst | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 8a31da5..251019f 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -121,6 +121,23 @@ Certificate revocation lists See also the man page for the C function :py:func:`PKCS12_parse`. + +.. _crl: + + +.. autoclass:: CRL + :members: + :special-members: + :exclude-members: __weakref__ + + +.. _revoked: + + +.. autoclass:: Revoked + :members: + + Signing and verifying signatures -------------------------------- @@ -281,24 +298,6 @@ NetscapeSPKI objects :special-members: :exclude-members: __weakref__ -.. _crl: - -CRL objects ------------ - -.. autoclass:: CRL - :members: - :special-members: - :exclude-members: __weakref__ - -.. _revoked: - -Revoked objects ---------------- - -.. autoclass:: Revoked - :members: - Digest names ------------ -- cgit v1.2.1 From 889b9d2359900bb0f16a513ef2b5d119856c10b1 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:18:28 -0700 Subject: Revert "Merge CRL, Revoked into certificate revocation section" This reverts commit 287abd1526ec931ec249ddbfb459af6dd6e419e7. --- doc/api/crypto.rst | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 251019f..8a31da5 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -121,23 +121,6 @@ Certificate revocation lists See also the man page for the C function :py:func:`PKCS12_parse`. - -.. _crl: - - -.. autoclass:: CRL - :members: - :special-members: - :exclude-members: __weakref__ - - -.. _revoked: - - -.. autoclass:: Revoked - :members: - - Signing and verifying signatures -------------------------------- @@ -298,6 +281,24 @@ NetscapeSPKI objects :special-members: :exclude-members: __weakref__ +.. _crl: + +CRL objects +----------- + +.. autoclass:: CRL + :members: + :special-members: + :exclude-members: __weakref__ + +.. _revoked: + +Revoked objects +--------------- + +.. autoclass:: Revoked + :members: + Digest names ------------ -- cgit v1.2.1 From 3de6b2b80152676faa6f5be806a8aa5269ecf722 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:20:42 -0700 Subject: Move Error around --- doc/api/crypto.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index 8a31da5..ad4e025 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -11,10 +11,6 @@ A class representing the X.509 store context. -.. py:exception:: Error - - Generic exception used in the :py:mod:`.crypto` module. - Elliptic curves --------------- @@ -299,6 +295,13 @@ Revoked objects .. autoclass:: Revoked :members: +Exceptions +---------- + +.. py:exception:: Error + + Generic exception used in the :py:mod:`.crypto` module. + Digest names ------------ -- cgit v1.2.1 From b5b70a52d680ae1e8b033dd8934c827de564721b Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Mon, 20 Apr 2015 12:21:14 -0700 Subject: Remove X509StoreContext reference --- doc/api/crypto.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index ad4e025..cfcc058 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -6,11 +6,6 @@ .. py:module:: OpenSSL.crypto :synopsis: Generic cryptographic module - -.. py:data:: X509StoreContext - - A class representing the X.509 store context. - Elliptic curves --------------- -- cgit v1.2.1 From 5faa2811230a0738e31766dcd9fdff732d85200e Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:44:10 -0700 Subject: Fix markup Thanks, @hynek! --- doc/api/crypto.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst index cfcc058..101f3bd 100644 --- a/doc/api/crypto.rst +++ b/doc/api/crypto.rst @@ -340,6 +340,6 @@ Type name Backwards-compatible name :py:class:`CRL` :py:class:`CRLType` ========================= ============================= -Some objects, such as py:class`Revoked`, don't have ``Type`` +Some objects, such as :py:class`Revoked`, don't have ``Type`` equivalents, because they were added after the restriction had been lifted. -- cgit v1.2.1 From 0dd8740cf52c7558281bea543b1cc3a736a0f49d Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:47:18 -0700 Subject: Fix markup Thanks, @hynek! --- OpenSSL/crypto.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 9061a4a..6e993d6 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1105,7 +1105,7 @@ class X509(object): :raises ValueError: If the signature algorithm is undefined. - ..versionadded:: 0.13 + .. versionadded:: 0.13 """ alg = self._x509.cert_info.signature.algorithm nid = _lib.OBJ_obj2nid(alg) -- cgit v1.2.1 From 6f2e426201f223b0178d966c340a5127bf36ab3c Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:48:32 -0700 Subject: Consistency between all three sign methods --- OpenSSL/crypto.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 6e993d6..60c34ce 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -947,7 +947,7 @@ class X509Req(object): def sign(self, pkey, digest): """ - Sign the certificate signing request using the supplied key and digest. + Sign the certificate signing request with this key and digest type. :param pkey: The key pair to sign with. :type pkey: :py:class:`PKey` @@ -1068,7 +1068,7 @@ class X509(object): def sign(self, pkey, digest): """ - Sign the certificate using the supplied key and digest type. + Sign the certificate with this key and digest type. :param pkey: The key to sign with. :type pkey: :py:class:`PKey` -- cgit v1.2.1 From a367fe8f2ac42186d9a05f9aa12fed7434bfdb93 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:49:12 -0700 Subject: Fix markup Thanks, @hynek! --- OpenSSL/crypto.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 60c34ce..75e3b42 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1076,7 +1076,7 @@ class X509(object): :param digest: The name of the message digest to use. :type digest: :py:class:`bytes` - :return: :py:data`None` + :return: :py:data:`None` """ if not isinstance(pkey, PKey): raise TypeError("pkey must be a PKey instance") -- cgit v1.2.1 From 33fcf12342bf67f617951e98f153bfb99fe8a5b7 Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:50:08 -0700 Subject: Fix markup Thanks, @hynek! --- OpenSSL/crypto.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 75e3b42..3b8abeb 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1056,7 +1056,7 @@ class X509(object): :param pkey: The public key. :type pkey: :py:class:`PKey` - :return: :py:data`None` + :return: :py:data:`None` """ if not isinstance(pkey, PKey): raise TypeError("pkey must be a PKey instance") -- cgit v1.2.1 From 5ee60b33b5323e2eab80d7059283ce49928a543d Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:51:16 -0700 Subject: Fix markup Thanks, @hynek! --- OpenSSL/crypto.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index 3b8abeb..d642c6c 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -1487,7 +1487,7 @@ class X509Store(object): :param X509 cert: The certificate to add to this store. :raises TypeError: If the certificate is not an :py:class:`X509`. :raises Error: If OpenSSL was unhappy with your certificate. - :return: py:data:`None` if the certificate was added successfully. + :return: :py:data:`None` if the certificate was added successfully. """ if not isinstance(cert, X509): raise TypeError() -- cgit v1.2.1 From 90c0914f2ae03afc16d3789223fe96f9ca79f17e Mon Sep 17 00:00:00 2001 From: Laurens Van Houtven <_@lvh.io> Date: Thu, 23 Apr 2015 10:52:49 -0700 Subject: How do you even grammar --- OpenSSL/crypto.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/OpenSSL/crypto.py b/OpenSSL/crypto.py index d642c6c..cab145d 100644 --- a/OpenSSL/crypto.py +++ b/OpenSSL/crypto.py @@ -173,7 +173,7 @@ class PKey(object): def generate_key(self, type, bits): """ - Generate a key pair of the given type, with the given number of a bits. + Generate a key pair of the given type, with the given number of bits. This generates a key "into" the this object. -- cgit v1.2.1