updated documentation on PKCS #11 trust module verification

1 files changed, 55 insertions, 7 deletions

diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 1a371543b3..ac0def0100 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -208,13 +208,11 @@ requires to retrieve the extension, and the second is the parsing part.
 
 To enumerate and retrieve the DER-encoded extension data available in a certificate the following
 two functions are available.
-@showfuncB{gnutls_x509_crt_get_extension_info,gnutls_x509_crt_get_extension_data2}
+@showfuncC{gnutls_x509_crt_get_extension_info,gnutls_x509_crt_get_extension_data2,gnutls_x509_crt_get_extension_by_oid2}
 
 After a supported DER-encoded extension is retrieved it can be parsed using the APIs in @code{x509-ext.h}.
 Complex extensions may require initializing an intermediate structure that holds the
-parsed extension data.
-
-Examples of simple parsing functions are shown below.
+parsed extension data. Examples of simple parsing functions are shown below.
 @showfuncD{gnutls_x509_ext_import_basic_constraints,gnutls_x509_ext_export_basic_constraints,gnutls_x509_ext_import_key_usage,gnutls_x509_ext_export_key_usage}
 
 More complex extensions, such as Name Constraints, require an intermediate structure, in that
@@ -322,6 +320,7 @@ provided.
 @showfuncdesc{gnutls_x509_trust_list_add_named_crt}
 @showfuncdesc{gnutls_x509_trust_list_add_crls}
 @showfuncdesc{gnutls_x509_trust_list_verify_crt}
+@showfuncdesc{gnutls_x509_trust_list_verify_crt2}
 @showfuncdesc{gnutls_x509_trust_list_verify_named_crt}
 
 @showfuncdesc{gnutls_x509_trust_list_add_trust_file}
@@ -365,7 +364,7 @@ the end certificate (e.g. @code{GNUTLS_KP_TLS_WWW_SERVER}); in these cases
 the more advanced @funcref{gnutls_certificate_verify_peers} should be used instead.
 
 There is also the possibility to pass some input to the verification
-functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt} the
+functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt2} the
 flags are passed directly, but for
 @funcref{gnutls_certificate_verify_peers3}, the flags are set using
 @funcref{gnutls_certificate_set_verify_flags}.  All the available
@@ -379,14 +378,63 @@ flags are part of the enumeration
 @cindex verifying certificate with pkcs11
 
 Some systems provide a system wide trusted certificate storage accessible using
-PKCS #11. That is, the trusted certificates are queried and accessed using the
-PKCS #11 API. One example is the p11-kit trust module@footnote{see @url{http://p11-glue.freedesktop.org/trust-module.html}.}.
+the PKCS #11 API. That is, the trusted certificates are queried and accessed using the
+PKCS #11 API, and trusted certificate properties, such as purpose, are marked using
+attached extensions. One example is the p11-kit trust module@footnote{see @url{http://p11-glue.freedesktop.org/trust-module.html}.}.
 
 These special PKCS #11 modules can be used for GnuTLS certificate verification if marked as trust 
 policy modules, i.e., with @code{trust-policy: yes} in the p11-kit module file.
 The way to use them is by specifying to the file verification function (e.g., @funcref{gnutls_certificate_set_x509_trust_file}),
 a pkcs11 URL, or simply @code{pkcs11:} to use all the marked with trust policy modules.
 
+The trust modules of p11-kit assign a purpose to trusted authorities using the extended
+key usage object identifiers. The common purposes are shown in @ref{tab:purposes}. Note
+that typically according to @xcite{RFC5280} the extended key usage object identifiers apply to end certificates. Their
+application to CA certificates is an extension used by the trust modules.
+
+@float Table,tab:purposes
+@multitable @columnfractions .2 .2 .6
+
+@headitem Purpose @tab OID @tab Description
+
+@item GNUTLS_KP_TLS_WWW_SERVER @tab
+1.3.6.1.5.5.7.3.1 @tab
+The certificate is to be used for TLS WWW authentication. When in a CA certificate, it
+indicates that the CA is allowed to sign certificates for TLS WWW authentication.
+
+@item GNUTLS_KP_TLS_WWW_CLIENT @tab
+1.3.6.1.5.5.7.3.2 @tab
+The certificate is to be used for TLS WWW client authentication. When in a CA certificate, it
+indicates that the CA is allowed to sign certificates for TLS WWW client authentication.
+
+@item GNUTLS_KP_CODE_SIGNING @tab
+1.3.6.1.5.5.7.3.3 @tab
+The certificate is to be used for code signing. When in a CA certificate, it
+indicates that the CA is allowed to sign certificates for code signing.
+
+@item GNUTLS_KP_EMAIL_PROTECTION @tab
+1.3.6.1.5.5.7.3.4 @tab
+The certificate is to be used for email protection. When in a CA certificate, it
+indicates that the CA is allowed to sign certificates for email users.
+
+@item GNUTLS_KP_OCSP_SIGNING @tab
+1.3.6.1.5.5.7.3.9 @tab
+The certificate is to be used for signing OCSP responses. When in a CA certificate, it
+indicates that the CA is allowed to sign certificates which sign OCSP reponses.
+
+@item GNUTLS_KP_ANY @tab
+2.5.29.37.0 @tab
+The certificate is to be used for any purpose. When in a CA certificate, it
+indicates that the CA is allowed to sign any kind of certificates.
+
+@end multitable
+@caption{Key purpose object identifiers.}
+@end float
+
+With such modules, it is recommended to use the verification functions @funcref{gnutls_x509_trust_list_verify_crt2},
+or @funcref{gnutls_certificate_verify_peers}, which allow to explicitly specify the key purpose. The
+other verification functions which do not allow setting a purpose, would operate as if
+@code{GNUTLS_KP_TLS_WWW_SERVER} was requested from the trusted authorities.
 
 @node OpenPGP certificates
 @subsection @acronym{OpenPGP} certificates