krb5_unparse_name_fixed_flags(3)

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

NAME

4     krb5_get_default_principal, krb5_principal, krb5_build_principal,
5     krb5_build_principal_ext, krb5_build_principal_va,
6     krb5_build_principal_va_ext, krb5_copy_principal, krb5_free_principal,
7     krb5_make_principal, krb5_parse_name, krb5_parse_name_flags,
8     krb5_parse_nametype, krb5_princ_set_realm, krb5_principal_compare,
9     krb5_principal_compare_any_realm, krb5_principal_get_comp_string,
10     krb5_principal_get_realm, krb5_principal_get_type, krb5_principal_match,
11     krb5_principal_set_type, krb5_realm_compare, krb5_sname_to_principal,
12     krb5_sock_to_principal, krb5_unparse_name, krb5_unparse_name_flags,
13     krb5_unparse_name_fixed, krb5_unparse_name_fixed_flags,
14     krb5_unparse_name_fixed_short, krb5_unparse_name_short — Kerberos 5 prin‐
15     cipal handling functions
16

LIBRARY

18     Kerberos 5 Library (libkrb5, -lkrb5)
19

SYNOPSIS

21     #include <krb5.h>
22
23     krb5_principal;
24
25     void
26     krb5_free_principal(krb5_context context, krb5_principal principal);
27
28     krb5_error_code
29     krb5_parse_name(krb5_context context, const char *name,
30         krb5_principal *principal);
31
32     krb5_error_code
33     krb5_parse_name_flags(krb5_context context, const char *name, int flags,
34         krb5_principal *principal);
35
36     krb5_error_code
37     krb5_unparse_name(krb5_context context, krb5_const_principal principal,
38         char **name);
39
40     krb5_error_code
41     krb5_unparse_name_flags(krb5_context context,
42         krb5_const_principal principal, int flags, char **name);
43
44     krb5_error_code
45     krb5_unparse_name_fixed(krb5_context context,
46         krb5_const_principal principal, char *name, size_t len);
47
48     krb5_error_code
49     krb5_unparse_name_fixed_flags(krb5_context context,
50         krb5_const_principal principal, int flags, char *name, size_t len);
51
52     krb5_error_code
53     krb5_unparse_name_short(krb5_context context,
54         krb5_const_principal principal, char **name);
55
56     krb5_error_code
57     krb5_unparse_name_fixed_short(krb5_context context,
58         krb5_const_principal principal, char *name, size_t len);
59
60     void
61     krb5_princ_set_realm(krb5_context context, krb5_principal principal,
62         krb5_realm *realm);
63
64     krb5_error_code
65     krb5_build_principal(krb5_context context, krb5_principal *principal,
66         int rlen, krb5_const_realm realm, ...);
67
68     krb5_error_code
69     krb5_build_principal_va(krb5_context context, krb5_principal *principal,
70         int rlen, krb5_const_realm realm, va_list ap);
71
72     krb5_error_code
73     krb5_build_principal_ext(krb5_context context, krb5_principal *principal,
74         int rlen, krb5_const_realm realm, ...);
75
76     krb5_error_code
77     krb5_build_principal_va_ext(krb5_context context,
78         krb5_principal *principal, int rlen, krb5_const_realm realm,
79         va_list ap);
80
81     krb5_error_code
82     krb5_make_principal(krb5_context context, krb5_principal *principal,
83         krb5_const_realm realm, ...);
84
85     krb5_error_code
86     krb5_copy_principal(krb5_context context, krb5_const_principal inprinc,
87         krb5_principal *outprinc);
88
89     krb5_boolean
90     krb5_principal_compare(krb5_context context, krb5_const_principal princ1,
91         krb5_const_principal princ2);
92
93     krb5_boolean
94     krb5_principal_compare_any_realm(krb5_context context,
95         krb5_const_principal princ1, krb5_const_principal princ2);
96
97     const char *
98     krb5_principal_get_comp_string(krb5_context context,
99         krb5_const_principal principal, unsigned int component);
100
101     const char *
102     krb5_principal_get_realm(krb5_context context,
103         krb5_const_principal principal);
104
105     int
106     krb5_principal_get_type(krb5_context context,
107         krb5_const_principal principal);
108
109     krb5_boolean
110     krb5_principal_match(krb5_context context,
111         krb5_const_principal principal, krb5_const_principal pattern);
112
113     void
114     krb5_principal_set_type(krb5_context context, krb5_principal principal,
115         int type);
116
117     krb5_boolean
118     krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
119         krb5_const_principal princ2);
120
121     krb5_error_code
122     krb5_sname_to_principal(krb5_context context, const char *hostname,
123         const char *sname, int32_t type, krb5_principal *ret_princ);
124
125     krb5_error_code
126     krb5_sock_to_principal(krb5_context context, int socket,
127         const char *sname, int32_t type, krb5_principal *principal);
128
129     krb5_error_code
130     krb5_get_default_principal(krb5_context context, krb5_principal *princ);
131
132     krb5_error_code
133     krb5_parse_nametype(krb5_context context, const char *str,
134         int32_t *type);
135

DESCRIPTION

137     krb5_principal holds the name of a user or service in Kerberos.
138
139     A principal has two parts, a PrincipalName and a realm.  The Principal‐
140     Name consists of one or more components. In printed form, the components
141     are separated by /.  The PrincipalName also has a name-type.
142
143     Examples of a principal are nisse/root@EXAMPLE.COM and
144     host/datan.kth.se@KTH.SE.  krb5_parse_name() and krb5_parse_name_flags()
145     passes a principal name in name to the kerberos principal structure.
146     krb5_parse_name_flags() takes an extra flags argument the following flags
147     can be passed in
148
149     KRB5_PRINCIPAL_PARSE_NO_REALM
150             requires the input string to be without a realm, and no realm is
151             stored in the principal return argument.
152
153     KRB5_PRINCIPAL_PARSE_REQUIRE_REALM
154             requires the input string to with a realm.
155
156     krb5_unparse_name() and krb5_unparse_name_flags() prints the principal
157     princ to the string name.  name should be freed with free(3).  To the
158     flags argument the following flags can be passed in
159
160     KRB5_PRINCIPAL_UNPARSE_SHORT
161             no realm if the realm is one of the local realms.
162
163     KRB5_PRINCIPAL_UNPARSE_NO_REALM
164             never include any realm in the principal name.
165
166     KRB5_PRINCIPAL_UNPARSE_DISPLAY
167             don't quote
168     On failure name is set to NULL.  krb5_unparse_name_fixed() and
169     krb5_unparse_name_fixed_flags() behaves just like krb5_unparse(), but
170     instead unparses the principal into a fixed size buffer.
171
172     krb5_unparse_name_short() just returns the principal without the realm if
173     the principal is in the default realm. If the principal isn't, the full
174     name is returned.  krb5_unparse_name_fixed_short() works just like
175     krb5_unparse_name_short() but on a fixed size buffer.
176
177     krb5_build_principal() builds a principal from the realm realm that has
178     the length rlen.  The following arguments form the components of the
179     principal.  The list of components is terminated with NULL.
180
181     krb5_build_principal_va() works like krb5_build_principal() using vargs.
182
183     krb5_build_principal_ext() and krb5_build_principal_va_ext() take a list
184     of length-value pairs, the list is terminated with a zero length.
185
186     krb5_make_principal() works the same way as krb5_build_principal(),
187     except it figures out the length of the realm itself.
188
189     krb5_copy_principal() makes a copy of a principal.  The copy needs to be
190     freed with krb5_free_principal().
191
192     krb5_principal_compare() compares the two principals, including realm of
193     the principals and returns TRUE if they are the same and FALSE if not.
194
195     krb5_principal_compare_any_realm() works the same way as
196     krb5_principal_compare() but doesn't compare the realm component of the
197     principal.
198
199     krb5_realm_compare() compares the realms of the two principals and
200     returns TRUE is they are the same, and FALSE if not.
201
202     krb5_principal_match() matches a principal against a pattern.  The pat‐
203     tern is a globbing expression, where each component (separated by /) is
204     matched against the corresponding component of the principal.
205
206     The krb5_principal_get_realm() and krb5_principal_get_comp_string() func‐
207     tions return parts of the principal, either the realm or a specific com‐
208     ponent.  Both functions return string pointers to data inside the princi‐
209     pal, so they are valid only as long as the principal exists.
210
211     The component argument to krb5_principal_get_comp_string() is the index
212     of the component to return, from zero to the total number of components
213     minus one. If the index is out of range NULL is returned.
214
215     krb5_principal_get_realm() and krb5_principal_get_comp_string() are
216     replacements for krb5_princ_component() and related macros, described as
217     internal in the MIT API specification.  Unlike the macros, these func‐
218     tions return strings, not krb5_data.  A reason to return krb5_data was
219     that it was believed that principal components could contain binary data,
220     but this belief was unfounded, and it has been decided that principal
221     components are infact UTF8, so it's safe to use zero terminated strings.
222
223     It's generally not necessary to look at the components of a principal.
224
225     krb5_principal_get_type() and krb5_principal_set_type() get and sets the
226     name type for a principal.  Name type handling is tricky and not often
227     needed, don't use this unless you know what you do.
228
229     krb5_sname_to_principal() and krb5_sock_to_principal() are for easy cre‐
230     ation of “service” principals that can, for instance, be used to lookup a
231     key in a keytab.  For both functions the sname parameter will be used for
232     the first component of the created principal.  If sname is NULL, “host”
233     will be used instead.
234
235     krb5_sname_to_principal() will use the passed hostname for the second
236     component.  If type is KRB5_NT_SRV_HST this name will be looked up with
237     gethostbyname().  If hostname is NULL, the local hostname will be used.
238
239     krb5_sock_to_principal() will use the “sockname” of the passed socket,
240     which should be a bound AF_INET or AF_INET6 socket.  There must be a map‐
241     ping between the address and “sockname”.  The function may try to resolve
242     the name in DNS.
243
244     krb5_get_default_principal() tries to find out what's a reasonable
245     default principal by looking at the environment it is running in.
246
247     krb5_parse_nametype() parses and returns the name type integer value in
248     type.  On failure the function returns an error code and set the error
249     string.
250

BUGS

255     You can not have a NUL in a component in some of the variable argument
256     functions above.  Until someone can give a good example of where it would
257     be a good idea to have NUL's in a component, this will not be fixed.
258
259HEIMDAL                           May 1, 2006                          HEIMDAL

NAME

LIBRARY

SYNOPSIS

DESCRIPTION

SEE ALSO

BUGS