From 9bbfcea022820e9783e22f5a8f1fe959c9b245eb Mon Sep 17 00:00:00 2001 From: Andre Caron Date: Mon, 18 May 2015 20:55:29 -0400 Subject: Adds certificate builder. --- docs/x509/reference.rst | 83 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 9179468f..65e3880d 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -388,6 +388,89 @@ X.509 CRL (Certificate Revocation List) Object The extensions encoded in the CRL. +X.509 Certificate Builder +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: CertificateBuilder + + .. method:: __init__() + + Creates an empty certificate (version 1). + + .. method:: set_version(version) + + Sets the X.509 version that will be used in the certificate. + + :param version: The :class:`~cryptography.x509.Version` that will be + used by the certificate. + + .. method:: set_issuer_name(name) + + Sets the issuer's distinguished name. + + :param public_key: The :class:`~cryptography.x509.Name` that describes + the issuer (CA). + + .. method:: set_subject_name(name) + + Sets the subject's distinguished name. + + :param public_key: The :class:`~cryptography.x509.Name` that describes + the subject (requester). + + .. method:: set_public_key(public_key) + + Sets the subject's public key. + + :param public_key: The subject's public key. + + .. method:: set_serial_number(serial_number) + + Sets the certificate's serial number (an integer). The CA's policy + determines how it attributes serial numbers to certificates. The only + requirement is that this number uniquely identify the certificate given + the issuer. + + :param serial_number: Integer number that will be used by the CA to + identify this certificate (most notably during certificate + revocation checking). + + .. method:: set_not_valid_before(time) + + Sets the certificate's activation time. This is the time from which + clients can start trusting the certificate. It may be different from + the time at which the certificate was created. + + :param time: The `datetime.datetime` object (in UTC) that marks the + activation time for the certificate. The certificate may not be + trusted clients if it is used before this time. + + .. method:: set_not_valid_after(time) + + Sets the certificate's expiration time. This is the time from which + clients should no longer trust the certificate. The CA's policy will + determine how long the certificate should remain in use. + + :param time: The `datetime.datetime` object (in UTC) that marks the + expiration time for the certificate. The certificate may not be + trusted clients if it is used after this time. + + .. method:: add_extension(extension) + + Adds an X.509 extension to the certificate. + + :param extension: The :class:`~cryptography.x509.Extension` to add to + the certificate. + + .. method:: sign(backend, private_key, algorithm) + + Sign the certificate using the CA's private key. + + :param algorithm: The + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that + will be used to generate the signature. + + X.509 CSR (Certificate Signing Request) Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 0092a0bb57590ce0946fdbd37513787bfa6d80b4 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sat, 18 Jul 2015 21:46:41 -0500 Subject: Remove unnecessary helper functions - Update documented methods - Do not mute the CertificateBuilder object if no version is set --- docs/x509/reference.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 65e3880d..b6c2f8a8 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -393,10 +393,6 @@ X.509 Certificate Builder .. class:: CertificateBuilder - .. method:: __init__() - - Creates an empty certificate (version 1). - .. method:: set_version(version) Sets the X.509 version that will be used in the certificate. @@ -404,27 +400,27 @@ X.509 Certificate Builder :param version: The :class:`~cryptography.x509.Version` that will be used by the certificate. - .. method:: set_issuer_name(name) + .. method:: issuer_name(name) Sets the issuer's distinguished name. :param public_key: The :class:`~cryptography.x509.Name` that describes the issuer (CA). - .. method:: set_subject_name(name) + .. method:: subject_name(name) Sets the subject's distinguished name. :param public_key: The :class:`~cryptography.x509.Name` that describes the subject (requester). - .. method:: set_public_key(public_key) + .. method:: public_key(public_key) Sets the subject's public key. :param public_key: The subject's public key. - .. method:: set_serial_number(serial_number) + .. method:: serial_number(serial_number) Sets the certificate's serial number (an integer). The CA's policy determines how it attributes serial numbers to certificates. The only @@ -435,7 +431,7 @@ X.509 Certificate Builder identify this certificate (most notably during certificate revocation checking). - .. method:: set_not_valid_before(time) + .. method:: not_valid_before(time) Sets the certificate's activation time. This is the time from which clients can start trusting the certificate. It may be different from @@ -445,7 +441,7 @@ X.509 Certificate Builder activation time for the certificate. The certificate may not be trusted clients if it is used before this time. - .. method:: set_not_valid_after(time) + .. method:: not_valid_after(time) Sets the certificate's expiration time. This is the time from which clients should no longer trust the certificate. The CA's policy will -- cgit v1.2.3 From 7644383e13f2dcc1e70e19a157b28608cc072830 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Tue, 21 Jul 2015 09:18:05 -0500 Subject: Fix documentation referring to CertificateBuilder.set_version --- docs/x509/reference.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index b6c2f8a8..e4ea252d 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -393,7 +393,7 @@ X.509 Certificate Builder .. class:: CertificateBuilder - .. method:: set_version(version) + .. method:: version(version) Sets the X.509 version that will be used in the certificate. -- cgit v1.2.3 From 893246fd6b6dcefa270777e7cb8261a3131a2745 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Fri, 24 Jul 2015 14:52:18 -0500 Subject: Remove CertificateBuilder.version Default CertificateBuilder to Version.v3 --- docs/x509/reference.rst | 7 ------- 1 file changed, 7 deletions(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index e4ea252d..5a809847 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -393,13 +393,6 @@ X.509 Certificate Builder .. class:: CertificateBuilder - .. method:: version(version) - - Sets the X.509 version that will be used in the certificate. - - :param version: The :class:`~cryptography.x509.Version` that will be - used by the certificate. - .. method:: issuer_name(name) Sets the issuer's distinguished name. -- cgit v1.2.3 From c5e1c254ba4bc9bb94e8ddcc66f4dc8eb62ce218 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Fri, 31 Jul 2015 23:33:35 -0500 Subject: Document other two parameters from sign method - Remove incorrect CertificateBuilder doc-string - Check that serial numbers are non-negative and < 160 bits - Check that dates passed aren't earlier than the unix epoch - Remove version from CertificateBuilder.__init__ and version method --- docs/x509/reference.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 5a809847..b7fef940 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -455,6 +455,17 @@ X.509 Certificate Builder Sign the certificate using the CA's private key. + :param backend: Backend that will be used to build the certificate. + Must support the + :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + interface. + + :param private_key: The + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`, + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey` or + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey` + that will be used to sign the certificate. + :param algorithm: The :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that will be used to generate the signature. -- cgit v1.2.3 From c9682adaf78cc0983ef639279d38e8bdccc97321 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sat, 1 Aug 2015 12:11:13 -0500 Subject: Fix up parameter names in the docs --- docs/x509/reference.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index b7fef940..9d5006ae 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -397,15 +397,15 @@ X.509 Certificate Builder Sets the issuer's distinguished name. - :param public_key: The :class:`~cryptography.x509.Name` that describes - the issuer (CA). + :param name: The :class:`~cryptography.x509.Name` that describes the + issuer (CA). .. method:: subject_name(name) Sets the subject's distinguished name. - :param public_key: The :class:`~cryptography.x509.Name` that describes - the subject (requester). + :param name: The :class:`~cryptography.x509.Name` that describes the + subject (requester). .. method:: public_key(public_key) -- cgit v1.2.3 From 85fc4d51635e96adb5781a571acad062b4aa0d88 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sat, 1 Aug 2015 20:29:31 -0500 Subject: Minor pep8 and doc fixes --- docs/x509/reference.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 9d5006ae..2029c08f 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -405,7 +405,7 @@ X.509 Certificate Builder Sets the subject's distinguished name. :param name: The :class:`~cryptography.x509.Name` that describes the - subject (requester). + subject. .. method:: public_key(public_key) -- cgit v1.2.3 From 8f57142489a0d0d832b0ba7fa56eec84e1f00cc4 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sun, 2 Aug 2015 11:31:08 -0500 Subject: Update the docs to be more accurate --- docs/x509/reference.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 2029c08f..ac07eade 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -411,7 +411,10 @@ X.509 Certificate Builder Sets the subject's public key. - :param public_key: The subject's public key. + :param public_key: The subject's public key. This can be one of + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`, + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey` .. method:: serial_number(serial_number) @@ -448,8 +451,9 @@ X.509 Certificate Builder Adds an X.509 extension to the certificate. - :param extension: The :class:`~cryptography.x509.Extension` to add to - the certificate. + :param extension: The extension to add to the certificate. Can be one + of :class:`~cryptography.x509.BasicConstraints` or + :class:`~cryptography.x509.SubjectAlternativeName`. .. method:: sign(backend, private_key, algorithm) -- cgit v1.2.3 From 17c8900f0b38052d16864de493bd1d409cc94180 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sun, 2 Aug 2015 21:13:59 -0500 Subject: Add note to serial_number parameter about entropy - Add reference to random-numbers.rst for easy intra-linking - Document critical parameter of CertificateBuilder.add_extension - Support InhibitAnyPolicy in the CertificateBuilder frontend but not in the backend - Slim down more tests - Fix up test that asserts the backend does not allow for unsupported extensions --- docs/x509/reference.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index ac07eade..26ac295b 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -425,7 +425,10 @@ X.509 Certificate Builder :param serial_number: Integer number that will be used by the CA to identify this certificate (most notably during certificate - revocation checking). + revocation checking). Users are encouraged to use a method of + generating 20 bytes of entropy, e.g., UUID4. For more information + on secure random number generation, see + :ref:`secure_random_number_generation`. .. method:: not_valid_before(time) @@ -433,7 +436,7 @@ X.509 Certificate Builder clients can start trusting the certificate. It may be different from the time at which the certificate was created. - :param time: The `datetime.datetime` object (in UTC) that marks the + :param time: The :class:`datetime.datetime` object (in UTC) that marks the activation time for the certificate. The certificate may not be trusted clients if it is used before this time. @@ -443,11 +446,11 @@ X.509 Certificate Builder clients should no longer trust the certificate. The CA's policy will determine how long the certificate should remain in use. - :param time: The `datetime.datetime` object (in UTC) that marks the + :param time: The :class:`datetime.datetime` object (in UTC) that marks the expiration time for the certificate. The certificate may not be trusted clients if it is used after this time. - .. method:: add_extension(extension) + .. method:: add_extension(extension, critical) Adds an X.509 extension to the certificate. @@ -455,6 +458,9 @@ X.509 Certificate Builder of :class:`~cryptography.x509.BasicConstraints` or :class:`~cryptography.x509.SubjectAlternativeName`. + :param critical: Set to ``True`` if the extension must be understood and + handled by whoever reads the certificate. + .. method:: sign(backend, private_key, algorithm) Sign the certificate using the CA's private key. -- cgit v1.2.3 From 1517a4bb9f349747bb8d13f7724864c3927e47f4 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sun, 2 Aug 2015 22:11:19 -0500 Subject: Add sign_x509_certificate to MultiBackend Add example of CertificateBuilder to the reference documentation --- docs/x509/reference.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 26ac295b..1dd466e8 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -393,6 +393,48 @@ X.509 Certificate Builder .. class:: CertificateBuilder + .. versionadded:: 1.0 + + .. doctest:: + + >>> from cryptography import x509 + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import rsa + >>> import datetime + >>> import uuid + >>> one_day = datetime.timedelta(1, 0, 0) + >>> private_key = rsa.generate_private_key( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = rsa.generate_private_key( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ).public_key() + >>> builder = x509.CertificateBuilder() + >>> builder = builder.subject_name(x509.Name([ + ... x509.NameAttribute(x509.OID_COMMON_NAME, u'cryptography.io'), + ... ])) + >>> builder = builder.issuer_name(x509.Name([ + ... x509.NameAttribute(x509.OID_COMMON_NAME, u'cryptography.io'), + ... ])) + >>> builder = builder.not_valid_before(datetime.datetime.today() - one_day) + >>> builder = builder.not_valid_after(datetime.datetime(2018, 8, 2)) + >>> builder = builder.serial_number(int(uuid.uuid4())) + >>> builder = builder.public_key(public_key) + >>> builder = builder.add_extension( + ... x509.BasicConstraints(ca=False, path_length=None), critical=True, + ... ) + >>> certificate = builder.sign( + ... private_key=private_key, algorithm=hashes.SHA256(), + ... backend=default_backend() + ... ) + >>> isinstance(certificate, x509.Certificate) + True + .. method:: issuer_name(name) Sets the issuer's distinguished name. -- cgit v1.2.3 From b7530a42518b30dba3950375cee09e4da419feae Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Sun, 2 Aug 2015 22:47:06 -0500 Subject: Use :doc: instead of :ref: for random-numbers --- docs/x509/reference.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/x509/reference.rst') diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 1dd466e8..5e58886f 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -469,8 +469,7 @@ X.509 Certificate Builder identify this certificate (most notably during certificate revocation checking). Users are encouraged to use a method of generating 20 bytes of entropy, e.g., UUID4. For more information - on secure random number generation, see - :ref:`secure_random_number_generation`. + on secure random number generation, see :doc:`/random-numbers`. .. method:: not_valid_before(time) -- cgit v1.2.3