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$ 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_set_realm , 51.Nm krb5_principal_compare , 52.Nm krb5_principal_compare_any_realm , 53.Nm krb5_principal_get_comp_string , 54.Nm krb5_principal_get_realm , 55.Nm krb5_principal_get_type , 56.Nm krb5_principal_match , 57.Nm krb5_principal_set_type , 58.Nm krb5_realm_compare , 59.Nm krb5_sname_to_principal , 60.Nm krb5_sock_to_principal , 61.Nm krb5_unparse_name , 62.Nm krb5_unparse_name_flags , 63.Nm krb5_unparse_name_fixed , 64.Nm krb5_unparse_name_fixed_flags , 65.Nm krb5_unparse_name_fixed_short , 66.Nm krb5_unparse_name_short 67.Nd Kerberos 5 principal handling functions 68.Sh LIBRARY 69Kerberos 5 Library (libkrb5, -lkrb5) 70.Sh SYNOPSIS 71.In krb5.h 72.Pp 73.Li krb5_principal ; 74.Ft void 75.Fn krb5_free_principal "krb5_context context" "krb5_principal principal" 76.Ft krb5_error_code 77.Fn krb5_parse_name "krb5_context context" "const char *name" "krb5_principal *principal" 78.Ft krb5_error_code 79.Fn krb5_parse_name_flags "krb5_context context" "const char *name" "int flags" "krb5_principal *principal" 80.Ft krb5_error_code 81.Fn "krb5_unparse_name" "krb5_context context" "krb5_const_principal principal" "char **name" 82.Ft krb5_error_code 83.Fn "krb5_unparse_name_flags" "krb5_context context" "krb5_const_principal principal" "int flags" "char **name" 84.Ft krb5_error_code 85.Fn krb5_unparse_name_fixed "krb5_context context" "krb5_const_principal principal" "char *name" "size_t len" 86.Ft krb5_error_code 87.Fn krb5_unparse_name_fixed_flags "krb5_context context" "krb5_const_principal principal" "int flags" "char *name" "size_t len" 88.Ft krb5_error_code 89.Fn "krb5_unparse_name_short" "krb5_context context" "krb5_const_principal principal" "char **name" 90.Ft krb5_error_code 91.Fn krb5_unparse_name_fixed_short "krb5_context context" "krb5_const_principal principal" "char *name" "size_t len" 92.Ft void 93.Fn krb5_princ_set_realm "krb5_context context" "krb5_principal principal" "krb5_realm *realm" 94.Ft krb5_error_code 95.Fn krb5_build_principal "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "..." 96.Ft krb5_error_code 97.Fn krb5_build_principal_va "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "va_list ap" 98.Ft krb5_error_code 99.Fn "krb5_build_principal_ext" "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "..." 100.Ft krb5_error_code 101.Fn krb5_build_principal_va_ext "krb5_context context" "krb5_principal *principal" "int rlen" "krb5_const_realm realm" "va_list ap" 102.Ft krb5_error_code 103.Fn krb5_make_principal "krb5_context context" "krb5_principal *principal" "krb5_const_realm realm" "..." 104.Ft krb5_error_code 105.Fn krb5_copy_principal "krb5_context context" "krb5_const_principal inprinc" "krb5_principal *outprinc" 106.Ft krb5_boolean 107.Fn krb5_principal_compare "krb5_context context" "krb5_const_principal princ1" "krb5_const_principal princ2" 108.Ft krb5_boolean 109.Fn krb5_principal_compare_any_realm "krb5_context context" "krb5_const_principal princ1" "krb5_const_principal princ2" 110.Ft "const char *" 111.Fn krb5_principal_get_comp_string "krb5_context context" "krb5_const_principal principal" "unsigned int component" 112.Ft "const char *" 113.Fn krb5_principal_get_realm "krb5_context context" "krb5_const_principal principal" 114.Ft int 115.Fn krb5_principal_get_type "krb5_context context" "krb5_const_principal principal" 116.Ft krb5_boolean 117.Fn krb5_principal_match "krb5_context context" "krb5_const_principal principal" "krb5_const_principal pattern" 118.Ft void 119.Fn krb5_principal_set_type "krb5_context context" "krb5_principal principal" "int type" 120.Ft krb5_boolean 121.Fn krb5_realm_compare "krb5_context context" "krb5_const_principal princ1" "krb5_const_principal princ2" 122.Ft krb5_error_code 123.Fn krb5_sname_to_principal "krb5_context context" "const char *hostname" "const char *sname" "int32_t type" "krb5_principal *ret_princ" 124.Ft krb5_error_code 125.Fn krb5_sock_to_principal "krb5_context context" "int socket" "const char *sname" "int32_t type" "krb5_principal *principal" 126.Ft krb5_error_code 127.Fn krb5_get_default_principal "krb5_context context" "krb5_principal *princ" 128.Ft krb5_error_code 129.Fn krb5_parse_nametype "krb5_context context" "const char *str" "int32_t *type" 130.Sh DESCRIPTION 131.Li krb5_principal 132holds the name of a user or service in Kerberos. 133.Pp 134A principal has two parts, a 135.Li PrincipalName 136and a 137.Li realm . 138The PrincipalName consists of one or more components. In printed form, 139the components are separated by /. 140The PrincipalName also has a name-type. 141.Pp 142Examples of a principal are 143.Li nisse/root@EXAMPLE.COM 144and 145.Li host/datan.kth.se@KTH.SE . 146.Fn krb5_parse_name 147and 148.Fn krb5_parse_name_flags 149passes a principal name in 150.Fa name 151to the kerberos principal structure. 152.Fn krb5_parse_name_flags 153takes an extra 154.Fa flags 155argument the following flags can be passed in 156.Bl -tag -width Ds 157.It Dv KRB5_PRINCIPAL_PARSE_NO_REALM 158requires the input string to be without a realm, and no realm is 159stored in the 160.Fa principal 161return argument. 162.It Dv KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 163requires the input string to with a realm. 164.El 165.Pp 166.Fn krb5_unparse_name 167and 168.Fn krb5_unparse_name_flags 169prints the principal 170.Fa princ 171to the string 172.Fa name . 173.Fa name 174should be freed with 175.Xr free 3 . 176To the 177.Fa flags 178argument the following flags can be passed in 179.Bl -tag -width Ds 180.It Dv KRB5_PRINCIPAL_UNPARSE_SHORT 181no realm if the realm is one of the local realms. 182.It Dv KRB5_PRINCIPAL_UNPARSE_NO_REALM 183never include any realm in the principal name. 184.It Dv KRB5_PRINCIPAL_UNPARSE_DISPLAY 185don't quote 186.El 187On failure 188.Fa name 189is set to 190.Dv NULL . 191.Fn krb5_unparse_name_fixed 192and 193.Fn krb5_unparse_name_fixed_flags 194behaves just like 195.Fn krb5_unparse , 196but instead unparses the principal into a fixed size buffer. 197.Pp 198.Fn krb5_unparse_name_short 199just returns the principal without the realm if the principal is 200in the default realm. If the principal isn't, the full name is 201returned. 202.Fn krb5_unparse_name_fixed_short 203works just like 204.Fn krb5_unparse_name_short 205but on a fixed size buffer. 206.Pp 207.Fn krb5_build_principal 208builds a principal from the realm 209.Fa realm 210that has the length 211.Fa rlen . 212The following arguments form the components of the principal. 213The list of components is terminated with 214.Dv NULL . 215.Pp 216.Fn krb5_build_principal_va 217works like 218.Fn krb5_build_principal 219using vargs. 220.Pp 221.Fn krb5_build_principal_ext 222and 223.Fn krb5_build_principal_va_ext 224take a list of length-value pairs, the list is terminated with a zero 225length. 226.Pp 227.Fn krb5_make_principal 228works the same way as 229.Fn krb5_build_principal , 230except it figures out the length of the realm itself. 231.Pp 232.Fn krb5_copy_principal 233makes a copy of a principal. 234The copy needs to be freed with 235.Fn krb5_free_principal . 236.Pp 237.Fn krb5_principal_compare 238compares the two principals, including realm of the principals and returns 239.Dv TRUE 240if they are the same and 241.Dv FALSE 242if not. 243.Pp 244.Fn krb5_principal_compare_any_realm 245works the same way as 246.Fn krb5_principal_compare 247but doesn't compare the realm component of the principal. 248.Pp 249.Fn krb5_realm_compare 250compares the realms of the two principals and returns 251.Dv TRUE 252is they are the same, and 253.Dv FALSE 254if not. 255.Pp 256.Fn krb5_principal_match 257matches a 258.Fa principal 259against a 260.Fa pattern . 261The pattern is a globbing expression, where each component (separated 262by /) is matched against the corresponding component of the principal. 263.Pp 264The 265.Fn krb5_principal_get_realm 266and 267.Fn krb5_principal_get_comp_string 268functions return parts of the 269.Fa principal , 270either the realm or a specific component. 271Both functions return string pointers to data inside the principal, so 272they are valid only as long as the principal exists. 273.Pp 274The 275.Fa component 276argument to 277.Fn krb5_principal_get_comp_string 278is the index of the component to return, from zero to the total number of 279components minus one. If the index is out of range 280.Dv NULL 281is returned. 282.Pp 283.Fn krb5_principal_get_realm 284and 285.Fn krb5_principal_get_comp_string 286are replacements for 287.Fn krb5_princ_component 288and related macros, described as internal in the MIT API 289specification. 290Unlike the macros, these functions return strings, not 291.Dv krb5_data . 292A reason to return 293.Dv krb5_data 294was that it was believed that principal components could contain 295binary data, but this belief was unfounded, and it has been decided 296that principal components are in fact UTF8, so it's safe to use zero 297terminated strings. 298.Pp 299It's generally not necessary to look at the components of a principal. 300.Pp 301.Fn krb5_principal_get_type 302and 303.Fn krb5_principal_set_type 304get and sets the name type for a principal. 305Name type handling is tricky and not often needed, 306don't use this unless you know what you do. 307.Pp 308.Fn krb5_sname_to_principal 309and 310.Fn krb5_sock_to_principal 311are for easy creation of 312.Dq service 313principals that can, for instance, be used to lookup a key in a keytab. 314For both functions the 315.Fa sname 316parameter will be used for the first component of the created principal. 317If 318.Fa sname 319is 320.Dv NULL , 321.Dq host 322will be used instead. 323.Pp 324.Fn krb5_sname_to_principal 325will use the passed 326.Fa hostname 327for the second component. 328If 329.Fa type 330is 331.Dv KRB5_NT_SRV_HST 332this name will be looked up with 333.Fn gethostbyname . 334If 335.Fa hostname 336is 337.Dv NULL , 338the local hostname will be used. 339.Pp 340.Fn krb5_sock_to_principal 341will use the 342.Dq sockname 343of the passed 344.Fa socket , 345which should be a bound 346.Dv AF_INET 347or 348.Dv AF_INET6 349socket. 350There must be a mapping between the address and 351.Dq sockname . 352The function may try to resolve the name in DNS. 353.Pp 354.Fn krb5_get_default_principal 355tries to find out what's a reasonable default principal by looking at 356the environment it is running in. 357.Pp 358.Fn krb5_parse_nametype 359parses and returns the name type integer value in 360.Fa type . 361On failure the function returns an error code and set the error 362string. 363.\" .Sh EXAMPLES 364.Sh SEE ALSO 365.Xr krb5_425_conv_principal 3 , 366.Xr krb5_config 3 , 367.Xr krb5.conf 5 368.Sh BUGS 369You can not have a NUL in a component in some of the variable argument 370functions above. 371Until someone can give a good example of where it would be a good idea 372to have NUL's in a component, this will not be fixed. 373