Principals define a uniquely named client or server instance that participates in a network communication. The following functions allow one to create, modify and access portions of the krb5_principal.
Other functions found in orther portions of the manual include krb5_sname_to_principal, krb5_free_principal,
While it is possible to directly access the data structure in the structure, it is recommended that the functions be used.
Converts a single-string representation name of the principal name to the multi-part principal format used in the protocols.
A single-string representation of a Kerberos name consists of one or more principal name components, separated by slashes, optionally followed by the ``@'' character and a realm name. If the realm name is not specified, the local realm is used.
The slash and ``@'' characters may be quoted (i.e., included as part
of a component rather than as a component separator or realm prefix)
by preceding them with a backslash (``'') character.
Similarly, newline, tab, backspace, and null characters may be
included in a component by using
,
,
or
, respectively.
The realm in a Kerberos name may not contain the slash, colon or null characters.
*principal will point to allocated storage which should be freed by the caller (using krb5_free_principal) after use.
krb5_parse_name returns KRB5_PARSE_MALFORMED if the string is badly formatted, or ENOMEM if space for the return value can't be allocated.
Converts the multi-part principal name principal from the format used in the protocols to a single-string representation of the name. The resulting single-string representation will use the format and quoting conventions described for krb5_parse_name above.
*name points to allocated storage and should be freed by the caller when finished.
krb5_unparse_name returns KRB_PARSE_MALFORMED if the principal does not contain at least 2 components, and system errors (ENOMEM if unable to allocate memory).
krb5_unparse_name_ext is designed for applications which must unparse a large number of principals, and are concerned about the speed impact of needing to do a lot of memory allocations and deallocations. It functions similarly to krb5_unparse_name except if *name is non-null, in which case, it is assumed to contain an allocated buffer of size *size and this buffer will be resized with realloc to hold the unparsed name. Note that in this case, size must not be null.
If size is non-null (whether or not *name is null when the function is called), it will be filled in with the size of the unparsed name upon successful return.
A macro which returns the realm of principal.
A macro which returns sets the realm of principal to realm.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
A macro which returns sets the data portion of the realm of principal to data.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
A macro which returns sets the length principal to length.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
A macro which gives the number of elements in the principal. May also be used on the left size of an assignment.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
A macro which gives the type of the principal. May also be used on the left size of an assignment.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
A macro which gives the pointer to data portion of the principal. May also be used on the left size of an assignment.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
A macro which gives the pointer to ith element of the principal. May also be used on the left size of an assignment.
krb5_build_principal and krb5_build_principal_va perform the same function; the former takes variadic arguments, while the latter takes a pre-computed varargs pointer.
Both functions take a realm name realm, realm name length rlen, and a list of null-terminated strings, and fill in a pointer to a principal structure princ, making it point to a structure representing the named principal. The last string must be followed in the argument list by a null pointer.
krb5_build_principal_ext is similar to krb5_build_principal but it takes its components as a list of (length, contents) pairs rather than a list of null-terminated strings. A length of zero indicates the end of the list.
Copy a principal structure, filling in *outprinc to point to the newly allocated copy, which should be freed with krb5_free_principal.
If the two principals are the same, return TRUE, else return FALSE.
If the realms of the two principals are the same, return TRUE, else return FALSE.
Build a principal princ from a V4 specification made up of name.instance@realm. The routine is site-customized to convert the V4 naming scheme to a V5 one. For instance, the V4 ``rcmd'' is changed to ``host''.
The returned principal should be freed with krb5_free_principal.