hx509_keyset(3)

💖 hx509_keyset(3) 💖

okay bestie, sit down, hydrate, because we're about to get into hx509_keyset — aka the hx509 certificate store functions from the Heimdal x509 library. this is the whole keyset situation: opening stores, yeeting certs in, iterating over them, all of it. no cap. 🎀

---

✨ NAME ✨

hx509_keyset — hx509 certificate store functions. that's it, that's the girl. 👑

---

🌸 SYNOPSIS 🌸

🦋 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)

look at her. sixteen functions. main character energy fr fr. 💅

---

🌈 DETAILED DESCRIPTION 🌈

See the Certificate store operations for description and examples. that's literally what it says, bestie — go read that one, it's giving context. 📚

---

🔥 FUNCTION DOCUMENTATION 🔥

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

Add a certificate to the certificiate store. yes we're adding a cert, so exciting.

the receiving keyset certs will either increase the reference counter of the cert or make a deep copy — either way, the caller needs to free the cert itself. don't forget, or that's a leak and we don't do leaks. 😭

Parameters

• context — a hx509 context.
• certs — certificate store to add the certificate to.
• cert — certificate to add.

Returns

Returns an hx509 error code.

---

🦋 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. yes, it says "Same a" — iconic typo, we keep it, we respect it. 🫶

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.

---

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

End the iteration over certificates. closing time, bestie, the cursor is done. 🎬

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.

---

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

Filter certificate matching the query. it's giving curated feed. only the certs that match get in. 💅

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.

---

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

Find a certificate matching the query. where is she. we must locate her. 🔍

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.

---

🌸 void hx509_certs_free (hx509_certs * certs)

Free a certificate store. let her go, she's done her job. 🕊️

Parameters

• certs — certificate store to free.

---

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

Print some info about the certificate store. gossip about the store, basically. ☕

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.

---

👑 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. the origin story. the opening scene. 🎬

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.

---

🧚 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. one by one, bestie, we're going through the whole roster. 📋

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.

---

💜 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. we're combining, not consuming. the from girl survives this. 🫶

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.

---

🦋 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. next. NEXT. keep the line moving. 🚶‍♀️

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.

---

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

Start the integration

yes bestie, the original literally just says "Start the integration" and nothing else. we don't question it, we honor it. 💀

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.

---

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

Write the certificate store to stable storage. committing. making it permanent. periodt. 💾

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.

---

🍓 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. yes she's built different, she's designed to be handed straight to the iterator. 💅

Parameters

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

Returns

Returns an hx509 error code.

---

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

Get one random certificate from the certificate store. random!! chaos!! the surprise me mechanic!! 🎲

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.

---

🫶 AUTHOR 🫶

Generated automatically by Doxygen for Heimdal x509 library from the source code. so technically the author is a robot and we love her for it. 🤖💖

---

okay that's the whole page bestie, you ate that. and for the cute sign-off: this gorgeous thing is Version 7.8.0, dated Tue Nov 15 2022, and she lives at hx509_keyset(3). go forth and handle your certificate stores responsibly. mwah. 💋🎀✨