logo_kerberos.gif

Difference between revisions of "Projects/Keyring collection cache"

From K5Wiki
Jump to: navigation, search
(→‎Possible integration in the current KEYRING cache type)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  +
{{project-rel|1.12}}
  +
 
= Scope =
  
= Scope =
   
−
Implement a new Kernel based credential cache collection that uses the Keys API.
  
  +
Augment the KEYRING ccache type to support collections, and to support a new type of key which persists across multiple user login sessions until the ticket expires.
−  
−
The new cahe type is a collection and is store in a per-user keyring avaialble to any user session and that can persist in the system until expiration time even in the absence of an active user session.
  
   
 
= Background and previous work =
  
= Background and previous work =
Line 9: Line 9:
 
The MIT Kerberos code base already include a KEYRING ccache type that uses kernel keyrings to implement a credential cache modeled after the FILE cache type.
  
The MIT Kerberos code base already include a KEYRING ccache type that uses kernel keyrings to implement a credential cache modeled after the FILE cache type.
 
This cache type has 3 important limitations:
  
This cache type has 3 important limitations:
−
* Uses only session or process or thread based keyrings
 +
* It uses only session, process, or thread based keyrings. This means the cache cannot survive a user logout and cannot be shared between different sessions of the same user.
−
This means the cache cannot survive a user logout and cannot be shared between different sessions of the same user.
 +
* It uses the classic "user" key type. The "user" key type is limited in size because it uses non-swappable memory, so it has issues storing large tickets (like those including MS-PAC authdata) due to strict default quotas on this type of key.
−
* Uses the classic "user" key type
  
−
The "user" keytype is limited in size because use kernel locked memory so it has issues storing large tickets (like those including a MS-PAC AD) due to strict default quotas on this type of key
  
 
* It cannot represent cache collections.
  
* It cannot represent cache collections.
   
−
= DesignComponents =
  
  +
== Current keyring cache format ==
  +
  +
The current implementation creates a new keyring named after the residual and links it to either the session, process, or thread special keyrings.
  +
  +
This keyring contains one special key named "__krb5_princ__" which contains the cache principal name. Each credential is stored as a separate key in the same keyring. The __krb5_princ__ key and the credential keys use the "user" key type, and contain serialized representations of the principal name or credential as appropriate.
  +
  +
Example:
  +
KRB5CCNAME=KEYRING:testccache
  +
session
  +
\_testccache
  +
\_ __krb5_princ__
  +
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
  +
\_ krb5_ccache_conf_data/fast_avail/krbtgt\/TEST.KERBEROS.ORG\@TEST.KERBEROS.ORG@X-CACHECONF
  +
\_ krb5_ccache_conf_data/pa_type/krbtgt\/TEST.KERBEROS.ORG\@TEST.KERBEROS.ORG@X-CACHECONF
  +
\_ HTTP/http.test.kerberos.org@TEST.KERBEROS.ORG
  +
\_ ...
  +
  +
= Design components =
   
 
== Linux Kernel improvements ==
  
== Linux Kernel improvements ==
   
−
Addition of a new key type "big_key" that allows us to create keys
 +
Addition of a new key type "big_key" that allows us to create keys up to 1MiB in size, backed by internal kernel tmpfs, allowing the
−
up to 1MiB in size, backed by internal kernel tmpfs, allowing the
 +
contents to be swapped out to disk (unlike most other keyrings, which remain in unswappable kernel memory).
−
contents to be swapped out to disk (unlike most other keyrings, which
  
−
remain in unswappable kernel memory).
  
   
−
Creation of a new public interface, keyctl_get_krbcache(uid_t,
  
  +
Creation of a new public interface, keyctl_get_persistent. This API allows the user or a privileged process to access keys for a specified UID. This keyring is not tied to a session, so it can outlive a login session if there is a need to perform actions while not logged in, via a cron scripts or similar. This kernel keyring is created automatically on the first request if it does not yet exist.
−
key_serial_t id). This API allows the user (and certain privileged
  
−
root processes such as rpc.gssd and GSS-Proxy) to access the keys for
  
−
a particular UID. This keyring is not tied to a session (so it
  
−
can outlive a user on the system if they need to perform actions while
  
−
not logged in, such as cron scripts access to Secure NFS). The kernel
  
−
keyring is created automatically on the first request if it does not
  
−
yet exist.
  
   
 
Proposed patches by David Howells with explanatory comments on the kernel krbcache keyring:
  
Proposed patches by David Howells with explanatory comments on the kernel krbcache keyring:
 
http://mailman.mit.edu/pipermail/krbdev/2013-August/011650.html
  
http://mailman.mit.edu/pipermail/krbdev/2013-August/011650.html
  +
(note now renamed to 'persistent')
  +
  +
== Augmenting the current KEYRING cache type ==
  +
  +
The current keyring ccache type accepts the following residual forms:
  +
  +
* KEYRING:<name>
  +
* KEYRING:process:<name>
  +
* KEYRING:thread:<name>
  +
  +
where <name> is an arbitrary string. The first form implies the use of a session keyring.
  +
  +
libkrb5 will now accept new forms for the residual string:
  +
  +
* KEYRING:session:<name>
  +
* KEYRING:user:<name>
  +
* KEYRING:persistent:<uidnumber>
  +
  +
All residual forms will support cache collections.
  +
  +
The session and user keyrings use the session and user keyrings respectively. The new "persistent" form uses a special keyring as provided by the new keyutils call keyctl_get_persistent(). It requires support from the kernel for this new type; otherwise, it will fall back to the user keyring and the "user" key type.
  +
  +
Individual caches within the collection are identified and displayed by appending the specific cache keyring name to the main residual. For example:
  +
  +
KEYRING:persistent:123:krb_ccache_WE324ffdX
  +
  +
== New credential cache collection schema ==
  +
  +
A collection is represented with a keyring named "_krb_<name>", where <name> is from the residual string. The collection keyring links to a cache keyring for each cache within the collection, and also to a key named "krb_ccache:primary" of type "user", containing a serialized representation of the primary cache name.
  +
  +
Cache keyrings are named "krb_ccache_XXXXXX", where XXXXXX is a unique string. The format of a cache keyring is unchanged.
  +
  +
For the "thread", "process", "session", and "user" residual forms, the collection keyring is named "_krb_<name>" (where <name> is from the residual string) and is linked into the appropriate special keyring. For the "persistent" form, the cache keyring is named "_krb" and is linked to the persistent keyring.
  +
  +
When the classic session residual form ("KEYRING:<name>") is used, the first cache is handled specially. It is named with just the <name> from the residual string, and is linked to both the session keyring and to the "_krb_<name>" collection keyring.
  +
  +
Examples:
  +
* KRB5CCNAME=KEYRING:testccache
  +
session
  +
\_ testccache
  +
\_ __krb5_princ__
  +
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
  +
\_ ...
  +
\_ _krb_testccache
  +
\_ testccache <link to the key above>
  +
\_ krb_ccache_WQRQWTQ3
  +
\_ ...
  +
\_ krb_ccache:primary (points to testccache at collection cration)
  +
  +
* KRB5CCNAME=KEYRING:user:testusercc
  +
user
  +
\_ _krb_testusercc
  +
\_ krb_ccache_12WEF43f2
  +
\_ __krb5_princ__
  +
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
  +
\_ ...
  +
\_ krb_ccache_fdgsER324
  +
\_ ...
  +
\_ krb_ccache:primary (krb_ccache_12WEF43f2)
  +
  +
* KRB5CCNAME=KEYRING:persistent:123
  +
_persistent.123
  +
\_ _krb
  +
\_ krb_ccache_12WEF43f2
  +
\_ __krb5_princ__
  +
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
  +
\_ ...
  +
\_ krb_ccache_fdgsER324
  +
\_ ...
  +
\_ krb_ccache:primary (krb_ccache_12WEF43f2)
  +
  +
= Testing =
  +
  +
The new keyring functionality will be tested using the t_cccol.c and t_cc.c test programs, the existing tests in t_ccache.py, and new tests added to t_ccache.py to check for legacy session cache linkage.
  +
  +
= Documentation =
  +
  +
The KEYRING credential cache type is currently undocumented. If time permits, doc/basic/ccache_def.rst will be created and will document all credential types, including KEYRING with its new functionaliy.
  +
  +
= Mailing list discussions =
  +
  +
* http://mailman.mit.edu/pipermail/krbdev/2013-August/011648.html
  +
* http://mailman.mit.edu/pipermail/krbdev/2013-September/011774.html
   
  +
= Commits =
   
−
== Possible integration in the current KEYRING cache type ==
  
  +
* 620275cd43e237ab273b726b2aee0ae729587772 Add ccache collection tests using API
  +
* d7b94742daae85329067b126d0a4bc5b2ea7e4a0 Improve kinit output credential cache selection
  +
* 1f1b76ab8937c2cb0273cc5d8a7ee806240e1879 Add "which" function to k5test
  +
* 75b7ea9163e57ff0522f55a9cd0c2ab4b4974e38 Defer KEYRING key creation until initialize
  +
* 253155e1db678546358b69ab953f8fdd9b7fb23a Clarify variable names in cc_keyring.c
  +
* c1e8d03a6254e3ce86a71eed31e4c127e3324f9b Add collection support for KEYRING ccache type
  +
* 7c69a0372db5b7ed670ef3099a97942ede7a4739 Support new KEYRING anchor names and big_key keys
  +
* 5d03cb6b235f0ee0e30b34630f95f208d6acd3d0 Conditionally test KEYRING ccache type
   
−
libkrb5 will now accept a new value for the credential cache string
  
  +
= Tickets =
−
(for example: when used in KRB5CCNAME).
  
   
−
It will take the form:
  
  +
http://krbdev.mit.edu/rt/Ticket/Display.html?id=7711
−
KEYRING:krbcache:$UID
  
−
to represent a credential cache collection and
  
−
KEYRING:krbcache:$UID:tktXXXXX
  
−
to represent a specific key within a cache collection.
  
   
−
The new krbcache type wil create a special parent keyring as provided by the new keys call keyctl_get_krbcache()
  
  +
= Release notes =
   
−
In this keyring a key called krbcache:index will contain a 4 byte version number and the name of the current primary cache, pretty much like the 'primary' file contains the name of the primary cache for the DIR cache type.
  
  +
Administrator experience:
   
−
Each cache will be stored in a child keyring, the format used in this keyring is the same as used by the classic KEYRING cache types except that tickets will be store in keys of type "big_key" instead of using the "user" type.
  
  +
* Add collection support to the KEYRING credential cache type on Linux, and add support for persistent user keyrings and larger credentials on systems which support them.

Latest revision as of 08:38, 4 October 2013

This project was completed in release 1.12.


Scope

Augment the KEYRING ccache type to support collections, and to support a new type of key which persists across multiple user login sessions until the ticket expires.

Background and previous work

The MIT Kerberos code base already include a KEYRING ccache type that uses kernel keyrings to implement a credential cache modeled after the FILE cache type. This cache type has 3 important limitations:

  • It uses only session, process, or thread based keyrings. This means the cache cannot survive a user logout and cannot be shared between different sessions of the same user.
  • It uses the classic "user" key type. The "user" key type is limited in size because it uses non-swappable memory, so it has issues storing large tickets (like those including MS-PAC authdata) due to strict default quotas on this type of key.
  • It cannot represent cache collections.

Current keyring cache format

The current implementation creates a new keyring named after the residual and links it to either the session, process, or thread special keyrings.

This keyring contains one special key named "__krb5_princ__" which contains the cache principal name. Each credential is stored as a separate key in the same keyring. The __krb5_princ__ key and the credential keys use the "user" key type, and contain serialized representations of the principal name or credential as appropriate.

Example: KRB5CCNAME=KEYRING:testccache 

session
 \_testccache
    \_ __krb5_princ__
    \_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
    \_ krb5_ccache_conf_data/fast_avail/krbtgt\/TEST.KERBEROS.ORG\@TEST.KERBEROS.ORG@X-CACHECONF
    \_ krb5_ccache_conf_data/pa_type/krbtgt\/TEST.KERBEROS.ORG\@TEST.KERBEROS.ORG@X-CACHECONF
    \_ HTTP/http.test.kerberos.org@TEST.KERBEROS.ORG
    \_ ...

Design components

Linux Kernel improvements

Addition of a new key type "big_key" that allows us to create keys up to 1MiB in size, backed by internal kernel tmpfs, allowing the contents to be swapped out to disk (unlike most other keyrings, which remain in unswappable kernel memory).

Creation of a new public interface, keyctl_get_persistent. This API allows the user or a privileged process to access keys for a specified UID. This keyring is not tied to a session, so it can outlive a login session if there is a need to perform actions while not logged in, via a cron scripts or similar. This kernel keyring is created automatically on the first request if it does not yet exist.

Proposed patches by David Howells with explanatory comments on the kernel krbcache keyring: http://mailman.mit.edu/pipermail/krbdev/2013-August/011650.html (note now renamed to 'persistent')

Augmenting the current KEYRING cache type

The current keyring ccache type accepts the following residual forms:

  • KEYRING:<name>
  • KEYRING:process:<name>
  • KEYRING:thread:<name>

where <name> is an arbitrary string. The first form implies the use of a session keyring.

libkrb5 will now accept new forms for the residual string:

  • KEYRING:session:<name>
  • KEYRING:user:<name>
  • KEYRING:persistent:<uidnumber>

All residual forms will support cache collections.

The session and user keyrings use the session and user keyrings respectively. The new "persistent" form uses a special keyring as provided by the new keyutils call keyctl_get_persistent(). It requires support from the kernel for this new type; otherwise, it will fall back to the user keyring and the "user" key type.

Individual caches within the collection are identified and displayed by appending the specific cache keyring name to the main residual. For example: 

 KEYRING:persistent:123:krb_ccache_WE324ffdX

New credential cache collection schema

A collection is represented with a keyring named "_krb_<name>", where <name> is from the residual string. The collection keyring links to a cache keyring for each cache within the collection, and also to a key named "krb_ccache:primary" of type "user", containing a serialized representation of the primary cache name.

Cache keyrings are named "krb_ccache_XXXXXX", where XXXXXX is a unique string. The format of a cache keyring is unchanged.

For the "thread", "process", "session", and "user" residual forms, the collection keyring is named "_krb_<name>" (where <name> is from the residual string) and is linked into the appropriate special keyring. For the "persistent" form, the cache keyring is named "_krb" and is linked to the persistent keyring.

When the classic session residual form ("KEYRING:<name>") is used, the first cache is handled specially. It is named with just the <name> from the residual string, and is linked to both the session keyring and to the "_krb_<name>" collection keyring.

Examples:

  • KRB5CCNAME=KEYRING:testccache
session
 \_ testccache
     \_ __krb5_princ__
     \_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
     \_ ...
 \_ _krb_testccache
     \_ testccache <link to the key above>
     \_ krb_ccache_WQRQWTQ3
     \_ ...
     \_ krb_ccache:primary (points to testccache at collection cration)
  • KRB5CCNAME=KEYRING:user:testusercc
user
 \_ _krb_testusercc
     \_ krb_ccache_12WEF43f2
         \_ __krb5_princ__
         \_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
         \_ ...
     \_ krb_ccache_fdgsER324
     \_ ...
     \_ krb_ccache:primary (krb_ccache_12WEF43f2)
  • KRB5CCNAME=KEYRING:persistent:123
_persistent.123
 \_ _krb
     \_ krb_ccache_12WEF43f2
         \_ __krb5_princ__
         \_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
         \_ ...
     \_ krb_ccache_fdgsER324
     \_ ...
     \_ krb_ccache:primary (krb_ccache_12WEF43f2)

Testing

The new keyring functionality will be tested using the t_cccol.c and t_cc.c test programs, the existing tests in t_ccache.py, and new tests added to t_ccache.py to check for legacy session cache linkage.

Documentation

The KEYRING credential cache type is currently undocumented. If time permits, doc/basic/ccache_def.rst will be created and will document all credential types, including KEYRING with its new functionaliy.

Mailing list discussions

Commits

  • 620275cd43e237ab273b726b2aee0ae729587772 Add ccache collection tests using API
  • d7b94742daae85329067b126d0a4bc5b2ea7e4a0 Improve kinit output credential cache selection
  • 1f1b76ab8937c2cb0273cc5d8a7ee806240e1879 Add "which" function to k5test
  • 75b7ea9163e57ff0522f55a9cd0c2ab4b4974e38 Defer KEYRING key creation until initialize
  • 253155e1db678546358b69ab953f8fdd9b7fb23a Clarify variable names in cc_keyring.c
  • c1e8d03a6254e3ce86a71eed31e4c127e3324f9b Add collection support for KEYRING ccache type
  • 7c69a0372db5b7ed670ef3099a97942ede7a4739 Support new KEYRING anchor names and big_key keys
  • 5d03cb6b235f0ee0e30b34630f95f208d6acd3d0 Conditionally test KEYRING ccache type

Tickets

http://krbdev.mit.edu/rt/Ticket/Display.html?id=7711

Release notes

Administrator experience:

  • Add collection support to the KEYRING credential cache type on Linux, and add support for persistent user keyrings and larger credentials on systems which support them.
Retrieved from "https://k5wiki.kerberos.org/wiki?title=Projects/Keyring_collection_cache&oldid=5219"