Functions
hx509 certificate store functions

## Functions
int | hx509_certs_init (hx509_context context, const char *name, int flags, hx509_lock lock, hx509_certs *certs)
int | hx509_certs_store (hx509_context context, hx509_certs certs, int flags, hx509_lock lock)
void | hx509_certs_free (hx509_certs *certs)
int | hx509_certs_start_seq (hx509_context context, hx509_certs certs, hx509_cursor *cursor)
int | hx509_certs_next_cert (hx509_context context, hx509_certs certs, hx509_cursor cursor, hx509_cert *cert)
int | hx509_certs_end_seq (hx509_context context, hx509_certs certs, hx509_cursor cursor)
int | hx509_certs_iter_f (hx509_context context, hx509_certs certs, int(*func)(hx509_context, void *, hx509_cert), void *ctx)
int | hx509_ci_print_names (hx509_context context, void *ctx, hx509_cert c)
int | hx509_certs_add (hx509_context context, hx509_certs certs, hx509_cert cert)
int | hx509_certs_find (hx509_context context, hx509_certs certs, const hx509_query *q, hx509_cert *r)
int | hx509_certs_filter (hx509_context context, hx509_certs certs, const hx509_query *q, hx509_certs *result)
int | hx509_certs_merge (hx509_context context, hx509_certs to, hx509_certs from)
int | hx509_certs_append (hx509_context context, hx509_certs to, hx509_lock lock, const char *name)
int | hx509_get_one_cert (hx509_context context, hx509_certs certs, hx509_cert *c)
int | hx509_certs_info (hx509_context context, hx509_certs certs, int(*func)(void *, const char *), void *ctx)

## Detailed Description

See the Certificate store operations for description and examples.

## Function Documentation

## ◆ hx509_certs_add()

int hx509_certs_add | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | hx509_cert | cert
| ) |  |

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.

Parameters

  context | a hx509 context.
  certs | certificate store to add the certificate to.
  cert | certificate to add.

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_append()

int hx509_certs_append | ( | hx509_context | context,
|  | hx509_certs | to,
|  | hx509_lock | lock,
|  | const char * | name
| ) |  |

Same a hx509_certs_merge() but use a lock and name to describe the from source.

Parameters

  context | a hx509 context.
  to | the store to merge into.
  lock | a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see Locking and unlocking certificates and encrypted data.).
  name | name of the source store

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_end_seq()

int hx509_certs_end_seq | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | hx509_cursor | cursor
| ) |  |

End the iteration over certificates.

Parameters

  context | a hx509 context.
  certs | certificate store to iterate over.
  cursor | cursor that will keep track of progress, freed.

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_filter()

int hx509_certs_filter | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | const hx509_query * | q,
|  | hx509_certs * | result
| ) |  |

Filter certificate matching the query.

Parameters

  context | a hx509 context.
  certs | certificate store to search.
  q | query allocated with hx509 query functions functions.
  result | the filtered certificate store, caller must free with hx509_certs_free().

Returns
  Returns an hx509 error code.

Return HX509_CERT_NOT_FOUND if no certificate in certs matched the query.

## ◆ hx509_certs_find()

int hx509_certs_find | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | const hx509_query * | q,
|  | hx509_cert * | r
| ) |  |

Find a certificate matching the query.

Parameters

  context | a hx509 context.
  certs | certificate store to search.
  q | query allocated with hx509 query functions functions.
  r | return certificate (or NULL on error), should be freed with hx509_cert_free().

Returns
  Returns an hx509 error code.

Return HX509_CERT_NOT_FOUND if no certificate in certs matched the query.

## ◆ hx509_certs_free()

void hx509_certs_free | ( | hx509_certs * | certs | ) |

Free a certificate store.

Parameters

  certs | certificate store to free.

## ◆ hx509_certs_info()

int hx509_certs_info | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | int(*)(void *, const char *) | func,
|  | void * | ctx
| ) |  |

Print some info about the certificate store.

Parameters

  context | a hx509 context.
  certs | certificate store to print information about.
  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.
  ctx | parameter to func.

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_init()

int hx509_certs_init | ( | hx509_context | context,
|  | const char * | name,
|  | int | flags,
|  | hx509_lock | lock,
|  | hx509_certs * | certs
| ) |  |

Open or creates a new hx509 certificate store.

Parameters

  context | A hx509 context
  name | name of the store, format is TYPE:type-specific-string, if NULL is used the MEMORY store is used.
  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.
  lock | a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see Locking and unlocking certificates and encrypted data.).
  certs | return pointer, free with hx509_certs_free().

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_iter_f()

int hx509_certs_iter_f | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | int(*)(hx509_context, void *, hx509_cert) | func,
|  | void * | ctx
| ) |  |

Iterate over all certificates in a keystore and call a function for each of them.

Parameters

  context | a hx509 context.
  certs | certificate store to iterate over.
  func | function to call for each certificate. The function should return non-zero to abort the iteration, that value is passed back to the caller of hx509_certs_iter_f().
  ctx | context variable that will passed to the function.

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_merge()

int hx509_certs_merge | ( | hx509_context | context,
|  | hx509_certs | to,
|  | hx509_certs | from
| ) |  |

Merge a certificate store into another. The from store is keep intact.

Parameters

  context | a hx509 context.
  to | the store to merge into.
  from | the store to copy the object from.

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_next_cert()

int hx509_certs_next_cert | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | hx509_cursor | cursor,
|  | hx509_cert * | cert
| ) |  |

Get next ceritificate from the certificate keystore pointed out by cursor.

Parameters

  context | a hx509 context.
  certs | certificate store to iterate over.
  cursor | cursor that keeps track of progress.
  cert | return certificate next in store, NULL if the store contains no more certificates. Free with hx509_cert_free().

Returns
  Returns an hx509 error code.

## ◆ hx509_certs_start_seq()

int hx509_certs_start_seq | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | hx509_cursor * | cursor
| ) |  |

Start the integration

Parameters

  context | a hx509 context.
  certs | certificate store to iterate over
  cursor | cursor that will keep track of progress, free with hx509_certs_end_seq().

Returns
  Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION is returned if the certificate store doesn't support the iteration operation.

## ◆ hx509_certs_store()

int hx509_certs_store | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | int | flags,
|  | hx509_lock | lock
| ) |  |

Write the certificate store to stable storage.

Parameters

  context | A hx509 context.
  certs | a certificate store to store.
  flags | currently unused, use 0.
  lock | a lock that unlocks the certificates store, use NULL to select no password/certifictes/prompt lock (see Locking and unlocking certificates and encrypted data.).

Returns
  Returns an hx509 error code. HX509_UNSUPPORTED_OPERATION if the certificate store doesn't support the store operation.

## ◆ hx509_ci_print_names()

int hx509_ci_print_names | ( | hx509_context | context,
|  | void * | ctx,
|  | hx509_cert | c
| ) |  |

Function to use to hx509_certs_iter_f() as a function argument, the ctx variable to hx509_certs_iter_f() should be a FILE file descriptor.

Parameters

  context | a hx509 context.
  ctx | used by hx509_certs_iter_f().
  c | a certificate

Returns
  Returns an hx509 error code.

## ◆ hx509_get_one_cert()

int hx509_get_one_cert | ( | hx509_context | context,
|  | hx509_certs | certs,
|  | hx509_cert * | c
| ) |  |

Get one random certificate from the certificate store.

Parameters

  context | a hx509 context.
  certs | a certificate store to get the certificate from.
  c | return certificate, should be freed with hx509_cert_free().

Returns
  Returns an hx509 error code.