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