xref: /freebsd/crypto/heimdal/lib/krb5/krb5_principal.3 (revision fc55c20355d889bf3d3f81d94b3614a0c4253fa0)
1*ae771770SStanislav Sedov.\" Copyright (c) 2003 - 2007 Kungliga Tekniska Högskolan
2c19800e8SDoug Rabson.\" (Royal Institute of Technology, Stockholm, Sweden).
3c19800e8SDoug Rabson.\" All rights reserved.
4c19800e8SDoug Rabson.\"
5c19800e8SDoug Rabson.\" Redistribution and use in source and binary forms, with or without
6c19800e8SDoug Rabson.\" modification, are permitted provided that the following conditions
7c19800e8SDoug Rabson.\" are met:
8c19800e8SDoug Rabson.\"
9c19800e8SDoug Rabson.\" 1. Redistributions of source code must retain the above copyright
10c19800e8SDoug Rabson.\"    notice, this list of conditions and the following disclaimer.
11c19800e8SDoug Rabson.\"
12c19800e8SDoug Rabson.\" 2. Redistributions in binary form must reproduce the above copyright
13c19800e8SDoug Rabson.\"    notice, this list of conditions and the following disclaimer in the
14c19800e8SDoug Rabson.\"    documentation and/or other materials provided with the distribution.
15c19800e8SDoug Rabson.\"
16c19800e8SDoug Rabson.\" 3. Neither the name of the Institute nor the names of its contributors
17c19800e8SDoug Rabson.\"    may be used to endorse or promote products derived from this software
18c19800e8SDoug Rabson.\"    without specific prior written permission.
19c19800e8SDoug Rabson.\"
20c19800e8SDoug Rabson.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
21c19800e8SDoug Rabson.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22c19800e8SDoug Rabson.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23c19800e8SDoug Rabson.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
24c19800e8SDoug Rabson.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25c19800e8SDoug Rabson.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26c19800e8SDoug Rabson.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27c19800e8SDoug Rabson.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28c19800e8SDoug Rabson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29c19800e8SDoug Rabson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30c19800e8SDoug Rabson.\" SUCH DAMAGE.
31c19800e8SDoug Rabson.\"
32*ae771770SStanislav Sedov.\" $Id$
33c19800e8SDoug Rabson.\"
34c19800e8SDoug Rabson.Dd May  1, 2006
35c19800e8SDoug Rabson.Dt KRB5_PRINCIPAL 3
36c19800e8SDoug Rabson.Os HEIMDAL
37c19800e8SDoug Rabson.Sh NAME
38c19800e8SDoug Rabson.Nm krb5_get_default_principal ,
39c19800e8SDoug Rabson.Nm krb5_principal ,
40c19800e8SDoug Rabson.Nm krb5_build_principal ,
41c19800e8SDoug Rabson.Nm krb5_build_principal_ext ,
42c19800e8SDoug Rabson.Nm krb5_build_principal_va ,
43c19800e8SDoug Rabson.Nm krb5_build_principal_va_ext ,
44c19800e8SDoug Rabson.Nm krb5_copy_principal ,
45c19800e8SDoug Rabson.Nm krb5_free_principal ,
46c19800e8SDoug Rabson.Nm krb5_make_principal ,
47c19800e8SDoug Rabson.Nm krb5_parse_name ,
48c19800e8SDoug Rabson.Nm krb5_parse_name_flags ,
49c19800e8SDoug Rabson.Nm krb5_parse_nametype ,
50c19800e8SDoug Rabson.Nm krb5_princ_set_realm ,
51c19800e8SDoug Rabson.Nm krb5_principal_compare ,
52c19800e8SDoug Rabson.Nm krb5_principal_compare_any_realm ,
53c19800e8SDoug Rabson.Nm krb5_principal_get_comp_string ,
54c19800e8SDoug Rabson.Nm krb5_principal_get_realm ,
55c19800e8SDoug Rabson.Nm krb5_principal_get_type ,
56c19800e8SDoug Rabson.Nm krb5_principal_match ,
57c19800e8SDoug Rabson.Nm krb5_principal_set_type ,
58c19800e8SDoug Rabson.Nm krb5_realm_compare ,
59c19800e8SDoug Rabson.Nm krb5_sname_to_principal ,
60c19800e8SDoug Rabson.Nm krb5_sock_to_principal ,
61c19800e8SDoug Rabson.Nm krb5_unparse_name ,
62c19800e8SDoug Rabson.Nm krb5_unparse_name_flags ,
63c19800e8SDoug Rabson.Nm krb5_unparse_name_fixed ,
64c19800e8SDoug Rabson.Nm krb5_unparse_name_fixed_flags ,
65c19800e8SDoug Rabson.Nm krb5_unparse_name_fixed_short ,
66c19800e8SDoug Rabson.Nm krb5_unparse_name_short
67c19800e8SDoug Rabson.Nd Kerberos 5 principal handling functions
68c19800e8SDoug Rabson.Sh LIBRARY
69c19800e8SDoug RabsonKerberos 5 Library (libkrb5, -lkrb5)
70c19800e8SDoug Rabson.Sh SYNOPSIS
71c19800e8SDoug Rabson.In krb5.h
72c19800e8SDoug Rabson.Pp
73c19800e8SDoug Rabson.Li krb5_principal ;
74c19800e8SDoug Rabson.Ft void
75c19800e8SDoug Rabson.Fn krb5_free_principal "krb5_context context" "krb5_principal principal"
76c19800e8SDoug Rabson.Ft krb5_error_code
77c19800e8SDoug Rabson.Fn krb5_parse_name "krb5_context context" "const char *name" "krb5_principal *principal"
78c19800e8SDoug Rabson.Ft krb5_error_code
79c19800e8SDoug Rabson.Fn krb5_parse_name_flags "krb5_context context" "const char *name" "int flags" "krb5_principal *principal"
80c19800e8SDoug Rabson.Ft krb5_error_code
81c19800e8SDoug Rabson.Fn "krb5_unparse_name" "krb5_context context" "krb5_const_principal principal" "char **name"
82c19800e8SDoug Rabson.Ft krb5_error_code
83c19800e8SDoug Rabson.Fn "krb5_unparse_name_flags" "krb5_context context" "krb5_const_principal principal" "int flags" "char **name"
84c19800e8SDoug Rabson.Ft krb5_error_code
85c19800e8SDoug Rabson.Fn krb5_unparse_name_fixed "krb5_context context" "krb5_const_principal principal" "char *name" "size_t len"
86c19800e8SDoug Rabson.Ft krb5_error_code
87c19800e8SDoug Rabson.Fn krb5_unparse_name_fixed_flags "krb5_context context" "krb5_const_principal principal" "int flags" "char *name" "size_t len"
88c19800e8SDoug Rabson.Ft krb5_error_code
89c19800e8SDoug Rabson.Fn "krb5_unparse_name_short" "krb5_context context" "krb5_const_principal principal" "char **name"
90c19800e8SDoug Rabson.Ft krb5_error_code
91c19800e8SDoug Rabson.Fn krb5_unparse_name_fixed_short "krb5_context context" "krb5_const_principal principal" "char *name" "size_t len"
92c19800e8SDoug Rabson.Ft void
93c19800e8SDoug Rabson.Fn krb5_princ_set_realm "krb5_context context" "krb5_principal principal" "krb5_realm *realm"
94c19800e8SDoug Rabson.Ft krb5_error_code
95c19800e8SDoug Rabson.Fn krb5_build_principal "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "..."
96c19800e8SDoug Rabson.Ft krb5_error_code
97c19800e8SDoug Rabson.Fn krb5_build_principal_va "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "va_list ap"
98c19800e8SDoug Rabson.Ft krb5_error_code
99c19800e8SDoug Rabson.Fn "krb5_build_principal_ext" "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "..."
100c19800e8SDoug Rabson.Ft krb5_error_code
101c19800e8SDoug Rabson.Fn krb5_build_principal_va_ext "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "va_list ap"
102c19800e8SDoug Rabson.Ft krb5_error_code
103c19800e8SDoug Rabson.Fn krb5_make_principal "krb5_context context" "krb5_principal *principal" "krb5_const_realm realm" "..."
104c19800e8SDoug Rabson.Ft krb5_error_code
105c19800e8SDoug Rabson.Fn krb5_copy_principal "krb5_context context" "krb5_const_principal inprinc" "krb5_principal *outprinc"
106c19800e8SDoug Rabson.Ft krb5_boolean
107c19800e8SDoug Rabson.Fn krb5_principal_compare "krb5_context context" "krb5_const_principal princ1" "krb5_const_principal princ2"
108c19800e8SDoug Rabson.Ft krb5_boolean
109c19800e8SDoug Rabson.Fn krb5_principal_compare_any_realm "krb5_context context" "krb5_const_principal princ1" "krb5_const_principal princ2"
110c19800e8SDoug Rabson.Ft "const char *"
111c19800e8SDoug Rabson.Fn krb5_principal_get_comp_string "krb5_context context" "krb5_const_principal principal" "unsigned int component"
112c19800e8SDoug Rabson.Ft "const char *"
113c19800e8SDoug Rabson.Fn krb5_principal_get_realm "krb5_context context" "krb5_const_principal principal"
114c19800e8SDoug Rabson.Ft int
115c19800e8SDoug Rabson.Fn krb5_principal_get_type "krb5_context context" "krb5_const_principal principal"
116c19800e8SDoug Rabson.Ft krb5_boolean
117c19800e8SDoug Rabson.Fn krb5_principal_match "krb5_context context" "krb5_const_principal principal" "krb5_const_principal pattern"
118c19800e8SDoug Rabson.Ft void
119c19800e8SDoug Rabson.Fn krb5_principal_set_type "krb5_context context" "krb5_principal principal" "int type"
120c19800e8SDoug Rabson.Ft krb5_boolean
121c19800e8SDoug Rabson.Fn krb5_realm_compare "krb5_context context" "krb5_const_principal princ1" "krb5_const_principal princ2"
122c19800e8SDoug Rabson.Ft krb5_error_code
123c19800e8SDoug Rabson.Fn krb5_sname_to_principal  "krb5_context context" "const char *hostname" "const char *sname" "int32_t type" "krb5_principal *ret_princ"
124c19800e8SDoug Rabson.Ft krb5_error_code
125c19800e8SDoug Rabson.Fn krb5_sock_to_principal "krb5_context context" "int socket" "const char *sname" "int32_t type" "krb5_principal *principal"
126c19800e8SDoug Rabson.Ft krb5_error_code
127c19800e8SDoug Rabson.Fn krb5_get_default_principal "krb5_context context" "krb5_principal *princ"
128c19800e8SDoug Rabson.Ft krb5_error_code
129c19800e8SDoug Rabson.Fn krb5_parse_nametype "krb5_context context" "const char *str" "int32_t *type"
130c19800e8SDoug Rabson.Sh DESCRIPTION
131c19800e8SDoug Rabson.Li krb5_principal
132c19800e8SDoug Rabsonholds the name of a user or service in Kerberos.
133c19800e8SDoug Rabson.Pp
134c19800e8SDoug RabsonA principal has two parts, a
135c19800e8SDoug Rabson.Li PrincipalName
136c19800e8SDoug Rabsonand a
137c19800e8SDoug Rabson.Li realm .
138c19800e8SDoug RabsonThe PrincipalName consists of one or more components. In printed form,
139c19800e8SDoug Rabsonthe components are separated by /.
140c19800e8SDoug RabsonThe PrincipalName also has a name-type.
141c19800e8SDoug Rabson.Pp
142c19800e8SDoug RabsonExamples of a principal are
143c19800e8SDoug Rabson.Li nisse/root@EXAMPLE.COM
144c19800e8SDoug Rabsonand
145c19800e8SDoug Rabson.Li host/datan.kth.se@KTH.SE .
146c19800e8SDoug Rabson.Fn krb5_parse_name
147c19800e8SDoug Rabsonand
148c19800e8SDoug Rabson.Fn krb5_parse_name_flags
149c19800e8SDoug Rabsonpasses a principal name in
150c19800e8SDoug Rabson.Fa name
151c19800e8SDoug Rabsonto the kerberos principal structure.
152c19800e8SDoug Rabson.Fn krb5_parse_name_flags
153c19800e8SDoug Rabsontakes an extra
154c19800e8SDoug Rabson.Fa flags
155c19800e8SDoug Rabsonargument the following flags can be passed in
156c19800e8SDoug Rabson.Bl -tag -width Ds
157c19800e8SDoug Rabson.It Dv KRB5_PRINCIPAL_PARSE_NO_REALM
158*ae771770SStanislav Sedovrequires the input string to be without a realm, and no realm is
159c19800e8SDoug Rabsonstored in the
160c19800e8SDoug Rabson.Fa principal
161c19800e8SDoug Rabsonreturn argument.
162*ae771770SStanislav Sedov.It Dv KRB5_PRINCIPAL_PARSE_REQUIRE_REALM
163*ae771770SStanislav Sedovrequires the input string to with a realm.
164c19800e8SDoug Rabson.El
165c19800e8SDoug Rabson.Pp
166c19800e8SDoug Rabson.Fn krb5_unparse_name
167c19800e8SDoug Rabsonand
168c19800e8SDoug Rabson.Fn krb5_unparse_name_flags
169c19800e8SDoug Rabsonprints the principal
170c19800e8SDoug Rabson.Fa princ
171c19800e8SDoug Rabsonto the string
172c19800e8SDoug Rabson.Fa name .
173c19800e8SDoug Rabson.Fa name
174c19800e8SDoug Rabsonshould be freed with
175c19800e8SDoug Rabson.Xr free 3 .
176c19800e8SDoug RabsonTo the
177c19800e8SDoug Rabson.Fa flags
178c19800e8SDoug Rabsonargument the following flags can be passed in
179c19800e8SDoug Rabson.Bl -tag -width Ds
180c19800e8SDoug Rabson.It Dv KRB5_PRINCIPAL_UNPARSE_SHORT
181c19800e8SDoug Rabsonno realm if the realm is one of the local realms.
182c19800e8SDoug Rabson.It Dv KRB5_PRINCIPAL_UNPARSE_NO_REALM
183c19800e8SDoug Rabsonnever include any realm in the principal name.
184c19800e8SDoug Rabson.It Dv KRB5_PRINCIPAL_UNPARSE_DISPLAY
185c19800e8SDoug Rabsondon't quote
186c19800e8SDoug Rabson.El
187c19800e8SDoug RabsonOn failure
188c19800e8SDoug Rabson.Fa name
189c19800e8SDoug Rabsonis set to
190c19800e8SDoug Rabson.Dv NULL .
191c19800e8SDoug Rabson.Fn krb5_unparse_name_fixed
192c19800e8SDoug Rabsonand
193c19800e8SDoug Rabson.Fn krb5_unparse_name_fixed_flags
194c19800e8SDoug Rabsonbehaves just like
195c19800e8SDoug Rabson.Fn krb5_unparse ,
196c19800e8SDoug Rabsonbut instead unparses the principal into a fixed size buffer.
197c19800e8SDoug Rabson.Pp
198c19800e8SDoug Rabson.Fn krb5_unparse_name_short
199c19800e8SDoug Rabsonjust returns the principal without the realm if the principal is
200c19800e8SDoug Rabsonin the default realm. If the principal isn't, the full name is
201c19800e8SDoug Rabsonreturned.
202c19800e8SDoug Rabson.Fn krb5_unparse_name_fixed_short
203c19800e8SDoug Rabsonworks just like
204c19800e8SDoug Rabson.Fn krb5_unparse_name_short
205c19800e8SDoug Rabsonbut on a fixed size buffer.
206c19800e8SDoug Rabson.Pp
207c19800e8SDoug Rabson.Fn krb5_build_principal
208c19800e8SDoug Rabsonbuilds a principal from the realm
209c19800e8SDoug Rabson.Fa realm
210c19800e8SDoug Rabsonthat has the length
211c19800e8SDoug Rabson.Fa rlen .
212c19800e8SDoug RabsonThe following arguments form the components of the principal.
213c19800e8SDoug RabsonThe list of components is terminated with
214c19800e8SDoug Rabson.Dv NULL .
215c19800e8SDoug Rabson.Pp
216c19800e8SDoug Rabson.Fn krb5_build_principal_va
217c19800e8SDoug Rabsonworks like
218c19800e8SDoug Rabson.Fn krb5_build_principal
219c19800e8SDoug Rabsonusing vargs.
220c19800e8SDoug Rabson.Pp
221c19800e8SDoug Rabson.Fn krb5_build_principal_ext
222c19800e8SDoug Rabsonand
223c19800e8SDoug Rabson.Fn krb5_build_principal_va_ext
224c19800e8SDoug Rabsontake a list of length-value pairs, the list is terminated with a zero
225c19800e8SDoug Rabsonlength.
226c19800e8SDoug Rabson.Pp
227c19800e8SDoug Rabson.Fn krb5_make_principal
228c19800e8SDoug Rabsonworks the same way as
229c19800e8SDoug Rabson.Fn krb5_build_principal ,
230c19800e8SDoug Rabsonexcept it figures out the length of the realm itself.
231c19800e8SDoug Rabson.Pp
232c19800e8SDoug Rabson.Fn krb5_copy_principal
233c19800e8SDoug Rabsonmakes a copy of a principal.
234c19800e8SDoug RabsonThe copy needs to be freed with
235c19800e8SDoug Rabson.Fn krb5_free_principal .
236c19800e8SDoug Rabson.Pp
237c19800e8SDoug Rabson.Fn krb5_principal_compare
238c19800e8SDoug Rabsoncompares the two principals, including realm of the principals and returns
239c19800e8SDoug Rabson.Dv TRUE
240c19800e8SDoug Rabsonif they are the same and
241c19800e8SDoug Rabson.Dv FALSE
242c19800e8SDoug Rabsonif not.
243c19800e8SDoug Rabson.Pp
244c19800e8SDoug Rabson.Fn krb5_principal_compare_any_realm
245c19800e8SDoug Rabsonworks the same way as
246c19800e8SDoug Rabson.Fn krb5_principal_compare
247c19800e8SDoug Rabsonbut doesn't compare the realm component of the principal.
248c19800e8SDoug Rabson.Pp
249c19800e8SDoug Rabson.Fn krb5_realm_compare
250c19800e8SDoug Rabsoncompares the realms of the two principals and returns
251c19800e8SDoug Rabson.Dv TRUE
252c19800e8SDoug Rabsonis they are the same, and
253c19800e8SDoug Rabson.Dv FALSE
254c19800e8SDoug Rabsonif not.
255c19800e8SDoug Rabson.Pp
256c19800e8SDoug Rabson.Fn krb5_principal_match
257c19800e8SDoug Rabsonmatches a
258c19800e8SDoug Rabson.Fa principal
259c19800e8SDoug Rabsonagainst a
260c19800e8SDoug Rabson.Fa pattern .
261c19800e8SDoug RabsonThe pattern is a globbing expression, where each component (separated
262c19800e8SDoug Rabsonby /) is matched against the corresponding component of the principal.
263c19800e8SDoug Rabson.Pp
264c19800e8SDoug RabsonThe
265c19800e8SDoug Rabson.Fn krb5_principal_get_realm
266c19800e8SDoug Rabsonand
267c19800e8SDoug Rabson.Fn krb5_principal_get_comp_string
268c19800e8SDoug Rabsonfunctions return parts of the
269c19800e8SDoug Rabson.Fa principal ,
270c19800e8SDoug Rabsoneither the realm or a specific component.
271c19800e8SDoug RabsonBoth functions return string pointers to data inside the principal, so
272c19800e8SDoug Rabsonthey are valid only as long as the principal exists.
273c19800e8SDoug Rabson.Pp
274c19800e8SDoug RabsonThe
275c19800e8SDoug Rabson.Fa component
276c19800e8SDoug Rabsonargument to
277c19800e8SDoug Rabson.Fn krb5_principal_get_comp_string
278c19800e8SDoug Rabsonis the index of the component to return, from zero to the total number of
279c19800e8SDoug Rabsoncomponents minus one. If the index is out of range
280c19800e8SDoug Rabson.Dv NULL
281c19800e8SDoug Rabsonis returned.
282c19800e8SDoug Rabson.Pp
283c19800e8SDoug Rabson.Fn krb5_principal_get_realm
284c19800e8SDoug Rabsonand
285c19800e8SDoug Rabson.Fn krb5_principal_get_comp_string
286c19800e8SDoug Rabsonare replacements for
287c19800e8SDoug Rabson.Fn krb5_princ_component
288c19800e8SDoug Rabsonand related macros, described as internal in the MIT API
289c19800e8SDoug Rabsonspecification.
290c19800e8SDoug RabsonUnlike the macros, these functions return strings, not
291c19800e8SDoug Rabson.Dv krb5_data .
292c19800e8SDoug RabsonA reason to return
293c19800e8SDoug Rabson.Dv krb5_data
294c19800e8SDoug Rabsonwas that it was believed that principal components could contain
295c19800e8SDoug Rabsonbinary data, but this belief was unfounded, and it has been decided
296c19800e8SDoug Rabsonthat principal components are in fact UTF8, so it's safe to use zero
297c19800e8SDoug Rabsonterminated strings.
298c19800e8SDoug Rabson.Pp
299c19800e8SDoug RabsonIt's generally not necessary to look at the components of a principal.
300c19800e8SDoug Rabson.Pp
301c19800e8SDoug Rabson.Fn krb5_principal_get_type
302c19800e8SDoug Rabsonand
303c19800e8SDoug Rabson.Fn krb5_principal_set_type
304c19800e8SDoug Rabsonget and sets the name type for a principal.
305c19800e8SDoug RabsonName type handling is tricky and not often needed,
306c19800e8SDoug Rabsondon't use this unless you know what you do.
307c19800e8SDoug Rabson.Pp
308c19800e8SDoug Rabson.Fn krb5_sname_to_principal
309c19800e8SDoug Rabsonand
310c19800e8SDoug Rabson.Fn krb5_sock_to_principal
311c19800e8SDoug Rabsonare for easy creation of
312c19800e8SDoug Rabson.Dq service
313c19800e8SDoug Rabsonprincipals that can, for instance, be used to lookup a key in a keytab.
314c19800e8SDoug RabsonFor both functions the
315c19800e8SDoug Rabson.Fa sname
316c19800e8SDoug Rabsonparameter will be used for the first component of the created principal.
317c19800e8SDoug RabsonIf
318c19800e8SDoug Rabson.Fa sname
319c19800e8SDoug Rabsonis
320c19800e8SDoug Rabson.Dv NULL ,
321c19800e8SDoug Rabson.Dq host
322c19800e8SDoug Rabsonwill be used instead.
323c19800e8SDoug Rabson.Pp
324c19800e8SDoug Rabson.Fn krb5_sname_to_principal
325c19800e8SDoug Rabsonwill use the passed
326c19800e8SDoug Rabson.Fa hostname
327c19800e8SDoug Rabsonfor the second component.
328c19800e8SDoug RabsonIf
329c19800e8SDoug Rabson.Fa type
330c19800e8SDoug Rabsonis
331c19800e8SDoug Rabson.Dv KRB5_NT_SRV_HST
332c19800e8SDoug Rabsonthis name will be looked up with
333c19800e8SDoug Rabson.Fn gethostbyname .
334c19800e8SDoug RabsonIf
335c19800e8SDoug Rabson.Fa hostname
336c19800e8SDoug Rabsonis
337c19800e8SDoug Rabson.Dv NULL ,
338c19800e8SDoug Rabsonthe local hostname will be used.
339c19800e8SDoug Rabson.Pp
340c19800e8SDoug Rabson.Fn krb5_sock_to_principal
341c19800e8SDoug Rabsonwill use the
342c19800e8SDoug Rabson.Dq sockname
343c19800e8SDoug Rabsonof the passed
344c19800e8SDoug Rabson.Fa socket ,
345c19800e8SDoug Rabsonwhich should be a bound
346c19800e8SDoug Rabson.Dv AF_INET
347c19800e8SDoug Rabsonor
348c19800e8SDoug Rabson.Dv AF_INET6
349c19800e8SDoug Rabsonsocket.
350c19800e8SDoug RabsonThere must be a mapping between the address and
351c19800e8SDoug Rabson.Dq sockname .
352c19800e8SDoug RabsonThe function may try to resolve the name in DNS.
353c19800e8SDoug Rabson.Pp
354c19800e8SDoug Rabson.Fn krb5_get_default_principal
355c19800e8SDoug Rabsontries to find out what's a reasonable default principal by looking at
356c19800e8SDoug Rabsonthe environment it is running in.
357c19800e8SDoug Rabson.Pp
358c19800e8SDoug Rabson.Fn krb5_parse_nametype
359c19800e8SDoug Rabsonparses and returns the name type integer value in
360c19800e8SDoug Rabson.Fa type .
361c19800e8SDoug RabsonOn failure the function returns an error code and set the error
362c19800e8SDoug Rabsonstring.
363c19800e8SDoug Rabson.\" .Sh EXAMPLES
364c19800e8SDoug Rabson.Sh SEE ALSO
365c19800e8SDoug Rabson.Xr krb5_425_conv_principal 3 ,
366c19800e8SDoug Rabson.Xr krb5_config 3 ,
367c19800e8SDoug Rabson.Xr krb5.conf 5
368c19800e8SDoug Rabson.Sh BUGS
369c19800e8SDoug RabsonYou can not have a NUL in a component in some of the variable argument
370c19800e8SDoug Rabsonfunctions above.
371c19800e8SDoug RabsonUntil someone can give a good example of where it would be a good idea
372c19800e8SDoug Rabsonto have NUL's in a component, this will not be fixed.
373