Kerberos basics

Kerberos and HSI | Commands to know | Renewing tickets | Concepts and terms

The CISL High Performance Storage System (HPSS) uses HSI as its POSIX-compliant interface. HSI, in turn, uses Kerberos as an authentication mechanism.

Supercomputing system users do not need the Kerberos information to access HPSS.
See Logging in and managing files.

This document addresses only interactive use of HSI based on the Kerberos principal that matches your UCAR username. Using HSI for unattended file transfers with long-term role principals is different.

If your client machine uses role principals for HSI transfers, you do not need to worry about executing Kerberos commands yourself; you just invoke hsi without further ado.

Contact your division sysadmin/CSAC representative to find out if your machine is equipped with this infrastructure, or if there is one you should use that is so equipped. If your sysadmin does not manage role principals for you, see the examples below for how to automatically renew your Kerberos tickets within scripts.


Kerberos and HSI

To use HSI on some NCAR systems that are outside of the supercomputing environment, you will need to use Kerberos credentials as described here.

Log in to the system, then execute command kinit.

Enter your UCAS password.

Sample output:

Password for username@UCAR.EDU
Warning: Your password will expire in 137 days on Sun Jul 20 14:26:11 2014

Execute klist. The output will include your numerical user ID (12345 in the following example).

Ticket cache: FILE:/tmp/krb5cc_12345
Default principal: username@UCAR.EDU
Valid starting Expires Service principal
03/05/15 15:07:39 03/06/15 15:07:39 krbtgt/UCAR.EDU@UCAR.EDU

Execute hsi as follows, making sure to include -c and the text that you see after FILE: in the first line of the previous output.

$ hsi -c /tmp/krb5cc_12345

HSI should now work as usual until you log out of the system. See Managing files with HSI for how to use HSI commands.


Commands to know

There are four basic Kerberos client commands to be aware of. Examples of how they are used follow.

You can invoke these commands yourself only within your UNIX or Linux shell. You will get an error if you try to invoke Kerberos commands within HSI.

kinit—Authenticates with Kerberos as shown above. Once you have authenticated with Kerberos, you can invoke hsi and it won't ask you for anything further during your HSI session.

klist—Lists your ticket cache, which includes your ticket granting ticket and both current and expired HSI tickets.

kpasswd—Allows you to change your Kerberos password. The system will request your current password before allowing you to enter and confirm a new password.

kdestroy—Clears your ticket cache.

Defaults, output, and some syntax can differ between Kerberos clients, so refer to the man pages on the machine you are using to confirm the details.

Command examples

The examples below follow an intentional order. For these examples, assume a user "someuser" with uid (scientist number) 1234.

klist example

Log in to a target client machine on which you wish to use HSI. If you execute a klist command to list your tickets on a Linux system, you might see the following if you have no tickets.

$ klist
klist: No credentials cache found (ticket cache FILE:/tmp/krb5cc_1234)
Kerberos 4 ticket cache: /tmp/tkt1234
klist: You have no tickets cached

The ticket cache is placed in different places on different machines. You can always do a klist both to see your tickets and locate your credentials cache.

kinit example

For this example, we will authenticate, getting a ticket granting ticket, and list this out. Then hsi will be invoked, which will cause HSI to issue its own service ticket, and the ticket cache is listed again, to show both types of tickets.

$ kinit
Password for someuser@UCAR.EDU:
Warning: Your password will expire in 276 days on Sat Jan 15 17:47:38 2011

Note that the output indicates when your current password will expire. Use the kpasswd command to change your password to prevent it from expiring when this is close to happening (see below).

Also, the name is fully qualified with the Kerberos domain UCAR.EDU. If you see any other domain name here, you are in a different default domain and hsi will not work. In this case you should explicitly enter a fully qualified principal for yourself.

$ kinit someuser@ucar.edu

Use klist to list your tickets:

$ klist
Ticket cache: FILE:/tmp/krb5cc_1234
Default principal:someuser@UCAR.EDU
Valid starting Expires Service principal
04/14/15 15:59:59 04/15/15 15:59:59 krbtgt/UCAR.EDU@UCAR.EDU
Kerberos 4 ticket cache: /tmp/tkt1234
klist: You have no tickets cached

Note that starting and expiration times are associated with your listed ticket.

This is a ticket granting ticket from the service principal named "krbtgt/UCAR.EDU@UCAR.EDU" and it means you have been authenticated and can use HSI.

Now use HSI by executing hsi on the command line. Once your HSI session starts, exit (or quit) immediately. Execute klist again and you will see service tickets from HSI as well.

Valid starting           Expires                  Service principal
04/14/15 16:08:27  04/15/15 16:08:23 krbtgt/UCAR.EDU@UCAR.EDU
04/14/15 16:08:38  04/15/15 16:08:23 ftp/hpssmvr01.ucar.edu@UCAR.EDU

To start over, enter kdestroy to empty your ticket cache. Over time, as your tickets expire, they will still show up in your cache and it will get increasingly cluttered as you execute more klist commands. Using kdestroy will clean them out (and require you to re-authenticate with kinit, of course).

kpasswd example

One final example is to change your password. A typical sequence looks like the following.

$ kpasswd
Password for someuser@UCAR.EDU:
Enter new password: :
Enter it again: :
Password changed.

There are differences in how this is handled. Some clients require you to be authenticated (via kinit) to change your password, others don't.

The bottom line is, you can use HSI as long as you have authenticated and have a ticket granting ticket. This is a separate process with the KDC (the Kerberos service). If you aren't authenticated, and you invoke HSI, it will execute a kinit for you, and the KDC will prompt you for your Kerberos principal and password.


Renewing tickets

Requesting a renewable ticket can make it easier for you to make unattended transfers. The special kinit command shown below requests a renewable ticket that you can renew up to its final expiration date.

Typical ticket lifetimes are 24 hours, and renewable tickets can be renewed for up to 7 days. Follow the procedure below and take note of the values that are returned when you execute a klist command, which tells you definitively what you have.

If you want to renew a ticket, first ask for a renewable ticket that is good for 7 days, as shown:

$ kinit -r7d

Execute a klist command to verify the values that the system actually granted you.

Ticket cache: FILE:/tmp/krb5cc_1234
Default principal:someuser@UCAR.EDU
Valid starting Expires Service principal
12/07/15 13:00:05 12/08/15 13:00:01 krbtgt/UCAR.EDU@UCAR.EDU
renew until 12/12/15 15:48:44

The ticket will expire like an ordinary ticket in 24 hours, but you can renew multiple times before its expiration, until the final expiration date (Dec 12 in the example above). You must do the kinit command interactively because you will have to provide your Kerberos passphrase; this cannot be put into a cron job or other unattended situation.

To avoid storing your ticket in a /tmp director as shown above, you can define the environment variable KRB5CCNAME to specify the name of the credentials cache file. Make sure the directory that will contain the credentials cache has been created.

If you are using Korn shell, use the following command.

$ export KRB5CCNAME=~/.krbcc/MyOwn

If you are using csh or tcsh shell, use the following command.

$ setenv KRB5CCNAME ~/.krbcc/MyOwn

You can also specify the name of the credentials cache file using the -c option in the kinit and klist commands.

Once you have the renewable ticket, you can put the renewal in a script and cron it. The command to renew a ticket is:

$ kinit -R

You will not be asked for your Kerberos passphrase in this case.

To be safe, renew the ticket above twice a day until its expiration:

00 00 * * * kinit -R
00 12 * * * kinit -R

Concepts and terms

Kerberos is an authentication service. Authentication is the process of safely validating who you are to the HPSS archival system. The authentication is done by HSI contacting a service to do so. This (Kerberos) service is implemented on a separate server, with a set of functions and so on, just like any other service such as DNS, or a Web server or a mail service.

A Kerberos service operates in a domain, which in the case of HPSS/HSI is UCAR.EDU. Note the similarities and differences with UCAR's DNS domain, ucar.edu. The Kerberos domain looks like the DNS domain except that it is capitalized. This is a common Kerberos convention.

Both users, like yourself, and Kerberized services, like HPSS and HSI, make use of Kerberos.

A Kerberos domain is served by a Key Distribution Center (KDC), which is a server that maintains a database of users and Kerberized services and their passwords. Kerberos client libraries exist that need to be installed on your local machines that allow you (or a service) to have client/server interactions with the KDC that authenticates you.

Kerberos principals identify users and/or services. Principals are quite flexible and usually are administered according to site-adopted conventions. Login principals identify users in the way in which you normally think of login names. Role principals support both long-term unattended file transfers and group logins. Role principals are not accessible directly by the end user, as is your login principal, but require the KROLE infrastructure (contact your divisional sysadmin/CSAC representative about KROLE).

Kerberos authenticates users through a system of tickets. There are two basic types: One that authenticates you as an individual and one that authenticates HSI as a service.

The authentication process for an end user is as follows: you identify yourself to the KDC with your principal and a password. You will be authenticated if your principal and password are valid.

Kerberos gives you a ticket granting ticket if you are authenticated. This is a credential that tells Kerberized services who you are. It is given to you by a special service principal with the name "krbtgt/UCAR.EDU@UCAR.EDU."

When you use HSI, it will trust you based on the ticket granting ticket the KDC issued to you. HSI will then issue you its own tickets which grant you access to the HSI service itself. These tickets will be issued to you by HSI specific principals with names like:

ftp/hpssmvr01.ucar.edu@UCAR.EDU

or

ftp/hpssmvr02.ucar.edu@UCAR.EDU

Note: The HSI service principals are named after FTP for historical reasons, but in the examples above the "ftp" refers to a service name (HSI). The "hpssmvr01.ucar.edu" portion refers to a machine on which that service resides. The "UCAR.EDU" reference is the Kerberos realm you are in. These are common Kerberos conventions for naming principals.