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

4 files changed, 17 insertions, 15 deletions

diff --git a/docs/random-numbers.rst b/docs/random-numbers.rst
index 8b119a3e..81e5efbb 100644
--- a/docs/random-numbers.rst
+++ b/docs/random-numbers.rst
@@ -1,3 +1,5 @@
+.. _secure_random_number_generation:
+
 Random number generation
 ========================
 
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.
diff --git a/src/cryptography/x509.py b/src/cryptography/x509.py
index 5760aae7..9f6cda13 100644
--- a/src/cryptography/x509.py
+++ b/src/cryptography/x509.py
@@ -1720,6 +1720,8 @@ class CertificateBuilder(object):
             extension = Extension(
                 OID_SUBJECT_ALTERNATIVE_NAME, critical, extension
             )
+        elif isinstance(extension, InhibitAnyPolicy):
+            extension = Extension(OID_INHIBIT_ANY_POLICY, critical, extension)
         else:
             raise NotImplementedError('Unsupported X.509 extension.')
 
diff --git a/tests/hazmat/backends/test_openssl.py b/tests/hazmat/backends/test_openssl.py
index daa37874..5b611cd0 100644
--- a/tests/hazmat/backends/test_openssl.py
+++ b/tests/hazmat/backends/test_openssl.py
@@ -491,10 +491,6 @@ class TestOpenSSLSignX509Certificate(object):
         private_key = RSA_KEY_2048.private_key(backend)
         builder = x509.CertificateBuilder().subject_name(x509.Name([
             x509.NameAttribute(x509.OID_COUNTRY_NAME, u'US'),
-            x509.NameAttribute(x509.OID_STATE_OR_PROVINCE_NAME, u'Texas'),
-            x509.NameAttribute(x509.OID_LOCALITY_NAME, u'Austin'),
-            x509.NameAttribute(x509.OID_ORGANIZATION_NAME, u'PyCA'),
-            x509.NameAttribute(x509.OID_COMMON_NAME, u'cryptography.io'),
         ])).public_key(
             private_key.public_key()
         ).serial_number(
@@ -503,16 +499,12 @@ class TestOpenSSLSignX509Certificate(object):
             datetime.datetime(1999, 1, 1)
         ).not_valid_after(
             datetime.datetime(2020, 1, 1)
+        ).add_extension(
+            x509.InhibitAnyPolicy(0), False
         )
 
-        builder._extensions.append(x509.Extension(
-            oid=x509.OID_COUNTRY_NAME,
-            critical=False,
-            value=object()
-        ))
-
         with pytest.raises(NotImplementedError):
-            backend.sign_x509_certificate(builder, private_key, hashes.SHA1())
+            builder.sign(backend, private_key, hashes.SHA1())
 
 
 class TestOpenSSLSerialisationWithOpenSSL(object):