KRB5_PRINCIPAL(3)        BSD Library Functions Manual        KRB5_PRINCIPAL(3)

NNAAMMEE
     kkrrbb55__ggeett__ddeeffaauulltt__pprriinncciippaall, kkrrbb55__pprriinncciippaall, kkrrbb55__bbuuiilldd__pprriinncciippaall,
     kkrrbb55__bbuuiilldd__pprriinncciippaall__eexxtt, kkrrbb55__bbuuiilldd__pprriinncciippaall__vvaa,
     kkrrbb55__bbuuiilldd__pprriinncciippaall__vvaa__eexxtt, kkrrbb55__ccooppyy__pprriinncciippaall, kkrrbb55__ffrreeee__pprriinncciippaall,
     kkrrbb55__mmaakkee__pprriinncciippaall, kkrrbb55__ppaarrssee__nnaammee, kkrrbb55__ppaarrssee__nnaammee__ffllaaggss,
     kkrrbb55__ppaarrssee__nnaammeettyyppee, kkrrbb55__pprriinncc__sseett__rreeaallmm, kkrrbb55__pprriinncciippaall__ccoommppaarree,
     kkrrbb55__pprriinncciippaall__ccoommppaarree__aannyy__rreeaallmm, kkrrbb55__pprriinncciippaall__ggeett__ccoommpp__ssttrriinngg,
     kkrrbb55__pprriinncciippaall__ggeett__rreeaallmm, kkrrbb55__pprriinncciippaall__ggeett__ttyyppee, kkrrbb55__pprriinncciippaall__mmaattcchh,
     kkrrbb55__pprriinncciippaall__sseett__ttyyppee, kkrrbb55__rreeaallmm__ccoommppaarree, kkrrbb55__ssnnaammee__ttoo__pprriinncciippaall,
     kkrrbb55__ssoocckk__ttoo__pprriinncciippaall, kkrrbb55__uunnppaarrssee__nnaammee, kkrrbb55__uunnppaarrssee__nnaammee__ffllaaggss,
     kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd, kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd__ffllaaggss,
     kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd__sshhoorrtt, kkrrbb55__uunnppaarrssee__nnaammee__sshhoorrtt -- Kerberos 5
     principal handling functions

LLIIBBRRAARRYY
     Kerberos 5 Library (libkrb5, -lkrb5)

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<kkrrbb55..hh>>

     krb5_principal;

     _v_o_i_d
     kkrrbb55__ffrreeee__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ppaarrssee__nnaammee(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _c_o_n_s_t _c_h_a_r _*_n_a_m_e,
         _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ppaarrssee__nnaammee__ffllaaggss(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _c_o_n_s_t _c_h_a_r _*_n_a_m_e, _i_n_t _f_l_a_g_s,
         _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__uunnppaarrssee__nnaammee(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l,
         _c_h_a_r _*_*_n_a_m_e);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__uunnppaarrssee__nnaammee__ffllaaggss(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _i_n_t _f_l_a_g_s, _c_h_a_r _*_*_n_a_m_e);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _c_h_a_r _*_n_a_m_e, _s_i_z_e___t _l_e_n);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd__ffllaaggss(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _i_n_t _f_l_a_g_s, _c_h_a_r _*_n_a_m_e, _s_i_z_e___t _l_e_n);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__uunnppaarrssee__nnaammee__sshhoorrtt(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _c_h_a_r _*_*_n_a_m_e);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd__sshhoorrtt(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _c_h_a_r _*_n_a_m_e, _s_i_z_e___t _l_e_n);

     _v_o_i_d
     kkrrbb55__pprriinncc__sseett__rreeaallmm(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l,
         _k_r_b_5___r_e_a_l_m _*_r_e_a_l_m);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__bbuuiilldd__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l,
         _i_n_t _r_l_e_n, _k_r_b_5___c_o_n_s_t___r_e_a_l_m _r_e_a_l_m, _._._.);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__bbuuiilldd__pprriinncciippaall__vvaa(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l,
         _i_n_t _r_l_e_n, _k_r_b_5___c_o_n_s_t___r_e_a_l_m _r_e_a_l_m, _v_a___l_i_s_t _a_p);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__bbuuiilldd__pprriinncciippaall__eexxtt(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l,
         _i_n_t _r_l_e_n, _k_r_b_5___c_o_n_s_t___r_e_a_l_m _r_e_a_l_m, _._._.);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__bbuuiilldd__pprriinncciippaall__vvaa__eexxtt(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l, _i_n_t _r_l_e_n, _k_r_b_5___c_o_n_s_t___r_e_a_l_m _r_e_a_l_m,
         _v_a___l_i_s_t _a_p);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__mmaakkee__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l,
         _k_r_b_5___c_o_n_s_t___r_e_a_l_m _r_e_a_l_m, _._._.);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ccooppyy__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _i_n_p_r_i_n_c,
         _k_r_b_5___p_r_i_n_c_i_p_a_l _*_o_u_t_p_r_i_n_c);

     _k_r_b_5___b_o_o_l_e_a_n
     kkrrbb55__pprriinncciippaall__ccoommppaarree(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_1,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_2);

     _k_r_b_5___b_o_o_l_e_a_n
     kkrrbb55__pprriinncciippaall__ccoommppaarree__aannyy__rreeaallmm(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_1, _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_2);

     _c_o_n_s_t _c_h_a_r _*
     kkrrbb55__pprriinncciippaall__ggeett__ccoommpp__ssttrriinngg(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _u_n_s_i_g_n_e_d _i_n_t _c_o_m_p_o_n_e_n_t);

     _c_o_n_s_t _c_h_a_r _*
     kkrrbb55__pprriinncciippaall__ggeett__rreeaallmm(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l);

     _i_n_t
     kkrrbb55__pprriinncciippaall__ggeett__ttyyppee(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l);

     _k_r_b_5___b_o_o_l_e_a_n
     kkrrbb55__pprriinncciippaall__mmaattcchh(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l, _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_a_t_t_e_r_n);

     _v_o_i_d
     kkrrbb55__pprriinncciippaall__sseett__ttyyppee(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _p_r_i_n_c_i_p_a_l,
         _i_n_t _t_y_p_e);

     _k_r_b_5___b_o_o_l_e_a_n
     kkrrbb55__rreeaallmm__ccoommppaarree(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_1,
         _k_r_b_5___c_o_n_s_t___p_r_i_n_c_i_p_a_l _p_r_i_n_c_2);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ssnnaammee__ttoo__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _c_o_n_s_t _c_h_a_r _*_h_o_s_t_n_a_m_e,
         _c_o_n_s_t _c_h_a_r _*_s_n_a_m_e, _i_n_t_3_2___t _t_y_p_e, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_r_e_t___p_r_i_n_c);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ssoocckk__ttoo__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _i_n_t _s_o_c_k_e_t,
         _c_o_n_s_t _c_h_a_r _*_s_n_a_m_e, _i_n_t_3_2___t _t_y_p_e, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c_i_p_a_l);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ggeett__ddeeffaauulltt__pprriinncciippaall(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _k_r_b_5___p_r_i_n_c_i_p_a_l _*_p_r_i_n_c);

     _k_r_b_5___e_r_r_o_r___c_o_d_e
     kkrrbb55__ppaarrssee__nnaammeettyyppee(_k_r_b_5___c_o_n_t_e_x_t _c_o_n_t_e_x_t, _c_o_n_s_t _c_h_a_r _*_s_t_r,
         _i_n_t_3_2___t _*_t_y_p_e);

DDEESSCCRRIIPPTTIIOONN
     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 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.  kkrrbb55__ppaarrssee__nnaammee() and kkrrbb55__ppaarrssee__nnaammee__ffllaaggss()
     passes a principal name in _n_a_m_e to the kerberos principal structure.
     kkrrbb55__ppaarrssee__nnaammee__ffllaaggss() takes an extra _f_l_a_g_s 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 _p_r_i_n_c_i_p_a_l return argument.

     KRB5_PRINCIPAL_PARSE_REQUIRE_REALM
             requires the input string to with a realm.

     kkrrbb55__uunnppaarrssee__nnaammee() and kkrrbb55__uunnppaarrssee__nnaammee__ffllaaggss() prints the principal
     _p_r_i_n_c to the string _n_a_m_e.  _n_a_m_e should be freed with free(3).  To the
     _f_l_a_g_s 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 _n_a_m_e is set to NULL.  kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd() and
     kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd__ffllaaggss() behaves just like kkrrbb55__uunnppaarrssee(), but
     instead unparses the principal into a fixed size buffer.

     kkrrbb55__uunnppaarrssee__nnaammee__sshhoorrtt() 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.  kkrrbb55__uunnppaarrssee__nnaammee__ffiixxeedd__sshhoorrtt() works just like
     kkrrbb55__uunnppaarrssee__nnaammee__sshhoorrtt() but on a fixed size buffer.

     kkrrbb55__bbuuiilldd__pprriinncciippaall() builds a principal from the realm _r_e_a_l_m that has
     the length _r_l_e_n.  The following arguments form the components of the
     principal.  The list of components is terminated with NULL.

     kkrrbb55__bbuuiilldd__pprriinncciippaall__vvaa() works like kkrrbb55__bbuuiilldd__pprriinncciippaall() using vargs.

     kkrrbb55__bbuuiilldd__pprriinncciippaall__eexxtt() and kkrrbb55__bbuuiilldd__pprriinncciippaall__vvaa__eexxtt() take a list
     of length-value pairs, the list is terminated with a zero length.

     kkrrbb55__mmaakkee__pprriinncciippaall() works the same way as kkrrbb55__bbuuiilldd__pprriinncciippaall(),
     except it figures out the length of the realm itself.

     kkrrbb55__ccooppyy__pprriinncciippaall() makes a copy of a principal.  The copy needs to be
     freed with kkrrbb55__ffrreeee__pprriinncciippaall().

     kkrrbb55__pprriinncciippaall__ccoommppaarree() compares the two principals, including realm of
     the principals and returns TRUE if they are the same and FALSE if not.

     kkrrbb55__pprriinncciippaall__ccoommppaarree__aannyy__rreeaallmm() works the same way as
     kkrrbb55__pprriinncciippaall__ccoommppaarree() but doesn't compare the realm component of the
     principal.

     kkrrbb55__rreeaallmm__ccoommppaarree() compares the realms of the two principals and
     returns TRUE is they are the same, and FALSE if not.

     kkrrbb55__pprriinncciippaall__mmaattcchh() matches a _p_r_i_n_c_i_p_a_l against a _p_a_t_t_e_r_n.  The pat-
     tern is a globbing expression, where each component (separated by /) is
     matched against the corresponding component of the principal.

     The kkrrbb55__pprriinncciippaall__ggeett__rreeaallmm() and kkrrbb55__pprriinncciippaall__ggeett__ccoommpp__ssttrriinngg() func-
     tions return parts of the _p_r_i_n_c_i_p_a_l, either the realm or a specific com-
     ponent.  Both functions return string pointers to data inside the princi-
     pal, so they are valid only as long as the principal exists.

     The _c_o_m_p_o_n_e_n_t argument to kkrrbb55__pprriinncciippaall__ggeett__ccoommpp__ssttrriinngg() 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.

     kkrrbb55__pprriinncciippaall__ggeett__rreeaallmm() and kkrrbb55__pprriinncciippaall__ggeett__ccoommpp__ssttrriinngg() are
     replacements for kkrrbb55__pprriinncc__ccoommppoonneenntt() 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 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.

     kkrrbb55__pprriinncciippaall__ggeett__ttyyppee() and kkrrbb55__pprriinncciippaall__sseett__ttyyppee() 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.

     kkrrbb55__ssnnaammee__ttoo__pprriinncciippaall() and kkrrbb55__ssoocckk__ttoo__pprriinncciippaall() are for easy cre-
     ation of ``service'' principals that can, for instance, be used to lookup
     a key in a keytab.  For both functions the _s_n_a_m_e parameter will be used
     for the first component of the created principal.  If _s_n_a_m_e is NULL,
     ``host'' will be used instead.

     kkrrbb55__ssnnaammee__ttoo__pprriinncciippaall() will use the passed _h_o_s_t_n_a_m_e for the second
     component.  If _t_y_p_e is KRB5_NT_SRV_HST this name will be looked up with
     ggeetthhoossttbbyynnaammee().  If _h_o_s_t_n_a_m_e is NULL, the local hostname will be used.

     kkrrbb55__ssoocckk__ttoo__pprriinncciippaall() will use the ``sockname'' of the passed _s_o_c_k_e_t,
     which should be a bound AF_INET or AF_INET6 socket.  There must be a map-
     ping between the address and ``sockname''.  The function may try to
     resolve the name in DNS.

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

     kkrrbb55__ppaarrssee__nnaammeettyyppee() parses and returns the name type integer value in
     _t_y_p_e.  On failure the function returns an error code and set the error
     string.

SSEEEE AALLSSOO
     krb5_config(3), krb5.conf(5)

BBUUGGSS
     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                          HEIMDAL