Add documentation for CRL API in FFI and Python binding

3 files changed, 77 insertions, 16 deletions

diff --git a/doc/api_ref/ffi.rst b/doc/api_ref/ffi.rst
index 4c9472dd2..4bf03a5b1 100644
--- a/doc/api_ref/ffi.rst
+++ b/doc/api_ref/ffi.rst
@@ -1152,7 +1152,51 @@ X.509 Certificates
     Set ``reference_time`` to be the time which the certificate chain is
     validated against. Use zero to use the current system clock.
 
+.. cpp:function:: int botan_x509_cert_verify_with_crl(int* validation_result, \
+                  botan_x509_cert_t cert, \
+                  const botan_x509_cert_t* intermediates, \
+                  size_t intermediates_len, \
+                  const botan_x509_cert_t* trusted, \
+                  size_t trusted_len, \
+                  const botan_x509_crl_t* crls, \
+                  size_t crls_len, \
+                  const char* trusted_path, \
+                  size_t required_strength, \
+                  const char* hostname, \
+                  uint64_t reference_time)
+
+   Certificate path validation supporting Certificate Revocation Lists.
+
+   Works the same as ``botan_x509_cert_cerify``.
+
+   ``crls`` is an array of ``botan_x509_crl_t`` objects, ``crls_len`` is its length.
+
 .. cpp:function:: const char* botan_x509_cert_validation_status(int code)
 
    Return a (statically allocated) string associated with the verification
    result.
+
+X.509 Certificate Revocation Lists
+----------------------------------------
+
+.. cpp:type:: opaque* botan_x509_crl_t
+
+   An opaque data type for an X.509 CRL.
+
+.. cpp:function:: int botan_x509_crl_load(botan_x509_crl_t* crl_obj, \
+                                        const uint8_t crl[], size_t crl_len)
+
+   Load a CRL from the DER or PEM representation.
+
+.. cpp:function:: int botan_x509_crl_load_file(botan_x509_crl_t* crl_obj, const char* filename)
+
+   Load a CRL from a file.
+
+.. cpp:function:: int botan_x509_crl_destroy(botan_x509_crl_t crl)
+
+   Destroy the CRL object.
+
+.. cpp:function:: int botan_x509_is_revoked(botan_x509_crl_t crl, botan_x509_cert_t cert)
+
+   Check whether a given ``crl`` contains a given ``cert``.
+   Return ``0`` when the certificate is revoked, ``-1`` otherwise.
\ No newline at end of file
diff --git a/doc/api_ref/python.rst b/doc/api_ref/python.rst
index 1fda54193..a57f29e6d 100644
--- a/doc/api_ref/python.rst
+++ b/doc/api_ref/python.rst
@@ -547,7 +547,7 @@ HOTP
 X509Cert
 -----------------------------------------
 
-.. py:class:: X509Cert(filename=None, buf=None)
+.. py:class:: X509Cert(filename=None, buf=None) 
 
    .. py:method:: time_starts()
 
@@ -626,7 +626,8 @@ X509Cert
                   trusted_path=None, \
                   required_strength=0, \
                   hostname=None, \
-                  reference_time=0)
+                  reference_time=0 \
+                  crls=None)
 
       Verify a certificate. Returns 0 if validation was successful, returns a positive error code 
       if the validation was unsuccesful.
@@ -648,16 +649,25 @@ X509Cert
       Set ``reference_time`` to be the time which the certificate chain is
       validated against. Use zero (default) to use the current system clock.
 
+      ``crls`` is a list of CRLs issued by either trusted or untrusted authorities.
+
    .. py:classmethod:: validation_status(error_code)
 
       Return an informative string associated with the verification return code.
 
-     
+   .. py:method:: is_revoked(self, crl)
 
+      Check if the certificate (``self``) is revoked on the given ``crl``.
 
+X509CRL
+-----------------------------------------
 
+.. py:class:: X509CRL(filename=None, buf=None)
 
+   Class representing an X.509 Certificate Revocation List.
 
+   A CRL in PEM or DER format can be loaded from a file, with the ``filename`` argument,
+   or from a bytestring, with the ``buf`` argument.
 
 
 
diff --git a/src/lib/ffi/ffi.h b/src/lib/ffi/ffi.h
index 17d5a282a..a7cd11d25 100644
--- a/src/lib/ffi/ffi.h
+++ b/src/lib/ffi/ffi.h
@@ -1590,19 +1590,6 @@ BOTAN_PUBLIC_API(2,8) int botan_x509_cert_verify(
 */
 BOTAN_PUBLIC_API(2,8) const char* botan_x509_cert_validation_status(int code);
 
-/**
- * Key wrapping as per RFC 3394
- */
-BOTAN_PUBLIC_API(2,2)
-int botan_key_wrap3394(const uint8_t key[], size_t key_len,
-                       const uint8_t kek[], size_t kek_len,
-                       uint8_t wrapped_key[], size_t *wrapped_key_len);
-
-BOTAN_PUBLIC_API(2,2)
-int botan_key_unwrap3394(const uint8_t wrapped_key[], size_t wrapped_key_len,
-                         const uint8_t kek[], size_t kek_len,
-                         uint8_t key[], size_t *key_len);
-
 /*
 * X.509 CRL
 **************************/
@@ -1614,8 +1601,16 @@ BOTAN_PUBLIC_API(2,13) int botan_x509_crl_load(botan_x509_crl_t* crl_obj, const
 
 BOTAN_PUBLIC_API(2,13) int botan_x509_crl_destroy(botan_x509_crl_t crl);
 
+/**
+ * Given a CRL and a certificate, 
+ * check if the certificate is revoked on that particular CRL
+ */
 BOTAN_PUBLIC_API(2,13) int botan_x509_is_revoked(botan_x509_crl_t crl, botan_x509_cert_t cert);
 
+/**
+ * Different flavor of `botan_x509_cert_verify`, supports revocation lists.
+ * CRLs are passed as an array, same as intermediates and trusted CAs 
+ */
 BOTAN_PUBLIC_API(2,13) int botan_x509_cert_verify_with_crl(
    int* validation_result,
    botan_x509_cert_t cert,
@@ -1630,6 +1625,18 @@ BOTAN_PUBLIC_API(2,13) int botan_x509_cert_verify_with_crl(
    const char* hostname,
    uint64_t reference_time);
 
+/**
+ * Key wrapping as per RFC 3394
+ */
+BOTAN_PUBLIC_API(2,2)
+int botan_key_wrap3394(const uint8_t key[], size_t key_len,
+                       const uint8_t kek[], size_t kek_len,
+                       uint8_t wrapped_key[], size_t *wrapped_key_len);
+
+BOTAN_PUBLIC_API(2,2)
+int botan_key_unwrap3394(const uint8_t wrapped_key[], size_t wrapped_key_len,
+                         const uint8_t kek[], size_t kek_len,
+                         uint8_t key[], size_t *key_len);
 
 /**
 * HOTP