.TH "Heimdal Kerberos 5 principal functions" 3 "11 Jan 2012" "Version 1.5.2" "HeimdalKerberos5library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Heimdal Kerberos 5 principal functions \- 
.SS "Functions"

.in +1c
.ti -1c
.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_free_principal\fP (krb5_context context, krb5_principal p)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION void KRB5_LIB_CALL \fBkrb5_principal_set_type\fP (krb5_context context, krb5_principal principal, int type)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION int KRB5_LIB_CALL \fBkrb5_principal_get_type\fP (krb5_context context, krb5_const_principal principal)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL \fBkrb5_principal_get_realm\fP (krb5_context context, krb5_const_principal principal)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL \fBkrb5_principal_get_num_comp\fP (krb5_context context, krb5_const_principal principal)"
.br
.ti -1c
.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)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_name\fP (krb5_context context, const char *name, krb5_principal *principal)"
.br
.ti -1c
.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)"
.br
.ti -1c
.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)"
.br
.ti -1c
.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)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name\fP (krb5_context context, krb5_const_principal principal, char **name)"
.br
.ti -1c
.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)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_unparse_name_short\fP (krb5_context context, krb5_const_principal principal, char **name)"
.br
.ti -1c
.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)"
.br
.ti -1c
.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,...)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_make_principal\fP (krb5_context context, krb5_principal *principal, krb5_const_realm realm,...)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_copy_principal\fP (krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc)"
.br
.ti -1c
.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)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_compare\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_realm_compare\fP (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_match\fP (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)"
.br
.ti -1c
.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)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL \fBkrb5_parse_nametype\fP (krb5_context context, const char *str, int32_t *nametype)"
.br
.ti -1c
.RI "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL \fBkrb5_principal_is_krbtgt\fP (krb5_context context, krb5_const_principal p)"
.br
.in -1c
.SH "Detailed Description"
.PP 

.SH "Function Documentation"
.PP 
.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,  ...)"
.PP
Build a principal using vararg style building
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP returned principal 
.br
\fIrlen\fP length of realm 
.br
\fIrealm\fP realm name 
.br
\fI...\fP a list of components ended with NULL.
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal (krb5_context context, krb5_const_principal inprinc, krb5_principal * outprinc)"
.PP
Copy a principal
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIinprinc\fP principal to copy 
.br
\fIoutprinc\fP copied principal, free with \fBkrb5_free_principal()\fP
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal (krb5_context context, krb5_principal p)"
.PP
Frees a Kerberos principal allocated by the library with \fBkrb5_parse_name()\fP, \fBkrb5_make_principal()\fP or any other related principal functions.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIp\fP a principal to free.
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal (krb5_context context, krb5_principal * principal, krb5_const_realm realm,  ...)"
.PP
Build a principal using vararg style building
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP returned principal 
.br
\fIrealm\fP realm name 
.br
\fI...\fP a list of components ended with NULL.
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name (krb5_context context, const char * name, krb5_principal * principal)"
.PP
Parse a name into a krb5_principal structure
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIname\fP name to parse into a Kerberos principal 
.br
\fIprincipal\fP returned principal, free with \fBkrb5_free_principal()\fP.
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.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)"
.PP
Parse a name into a krb5_principal structure, flags controls the behavior.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIname\fP name to parse into a Kerberos principal 
.br
\fIflags\fP flags to control the behavior 
.br
\fIprincipal\fP returned principal, free with \fBkrb5_free_principal()\fP.
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype (krb5_context context, const char * str, int32_t * nametype)"
.PP
Parse nametype string and return a nametype integer 
.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
.PP
Compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIprinc1\fP first principal to compare 
.br
\fIprinc2\fP second principal to compare
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkrb5_principal_compare_any_realm()\fP 
.PP
\fBkrb5_realm_compare()\fP 
.RE
.PP

.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)"
.PP
Return TRUE iff princ1 == princ2 (without considering the realm)
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIprinc1\fP first principal to compare 
.br
\fIprinc2\fP second principal to compare
.RE
.PP
\fBReturns:\fP
.RS 4
non zero if equal, 0 if not
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkrb5_principal_compare()\fP 
.PP
\fBkrb5_realm_compare()\fP 
.RE
.PP

.SS "KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp (krb5_context context, krb5_const_principal principal)"
.PP
Get number of component is principal.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIprincipal\fP principal to query
.RE
.PP
\fBReturns:\fP
.RS 4
number of components in string 
.RE
.PP

.SS "KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_principal_get_realm (krb5_context context, krb5_const_principal principal)"
.PP
Get the realm of the principal
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to get the realm for
.RE
.PP
\fBReturns:\fP
.RS 4
realm of the principal, don't free or use after krb5_principal is freed 
.RE
.PP

.SS "KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type (krb5_context context, krb5_const_principal principal)"
.PP
Get the type of the principal
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to get the type for
.RE
.PP
\fBReturns:\fP
.RS 4
the type of principal 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt (krb5_context context, krb5_const_principal p)"
.PP
Check if the cname part of the principal is a krbtgt principal 
.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)"
.PP
return TRUE iff princ matches pattern 
.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm (krb5_context context, krb5_principal principal, krb5_const_realm realm)"
.PP
Set a new realm for a principal, and as a side-effect free the previous realm.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal set the realm for 
.br
\fIrealm\fP the new realm to set
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type (krb5_context context, krb5_principal principal, int type)"
.PP
Set the type of the principal
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to set the type for 
.br
\fItype\fP the new type
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)"
.PP
return TRUE iff realm(princ1) == realm(princ2)
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIprinc1\fP first principal to compare 
.br
\fIprinc2\fP second principal to compare
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkrb5_principal_compare_any_realm()\fP 
.PP
\fBkrb5_principal_compare()\fP 
.RE
.PP

.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)"
.PP
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.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIhostname\fP hostname to use 
.br
\fIsname\fP Service name to use 
.br
\fItype\fP name type of pricipal, use KRB5_NT_SRV_HST or KRB5_NT_UNKNOWN. 
.br
\fIret_princ\fP return principal, free with \fBkrb5_free_principal()\fP.
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name (krb5_context context, krb5_const_principal principal, char ** name)"
.PP
Unparse the Kerberos name into a string
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIprincipal\fP principal to query 
.br
\fIname\fP resulting string, free with krb5_xfree()
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.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)"
.PP
Unparse the principal name to a fixed buffer
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to unparse 
.br
\fIname\fP buffer to write name to 
.br
\fIlen\fP length of buffer
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.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)"
.PP
Unparse the principal name with unparse flags to a fixed buffer.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to unparse 
.br
\fIflags\fP unparse flags 
.br
\fIname\fP buffer to write name to 
.br
\fIlen\fP length of buffer
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.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)"
.PP
Unparse the principal name to a fixed buffer. The realm is skipped if its a default realm.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to unparse 
.br
\fIname\fP buffer to write name to 
.br
\fIlen\fP length of buffer
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.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)"
.PP
Unparse the Kerberos name into a string
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP Kerberos 5 context 
.br
\fIprincipal\fP principal to query 
.br
\fIflags\fP flag to determine the behavior 
.br
\fIname\fP resulting string, free with krb5_xfree()
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP

.SS "KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short (krb5_context context, krb5_const_principal principal, char ** name)"
.PP
Unparse the principal name to a allocated buffer. The realm is skipped if its a default realm.
.PP
\fBParameters:\fP
.RS 4
\fIcontext\fP A Kerberos context. 
.br
\fIprincipal\fP principal to unparse 
.br
\fIname\fP returned buffer, free with krb5_xfree()
.RE
.PP
\fBReturns:\fP
.RS 4
An krb5 error code, see krb5_get_error_message(). 
.RE
.PP