2 * Copyright (c) 2004 - 2007 Kungliga Tekniska Högskolan
3 * (Royal Institute of Technology, Stockholm, Sweden).
6 * Portions Copyright (c) 2009 Apple Inc. All rights reserved.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in the
17 * documentation and/or other materials provided with the distribution.
19 * 3. Neither the name of the Institute nor the names of its contributors
20 * may be used to endorse or promote products derived from this software
21 * without specific prior written permission.
23 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
27 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 * @page page_keyset Certificate store operations
41 * Type of certificates store:
43 * In memory based format. Doesnt support storing.
45 * FILE supports raw DER certicates and PEM certicates. When PEM is
46 * used the file can contain may certificates and match private
47 * keys. Support storing the certificates. DER format only supports
48 * on certificate and no private key.
50 * Same as FILE, defaulting to PEM encoded certificates.
52 * Same as FILE, defaulting to DER encoded certificates.
57 * Apple Mac OS X KeyChain backed keychain object.
59 * See the library functions here: @ref hx509_keyset
62 struct hx509_certs_data {
64 struct hx509_keyset_ops *ops;
68 static struct hx509_keyset_ops *
69 _hx509_ks_type(hx509_context context, const char *type)
73 for (i = 0; i < context->ks_num_ops; i++)
74 if (strcasecmp(type, context->ks_ops[i]->name) == 0)
75 return context->ks_ops[i];
81 _hx509_ks_register(hx509_context context, struct hx509_keyset_ops *ops)
83 struct hx509_keyset_ops **val;
85 if (_hx509_ks_type(context, ops->name))
88 val = realloc(context->ks_ops,
89 (context->ks_num_ops + 1) * sizeof(context->ks_ops[0]));
92 val[context->ks_num_ops] = ops;
93 context->ks_ops = val;
94 context->ks_num_ops++;
98 * Open or creates a new hx509 certificate store.
100 * @param context A hx509 context
101 * @param name name of the store, format is TYPE:type-specific-string,
102 * if NULL is used the MEMORY store is used.
103 * @param flags list of flags:
104 * - HX509_CERTS_CREATE create a new keystore of the specific TYPE.
105 * - HX509_CERTS_UNPROTECT_ALL fails if any private key failed to be extracted.
106 * @param lock a lock that unlocks the certificates store, use NULL to
107 * select no password/certifictes/prompt lock (see @ref page_lock).
108 * @param certs return pointer, free with hx509_certs_free().
110 * @ingroup hx509_keyset
114 hx509_certs_init(hx509_context context,
115 const char *name, int flags,
116 hx509_lock lock, hx509_certs *certs)
118 struct hx509_keyset_ops *ops;
126 residue = strchr(name, ':');
128 type = malloc(residue - name + 1);
130 strlcpy(type, name, residue - name + 1);
132 if (residue[0] == '\0')
135 type = strdup("MEMORY");
139 hx509_clear_error_string(context);
143 ops = _hx509_ks_type(context, type);
145 hx509_set_error_string(context, 0, ENOENT,
146 "Keyset type %s is not supported", type);
151 c = calloc(1, sizeof(*c));
153 hx509_clear_error_string(context);
159 ret = (*ops->init)(context, c, &c->ops_data, flags, residue, lock);
170 * Write the certificate store to stable storage.
172 * @param context A hx509 context.
173 * @param certs a certificate store to store.
174 * @param flags currently unused, use 0.
175 * @param lock a lock that unlocks the certificates store, use NULL to
176 * select no password/certifictes/prompt lock (see @ref page_lock).
178 * @return Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION if
179 * the certificate store doesn't support the store operation.
181 * @ingroup hx509_keyset
185 hx509_certs_store(hx509_context context,
190 if (certs->ops->store == NULL) {
191 hx509_set_error_string(context, 0, HX509_UNSUPPORTED_OPERATION,
192 "keystore if type %s doesn't support "
195 return HX509_UNSUPPORTED_OPERATION;
198 return (*certs->ops->store)(context, certs, certs->ops_data, flags, lock);
203 hx509_certs_ref(hx509_certs certs)
208 _hx509_abort("certs refcount == 0 on ref");
209 if (certs->ref == UINT_MAX)
210 _hx509_abort("certs refcount == UINT_MAX on ref");
216 * Free a certificate store.
218 * @param certs certificate store to free.
220 * @ingroup hx509_keyset
224 hx509_certs_free(hx509_certs *certs)
227 if ((*certs)->ref == 0)
228 _hx509_abort("cert refcount == 0 on free");
229 if (--(*certs)->ref > 0)
232 (*(*certs)->ops->free)(*certs, (*certs)->ops_data);
239 * Start the integration
241 * @param context a hx509 context.
242 * @param certs certificate store to iterate over
243 * @param cursor cursor that will keep track of progress, free with
244 * hx509_certs_end_seq().
246 * @return Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION is
247 * returned if the certificate store doesn't support the iteration
250 * @ingroup hx509_keyset
254 hx509_certs_start_seq(hx509_context context,
256 hx509_cursor *cursor)
260 if (certs->ops->iter_start == NULL) {
261 hx509_set_error_string(context, 0, HX509_UNSUPPORTED_OPERATION,
262 "Keyset type %s doesn't support iteration",
264 return HX509_UNSUPPORTED_OPERATION;
267 ret = (*certs->ops->iter_start)(context, certs, certs->ops_data, cursor);
275 * Get next ceritificate from the certificate keystore pointed out by
278 * @param context a hx509 context.
279 * @param certs certificate store to iterate over.
280 * @param cursor cursor that keeps track of progress.
281 * @param cert return certificate next in store, NULL if the store
282 * contains no more certificates. Free with hx509_cert_free().
284 * @return Returns an hx509 error code.
286 * @ingroup hx509_keyset
290 hx509_certs_next_cert(hx509_context context,
296 return (*certs->ops->iter)(context, certs, certs->ops_data, cursor, cert);
300 * End the iteration over certificates.
302 * @param context a hx509 context.
303 * @param certs certificate store to iterate over.
304 * @param cursor cursor that will keep track of progress, freed.
306 * @return Returns an hx509 error code.
308 * @ingroup hx509_keyset
312 hx509_certs_end_seq(hx509_context context,
316 (*certs->ops->iter_end)(context, certs, certs->ops_data, cursor);
321 * Iterate over all certificates in a keystore and call an function
324 * @param context a hx509 context.
325 * @param certs certificate store to iterate over.
326 * @param func function to call for each certificate. The function
327 * should return non-zero to abort the iteration, that value is passed
328 * back to the caller of hx509_certs_iter_f().
329 * @param ctx context variable that will passed to the function.
331 * @return Returns an hx509 error code.
333 * @ingroup hx509_keyset
337 hx509_certs_iter_f(hx509_context context,
339 int (*func)(hx509_context, void *, hx509_cert),
346 ret = hx509_certs_start_seq(context, certs, &cursor);
351 ret = hx509_certs_next_cert(context, certs, cursor, &c);
358 ret = (*func)(context, ctx, c);
364 hx509_certs_end_seq(context, certs, cursor);
370 * Iterate over all certificates in a keystore and call an function
373 * @param context a hx509 context.
374 * @param certs certificate store to iterate over.
375 * @param func function to call for each certificate. The function
376 * should return non-zero to abort the iteration, that value is passed
377 * back to the caller of hx509_certs_iter().
379 * @return Returns an hx509 error code.
381 * @ingroup hx509_keyset
387 certs_iter(hx509_context context, void *ctx, hx509_cert cert)
389 int (^func)(hx509_cert) = ctx;
394 * Iterate over all certificates in a keystore and call an block
397 * @param context a hx509 context.
398 * @param certs certificate store to iterate over.
399 * @param func block to call for each certificate. The function
400 * should return non-zero to abort the iteration, that value is passed
401 * back to the caller of hx509_certs_iter().
403 * @return Returns an hx509 error code.
405 * @ingroup hx509_keyset
409 hx509_certs_iter(hx509_context context,
411 int (^func)(hx509_cert))
413 return hx509_certs_iter_f(context, certs, certs_iter, func);
419 * Function to use to hx509_certs_iter_f() as a function argument, the
420 * ctx variable to hx509_certs_iter_f() should be a FILE file descriptor.
422 * @param context a hx509 context.
423 * @param ctx used by hx509_certs_iter_f().
424 * @param c a certificate
426 * @return Returns an hx509 error code.
428 * @ingroup hx509_keyset
432 hx509_ci_print_names(hx509_context context, void *ctx, hx509_cert c)
438 cert = _hx509_get_cert(c);
440 _hx509_name_from_Name(&cert->tbsCertificate.subject, &n);
441 hx509_name_to_string(n, &s);
443 _hx509_name_from_Name(&cert->tbsCertificate.issuer, &n);
444 hx509_name_to_string(n, &i);
446 fprintf(ctx, "subject: %s\nissuer: %s\n", s, i);
453 * Add a certificate to the certificiate store.
455 * The receiving keyset certs will either increase reference counter
456 * of the cert or make a deep copy, either way, the caller needs to
457 * free the cert itself.
459 * @param context a hx509 context.
460 * @param certs certificate store to add the certificate to.
461 * @param cert certificate to add.
463 * @return Returns an hx509 error code.
465 * @ingroup hx509_keyset
469 hx509_certs_add(hx509_context context, hx509_certs certs, hx509_cert cert)
471 if (certs->ops->add == NULL) {
472 hx509_set_error_string(context, 0, ENOENT,
473 "Keyset type %s doesn't support add operation",
478 return (*certs->ops->add)(context, certs, certs->ops_data, cert);
482 * Find a certificate matching the query.
484 * @param context a hx509 context.
485 * @param certs certificate store to search.
486 * @param q query allocated with @ref hx509_query functions.
487 * @param r return certificate (or NULL on error), should be freed
488 * with hx509_cert_free().
490 * @return Returns an hx509 error code.
492 * @ingroup hx509_keyset
496 hx509_certs_find(hx509_context context,
498 const hx509_query *q,
507 _hx509_query_statistic(context, 0, q);
509 if (certs->ops->query)
510 return (*certs->ops->query)(context, certs, certs->ops_data, q, r);
512 ret = hx509_certs_start_seq(context, certs, &cursor);
518 ret = hx509_certs_next_cert(context, certs, cursor, &c);
523 if (_hx509_query_match_cert(context, q, c)) {
530 hx509_certs_end_seq(context, certs, cursor);
534 * Return HX509_CERT_NOT_FOUND if no certificate in certs matched
538 hx509_clear_error_string(context);
539 return HX509_CERT_NOT_FOUND;
546 * Filter certificate matching the query.
548 * @param context a hx509 context.
549 * @param certs certificate store to search.
550 * @param q query allocated with @ref hx509_query functions.
551 * @param result the filtered certificate store, caller must free with
552 * hx509_certs_free().
554 * @return Returns an hx509 error code.
556 * @ingroup hx509_keyset
560 hx509_certs_filter(hx509_context context,
562 const hx509_query *q,
569 _hx509_query_statistic(context, 0, q);
571 ret = hx509_certs_init(context, "MEMORY:filter-certs", 0,
576 ret = hx509_certs_start_seq(context, certs, &cursor);
578 hx509_certs_free(result);
584 ret = hx509_certs_next_cert(context, certs, cursor, &c);
589 if (_hx509_query_match_cert(context, q, c)) {
590 hx509_certs_add(context, *result, c);
596 hx509_certs_end_seq(context, certs, cursor);
598 hx509_certs_free(result);
603 * Return HX509_CERT_NOT_FOUND if no certificate in certs matched
607 hx509_certs_free(result);
608 hx509_clear_error_string(context);
609 return HX509_CERT_NOT_FOUND;
617 certs_merge_func(hx509_context context, void *ctx, hx509_cert c)
619 return hx509_certs_add(context, (hx509_certs)ctx, c);
623 * Merge a certificate store into another. The from store is keep
626 * @param context a hx509 context.
627 * @param to the store to merge into.
628 * @param from the store to copy the object from.
630 * @return Returns an hx509 error code.
632 * @ingroup hx509_keyset
636 hx509_certs_merge(hx509_context context, hx509_certs to, hx509_certs from)
640 return hx509_certs_iter_f(context, from, certs_merge_func, to);
644 * Same a hx509_certs_merge() but use a lock and name to describe the
647 * @param context a hx509 context.
648 * @param to the store to merge into.
649 * @param lock a lock that unlocks the certificates store, use NULL to
650 * select no password/certifictes/prompt lock (see @ref page_lock).
651 * @param name name of the source store
653 * @return Returns an hx509 error code.
655 * @ingroup hx509_keyset
659 hx509_certs_append(hx509_context context,
667 ret = hx509_certs_init(context, name, 0, lock, &s);
670 ret = hx509_certs_merge(context, to, s);
671 hx509_certs_free(&s);
676 * Get one random certificate from the certificate store.
678 * @param context a hx509 context.
679 * @param certs a certificate store to get the certificate from.
680 * @param c return certificate, should be freed with hx509_cert_free().
682 * @return Returns an hx509 error code.
684 * @ingroup hx509_keyset
688 hx509_get_one_cert(hx509_context context, hx509_certs certs, hx509_cert *c)
695 ret = hx509_certs_start_seq(context, certs, &cursor);
699 ret = hx509_certs_next_cert(context, certs, cursor, c);
703 hx509_certs_end_seq(context, certs, cursor);
708 certs_info_stdio(void *ctx, const char *str)
711 fprintf(f, "%s\n", str);
716 * Print some info about the certificate store.
718 * @param context a hx509 context.
719 * @param certs certificate store to print information about.
720 * @param func function that will get each line of the information, if
721 * NULL is used the data is printed on a FILE descriptor that should
722 * be passed in ctx, if ctx also is NULL, stdout is used.
723 * @param ctx parameter to func.
725 * @return Returns an hx509 error code.
727 * @ingroup hx509_keyset
731 hx509_certs_info(hx509_context context,
733 int (*func)(void *, const char *),
737 func = certs_info_stdio;
741 if (certs->ops->printinfo == NULL) {
742 (*func)(ctx, "No info function for certs");
745 return (*certs->ops->printinfo)(context, certs, certs->ops_data,
750 _hx509_pi_printf(int (*func)(void *, const char *), void *ctx,
751 const char *fmt, ...)
757 vasprintf(&str, fmt, ap);
766 _hx509_certs_keys_get(hx509_context context,
768 hx509_private_key **keys)
770 if (certs->ops->getkeys == NULL) {
774 return (*certs->ops->getkeys)(context, certs, certs->ops_data, keys);
778 _hx509_certs_keys_add(hx509_context context,
780 hx509_private_key key)
782 if (certs->ops->addkey == NULL) {
783 hx509_set_error_string(context, 0, EINVAL,
784 "keystore if type %s doesn't support "
789 return (*certs->ops->addkey)(context, certs, certs->ops_data, key);
794 _hx509_certs_keys_free(hx509_context context,
795 hx509_private_key *keys)
798 for (i = 0; keys[i]; i++)
799 hx509_private_key_free(&keys[i]);