hx509_ca(3)

💖 hx509_ca — hx509 CA functions 💖

okay bestie, welcome to the CA corner of the Heimdal x509 library 🌸 this is manual section 3, and no cap, this page is a whole moment — it's the certificate-authority toolkit, and we're gonna get through it together. grab a lil snack, we got this 🍓

---

✨ SYNOPSIS ✨

Functions

here's the whole squad, listed exactly how the page lists them, periodt 👑

   Functions
       int hx509_ca_tbs_init (hx509_context context, hx509_ca_tbs *tbs)
       void hx509_ca_tbs_free (hx509_ca_tbs *tbs)
       int hx509_ca_tbs_set_notBefore (hx509_context context, hx509_ca_tbs tbs,
           time_t t)
       int hx509_ca_tbs_set_notAfter (hx509_context context, hx509_ca_tbs tbs,
           time_t t)
       int hx509_ca_tbs_set_notAfter_lifetime (hx509_context context,
           hx509_ca_tbs tbs, time_t delta)
       const struct units * hx509_ca_tbs_template_units (void)
       int hx509_ca_tbs_set_template (hx509_context context, hx509_ca_tbs tbs,
           int flags, hx509_cert cert)
       int hx509_ca_tbs_set_ca (hx509_context context, hx509_ca_tbs tbs, int
           pathLenConstraint)
       int hx509_ca_tbs_set_proxy (hx509_context context, hx509_ca_tbs tbs, int
           pathLenConstraint)
       int hx509_ca_tbs_set_domaincontroller (hx509_context context,
           hx509_ca_tbs tbs)
       int hx509_ca_tbs_set_spki (hx509_context context, hx509_ca_tbs tbs,
           const SubjectPublicKeyInfo *spki)
       int hx509_ca_tbs_set_serialnumber (hx509_context context, hx509_ca_tbs
           tbs, const heim_integer *serialNumber)
       int hx509_ca_tbs_add_eku (hx509_context context, hx509_ca_tbs tbs, const
           heim_oid *oid)
       int hx509_ca_tbs_add_crl_dp_uri (hx509_context context, hx509_ca_tbs
           tbs, const char *uri, hx509_name issuername)
       int hx509_ca_tbs_add_san_otherName (hx509_context context, hx509_ca_tbs
           tbs, const heim_oid *oid, const heim_octet_string *os)
       int hx509_ca_tbs_add_san_pkinit (hx509_context context, hx509_ca_tbs
           tbs, const char *principal)
       int hx509_ca_tbs_add_san_ms_upn (hx509_context context, hx509_ca_tbs
           tbs, const char *principal)
       int hx509_ca_tbs_add_san_jid (hx509_context context, hx509_ca_tbs tbs,
           const char *jid)
       int hx509_ca_tbs_add_san_hostname (hx509_context context, hx509_ca_tbs
           tbs, const char *dnsname)
       int hx509_ca_tbs_add_san_rfc822name (hx509_context context, hx509_ca_tbs
           tbs, const char *rfc822Name)
       int hx509_ca_tbs_set_subject (hx509_context context, hx509_ca_tbs tbs,
           hx509_name subject)
       int hx509_ca_tbs_set_unique (hx509_context context, hx509_ca_tbs tbs,
           const heim_bit_string *subjectUniqueID, const heim_bit_string
           *issuerUniqueID)
       int hx509_ca_tbs_subject_expand (hx509_context context, hx509_ca_tbs
           tbs, hx509_env env)
       int hx509_ca_tbs_set_signature_algorithm (hx509_context context,
           hx509_ca_tbs tbs, const AlgorithmIdentifier *sigalg)
       int hx509_ca_sign (hx509_context context, hx509_ca_tbs tbs, hx509_cert
           signer, hx509_cert *certificate)
       int hx509_ca_sign_self (hx509_context context, hx509_ca_tbs tbs,
           hx509_private_key signer, hx509_cert *certificate)

---

okay so vibe check on what you're looking at 👀 almost every single one of these is a hx509_ca_tbs_* function, which is giving tbs = "to be signed" energy — you build up the certificate-to-be, tweak it, and then hand it off to be signed. the tbs ones are the build-up era, and the last two are the main-character moment where the signing actually happens 💅

a few things you'll spot in the crowd:

• the classic hx509_context context first argument, everywhere, like a lil signature perfume
• the matching pair of hx509_ca_tbs_init and hx509_ca_tbs_free — one opens the door, one closes it 🚪✨
• the add_san_* crew: otherName, pkinit, ms_upn, jid, hostname, rfc822name — all the subject alternative name flavors, each with its own lil type
• hx509_ca_tbs_template_units is the odd one out and honestly iconic for it — it takes void and hands you back a const struct units *, no context arg, no tbs, just vibes 🦋
• hx509_ca_sign and hx509_ca_sign_self — the finale 🎀 one takes an hx509_cert signer, the other an hx509_private_key signer, and both hand you back an hx509_cert *certificate

heads up bestie: the names of these functions are not the whole story, and this page doesn't spill the details on them right here — the descriptions and examples live over in the Hx509 CA functions, so don't be out here guessing at behavior from a function name alone 🙈

---

🫶 Detailed Description 🫶

See the Hx509 CA functions for description and examples.

that's it, that's the whole section, no crumbs left 😭 and lowkey that's the whole point — this page is the index of the squad, and the actual lore drops in the CA functions doc. we're just getting started tho, so don't go anywhere 🌈

🔥 FUNCTION DOCUMENTATION 🔥

ok bestie, this is the part where we meet the actual functions 💖 every single one of them, no skips, no cuts. buckle up 🎀

---

hx509_ca_sign()

int hx509_ca_sign (hx509_context context, hx509_ca_tbs tbs,
    hx509_cert signer, hx509_cert * certificate)

Signs a to-be-signed certificate object with an issuer certificate. like stamping your whole vibe with a CA seal of approval ✨

The caller needs to at least have called the following functions on the to-be-signed certificate object:

• hx509_ca_tbs_init()
• hx509_ca_tbs_set_subject()
• hx509_ca_tbs_set_spki()

When done, the to-be-signed certificate object should be freed with hx509_ca_tbs_free(). 🧹

When creating a self-signed certificate, use hx509_ca_sign_self() instead. not optional, bestie — different function for that 💅

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• signer — the CA certificate object to sign with (need private key). 🔑
• certificate — return cerificate, free with hx509_cert_free().

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_sign_self()

int hx509_ca_sign_self (hx509_context context, hx509_ca_tbs tbs,
    hx509_private_key signer, hx509_cert * certificate)

Works just like hx509_ca_sign() but signs it-self. main character energy, signing your own certificate 💅 ✨

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• signer — private key to sign with. 🔑
• certificate — return cerificate, free with hx509_cert_free().

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_crl_dp_uri()

int hx509_ca_tbs_add_crl_dp_uri (hx509_context context, hx509_ca_tbs tbs,
    const char * uri, hx509_name issuername)

Adds a CRL distribution point URI to the to-be-signed certificate object. 🦋

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• uri — uri to the CRL.
• issuername — name of the issuer.

Returns

An hx509 error code, see hx509_get_error_string().

heads up bestie: issuername not supported 💀 so don't go relying on that one.

---

hx509_ca_tbs_add_eku()

int hx509_ca_tbs_add_eku (hx509_context context, hx509_ca_tbs tbs,
    const heim_oid * oid)

Adds an extended key usage to the to-be-signed certificate object. Duplicates will be detected and not added. so don't worry about accidentally double-dipping, it clocks it 👑

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• oid — extended key usage to add.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_san_hostname()

int hx509_ca_tbs_add_san_hostname (hx509_context context, hx509_ca_tbs tbs,
    const char * dnsname)

Adds a Subject Alternative Name hostname to the to-be-signed certificate object. A domain match starts with ., an exact match does not. 🎀

Example of a domain match: .domain.se matches the hostname host.domain.se. see the lil dot? that's the whole difference, iykyk ✨

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• dnsname — a hostame.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_san_jid()

int hx509_ca_tbs_add_san_jid (hx509_context context, hx509_ca_tbs tbs,
    const char * jid)

Adds a Jabber/XMPP jid Subject Alternative Name to the to-be-signed certificate object. The jid is an UTF8 string. 💬

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• jid — string of an a jabber id in UTF8.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_san_ms_upn()

int hx509_ca_tbs_add_san_ms_upn (hx509_context context, hx509_ca_tbs tbs,
    const char * principal)

Adds a Microsoft UPN Subject Alternative Name to the to-be-signed certificate object. The principal string is a UTF8 string. 🪟

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• principal — Microsoft UPN string.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_san_otherName()

int hx509_ca_tbs_add_san_otherName (hx509_context context, hx509_ca_tbs tbs,
    const heim_oid * oid, const heim_octet_string * os)

Adds a Subject Alternative Name otherName to the to-be-signed certificate object. 🌈 the catch-all slot fr fr

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• oid — the oid of the OtherName.
• os — data in the other name.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_san_pkinit()

int hx509_ca_tbs_add_san_pkinit (hx509_context context, hx509_ca_tbs tbs,
    const char * principal)

Adds a Kerberos Subject Alternative Name to the to-be-signed certificate object. The principal string is a UTF8 string. 🎭

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• principal — Kerberos principal to add to the certificate.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_add_san_rfc822name()

int hx509_ca_tbs_add_san_rfc822name (hx509_context context, hx509_ca_tbs tbs,
    const char * rfc822Name)

Adds a Subject Alternative Name rfc822 (email address) to the to-be-signed certificate object. 📧 yes bestie, the certificate gets an email addy

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• rfc822Name — a string to a email address.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_free()

void hx509_ca_tbs_free (hx509_ca_tbs * tbs)

Frees a To Be Signed object. clean up after yourself, bestie 🧚

Parameters

• tbs — object to free.

---

hx509_ca_tbs_init()

int hx509_ca_tbs_init (hx509_context context, hx509_ca_tbs * tbs)

Allocates a to-be-signed certificate object that will be converted into a certificate. this is the glow-up starting point ✨

Parameters

• context — A hx509 context.
• tbs — returned to-be-signed certicate object, free with hx509_ca_tbs_free().

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_ca()

int hx509_ca_tbs_set_ca (hx509_context context, hx509_ca_tbs tbs,
    int pathLenConstraint)

Makes the to-be-signed certificate object a CA certificate. If the pathLenConstraint is negative, no path length constraint is used. 👑

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• pathLenConstraint — path length constraint, negative, no constraint.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_domaincontroller()

int hx509_ca_tbs_set_domaincontroller (hx509_context context,
    hx509_ca_tbs tbs)

Makes the to-be-signed certificate object a windows domain controller certificate. 🪟💻

Parameters

• context — A hx509 context.
• tbs — object to be signed.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_notAfter()

int hx509_ca_tbs_set_notAfter (hx509_context context, hx509_ca_tbs tbs,
    time_t t)

Sets the absolute time when the certificate is valid to. ⏰ the expiry date, bestie, put it on your calendar

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• t — time when the certificate will expire

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_notAfter_lifetime()

int hx509_ca_tbs_set_notAfter_lifetime (hx509_context context,
    hx509_ca_tbs tbs, time_t delta)

Sets the relative time when the certificiate is going to expire. ⏳ relative, not absolute — big difference bestie

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• delta — seconds to the certificate is going to expire.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_notBefore()

int hx509_ca_tbs_set_notBefore (hx509_context context, hx509_ca_tbs tbs,
    time_t t)

Sets the absolute time when the certificate is valid from. If not set, the current time will be used. 🌅 default is literally right now

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• t — time the certificated will start to be valid

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_proxy()

int hx509_ca_tbs_set_proxy (hx509_context context, hx509_ca_tbs tbs,
    int pathLenConstraint)

Makes the to-be-signed certificate object a proxy certificate. If the pathLenConstraint is negative, no path length constraint is used. 🕶️

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• pathLenConstraint — path length constraint, negative, no constraint.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_serialnumber()

int hx509_ca_tbs_set_serialnumber (hx509_context context, hx509_ca_tbs tbs,
    const heim_integer * serialNumber)

Sets the serial number to use for the to-be-signed certificate object. 🔢

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• serialNumber — serial number to use for the to-be-signed certificate object.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_signature_algorithm()

int hx509_ca_tbs_set_signature_algorithm (hx509_context context,
    hx509_ca_tbs tbs, const AlgorithmIdentifier * sigalg)

Sets the signature algorithm on the to be signed certificate. ✍️

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• sigalg — signature algorithm to use

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_spki()

int hx509_ca_tbs_set_spki (hx509_context context, hx509_ca_tbs tbs,
    const SubjectPublicKeyInfo * spki)

Sets the subject public key info (SPKI) in the to-be-signed certificate object. SPKI is the public key and key related parameters in the certificate. 🔑✨ the whole point of the cert honestly

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• spki — subject public key info to use for the to-be-signed certificate object.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_subject()

int hx509_ca_tbs_set_subject (hx509_context context, hx509_ca_tbs tbs,
    hx509_name subject)

Sets the subject name of a to-be-signed certificate object. 🏷️ who's this cert for, bestie

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• subject — the name to set a subject.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_template()

int hx509_ca_tbs_set_template (hx509_context context, hx509_ca_tbs tbs,
    int flags, hx509_cert cert)

Initializes the to-be-signed certificate object from a template certifiate. 🧬 copy-paste but make it cryptographic

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• flags — bit field selecting what to copy from the template certifiate.
• cert — template certificate.

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_set_unique()

int hx509_ca_tbs_set_unique (hx509_context context, hx509_ca_tbs tbs,
    const heim_bit_string * subjectUniqueID,
    const heim_bit_string * issuerUniqueID)

Sets the issuerUniqueID and subjectUniqueID. 🆔

These are only supposed to be used considered with version 2 certificates, replaced by the two extensions SubjectKeyIdentifier and IssuerKeyIdentifier. This function is to allow applications using legacy protocol to issue them.

fr fr read this one: these are legacy territory — the modern world moved on to SubjectKeyIdentifier and IssuerKeyIdentifier. this exists purely so apps speaking old protocols can still issue them. don't reach for it unless you actually have to 💀

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• issuerUniqueID — to be set
• subjectUniqueID — to be set

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_subject_expand()

int hx509_ca_tbs_subject_expand (hx509_context context, hx509_ca_tbs tbs,
    hx509_env env)

Expands the the subject name in the to-be-signed certificate object using hx509_name_expand(). 🌸 variable substitution, but for your DN

Parameters

• context — A hx509 context.
• tbs — object to be signed.
• env — environment variable to expand variables in the subject name, see hx509_env_init().

Returns

An hx509 error code, see hx509_get_error_string().

---

hx509_ca_tbs_template_units()

const struct units* hx509_ca_tbs_template_units (void)

Make of template units, use to build the flags argument to hx509_ca_tbs_set_template() with parse_units(). 🧩

Returns

an units structure.

---

👑 Author 👑

okay so bestie, plot twist: no human wrote this 💅

This whole page was generated automatically by Doxygen for the Heimdal x509 library, straight up pulled from the source code. So like… nobody's out here taking credit for the prose, the computer just did its little thing and we love that for it. 🤖✨

No cap, that means if something in here looks a lil quirky, it's because the source code said so, not because some author had main character energy. The docs and the code are basically holding hands fr fr. 🫶

---

🌸 the sign-off 🌸

So this iconic lil manual page is hx509_ca(3), living in Version 7.8.0, and it was born way back on Tue Nov 15 2022 — a true vintage queen, honestly. 🎀

That's the whole vibe, bestie. Go read the source, go call the functions, go slay. 💖🦋⭐