hx509_cert(3)

πŸ“¦
version 7.8.0 Β· 3 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, epel 10, epel 9, fedora 43, fedora 44

πŸ’– hx509_cert β€” the hx509_cert(3) glow-up πŸ’–

okay bestie so this is the manual for the hx509 certificate functions from the Heimdal x509 library. yes it's a big one. yes it's gonna be a lot. but we're doing this together and honestly? it's giving "essential reading". let's go πŸ¦‹


✨ NAME ✨

hx509_cert β€” hx509 certificate functions πŸ’…


🌸 SYNOPSIS 🌸

the function squad (yes, all of them, we don't skip)

hx509_cert hx509_cert_init (hx509_context context, const Certificate *c, heim_error_t *error)
hx509_cert hx509_cert_init_data (hx509_context context, const void *ptr, size_t len, heim_error_t *error)
void hx509_cert_free (hx509_cert cert)
hx509_cert hx509_cert_ref (hx509_cert cert)
void hx509_verify_ctx_f_allow_default_trustanchors (hx509_verify_ctx ctx, int boolean)
int hx509_cert_find_subjectAltName_otherName (hx509_context context, hx509_cert cert, const heim_oid *oid, hx509_octet_string_list *list)
int hx509_cert_cmp (hx509_cert p, hx509_cert q)
int hx509_cert_get_issuer (hx509_cert p, hx509_name *name)
int hx509_cert_get_subject (hx509_cert p, hx509_name *name)
int hx509_cert_get_base_subject (hx509_context context, hx509_cert c, hx509_name *name)
int hx509_cert_get_serialnumber (hx509_cert p, heim_integer *i)
time_t hx509_cert_get_notBefore (hx509_cert p)
time_t hx509_cert_get_notAfter (hx509_cert p)
int hx509_cert_get_SPKI (hx509_context context, hx509_cert p, SubjectPublicKeyInfo *spki)
int hx509_cert_get_SPKI_AlgorithmIdentifier (hx509_context context, hx509_cert p, AlgorithmIdentifier *alg)
int hx509_cert_get_issuer_unique_id (hx509_context context, hx509_cert p, heim_bit_string *issuer)
int hx509_cert_get_subject_unique_id (hx509_context context, hx509_cert p, heim_bit_string *subject)
int hx509_verify_hostname (hx509_context context, const hx509_cert cert, int flags, hx509_hostname_type type, const char *hostname, const struct sockaddr *sa, int sa_size)
hx509_cert_attribute hx509_cert_get_attribute (hx509_cert cert, const heim_oid *oid)
int hx509_cert_set_friendly_name (hx509_cert cert, const char *name)
const char * hx509_cert_get_friendly_name (hx509_cert cert)
int hx509_query_alloc (hx509_context context, hx509_query **q)
void hx509_query_match_option (hx509_query *q, hx509_query_option option)
int hx509_query_match_issuer_serial (hx509_query *q, const Name *issuer, const heim_integer *serialNumber)
int hx509_query_match_friendly_name (hx509_query *q, const char *name)
int hx509_query_match_eku (hx509_query *q, const heim_oid *eku)
int hx509_query_match_cmp_func (hx509_query *q, int(*func)(hx509_context, hx509_cert, void *), void *ctx)
void hx509_query_free (hx509_context context, hx509_query *q)
void hx509_query_statistic_file (hx509_context context, const char *fn)
void hx509_query_unparse_stats (hx509_context context, int printtype, FILE *out)
int hx509_cert_check_eku (hx509_context context, hx509_cert cert, const heim_oid *eku, int allow_any_eku)
int hx509_cert_binary (hx509_context context, hx509_cert c, heim_octet_string *os)
int hx509_print_cert (hx509_context context, hx509_cert cert, FILE *out)

πŸŽ€ Detailed Description πŸŽ€

ok so if you want the whole lore β€” descriptions AND examples β€” go peek at The basic certificate. that's where the story starts, bestie. πŸ“–βœ¨


πŸ‘‘ Function Documentation πŸ‘‘


int hx509_cert_binary (hx509_context context, hx509_cert c, heim_octet_string * os)

takes your hx509 certificate and encodes it as a DER encoded binary. it's giving "glow up into bytes". πŸ”₯

Parameters

  • context β€” a hx509 context.
  • c β€” the certificate to encode.
  • os β€” the encoded certificate. heads up: it gets set to NULL, 0 if there's an error. and bestie, you gotta free os->data yourself with hx509_xfree().

Returns

an hx509 error code, peep hx509_get_error_string() for the deets.


int hx509_cert_check_eku (hx509_context context, hx509_cert cert, const heim_oid * eku, int allow_any_eku)

vibe-checks the extended key usage on the hx509 certificate. πŸ‘€

Parameters

  • context β€” a hx509 context.
  • cert β€” a hx509 context. (yes it says context, no we're not arguing with the original)
  • eku β€” the EKU to check for.
  • allow_any_eku β€” if the any EKU is set, let that count as a substitute.

Returns

an hx509 error code, see hx509_get_error_string().


int hx509_cert_cmp (hx509_cert p, hx509_cert q)

compares two hx509 certificate objects. super handy for sorting, no cap. πŸ“Š

Parameters

  • p β€” a hx509 certificate object.
  • q β€” a hx509 certificate object.

Returns

0 if the objects are the same, > 0 if p is 'larger' than q, < 0 if p is 'smaller' than q.


int hx509_cert_find_subjectAltName_otherName (hx509_context context, hx509_cert cert, const heim_oid * oid, hx509_octet_string_list * list)

returns a list of subjectAltNames specified by oid in the certificate. On error the

the list of octet strings it hands back should be freed with hx509_free_octet_string_list(). don't forget, bestie, or that's a leak and we don't do leaks here 🫢

Parameters

  • context β€” a hx509 context.
  • cert β€” a hx509 certificate object.
  • oid β€” an oid to for SubjectAltName.
  • list β€” list of matching SubjectAltName.

Returns

an hx509 error code, see hx509_get_error_string().


void hx509_cert_free (hx509_cert cert)

frees a reference to the hx509 certificate object. when the refcounter hits 0, the object itself gets freed β€” it's giving "last one out turns off the lights". πŸ’€ and yes, passing in NULL is totally allowed, we're not judging.

Parameters

  • cert β€” the cert to free.

hx509_cert_attribute hx509_cert_get_attribute (hx509_cert cert, const heim_oid * oid)

grabs an external attribute for the certificate β€” think friendly name, id, that kind of thing. 🏷️

Parameters

  • cert β€” hx509 certificate object to search
  • oid β€” an oid to search for.

Returns

an hx509_cert_attribute, which is only valid as long as the certificate is referenced.


int hx509_cert_get_base_subject (hx509_context context, hx509_cert c, hx509_name * name)

returns the name of the base subject of the hx509 certificate. if the certificate is a verified proxy certificate, this gives you the base certificate (aka the root of the proxy chain). 🧚 and if the proxy certificate is NOT verified with the base certificate, you get HX509_PROXY_CERTIFICATE_NOT_CANONICALIZED back. so like, no verified chain, no base subject. periodt.

Parameters

  • context β€” a hx509 context.
  • c β€” a hx509 certificate object.
  • name β€” a pointer to a hx509 name, should be freed by hx509_name_free(). See also hx509_cert_get_subject().

Returns

an hx509 error code, see hx509_get_error_string().


const char* hx509_cert_get_friendly_name (hx509_cert cert)

gets the friendly name of the certificate. yes it's literally called friendly name, we love a wholesome API πŸ₯Ή

Parameters

  • cert β€” cert to get the friendly name from.

Returns

a friendly name, or NULL if there is. the friendly name is only valid as long as the certificate is referenced.


int hx509_cert_get_issuer (hx509_cert p, hx509_name * name)

returns the name of the issuer of the hx509 certificate.

Parameters

  • p β€” a hx509 certificate object.
  • name β€” a pointer to a hx509 name, should be freed by hx509_name_free().

Returns

an hx509 error code, see hx509_get_error_string().


int hx509_cert_get_issuer_unique_id (hx509_context context, hx509_cert p, heim_bit_string * issuer)

gets a copy of the Issuer Unique ID. πŸ’…

Parameters

  • context β€” a hx509_context
  • p β€” a hx509 certificate
  • issuer β€” the issuer id returned, free with der_free_bit_string()

Returns

an hx509 error code, see hx509_get_error_string(). the error code HX509_EXTENSION_NOT_FOUND is returned if the certificate doesn't have a issuerUniqueID.


time_t hx509_cert_get_notAfter (hx509_cert p)

gets the notAfter time of the certificate. aka when it stops being valid, aka its expiration era. 😭

Parameters

  • p β€” a hx509 certificate object.

Returns

return not after time.


time_t hx509_cert_get_notBefore (hx509_cert p)

gets the notBefore time of the certificate. aka when it starts being valid, its birthday if you will πŸŽ‚

Parameters

  • p β€” a hx509 certificate object.

Returns

return not before time


int hx509_cert_get_serialnumber (hx509_cert p, heim_integer * i)

gets the serial number of the certificate.

Parameters

  • p β€” a hx509 certificate object.
  • i β€” serial number, should be freed ith der_free_heim_integer().

Returns

an hx509 error code, see hx509_get_error_string().


int hx509_cert_get_SPKI (hx509_context context, hx509_cert p, SubjectPublicKeyInfo * spki)

gets the SubjectPublicKeyInfo structure from the hx509 certificate. it's giving "the actual key material reveal" πŸ”‘βœ¨

Parameters

  • context β€” a hx509 context.
  • p β€” a hx509 certificate object.
  • spki β€” SubjectPublicKeyInfo, should be freed with free_SubjectPublicKeyInfo().

Returns

an hx509 error code, see hx509_get_error_string().


int hx509_cert_get_SPKI_AlgorithmIdentifier (hx509_context context, hx509_cert p, AlgorithmIdentifier * alg)

gets the AlgorithmIdentifier from the hx509 certificate. 🧬

Parameters

  • context β€” a hx509 context.
  • p β€” a hx509 certificate object.
  • alg β€” AlgorithmIdentifier, should be freed with free_AlgorithmIdentifier(). the algorithmidentifier is typicly rsaEncryption, or id-ecPublicKey, or some other public key mechanism.

Returns

an hx509 error code, see hx509_get_error_string().


int hx509_cert_get_subject (hx509_cert p, hx509_name * name)

returns the name of the subject of the hx509 certificate.

Parameters

  • p β€” a hx509 certificate object.
  • name β€” a pointer to a hx509 name, should be freed by hx509_name_free(). See also hx509_cert_get_base_subject().

Returns

an hx509 error code, see hx509_get_error_string().


int hx509_cert_get_subject_unique_id (hx509_context context, hx509_cert p, heim_bit_string * subject)

gets a copy of the Subect Unique ID. πŸͺͺ

Parameters

  • context β€” a hx509_context
  • p β€” a hx509 certificate
  • subject β€” the subject id returned, free with der_free_bit_string()

Returns

an hx509 error code, see hx509_get_error_string(). the error code HX509_EXTENSION_NOT_FOUND is returned if the certificate doesn't have a subjectUniqueID.


hx509_cert hx509_cert_init (hx509_context context, const Certificate * c, heim_error_t * error)

allocates and inits an hx509 certificate object from the decoded certificate c. the origin story fr fr. 🌱

Parameters

  • context β€” A hx509 context.
  • c β€”
  • error β€”

Returns

returns an hx509 certificate


hx509_cert hx509_cert_init_data (hx509_context context, const void * ptr, size_t len, heim_error_t * error)

literally just like hx509_cert_init(), except instead of a decoded certificate you hand it a pointer and a length to a memory region holding a DER/BER encoded certificate. πŸ“¦

⚠️ if that memory region contains the certificate plus anything extra, the function fails with HX509_EXTRA_DATA_AFTER_STRUCTURE. no bonus bytes allowed, bestie, it's strict like that.

Parameters

  • context β€” A hx509 context.
  • ptr β€” pointer to memory region containing encoded certificate.
  • len β€” length of memory region.
  • error β€” possibly returns an error

Returns

an hx509 certificate


hx509_cert hx509_cert_ref (hx509_cert cert)

adds a reference to a hx509 certificate object. refcounting, our beloved 🫢

Parameters

  • cert β€” a pointer to an hx509 certificate object.

Returns

the same object as is passed in.


int hx509_cert_set_friendly_name (hx509_cert cert, const char * name)

sets the friendly name on the certificate. giving your cert a little nickname, iconic behavior. 🏷️✨


ok bestie we're not done yet β€” this is only part one. more of the function fam is coming right up, don't go anywhere πŸ’œ

Parameters πŸ’–

  • cert β€” the certificate you're putting the friendly name on. That's the one.
  • name β€” the friendly name. Adorable. 🌸

Returns

An hx509 error code, and if you're confused about it, go read hx509_get_error_string(). She'll tell you what's up.


✨ int hx509_print_cert (hx509_context context, hx509_cert cert, FILE * out)

Prints out a simple little representation of a certificate. Nothing fancy, just the basics, but it gets the job done. πŸ’…

Parameters

  • context β€” an hx509 context. Can be NULL, she's chill like that.
  • cert β€” the certificate you wanna print.
  • out β€” the stdio output stream. If it's NULL, then stdout is used, so it just goes straight to your terminal, periodt.

Returns

An hx509 error code.


🌈 int hx509_query_alloc (hx509_context context, hx509_query ** q)

Allocates a query controller. When you're done with it, free it with hx509_query_free(). Don't leave it lying around, bestie, that's a memory leak and we don't do those. 🫢

Parameters

  • context β€” an hx509 context.
  • q β€” return pointer to a hx509_query.

Returns

An hx509 error code, see hx509_get_error_string().


πŸ¦‹ void hx509_query_free (hx509_context context, hx509_query * q)

Frees the query controller. Cleanup era. 🧹

Parameters

  • context β€” an hx509 context.
  • q β€” a pointer to the query controller.

πŸ‘‘ int hx509_query_match_cmp_func (hx509_query * q, int(*)(hx509_context, hx509_cert, void *) func, void * ctx)

Sets the query controller to match using a specific match function. You bring your own logic, she respects that.

Parameters

  • q β€” a hx509 query controller.
  • func β€” the function to use for matching. If this argument is NULL, the match function gets removed. Gone. Not invited back. πŸ’€
  • ctx β€” context passed to the function.

Returns

An hx509 error code, see hx509_get_error_string().


πŸŽ€ int hx509_query_match_eku (hx509_query * q, const heim_oid * eku)

Sets the query controller to require one specific EKU (extended key usage). Heads up: any previous EKU matching is overwitten β€” yes, overwritten, the original spelling said "overwitten" and we keep the lore β€” so it's one at a time, she's monogamous about EKUs. If NULL is passed in as the eku, the EKU requirement is reset. No EKU, no problem. ✨

Parameters

  • q β€” a hx509 query controller.
  • eku β€” an EKU to match on.

Returns

An hx509 error code, see hx509_get_error_string().


πŸ’œ int hx509_query_match_friendly_name (hx509_query * q, const char * name)

Sets the query controller to match on a friendly name. It's giving "find me by my cute nickname". πŸ₯°

Parameters

  • q β€” a hx509 query controller.
  • name β€” a friendly name to match on.

Returns

An hx509 error code, see hx509_get_error_string().


⭐ int hx509_query_match_issuer_serial (hx509_query * q, const Name * issuer, const heim_integer * serialNumber)

Sets the issuer and serial number to match in the query controller. The function makes copies of the issuer and the serial number, so you don't gotta worry about your originals getting snatched. πŸ”₯

Parameters

  • q β€” a hx509 query controller.
  • issuer β€” issuer to search for.
  • serialNumber β€” the serialNumber of the issuer.

Returns

An hx509 error code, see hx509_get_error_string().


πŸ“ void hx509_query_match_option (hx509_query * q, hx509_query_option option)

Sets the match options for the hx509 query controller.

Parameters

  • q β€” query controller.
  • option β€” options to control the query controller.

Returns

An hx509 error code, see hx509_get_error_string(). (Yeah, it's a void function with a Returns section. The docs said what they said, we're not editing the canon. πŸ™ˆ)


🌸 void hx509_query_statistic_file (hx509_context context, const char * fn)

Sets a statistic file for the query statistics. Numbers girlies, this one's for you.

Parameters

  • context β€” an hx509 context.
  • fn β€” statistics file name.

🧚 void hx509_query_unparse_stats (hx509_context context, int printtype, FILE * out)

Unparses the statistics file and prints the result on a FILE descriptor. Reverse engineering the stats, iconic behavior.

Parameters

  • context β€” an hx509 context.
  • printtype β€” type to print.
  • out β€” the FILE to write the data on.

πŸ”₯ void hx509_verify_ctx_f_allow_default_trustanchors (hx509_verify_ctx ctx, int boolean)

Allows using the operating system's builtin trust anchors if no other trust anchors are configured. Like, if nobody set anything up, fine, we'll use the OS ones. Backup plan energy. 🫢

Parameters

  • ctx β€” a verification context.
  • boolean β€” if non-zero, use the operating system's builtin trust anchors.

Returns

An hx509 error code, see hx509_get_error_string(). (Also a void function with a Returns section. We don't question the ancients.)


🌟 int hx509_verify_hostname (hx509_context context, const hx509_cert cert, int flags, hx509_hostname_type type, const char * hostname, const struct sockaddr * sa, int sa_size)

Verifies that the certificate is actually allowed to be used for the hostname and the address. This is the vibe check of the whole page, ngl.

Parameters

  • context β€” an hx509 context.
  • cert β€” the certificate to match with.
  • flags β€” flags to modify the behavior:
    • HX509_VHN_F_ALLOW_NO_MATCH β€” no match is ok.
  • type β€” type of hostname:
    • HX509_HN_HOSTNAME β€” for plain hostname.
    • HX509_HN_DNSSRV β€” for DNS SRV names.
  • hostname β€” the hostname to check.
  • sa β€” address of the host.
  • sa_size β€” length of address.

Returns

An hx509 error code, see hx509_get_error_string().


✍️ Author

Generated automatically by Doxygen for Heimdal x509 library from the source code. Not a human, not a girlie, just a doc generator doing its little thing. πŸŽ€


That's the whole page, bestie β€” no cap. πŸ’–

This one's from the Heimdal x509 library docs, Version 7.8.0, dated Tue Nov 15 2022, and it lives under hx509_cert(3). Go forth and verify some hostnames. Slay. πŸ‘‘βœ¨πŸ¦‹

πŸ“¦ where this page comes from