Next: AP-REQ and AP-REP Functions, Previous: Initialization Functions, Up: Programming Manual [Contents][Index]
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
tkts: ticket set handle as allocated by shishi_tkts().
Description: Remove expired tickets from ticket set.
Return value: Returns SHISHI_OK iff successful.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Next: AP-REQ and AP-REP Functions, Previous: Initialization Functions, Up: Programming Manual [Contents][Index]