FreeBSD Manual Pages
KRB5_PRINCIPAL(3) Library Functions Manual KRB5_PRINCIPAL(3) NAME krb5_get_default_principal, krb5_principal, krb5_build_principal, krb5_build_principal_ext, krb5_build_principal_va, krb5_build_principal_va_ext, krb5_copy_principal, krb5_free_principal, krb5_make_principal, krb5_parse_name, krb5_parse_name_flags, krb5_parse_nametype, krb5_princ_set_realm, krb5_principal_compare, krb5_principal_compare_any_realm, krb5_principal_get_comp_string, krb5_principal_get_realm, krb5_principal_get_type, krb5_principal_match, krb5_principal_set_type, krb5_realm_compare, krb5_sname_to_principal, krb5_sock_to_principal, krb5_unparse_name, krb5_unparse_name_flags, krb5_unparse_name_fixed, krb5_unparse_name_fixed_flags, krb5_unparse_name_fixed_short, krb5_unparse_name_short -- Kerberos 5 principal handling functions LIBRARY Kerberos 5 Library (libkrb5, -lkrb5) SYNOPSIS #include <krb5.h> krb5_principal; void krb5_free_principal(krb5_context context, krb5_principal principal); krb5_error_code krb5_parse_name(krb5_context context, const char *name, krb5_principal *principal); krb5_error_code krb5_parse_name_flags(krb5_context context, const char *name, int flags, krb5_principal *principal); krb5_error_code krb5_unparse_name(krb5_context context, krb5_const_principal principal, char **name); krb5_error_code krb5_unparse_name_flags(krb5_context context, krb5_const_principal principal, int flags, char **name); krb5_error_code krb5_unparse_name_fixed(krb5_context context, krb5_const_principal principal, char *name, size_t len); krb5_error_code krb5_unparse_name_fixed_flags(krb5_context context, krb5_const_principal principal, int flags, char *name, size_t len); krb5_error_code krb5_unparse_name_short(krb5_context context, krb5_const_principal principal, char **name); krb5_error_code krb5_unparse_name_fixed_short(krb5_context context, krb5_const_principal principal, char *name, size_t len); void krb5_princ_set_realm(krb5_context context, krb5_principal principal, krb5_realm *realm); krb5_error_code krb5_build_principal(krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, ...); krb5_error_code krb5_build_principal_va(krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, va_list ap); krb5_error_code krb5_build_principal_ext(krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, ...); krb5_error_code krb5_build_principal_va_ext(krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm, va_list ap); krb5_error_code krb5_make_principal(krb5_context context, krb5_principal *principal, krb5_const_realm realm, ...); krb5_error_code krb5_copy_principal(krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc); krb5_boolean krb5_principal_compare(krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2); krb5_boolean krb5_principal_compare_any_realm(krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2); const char * krb5_principal_get_comp_string(krb5_context context, krb5_const_principal principal, unsigned int component); const char * krb5_principal_get_realm(krb5_context context, krb5_const_principal principal); int krb5_principal_get_type(krb5_context context, krb5_const_principal principal); krb5_boolean krb5_principal_match(krb5_context context, krb5_const_principal principal, krb5_const_principal pattern); void krb5_principal_set_type(krb5_context context, krb5_principal principal, int type); krb5_boolean krb5_realm_compare(krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2); krb5_error_code krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname, int32_t type, krb5_principal *ret_princ); krb5_error_code krb5_sock_to_principal(krb5_context context, int socket, const char *sname, int32_t type, krb5_principal *principal); krb5_error_code krb5_get_default_principal(krb5_context context, krb5_principal *princ); krb5_error_code krb5_parse_nametype(krb5_context context, const char *str, int32_t *type); DESCRIPTION krb5_principal holds the name of a user or service in Kerberos. A principal has two parts, a PrincipalName and a realm. The Principal- Name consists of one or more components. In printed form, the compo- nents are separated by /. The PrincipalName also has a name-type. Examples of a principal are nisse/root@EXAMPLE.COM and host/datan.kth.se@KTH.SE. krb5_parse_name() and krb5_parse_name_flags() passes a principal name in name to the kerberos principal structure. krb5_parse_name_flags() takes an extra flags ar- gument 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 principal return argument. KRB5_PRINCIPAL_PARSE_REQUIRE_REALM requires the input string to with a realm. krb5_unparse_name() and krb5_unparse_name_flags() prints the principal princ to the string name. name should be freed with free(3). To the 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 name is set to NULL. krb5_unparse_name_fixed() and krb5_unparse_name_fixed_flags() behaves just like krb5_unparse(), but instead unparses the principal into a fixed size buffer. 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. krb5_unparse_name_fixed_short() works just like krb5_unparse_name_short() but on a fixed size buffer. krb5_build_principal() builds a principal from the realm realm that has the length rlen. The following arguments form the components of the principal. The list of components is terminated with NULL. krb5_build_principal_va() works like krb5_build_principal() using vargs. krb5_build_principal_ext() and krb5_build_principal_va_ext() take a list of length-value pairs, the list is terminated with a zero length. krb5_make_principal() works the same way as krb5_build_principal(), ex- cept it figures out the length of the realm itself. krb5_copy_principal() makes a copy of a principal. The copy needs to be freed with krb5_free_principal(). krb5_principal_compare() compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not. krb5_principal_compare_any_realm() works the same way as krb5_principal_compare() but doesn't compare the realm component of the principal. krb5_realm_compare() compares the realms of the two principals and re- turns TRUE is they are the same, and FALSE if not. krb5_principal_match() matches a principal against a pattern. The pat- tern is a globbing expression, where each component (separated by /) is matched against the corresponding component of the principal. The krb5_principal_get_realm() and krb5_principal_get_comp_string() functions return parts of the 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 component argument to 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. krb5_principal_get_realm() and krb5_principal_get_comp_string() are re- placements for krb5_princ_component() and related macros, described as internal in the MIT API specification. Unlike the macros, these func- tions 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 prin- cipal 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. krb5_principal_get_type() and 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. krb5_sname_to_principal() and 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 sname parameter will be used for the first component of the created principal. If sname is NULL, "host" will be used instead. krb5_sname_to_principal() will use the passed hostname for the second component. If type is KRB5_NT_SRV_HST this name will be looked up with gethostbyname(). If hostname is NULL, the local hostname will be used. krb5_sock_to_principal() will use the "sockname" of the passed 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. krb5_get_default_principal() tries to find out what's a reasonable de- fault principal by looking at the environment it is running in. krb5_parse_nametype() parses and returns the name type integer value in type. On failure the function returns an error code and set the error string. SEE ALSO krb5_config(3), krb5.conf(5) BUGS You can not have a NUL in a component in some of the variable argument functions above. Until someone can give a good example of where it would be a good idea to have NUL's in a component, this will not be fixed. HEIMDAL May 1, 2006 KRB5_PRINCIPAL(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=krb5_principal_get_comp_string&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>