shishi_alloc_fail_function ()

void
(*shishi_alloc_fail_function) (void);

shishi ()

Shishi *
shishi (void);

Initializes the Shishi library, and primes logging so that future warnings and informational messages are printed on stderr. If this function fails, it may send its own diagnostic errors to stderr.

shishi_server ()

Shishi *
shishi_server (void);

Initializes the Shishi library, and primes logging so that future warnings and informational messages are sent to the syslog system. If this function fails, it may print diagnostic errors in the syslog.

shishi_done ()

void
shishi_done (Shishi *handle);

Deallocates the Shishi library handle. The handle must not be used in any call to a shishi function after an execution of shishi_done().

If there is a default tkts, it is written to the default tkts file. If you do not wish to write the default tkts file, close the default file before calling this function. It is closed with a simple shishi_tkts_done(handle , NULL). For related information, see shishi_tkts_default_file_set().

shishi_init ()

int
shishi_init (Shishi **handle);

Creates a Shishi library handle, using shishi(), and reads the system configuration file, user configuration file and user tickets from their default locations. The paths to the system configuration file is decided at compile time, and is $sysconfdir/shishi.conf. The user configuration file is $HOME/.shishi/config, and the user ticket file is $HOME/.shishi/ticket.

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while reading files.

shishi_init_with_paths ()

int
shishi_init_with_paths (Shishi **handle,
                        const char *tktsfile,
                        const char *systemcfgfile,
                        const char *usercfgfile);

Creates a Shishi library handle, using shishi(), and reads the system configuration file, user configuration file, and user tickets at the specified locations. If any of usercfgfile or systemcfgfile is NULL, the file is read from its default location, which for the system configuration is decided at compile time, and is $sysconfdir/shishi.conf, and for the user configuration it is $HOME/.shishi/config. If the ticket file name is NULL, a ticket file is not read at all.

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while reading files.

shishi_init_server ()

int
shishi_init_server (Shishi **handle);

Creates a Shishi library handle, using shishi_server(), and reads the system configuration file. The path to the system configuration file is decided at compile time, and is $sysconfdir/shishi.conf.

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while reading the file.

shishi_init_server_with_paths ()

int
shishi_init_server_with_paths (Shishi **handle,
                               const char *systemcfgfile);

Creates a Shishi library handle, using shishi_server(), and reads the system configuration file from the specified location. The path to the system configuration file is decided at compile time, and is $sysconfdir/shishi.conf.

The handle is allocated regardless of return value. The single exception being SHISHI_HANDLE_ERROR, which indicates a problem in allocating the handle. Other error conditions could arise while reading the file.

shishi_cfg ()

int
shishi_cfg (Shishi *handle,
            const char *option);

Configures the shishi library according to the options given in option .

shishi_cfg_from_file ()

int
shishi_cfg_from_file (Shishi *handle,
                      const char *cfg);

Configures the shishi library using a configuration file located at cfg .

shishi_cfg_print ()

int
shishi_cfg_print (Shishi *handle,
                  FILE *fh);

Prints library configuration status to fh . This function is mostly intended for debugging purposes.

shishi_cfg_default_systemfile ()

const char *
shishi_cfg_default_systemfile (Shishi *handle);

The system configuration file name is decided at compile time, but is replaced by assigning another file name to the environment variable $SHISHI_CONFIG. This call offers a single interface for determining the file name, to which the library turns for its settings.

shishi_cfg_default_userdirectory ()

const char *
shishi_cfg_default_userdirectory (Shishi *handle);

The default user directory, referred to for Shishi ticket cache and other purposes, is normally computed by appending the fixed string "/.shishi" to the content of the environment variable $HOME.

This hard coded directory, i.e., "$HOME/.shishi/", can be replaced by whatever complete path is stored in the environment variable $SHISHI_HOME.

shishi_cfg_default_userfile ()

const char *
shishi_cfg_default_userfile (Shishi *handle);

Reports the absolute filename of the default user configuration file. This is typically "$HOME/.shishi/shishi.conf".

The value of $SHISHI_HOME will change the directory part, as stated regarding shishi_cfg_default_userdirectory().

shishi_cfg_userdirectory_file ()

char *
shishi_cfg_userdirectory_file (Shishi *handle,
                               const char *file);

Reports the full path to the file where the Shishi library expects to find the user's library configuration, given that the file itself is named by the parameter file .

The answer is composed from the value of file and the directory returned by shishi_cfg_default_userdirectory(). Typically, the returned string would be expanded from "$HOME/.shishi/file ".

shishi_cfg_clientkdcetype ()

int
shishi_cfg_clientkdcetype (Shishi *handle,
                           int32_t **etypes);

Sets the variable etypes to a static array of preferred encryption types applicable to clients.

shishi_cfg_clientkdcetype_fast ()

int32_t
shishi_cfg_clientkdcetype_fast (Shishi *handle);

Extracts the default encryption type from the list of preferred encryption types acceptable to the client.

When the preferred list is empty, SHISHI_AES256_CTS_HMAC_SHA1_96 is returned as a sensible default type.

shishi_cfg_clientkdcetype_set ()

int
shishi_cfg_clientkdcetype_set (Shishi *handle,
                               char *value);

Sets the configuration option "client-kdc-etypes" from value . The string contains encryption types, integers or names, separated by comma or by whitespace. An example naming three encryption types could be:

aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5

shishi_cfg_authorizationtype_set ()

int
shishi_cfg_authorizationtype_set (Shishi *handle,
                                  char *value);

Sets the configuration option "authorization-types" from value . The string contains authorization types, integers or names, separated by comma or whitespace.

As an example, "k5login basic" would first check Kerberos5 authentication based on preset principals, and then fall back to the basic test of identical principal names.

shishi_strerror ()

const char *
shishi_strerror (int err);

Converts the return code in err to a human readable string.

shishi_error ()

const char *
shishi_error (Shishi *handle);

Extracts detailed information on the most recently occurred error condition. Note that memory is managed by the Shishi library, so the returned string must not be deallocated.

shishi_error_clear ()

void
shishi_error_clear (Shishi *handle);

Clears the internal error description. See shishi_error() on how to access the error string, and shishi_error_set() as well as shishi_error_printf() on how to set the error string.

This function is mostly for Shishi's internal use, but if you develop an extension of Shishi, it may be useful to support the same error handling infrastructure.

shishi_error_set ()

void
shishi_error_set (Shishi *handle,
                  const char *errstr);

Sets the error description to the content of errstr . The string is copied into the Shishi internal structure, so you can deallocate any string passed to this function.

This function is mostly for Shishi's internal use, but if you develop an extension of Shishi, it may be useful to support the same error handling infrastructure.

shishi_error_printf ()

void
shishi_error_printf (Shishi *handle,
                     const char *format,
                     ...);

Sets the internal error description to a printf(3) formatted string. This function is mostly for Shishi's internal use, but if you develop an extension of Shishi, it may be useful to support the same infrastructure for error handling.

shishi_error_outputtype ()

int
shishi_error_outputtype (Shishi *handle);

Reports the current output type used in message logging.

shishi_error_set_outputtype ()

void
shishi_error_set_outputtype (Shishi *handle,
                             int type);

Sets the output type (NULL, stderr or syslog) used for information and warning messages. Intended values are SHISHI_OUTPUTTYPE_NULL, for no output at all, SHISHI_OUTPUTTYPE_STDERR for output to the console, and SHISHI_OUTPUTTYPE_SYSLOG for syslog messaging. The first value covers everything different from the latter two values.

shishi_info ()

void
shishi_info (Shishi *handle,
             const char *format,
             ...);

Prints an informational message, composed from the arguments, to the output stream set in handle .

shishi_warn ()

void
shishi_warn (Shishi *handle,
             const char *format,
             ...);

Prints a warning, composed from the arguments, to the output stream set in handle .

shishi_verbose ()

void
shishi_verbose (Shishi *handle,
                const char *format,
                ...);

Prints a diagnostic message, composed from the arguments, to the output stream set in handle . The current verbosity setting determines whether the message is actually printed, or is suppressed due to low significance.

shishi_realm_default_guess ()

char *
shishi_realm_default_guess (void);

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().

shishi_realm_default ()

const char *
shishi_realm_default (Shishi *handle);

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.

shishi_realm_default_set ()

void
shishi_realm_default_set (Shishi *handle,
                          const char *realm);

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.

shishi_realm_for_server_file ()

char *
shishi_realm_for_server_file (Shishi *handle,
                              char *server);

Finds the realm applicable to a host server , using the standard configuration file.

shishi_realm_for_server_dns ()

char *
shishi_realm_for_server_dns (Shishi *handle,
                             char *server);

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.

shishi_realm_for_server ()

char *
shishi_realm_for_server (Shishi *handle,
                         char *server);

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.

shishi_principal_default_guess ()

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".

shishi_principal_default ()

const char *
shishi_principal_default (Shishi *handle);

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.

shishi_principal_default_set ()

void
shishi_principal_default_set (Shishi *handle,
                              const char *principal);

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.

shishi_principal_name ()

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

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.

shishi_principal_name_realm ()

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

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.

shishi_principal_name_set ()

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

Set the given principal name field to the given name.

shishi_principal_set ()

int
shishi_principal_set (Shishi *handle,
                      Shishi_asn1 namenode,
                      const char *namefield,
                      const char *name);

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

shishi_parse_name ()

int
shishi_parse_name (Shishi *handle,
                   const char *name,
                   char **principal,
                   char **realm);

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.

shishi_derive_default_salt ()

int
shishi_derive_default_salt (Shishi *handle,
                            const char *name,
                            char **salt);

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

shishi_server_for_local_service ()

char *
shishi_server_for_local_service (Shishi *handle,
                                 const char *service);

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.

shishi_ticket ()

Shishi_asn1
shishi_ticket (Shishi *handle);

This function creates a new ASN.1 Ticket, populated with some default values.

shishi_ticket_server ()

int
shishi_ticket_server (Shishi *handle,
                      Shishi_asn1 ticket,
                      char **server,
                      size_t *serverlen);

Represent server principal name in Ticket 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 serverlen does not include the terminating zero.

shishi_ticket_sname_set ()

int
shishi_ticket_sname_set (Shishi *handle,
                         Shishi_asn1 ticket,
                         Shishi_name_type name_type,
                         char *sname[]);

Set the server name field in the Ticket.

shishi_ticket_srealmserver_set ()

int
shishi_ticket_srealmserver_set (Shishi *handle,
                                Shishi_asn1 ticket,
                                const char *realm,
                                const char *server);

shishi_ticket_set_server ()

int
shishi_ticket_set_server (Shishi *handle,
                          Shishi_asn1 ticket,
                          const char *server);

shishi_ticket_realm_get ()

int
shishi_ticket_realm_get (Shishi *handle,
                         Shishi_asn1 ticket,
                         char **realm,
                         size_t *realmlen);

Extract realm from ticket.

shishi_ticket_realm_set ()

int
shishi_ticket_realm_set (Shishi *handle,
                         Shishi_asn1 ticket,
                         const char *realm);

Set the realm field in the Ticket.

shishi_ticket_get_enc_part_etype ()

int
shishi_ticket_get_enc_part_etype (Shishi *handle,
                                  Shishi_asn1 ticket,
                                  int32_t *etype);

Extract Ticket.enc-part.etype.

shishi_ticket_set_enc_part ()

int
shishi_ticket_set_enc_part (Shishi *handle,
                            Shishi_asn1 ticket,
                            int32_t etype,
                            uint32_t kvno,
                            const char *buf,
                            size_t buflen);

Set the encrypted enc-part field in the Ticket. The encrypted data is usually created by calling shishi_encrypt() on the DER encoded enc-part. To save time, you may want to use shishi_ticket_add_enc_part() instead, which calculates the encrypted data and calls this function in one step.

shishi_ticket_add_enc_part ()

int
shishi_ticket_add_enc_part (Shishi *handle,
                            Shishi_asn1 ticket,
                            Shishi_key *key,
                            Shishi_asn1 encticketpart);

Encrypts DER encoded EncTicketPart using key and stores it in the Ticket.

shishi_ticket_decrypt ()

int
shishi_ticket_decrypt (Shishi *handle,
                       Shishi_asn1 ticket,
                       Shishi_key *key,
                       Shishi_asn1 *encticketpart);

shishi_tkt_ticket ()

Shishi_asn1
shishi_tkt_ticket (Shishi_tkt *tkt);

Get ASN.1 Ticket structure from ticket.

shishi_tkt_ticket_set ()

void
shishi_tkt_ticket_set (Shishi_tkt *tkt,
                       Shishi_asn1 ticket);

Set the ASN.1 Ticket in the Ticket.

shishi_tkt_kdcrep ()

Shishi_asn1
shishi_tkt_kdcrep (Shishi_tkt *tkt);

Get ASN.1 KDCRep structure from ticket.

shishi_tkt_enckdcreppart ()

Shishi_asn1
shishi_tkt_enckdcreppart (Shishi_tkt *tkt);

Get ASN.1 EncKDCRepPart structure from ticket.

shishi_tkt_enckdcreppart_set ()

void
shishi_tkt_enckdcreppart_set (Shishi_tkt *tkt,
                              Shishi_asn1 enckdcreppart);

Set the EncKDCRepPart in the Ticket.

shishi_tkt_encticketpart ()

Shishi_asn1
shishi_tkt_encticketpart (Shishi_tkt *tkt);

Get ASN.1 EncTicketPart structure from ticket.

shishi_tkt_encticketpart_set ()

void
shishi_tkt_encticketpart_set (Shishi_tkt *tkt,
                              Shishi_asn1 encticketpart);

Set the EncTicketPart in the Ticket.

shishi_tkt_key ()

Shishi_key *
shishi_tkt_key (Shishi_tkt *tkt);

Get key used in ticket, by looking first in EncKDCRepPart and then in EncTicketPart. If key is already populated, it is not extracted again.

shishi_tkt_key_set ()

int
shishi_tkt_key_set (Shishi_tkt *tkt,
                    Shishi_key *key);

Set the key in the EncTicketPart.

shishi_tkt ()

int
shishi_tkt (Shishi *handle,
            Shishi_tkt **tkt);

Create a new ticket handle.

shishi_tkt2 ()

Shishi_tkt *
shishi_tkt2 (Shishi *handle,
             Shishi_asn1 ticket,
             Shishi_asn1 enckdcreppart,
             Shishi_asn1 kdcrep);

Create a new ticket handle.

shishi_tkt_pretty_print ()

void
shishi_tkt_pretty_print (Shishi_tkt *tkt,
                         FILE *fh);

Print a human readable representation of a ticket to file handle.

shishi_tkt_realm ()

int
shishi_tkt_realm (Shishi_tkt *tkt,
                  char **realm,
                  size_t *realmlen);

Extract realm of server in ticket.

shishi_tkt_client ()

int
shishi_tkt_client (Shishi_tkt *tkt,
                   char **client,
                   size_t *clientlen);

Represent client principal name in Ticket KDC-REP 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 clientlen does not include the terminating zero.

shishi_tkt_client_p ()

int
shishi_tkt_client_p (Shishi_tkt *tkt,
                     const char *client);

Determine if ticket is for specified client.

shishi_tkt_clientrealm ()

int
shishi_tkt_clientrealm (Shishi_tkt *tkt,
                        char **client,
                        size_t *clientlen);

Convert cname and realm fields from AS-REQ to printable principal name format. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length clientlen does not include the terminating zero.

shishi_tkt_clientrealm_p ()

int
shishi_tkt_clientrealm_p (Shishi_tkt *tkt,
                          const char *client);

Determine if ticket is for specified client principal.

shishi_tkt_clientrealm_set ()

int
shishi_tkt_clientrealm_set (Shishi_tkt *tkt,
                            const char *realm,
                            const char *client);

shishi_tkt_serverrealm_set ()

int
shishi_tkt_serverrealm_set (Shishi_tkt *tkt,
                            const char *realm,
                            const char *server);

shishi_tkt_build ()

int
shishi_tkt_build (Shishi_tkt *tkt,
                  Shishi_key *key);

shishi_tkt_lastreq ()

int
shishi_tkt_lastreq (Shishi_tkt *tkt,
                    char **lrtime,
                    size_t *lrtimelen,
                    int32_t lrtype);