Skip to main content

Keytabs and Wallet

Introduction

The wallet is a system for managing keys and other secure data for systems. Among the types of secure data that it supports are Kerberos keytabs. It is the way nearly all keytabs for service principals at Stanford are managed.

Before following these instructions, please review review An Introduction to Keytabs. This explains principal naming and how keytabs are used.

Before using the wallet client, you will need to set up Kerberos on your system following the client installation instructions. You'll need the Kerberos software and krb5.conf installed.

Wallet is a free software project. You can obtain the source code and documentation from the wallet distribution page. It is based on the remctl protocol, which uses GSSAPI and Kerberos v5 to authenticate and encrypt a simple command/response network protocol.

Obtaining the wallet client

Debian systems

For Debian or Ubuntu systems, you can obtain wallet-client packages from the Stanford Debian repository. Add the following to your /etc/apt/sources.list file:

    deb http://debian.stanford.edu/debian-stanford stable main

and the following to /etc/apt/preferences (creating it if it doesn't exist):

    Package: *
    Pin: release o=Stanford
    Pin-Priority: 200

    Package: libremctl1
    Pin: release o=Stanford
    Pin-Priority: 600

Then, after aptitude update you should be able to install the wallet client with aptitude install wallet-client. This may require installation of a newer version of the remctl libraries.

This repository is not yet signed, so you may need to accept warnings about installing unsigned packages. We're working on upgrading to newer archive software.

Red Hat 4 systems

You can obtain the wallet-client packages from Stanford's yum repository (only accessible from on-campus systems). Add the following lines to your /etc/sysconfig/rhn/sources file:

    yum stanford-EL4 http://yum.stanford.edu/mrepo/stanford-EL4-$ARCH/RPMS.updates
    yum stanford-EL4-noarch http://yum.stanford.edu/mrepo/stanford-EL4-noarch/RPMS.updates

and install the public key for the repository:

    rpm --import http://yum.stanford.edu/STANFORD-GPG-KEY

You can then install the wallet-client package plus the remctl-client package that it depends on with:

    up2date remctl-client wallet-client

Red Hat 5 or newer systems

You can obtain the wallet-client packages from Stanford's yum repository (only accessible from on-campus systems). Create a new file named /etc/yum.repos.d/stanford.repo with the contents:

    # Name: Stanford RPMs for EL
    # URL: http://yum.stanford.edu/

    [stanford]
    name = Stanford RPMs for EL$releasever $basearch
    baseurl = http://yum.stanford.edu/mrepo/stanford-EL5-$basearch/RPMS.updates
    enabled = 1
    gpgkey = http://yum.stanford.edu/STANFORD-GPG-KEY
    gpgcheck = 1

    [stanford-noarch]
    name = Stanford RPMs for EL$releasever noarch
    baseurl = http://yum.stanford.edu/mrepo/stanford-EL5-noarch/RPMS.updates
    enabled = 1
    gpgkey = http://yum.stanford.edu/STANFORD-GPG-KEY
    gpgcheck = 1

and install the public key for the repository:

    rpm --import http://yum.stanford.edu/STANFORD-GPG-KEY

You can then install the wallet-client package plus the remctl-client package that it depends on with:

    yum install remctl-client wallet-client

Other systems

For other systems, you may need to build the wallet client yourself. You will need Kerberos development packages, and you will need to compile and install both remctl and wallet. You'll need to build and install remctl first, since it provides libraries used by the wallet client.

You can also instead log on to the one of the systems in the Remote Computing Facility and run wallet there, then copy the keytab to the system that will use it. If you do so, you should follow some precautions, since the keytab is essentially a password equivalent and should be treated with care:

  • Create a directory in /tmp, make it readable only by you with chmod 700, and then run wallet from that directory and download the keytab in that directory. This avoids storing the keytab in a network file system or where someone else may be able to read it.

  • Copy it to the system where it needs to live using a file copying method that uses encryption. This means using either scp (or sftp) or rcp -x.

Configuring the wallet client

However you obtain the wallet client, you need to configure it for which wallet server to use. Normally, this is done by adding the lines:

    wallet = {
        wallet_server     = wallet.stanford.edu
    }

to the [appdefaults] section of your krb5.conf file. If you build the wallet client yourself, you can specify wallet.stanford.edu as the default server. You can also specify wallet.stanford.edu with the -s command-line option each time you run wallet, but that's less convenient.

The standard Stanford krb5.conf file already contains this section.

Creating keytabs with wallet

The first step is to make sure that you have the appropriate rights to create the keytab. For all host-based service principals (ones based on the system name; see An Introduction to Keytabs for more information), the wallet by default uses NetDB as the authorization service. In order to create a host-based keytab for a system, you must be listed in NetDB as the user or administrator of that system or a member of an admin team for that system. The group setting is not used, only the user and administrator fields.

If you are not listed in the NetDB record, first fix that (either directly if you're an LNA or by asking your local LNA to make the change).

Once you are listed correctly in NetDB, you can create any host-based principal for that system. The service principal will automatically be created in Kerberos if it doesn't already exist.

If you need a non-host-based service principal (one of the form service/*), or if for some reason you cannot update NetDB, the principal must first be created in the wallet by a wallet administrator. Submit a Help ticket asking for a Kerberos service principal to be created and including who should have access to download keytabs for it and what the principal will be used for.

Once the access control is properly set up, you can create a keytab for a service principal with the command:

    kinit sunetid
    wallet -f file get keytab principal

sunetid should be your SUNet ID (or your /root instance if you have one; don't worry about that if you don't know what one is). principal should not include the realm (the @stanford.edu part at the end of a full Kerberos principal name). This will download a keytab for principal and put it in file. For a host/* principal, file should be /etc/krb5.keytab. This will use your existing Kerberos tickets for authentication to the wallet.

Instead of running kinit first, you can add the -u user flag to specify the user to authenticate as. You will then be prompted for that user's password. This is equivalent; it tells wallet to do the kinit internally.

For example, to download a WebAuth keytab for example.stanford.edu, use:

    kinit sunetid
    wallet -f keytab get keytab webauth/example.stanford.edu

Each time you run this command, it will invalidate any other keytabs for this principal. Usually, this is not an issue since the keytab for a given service principal only exists on one system.

For non-host-based principals, if you have a special need for a keytab for that principal to be stored on multiple systems, you can request that the keytab be marked unchanging in the wallet. To do this, submit a Help ticket specifying the service principal that should be marked unchanging and the rationale for why it this is needed. Marking keytabs unchanging is not recommended since it means the key is never changed and the service principal becomes more vulnerable to a brute-force attack.

Host-based principals should only be used on the host included in the principal name. University IT administrators will periodically purge from the wallet and from Kerberos all host-based keytabs for systems no longer registered in NetDB, so using a host-based keytab on a system other than the one for which it was issued risks having it deleted out from under your service.

Viewing keytab information

You can look at the information about any keytab for which you have access, including what ACLs are applied to that keytab, with the command:

    wallet show keytab principal

You can see the complete change and action history for a keytab with:

    wallet history keytab principal

Rekeying keytabs

We eventually plan to remove support for DES keys for security reasons.  Some keytabs downloaded in the past, when only DES was supported, may not have any encryption types but DES.  These keytabs will need to be updated before we can remove DES support.  Users affected by this change will be contacted multiple times before we actually disable DES, and will need to rekey the old keytabs.  Users who do not receive this contact do not need to rekey their keytabs for this reason, but still should do so periodically in order to get any new encryption types and to change important system keys to avoid long-term cracking attempts on their keys.

Rekeying a keytab is the process of taking an existing keytab and downloading new keys from wallet for every principal found in the keytab.  The net effect is that the keytab file will be updated for any new encryption types added to the Kerberos servers since it was created.  At the same time, it will keep the old keys in the keytab file in order to keep from invalidating any current use of that keytab.  This means that the keytab can be updated without breaking anything using it at the time you update, and anything using the keytab will quietly pick up the new keys as they re-authenticate normally.

wallet-rekey is available in versions of wallet from 0.12 onward.  You may use it by running, for keytabs for which you have access:

    wallet-rekey keytab

This will go through the given keytab and download new keys for any principal within it.  If an error occurs before any new keytabs were downloaded, wallet-rekey will abort.  If some new keys were successfully downloaded before an error, wallet-rekey warns about errors but continues to rekey all principals that it can.  In that case, a copy of the existing keytab prior to the rekeying is saved in a file named by appending ".old" to the keytab's file name.  Users should be able to use the new keytab, and can file a Help ticket with a copy of all errors if they need help understanding what went wrong.

Restricting encryption types

If you're creating a keytab for a Java application, be aware that the default Java runtime provided by Sun does not support the 256-bit AES keys used by preference in our Kerberos environment. Not only are they not supported, but at least some versions of Java do not correctly handle negotiation of key encryption types and will simply fail if you use a keytab that includes encryption types they don't understand. Some other, very old non-Java applications have similar problems.

If you need to use such software, you can tell the wallet to restrict the encryption types in the keytab you download to only those understood by the application you're using. You do this with the command:

    wallet setattr keytab principal enctypes enctype ...

where principal is the principal for which you're creating a keytab and enctype is a space-separated list of encryption types chosen from the following list: aes256-cts (256-bit AES), des3-cbc-sha1 (Triple-DES), and des-cbc-crc (single DES). We recommend including at least one encryption type stronger than single DES, and DES keys will eventually no longer be supported. You can include more than one encryption type and Kerberos software will automatically negotiate using the strongest one.

Troubleshooting

The wallet client tries to produce a useful error message if anything went wrong, but some Kerberos libraries aren't good about producing useful messages if there was an authentication failure. If you get a GSSAPI error, start by checking the following:

  • Make sure you can obtain Kerberos tickets with kinit and see those tickets with klist. If kinit doesn't work, Kerberos is generally not working on your system and you need to fix that problem first. (Often this is due to a missing /etc/krb5.conf file.)

  • The wallet client makes a connection to the wallet server on either port 4373 (the new port towards which we're migrating) or port 4444 (the old port). If you're behind a very restrictive firewall that limits outgoing connections, you may need to permit outgoing connections to those ports on wallet.stanford.edu. You must also be able to do a Kerberos authentication; see Kerberos and firewalls for more information.

  • The clock on your local system must be within five minutes of the time on the Kerberos servers for Kerberos to work. You can fix the clock by running ntpdate time.stanford.edu if you have ntpdate installed or by running a time setting daemon like ntpd.

  • If you are using an implementation of Kerberos that puts addresses in tickets and you have a DNS mismatch for your system or are behind address translation (NAT) of some kind, that will cause authentication failures. Ensure that your tickets do not contain address information by running klist -a and checking that the tickets have an address of "(none)". If they don't, try using kinit -A to get address-less tickets.

If you can successfully talk to the wallet server but you see permission errors for host-based principals, double-check the host information in NetDB and be sure that you're listed as a user or administrator of that node. You can do this without a NetDB account by running:

    whois -h whois.stanford.edu system.

where system is the host for which you're downloading a keytab. Don't forget the trailing period. This command must be run from an on-campus host.

Also, when downloading a host-based principal, make sure that the hostname in the principal is fully-qualified. In other words, host/example is wrong. host/example.stanford.edu is correct.

Last modified