hx509_cert(3)
π 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 toNULL, 0if there's an error. and bestie, you gotta freeos->datayourself withhx509_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 theanyEKU 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 searchoidβ 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 byhx509_name_free(). See alsohx509_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 byhx509_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_contextpβ a hx509 certificateissuerβ the issuer id returned, free withder_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 ithder_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 withfree_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 withfree_AlgorithmIdentifier(). the algorithmidentifier is typiclyrsaEncryption, orid-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 byhx509_name_free(). See alsohx509_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_contextpβ a hx509 certificatesubjectβ the subject id returned, free withder_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 beNULL, she's chill like that.certβ the certificate you wanna print.outβ the stdio output stream. If it'sNULL, thenstdoutis 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 ahx509_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 isNULL, 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β theserialNumberof 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
- alpine 3.22: heimdal-doc 7.8.0-r4 Β· BSD-3-Clause
- alpine 3.23: heimdal-doc 7.8.0-r5 Β· BSD-3-Clause
- alpine 3.24: heimdal-doc 7.8.0-r5 Β· BSD-3-Clause
- epel 10: heimdal-devel 7.8.0-26.el10_2 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- epel 9: heimdal-devel 7.8.0-5.el9 Β· BSD and MIT
- fedora 43: heimdal-devel 7.8.0-26.fc43 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- fedora 43: heimdal-devel 7.8.0-26.fc43 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- fedora 44: heimdal-devel 7.8.0-26.fc43 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- fedora 44: heimdal-devel 7.8.0-26.fc43 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- fedora 44: heimdal-devel 7.8.0-28.fc44 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- fedora 44: heimdal-devel 7.8.0-28.fc44 Β· BSD-2-Clause AND BSD-3-Clause AND HPND-export-US AND HPND-export2-US AND LicenseRef-Fedora-Public-Domain
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms