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 (Section 6.7) or subsequent authentication (Section 6.8) and storing the new ticket in the ticket set are also provided.
To manipulate each individual ticket, Section 6.6. For low-level ASN.1 manipulation see Section 6.9.
char * shishi_tkts_default_file_guess ( void)
Guesses the default ticket filename; it is $HOME/.shishi/tickets.
Return value: Returns default tkts filename as a string that has to be deallocated with free() by the caller.
const char * shishi_tkts_default_file (Shishi * handle)
handle: Shishi library handle create by shishi_init().
Return value: Returns the default ticket set filename used in the library. (Not a copy of it, so don't modify or deallocate it.)
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.
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 * shishi_tkts_default (Shishi * handle)
handle: Shishi library handle create by shishi_init().
Return value: Return the handle global ticket set.
int shishi_tkts (Shishi * handle, Shishi_tkts ** tkts)
handle: shishi handle as allocated by shishi_init().
tkts: output pointer to newly allocated tkts handle.
Return value: Returns SHISHI_OK iff successful.
void shishi_tkts_done (Shishi_tkts ** tkts)
tkts: ticket set handle as allocated by shishi_tkts().
Deallocates all resources associated with ticket set. The ticket set handle must not be used in calls to other shishi_tkts_*() functions after this.
int shishi_tkts_size (Shishi_tkts * tkts)
tkts: ticket set handle as allocated by shishi_tkts().
Return value: Returns number of tickets stored in ticket set.
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.
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.
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.
Return value: Returns SHISHI_OK if succesful or if ticketno larger than size of ticket set.
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.
Return value: Returns SHISHI_OK iff succesful.
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.
Allocate a new ticket and add it to the ticket set.
Return value: Returns SHISHI_OK iff succesful.
int shishi_tkts_read (Shishi_tkts * tkts, FILE * fh)
tkts: ticket set handle as allocated by shishi_tkts().
fh: file descriptor to read from.
Read tickets from file descriptor and add them to the ticket set.
Return value: Returns SHISHI_OK iff succesful.
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.
Read tickets from file and add them to the ticket set.
Return value: Returns SHISHI_OK iff succesful.
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.
Write tickets in set to file descriptor.
Return value: Returns SHISHI_OK iff succesful.
int shishi_tkts_expire (Shishi_tkts * tkts)
tkts: ticket set handle as allocated by shishi_tkts().
Remove expired tickets from ticket set.
Return value: Returns SHISHI_OK iff succesful.
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.
Write tickets in set to file.
Return value: Returns SHISHI_OK iff succesful.
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.
Print description of tickets for specified service to file descriptor. If service is NULL, all tickets are printed.
Return value: Returns SHISHI_OK iff succesful.
int shishi_tkts_print (Shishi_tkts * tkts, FILE * fh)
tkts: ticket set handle as allocated by shishi_tkts().
fh: file descriptor to print to.
Print description of all tickets to file descriptor.
Return value: Returns SHISHI_OK iff succesful.
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.
Return value: Returns 0 iff ticket fails to match given criteria.
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.
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
Return value: Returns a ticket if found, or NULL if no further matching tickets could be found.
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.
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_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.
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_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.
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_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.
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_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 begot.
Get a ticket matching given characteristics. This function first looks in the ticket set for the ticket, then tries to find a suitable TGT, possibly via an AS exchange, using shishi_tkts_get_tgt(), and then use that TGT in a TGS exchange to get the ticket.
Currently this function do not implement cross realm logic.
Return value: Returns a ticket if found, or NULL if this function is unable to get the ticket.
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.
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_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.
Short-hand function for getting a ticket for the given server and the default principal client. See shishi_tkts_get().
Return value: Returns a ticket if found, or NULL.