Next: ASN.1 Functions, Previous: X.509 Functions, Up: Programming Manual [Contents][Index]
Description: Guesses a realm based on getdomainname(), which really responds
with a NIS/YP domain, but if set properly, it might be a good
first guess. If this NIS query fails, call gethostname(),
and on its failure, fall back to returning the artificial
string "could-not-guess-default-realm".
Note that the hostname is not trimmed off of the string returned
by gethostname(), thus pretending the local host name is a valid
realm name. The resulting corner case could merit a check that
the suggested realm is distinct from the fully qualifies host,
and if not, simply strip the host name from the returned string
before it is used in an application. One reason for sticking
with the present behaviour, is that some systems respond with
a non-qualified host name as reply from gethostname().
Return value: Returns a guessed realm for the running host,
containing a string that has to be deallocated with
free() by the caller.
handle: Shishi library handle created by shishi_init().
Description: Determines name of default realm, i.e., the name of whatever realm the library will use whenever an explicit realm is not stated during a library call.
Return value: Returns the default realm in use by the library. Not a copy, so do not modify or deallocate the returned string.
handle: Shishi library handle created by shishi_init().
realm: String stating a new default realm name, or NULL.
Description: Sets the default realm used by the library; or, with realm
set to NULL, resets the library realm setting to that name
selected by configuration for default value.
The string is copied into the library, so you can dispose of the content in realm immediately after calling this function.
handle: Shishi library handle created by shishi_init().
server: Hostname to determine realm for.
Description: Finds the realm applicable to a host server, using the standard configuration file.
Return value: Returns realm for host, or NULL if not known.
handle: Shishi library handle created by shishi_init().
server: Hostname to find realm for.
Description: Finds the realm for a host server using DNS lookup, as is prescribed in "draft-ietf-krb-wg-krb-dns-locate-03.txt".
Since DNS lookup can 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 trust across multiple realms the attack may redirect you to a compromised realm. For this reason, Shishi prints a warning, suggesting that the user should instead add a proper ’server-realm’ configuration token.
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 for
_kerberos.foo.asdf.com. IN TXT
Finding no match, it would then query for
_kerberos.asdf.com. IN TXT
With the resource records stated above, the latter query returns a positive answer.
Return value: Returns realm for the indicated host, or NULL
if no relevant TXT record could be found.
handle: Shishi library handle created by shishi_init().
server: Hostname to find realm for.
Description: Finds a realm for the host server, using various methods.
Currently this includes static configuration files, using
the library call shishi_realm_for_server_file(), and DNS
lookup using shishi_realm_for_server_dns(). They are
attempted in the stated order. See the documentation of
either function for more information.
Return value: Returns realm for the indicated host, or NULL
if nothing is known about server.
Description: 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().
handle: Shishi library handle created by shishi_init().
Description: 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.)
handle: Shishi library handle created by shishi_init().
principal: string with new default principal name, or NULL to
reset to default.
Description: 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.
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.
Description: 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.
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).
Description: 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.
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).
Description: 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.
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.
Description: Set the given principal name field to the given name.
Return value: Returns SHISHI_OK if successful.
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.
Description: Set principal name field in an ASN.1 structure to the given name.
Return value: Returns SHISHI_OK if successful.
handle: shishi handle as allocated by shishi_init().
name: principal name of user.
salt: output variable with newly allocated salt string.
Description: 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.
handle: shishi handle as allocated by shishi_init().
service: null terminated string with name of service, e.g., "host".
Description: 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.
handle: shishi handle allocated by shishi_init().
principal: string with desired principal name.
authzname: authorization name.
Description: 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.
handle: shishi handle allocated by shishi_init().
principal: string with desired principal name and realm.
authzname: authorization name.
Description: 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.
authorization: name of authorization type, "basic" or "k5login".
Description: Parse authorization type name.
Return value: Returns authorization type corresponding to a string.
handle: shishi handle allocated by shishi_init().
tkt: input variable with ticket info.
authzname: authorization name.
Description: 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.
handle: Shishi handle as allocated by shishi_init().
t: C time to convert.
Description: Converts C time t to a KerberosTime string representation. The returned string must not be deallocated by the caller.
Return value: Returns a KerberosTime formatted string corresponding to the input parameter.
handle: Shishi handle as allocated by shishi_init().
Description: Converts the current time to a KerberosTime string. The returned string must not be deallocated by the caller.
Return value: Returns a KerberosTime formatted string corresponding to the current time.
handle: Shishi handle as allocated by shishi_init().
t: KerberosTime string to convert.
Description: Converts a KerberosTime formatted string in t to integral C time representation.
Return value: Returns the C time corresponding to the input argument.
handle: Shishi handle as allocated by shishi_init().
node: ASN.1 structure to get time from.
field: Name of the field in the ASN.1 node carrying time.
t: Returned pointer to an allocated char array containing
a null-terminated time string.
Description: Extracts time information from an ASN.1 structure, and to be precise, does so from the named field field within the structure node.
Return value: Returns SHISHI_OK if successful, or an error.
handle: Shishi handle as allocated by shishi_init().
node: ASN.1 structure to read field from.
field: Name of field in node to read.
t: Pointer to a C-time valued integer, being updated with
the time value to be extracted.
Description: Extracts time information from an ASN.1 structure node, and from an arbitrary element field of that structure.
Return value: Returns SHISHI_OK if successful,
SHISHI_ASN1_NO_ELEMENT if the element does not exist,
SHISHI_ASN1_NO_VALUE if the field has no value.
In all other cases, SHISHI_ASN1_ERROR is returned.
handle: shishi handle as allocated by shishi_init().
cb: function pointer to application password callback, a
shishi_prompt_password_func type.
Description: 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.
handle: shishi handle as allocated by shishi_init().
Description: 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.
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.
Description: 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.
zone: Domain name of authentication zone, e.g. "EXAMPLE.ORG"
querytype: Type of domain data to query for.
Description: Queries the DNS resolver for data of type querytype about
the domain name zone. Currently, the types SHISHI_DNS_TXT
and SHISHI_DNS_SRV are the only supported kinds.
After its use, the returned list should be deallocated by
a call to shishi_resolv_free().
Return value: Returns a linked list of DNS resource records,
or NULL if the query failed.
rrs: List of DNS RRs as returned by shishi_resolv().
Description: Deallocates a list of DNS resource records returned by
a call to shishi_resolv().
Next: ASN.1 Functions, Previous: X.509 Functions, Up: Programming Manual [Contents][Index]