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 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/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 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 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
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
(), except 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 returns TRUE
is they
are the same, and FALSE
if not.
krb5_principal_match
() matches a
principal against a
pattern. The pattern 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
replacements for 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.
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 default 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_425_conv_principal(3), 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.May 1, 2006 | HEIMDAL |