Heimdal Kerberos 5 principal functions

Functions
KRB5_LIB_FUNCTION void KRB5_LIB_CALL	krb5_free_principal (krb5_context context, krb5_principal p)
KRB5_LIB_FUNCTION void KRB5_LIB_CALL	krb5_principal_set_type (krb5_context context, krb5_principal principal, int type)
KRB5_LIB_FUNCTION int KRB5_LIB_CALL	krb5_principal_get_type (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION const char *KRB5_LIB_CALL	krb5_principal_get_realm (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL	krb5_principal_get_num_comp (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_parse_name_flags (krb5_context context, const char *name, int flags, krb5_principal *principal)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_parse_name (krb5_context context, const char *name, krb5_principal *principal)
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)
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)
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)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_unparse_name (krb5_context context, krb5_const_principal principal, char **name)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_unparse_name_flags (krb5_context context, krb5_const_principal principal, int flags, char **name)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_unparse_name_short (krb5_context context, krb5_const_principal principal, char **name)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_principal_set_realm (krb5_context context, krb5_principal principal, krb5_const_realm realm)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_build_principal (krb5_context context, krb5_principal *principal, int rlen, krb5_const_realm realm,...)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_make_principal (krb5_context context, krb5_principal *principal, krb5_const_realm realm,...)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_copy_principal (krb5_context context, krb5_const_principal inprinc, krb5_principal *outprinc)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL	krb5_principal_compare_any_realm (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL	krb5_principal_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL	krb5_realm_compare (krb5_context context, krb5_const_principal princ1, krb5_const_principal princ2)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL	krb5_principal_match (krb5_context context, krb5_const_principal princ, krb5_const_principal pattern)
KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL	krb5_parse_nametype (krb5_context context, const char *str, int32_t *nametype)
krb5_boolean KRB5_LIB_FUNCTION	krb5_principal_is_null (krb5_context context, krb5_const_principal principal)
krb5_boolean KRB5_LIB_FUNCTION	krb5_realm_is_lkdc (const char *realm)
krb5_boolean KRB5_LIB_FUNCTION	krb5_principal_is_lkdc (krb5_context context, krb5_const_principal principal)
krb5_boolean KRB5_LIB_FUNCTION	krb5_principal_is_pku2u (krb5_context context, krb5_const_principal principal)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL	krb5_principal_is_krbtgt (krb5_context context, krb5_const_principal p)
krb5_boolean KRB5_LIB_FUNCTION	krb5_principal_is_gss_hostbased_service (krb5_context context, krb5_const_principal principal)
krb5_boolean KRB5_LIB_FUNCTION	krb5_principal_is_root_krbtgt (krb5_context context, krb5_const_principal p)
KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL	krb5_principal_is_anonymous (krb5_context context, krb5_const_principal p, unsigned int flags)
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)

Detailed Description

Function Documentation

krb5_build_principal()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_build_principal	(	krb5_context	context,
		krb5_principal *	principal,
		int	rlen,
		krb5_const_realm	realm,
			...
	)

Build a principal using vararg style building

Parameters

context	A Kerberos context.
principal	returned principal
rlen	length of realm
realm	realm name
...	a list of components ended with NULL.

Returns

An krb5 error code, see krb5_get_error_message().

krb5_copy_principal()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_copy_principal	(	krb5_context	context,
		krb5_const_principal	inprinc,
		krb5_principal *	outprinc
	)

Copy a principal

Parameters

context	A Kerberos context.
inprinc	principal to copy
outprinc	copied principal, free with krb5_free_principal()

Returns

An krb5 error code, see krb5_get_error_message().

krb5_free_principal()

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_free_principal	(	krb5_context	context,
		krb5_principal	p
	)

Frees a Kerberos principal allocated by the library with krb5_parse_name(), krb5_make_principal() or any other related principal functions.

Parameters

context	A Kerberos context.
p	a principal to free.

Returns

An krb5 error code, see krb5_get_error_message().

krb5_make_principal()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_make_principal	(	krb5_context	context,
		krb5_principal *	principal,
		krb5_const_realm	realm,
			...
	)

Build a principal using vararg style building

Parameters

context	A Kerberos context.
principal	returned principal
realm	realm name
...	a list of components ended with NULL.

Returns

An krb5 error code, see krb5_get_error_message().

krb5_parse_name()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name	(	krb5_context	context,
		const char *	name,
		krb5_principal *	principal
	)

Parse a name into a krb5_principal structure

Parameters

context	Kerberos 5 context
name	name to parse into a Kerberos principal
principal	returned principal, free with krb5_free_principal().

Returns

An krb5 error code, see krb5_get_error_message().

krb5_parse_name_flags()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_name_flags	(	krb5_context	context,
		const char *	name,
		int	flags,
		krb5_principal *	principal
	)

Parse a name into a krb5_principal structure, flags controls the behavior.

Parameters

context	Kerberos 5 context
name	name to parse into a Kerberos principal
flags	flags to control the behavior
principal	returned principal, free with krb5_free_principal().

Returns

An krb5 error code, see krb5_get_error_message().

krb5_parse_nametype()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_parse_nametype	(	krb5_context	context,
		const char *	str,
		int32_t *	nametype
	)

Parse nametype string and return a nametype integer

krb5_principal_compare()

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare	(	krb5_context	context,
		krb5_const_principal	princ1,
		krb5_const_principal	princ2
	)

Compares the two principals, including realm of the principals and returns TRUE if they are the same and FALSE if not.

Parameters

context	Kerberos 5 context
princ1	first principal to compare
princ2	second principal to compare

See also

krb5_principal_compare_any_realm()

krb5_realm_compare()

krb5_principal_compare_any_realm()

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_compare_any_realm	(	krb5_context	context,
		krb5_const_principal	princ1,
		krb5_const_principal	princ2
	)

Return TRUE iff princ1 == princ2 (without considering the realm)

Parameters

context	Kerberos 5 context
princ1	first principal to compare
princ2	second principal to compare

Returns

non zero if equal, 0 if not

See also

krb5_principal_compare()

krb5_realm_compare()

krb5_principal_get_num_comp()

KRB5_LIB_FUNCTION unsigned int KRB5_LIB_CALL krb5_principal_get_num_comp	(	krb5_context	context,
		krb5_const_principal	principal
	)

Get number of component is principal.

Parameters

context	Kerberos 5 context
principal	principal to query

Returns

number of components in string

krb5_principal_get_realm()

KRB5_LIB_FUNCTION const char* KRB5_LIB_CALL krb5_principal_get_realm	(	krb5_context	context,
		krb5_const_principal	principal
	)

Get the realm of the principal

Parameters

context	A Kerberos context.
principal	principal to get the realm for

Returns

realm of the principal, don't free or use after krb5_principal is freed

krb5_principal_get_type()

KRB5_LIB_FUNCTION int KRB5_LIB_CALL krb5_principal_get_type	(	krb5_context	context,
		krb5_const_principal	principal
	)

Get the type of the principal

Parameters

context	A Kerberos context.
principal	principal to get the type for

Returns

the type of principal

krb5_principal_is_anonymous()

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_anonymous	(	krb5_context	context,
		krb5_const_principal	p,
		unsigned int	flags
	)

Returns true iff name is WELLKNOWN/ANONYMOUS

krb5_principal_is_gss_hostbased_service()

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_gss_hostbased_service	(	krb5_context	context,
		krb5_const_principal	principal
	)

Returns true iff name is an WELLKNOWN:ORG.H5L.HOSTBASED-SERVICE

krb5_principal_is_krbtgt()

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_is_krbtgt	(	krb5_context	context,
		krb5_const_principal	p
	)

Check if the cname part of the principal is a krbtgt principal

krb5_principal_is_lkdc()

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_lkdc	(	krb5_context	context,
		krb5_const_principal	principal
	)

Returns true if name is Kerberos an LKDC realm

krb5_principal_is_null()

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_null	(	krb5_context	context,
		krb5_const_principal	principal
	)

Returns true if name is Kerberos NULL name

krb5_principal_is_pku2u()

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_pku2u	(	krb5_context	context,
		krb5_const_principal	principal
	)

Returns true if name is Kerberos an LKDC realm

krb5_principal_is_root_krbtgt()

krb5_boolean KRB5_LIB_FUNCTION krb5_principal_is_root_krbtgt	(	krb5_context	context,
		krb5_const_principal	p
	)

Check if the cname part of the principal is a initial or renewed krbtgt principal

krb5_principal_match()

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_principal_match	(	krb5_context	context,
		krb5_const_principal	princ,
		krb5_const_principal	pattern
	)

return TRUE iff princ matches pattern

krb5_principal_set_realm()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_principal_set_realm	(	krb5_context	context,
		krb5_principal	principal,
		krb5_const_realm	realm
	)

Set a new realm for a principal, and as a side-effect free the previous realm.

Parameters

context	A Kerberos context.
principal	principal set the realm for
realm	the new realm to set

Returns

An krb5 error code, see krb5_get_error_message().

krb5_principal_set_type()

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_principal_set_type	(	krb5_context	context,
		krb5_principal	principal,
		int	type
	)

Set the type of the principal

Parameters

context	A Kerberos context.
principal	principal to set the type for
type	the new type

Returns

An krb5 error code, see krb5_get_error_message().

krb5_realm_compare()

KRB5_LIB_FUNCTION krb5_boolean KRB5_LIB_CALL krb5_realm_compare	(	krb5_context	context,
		krb5_const_principal	princ1,
		krb5_const_principal	princ2
	)

return TRUE iff realm(princ1) == realm(princ2)

Parameters

context	Kerberos 5 context
princ1	first principal to compare
princ2	second principal to compare

See also

krb5_principal_compare_any_realm()

krb5_principal_compare()

krb5_realm_is_lkdc()

krb5_boolean KRB5_LIB_FUNCTION krb5_realm_is_lkdc

(

const char *

realm

)

Returns true if name is Kerberos an LKDC realm

krb5_sname_to_principal()

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
	)

Create a principal for the given service running on the given hostname. If KRB5_NT_SRV_HST is used, the hostname is canonicalized according the configured name canonicalization rules, with canonicalization delayed in some cases. One rule involves DNS, which is insecure unless DNSSEC is used, but we don't use DNSSEC-capable resolver APIs here, so that if DNSSEC is used we wouldn't know it.

Canonicalization is immediate (not delayed) only when there is only one canonicalization rule and that rule indicates that we should do a host lookup by name (i.e., DNS).

Parameters

context	A Kerberos context.
hostname	hostname to use
sname	Service name to use
type	name type of principal, use KRB5_NT_SRV_HST or KRB5_NT_UNKNOWN.
ret_princ	return principal, free with krb5_free_principal().

Returns

An krb5 error code, see krb5_get_error_message().

krb5_unparse_name()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name	(	krb5_context	context,
		krb5_const_principal	principal,
		char **	name
	)

Unparse the Kerberos name into a string

Parameters

context	Kerberos 5 context
principal	principal to query
name	resulting string, free with krb5_xfree()

Returns

An krb5 error code, see krb5_get_error_message().

krb5_unparse_name_fixed()

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
	)

Unparse the principal name to a fixed buffer

Parameters

context	A Kerberos context.
principal	principal to unparse
name	buffer to write name to
len	length of buffer

Returns

An krb5 error code, see krb5_get_error_message().

krb5_unparse_name_fixed_flags()

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
	)

Unparse the principal name with unparse flags to a fixed buffer.

Parameters

context	A Kerberos context.
principal	principal to unparse
flags	unparse flags
name	buffer to write name to
len	length of buffer

Returns

An krb5 error code, see krb5_get_error_message().

krb5_unparse_name_fixed_short()

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
	)

Unparse the principal name to a fixed buffer. The realm is skipped if its a default realm.

Parameters

context	A Kerberos context.
principal	principal to unparse
name	buffer to write name to
len	length of buffer

Returns

An krb5 error code, see krb5_get_error_message().

krb5_unparse_name_flags()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_flags	(	krb5_context	context,
		krb5_const_principal	principal,
		int	flags,
		char **	name
	)

Unparse the Kerberos name into a string

Parameters

context	Kerberos 5 context
principal	principal to query
flags	flag to determine the behavior
name	resulting string, free with krb5_xfree()

Returns

An krb5 error code, see krb5_get_error_message().

krb5_unparse_name_short()

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_unparse_name_short	(	krb5_context	context,
		krb5_const_principal	principal,
		char **	name
	)

Unparse the principal name to a allocated buffer. The realm is skipped if its a default realm.

Parameters

context	A Kerberos context.
principal	principal to unparse
name	returned buffer, free with krb5_xfree()

Returns

An krb5 error code, see krb5_get_error_message().