Added documentation on revocation lists.

3 files changed, 84 insertions, 5 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 26a23e7eb1..4cc3ab3cbc 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -34,6 +34,7 @@ acceptable.  The framework is illustrated on @ref{fig:x509}.
 * Verifying X.509 certificate paths::
 * Verifying a certificate in the context of TLS session::
 * Certificate requests::
+* Certificate revocation lists::
 * PKCS 12 structures::
 @end menu
 
@@ -55,6 +56,9 @@ The field that indicates the version of the certificate.
 @item serialNumber @tab
 This field holds a unique serial number per certificate.
 
+@item signature @tab
+The issuing authority's signature.
+
 @item issuer @tab
 Holds the issuer's distinguished name.
 
@@ -240,6 +244,77 @@ which should return a signed certificate.
 @anchor{ex:crq}
 @verbatiminclude examples/ex-crq.c
 
+@node Certificate revocation lists
+@subsection Certificate revocation lists
+@cindex certificate revocation lists
+@cindex CRL
+
+A certificate revocation list (CRL) is a structure issued by an authority
+periodically containing a list of revoked certificates serial numbers. 
+The CRL structure is signed with the issuing authorities' keys. A typical
+CRL contains the fields as shown in @ref{tab:crl}.
+Certificate revocation lists are used to complement the expiration date of a certificate,
+in order to account for other reasons of revocation, such as compromised keys, etc.
+
+@showfuncB{gnutls_x509_crl_init,gnutls_x509_crl_deinit}
+@showfuncB{gnutls_x509_crl_import,gnutls_x509_crl_export}
+
+A certificate request can be generated by
+associating it with a private key, setting the
+subject's information and finally self signing it.
+The last step ensures that the requester is in
+possession of the private key. Each CRL is valid for limited amount of
+time and is required to provide, except for the current issuing time, also 
+the issuing time of the next update.
+
+@float Table,tab:crl
+@multitable @columnfractions .2 .7
+
+@headitem Field @tab Description
+
+@item version @tab
+The field that indicates the version of the CRL structure.
+
+@item signature @tab
+A signature by the issuing authority.
+
+@item issuer @tab
+Holds the issuer's distinguished name.
+
+@item thisUpdate @tab
+The issuing time of the revocation list.
+
+@item nextUpdate @tab
+The issuing time of the revocation list that will update that one.
+
+@item revokedCertificates @tab
+List of revoked certificates serial numbers.
+
+@item extensions @tab
+Optional CRL structure extensions.
+
+@end multitable
+@caption{Certificate revocation list fields.}
+@end float
+
+
+@showfuncdesc{gnutls_x509_crl_set_version}
+@showfuncdesc{gnutls_x509_crl_set_crt_serial}
+
+@showfuncC{gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
+
+The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign} 
+functions sign the revocation list with a private key. The latter function
+can be used to sign with a key residing in a PKCS #11 token.
+
+@showfuncdesc{gnutls_x509_crl_sign2}
+@showfuncdesc{gnutls_x509_crl_privkey_sign}
+
+Few extensions on the CRL structure are supported, including the
+CRL number extension and the authority key identifier.
+
+@showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id}
+
 @node PKCS 12 structures
 @subsection @acronym{PKCS} #12 structures
 @cindex PKCS #12
@@ -546,7 +621,7 @@ gnutls_privkey_t abs_key;
 
   /* sign the certificate to be signed */
   gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, ca_key, 
-                               GNUTLS_DIG_SHA1, 0);
+                               GNUTLS_DIG_SHA256, 0);
 @}
 @end example
 
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index 4b9518e334..db333a0771 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -262,12 +262,12 @@ multitable:
                         $mode = ITEMIZE;
                         push(@stack, NORMAL);
                 }
-                if ($line =~ s/\@float Figure\,(.*)/\\begin{figure}[htp]\n\\centering/g) {
+                if ($line =~ s/\@float Figure\,(.*)/\\begin{figure}[htbp]\n\\centering/g) {
 			$label = $1;
                         push(@stack, NORMAL);
                         $mode = FLOAT;
                 }
-                if ($line =~ s/\@float Table\,(.*)/\\begin{table}[thp]\n\\centering/g) {
+                if ($line =~ s/\@float Table\,(.*)/\\begin{table}[htbp]\n\\centering/g) {
 			$label = $1;
                         push(@stack, NORMAL);
                         $mode = FLOAT_TABLE;
diff --git a/lib/x509/crl_write.c b/lib/x509/crl_write.c
index 8a380710d7..8fd9f18898 100644
--- a/lib/x509/crl_write.c
+++ b/lib/x509/crl_write.c
@@ -335,7 +335,9 @@ disable_optional_stuff (gnutls_x509_crl_t crl)
  * @id_size: Holds the size of the serial field.
  *
  * This function will set the CRL's authority key ID extension.  Only
- * the keyIdentifier field can be set with this function.
+ * the keyIdentifier field can be set with this function. This may
+ * be used by an authority that holds multiple private keys, to distinguish
+ * the used key.
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
@@ -399,7 +401,9 @@ gnutls_x509_crl_set_authority_key_id (gnutls_x509_crl_t crl,
  * @nr: The CRL number
  * @nr_size: Holds the size of the nr field.
  *
- * This function will set the CRL's number extension.
+ * This function will set the CRL's number extension. This
+ * is to be used as a unique and monotonic number assigned to
+ * the CRL by the authority.
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.