Next: , Previous: Introduction, Up: Top


2 User Manual

Usually Shishi interacts with you to get some initial authentication information like a password, and then contacts a server to receive a so called ticket granting ticket. From now on, you rarely interact with Shishi directly. Applications that need security services instruct the Shishi library to use the ticket granting ticket to get new tickets for various servers. An example could be if you log on to a host remotely via ‘telnet’. The host usually requires authentication before permitting you in. The ‘telnet’ client uses the ticket granting ticket to get a ticket for the server, and then uses this ticket to authenticate you against the server (typically the server is also authenticated to you). You perform the initial authentication by typing shishi at the prompt. Sometimes it is necessary to supply options telling Shishi what your principal name (user name in the Kerberos realm) or your realm is. In the example, I specify the client name simon@JOSEFSSON.ORG.

     $ shishi simon@JOSEFSSON.ORG
     Enter password for `simon@JOSEFSSON.ORG':
     simon@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:44:49 2003
     Endtime:        Fri Aug 15 05:01:29 2003
     Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   INITIAL (512)
     $

As you can see, Shishi also prints a short description of the ticket received.

A logical next step is to display all tickets you have received. By the way, the tickets are usually stored as text in ~/.shishi/tickets. This is achieved by typing shishi --list.

     $ shishi --list
     Tickets in `/home/jas/.shishi/tickets':
     
     jas@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:49:46 2003
     Endtime:        Fri Aug 15 05:06:26 2003
     Server:         krbtgt/JOSEFSSON.ORG key des-cbc-md5 (3)
     Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
     Ticket flags:   INITIAL (512)
     
     jas@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:49:46 2003
     Starttime:      Fri Aug 15 04:49:49 2003
     Endtime:        Fri Aug 15 05:06:26 2003
     Server:         host/latte.josefsson.org key des-cbc-md5 (3)
     Ticket key:     des-cbc-md5 (3) protected by des-cbc-md5 (3)
     
     2 tickets found.
     $

As you can see, I had a ticket for the server ‘host/latte.josefsson.org’ which was generated by ‘telnet’:ing to that host.

If, for some reason, you want to manually get a ticket for a specific server, you can use the shishi --server-name command. Normally, however, the application that uses Shishi will take care of getting a ticket for the appropriate server, so you normally wouldn't need to issue this command.

     $ shishi --server-name=user/billg --encryption-type=des-cbc-md4
     jas@JOSEFSSON.ORG:
     Authtime:       Fri Aug 15 04:49:46 2003
     Starttime:      Fri Aug 15 04:54:33 2003
     Endtime:        Fri Aug 15 05:06:26 2003
     Server:         user/billg key des-cbc-md4 (2)
     Ticket key:     des-cbc-md4 (2) protected by des-cbc-md5 (3)
     $

As you can see, I acquired a ticket for ‘user/billg’ with a ‘des-cbc-md4’ (see Cryptographic Overview) encryption key specified with the ‘--encryption-type’ parameter.

To wrap up this introduction, let us see how you can remove tickets. You may want to do this if you leave your terminal for lunch or similar, and don't want someone to be able to copy the file and then use your credentials. Note that this only destroys the tickets locally, it does not contact any server telling that these credentials are no longer valid. So, if someone stole your ticket file, you must still contact your administrator and have them reset your account. Simply using this switch is not sufficient.

     $ shishi --server-name=imap/latte.josefsson.org --destroy
     1 ticket removed.
     $ shishi --server-name=foobar --destroy
     No tickets removed.
     $ shishi --destroy
     3 tickets removed.
     $

Since the ‘--server-name’ parameter takes a long string to type, it is possible to type the server name directly, after the client name. The following example demonstrates an AS-REQ followed by a TGS-REQ for a specific server (assuming you did not have any tickets to begin with).

     $ src/shishi simon@latte.josefsson.org imap/latte.josefsson.org
     Enter password for `simon@latte.josefsson.org':
     simon@latte.josefsson.org:
     Acquired:       Wed Aug 27 17:21:06 2003
     Expires:        Wed Aug 27 17:37:46 2003
     Server:         imap/latte.josefsson.org key aes256-cts-hmac-sha1-96 (18)
     Ticket key:     aes256-cts-hmac-sha1-96 (18) protected by aes256-cts-hmac-sha1-96 (18)
     Ticket flags:   FORWARDED PROXIABLE (12)
     $

Refer to the reference manual for all available parameters (see Parameters for shishi). The rest of this section contains descriptions of more specialized usage modes that can be ignored by most users.

2.1 Proxiable and Proxy Tickets

At times it may be necessary for a principal to allow a service to perform an operation on its behalf. The service must be able to take on the identity of the client, but only for a particular purpose. A principal can allow a service to take on the principal's identity for a particular purpose by granting it a proxy.

The process of granting a proxy using the proxy and proxiable flags is used to provide credentials for use with specific services. Though conceptually also a proxy, users wishing to delegate their identity in a form usable for all purpose MUST use the ticket forwarding mechanism described in the next section to forward a ticket-granting ticket.

The PROXIABLE flag in a ticket is normally only interpreted by the ticket-granting service. It can be ignored by application servers. When set, this flag tells the ticket-granting server that it is OK to issue a new ticket (but not a ticket-granting ticket) with a different network address based on this ticket. This flag is set if requested by the client on initial authentication. By default, the client will request that it be set when requesting a ticket-granting ticket, and reset when requesting any other ticket.

This flag allows a client to pass a proxy to a server to perform a remote request on its behalf (e.g. a print service client can give the print server a proxy to access the client's files on a particular file server in order to satisfy a print request).

In order to complicate the use of stolen credentials, Kerberos tickets are usually valid from only those network addresses specifically included in the ticket[4]. When granting a proxy, the client MUST specify the new network address from which the proxy is to be used, or indicate that the proxy is to be issued for use from any address.

The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. Application servers MAY check this flag and at their option they MAY require additional authentication from the agent presenting the proxy in order to provide an audit trail.

Here is how you would acquire a PROXY ticket for the service ‘imap/latte.josefsson.org’:

     $ shishi jas@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
     Enter password for `jas@JOSEFSSON.ORG':
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:02:35 2003
     Starttime:      Mon Sep  8 20:02:36 2003
     Endtime:        Tue Sep  9 04:02:35 2003
     Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   PROXY (16)
     $

As you noticed, this asked for your password. The reason is that proxy tickets must be acquired using a proxiable ticket granting ticket, which was not present. If you often need to get proxy tickets, you may acquire a proxiable ticket granting ticket from the start:

     $ shishi --proxiable
     Enter password for `jas@JOSEFSSON.ORG':
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:04:27 2003
     Endtime:        Tue Sep  9 04:04:27 2003
     Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   PROXIABLE INITIAL (520)

Then you should be able to acquire proxy tickets based on that ticket granting ticket, as follows:

     $ shishi jas@JOSEFSSON.ORG imap/latte.josefsson.org --proxy
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:04:27 2003
     Starttime:      Mon Sep  8 20:04:32 2003
     Endtime:        Tue Sep  9 04:04:27 2003
     Server:         imap/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   PROXY (16)
     $

2.2 Forwardable and Forwarded Tickets

Authentication forwarding is an instance of a proxy where the service that is granted is complete use of the client's identity. An example where it might be used is when a user logs in to a remote system and wants authentication to work from that system as if the login were local.

The FORWARDABLE flag in a ticket is normally only interpreted by the ticket-granting service. It can be ignored by application servers. The FORWARDABLE flag has an interpretation similar to that of the PROXIABLE flag, except ticket-granting tickets may also be issued with different network addresses. This flag is reset by default, but users MAY request that it be set by setting the FORWARDABLE option in the AS request when they request their initial ticket-granting ticket.

This flag allows for authentication forwarding without requiring the user to enter a password again. If the flag is not set, then authentication forwarding is not permitted, but the same result can still be achieved if the user engages in the AS exchange specifying the requested network addresses and supplies a password.

The FORWARDED flag is set by the TGS when a client presents a ticket with the FORWARDABLE flag set and requests a forwarded ticket by specifying the FORWARDED KDC option and supplying a set of addresses for the new ticket. It is also set in all tickets issued based on tickets with the FORWARDED flag set. Application servers may choose to process FORWARDED tickets differently than non-FORWARDED tickets.

If addressless tickets are forwarded from one system to another, clients SHOULD still use this option to obtain a new TGT in order to have different session keys on the different systems.

Here is how you would acquire a FORWARDED ticket for the service ‘host/latte.josefsson.org’:

     $ shishi jas@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
     Enter password for `jas@JOSEFSSON.ORG':
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:07:11 2003
     Starttime:      Mon Sep  8 20:07:12 2003
     Endtime:        Tue Sep  9 04:07:11 2003
     Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   FORWARDED (4)
     $

As you noticed, this asked for your password. The reason is that forwarded tickets must be acquired using a forwardable ticket granting ticket, which was not present. If you often need to get forwarded tickets, you may acquire a forwardable ticket granting ticket from the start:

     $ shishi --forwardable
     Enter password for `jas@JOSEFSSON.ORG':
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:08:53 2003
     Endtime:        Tue Sep  9 04:08:53 2003
     Server:         krbtgt/JOSEFSSON.ORG key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   FORWARDABLE INITIAL (514)
     $

Then you should be able to acquire forwarded tickets based on that ticket granting ticket, as follows:

     $ shishi jas@JOSEFSSON.ORG host/latte.josefsson.org --forwarded
     libshishi: warning: KDC bug: Reply encrypted using wrong key.
     jas@JOSEFSSON.ORG:
     Authtime:       Mon Sep  8 20:08:53 2003
     Starttime:      Mon Sep  8 20:08:57 2003
     Endtime:        Tue Sep  9 04:08:53 2003
     Server:         host/latte.josefsson.org key des3-cbc-sha1-kd (16)
     Ticket key:     des3-cbc-sha1-kd (16) protected by des3-cbc-sha1-kd (16)
     Ticket flags:   FORWARDED (4)
     $