Added documentation on PKCS #7 signing

3 files changed, 48 insertions, 8 deletions

diff --git a/doc/cha-crypto.texi b/doc/cha-crypto.texi
index ebe4331915..3e640c2dd2 100644
--- a/doc/cha-crypto.texi
+++ b/doc/cha-crypto.texi
@@ -44,6 +44,35 @@ accessed using the abstract key API in @ref{Abstract key types}. This
 is a high level API with the advantage of transparently handling keys
 in memory and keys present in smart cards.
 
+@subsection PKCS #7 signing
+@cindex PKCS #7
+@cindex file signing
+
+The PKCS #7 format is common format used for digital signatures. It allows to sign
+by embedding the data into the signature, or creating detached signatures of the data,
+including a timestamp, additional certificates etc. In certain cases this format is also
+used to transport lists of certificates and CRLs.
+
+The basic functions to initialize, deinitialize, import, export or print information
+about a PKCS #7 structure are shown below.
+@showfuncE{gnutls_pkcs7_init,gnutls_pkcs7_deinit,gnutls_pkcs7_export2,gnutls_pkcs7_import,gnutls_pkcs7_print}
+
+The following functions allow the verification of a structure using either a trust list, or
+individual certificates. The @funcref{gnutls_pkcs7_sign} function is the data signing function.
+
+@showfuncB{gnutls_pkcs7_verify_direct,gnutls_pkcs7_verify}
+@showfuncdesc{gnutls_pkcs7_sign}
+
+@showenumdesc{gnutls_pkcs7_sign_flags,Flags applicable to gnutls_pkcs7_sign()}
+
+Other helper functions which allow to access the signatures, or certificates attached
+in the structure are listed below.
+
+@showfuncF{gnutls_pkcs7_get_signature_count,gnutls_pkcs7_get_signature_info,gnutls_pkcs7_get_crt_count,gnutls_pkcs7_get_crt_raw2,gnutls_pkcs7_get_crl_count,gnutls_pkcs7_get_crl_raw2}
+
+To append certificates, or CRLs in the structure the following functions are provided.
+@showfuncD{gnutls_pkcs7_set_crt_raw,gnutls_pkcs7_set_crt,gnutls_pkcs7_set_crl_raw,gnutls_pkcs7_set_crl}
+
 @node Hash and HMAC functions
 @section Hash and HMAC functions
 @cindex hash functions
diff --git a/lib/includes/gnutls/pkcs7.h b/lib/includes/gnutls/pkcs7.h
index fbc449f50c..fb88b48448 100644
--- a/lib/includes/gnutls/pkcs7.h
+++ b/lib/includes/gnutls/pkcs7.h
@@ -102,10 +102,22 @@ int gnutls_pkcs7_add_attr(gnutls_pkcs7_attrs_t *list, const char *oid, gnutls_da
 void gnutls_pkcs7_attrs_deinit(gnutls_pkcs7_attrs_t list);
 int gnutls_pkcs7_get_attr(gnutls_pkcs7_attrs_t list, unsigned idx, char **oid, gnutls_datum_t *data, unsigned flags);
 
-#define GNUTLS_PKCS7_EMBED_DATA 1
-#define GNUTLS_PKCS7_INCLUDE_TIME (1<<1)
-#define GNUTLS_PKCS7_INCLUDE_CERT (1<<2)
-#define GNUTLS_PKCS7_WRITE_SPKI (1<<3)
+/**
+ * gnutls_pkcs7_sign_flags:
+ * @GNUTLS_PKCS7_EMBED_DATA: The signed data will be embedded in the structure.
+ * @GNUTLS_PKCS7_INCLUDE_TIME: The signing time will be included in the structure.
+ * @GNUTLS_PKCS7_INCLUDE_CERT: The signer's certificate will be included in the cert list.
+ * @GNUTLS_PKCS7_WRITE_SPKI: Use the signer's key identifier instead of name.
+ *
+ * Enumeration of the different PKCS #7 signature flags.
+ */
+typedef enum gnutls_pkcs7_sign_flags {
+	GNUTLS_PKCS7_EMBED_DATA = 1,
+	GNUTLS_PKCS7_INCLUDE_TIME = (1<<1),
+	GNUTLS_PKCS7_INCLUDE_CERT = (1<<2),
+	GNUTLS_PKCS7_WRITE_SPKI = (1<<3)
+} gnutls_pkcs7_sign_flags;
+
 int gnutls_pkcs7_sign(gnutls_pkcs7_t pkcs7,
 		      gnutls_x509_crt_t signer,
 		      gnutls_privkey_t signer_key,
diff --git a/lib/x509/pkcs7.c b/lib/x509/pkcs7.c
index 5d3910f98c..89b5a61073 100644
--- a/lib/x509/pkcs7.c
+++ b/lib/x509/pkcs7.c
@@ -1901,10 +1901,9 @@ static int write_attributes(ASN1_TYPE c2, const char *root, const gnutls_datum_t
  * signers.
  * 
  * The available flags are:
- *  - %GNUTLS_PKCS7_EMBED_DATA: the data will be embedded in the structure
- *  - %GNUTLS_PKCS7_INCLUDE_TIME: the signing time will be included
- *  - %GNUTLS_PKCS7_INCLUDE_CERT: the signer's certificate will be included in the cert list
- *  - %GNUTLS_PKCS7_WRITE_SPKI: store the issuer's ID instead of name
+ *  %GNUTLS_PKCS7_EMBED_DATA, %GNUTLS_PKCS7_INCLUDE_TIME, %GNUTLS_PKCS7_INCLUDE_CERT,
+ *  and %GNUTLS_PKCS7_WRITE_SPKI. They are explained in the #gnutls_pkcs7_sign_flags
+ *  definition.
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.