LIBRARY

SYNOPSIS

krb5_principal Ft void Fn krb5_free_principal krb5_context context krb5_principal principal Ft krb5_error_code Fn krb5_parse_name krb5_context context const char *name krb5_principal *principal Ft krb5_error_code Fn krb5_parse_name_flags krb5_context context const char *name int flags krb5_principal *principal Ft krb5_error_code Fn krb5_unparse_name krb5_context context krb5_const_principal principal char **name Ft krb5_error_code Fn krb5_unparse_name_flags krb5_context context krb5_const_principal principal int flags char **name Ft krb5_error_code Fn krb5_unparse_name_fixed krb5_context context krb5_const_principal principal char *name size_t len Ft krb5_error_code Fn krb5_unparse_name_fixed_flags krb5_context context krb5_const_principal principal int flags char *name size_t len Ft krb5_error_code Fn krb5_unparse_name_short krb5_context context krb5_const_principal principal char **name Ft krb5_error_code Fn krb5_unparse_name_fixed_short krb5_context context krb5_const_principal principal char *name size_t len Ft void Fn krb5_princ_set_realm krb5_context context krb5_principal principal krb5_realm *realm Ft krb5_error_code Fn krb5_build_principal krb5_context context krb5_principal *principal int rlen krb5_const_realm realm ... Ft krb5_error_code Fn krb5_build_principal_va krb5_context context krb5_principal *principal int rlen krb5_const_realm realm va_list ap Ft krb5_error_code Fn krb5_build_principal_ext krb5_context context krb5_principal *principal int rlen krb5_const_realm realm ... Ft krb5_error_code Fn krb5_build_principal_va_ext krb5_context context krb5_principal *principal int rlen krb5_const_realm realm va_list ap Ft krb5_error_code Fn krb5_make_principal krb5_context context krb5_principal *principal krb5_const_realm realm ... Ft krb5_error_code Fn krb5_copy_principal krb5_context context krb5_const_principal inprinc krb5_principal *outprinc Ft krb5_boolean Fn krb5_principal_compare krb5_context context krb5_const_principal princ1 krb5_const_principal princ2 Ft krb5_boolean Fn krb5_principal_compare_any_realm krb5_context context krb5_const_principal princ1 krb5_const_principal princ2 Ft const char * Fn krb5_principal_get_comp_string krb5_context context krb5_const_principal principal unsigned int component Ft const char * Fn krb5_principal_get_realm krb5_context context krb5_const_principal principal Ft int Fn krb5_principal_get_type krb5_context context krb5_const_principal principal Ft krb5_boolean Fn krb5_principal_match krb5_context context krb5_const_principal principal krb5_const_principal pattern Ft void Fn krb5_principal_set_type krb5_context context krb5_principal principal int type Ft krb5_boolean Fn krb5_realm_compare krb5_context context krb5_const_principal princ1 krb5_const_principal princ2 Ft krb5_error_code Fn krb5_sname_to_principal krb5_context context const char *hostname const char *sname int32_t type krb5_principal *ret_princ Ft krb5_error_code Fn krb5_sock_to_principal krb5_context context int socket const char *sname int32_t type krb5_principal *principal Ft krb5_error_code Fn krb5_get_default_principal krb5_context context krb5_principal *princ Ft krb5_error_code Fn krb5_parse_nametype krb5_context context const char *str int32_t *type

DESCRIPTION

A principal has two parts, a PrincipalName and a realm The PrincipalName consists of one or more components. In printed form, the components are separated by /. The PrincipalName also has a name-type.

Examples of a principal are nisse/[email protected] and host/[email protected] Fn krb5_parse_name and Fn krb5_parse_name_flags passes a principal name in Fa name to the kerberos principal structure. Fn krb5_parse_name_flags takes an extra Fa flags argument the following flags can be passed in

KRB5_PRINCIPAL_PARSE_NO_REALM

requires the input string to be without a realm, and no realm is stored in the Fa principal return argument.

KRB5_PRINCIPAL_PARSE_REQUIRE_REALM

requires the input string to with a realm.

Fn krb5_unparse_name and Fn krb5_unparse_name_flags prints the principal Fa princ to the string Fa name . Fa name should be freed with free(3). To the Fa flags argument the following flags can be passed in

KRB5_PRINCIPAL_UNPARSE_SHORT

no realm if the realm is one of the local realms.

KRB5_PRINCIPAL_UNPARSE_NO_REALM

never include any realm in the principal name.

KRB5_PRINCIPAL_UNPARSE_DISPLAY

don't quote

On failure Fa name is set to NULL Fn krb5_unparse_name_fixed and Fn krb5_unparse_name_fixed_flags behaves just like Fn krb5_unparse , but instead unparses the principal into a fixed size buffer.

Fn krb5_unparse_name_short just returns the principal without the realm if the principal is in the default realm. If the principal isn't, the full name is returned. Fn krb5_unparse_name_fixed_short works just like Fn krb5_unparse_name_short but on a fixed size buffer.

Fn krb5_build_principal builds a principal from the realm Fa realm that has the length Fa rlen . The following arguments form the components of the principal. The list of components is terminated with NULL

Fn krb5_build_principal_va works like Fn krb5_build_principal using vargs.

Fn krb5_build_principal_ext and Fn krb5_build_principal_va_ext take a list of length-value pairs, the list is terminated with a zero length.

Fn krb5_make_principal works the same way as Fn krb5_build_principal , except it figures out the length of the realm itself.

Fn krb5_copy_principal makes a copy of a principal. The copy needs to be freed with Fn krb5_free_principal .

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

Fn krb5_principal_compare_any_realm works the same way as Fn krb5_principal_compare but doesn't compare the realm component of the principal.

Fn krb5_realm_compare compares the realms of the two principals and returns TRUE is they are the same, and FALSE if not.

Fn krb5_principal_match matches a Fa principal against a Fa pattern . The pattern is a globbing expression, where each component (separated by /) is matched against the corresponding component of the principal.

The Fn krb5_principal_get_realm and Fn krb5_principal_get_comp_string functions return parts of the Fa principal , either the realm or a specific component. Both functions return string pointers to data inside the principal, so they are valid only as long as the principal exists.

The Fa component argument to Fn krb5_principal_get_comp_string is the index of the component to return, from zero to the total number of components minus one. If the index is out of range NULL is returned.

Fn krb5_principal_get_realm and Fn krb5_principal_get_comp_string are replacements for Fn krb5_princ_component and related macros, described as internal in the MIT API specification. Unlike the macros, these functions return strings, not krb5_data A reason to return krb5_data was that it was believed that principal components could contain binary data, but this belief was unfounded, and it has been decided that principal components are infact UTF8, so it's safe to use zero terminated strings.

It's generally not necessary to look at the components of a principal.

Fn krb5_principal_get_type and Fn krb5_principal_set_type get and sets the name type for a principal. Name type handling is tricky and not often needed, don't use this unless you know what you do.

Fn krb5_sname_to_principal and Fn krb5_sock_to_principal are for easy creation of ``service'' principals that can, for instance, be used to lookup a key in a keytab. For both functions the Fa sname parameter will be used for the first component of the created principal. If Fa sname is NULL ``host'' will be used instead.

Fn krb5_sname_to_principal will use the passed Fa hostname for the second component. If Fa type is KRB5_NT_SRV_HST this name will be looked up with Fn gethostbyname . If Fa hostname is NULL the local hostname will be used.

Fn krb5_sock_to_principal will use the ``sockname'' of the passed Fa socket , which should be a bound AF_INET or AF_INET6 socket. There must be a mapping between the address and ``sockname'' The function may try to resolve the name in DNS.

Fn krb5_get_default_principal tries to find out what's a reasonable default principal by looking at the environment it is running in.

Fn krb5_parse_nametype parses and returns the name type integer value in Fa type . On failure the function returns an error code and set the error string.