*/
#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;
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,
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,
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);
hx509_certs
_hx509_certs_ref(hx509_certs certs)
{
+ if (certs == NULL)
+ return NULL;
if (certs->ref <= 0)
_hx509_abort("certs refcount <= 0");
certs->ref++;
return certs;
}
+/**
+ * Free a certificate store.
+ *
+ * @param certs certificate store to free.
+ *
+ * @ingroup hx509_keyset
+ */
+
void
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,
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);
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,
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,
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;
ret = 0;
break;
}
- ret = (*fn)(context, ctx, c);
+ ret = (*func)(context, ctx, c);
hx509_cert_free(c);
if (ret)
break;
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)
{
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
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,
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)
{
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,
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)
{
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,
git.samba.org / samba.git / blobdiff