— 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 and USER, or if that fails, returns the string "user".

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

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

handle: Shishi library handle create by shishi_init().

The default principal name is the name in the environment variable USER, but can be overridden by specifying the environment variable SHISHI_USER.

Return value: Returns the default principal name used in 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 create by shishi_init().

principal: string with new default principal 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: int shishi_parse_name (Shishi * handle, const char * name, char ** principal, char ** realm)

handle: Shishi library handle create by shishi_init().

name: Input principal name string, e.g. imap/mail.gnu.orgGNU.ORG.

principal: newly allocated output string with principal name.

realm: newly allocated output string with realm name.

Split up principal name (e.g., "simonJOSEFSSON.ORG") into two newly allocated strings, the principal ("simon") and 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 "\", or SHISHI_OK iff successful

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

handle: Shishi library handle create 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 zero terminated string containing principal name. May be NULL (to only populate outlen).

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

Represent principal name in ASN.1 structure as zero-terminated string. The string is allocate 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 zero.

Return value: Returns SHISHI_OK iff 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 create 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 zero terminated string containing principal name. May be NULL (to only populate outlen).

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

Represent principal name and realm in ASN.1 structure as zero-terminated string. The string is allocate 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 zero.

Return value: Returns SHISHI_OK iff 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 principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.

name: zero-terminated input array with principal name.

Set the given principal name field to given name.

Return value: Returns SHISHI_OK iff 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: zero-terminated string with principal name on RFC 1964 form.

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

Return value: Returns SHISHI_OK iff 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 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: zero 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 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_authorization_parse (const char * authorization)

authorization: name of authorization type, e.g. "basic".

Parse authorization type name.

Return value: Return authorization type corresponding to a string.

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

handle: shishi handle as allocated by shishi_init().

tkt: input variable with ticket info.

authzname: authorization name.

Simplistic authorization of authzname against encrypted client principal name inside ticket. Currently this function only compare the principal name with authzname using strcmp().

Return value: Returns 1 if authzname is authorized for services by authenticated client principal, or 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_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().