Heimdal Kerberos 5 principal functions(3)

NAME
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_error_code KRB5_LIB_FUNCTION 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_error_code krb5_parse_nametype (krb5_context context, const char *str, int32_t *nametype)
krb5_boolean 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_error_code KRB5_LIB_FUNCTION 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_error_code 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_boolean 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().