5.3 Ticket Set Functions

A “ticket set” is, as the name implies, a collection of tickets. Functions are provided to read tickets from file into a ticket set, to query number of tickets in the set, to extract a given ticket from the set, to search the ticket set for tickets matching certain criterium, to write the ticket set to a file, etc. High level functions for performing a initial authentication (see AS Functions) or subsequent authentication (see TGS Functions) and storing the new ticket in the ticket set are also provided.

See Ticket Functions, to manipulate each individual ticket. See Ticket (ASN.1) Functions, for low-level ASN.1 manipulation.

shishi_tkts_default_file_guess

Function: char * shishi_tkts_default_file_guess (Shishi * handle)

handle: Shishi library handle create by shishi_init().

Description: Guesses the default ticket filename; it is SHISHI_TICKETS, SHISHI_HOME/tickets, or HOME/.shishi/tickets.

Return value: Returns default tkts filename as a string that has to be deallocated with free() by the caller.

shishi_tkts_default_file

Function: const char * shishi_tkts_default_file (Shishi * handle)

handle: Shishi library handle create by shishi_init().

Description: Get filename of default ticket set.

Return value: Returns the default ticket set filename used in the library. The string is not a copy, so don’t modify or deallocate it.

shishi_tkts_default_file_set

Function: void shishi_tkts_default_file_set (Shishi * handle, const char * tktsfile)

handle: Shishi library handle create by shishi_init().
tktsfile: string with new default tkts file name, or NULL to reset to default.

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

shishi_tkts_default

Function: Shishi_tkts * shishi_tkts_default (Shishi * handle)

handle: Shishi library handle create by shishi_init().

Description: Get the default ticket set for library handle.

Return value: Return the handle global ticket set.

shishi_tkts

Function: int shishi_tkts (Shishi * handle, Shishi_tkts ** tkts)

handle: shishi handle as allocated by shishi_init().
tkts: output pointer to newly allocated tkts handle.

Description: Get a new ticket set handle.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_done

Function: void shishi_tkts_done (Shishi_tkts ** tkts)

tkts: ticket set handle as allocated by shishi_tkts().

Description: Deallocates all resources associated with ticket set. The ticket set handle must not be used in calls to other shishi_tkts_*() functions after this.

shishi_tkts_size

Function: int shishi_tkts_size (Shishi_tkts * tkts)

tkts: ticket set handle as allocated by shishi_tkts().

Description: Get size of ticket set.

Return value: Returns number of tickets stored in ticket set.

shishi_tkts_nth

Function: Shishi_tkt * shishi_tkts_nth (Shishi_tkts * tkts, int ticketno)

tkts: ticket set handle as allocated by shishi_tkts().
ticketno: integer indicating requested ticket in ticket set.

Get the n: th ticket in ticket set.

Return value: Returns a ticket handle to the ticketno:th ticket in the ticket set, or NULL if ticket set is invalid or ticketno is out of bounds. The first ticket is ticketno 0, the second ticketno 1, and so on.

shishi_tkts_remove

Function: int shishi_tkts_remove (Shishi_tkts * tkts, int ticketno)

tkts: ticket set handle as allocated by shishi_tkts().
ticketno: ticket number of ticket in the set to remove. The first ticket is ticket number 0.

Description: Remove a ticket, indexed by ticketno, in ticket set.

Return value: SHISHI_OK if successful or if ticketno larger than size of ticket set.

shishi_tkts_add

Function: int shishi_tkts_add (Shishi_tkts * tkts, Shishi_tkt * tkt)

tkts: ticket set handle as allocated by shishi_tkts().
tkt: ticket to be added to ticket set.

Description: Add a ticket to the ticket set. Only the pointer is stored, so if you modify tkt, the ticket in the ticket set will also be modified.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_new

Function: int shishi_tkts_new (Shishi_tkts * tkts, Shishi_asn1 ticket, Shishi_asn1 enckdcreppart, Shishi_asn1 kdcrep)

tkts: ticket set handle as allocated by shishi_tkts().
ticket: input ticket variable.
enckdcreppart: input ticket detail variable.
kdcrep: input KDC-REP variable.

Description: Allocate a new ticket and add it to the ticket set.

Note that ticket, enckdcreppart and kdcrep are stored by reference, so you must not de-allocate them before the ticket is removed from the ticket set and de-allocated.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_read

Function: int shishi_tkts_read (Shishi_tkts * tkts, FILE * fh)

tkts: ticket set handle as allocated by shishi_tkts().
fh: file descriptor to read from.

Description: Read tickets from file descriptor and add them to the ticket set.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_from_file

Function: int shishi_tkts_from_file (Shishi_tkts * tkts, const char * filename)

tkts: ticket set handle as allocated by shishi_tkts().
filename: filename to read tickets from.

Description: Read tickets from file and add them to the ticket set.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_write

Function: int shishi_tkts_write (Shishi_tkts * tkts, FILE * fh)

tkts: ticket set handle as allocated by shishi_tkts().
fh: file descriptor to write tickets to.

Description: Write tickets in set to file descriptor.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_expire

Function: int shishi_tkts_expire (Shishi_tkts * tkts)

tkts: ticket set handle as allocated by shishi_tkts().

Description: Remove expired tickets from ticket set.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_to_file

Function: int shishi_tkts_to_file (Shishi_tkts * tkts, const char * filename)

tkts: ticket set handle as allocated by shishi_tkts().
filename: filename to write tickets to.

Description: Write tickets in set to file.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_print_for_service

Function: int shishi_tkts_print_for_service (Shishi_tkts * tkts, FILE * fh, const char * service)

tkts: ticket set handle as allocated by shishi_tkts().
fh: file descriptor to print to.
service: service to limit tickets printed to, or NULL.

Description: Print description of tickets for specified service to file descriptor. If service is NULL, all tickets are printed.

Return value: Returns SHISHI_OK iff successful.

shishi_tkts_print

Function: int shishi_tkts_print (Shishi_tkts * tkts, FILE * fh)

tkts: ticket set handle as allocated by shishi_tkts().
fh: file descriptor to print to.

Description: Print description of all tickets to file descriptor.

Return value: Returns SHISHI_OK iff successful.

shishi_tkt_match_p

Function: int shishi_tkt_match_p (Shishi_tkt * tkt, Shishi_tkts_hint * hint)

tkt: ticket to test hints on.
hint: structure with characteristics of ticket to be found.

Description: Test if a ticket matches specified hints.

Return value: Returns 0 iff ticket fails to match given criteria.

shishi_tkts_find

Function: Shishi_tkt * shishi_tkts_find (Shishi_tkts * tkts, Shishi_tkts_hint * hint)

tkts: ticket set handle as allocated by shishi_tkts().
hint: structure with characteristics of ticket to be found.

Description: Search the ticketset sequentially (from ticket number 0 through all tickets in the set) for a ticket that fits the given characteristics. If a ticket is found, the hint->startpos field is updated to point to the next ticket in the set, so this function can be called repeatedly with the same hint argument in order to find all tickets matching a certain criterium. Note that if tickets are added to, or removed from, the ticketset during a query with the same hint argument, the hint->startpos field must be updated appropriately.

Here is how you would typically use this function: Shishi_tkts_hint hint;

Shishi_tkt tkt;

memset(&hint, 0, sizeof(hint));

hint.server = "imap/mail.example.org";

tkt = shishi_tkts_find (shishi_tkts_default(handle), &hint);

if (!tkt)

printf("No ticket found...\n");

else

do_something_with_ticket (tkt);

Return value: Returns a ticket if found, or NULL if no further matching tickets could be found.

shishi_tkts_find_for_clientserver

Function: Shishi_tkt * shishi_tkts_find_for_clientserver (Shishi_tkts * tkts, const char * client, const char * server)

tkts: ticket set handle as allocated by shishi_tkts().
client: client name to find ticket for.
server: server name to find ticket for.

Description: Short-hand function for searching the ticket set for a ticket for the given client and server. See shishi_tkts_find().

Return value: Returns a ticket if found, or NULL.

shishi_tkts_find_for_server

Function: Shishi_tkt * shishi_tkts_find_for_server (Shishi_tkts * tkts, const char * server)

tkts: ticket set handle as allocated by shishi_tkts().
server: server name to find ticket for.

Description: Short-hand function for searching the ticket set for a ticket for the given server using the default client principal. See shishi_tkts_find_for_clientserver() and shishi_tkts_find().

Return value: Returns a ticket if found, or NULL.

shishi_tkts_get_tgt

Function: Shishi_tkt * shishi_tkts_get_tgt (Shishi_tkts * tkts, Shishi_tkts_hint * hint)

tkts: ticket set handle as allocated by shishi_tkts().
hint: structure with characteristics of ticket to begot.

Description: Get a ticket granting ticket (TGT) suitable for acquiring ticket matching the hint. I.e., get a TGT for the server realm in the hint structure (hint->serverrealm), or the default realm if the serverrealm field is NULL. Can result in AS exchange.

Currently this function do not implement cross realm logic.

This function is used by shishi_tkts_get(), which is probably what you really want to use unless you have special needs.

Return value: Returns a ticket granting ticket if successful, or NULL if this function is unable to acquire on.

shishi_tkts_get_tgs

Function: Shishi_tkt * shishi_tkts_get_tgs (Shishi_tkts * tkts, Shishi_tkts_hint * hint, Shishi_tkt * tgt)

tkts: ticket set handle as allocated by shishi_tkts().
hint: structure with characteristics of ticket to begot.
tgt: ticket granting ticket to use.

Description: Get a ticket via TGS exchange using specified ticket granting ticket.

This function is used by shishi_tkts_get(), which is probably what you really want to use unless you have special needs.

Return value: Returns a ticket if successful, or NULL if this function is unable to acquire on.

shishi_tkts_get

Function: Shishi_tkt * shishi_tkts_get (Shishi_tkts * tkts, Shishi_tkts_hint * hint)

tkts: ticket set handle as allocated by shishi_tkts().
hint: structure with characteristics of ticket to be found.

Description: Get a ticket matching given characteristics. This function first looks in the ticket set for a ticket, then tries to find a suitable TGT, possibly via an AS exchange, using shishi_tkts_get_tgt(), and then uses that TGT in a TGS exchange to get the ticket.

Currently this function does not implement cross realm logic.

Return value: Returns a ticket if found, or NULL if this function is unable to get the ticket.

shishi_tkts_get_for_clientserver

Function: Shishi_tkt * shishi_tkts_get_for_clientserver (Shishi_tkts * tkts, const char * client, const char * server)

tkts: ticket set handle as allocated by shishi_tkts().
client: client name to get ticket for.
server: server name to get ticket for.

Description: Short-hand function for getting a ticket for the given client and server. See shishi_tkts_get().

Return value: Returns a ticket if found, or NULL.

shishi_tkts_get_for_server

Function: Shishi_tkt * shishi_tkts_get_for_server (Shishi_tkts * tkts, const char * server)

tkts: ticket set handle as allocated by shishi_tkts().
server: server name to get ticket for.

Description: Short-hand function for getting a ticket to the given server and for the default principal client. See shishi_tkts_get().

Return value: Returns a ticket if found, or NULL.

shishi_tkts_get_for_localservicepasswd

Function: Shishi_tkt * shishi_tkts_get_for_localservicepasswd (Shishi_tkts * tkts, const char * service, const char * passwd)

tkts: ticket set handle as allocated by shishi_tkts().
service: service name to get ticket for.
passwd: password for the default client principal.

Description: Short-hand function for getting a ticket to the given local service, and for the default principal client. The latter’s password is given as argument. See shishi_tkts_get().

Return value: Returns a ticket if found, or NULL otherwise.