Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KRB5_PRINCIPAL(3)	 BSD Library Functions Manual	     KRB5_PRINCIPAL(3)

NAME
     krb5_get_default_principal, krb5_principal, krb5_build_principal,
     krb5_build_principal_ext, krb5_build_principal_va,
     krb5_build_principal_va_ext, krb5_copy_principal, krb5_free_principal,
     krb5_make_principal, krb5_parse_name, krb5_parse_name_flags,
     krb5_parse_nametype, krb5_princ_set_realm,	krb5_principal_compare,
     krb5_principal_compare_any_realm, krb5_principal_get_comp_string,
     krb5_principal_get_realm, krb5_principal_get_type,	krb5_principal_match,
     krb5_principal_set_type, krb5_realm_compare, krb5_sname_to_principal,
     krb5_sock_to_principal, krb5_unparse_name,	krb5_unparse_name_flags,
     krb5_unparse_name_fixed, krb5_unparse_name_fixed_flags,
     krb5_unparse_name_fixed_short, krb5_unparse_name_short -- Kerberos	5
     principal handling	functions

LIBRARY
     Kerberos 5	Library	(libkrb5, -lkrb5)

SYNOPSIS
     #include <krb5.h>

     krb5_principal;

     void
     krb5_free_principal(krb5_context context, krb5_principal principal);

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

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

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

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

     krb5_error_code
     krb5_unparse_name_fixed(krb5_context context,
	 krb5_const_principal principal, char *name, size_t len);

     krb5_error_code
     krb5_unparse_name_fixed_flags(krb5_context	context,
	 krb5_const_principal principal, int flags, char *name,	size_t len);

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

     krb5_error_code
     krb5_unparse_name_fixed_short(krb5_context	context,
	 krb5_const_principal principal, char *name, size_t len);

     void
     krb5_princ_set_realm(krb5_context context,	krb5_principal principal,
	 krb5_realm *realm);

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

     krb5_error_code
     krb5_build_principal_va(krb5_context context, krb5_principal *principal,
	 int rlen, krb5_const_realm realm, va_list ap);

     krb5_error_code
     krb5_build_principal_ext(krb5_context context, krb5_principal *principal,
	 int rlen, krb5_const_realm realm, ...);

     krb5_error_code
     krb5_build_principal_va_ext(krb5_context context,
	 krb5_principal	*principal, int	rlen, krb5_const_realm realm,
	 va_list ap);

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

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

     krb5_boolean
     krb5_principal_compare(krb5_context context, krb5_const_principal princ1,
	 krb5_const_principal princ2);

     krb5_boolean
     krb5_principal_compare_any_realm(krb5_context context,
	 krb5_const_principal princ1, krb5_const_principal princ2);

     const char	*
     krb5_principal_get_comp_string(krb5_context context,
	 krb5_const_principal principal, unsigned int component);

     const char	*
     krb5_principal_get_realm(krb5_context context,
	 krb5_const_principal principal);

     int
     krb5_principal_get_type(krb5_context context,
	 krb5_const_principal principal);

     krb5_boolean
     krb5_principal_match(krb5_context context,
	 krb5_const_principal principal, krb5_const_principal pattern);

     void
     krb5_principal_set_type(krb5_context context, krb5_principal principal,
	 int type);

     krb5_boolean
     krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
	 krb5_const_principal princ2);

     krb5_error_code
     krb5_sname_to_principal(krb5_context context, const char *hostname,
	 const char *sname, int32_t type, krb5_principal *ret_princ);

     krb5_error_code
     krb5_sock_to_principal(krb5_context context, int socket,
	 const char *sname, int32_t type, krb5_principal *principal);

     krb5_error_code
     krb5_get_default_principal(krb5_context context, krb5_principal *princ);

     krb5_error_code
     krb5_parse_nametype(krb5_context context, const char *str,
	 int32_t *type);

DESCRIPTION
     krb5_principal holds the name of a	user or	service	in Kerberos.

     A principal has two parts,	a PrincipalName	and a realm.  The Principal-
     Name consists of one or more components. In printed form, the components
     are separated by /.  The PrincipalName also has a name-type.

     Examples of a principal are nisse/root@EXAMPLE.COM	and
     host/datan.kth.se@KTH.SE.	krb5_parse_name() and krb5_parse_name_flags()
     passes a principal	name in	name to	the kerberos principal structure.
     krb5_parse_name_flags() takes an extra flags argument the following flags
     can be passed in

     KRB5_PRINCIPAL_PARSE_NO_REALM
	     requires the input	string to be without a realm, and no realm is
	     stored in the principal return argument.

     KRB5_PRINCIPAL_PARSE_REQUIRE_REALM
	     requires the input	string to with a realm.

     krb5_unparse_name() and krb5_unparse_name_flags() prints the principal
     princ to the string name.	name should be freed with free(3).  To the
     flags argument the	following flags	can be passed in

     KRB5_PRINCIPAL_UNPARSE_SHORT
	     no	realm if the realm is one of the local realms.

     KRB5_PRINCIPAL_UNPARSE_NO_REALM
	     never include any realm in	the principal name.

     KRB5_PRINCIPAL_UNPARSE_DISPLAY
	     don't quote
     On	failure	name is	set to NULL.  krb5_unparse_name_fixed()	and
     krb5_unparse_name_fixed_flags() behaves just like krb5_unparse(), but in-
     stead unparses the	principal into a fixed size buffer.

     krb5_unparse_name_short() just returns the	principal without the realm if
     the principal is in the default realm. If the principal isn't, the	full
     name is returned.	krb5_unparse_name_fixed_short()	works just like
     krb5_unparse_name_short() but on a	fixed size buffer.

     krb5_build_principal() builds a principal from the	realm realm that has
     the length	rlen.  The following arguments form the	components of the
     principal.	 The list of components	is terminated with NULL.

     krb5_build_principal_va() works like krb5_build_principal() using vargs.

     krb5_build_principal_ext()	and krb5_build_principal_va_ext() take a list
     of	length-value pairs, the	list is	terminated with	a zero length.

     krb5_make_principal() works the same way as krb5_build_principal(), ex-
     cept it figures out the length of the realm itself.

     krb5_copy_principal() makes a copy	of a principal.	 The copy needs	to be
     freed with	krb5_free_principal().

     krb5_principal_compare() compares the two principals, including realm of
     the principals and	returns	TRUE if	they are the same and FALSE if not.

     krb5_principal_compare_any_realm()	works the same way as
     krb5_principal_compare() but doesn't compare the realm component of the
     principal.

     krb5_realm_compare() compares the realms of the two principals and	re-
     turns TRUE	is they	are the	same, and FALSE	if not.

     krb5_principal_match() matches a principal	against	a pattern.  The	pat-
     tern is a globbing	expression, where each component (separated by /) is
     matched against the corresponding component of the	principal.

     The krb5_principal_get_realm() and	krb5_principal_get_comp_string() func-
     tions return parts	of the principal, either the realm or a	specific com-
     ponent.  Both functions return string pointers to data inside the princi-
     pal, so they are valid only as long as the	principal exists.

     The component argument to krb5_principal_get_comp_string()	is the index
     of	the component to return, from zero to the total	number of components
     minus one.	If the index is	out of range NULL is returned.

     krb5_principal_get_realm()	and krb5_principal_get_comp_string() are re-
     placements	for krb5_princ_component() and related macros, described as
     internal in the MIT API specification.  Unlike the	macros,	these func-
     tions return strings, not krb5_data.  A reason to return krb5_data	was
     that it was believed that principal components could contain binary data,
     but this belief was unfounded, and	it has been decided that principal
     components	are infact UTF8, so it's safe to use zero terminated strings.

     It's generally not	necessary to look at the components of a principal.

     krb5_principal_get_type() and krb5_principal_set_type() get and sets the
     name type for a principal.	 Name type handling is tricky and not often
     needed, don't use this unless you know what you do.

     krb5_sname_to_principal() and krb5_sock_to_principal() are	for easy cre-
     ation of "service"	principals that	can, for instance, be used to lookup a
     key in a keytab.  For both	functions the sname parameter will be used for
     the first component of the	created	principal.  If sname is	NULL, "host"
     will be used instead.

     krb5_sname_to_principal() will use	the passed hostname for	the second
     component.	 If type is KRB5_NT_SRV_HST this name will be looked up	with
     gethostbyname().  If hostname is NULL, the	local hostname will be used.

     krb5_sock_to_principal() will use the "sockname" of the passed socket,
     which should be a bound AF_INET or	AF_INET6 socket.  There	must be	a map-
     ping between the address and "sockname".  The function may	try to resolve
     the name in DNS.

     krb5_get_default_principal() tries	to find	out what's a reasonable	de-
     fault principal by	looking	at the environment it is running in.

     krb5_parse_nametype() parses and returns the name type integer value in
     type.  On failure the function returns an error code and set the error
     string.

SEE ALSO
     krb5_425_conv_principal(3), krb5_config(3), krb5.conf(5)

BUGS
     You can not have a	NUL in a component in some of the variable argument
     functions above.  Until someone can give a	good example of	where it would
     be	a good idea to have NUL's in a component, this will not	be fixed.

HEIMDAL				  May 1, 2006			       HEIMDAL

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=krb5_free_principal&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help