HeimdalKerberos5library: Heimdal Kerberos 5 principal 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_sname_to_principal (krb5_context context, const char *hostname, const char *sname, int32_t type, krb5_principal *ret_princ)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL | krb5_parse_nametype (krb5_context context, const char *str, int32_t *nametype)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL | krb5_principal_is_krbtgt (krb5_context context, krb5_const_principal p)

## Detailed Description

## Function Documentation

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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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 service running on hostname. If KRB5_NT_SRV_HST is used, the hostname is canonization using DNS (or some other service), this is potentially insecure.

Parameters:

  | context | A Kerberos context.
  | hostname | hostname to use
  | sname | Service name to use
  | type | name type of pricipal, 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_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_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_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_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_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_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().