krb5_principal(3)

🌸 NAME 🌸

okay bestie, so you've opened krb5_principal(3) — that's the Heimdal Kerberos 5 library page for the Heimdal Kerberos 5 principal functions. it's giving "the entire principal system, laid out for you," and yes it's long, but we're doing this together. 💅

---

✨ SYNOPSIS ✨

🫶 Functions 🫶

here's the whole lineup, exactly as written, no cap:

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal (krb5_context context, krb5_principal p)
KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type (krb5_context context, krb5_principal principal, int type)
KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL krb5_principal_get_realm (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name_flags (krb5_context context, const char *name, int flags, krb5_principal *principal)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name (krb5_context context, const char *name, krb5_principal *principal)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed (krb5_context context, krb5_const_principal principal, char *name, size_t len)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_short (krb5_context context, krb5_const_principal principal, char *name, size_t len)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_flags (krb5_context context, krb5_const_principal principal, int flags, char *name, size_t len)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name (krb5_context context, krb5_const_principal principal, char **name)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_flags (krb5_context context, krb5_const_principal principal, int flags, char **name)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short (krb5_context context, krb5_const_principal principal, char **name)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm (krb5_context context, krb5_principal principal, krb5_const_realm realm)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_build_principal (krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm,...)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal (krb5_context context, krb5_principal *principal, krb5_const_realm realm,...)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal (krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare_any_realm (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype (krb5_context context, const char *str, int32_t *nametype)
krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_null (krb5_context context, krb5_const_principal principal)
krb5_boolean KRB5_LIB_FUNCTION krb5_realm_is_lkdc (const char *realm)
krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_lkdc (krb5_context context, krb5_const_principal principal)
krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_pku2u (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt (krb5_context context, krb5_const_principal p)
krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_gss_hostbased_service (krb5_context context, krb5_const_principal principal)
krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_root_krbtgt (krb5_context context, krb5_const_principal p)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_anonymous (krb5_context context, krb5_const_principal p, unsigned int flags)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sname_to_principal (krb5_context context, const char *hostname, const char *sname, int32_t type, krb5_principal *ret_princ)

---

🦋 Detailed Description 🦋

girl, that's it. that's the whole detailed description. iconic minimalism. 💜

---

👑 Function Documentation 👑

🧸 krb5_build_principal 🧸

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_build_principal
    (krb5_context context, krb5_principal * principal, int rlen,
    krb5_const_realm realm,  ...)

Build a principal using vararg style building — yes bestie, it's a vararg moment, so bring your NULL terminator. 🎀

Parameters:

• context — A Kerberos context.
• principal — returned principal
• rlen — length of realm
• realm — realm name
• ... — a list of components ended with NULL.

Returns: An krb5 error code, see krb5_get_error_message().

---

🍓 krb5_copy_principal 🍓

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal
    (krb5_context context, krb5_const_principal inprinc, krb5_principal *
    outprinc)

Copy a principal. dupe it, but make it a real copy, not just a "we're the same person" situation. 🙈

Parameters:

• context — A Kerberos context.
• inprinc — principal to copy
• outprinc — copied principal, free with krb5_free_principal()

Returns: An krb5 error code, see krb5_get_error_message().

---

💅 krb5_free_principal 💅

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal (krb5_context
    context, krb5_principal p)

Frees a Kerberos principal allocated by the library with krb5_parse_name(), krb5_make_principal() or any other related principal functions.

Parameters:

• context — A Kerberos context.
• p — a principal to free.

Returns: An krb5 error code, see krb5_get_error_message().

not me pointing out that this one is declared void but the page still lists a Returns line saying "An krb5 error code, see krb5_get_error_message()." that's exactly what it says though, so we're keeping it fr fr. 🫶

---

🎀 krb5_make_principal 🎀

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal
    (krb5_context context, krb5_principal * principal, krb5_const_realm
    realm,  ...)

Build a principal using vararg style building — same energy as krb5_build_principal, but without the rlen guest star. ✨

Parameters:

• context — A Kerberos context.
• principal — returned principal
• realm — realm name
• ... — a list of components ended with NULL.

Returns: An krb5 error code, see krb5_get_error_message().

---

🌈 krb5_parse_name 🌈

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name
    (krb5_context context, const char * name, krb5_principal * principal)

Parse a name into a krb5_principal structure. you hand it a string, it hands you a principal, main character transformation arc. 💖

Parameters:

• context — Kerberos 5 context
• name — name to parse into a Kerberos principal
• principal — returned principal, free with krb5_free_principal().

Returns: An krb5 error code, see krb5_get_error_message().

---

🦄 krb5_parse_name_flags 🦄

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name_flags
    (krb5_context context, const char * name, int flags, krb5_principal *
    principal)

Parse a name into a krb5_principal structure, flags controls the behavior. same as above but now you get to have opinions via flags. 🔥

Parameters:

• context — Kerberos 5 context
• name — name to parse into a Kerberos principal
• flags — flags to control the behavior
• principal — returned principal, free with krb5_free_principal().

Returns: An krb5 error code, see krb5_get_error_message().

---

⭐ krb5_parse_nametype ⭐

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype
    (krb5_context context, const char * str, int32_t * nametype)

Parse nametype string and return a nametype integer. glowed up from text to int32_t, we love a numeric era. ✨

---

🫶 krb5_principal_compare 🫶

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare
    (krb5_context context, krb5_const_principal princ1, krb5_const_principal
    princ2)

Compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not.

Parameters:

• context — Kerberos 5 context
• princ1 — first principal to compare
• princ2 — second principal to compare

See also:

• krb5_principal_compare_any_realm()
• krb5_realm_compare()

---

🧚 krb5_principal_compare_any_realm 🧚

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL
    krb5_principal_compare_any_realm (krb5_context context,
    krb5_const_principal princ1, krb5_const_principal princ2)

Return TRUE iff princ1 == princ2 (without considering the realm). the realm is literally not invited to this comparison. 💀

Parameters:

• context — Kerberos 5 context
• princ1 — first principal to compare
• princ2 — second principal to compare

Returns: non zero if equal, 0 if not

See also:

• krb5_principal_compare()
• krb5_realm_compare()

---

🍓 krb5_principal_get_num_comp 🍓

KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp
    (krb5_context context, krb5_const_principal principal)

Get number of component is principal. (that's the original wording bestie, we're keeping it verbatim energy.) 🌸

Parameters:

• context — Kerberos 5 context
• principal — principal to query

Returns: number of components in string

---

💜 krb5_principal_get_realm 💜

KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_principal_get_realm
    (krb5_context context, krb5_const_principal principal)

Get the realm of the principal.

Parameters:

• context — A Kerberos context.
• principal — principal to get the realm for

Returns: realm of the principal, don't free or use after krb5_principal is freed

important!! do not free it, and do not touch it after the krb5_principal is freed. it's borrowed, bestie, hands off. 🙈

---

🦋 krb5_principal_get_type 🦋

KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type (krb5_context
    context, krb5_const_principal principal)

Get the type of the principal.

Parameters:

• context — A Kerberos context.
• principal — principal to get the type for

Returns: the type of principal

---

🌈 krb5_principal_is_anonymous 🌈

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_anonymous
    (krb5_context context, krb5_const_principal p, unsigned int flags)

Returns true iff name is WELLKNOWN/ANONYMOUS.

---

🎀 krb5_principal_is_gss_hostbased_service 🎀

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_gss_hostbased_service
    (krb5_context context, krb5_const_principal principal)

Returns true iff name is an WELLKNOWN:ORG.H5L.HOSTBASED-SERVICE.

---

🧸 krb5_principal_is_krbtgt 🧸

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt
    (krb5_context context, krb5_const_principal p)

Check if the cname part of the principal is a krbtgt principal.

---

✨ krb5_principal_is_lkdc ✨

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_lkdc (krb5_context context,
    krb5_const_principal principal)

Returns true if name is Kerberos an LKDC realm.

---

💖 krb5_principal_is_null 💖

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_null (krb5_context context,
    krb5_const_principal principal)

Returns true if name is Kerberos NULL name.

---

🦄 krb5_principal_is_pku2u 🦄

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_pku2u (krb5_context
    context, krb5_const_principal principal)

Returns true if name is Kerberos an LKDC realm.

heads up bestie — yes, this one says the exact same thing as krb5_principal_is_lkdc up there. that's the page's own wording, and we do not edit the source of truth. 🤷‍♀️

---

👑 krb5_principal_is_root_krbtgt 👑

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_root_krbtgt (krb5_context
    context, krb5_const_principal p)

Check if the cname part of the principal is a initial or renewed krbtgt principal.

---

🫶 krb5_principal_match 🫶

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match
    (krb5_context context, krb5_const_principal princ, krb5_const_principal
    pattern)

return TRUE iff princ matches pattern.

---

and that's where part 1 wraps... but bestie, we are NOT done. more parts incoming, keep scrolling energy activated. 🔥

✨ krb5_principal_set_realm ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm (krb5_context context, krb5_principal principal, krb5_const_realm realm)

Okay so this one sets a whole new realm for a principal, and as a side-effect it frees the previous realm. It's giving new realm, who dis? energy. 💅

🌸 Parameters 🌸

• context — A Kerberos context.
• principal — principal set the realm for
• realm — the new realm to set

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 🫶

---

✨ krb5_principal_set_type ✨

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type (krb5_context context, krb5_principal principal, int type)

Set the type of the principal. No cap, just assign the new type. 🎀

🌸 Parameters 🌸

• context — A Kerberos context.
• principal — principal to set the type for
• type — the new type

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 👑

---

✨ krb5_realm_compare ✨

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)

This one returns TRUE iff realm(princ1) == realm(princ2). It's literally checking if the realms match. 🦋

🌸 Parameters 🌸

• context — Kerberos 5 context
• princ1 — first principal to compare
• princ2 — second principal to compare

🦋 See also 🦋

• krb5_principal_compare_any_realm()
• krb5_principal_compare()

---

✨ krb5_realm_is_lkdc ✨

krb5_boolean KRB5_LIB_FUNCTION krb5_realm_is_lkdc (const char * realm)

Returns true if name is Kerberos an LKDC realm. (Yes, it says "name" — we're just the messengers. 🙈)

---

✨ krb5_sname_to_principal ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sname_to_principal (krb5_context context, const char * hostname, const char * sname, int32_t type, krb5_principal * ret_princ)

Create a principal for the given service running on the given hostname. If KRB5_NT_SRV_HST is used, the hostname is canonicalized according the configured name canonicalization rules, with canonicalization delayed in some cases. One rule involves DNS, which is insecure unless DNSSEC is used, but we don't use DNSSEC-capable resolver APIs here, so that if DNSSEC is used we wouldn't know it. ⚠️

Canonicalization is immediate (not delayed) only when there is only one canonicalization rule and that rule indicates that we should do a host lookup by name (i.e., DNS). ✨

🌸 Parameters 🌸

• context — A Kerberos context.
• hostname — hostname to use
• sname — Service name to use
• type — name type of principal, use KRB5_NT_SRV_HST or KRB5_NT_UNKNOWN.
• ret_princ — return principal, free with krb5_free_principal().

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 🫶

---

✨ krb5_unparse_name ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name (krb5_context context, krb5_const_principal principal, char ** name)

Unparse the Kerberos name into a string. It's the principal-to-string glow-up. 💅

🌸 Parameters 🌸

• context — Kerberos 5 context
• principal — principal to query
• name — resulting string, free with krb5_xfree()

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 👑

---

✨ krb5_unparse_name_fixed ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed (krb5_context context, krb5_const_principal principal, char * name, size_t len)

Unparse the principal name to a fixed buffer. No malloc drama, just a buffer you already own. 🎀

🌸 Parameters 🌸

• context — A Kerberos context.
• principal — principal to unparse
• name — buffer to write name to
• len — length of buffer

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 🫶

---

✨ krb5_unparse_name_fixed_flags ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_flags (krb5_context context, krb5_const_principal principal, int flags, char * name, size_t len)

Unparse the principal name with unparse flags to a fixed buffer. Same fixed-buffer vibe, but now with flags. 🦋

🌸 Parameters 🌸

• context — A Kerberos context.
• principal — principal to unparse
• flags — unparse flags
• name — buffer to write name to
• len — length of buffer

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). ✨

---

✨ krb5_unparse_name_fixed_short ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_short (krb5_context context, krb5_const_principal principal, char * name, size_t len)

Unparse the principal name to a fixed buffer. The realm is skipped if its a default realm. (Grammar? Never heard of her. 💅)

🌸 Parameters 🌸

• context — A Kerberos context.
• principal — principal to unparse
• name — buffer to write name to
• len — length of buffer

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 🫶

---

✨ krb5_unparse_name_flags ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_flags (krb5_context context, krb5_const_principal principal, int flags, char ** name)

Unparse the Kerberos name into a string. Now with flags to determine the behavior. 🔥

🌸 Parameters 🌸

• context — Kerberos 5 context
• principal — principal to query
• flags — flag to determine the behavior
• name — resulting string, free with krb5_xfree()

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 👑

---

✨ krb5_unparse_name_short ✨

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short (krb5_context context, krb5_const_principal principal, char ** name)

Unparse the principal name to a allocated buffer. The realm is skipped if its a default realm. 🎀

🌸 Parameters 🌸

• context — A Kerberos context.
• principal — principal to unparse
• name — returned buffer, free with krb5_xfree()

💖 Returns 💖

An krb5 error code, see krb5_get_error_message(). 🫶

---

👑 Author 👑

Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code. 🤖✨

---

This whole page is from Heimdal Kerberos 5 library, version 7.8.0, dated Tue Nov 15 2022, and it's krb5_principal(3). That's the tea, bestie. 💅✨