— Function: char * shishi_realm_default_guess ( void)

Guesses a realm based on getdomainname() (which really is NIS/YP domain, but if it is set it might be a good guess), or if it fails, based on gethostname(), or if it fails, the string "could-not-guess-default-realm". Note that the hostname is not trimmed off of the data returned by gethostname() to get the domain name and use that as the realm.

Return value: Returns guessed realm for host as a string that has to be deallocated with free() by the caller.

— Function: const char * shishi_realm_default (Shishi * handle)

handle: Shishi library handle create by shishi_init().

Get name of default realm.

Return value: Returns the default realm used in the library. (Not a copy of it, so don't modify or deallocate it.)

— Function: void shishi_realm_default_set (Shishi * handle, const char * realm)

handle: Shishi library handle create by shishi_init().

realm: string with new default realm name, or NULL to reset to default.

Set the default realm used in the library. The string is copied into the library, so you can dispose of the variable immediately after calling this function.

— Function: char * shishi_realm_for_server_file (Shishi * handle, char * server)

handle: Shishi library handle create by shishi_init().

server: hostname to find realm for.

Find realm for a host using configuration file.

Return value: Returns realm for host, or NULL if not found.

— Function: char * shishi_realm_for_server_dns (Shishi * handle, char * server)

handle: Shishi library handle create by shishi_init().

server: hostname to find realm for.

Find realm for a host using DNS lookups, according to draft-ietf-krb-wg-krb-dns-locate-03.txt. Since DNS lookups may be spoofed, relying on the realm information may result in a redirection attack. In a single-realm scenario, this only achieves a denial of service, but with cross-realm trust it may redirect you to a compromised realm. For this reason, Shishi prints a warning, suggesting that the user should add the proper 'server-realm' configuration tokens instead.

To illustrate the DNS information used, here is an extract from a zone file for the domain ASDF.COM:

_kerberos.asdf.com. IN TXT "ASDF.COM" _kerberos.mrkserver.asdf.com. IN TXT "MARKETING.ASDF.COM" _kerberos.salesserver.asdf.com. IN TXT "SALES.ASDF.COM"

Let us suppose that in this case, a client wishes to use a service on the host foo.asdf.com. It would first query:

_kerberos.foo.asdf.com. IN TXT

Finding no match, it would then query:

_kerberos.asdf.com. IN TXT

Return value: Returns realm for host, or NULL if not found.

— Function: char * shishi_realm_for_server (Shishi * handle, char * server)

handle: Shishi library handle create by shishi_init().

server: hostname to find realm for.

Find realm for a host, using various methods. Currently this includes static configuration files (see shishi_realm_for_server_file()) and DNS (see shishi_realm_for_server_dns()).

Return value: Returns realm for host, or NULL if not found.

— Function: char * shishi_principal_default_guess ( void)

Guesses the principal name for the user, looking at environment variables SHISHI_USER, USER and LOGNAME, or if that fails, returns the string "user".

Return value: Returns guessed default principal for user as a string that has to be deallocated by the caller with free().

— Function: const char * shishi_principal_default (Shishi * handle)

handle: Shishi library handle created by shishi_init().

The default principal name is the name in the environment variable USER, or LOGNAME for some systems, but it can be overridden by specifying the environment variable SHISHI_USER.

Return value: Returns the default principal name used by the library. (Not a copy of it, so don't modify or deallocate it.)

— Function: void shishi_principal_default_set (Shishi * handle, const char * principal)

handle: Shishi library handle created by shishi_init().

principal: string with new default principal name, or NULL to reset to default.

Set the default principal used by the library. The string is copied into the library, so you can dispose of the variable immediately after calling this function.

— Function: int shishi_parse_name (Shishi * handle, const char * name, char ** principal, char ** realm)

handle: Shishi library handle created by shishi_init().

name: input principal name string, e.g. imap/mail.gnu.org\GNU.ORG.

principal: newly allocated output string with principal name.

realm: newly allocated output string with realm name.

Split principal name (e.g., "simon\JOSEFSSON.ORG") into two newly allocated strings, the principal ("simon"), and the realm ("JOSEFSSON.ORG"). If there is no realm part in name, realm is set to NULL.

Return value: Returns SHISHI_INVALID_PRINCIPAL_NAME if name is NULL or ends with the escape character "\", and SHISHI_OK if successful.

— Function: int shishi_principal_name (Shishi * handle, Shishi_asn1 namenode, const char * namefield, char ** out, size_t * outlen)

handle: Shishi library handle created by shishi_init().

namenode: ASN.1 structure with principal in namefield.

namefield: name of field in namenode containing principal name.

out: pointer to newly allocated, null terminated, string containing principal name. May be NULL (to only populate outlen).

outlen: pointer to length of out on output, excluding terminating null. May be NULL (to only populate out).

Represent principal name in ASN.1 structure as null-terminated string. The string is allocated by this function, and it is the responsibility of the caller to deallocate it. Note that the output length outlen does not include the terminating null.

Return value: Returns SHISHI_OK if successful.

— Function: int shishi_principal_name_realm (Shishi * handle, Shishi_asn1 namenode, const char * namefield, Shishi_asn1 realmnode, const char * realmfield, char ** out, size_t * outlen)

handle: Shishi library handle created by shishi_init().

namenode: ASN.1 structure with principal name in namefield.

namefield: name of field in namenode containing principal name.

realmnode: ASN.1 structure with principal realm in realmfield.

realmfield: name of field in realmnode containing principal realm.

out: pointer to newly allocated null terminated string containing principal name. May be NULL (to only populate outlen).

outlen: pointer to length of out on output, excluding terminating null. May be NULL (to only populate out).

Represent principal name and realm in ASN.1 structure as null-terminated string. The string is allocated by this function. It is the responsibility of the caller to deallocate it. Note that the output length outlen does not include the terminating null character.

Return value: Returns SHISHI_OK if successful.

— Function: int shishi_principal_name_set (Shishi * handle, Shishi_asn1 namenode, const char * namefield, Shishi_name_type name_type, const char * [] name)

handle: shishi handle as allocated by shishi_init().

namenode: ASN.1 structure with principal in namefield.

namefield: name of field in namenode containing principal name.

name_type: type of principal, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.

name: null-terminated input array with principal name.

Set the given principal name field to the given name.

Return value: Returns SHISHI_OK if successful.

— Function: int shishi_principal_set (Shishi * handle, Shishi_asn1 namenode, const char * namefield, const char * name)

handle: shishi handle as allocated by shishi_init().

namenode: ASN.1 structure with principal in namefield.

namefield: name of field in namenode containing principal name.

name: null-terminated string with principal name in RFC 1964 form.

Set principal name field in an ASN.1 structure to the given name.

Return value: Returns SHISHI_OK if successful.

— Function: int shishi_derive_default_salt (Shishi * handle, const char * name, char ** salt)

handle: shishi handle as allocated by shishi_init().

name: principal name of user.

salt: output variable with newly allocated salt string.

Derive the default salt from a principal. The default salt is the concatenation of the decoded realm and the principal.

Return value: Return SHISHI_OK if successful.

— Function: char * shishi_server_for_local_service (Shishi * handle, const char * service)

handle: shishi handle as allocated by shishi_init().

service: null terminated string with name of service, e.g., "host".

Construct a service principal (e.g., "imap/yxa.extuno.com") based on supplied service name (i.e., "imap") and the system's hostname as returned by hostname() (i.e., "yxa.extundo.com"). The string must be deallocated by the caller.

Return value: Return newly allocated service name string.

— Function: int shishi_authorize_strcmp (Shishi * handle, const char * principal, const char * authzname)

handle: shishi handle allocated by shishi_init().

principal: string with desired principal name.

authzname: authorization name.

Authorization of authzname against desired principal according to "basic" authentication, i.e., testing for identical strings.

Return value: Returns 1 if authzname is authorized for services by the encrypted principal, and 0 otherwise.

— Function: int shishi_authorize_k5login (Shishi * handle, const char * principal, const char * authzname)

handle: shishi handle allocated by shishi_init().

principal: string with desired principal name and realm.

authzname: authorization name.

Authorization of authzname against desired principal in accordance with the MIT/Heimdal authorization method.

Return value: Returns 1 if authzname is authorized for services by principal, and returns 0 otherwise.

— Function: int shishi_authorization_parse (const char * authorization)

authorization: name of authorization type, "basic" or "k5login".

Parse authorization type name.

Return value: Returns authorization type corresponding to a string.

— Function: int shishi_authorized_p (Shishi * handle, Shishi_tkt * tkt, const char * authzname)

handle: shishi handle allocated by shishi_init().

tkt: input variable with ticket info.

authzname: authorization name.

Simplistic authorization of authzname against encrypted client principal name inside ticket. For "basic" authentication type, the principal name must coincide with authzname. The "k5login" authentication type attempts the MIT/Heimdal method of parsing the file "~/.k5login" for additional equivalence names.

Return value: Returns 1 if authzname is authorized for services by the encrypted principal, and 0 otherwise.

— Function: const char * shishi_generalize_time (Shishi * handle, time_t t)

handle: shishi handle as allocated by shishi_init().

t: C time to convert.

Convert C time to KerberosTime. The string must not be deallocate by caller.

Return value: Return a KerberosTime time string corresponding to C time t.

— Function: const char * shishi_generalize_now (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Convert current time to KerberosTime. The string must not be deallocate by caller.

Return value: Return a KerberosTime time string corresponding to current time.

— Function: time_t shishi_generalize_ctime (Shishi * handle, const char * t)

handle: shishi handle as allocated by shishi_init().

t: KerberosTime to convert.

Convert KerberosTime to C time.

Return value: Returns C time corresponding to KerberosTime t.

— Function: int shishi_time (Shishi * handle, Shishi_asn1 node, const char * field, char ** t)

handle: shishi handle as allocated by shishi_init().

node: ASN.1 node to get time from.

field: Name of field in ASN.1 node to get time from.

t: newly allocated output array with zero terminated time string.

Extract time from ASN.1 structure.

Return value: Returns SHISHI_OK iff successful.

— Function: int shishi_ctime (Shishi * handle, Shishi_asn1 node, const char * field, time_t * t)

handle: shishi handle as allocated by shishi_init().

node: ASN.1 variable to read field from.

field: name of field in node to read.

t: pointer to time field to set.

Extract time from ASN.1 structure.

Return value: Returns SHISHI_OK if successful, SHISHI_ASN1_NO_ELEMENT if the element do not exist, SHISHI_ASN1_NO_VALUE if the field has no value, ot SHISHI_ASN1_ERROR otherwise.

— Function: void shishi_prompt_password_callback_set (Shishi * handle, shishi_prompt_password_func cb)

handle: shishi handle as allocated by shishi_init().

cb: function pointer to application password callback, a shishi_prompt_password_func type.

Set a callback function that will be used by shishi_prompt_password() to query the user for a password. The function pointer can be retrieved using shishi_prompt_password_callback_get().

The cb function should follow the shishi_prompt_password_func prototype:

int prompt_password (Shishi * handle, char **s, const char *format, va_list ap);

If the function returns 0, the s variable should contain a newly allocated string with the password read from the user.

— Function: shishi_prompt_password_func shishi_prompt_password_callback_get (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Get the application password prompt function callback as set by shishi_prompt_password_callback_set().

Returns: Returns the callback, a shishi_prompt_password_func type, or NULL.

— Function: int shishi_prompt_password (Shishi * handle, char ** s, const char * format, ...)

handle: shishi handle as allocated by shishi_init().

s: pointer to newly allocated output string with read password.

format: printf(3) style format string. ...: printf(3) style arguments.

Format and print a prompt, and read a password from user. The password is possibly converted (e.g., converted from Latin-1 to UTF-8, or processed using Stringprep profile) following any "stringprocess" keywords in configuration files.

Return value: Returns SHISHI_OK iff successful.

— Function: Shishi_dns shishi_resolv (const char * zone, uint16_t querytype)

zone: owner name of data, e.g. "EXAMPLE.ORG"

querytype: type of data to query for, e.g., SHISHI_DNS_TXT.

Query DNS resolver for data of type querytype at owner name zone. Currently TXT and SRV types are supported.

Return value: Returns linked list of DNS records, or NULL if query failed.

— Function: void shishi_resolv_free (Shishi_dns rrs)

rrs: list of DNS RR as returned by shishi_resolv().

Deallocate list of DNS RR as returned by shishi_resolv().