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