Functions
Heimdal Kerberos 5 principal functions

## Functions
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

## 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

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

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().

## ◆ 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

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

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.

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

## ◆ 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)

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.

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

## ◆ 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

## ◆ 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

## ◆ 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
| ) |  |

Set a new realm for a principal, and as a side-effect free the previous realm.

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

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

return TRUE iff realm(princ1) == realm(princ2)

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

## ◆ 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

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

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.

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.

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

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().