logo_kerberos.gif

Difference between revisions of "Projects/Keytab ccache name parameters"

From K5Wiki
Jump to: navigation, search
(Profile changes)
(Build configuration additions)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{project-early}}
+
{{project-rel|1.11}}
{{project-target|1.11}}
 
   
This project is to make it possible for a build or configuration of krb5 to change the location of the default keytab, client keytab, and ccache using parameterized search lists.
+
This project is to make it possible for a build or configuration of krb5 to change the location of the default keytab, client keytab, and ccache using a parameterized string.
   
 
==Background==
 
==Background==
Line 13: Line 13:
 
* On Unix, the hardcoded default /tmp/krb5cc_{uid} for the default ccache, /etc/krb5.keytab for the default keytab, and /etc/krb5.client-keytab for the default client keytab
 
* On Unix, the hardcoded default /tmp/krb5cc_{uid} for the default ccache, /etc/krb5.keytab for the default keytab, and /etc/krb5.client-keytab for the default client keytab
   
There are two main problems with the current state of affairs:
+
Problems with this state of affairs include:
   
 
* If a collection of daemon processes are running as different uids and need to use different keytabs or client keytabs, they must currently use environment variables in order to do so, which is unwieldy on some operating systems.
 
* If a collection of daemon processes are running as different uids and need to use different keytabs or client keytabs, they must currently use environment variables in order to do so, which is unwieldy on some operating systems.
 
 
* The use of a shared temporary area for the default ccache on Unix systems carries inherent security risks relative to using a per-user temporary area (if the operating system supplies one). Although the login system can override this default by setting KRB5CCNAME, tickets obtained using kinit on a system without Kerberos login integration will use the per-uid default in /tmp.
 
* The use of a shared temporary area for the default ccache on Unix systems carries inherent security risks relative to using a per-user temporary area (if the operating system supplies one). Although the login system can override this default by setting KRB5CCNAME, tickets obtained using kinit on a system without Kerberos login integration will use the per-uid default in /tmp.
  +
* If an operating system vendor changes the hardcoded default (as Solaris did by moving the default keytab to /etc/krb5/krb5.keytab), then a build from source on that operating system will use different defaults from the vendor build.
   
 
==Requirements==
 
==Requirements==
   
 
* It must be possible for a group of processes, each running under a different UID, to use distinct keytabs and distinct client keytabs without each setting the KRB5_KTNAME or KRB5_CLIENT_KTNAME environment variables.
 
* It must be possible for a group of processes, each running under a different UID, to use distinct keytabs and distinct client keytabs without each setting the KRB5_KTNAME or KRB5_CLIENT_KTNAME environment variables.
 
  +
* It should be possible for a host or operating system to stop using /tmp for the default ccache.
* It should be possible for an operating system to gracefully migrate away from the use of /tmp for the default ccache.
 
 
 
* It should be possible to determine the default locations used by a build of krb5 from within a shell script.
 
* It should be possible to determine the default locations used by a build of krb5 from within a shell script.
 
 
* By default, a build of krb5 should use the same default ccache and keytab locations as the current system installation of krb5, if the system installation is new enough to report that information.
 
* By default, a build of krb5 should use the same default ccache and keytab locations as the current system installation of krb5, if the system installation is new enough to report that information.
   
 
==Design==
 
==Design==
   
The design of this project involves two building blocks (parameter expansion and search lists) and changes to the profile relations, build configuration, and krb5-config scripts.
 
  +
The design has three parts:
  +
* Make the default keytab and default client keytab names subject to parameter expansion.
  +
* Add a new profile variable for the default ccache name, also subject to parameter expansion.
  +
* Add support for overriding the default ccache and keytab names
  +
  +
We will make the default keytab names subject to parameter expansion, and will add a new profile variable for the default ccache name.
   
 
===Parameter expansion===
 
===Parameter expansion===
Line 42: Line 44:
 
* %{SYSTEM} -- Windows system folder
 
* %{SYSTEM} -- Windows system folder
 
* %{WINDOWS} -- Windows folder
 
* %{WINDOWS} -- Windows folder
* %{USERCONFIG} -- Windows per-user package config directory
+
* %{USERCONFIG} -- Windows per-user MIT krb5 config file dir
* %{COMMONCONFIG} -- Windows package config directory for all users
+
* %{COMMONCONFIG} -- Windows all-users MIT krb5 config file dir
 
* %{LIBDIR} -- Package library install directory
 
* %{LIBDIR} -- Package library install directory
 
* %{BINDIR} -- Package binary install directory
 
* %{BINDIR} -- Package binary install directory
* %{LIBEXEC} -- Package internal binary install directory
 
 
* %{SBINDIR} -- Package root binary install directory
 
* %{SBINDIR} -- Package root binary install directory
 
* %{TEMP} -- Temporary directory (e.g. /tmp)
 
* %{TEMP} -- Temporary directory (e.g. /tmp)
Line 52: Line 53:
 
* %{null} -- Empty string
 
* %{null} -- Empty string
   
Not all of these expansions are needed for the current purpose, but it makes sense to support them for consistency.
+
Not all of these parameters are needed for the current use, but it makes sense to support them for consistency with Heimdal.
   
===Search lists===
+
===Profile changes===
   
We will create a facility for searching an ordered list of default keytab or ccache names. The intended semantics are:
 
  +
default_keytab_name and default_client_keytab_name will be modified to perform parameter expansion on their values.
   
* Use the first value which exists
 
  +
A new variable default_ccache_name will be added, also subject to parameter expansion. It will be used if there is no KRB5CCNAME environment variable setting, and in preference to the build-time default.
* If no value exists, use the first value which we can create
 
* If no value can be created, use the first value
 
   
To make this work, we need new vtable functions for "exists" and "can be created". These vtable functions will operate on the residual part of the name rather than on ccache or keytab handles, since ccache or keytab resolution can cause have side effects for some types.
 
  +
===Build configuration additions===
   
To test whether filesystem-based ccaches and keytabs exist, we will use stat(). To test whether they can be created, we will use access(). Using access() has the unfortunate property of using the real UID for access control checks for a setuid program, but there isn't a great alternative.
 
  +
configure will support the DEFCCNAME, DEFKTNAME, and DEFCKTNAME variables (e.g. "./configure DEFCCNAME=DIR:/var/run/user/%{uid}/ccache"). Setting these variables will set the built-in defaults.
   
===Profile changes===
 
  +
The krb5-config script will be augmented to support --defccname, --defktname, and --defcktname options.
   
default_keytab_name and default_client_keytab_name will be modified to perform parameter expansion on their values. They will also support multiple values (by setting the variable multiple times), in which case the list of values will be searched as specified above.
 
  +
configure will support --with-krb5-config=PATH and --without-krb5-config. If a path is specified, or if a krb5-config program is in the path and no option is specified, the new krb5-config options will be used to set the built-in defaults (unless the defaults are set explicitly with variable assignments). If krb5-config does not support the new options, the usual defaults will be used.
   
A new variable default_ccache_name will be added, with the same semantics as above. It will be used if there is no KRB5CCNAME environment variable setting, and in preference to the build-time default.
 
  +
These changes are for Unix systems only. The Windows built-in defaults for ccache and keytabs will not change.
   
===krb5-config additions===
 
  +
==Testing==
   
The krb5-config script will be augmented to support --defccname, --defktname, and --defclientktname options. (TBD: format?)
 
  +
A simple test program will be used to exercise the path token expansion function.
   
===Build configuration additions===
 
  +
Python script test cases will be added to test parameter expansion in the profile variables.
   
TBD
 
  +
The build configuration changes will be tested by hand.
   
==Testing==
 
  +
==Documentation==
   
TBD
 
  +
Parameter expansion and the new profile variables will be documented in krb5_conf.rst.
   
==Documentation==
 
  +
New configure options will be documented in options2configure.rst.
   
TBD
 
  +
New krb5-config options will be documented in the krb5-config man page.
   
 
==Mailing list discussions==
 
==Mailing list discussions==
Line 95: Line 94:
 
==Release notes==
 
==Release notes==
   
TBD
 
  +
Administrator experience:
  +
* Add parameter expansion for default_keytab_name and default_client_keytab_name profile variables.
  +
* Add new default_ccache_name profile variable to override the built-in default credential cache name.
  +
* Add configure-time support for changing the built-in ccache and keytab names.
  +
* Add krb5-config options for displaying the built-in ccache and keytab names.
  +
* In the default build, use the system's built-in ccache and keytab names if they can be discovered using krb5-config.

Latest revision as of 14:00, 29 November 2012

This project was completed in release 1.11.


This project is to make it possible for a build or configuration of krb5 to change the location of the default keytab, client keytab, and ccache using a parameterized string.

Background

libkrb5 provides the concepts of the default ccache, default keytab, and default client keytab for a library context. (The default client keytab is new in 1.11; see Projects/Keytab_initiation.) The user-visible discovery mechanisms for these concepts at the moment are:

  • The KRB5CCNAME, KRB5_KTNAME, and KRB5_CLIENT_KTNAME environment variables
  • The default_keytab_name and default_client_keytab_name profile relations (there is no equivalent for the default ccache)
  • On Windows, registry settings for the default ccache
  • On Windows, the hardcoded default %TEMP%\krb5cc or %TMP%\krb5cc or {windir}\krb5cc for the default ccache, {windir}\krb5kt for the default keytab, and {windir}\krb5clientkt for the default client keytab.
  • On Unix, the hardcoded default /tmp/krb5cc_{uid} for the default ccache, /etc/krb5.keytab for the default keytab, and /etc/krb5.client-keytab for the default client keytab

Problems with this state of affairs include:

  • If a collection of daemon processes are running as different uids and need to use different keytabs or client keytabs, they must currently use environment variables in order to do so, which is unwieldy on some operating systems.
  • The use of a shared temporary area for the default ccache on Unix systems carries inherent security risks relative to using a per-user temporary area (if the operating system supplies one). Although the login system can override this default by setting KRB5CCNAME, tickets obtained using kinit on a system without Kerberos login integration will use the per-uid default in /tmp.
  • If an operating system vendor changes the hardcoded default (as Solaris did by moving the default keytab to /etc/krb5/krb5.keytab), then a build from source on that operating system will use different defaults from the vendor build.

Requirements

  • It must be possible for a group of processes, each running under a different UID, to use distinct keytabs and distinct client keytabs without each setting the KRB5_KTNAME or KRB5_CLIENT_KTNAME environment variables.
  • It should be possible for a host or operating system to stop using /tmp for the default ccache.
  • It should be possible to determine the default locations used by a build of krb5 from within a shell script.
  • By default, a build of krb5 should use the same default ccache and keytab locations as the current system installation of krb5, if the system installation is new enough to report that information.

Design

The design has three parts:

  • Make the default keytab and default client keytab names subject to parameter expansion.
  • Add a new profile variable for the default ccache name, also subject to parameter expansion.
  • Add support for overriding the default ccache and keytab names

We will make the default keytab names subject to parameter expansion, and will add a new profile variable for the default ccache name.

Parameter expansion

We will adapt the Heimdal expand_path.c facility for our code. This facility supports the following parameter expansions:

  •  %{APPDATA} -- Windows roaming application data directory for current user
  •  %{COMMON_APPDATA} -- Windows application data directory for all users
  •  %{LOCAL_APPDATA} -- Windows local application data directory for current user
  •  %{SYSTEM} -- Windows system folder
  •  %{WINDOWS} -- Windows folder
  •  %{USERCONFIG} -- Windows per-user MIT krb5 config file dir
  •  %{COMMONCONFIG} -- Windows all-users MIT krb5 config file dir
  •  %{LIBDIR} -- Package library install directory
  •  %{BINDIR} -- Package binary install directory
  •  %{SBINDIR} -- Package root binary install directory
  •  %{TEMP} -- Temporary directory (e.g. /tmp)
  •  %{USERID} or %{uid} -- Current uid (or string representation of Windows SID)
  •  %{null} -- Empty string

Not all of these parameters are needed for the current use, but it makes sense to support them for consistency with Heimdal.

Profile changes

default_keytab_name and default_client_keytab_name will be modified to perform parameter expansion on their values.

A new variable default_ccache_name will be added, also subject to parameter expansion. It will be used if there is no KRB5CCNAME environment variable setting, and in preference to the build-time default.

Build configuration additions

configure will support the DEFCCNAME, DEFKTNAME, and DEFCKTNAME variables (e.g. "./configure DEFCCNAME=DIR:/var/run/user/%{uid}/ccache"). Setting these variables will set the built-in defaults.

The krb5-config script will be augmented to support --defccname, --defktname, and --defcktname options.

configure will support --with-krb5-config=PATH and --without-krb5-config. If a path is specified, or if a krb5-config program is in the path and no option is specified, the new krb5-config options will be used to set the built-in defaults (unless the defaults are set explicitly with variable assignments). If krb5-config does not support the new options, the usual defaults will be used.

These changes are for Unix systems only. The Windows built-in defaults for ccache and keytabs will not change.

Testing

A simple test program will be used to exercise the path token expansion function.

Python script test cases will be added to test parameter expansion in the profile variables.

The build configuration changes will be tested by hand.

Documentation

Parameter expansion and the new profile variables will be documented in krb5_conf.rst.

New configure options will be documented in options2configure.rst.

New krb5-config options will be documented in the krb5-config man page.

Mailing list discussions

http://mailman.mit.edu/pipermail/krbdev/2012-June/010907.html http://mailman.mit.edu/pipermail/krbdev/2012-June/010959.html

Release notes

Administrator experience:

  • Add parameter expansion for default_keytab_name and default_client_keytab_name profile variables.
  • Add new default_ccache_name profile variable to override the built-in default credential cache name.
  • Add configure-time support for changing the built-in ccache and keytab names.
  • Add krb5-config options for displaying the built-in ccache and keytab names.
  • In the default build, use the system's built-in ccache and keytab names if they can be discovered using krb5-config.