| KRB5_PRINCIPAL(3) | Library Functions Manual | KRB5_PRINCIPAL(3) | 
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 —
#include <krb5/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);
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_REALMKRB5_PRINCIPAL_PARSE_REQUIRE_REALMkrb5_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_SHORTKRB5_PRINCIPAL_UNPARSE_NO_REALMKRB5_PRINCIPAL_UNPARSE_DISPLAYNULL.
  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.
| May 1, 2006 | NetBSD 9.3 |