diff options
Diffstat (limited to 'source4/heimdal/lib/hx509/keyset.c')
| -rw-r--r-- | source4/heimdal/lib/hx509/keyset.c | 237 |
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, |