Merge lorikeet-heimdal -r 787 into Samba4 tree.

Andrew Bartlett
(This used to be commit d88b530522d3cef67c24422bd5182fb875d87ee2)

1 files changed, 226 insertions, 11 deletions

diff --git a/source4/heimdal/lib/hx509/keyset.c b/source4/heimdal/lib/hx509/keyset.c
index 7da5705a80..2fcff7b03b 100644
--- a/source4/heimdal/lib/hx509/keyset.c
+++ b/source4/heimdal/lib/hx509/keyset.c
@@ -32,7 +32,31 @@
  */
 
 #include "hx_locl.h"
-RCSID("$Id: keyset.c 21140 2007-06-18 21:24:19Z lha $");
+RCSID("$Id: keyset.c 22466 2008-01-16 14:26:35Z lha $");
+
+/**
+ * @page page_keyset Certificate store operations
+ *
+ * Type of certificates store:
+ * - MEMORY
+ *   In memory based format. Doesnt support storing.
+ * - FILE 
+ *   FILE supports raw DER certicates and PEM certicates. When PEM is
+ *   used the file can contain may certificates and match private
+ *   keys. Support storing the certificates. DER format only supports
+ *   on certificate and no private key.
+ * - PEM-FILE
+ *   Same as FILE, defaulting to PEM encoded certificates.
+ * - PEM-FILE
+ *   Same as FILE, defaulting to DER encoded certificates.
+ * - PKCS11
+ * - PKCS12
+ * - DIR
+ * - KEYCHAIN
+ *   Apple Mac OS X KeyChain backed keychain object.
+ *
+ * See the library functions here: @ref hx509_keyset
+ */
 
 struct hx509_certs_data {
     int ref;
@@ -69,6 +93,22 @@ _hx509_ks_register(hx509_context context, struct hx509_keyset_ops *ops)
     context->ks_num_ops++;
 }
 
+/**
+ * Open or creates a new hx509 certificate store.
+ *
+ * @param context A hx509 context
+ * @param name name of the store, format is TYPE:type-specific-string,
+ * if NULL is used the MEMORY store is used.
+ * @param flags list of flags:
+ * - HX509_CERTS_CREATE create a new keystore of the specific TYPE.
+ * - HX509_CERTS_UNPROTECT_ALL fails if any private key failed to be extracted.
+ * @param lock a lock that unlocks the certificates store, use NULL to
+ * select no password/certifictes/prompt lock (see @ref page_lock).
+ * @param certs return pointer, free with hx509_certs_free().
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_init(hx509_context context,
 		 const char *name, int flags,
@@ -125,6 +165,21 @@ hx509_certs_init(hx509_context context,
     return 0;
 }
 
+/**
+ * Write the certificate store to stable storage.
+ *
+ * @param context A hx509 context.
+ * @param certs a certificate store to store.
+ * @param flags currently unused, use 0.
+ * @param lock a lock that unlocks the certificates store, use NULL to
+ * select no password/certifictes/prompt lock (see @ref page_lock).
+ *
+ * @return Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION if
+ * the certificate store doesn't support the store operation.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_store(hx509_context context,
 		  hx509_certs certs,
@@ -132,11 +187,11 @@ hx509_certs_store(hx509_context context,
 		  hx509_lock lock)
 {
     if (certs->ops->store == NULL) {
-	hx509_set_error_string(context, 0, EINVAL,
+	hx509_set_error_string(context, 0, HX509_UNSUPPORTED_OPERATION,
 			       "keystore if type %s doesn't support "
 			       "store operation",
 			       certs->ops->name);
-	return EINVAL;
+	return HX509_UNSUPPORTED_OPERATION;
     }
 
     return (*certs->ops->store)(context, certs, certs->ops_data, flags, lock);
@@ -146,6 +201,8 @@ hx509_certs_store(hx509_context context,
 hx509_certs
 _hx509_certs_ref(hx509_certs certs)
 {
+    if (certs == NULL)
+	return NULL;
     if (certs->ref <= 0)
 	_hx509_abort("certs refcount <= 0");
     certs->ref++;
@@ -154,6 +211,14 @@ _hx509_certs_ref(hx509_certs certs)
     return certs;
 }
 
+/**
+ * Free a certificate store.
+ *
+ * @param certs certificate store to free.
+ *
+ * @ingroup hx509_keyset
+ */
+
 void
 hx509_certs_free(hx509_certs *certs)
 {
@@ -169,6 +234,21 @@ hx509_certs_free(hx509_certs *certs)
     }
 }
 
+/**
+ * Start the integration
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to iterate over
+ * @param cursor cursor that will keep track of progress, free with
+ * hx509_certs_end_seq().
+ *
+ * @return Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION is
+ * returned if the certificate store doesn't support the iteration
+ * operation.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_start_seq(hx509_context context,
 		      hx509_certs certs,
@@ -177,10 +257,10 @@ hx509_certs_start_seq(hx509_context context,
     int ret;
 
     if (certs->ops->iter_start == NULL) {
-	hx509_set_error_string(context, 0, ENOENT, 
+	hx509_set_error_string(context, 0, HX509_UNSUPPORTED_OPERATION, 
 			       "Keyset type %s doesn't support iteration", 
 			       certs->ops->name);
-	return ENOENT;
+	return HX509_UNSUPPORTED_OPERATION;
     }
 
     ret = (*certs->ops->iter_start)(context, certs, certs->ops_data, cursor);
@@ -190,6 +270,21 @@ hx509_certs_start_seq(hx509_context context,
     return 0;
 }
 
+/**
+ * Get next ceritificate from the certificate keystore pointed out by
+ * cursor.
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to iterate over.
+ * @param cursor cursor that keeps track of progress.
+ * @param cert return certificate next in store, NULL if the store
+ * contains no more certificates. Free with hx509_cert_free().
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_next_cert(hx509_context context,
 		      hx509_certs certs,
@@ -200,6 +295,18 @@ hx509_certs_next_cert(hx509_context context,
     return (*certs->ops->iter)(context, certs, certs->ops_data, cursor, cert);
 }
 
+/**
+ * End the iteration over certificates.
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to iterate over.
+ * @param cursor cursor that will keep track of progress, freed.
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_end_seq(hx509_context context,
 		    hx509_certs certs,
@@ -209,11 +316,26 @@ hx509_certs_end_seq(hx509_context context,
     return 0;
 }
 
+/**
+ * Iterate over all certificates in a keystore and call an function
+ * for each fo them.
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to iterate over.
+ * @param func function to call for each certificate. The function
+ * should return non-zero to abort the iteration, that value is passed
+ * back to te caller of hx509_certs_iter().
+ * @param ctx context variable that will passed to the function.
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
 
 int
 hx509_certs_iter(hx509_context context, 
 		 hx509_certs certs, 
-		 int (*fn)(hx509_context, void *, hx509_cert),
+		 int (*func)(hx509_context, void *, hx509_cert),
 		 void *ctx)
 {
     hx509_cursor cursor;
@@ -232,7 +354,7 @@ hx509_certs_iter(hx509_context context,
 	    ret = 0;
 	    break;
 	}
-	ret = (*fn)(context, ctx, c);
+	ret = (*func)(context, ctx, c);
 	hx509_cert_free(c);
 	if (ret)
 	    break;
@@ -243,6 +365,20 @@ hx509_certs_iter(hx509_context context,
     return ret;
 }
 
+
+/**
+ * Function to use to hx509_certs_iter() as a function argument, the
+ * ctx variable to hx509_certs_iter() should be a FILE file descriptor.
+ *
+ * @param context a hx509 context.
+ * @param ctx used by hx509_certs_iter().
+ * @param c a certificate
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_ci_print_names(hx509_context context, void *ctx, hx509_cert c)
 {
@@ -264,10 +400,20 @@ hx509_ci_print_names(hx509_context context, void *ctx, hx509_cert c)
     return 0;
 }
 
-/*
- * The receiving keyset `certsī will either increase reference counter
- * of the `certī or make a deep copy, either way, the caller needs to
- * free the `certī itself.
+/**
+ * Add a certificate to the certificiate store.
+ *
+ * The receiving keyset certs will either increase reference counter
+ * of the cert or make a deep copy, either way, the caller needs to
+ * free the cert itself.
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to add the certificate to.
+ * @param cert certificate to add.
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
  */
 
 int
@@ -283,6 +429,20 @@ hx509_certs_add(hx509_context context, hx509_certs certs, hx509_cert cert)
     return (*certs->ops->add)(context, certs, certs->ops_data, cert);
 }
 
+/**
+ * Find a certificate matching the query.
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to search.
+ * @param q query allocated with @ref hx509_query functions.
+ * @param r return certificate (or NULL on error), should be freed
+ * with hx509_cert_free().
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_find(hx509_context context,
 		 hx509_certs certs, 
@@ -335,6 +495,19 @@ certs_merge_func(hx509_context context, void *ctx, hx509_cert c)
     return hx509_certs_add(context, (hx509_certs)ctx, c);
 }
 
+/**
+ * Merge a certificate store into another. The from store is keep
+ * intact.
+ *
+ * @param context a hx509 context.
+ * @param to the store to merge into.
+ * @param from the store to copy the object from.
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_merge(hx509_context context, hx509_certs to, hx509_certs from)
 {
@@ -343,6 +516,21 @@ hx509_certs_merge(hx509_context context, hx509_certs to, hx509_certs from)
     return hx509_certs_iter(context, from, certs_merge_func, to);
 }
 
+/**
+ * Same a hx509_certs_merge() but use a lock and name to describe the
+ * from source.
+ *
+ * @param context a hx509 context.
+ * @param to the store to merge into.
+ * @param lock a lock that unlocks the certificates store, use NULL to
+ * select no password/certifictes/prompt lock (see @ref page_lock).
+ * @param name name of the source store
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_append(hx509_context context,
 		   hx509_certs to,
@@ -360,6 +548,18 @@ hx509_certs_append(hx509_context context,
     return ret;
 }
 
+/**
+ * Get one random certificate from the certificate store.
+ *
+ * @param context a hx509 context.
+ * @param certs a certificate store to get the certificate from.
+ * @param c return certificate, should be freed with hx509_cert_free().
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_get_one_cert(hx509_context context, hx509_certs certs, hx509_cert *c)
 {
@@ -388,6 +588,21 @@ certs_info_stdio(void *ctx, const char *str)
     return 0;
 }
 
+/**
+ * Print some info about the certificate store.
+ *
+ * @param context a hx509 context.
+ * @param certs certificate store to print information about.
+ * @param func function that will get each line of the information, if
+ * NULL is used the data is printed on a FILE descriptor that should
+ * be passed in ctx, if ctx also is NULL, stdout is used.
+ * @param ctx parameter to func.
+ *
+ * @return Returns an hx509 error code.
+ *
+ * @ingroup hx509_keyset
+ */
+
 int
 hx509_certs_info(hx509_context context, 
 		 hx509_certs certs,