1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
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
|
