diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/test-vectors.rst | 2 | ||||
| -rw-r--r-- | docs/installation.rst | 2 | ||||
| -rw-r--r-- | docs/x509/reference.rst | 153 |
3 files changed, 156 insertions, 1 deletions
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index ea44a46c..d400e662 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -233,6 +233,8 @@ Custom X.509 Vectors * ``cp_user_notice_no_explicit_text.pem`` - An RSA 2048 bit self-signed certificate containing a certificate policies extension with a user notice with no explicit text. +* ``cp_invalid.pem`` - An RSA 2048 bit self-signed certificate containing a + certificate policies extension with invalid data. * ``ian_uri.pem`` - An RSA 2048 bit certificate containing an issuer alternative name extension with a ``URI`` general name. * ``ocsp_nocheck.pem`` - An RSA 2048 bit self-signed certificate containing diff --git a/docs/installation.rst b/docs/installation.rst index becab6b0..f7a88b98 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -142,7 +142,7 @@ To link cryptography against a custom version of OpenSSL you'll need to set .. code-block:: console $ brew install openssl - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" pip install cryptography or `MacPorts`_: diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 9179468f..61971fed 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -388,6 +388,140 @@ X.509 CRL (Certificate Revocation List) Object The extensions encoded in the CRL. +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. + + :param name: The :class:`~cryptography.x509.Name` that describes the + issuer (CA). + + .. method:: subject_name(name) + + Sets the subject's distinguished name. + + :param name: The :class:`~cryptography.x509.Name` that describes the + subject. + + .. method:: public_key(public_key) + + Sets 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) + + 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). 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 :doc:`/random-numbers`. + + .. 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 + the time at which the certificate was created. + + :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. + + .. 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 + determine how long the certificate should remain in use. + + :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, critical) + + Adds an X.509 extension 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`. + + :param critical: Set to ``True`` if the extension must be understood and + handled by whoever reads the certificate. + + .. method:: sign(private_key, algorithm, backend) + + Sign the certificate using the CA's private key. + + :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. + + :param backend: Backend that will be used to build the certificate. + Must support the + :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + interface. + + X.509 CSR (Certificate Signing Request) Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -431,6 +565,25 @@ X.509 CSR (Certificate Signing Request) Object >>> isinstance(csr.signature_hash_algorithm, hashes.SHA1) True + .. attribute:: extensions + + :type: :class:`Extensions` + + The extensions encoded in the certificate signing request. + + :raises cryptography.x509.DuplicateExtension: If more than one + extension of the same type is found within the certificate signing request. + + :raises cryptography.x509.UnsupportedExtension: If the certificate signing request + contains an extension that is not supported. + + :raises cryptography.x509.UnsupportedGeneralNameType: If an extension + contains a general name that is not supported. + + :raises UnicodeError: If an extension contains IDNA encoding that is + invalid or not compliant with IDNA 2008. + + .. method:: public_bytes(encoding) .. versionadded:: 1.0 |