crypto/heimdal/doc/doxyout/krb5/man/man3/krb5_principal.3

   1 .TH "Heimdal Kerberos 5 principal functions" 3 "11 Jan 2012" "Version 1.5.2" "HeimdalKerberos5library" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Heimdal Kerberos 5 principal functions \-
   6 .SS "Functions"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_principal\fP (krb5_context context, krb5_principal p)"
  11 .br
  12 .ti -1c
  13 .RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_principal_set_type\fP (krb5_context context, krb5_principal principal, int type)"
  14 .br
  15 .ti -1c
  16 .RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_principal_get_type\fP (krb5_context context, krb5_const_principal principal)"
  17 .br
  18 .ti -1c
  19 .RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_principal_get_realm\fP (krb5_context context, krb5_const_principal principal)"
  20 .br
  21 .ti -1c
  22 .RI "KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL \fBkrb5_principal_get_num_comp\fP (krb5_context context, krb5_const_principal principal)"
  23 .br
  24 .ti -1c
  25 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_name_flags\fP (krb5_context context, const char *name, int flags, krb5_principal *principal)"
  26 .br
  27 .ti -1c
  28 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_name\fP (krb5_context context, const char *name, krb5_principal *principal)"
  29 .br
  30 .ti -1c
  31 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_fixed\fP (krb5_context context, krb5_const_principal principal, char *name, size_t len)"
  32 .br
  33 .ti -1c
  34 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_fixed_short\fP (krb5_context context, krb5_const_principal principal, char *name, size_t len)"
  35 .br
  36 .ti -1c
  37 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_fixed_flags\fP (krb5_context context, krb5_const_principal principal, int flags, char *name, size_t len)"
  38 .br
  39 .ti -1c
  40 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name\fP (krb5_context context, krb5_const_principal principal, char **name)"
  41 .br
  42 .ti -1c
  43 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_flags\fP (krb5_context context, krb5_const_principal principal, int flags, char **name)"
  44 .br
  45 .ti -1c
  46 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_short\fP (krb5_context context, krb5_const_principal principal, char **name)"
  47 .br
  48 .ti -1c
  49 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_principal_set_realm\fP (krb5_context context, krb5_principal principal, krb5_const_realm realm)"
  50 .br
  51 .ti -1c
  52 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_build_principal\fP (krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm,...)"
  53 .br
  54 .ti -1c
  55 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_make_principal\fP (krb5_context context, krb5_principal *principal, krb5_const_realm realm,...)"
  56 .br
  57 .ti -1c
  58 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_principal\fP (krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc)"
  59 .br
  60 .ti -1c
  61 .RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_compare_any_realm\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
  62 .br
  63 .ti -1c
  64 .RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_compare\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
  65 .br
  66 .ti -1c
  67 .RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_realm_compare\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
  68 .br
  69 .ti -1c
  70 .RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_match\fP (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)"
  71 .br
  72 .ti -1c
  73 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_sname_to_principal\fP (krb5_context context, const char *hostname, const char *sname, int32_t type, krb5_principal *ret_princ)"
  74 .br
  75 .ti -1c
  76 .RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_nametype\fP (krb5_context context, const char *str, int32_t *nametype)"
  77 .br
  78 .ti -1c
  79 .RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_is_krbtgt\fP (krb5_context context, krb5_const_principal p)"
  80 .br
  81 .in -1c
  82 .SH "Detailed Description"
  83 .PP
  84
  85 .SH "Function Documentation"
  86 .PP
  87 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_build_principal (krb5_context context, krb5_principal * principal, int rlen, krb5_const_realm realm,  ...)"
  88 .PP
  89 Build a principal using vararg style building
  90 .PP
  91 \fBParameters:\fP
  92 .RS 4
  93 \fIcontext\fP A Kerberos context.
  94 .br
  95 \fIprincipal\fP returned principal
  96 .br
  97 \fIrlen\fP length of realm
  98 .br
  99 \fIrealm\fP realm name
 100 .br
 101 \fI...\fP a list of components ended with NULL.
 102 .RE
 103 .PP
 104 \fBReturns:\fP
 105 .RS 4
 106 An krb5 error code, see krb5_get_error_message().
 107 .RE
 108 .PP
 109
 110 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal (krb5_context context, krb5_const_principal inprinc, krb5_principal * outprinc)"
 111 .PP
 112 Copy a principal
 113 .PP
 114 \fBParameters:\fP
 115 .RS 4
 116 \fIcontext\fP A Kerberos context.
 117 .br
 118 \fIinprinc\fP principal to copy
 119 .br
 120 \fIoutprinc\fP copied principal, free with \fBkrb5_free_principal()\fP
 121 .RE
 122 .PP
 123 \fBReturns:\fP
 124 .RS 4
 125 An krb5 error code, see krb5_get_error_message().
 126 .RE
 127 .PP
 128
 129 .SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal (krb5_context context, krb5_principal p)"
 130 .PP
 131 Frees a Kerberos principal allocated by the library with \fBkrb5_parse_name()\fP, \fBkrb5_make_principal()\fP or any other related principal functions.
 132 .PP
 133 \fBParameters:\fP
 134 .RS 4
 135 \fIcontext\fP A Kerberos context.
 136 .br
 137 \fIp\fP a principal to free.
 138 .RE
 139 .PP
 140 \fBReturns:\fP
 141 .RS 4
 142 An krb5 error code, see krb5_get_error_message().
 143 .RE
 144 .PP
 145
 146 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal (krb5_context context, krb5_principal * principal, krb5_const_realm realm,  ...)"
 147 .PP
 148 Build a principal using vararg style building
 149 .PP
 150 \fBParameters:\fP
 151 .RS 4
 152 \fIcontext\fP A Kerberos context.
 153 .br
 154 \fIprincipal\fP returned principal
 155 .br
 156 \fIrealm\fP realm name
 157 .br
 158 \fI...\fP a list of components ended with NULL.
 159 .RE
 160 .PP
 161 \fBReturns:\fP
 162 .RS 4
 163 An krb5 error code, see krb5_get_error_message().
 164 .RE
 165 .PP
 166
 167 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name (krb5_context context, const char * name, krb5_principal * principal)"
 168 .PP
 169 Parse a name into a krb5_principal structure
 170 .PP
 171 \fBParameters:\fP
 172 .RS 4
 173 \fIcontext\fP Kerberos 5 context
 174 .br
 175 \fIname\fP name to parse into a Kerberos principal
 176 .br
 177 \fIprincipal\fP returned principal, free with \fBkrb5_free_principal()\fP.
 178 .RE
 179 .PP
 180 \fBReturns:\fP
 181 .RS 4
 182 An krb5 error code, see krb5_get_error_message().
 183 .RE
 184 .PP
 185
 186 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name_flags (krb5_context context, const char * name, int flags, krb5_principal * principal)"
 187 .PP
 188 Parse a name into a krb5_principal structure, flags controls the behavior.
 189 .PP
 190 \fBParameters:\fP
 191 .RS 4
 192 \fIcontext\fP Kerberos 5 context
 193 .br
 194 \fIname\fP name to parse into a Kerberos principal
 195 .br
 196 \fIflags\fP flags to control the behavior
 197 .br
 198 \fIprincipal\fP returned principal, free with \fBkrb5_free_principal()\fP.
 199 .RE
 200 .PP
 201 \fBReturns:\fP
 202 .RS 4
 203 An krb5 error code, see krb5_get_error_message().
 204 .RE
 205 .PP
 206
 207 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype (krb5_context context, const char * str, int32_t * nametype)"
 208 .PP
 209 Parse nametype string and return a nametype integer
 210 .SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
 211 .PP
 212 Compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not.
 213 .PP
 214 \fBParameters:\fP
 215 .RS 4
 216 \fIcontext\fP Kerberos 5 context
 217 .br
 218 \fIprinc1\fP first principal to compare
 219 .br
 220 \fIprinc2\fP second principal to compare
 221 .RE
 222 .PP
 223 \fBSee also:\fP
 224 .RS 4
 225 \fBkrb5_principal_compare_any_realm()\fP
 226 .PP
 227 \fBkrb5_realm_compare()\fP
 228 .RE
 229 .PP
 230
 231 .SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare_any_realm (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
 232 .PP
 233 Return TRUE iff princ1 == princ2 (without considering the realm)
 234 .PP
 235 \fBParameters:\fP
 236 .RS 4
 237 \fIcontext\fP Kerberos 5 context
 238 .br
 239 \fIprinc1\fP first principal to compare
 240 .br
 241 \fIprinc2\fP second principal to compare
 242 .RE
 243 .PP
 244 \fBReturns:\fP
 245 .RS 4
 246 non zero if equal, 0 if not
 247 .RE
 248 .PP
 249 \fBSee also:\fP
 250 .RS 4
 251 \fBkrb5_principal_compare()\fP
 252 .PP
 253 \fBkrb5_realm_compare()\fP
 254 .RE
 255 .PP
 256
 257 .SS "KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp (krb5_context context, krb5_const_principal principal)"
 258 .PP
 259 Get number of component is principal.
 260 .PP
 261 \fBParameters:\fP
 262 .RS 4
 263 \fIcontext\fP Kerberos 5 context
 264 .br
 265 \fIprincipal\fP principal to query
 266 .RE
 267 .PP
 268 \fBReturns:\fP
 269 .RS 4
 270 number of components in string
 271 .RE
 272 .PP
 273
 274 .SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_principal_get_realm (krb5_context context, krb5_const_principal principal)"
 275 .PP
 276 Get the realm of the principal
 277 .PP
 278 \fBParameters:\fP
 279 .RS 4
 280 \fIcontext\fP A Kerberos context.
 281 .br
 282 \fIprincipal\fP principal to get the realm for
 283 .RE
 284 .PP
 285 \fBReturns:\fP
 286 .RS 4
 287 realm of the principal, don't free or use after krb5_principal is freed
 288 .RE
 289 .PP
 290
 291 .SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type (krb5_context context, krb5_const_principal principal)"
 292 .PP
 293 Get the type of the principal
 294 .PP
 295 \fBParameters:\fP
 296 .RS 4
 297 \fIcontext\fP A Kerberos context.
 298 .br
 299 \fIprincipal\fP principal to get the type for
 300 .RE
 301 .PP
 302 \fBReturns:\fP
 303 .RS 4
 304 the type of principal
 305 .RE
 306 .PP
 307
 308 .SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt (krb5_context context, krb5_const_principal p)"
 309 .PP
 310 Check if the cname part of the principal is a krbtgt principal
 311 .SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)"
 312 .PP
 313 return TRUE iff princ matches pattern
 314 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm (krb5_context context, krb5_principal principal, krb5_const_realm realm)"
 315 .PP
 316 Set a new realm for a principal, and as a side-effect free the previous realm.
 317 .PP
 318 \fBParameters:\fP
 319 .RS 4
 320 \fIcontext\fP A Kerberos context.
 321 .br
 322 \fIprincipal\fP principal set the realm for
 323 .br
 324 \fIrealm\fP the new realm to set
 325 .RE
 326 .PP
 327 \fBReturns:\fP
 328 .RS 4
 329 An krb5 error code, see krb5_get_error_message().
 330 .RE
 331 .PP
 332
 333 .SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type (krb5_context context, krb5_principal principal, int type)"
 334 .PP
 335 Set the type of the principal
 336 .PP
 337 \fBParameters:\fP
 338 .RS 4
 339 \fIcontext\fP A Kerberos context.
 340 .br
 341 \fIprincipal\fP principal to set the type for
 342 .br
 343 \fItype\fP the new type
 344 .RE
 345 .PP
 346 \fBReturns:\fP
 347 .RS 4
 348 An krb5 error code, see krb5_get_error_message().
 349 .RE
 350 .PP
 351
 352 .SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
 353 .PP
 354 return TRUE iff realm(princ1) == realm(princ2)
 355 .PP
 356 \fBParameters:\fP
 357 .RS 4
 358 \fIcontext\fP Kerberos 5 context
 359 .br
 360 \fIprinc1\fP first principal to compare
 361 .br
 362 \fIprinc2\fP second principal to compare
 363 .RE
 364 .PP
 365 \fBSee also:\fP
 366 .RS 4
 367 \fBkrb5_principal_compare_any_realm()\fP
 368 .PP
 369 \fBkrb5_principal_compare()\fP
 370 .RE
 371 .PP
 372
 373 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_sname_to_principal (krb5_context context, const char * hostname, const char * sname, int32_t type, krb5_principal * ret_princ)"
 374 .PP
 375 Create a principal for the service running on hostname. If KRB5_NT_SRV_HST is used, the hostname is canonization using DNS (or some other service), this is potentially insecure.
 376 .PP
 377 \fBParameters:\fP
 378 .RS 4
 379 \fIcontext\fP A Kerberos context.
 380 .br
 381 \fIhostname\fP hostname to use
 382 .br
 383 \fIsname\fP Service name to use
 384 .br
 385 \fItype\fP name type of pricipal, use KRB5_NT_SRV_HST or KRB5_NT_UNKNOWN.
 386 .br
 387 \fIret_princ\fP return principal, free with \fBkrb5_free_principal()\fP.
 388 .RE
 389 .PP
 390 \fBReturns:\fP
 391 .RS 4
 392 An krb5 error code, see krb5_get_error_message().
 393 .RE
 394 .PP
 395
 396 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name (krb5_context context, krb5_const_principal principal, char ** name)"
 397 .PP
 398 Unparse the Kerberos name into a string
 399 .PP
 400 \fBParameters:\fP
 401 .RS 4
 402 \fIcontext\fP Kerberos 5 context
 403 .br
 404 \fIprincipal\fP principal to query
 405 .br
 406 \fIname\fP resulting string, free with krb5_xfree()
 407 .RE
 408 .PP
 409 \fBReturns:\fP
 410 .RS 4
 411 An krb5 error code, see krb5_get_error_message().
 412 .RE
 413 .PP
 414
 415 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed (krb5_context context, krb5_const_principal principal, char * name, size_t len)"
 416 .PP
 417 Unparse the principal name to a fixed buffer
 418 .PP
 419 \fBParameters:\fP
 420 .RS 4
 421 \fIcontext\fP A Kerberos context.
 422 .br
 423 \fIprincipal\fP principal to unparse
 424 .br
 425 \fIname\fP buffer to write name to
 426 .br
 427 \fIlen\fP length of buffer
 428 .RE
 429 .PP
 430 \fBReturns:\fP
 431 .RS 4
 432 An krb5 error code, see krb5_get_error_message().
 433 .RE
 434 .PP
 435
 436 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_flags (krb5_context context, krb5_const_principal principal, int flags, char * name, size_t len)"
 437 .PP
 438 Unparse the principal name with unparse flags to a fixed buffer.
 439 .PP
 440 \fBParameters:\fP
 441 .RS 4
 442 \fIcontext\fP A Kerberos context.
 443 .br
 444 \fIprincipal\fP principal to unparse
 445 .br
 446 \fIflags\fP unparse flags
 447 .br
 448 \fIname\fP buffer to write name to
 449 .br
 450 \fIlen\fP length of buffer
 451 .RE
 452 .PP
 453 \fBReturns:\fP
 454 .RS 4
 455 An krb5 error code, see krb5_get_error_message().
 456 .RE
 457 .PP
 458
 459 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_fixed_short (krb5_context context, krb5_const_principal principal, char * name, size_t len)"
 460 .PP
 461 Unparse the principal name to a fixed buffer. The realm is skipped if its a default realm.
 462 .PP
 463 \fBParameters:\fP
 464 .RS 4
 465 \fIcontext\fP A Kerberos context.
 466 .br
 467 \fIprincipal\fP principal to unparse
 468 .br
 469 \fIname\fP buffer to write name to
 470 .br
 471 \fIlen\fP length of buffer
 472 .RE
 473 .PP
 474 \fBReturns:\fP
 475 .RS 4
 476 An krb5 error code, see krb5_get_error_message().
 477 .RE
 478 .PP
 479
 480 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_flags (krb5_context context, krb5_const_principal principal, int flags, char ** name)"
 481 .PP
 482 Unparse the Kerberos name into a string
 483 .PP
 484 \fBParameters:\fP
 485 .RS 4
 486 \fIcontext\fP Kerberos 5 context
 487 .br
 488 \fIprincipal\fP principal to query
 489 .br
 490 \fIflags\fP flag to determine the behavior
 491 .br
 492 \fIname\fP resulting string, free with krb5_xfree()
 493 .RE
 494 .PP
 495 \fBReturns:\fP
 496 .RS 4
 497 An krb5 error code, see krb5_get_error_message().
 498 .RE
 499 .PP
 500
 501 .SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short (krb5_context context, krb5_const_principal principal, char ** name)"
 502 .PP
 503 Unparse the principal name to a allocated buffer. The realm is skipped if its a default realm.
 504 .PP
 505 \fBParameters:\fP
 506 .RS 4
 507 \fIcontext\fP A Kerberos context.
 508 .br
 509 \fIprincipal\fP principal to unparse
 510 .br
 511 \fIname\fP returned buffer, free with krb5_xfree()
 512 .RE
 513 .PP
 514 \fBReturns:\fP
 515 .RS 4
 516 An krb5 error code, see krb5_get_error_message().
 517 .RE
 518 .PP
 519