K5Wiki - User contributions [en]

Projects/ProxyGSSAPI

2017-05-23T12:37:53Z

Simo:

{{project-early}}

'''NOTE''': The actual project is now hosted and documented at: https://pagure.io/gssproxy

This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without giving access to long term keys to an application.
The proxy would be created at the mechglue layer so that any mechanism can be proxied.

= Background =

We have identified two main scenarios that benefit from this approach.

One is the ability to lock long term keys (especially the host/ key when the krb5 mechanism is used) into a trusted service on the system so that "less" trusted applications do not have direct access to the keys. This is a form of privilege separation that allows better control of the keys and reduces the attack surface of the system when it comes to gaining access to such keys.

The other is about trusting data being carried through, for example, krb5 tickets. In systems that use signed authorization data, it is fundamental for a "trusted" service to directly handle accepting a context so that it is impossible for an application to "fake" Authorization data by having access to the host keys and therefore being able to sign authorization data blobs.
As an example think of a user accessing a FTP daemon and sending a user credentials (MS-PAC/PAD) in the ticket. A trusted service need to be able to verify that the KDC actually did sign this data in order to trust its authenticity and allow the system to create a user out of this data. A way to fully trust this data when it is signed by the long term key is to not allow the FTP service to have access to the long term keys, so that a subverted service is not allowed to create fake data and sign it in order to perform privilege elevation attacks.

= Requirements =

In order to be able to implement this proxy it is fundamental to be able to create an IPC mechanism to transfer data from the process handling the GSSAPI exchange to the trusted service holding the keys and negotiating the security context.

This IPC mechanism should use a defined protocol so that independent implementations of the trusted service can be created.

Interface stability either at an API level (if an endpoint library is created) or at the protocol level is highly desirable but not fundamental.

= Considerations on the design =

There are a few challenges that need to be considered for this project.

== Access privileges ==

Currently access to credentials is determined base on file permissions. If the user/application have access to the keytab/credentials then it is allowed to use them for any purpose. By adding an IPC mechanism we need to also add a mechanism to determine what privileges the calling in process have.

One way to do this is by replicating the permission model on keytab files as permission on the directories containing the unix socket. One directory per credential/keytab with file system permissions et so only processes belonging to the user owner can access the IPC pipe.
On some systems it is also possible to inspect the credentials of the connecting process via special system calls on the socket. On those systems it is possible to decide to use a single socket and perform access control in the daemon.

== What to proxy ? ==

There are a few ways the proxy code can be designed.

a) Proxy everything unconditionally in any case
b) Have a flag or method call that can tell which mechanisms to proxy
c) Proxy on a per application based on per application configuration

Each of them may be desirable but there are a few drawbacks with each approach:

With (a) it may turn out that the mechanism will need access to long term secrets even after the security context has been established. That could be handled by passing in the long term keys with the export/import credentials function that is needed to transfer session keys.
This would render privilege separation useless though. Another option would be to provide extensions so mechanism can delegate these operation to the proxy, but this looks tricky.

With (b), mechanisms that cannot easily be proxied could be marked as such and not proxied. The issue here is that there are meta-mechs like SPNEGO that would have to deal with the saem flags and change behavior dynamically based on which mech is being probed. It is not unconceivable to make meta-mechs smart enough to do that but probably too much for a first release.

The problem with (c) is that it may require application changes to add the desired option, and in general you want a global policy. However a simplistic method to check whether to proxy or not could be for the GSSAPI to check if direct access to credentials is available and skip proxying in case direct access is possible.

== RPC mechanism ==

In order to proxy data around the IPC pipes need to be able to (un)marshal data back and forth.
There are a few options I can see to handle messaging.

After careful considreation it has been decided to use SUNRPC/XDR as the transport. The actual proxy server does not register to a RPC endpoint mapper but otherwise uses full RPC format on the wire and XDR encoding.

The actual protocol has been assigned number 400112 and is being documented in the [https://pagure.io/gssproxy/blob/master/f/proxy/docs/ProtocolDocumentation.md gss-proxy project]

The resons for choosing RPC/XDR were multiple.
* It is a wellknown encoding with a reasonable description language and a compiler for RPC stubs.
* Most krb5 projects already have bultin facilities to handle this protocol.
* Most kernels also already have support for handling SUNRPC/XDR from the NFS code.

The last point is relevant due to the fact that the Gss-Proxy concept aligns quite well also to the Kernel case where supporting GSSAPI authentication for NFS or CIFS server/clients is valuable but embedding a whle gss library is excessive. In this case using the gss-proxy protocol directly allows to use basic gssapi services easily without having to implement a full gssapi library in kernel.
A proof of concept implementation for using part of the protocol in the Linux kernel has been implemented and posted to LKML.

== Additional Considerations ==

The GSSAPI design is currently completely synchronous. By adding an IPC communication venue we increase the risk of stalling the application by blocking on socket operations while waiting for the trusted service to be scheduled and perform the needed operations.
Although this is not always desirable as it add latency, other parts of GSSAPI can add latency during accept/init phases. Some mechanism for example may perform blocking netowrk operations like DNS lookups as well.
Considering that the accept/init phases usually represent a very tiny amount of time compared to the life of a secured connection and considering that most of the time the connection setup already suffers from network latencies we think this is acceptable at this stage. Application can mitigate issues with blocking operations by confining GSSAPI related handling into a separate thread.

= Design =
(Draft)

The two main hooks for this functionality will be implemented in gss_accept_sec_context() for accepting 3rd party initiate security negotiations and gss_init_sec_context() for initializing a security context on the application behalf.

= Milestones =

* Introduce new RPC library with stub generator/IDL compiler
* Define the RPC interfaces to be implemented
* Introduce a new meta-mechanism that implements the client side of the proxy
* Create a simple server program for testing purposes

= Documentation =

See https://pagure.io/gssproxy

= Dependencies =

Interposer mechglue plugin mechanism

= Goal =

Have a working prototype for the 1.11 release

= Testing Plan =

Built client and server code as part of the GSS-Proxy project.

Projects/Improve GSSAPI mechanism configuration

2013-10-18T18:16:05Z

Simo:

{{project-early}}
{{project-target|1.13}}

==Requirements and scope==

The GSSAPI mechglue allows the installation of additional mechanisms, these mechanisms are currently sourced from the file /etc/gss/mech at library load time.

In order to improve management of additional mechanism as separate packages for distributions it would be easier if ech package could drop a configuration fragment in a separate file to activate a new installed plugin instead of changing a signle configuration file.

==Design==

A new directory owned by the GSSAPI library is created in /etc/gss/mech.d
In this directory packages can drop configuration fragments that use the exact same configuration format of the current /etc/gss/mech file.

After the main /etc/gss/mech file has been parsed, any file in this directory is opened and parsed to find additional mechanisms to load.

Projects/Improve GSSAPI mechanism configuration

2013-10-18T18:15:36Z

Simo: New page: ==Requirements and scope== The GSSAPI mechglue allows the installation of additional mechanisms, these mechanisms are currently sourced from the file /etc/gss/mech at library load time. ...

==Requirements and scope==

The GSSAPI mechglue allows the installation of additional mechanisms, these mechanisms are currently sourced from the file /etc/gss/mech at library load time.

In order to improve management of additional mechanism as separate packages for distributions it would be easier if ech package could drop a configuration fragment in a separate file to activate a new installed plugin instead of changing a signle configuration file.

==Design==

A new directory owned by the GSSAPI library is created in /etc/gss/mech.d
In this directory packages can drop configuration fragments that use the exact same configuration format of the current /etc/gss/mech file.

After the main /etc/gss/mech file has been parsed, any file in this directory is opened and parsed to find additional mechanisms to load.

Projects/Keyring collection cache

2013-08-28T20:50:44Z

Simo: /* New credential cache collection schema */

{{project-early}}

= 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 ccache 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 ccaches within the collection are identified and displayed by appending the specific ccache keyring name to the main residual. For example:

KEYRING:persistent:123:krb_ccache_WE324ffdX

== New credential cache collection schema ==

All KEYRING types become collection enabled. The only difference between the various types is where the cache keyrings are linked into.
Each credential cache in the collection has a name of the form "krb_ccache_XXXXXX", where XXXXXX is a unique string. The name of the currently active ccache is stored into a key named "krb_ccache:primary".

For the "thread", "process", "session", and "user" residual forms, the ccache keyring is stored in a keyring named "_krb_<name>" where <name> is the main part of the residual and linked into the appropriate special keyring. For the "persistent" form, the ccache keyring is named "_krb" and is linked to the persistent keyring. For backwards compatibility, the classic session residual form (the one identified by KEYRING:<name>) uses the <name> part of the residual for the first cache too, and the first ccache is linked both in the session keyring directly as well as the "_krb_<name>" collection keyring.

The format of a ccache keyring is unchanged from the classic scheme.

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)

Projects/Keyring collection cache

2013-08-20T18:51:58Z

Simo: /* New Credential Cache Collection schema */

{{project-early}}

= Scope =

Implement a new Kernel based credential cache collection that uses the Keys API.

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 =

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:
* Uses only session or 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.
* 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.

== Current Keyring cache format ==

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

This keyring contains one spaecial key named __krb5_princ__ that contain the ccache principal name.
Then each credential is stored as a separate key in the same keyring.

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
\_ ...

= DesignComponents =

== 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(uid_t,
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 there is the need to perform actions
while not logged in, such as cron scripts access to Secure NFS).
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 type implies the use of a session keyring.

libkrb5 will now accept a new values for the ccache name:

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

Also all the keyrings will now allow to create cache collections.

The session and user keyrings use the session and user's keyrings respecitively.
The new persistent type 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 fallback to use a user type keyring.

Individual ccache are identified and displayed by appending the specific ccache keyring name to the main residual:
Example:
KEYRING:persistent:123:krb_ccache_WE324ffdX

== New Credential Cache Collection schema ==

All KEYRING types become collection enabled, the only difference between the various types is where the ccache keyrings are linked into.
Each credential cache in the collection has a name of the form: krb_ccache_XXXXXX where XXXXXX is a random string and the name of the currently active ccache is stored into a key named krb_ccache:primary

All ccache keyring are furthemore stored in a keyring named fater the <name> part of the residual for keyring ccache of thread,process,session,user types, while in the case of the persistent keyring a keyring named _krb is created under the persistent keyring. For backwards compatibility reason on runtime upgrade the classic session keyring type (the one identified by KWYRING:<name>) uses the <name> part of the residual for the first ccache, so all the other ccache reside directly in the session keyring alongside the first one.

The format of a single ccache keyring is unchanged from the classic scheme.

Examples:
* KRB5CCNAME=KEYRING:testccache
session
\_ testccache
\_ __krb5_princ__
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
\_ ...
\_ krb_ccache_WQRQWTQ3
\_ ...
\_ krb_ccache:primary (points to testccache at collection cration)

* KRB5CCNAME=KEYRING:user:testusercc
user
\_ 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)

Projects/Keyring collection cache

2013-08-20T18:51:28Z

Simo: /* Augmenting the current KEYRING cache type */

{{project-early}}

= Scope =

Implement a new Kernel based credential cache collection that uses the Keys API.

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 =

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:
* Uses only session or 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.
* 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.

== Current Keyring cache format ==

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

This keyring contains one spaecial key named __krb5_princ__ that contain the ccache principal name.
Then each credential is stored as a separate key in the same keyring.

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
\_ ...

= DesignComponents =

== 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(uid_t,
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 there is the need to perform actions
while not logged in, such as cron scripts access to Secure NFS).
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 type implies the use of a session keyring.

libkrb5 will now accept a new values for the ccache name:

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

Also all the keyrings will now allow to create cache collections.

The session and user keyrings use the session and user's keyrings respecitively.
The new persistent type 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 fallback to use a user type keyring.

Individual ccache are identified and displayed by appending the specific ccache keyring name to the main residual:
Example:
KEYRING:persistent:123:krb_ccache_WE324ffdX

== New Credential Cache Collection schema ==

All KEYRING types become collection enabled, the only difference between the various types is where the ccache keyrings are linked into.
Each credential cache in the collection has a name of the form: krb_ccache_XXXXXX where XXXXXX is a random string and the name of the currently active ccache is stored into a key named krb_ccache:primary

All ccache keyring are furthemore stored in a keyring named fater the <name> part of the residual for keyring ccache of thread,process,session,user types, while in the case of the persistent keyring a keyring named _krb is created under the persistent keyring. For backwards compatibility reason on runtime upgrade the classic session keyring type (the one identified by KWYRING:<name>) uses the <name> part of the residual for the first ccache, so all the other ccache reside directly in the session keyring alongside the first one.

The format of a single ccache keyring is unchanged from the classic scheme.

Examples:
KRB5CCNAME=KEYRING:testccache
session
\_ testccache
\_ __krb5_princ__
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
\_ ...
\_ krb_ccache_WQRQWTQ3
\_ ...
\_ krb_ccache:primary (points to testccache at collection cration)

KRB5CCNAME=KEYRING:user:testusercc
user
\_ 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)

Projects/Keyring collection cache

2013-08-20T18:49:08Z

Simo:

{{project-early}}

= Scope =

Implement a new Kernel based credential cache collection that uses the Keys API.

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 =

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:
* Uses only session or 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.
* 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.

== Current Keyring cache format ==

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

This keyring contains one spaecial key named __krb5_princ__ that contain the ccache principal name.
Then each credential is stored as a separate key in the same keyring.

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
\_ ...

= DesignComponents =

== 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(uid_t,
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 there is the need to perform actions
while not logged in, such as cron scripts access to Secure NFS).
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 type implies the use of a session keyring.

libkrb5 will now accept a new values for the ccache name:

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

Also all the keyrings will now allow to create cache collections.

The session and user keyrings use the session and user's keyrings.
The new persistent type 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 fallback to use a user type keyring.

== New Credential Cache Collection schema ==

All KEYRING types become collection enabled, the only difference between the various types is where the ccache keyrings are linked into.
Each credential cache in the collection has a name of the form: krb_ccache_XXXXXX where XXXXXX is a random string and the name of the currently active ccache is stored into a key named krb_ccache:primary

All ccache keyring are furthemore stored in a keyring named fater the <name> part of the residual for keyring ccache of thread,process,session,user types, while in the case of the persistent keyring a keyring named _krb is created under the persistent keyring. For backwards compatibility reason on runtime upgrade the classic session keyring type (the one identified by KWYRING:<name>) uses the <name> part of the residual for the first ccache, so all the other ccache reside directly in the session keyring alongside the first one.

The format of a single ccache keyring is unchanged from the classic scheme.

Examples:
KRB5CCNAME=KEYRING:testccache
session
\_ testccache
\_ __krb5_princ__
\_ krbtgt/TEST.KERBEROS.ORG@TEST.KERBEROS.ORG
\_ ...
\_ krb_ccache_WQRQWTQ3
\_ ...
\_ krb_ccache:primary (points to testccache at collection cration)

KRB5CCNAME=KEYRING:user:testusercc
user
\_ 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)

Projects/Keyring collection cache

2013-08-20T18:06:05Z

Simo: /* Background and previous work */

Projects/Keyring collection cache

2013-08-20T17:24:10Z

Simo: /* Linux Kernel improvements */

Projects/Keyring collection cache

2013-08-20T17:22:39Z

Simo: /* Possible integration in the current KEYRING cache type */

Projects/Keyring collection cache

2013-08-06T03:01:04Z

Simo: /* Possible integration in the current KEYRING cache type */

Projects/Keyring collection cache

2013-08-02T01:22:14Z

Simo:

Projects/Keyring collection cache

2013-08-01T22:08:27Z

Simo: /* Possible integration in the current KEYRING cache type */

= Scope =

Implement a new Kernel based credential cache collection that uses the Keys API.

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 =

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:
* Uses only session or 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.
* 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.

= DesignComponents =

== 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_krbcache(uid_t,
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:
http://mailman.mit.edu/pipermail/krbdev/2013-August/011650.html

== Possible integration in the current KEYRING cache type ==

libkrb5 will now accept a new value for the credential cache string
(for example: when used in KRB5CCNAME).

It will take the form:
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()

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.

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.

Projects/Keyring collection cache

2013-08-01T21:57:46Z

Simo: New page: = Scope = Implement a new Kernel based credential cache collection that uses the Keys API. The new cahe type is a collection and is store in a per-user keyring avaialble to any user sess...

Projects/Interposer Mechanism

2012-10-02T21:30:10Z

Simo: /* Requirements */

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

* Interposer plugins must be able to intercept any mechanism function.
* Interposer plugins must also be able to call back into the mechglue in order to execute code using the original mechanism.
* Interposer mechanisms should be completely transparent to applications. A pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSSAPI function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugin SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. An interposer plugin specific
initialization function is used by the mechglue to initialize the plugin and retrieve the list of mechanism the interposer plugin wants to interpose.

Interposer plugins create special mech oids by concatenating the interposer mechanism and the original interposed mechanism oid.
This is needed in order to allow the interposer plugin to re-enter the mechglue avoiding loops.
These special oids are passed as input to gssapi functions that accept mechanism oids in input instad of the original mechanism oid.

The mechglue makes sure these oids are never leaked to applications, by providing a mapping back to normal public oids before they are returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for an interposer plugin that can intercept multiple mechanisms as it
has no way to understand which mechanism it is supposed to interpose on a specific request.
By passing in the public mechanism oid the mechglue
intended to use interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mechanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mechanism

2012-10-02T21:28:59Z

Simo: /* Design */

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSSAPI function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugin SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. An interposer plugin specific
initialization function is used by the mechglue to initialize the plugin and retrieve the list of mechanism the interposer plugin wants to interpose.

Interposer plugins create special mech oids by concatenating the interposer mechanism and the original interposed mechanism oid.
This is needed in order to allow the interposer plugin to re-enter the mechglue avoiding loops.
These special oids are passed as input to gssapi functions that accept mechanism oids in input instad of the original mechanism oid.

The mechglue makes sure these oids are never leaked to applications, by providing a mapping back to normal public oids before they are returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for an interposer plugin that can intercept multiple mechanisms as it
has no way to understand which mechanism it is supposed to interpose on a specific request.
By passing in the public mechanism oid the mechglue
intended to use interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mechanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mechanism

2012-10-02T21:28:13Z

Simo: /* Design */

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSs API function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugins SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. An interposer plugin specific
initialization function is used by the mechglue to initialize the plugin and retrieve the list of mechanism the interposer plugin wants to interpose.

Interposer plugins create special mech oids by concatenating the interposer mechanism and the original interposed mechanism oid.
This is needed in order to allow the interposer plugin to re-enter the mechglue avoiding loops.
These special oids are passed as input to gssapi functions that accept mechanism oids in input instad of the original mechanism oid.

The mechglue makes sure these oids are never leaked to applications, by providing a mapping back to normal public oids before they are returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for an interposer plugin that can intercept multiple mechanisms as it
has no way to understand which mechanism it is supposed to interpose on a specific request.
By passing in the public mechanism oid the mechglue
intended to use interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mechanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mechanism

2012-10-02T21:24:47Z

Simo: /* Design */

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSs API function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugins SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. They also exposes an interposer plugin specific
initialization function that is used by the mechglue to initialized the plugin
and also to retieve the list of mechanism the plugin wnats to interpose.

In order to allow the interposer plugin to re-enter the mechglue avoiding loops,
interposer plugins create special mech oids by concatenating the interposer mechanism and the original interposed mechanism oid and pass it as input to gssapi
functions that accept mechanism oids as input. The mechglue makes sure these oids
are never leaked to applications, by providing a mapping back to normal public
oids whenever they are passed to mechanisms or returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for an interposer plugin that can intercept multiple mechanisms as it
has no way to understand which mechanism it is supposed to interpose on a specific request.
By passing in the public mechanism oid the mechglue
intended to use interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mechanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mechanism

2012-10-02T21:12:41Z

Simo: Projects/Interposer Mehcanism moved to Projects/Interposer Mechanism

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSs API function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugins SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. They also exposes an interposer plugin specific
initialization function that is used by the mechglue to initialized the plugin
and also to retieve the list of mechanism the plugin wnats to interpose.

In order to allow the interposer plugin to re-enter the mechglue avoiding loops
interposer plugins create special invalid mech oids to pass as inputs to gssapi
functions that accept mech oids in input. The mechglue makes sure these oids
are never leaked to applications, by providing a mapping back to normal public
oids whenever they are passed to mechanisms or returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for an interposer plugin that can intercept multiple mechanisms as it
has no way to understand which mechanism it is supposed to interpose on a specific request.
By passing in the public mechanism oid the mechglue
intended to use interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mechanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mehcanism

2012-10-02T21:12:41Z

Simo: Projects/Interposer Mehcanism moved to Projects/Interposer Mechanism

#REDIRECT [[Projects/Interposer Mechanism]]

Projects/Interposer Mechanism

2012-10-02T21:12:16Z

Simo:

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSs API function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugins SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. They also exposes an interposer plugin specific
initialization function that is used by the mechglue to initialized the plugin
and also to retieve the list of mechanism the plugin wnats to interpose.

In order to allow the interposer plugin to re-enter the mechglue avoiding loops
interposer plugins create special invalid mech oids to pass as inputs to gssapi
functions that accept mech oids in input. The mechglue makes sure these oids
are never leaked to applications, by providing a mapping back to normal public
oids whenever they are passed to mechanisms or returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for an interposer plugin that can intercept multiple mechanisms as it
has no way to understand which mechanism it is supposed to interpose on a specific request.
By passing in the public mechanism oid the mechglue
intended to use interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mechanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mechanism

2012-10-02T21:09:41Z

Simo:

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Design =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSs API function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugins SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. They also exposes an interposer plugin specific
initialization function that is used by the mechglue to initialized the plguin
and also to retieve the list of mechanism the plugin wnats to interpose.

In order to allow the interposer plugin to re-enter the mechglue avoiding loops
interposer plugins create special invalid mech oids to pass as inputs to gssapi
functions that accept mech oids in input. The mechglue makes sure these oids
are never leaked to applications, by providing a mapping back to normal public
oids whenever they are passed to mechanisms or returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for interposer plugins that can intercept mutiple mechanisms as they
have no way to understand on which mechanism they are suppoed to act on behalf
of of the multiple ons that are being interposed.
By passing in the public mech oid of the interposed mechanism the mechglue
intended to use, interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mchanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

= Testing =

An interposer plugin with a test program is being worked on as part of the [https://fedorahosted.org/gss-proxy GSS-Proxy project]. that work will be used as a template for internal tests once it is complete. The internal test will simply loopback into gssapi. Thi will guarantee no regressions are introduced in the interposer interface.

Projects/Interposer Mechanism

2012-10-02T21:05:13Z

Simo:

{{project-early}}

This project is about creating a mechanism by which it is possible to intercept accepting and initializing a security context at the mechglue layer so that any mechanism can be ideally proxied to a separate application potentially running in a different security context.

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

= Architecture =

In order to allow interposer plugins to re-enter the mechglue we had to change their function signature so that the SPI does not match the GSs API function signatures, as interposer plugins are allowed to call back into GSSAPI.
The interposer plugins SPI uses the gssi_ prefix (GSS Interposer) for all the mechglue functions it implements.

The interposer plugins are specified in the gss.conf file with a new option
that identifies them as such. They also exposes an interposer plugin specific
initialization function that is used by the mechglue to initialized the plguin
and also to retieve the list of mechanism the plugin wnats to interpose.

In order to allow the interposer plugin to re-enter the mechglue avoiding loops
interposer plugins create special invalid mech oids to pass as inputs to gssapi
functions that accept mech oids in input. The mechglue makes sure these oids
are never leaked to applications, by providing a mapping back to normal public
oids whenever they are passed to mechanisms or returned to applications.

= Limitations =

Currently the mechglue code can handle only one interposer plugin
per-mechanism.

= New APIs =

Internal mechglue functions:
* gssint_select_mech_type()
* gssint_get_public_oid()
* gssint_make_public_oid_set()

Interposer initialization:
* gss_mech_interposer()

New mechanism functions:
* gssspi_import_sec_context_by_mech()
* gssspi_import_name_by_mech()
* gssspi_import_creD_by_mech()

Modified structures:
* gss_mech_info

== Internal mechglue functions ==

These new functions are used to aid the mechglue in finding the correct
mechanism to use when an interposer plugin is configured to intercept real
mechanisms.

=== gssint_select_mech_type() ===

This funciton is now called in the mechglue each time a mech oid is used as
input into a GSSAPI function. It correctly handles looking up by special OID
(if a interposer plugin is configured and returns the actual mechanism oid
to be used in case a mechanism has been interposed (typically the interposer
plugin mechanism).

=== gssint_get_public_oid() ===

This function always return the appropriate public oid associated with the
input oid which can be an actual public oid or a special interposer oid.

=== gssint_make_public_oid_set() ===

As the above but for oid sets.

== Interposer initialization ==

=== gss_mech_interposer() ===

This function is looked up right after an interposer plugin is dlopen()ed and
is called to initialize the plugin. It returns a list of mechanism to
interpose. The mechglue uses this information to properly set up information in
the gss_mech_info structure of the plugin and on the structures of the
interposed mechanisms.

== New mechanism functions ==

These functions are required to properly pass information to interposer
plugins. In particular the original functions did not pass to the interposer
plugin the oid of the mechanism these functions are supposed to act on. This is
a problem for interposer plugins that can intercept mutiple mechanisms as they
have no way to understand on which mechanism they are suppoed to act on behalf
of of the multiple ons that are being interposed.
By passing in the public mech oid of the interposed mechanism the mechglue
intended to use, interposer plugins can properly handle the request.

=== gssspi_import_sec_context_by_mech() ===

Same as gss_import_sec_context() but specifies the mechanism to use.

=== gssspi_import_name_by_mech() ===

Same as gss_import_name() but specifies the mechanism to use.

=== gssspi_import_cred_by_mech() ===

Same as gss_import_cred() but specifies the mechanism to use.

== Modified structures ==

Only one structure needed modifications:

=== gss_mech_info ===

This is the structure that describes internally a mechanism. In order to allow
GSSAPI to handle interposition this structure has now 3 new members:
* is_interposer
a boolean flag that is used to mark a mechanism as an interposer mechanism and not a real mchanism
* ine_mech_type
the oid of the interposer mechanism, it is set on real mechanisms
* int_mech
pointer to the interposer mechanism vtable

== New Functions Signatures ==

OM_uint32
gssint_select_mech_type(
OM_uint32 *minor,
gss_const_OID oid,
gss_OID *selected_oid
);

gss_OID
gssint_get_public_oid(
gss_const_OID oid
);

OM_uint32
gssint_make_public_oid_set(
OM_uint32 *minor_status,
gss_OID oids,
int count,
gss_OID_set *public_set
);

OM_uint32 gssspi_import_sec_context_by_mech(
OM_uint32 *minor_status,
gss_OID desired_mech,
gss_buffer_t interprocess_token,
gss_ctx_id_t *context_handle
);

OM_uint32 gssspi_import_name_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t *output_name
);

OM_uint32 gssspi_import_cred_by_mech(
OM_uint32 *minor_status,
gss_OID mech_type,
gss_buffer_t token,
gss_cred_id_t *cred_handle
);

gss_OID_set gss_mech_interposer(
gss_OID mech_type
);

Projects/Interposer Mechanism

2012-10-02T20:17:45Z

Simo:

Projects/Interposer Mechanism

2012-10-02T19:44:12Z

Simo:

Projects/Interposer Mechanism

2012-10-02T19:42:36Z

Simo:

{{project-early}}

= Background =

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] a new GSSAPI Mechanism interface has emerged. We call this kind of mechanism an '''Interposer Mechanism''' as it intercept all function calls for a specific mechanism.

The Interposer Mechanism instructs the mechglue layer on what mechanisms it wants to interpose. Once a mechnism is interposed the mechglue will always call the interposer for any function related to interposed mechanism.

The interposer plugin is responsible for handling the requested functionality, it can proxy it to another process (for example to the GSS-Proxy daemon) or can short-circuit it back to the mechglue in order to call the original mechanism handler.

= Requirements =

The Interposer mechanism must be able to intercept any mechanism function.
The Interposer mechanism must also be able to call back into the mechglue in order to execute code using the original mechanism.
The interposer mechanism should be completely transparent to applications, in that pure gssapi application should not need any modification in order to work with the interposer mechanism nor need to issue any special call to use the interposer functionality.

Projects/Interposer Mechanism

2012-10-02T19:34:02Z

Simo: New page: {{project-early}} = Background = During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the Projects/ProxyGSSAPI a new GSSAPI Mechanis...

Projects/ProxyGSSAPI

2012-10-02T19:28:59Z

Simo:

{{project-early}}

'''NOTE''': The actual project is now hosted and documented at: https://fedorahosted.org/gss-proxy

This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without giving access to long term keys to an application.
The proxy would be created at the mechglue layer so that any mechanism can be proxied.

= Background =

We have identified two main scenarios that benefit from this approach.

One is the ability to lock long term keys (especially the host/ key when the krb5 mechanism is used) into a trusted service on the system so that "less" trusted applications do not have direct access to the keys. This is a form of privilege separation that allows better control of the keys and reduces the attack surface of the system when it comes to gaining access to such keys.

The other is about trusting data being carried through, for example, krb5 tickets. In systems that use signed authorization data, it is fundamental for a "trusted" service to directly handle accepting a context so that it is impossible for an application to "fake" Authorization data by having access to the host keys and therefore being able to sign authorization data blobs.
As an example think of a user accessing a FTP daemon and sending a user credentials (MS-PAC/PAD) in the ticket. A trusted service need to be able to verify that the KDC actually did sign this data in order to trust its authenticity and allow the system to create a user out of this data. A way to fully trust this data when it is signed by the long term key is to not allow the FTP service to have access to the long term keys, so that a subverted service is not allowed to create fake data and sign it in order to perform privilege elevation attacks.

= Requirements =

In order to be able to implement this proxy it is fundamental to be able to create an IPC mechanism to transfer data from the process handling the GSSAPI exchange to the trusted service holding the keys and negotiating the security context.

This IPC mechanism should use a defined protocol so that independent implementations of the trusted service can be created.

Interface stability either at an API level (if an endpoint library is created) or at the protocol level is highly desirable but not fundamental.

= Considerations on the design =

There are a few challenges that need to be considered for this project.

== Access privileges ==

Currently access to credentials is determined base on file permissions. If the user/application have access to the keytab/credentials then it is allowed to use them for any purpose. By adding an IPC mechanism we need to also add a mechanism to determine what privileges the calling in process have.

One way to do this is by replicating the permission model on keytab files as permission on the directories containing the unix socket. One directory per credential/keytab with file system permissions et so only processes belonging to the user owner can access the IPC pipe.
On some systems it is also possible to inspect the credentials of the connecting process via special system calls on the socket. On those systems it is possible to decide to use a single socket and perform access control in the daemon.

== What to proxy ? ==

There are a few ways the proxy code can be designed.

a) Proxy everything unconditionally in any case
b) Have a flag or method call that can tell which mechanisms to proxy
c) Proxy on a per application based on per application configuration

Each of them may be desirable but there are a few drawbacks with each approach:

With (a) it may turn out that the mechanism will need access to long term secrets even after the security context has been established. That could be handled by passing in the long term keys with the export/import credentials function that is needed to transfer session keys.
This would render privilege separation useless though. Another option would be to provide extensions so mechanism can delegate these operation to the proxy, but this looks tricky.

With (b), mechanisms that cannot easily be proxied could be marked as such and not proxied. The issue here is that there are meta-mechs like SPNEGO that would have to deal with the saem flags and change behavior dynamically based on which mech is being probed. It is not unconceivable to make meta-mechs smart enough to do that but probably too much for a first release.

The problem with (c) is that it may require application changes to add the desired option, and in general you want a global policy. However a simplistic method to check whether to proxy or not could be for the GSSAPI to check if direct access to credentials is available and skip proxying in case direct access is possible.

== RPC mechanism ==

In order to proxy data around the IPC pipes need to be able to (un)marshal data back and forth.
There are a few options I can see to handle messaging.

After careful considreation it has been decided to use SUNRPC/XDR as the transport. The actual proxy server does not register to a RPC endpoint mapper but otherwise uses full RPC format on the wire and XDR encoding.

The actual protocol has been assigned number 400112 and is being documented in the [https://fedorahosted.org/gss-proxy/wiki/ProtocolDocumentation gss-proxy project]

The resons for choosing RPC/XDR were multiple.
* It is a wellknown encoding with a reasonable description language and a compiler for RPC stubs.
* Most krb5 projects already have bultin facilities to handle this protocol.
* Most kernels also already have support for handling SUNRPC/XDR from the NFS code.

The last point is relevant due to the fact that the Gss-Proxy concept aligns quite well also to the Kernel case where supporting GSSAPI authentication for NFS or CIFS server/clients is valuable but embedding a whle gss library is excessive. In this case using the gss-proxy protocol directly allows to use basic gssapi services easily without having to implement a full gssapi library in kernel.
A proof of concept implementation for using part of the protocol in the Linux kernel has been implemented and posted to LKML.

== Additional Considerations ==

The GSSAPI design is currently completely synchronous. By adding an IPC communication venue we increase the risk of stalling the application by blocking on socket operations while waiting for the trusted service to be scheduled and perform the needed operations.
Although this is not always desirable as it add latency, other parts of GSSAPI can add latency during accept/init phases. Some mechanism for example may perform blocking netowrk operations like DNS lookups as well.
Considering that the accept/init phases usually represent a very tiny amount of time compared to the life of a secured connection and considering that most of the time the connection setup already suffers from network latencies we think this is acceptable at this stage. Application can mitigate issues with blocking operations by confining GSSAPI related handling into a separate thread.

= Design =
(Draft)

The two main hooks for this functionality will be implemented in gss_accept_sec_context() for accepting 3rd party initiate security negotiations and gss_init_sec_context() for initializing a security context on the application behalf.

= Milestones =

* Introduce new RPC library with stub generator/IDL compiler
* Define the RPC interfaces to be implemented
* Introduce a new meta-mechanism that implements the client side of the proxy
* Create a simple server program for testing purposes

= Documentation =

See https://fedorahosted.org/gss-proxy

= Dependencies =

Interposer mechglue plugin mechanism

= Goal =

Have a working prototype for the 1.11 release

= Testing Plan =

Built client and server code as part of the GSS-Proxy project.

Projects/ProxyGSSAPI

2012-10-02T19:28:25Z

Simo:

{{project-early}}

NOTE: The actual project is now hosted and documented at: https://fedorahosted.org/gss-proxy

This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without giving access to long term keys to an application.
The proxy would be created at the mechglue layer so that any mechanism can be proxied.

= Background =

We have identified two main scenarios that benefit from this approach.

One is the ability to lock long term keys (especially the host/ key when the krb5 mechanism is used) into a trusted service on the system so that "less" trusted applications do not have direct access to the keys. This is a form of privilege separation that allows better control of the keys and reduces the attack surface of the system when it comes to gaining access to such keys.

The other is about trusting data being carried through, for example, krb5 tickets. In systems that use signed authorization data, it is fundamental for a "trusted" service to directly handle accepting a context so that it is impossible for an application to "fake" Authorization data by having access to the host keys and therefore being able to sign authorization data blobs.
As an example think of a user accessing a FTP daemon and sending a user credentials (MS-PAC/PAD) in the ticket. A trusted service need to be able to verify that the KDC actually did sign this data in order to trust its authenticity and allow the system to create a user out of this data. A way to fully trust this data when it is signed by the long term key is to not allow the FTP service to have access to the long term keys, so that a subverted service is not allowed to create fake data and sign it in order to perform privilege elevation attacks.

= Requirements =

In order to be able to implement this proxy it is fundamental to be able to create an IPC mechanism to transfer data from the process handling the GSSAPI exchange to the trusted service holding the keys and negotiating the security context.

This IPC mechanism should use a defined protocol so that independent implementations of the trusted service can be created.

Interface stability either at an API level (if an endpoint library is created) or at the protocol level is highly desirable but not fundamental.

= Considerations on the design =

There are a few challenges that need to be considered for this project.

== Access privileges ==

Currently access to credentials is determined base on file permissions. If the user/application have access to the keytab/credentials then it is allowed to use them for any purpose. By adding an IPC mechanism we need to also add a mechanism to determine what privileges the calling in process have.

One way to do this is by replicating the permission model on keytab files as permission on the directories containing the unix socket. One directory per credential/keytab with file system permissions et so only processes belonging to the user owner can access the IPC pipe.
On some systems it is also possible to inspect the credentials of the connecting process via special system calls on the socket. On those systems it is possible to decide to use a single socket and perform access control in the daemon.

== What to proxy ? ==

There are a few ways the proxy code can be designed.

a) Proxy everything unconditionally in any case
b) Have a flag or method call that can tell which mechanisms to proxy
c) Proxy on a per application based on per application configuration

Each of them may be desirable but there are a few drawbacks with each approach:

With (a) it may turn out that the mechanism will need access to long term secrets even after the security context has been established. That could be handled by passing in the long term keys with the export/import credentials function that is needed to transfer session keys.
This would render privilege separation useless though. Another option would be to provide extensions so mechanism can delegate these operation to the proxy, but this looks tricky.

With (b), mechanisms that cannot easily be proxied could be marked as such and not proxied. The issue here is that there are meta-mechs like SPNEGO that would have to deal with the saem flags and change behavior dynamically based on which mech is being probed. It is not unconceivable to make meta-mechs smart enough to do that but probably too much for a first release.

The problem with (c) is that it may require application changes to add the desired option, and in general you want a global policy. However a simplistic method to check whether to proxy or not could be for the GSSAPI to check if direct access to credentials is available and skip proxying in case direct access is possible.

== RPC mechanism ==

In order to proxy data around the IPC pipes need to be able to (un)marshal data back and forth.
There are a few options I can see to handle messaging.

After careful considreation it has been decided to use SUNRPC/XDR as the transport. The actual proxy server does not register to a RPC endpoint mapper but otherwise uses full RPC format on the wire and XDR encoding.

The actual protocol has been assigned number 400112 and is being documented in the [https://fedorahosted.org/gss-proxy/wiki/ProtocolDocumentation gss-proxy project]

The resons for choosing RPC/XDR were multiple.
* It is a wellknown encoding with a reasonable description language and a compiler for RPC stubs.
* Most krb5 projects already have bultin facilities to handle this protocol.
* Most kernels also already have support for handling SUNRPC/XDR from the NFS code.

The last point is relevant due to the fact that the Gss-Proxy concept aligns quite well also to the Kernel case where supporting GSSAPI authentication for NFS or CIFS server/clients is valuable but embedding a whle gss library is excessive. In this case using the gss-proxy protocol directly allows to use basic gssapi services easily without having to implement a full gssapi library in kernel.
A proof of concept implementation for using part of the protocol in the Linux kernel has been implemented and posted to LKML.

== Additional Considerations ==

The GSSAPI design is currently completely synchronous. By adding an IPC communication venue we increase the risk of stalling the application by blocking on socket operations while waiting for the trusted service to be scheduled and perform the needed operations.
Although this is not always desirable as it add latency, other parts of GSSAPI can add latency during accept/init phases. Some mechanism for example may perform blocking netowrk operations like DNS lookups as well.
Considering that the accept/init phases usually represent a very tiny amount of time compared to the life of a secured connection and considering that most of the time the connection setup already suffers from network latencies we think this is acceptable at this stage. Application can mitigate issues with blocking operations by confining GSSAPI related handling into a separate thread.

= Design =
(Draft)

The two main hooks for this functionality will be implemented in gss_accept_sec_context() for accepting 3rd party initiate security negotiations and gss_init_sec_context() for initializing a security context on the application behalf.

= Milestones =

* Introduce new RPC library with stub generator/IDL compiler
* Define the RPC interfaces to be implemented
* Introduce a new meta-mechanism that implements the client side of the proxy
* Create a simple server program for testing purposes

= Documentation =

See https://fedorahosted.org/gss-proxy

= Dependencies =

Interposer mechglue plugin mechanism

= Goal =

Have a working prototype for the 1.11 release

= Testing Plan =

Built client and server code as part of the GSS-Proxy project.

Projects/Credential Store extensions

2012-07-10T19:19:08Z

Simo: /* C bindings */

{{project-early}}

This project is about adding a set of extensions to GSSAPI to more easily handle credentials in a mechanism agnostic way.

== Background ==

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] project it became evident that the application implementing the proxy needs to be able to be configured to use different credentials depending on what application is connecting to the proxy. Using the normal defaults of GSSAPI is not possible because the proxy application does not run in the same process environment as the proxied application, and may run multiple concurrent tasks on behalf of different applications with different trust/credentials.

A method to pass a set of default credentials to use on behalf of these application is necessary. This method should not be mechanism-specific, as the proxy tries to be mechanism-agnostic as much as possible.

In this light a 'Credential Stores' Extension has been [http://www.ietf.org/mail-archive/web/kitten/current/msg03013.html proposed] on the Kitten IETF Mailing list.

== Requirements ==

* Abstract interface to pass credential store configuration to GSSAPI mechanisms.
* The credentials need to be specified in configuration files, so security sensitive information (like passwords) must not be exposed there.
* Mechanisms can define their own key/value pairs.
* New Key/Value pairs can be easily added in future.
* The mechglue need not to know how to interpret key/value pairs; they are interpreted only by mechanisms.

== Architecture ==

The exposed public functions are paired with analogous functions in the mechglue SPI to give mechanisms access to the Credentials Store.
The implementation provides functions only for mechanisms for which it makes sense--initially krb5 but not SPNEGO.

== New APIs ==

Functions:
* GSS_Acquire_cred_from()
* GSS_Add_cred_from()
* GSS_Store_cred_into()

Structures:
* gss_cred_store_element_struct
* gss_cred_store_struct

If the cred store structure does not contain a mechanism-specific configuration for the mechanism at hand, the usual defaults are applied.

=== gss_acquire_cred_from() ===

Acquires new credentials using the provided store. The store can specify both the actual credentials and/or the credential cache.
In the krb5 mechanism case it could specify a keytab and a ccache location.

=== gss_add_cred_from() ===

Same as above, but can target a specific mechanism. The credential store need not be mechanism-specific and remains abstract.

=== gss_store_cred_into() ===

This is analogous to gss_cred_store() except that a specific credential store can be specified (in the krb5 case, generally a ccache file).

=== gss_cred_store_element_struct ===

A urn/value pair.
Example:
URN = 'ccache'
Value = 'FILE:/tmp/somecc'

=== gss_cred_store_struct ===

A counter and an array of elements.

== C bindings ==

/* Extension for credential stores */
typedef struct gss_cred_store_element_struct {
const char *urn;
const char *value;
} gss_cred_store_element, *gss_cred_store_element_t;
typedef struct gss_cred_store_element gss_cred_store_element_t;

typedef struct gss_cred_store_struct {
OM_uint32 count;
gss_cred_store_element_t *elements;
} gss_cred_store, *gss_cred_store_t;
typedef const struct gss_cred_store_struct *gss_const_cred_store_t;

#define GSS_C_NO_CRED_STORE ((gss_const_cred_store_t) 0)

OM_uint32 gss_acquire_cred_from(
OM_uint32 *minor_status,
const gss_name_t desired_name,
OM_uint32 time_req,
gss_OID_set desired_mechs,
gss_cred_usage_t cred_usage,
gss_const_cred_store_t cred_store,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *time_rec);

OM_uint32 gss_add_cred_from (
OM_uint32 *minor_status,
gss_cred_id_t input_cred_handle,
gss_name_t desired_name,
gss_OID desired_mech,
gss_cred_usage_t cred_usage,
OM_uint32 initiator_time_req,
OM_uint32 acceptor_time_req,
gss_const_cred_store_t cred_store,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *initiator_time_rec,
OM_uint32 *acceptor_time_rec);

OM_uint32 gss_store_cred_into(
OM_uint32 *minor_status,
gss_cred_id_t input_cred_handle,
gss_cred_usage_t cred_usage,
gss_OID desired_mech,
OM_uint32 overwrite_cred,
OM_uint32 default_cred,
gss_const_cred_store_t cred_store,
gss_OID_set *elements_stored,
gss_cred_usage_t *cred_usage_stored);

Projects/Credential Store extensions

2012-05-05T15:24:07Z

Simo: /* C bindings */

{{project-early}}

This project is about adding a set of extensions to GSSAPI to more easily handle credentials in a mechanism agnostic way.

== Background ==

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] project it became evident that the application implementing the proxy needs to be able to be configured to use different credentials depending on what application is connecting to the proxy. Using the normal defaults of GSSAPI is not possible because the proxy application does not run in the same process environment as the proxied application, and may run multiple concurrent tasks on behalf of different applications with different trust/credentials.

A method to pass a set of default credentials to use on behalf of these application is necessary. This method should not be mechanism-specific, as the proxy tries to be mechanism-agnostic as much as possible.

In this light a 'Credential Stores' Extension has been [http://www.ietf.org/mail-archive/web/kitten/current/msg03013.html proposed] on the Kitten IETF Mailing list.

== Requirements ==

* Abstract interface to pass credential store configuration to GSSAPI mechanisms.
* The credentials need to be specified in configuration files, so security sensitive information (like passwords) must not be exposed there.
* Mechanisms can define their own key/value pairs.
* New Key/Value pairs can be easily added in future.
* The mechglue need not to know how to interpret key/value pairs; they are interpreted only by mechanisms.

== Architecture ==

The exposed public functions are paired with analogous functions in the mechglue SPI to give mechanisms access to the Credentials Store.
The implementation provides functions only for mechanisms for which it makes sense--initially krb5 but not SPNEGO.

== New APIs ==

Functions:
* GSS_Acquire_cred_from()
* GSS_Add_cred_from()
* GSS_Store_cred_into()

Structures:
* gss_cred_store_element_struct
* gss_cred_store_struct

If the cred store structure does not contain a mechanism-specific configuration for the mechanism at hand, the usual defaults are applied.

=== gss_acquire_cred_from() ===

Acquires new credentials using the provided store. The store can specify both the actual credentials and/or the credential cache.
In the krb5 mechanism case it could specify a keytab and a ccache location.

=== gss_add_cred_from() ===

Same as above, but can target a specific mechanism. The credential store need not be mechanism-specific and remains abstract.

=== gss_store_cred_into() ===

This is analogous to gss_cred_store() except that a specific credential store can be specified (in the krb5 case, generally a ccache file).

=== gss_cred_store_element_struct ===

A urn/value pair.
Example:
URN = 'ccache'
Value = 'FILE:/tmp/somecc'

=== gss_cred_store_struct ===

A counter and an array of elements.

== C bindings ==

/* Extension for credential stores */
typedef struct gss_cred_store_element_struct {
const char *urn;
const char *value;
} gss_cred_store_element, *gss_cred_store_element_t;
typedef struct gss_cred_store_element gss_cred_store_element_t;

typedef struct gss_cred_store_struct {
OM_uint32 count;
gss_cred_store_element_t *elements;
} gss_cred_store, *gss_cred_store_t;
typedef const struct gss_cred_store_struct *gss_const_cred_store_t;

#define GSS_C_NO_CRED_STORE ((gss_const_cred_store_t) 0)

OM_uint32 gss_acquire_cred_from(
OM_uint32 *minor_status,
const gss_name_t desired_name,
OM_uint32 time_req,
const gss_OID_set desired_mechs,
gss_cred_usage_t cred_usage,
gss_const_cred_store_t cred_store,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *time_rec);

OM_uint32 gss_add_cred_from (
OM_uint32 *minor_status,
const gss_cred_id_t input_cred_handle,
const gss_name_t desired_name,
const gss_OID desired_mech,
gss_cred_usage_t cred_usage,
OM_uint32 initiator_time_req,
OM_uint32 acceptor_time_req,
gss_const_cred_store_t cred_store,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *initiator_time_rec,
OM_uint32 *acceptor_time_rec);

OM_uint32 gss_store_cred_into(
OM_uint32 *minor_status,
gss_cred_id_t input_cred_handle,
gss_cred_usage_t cred_usage,
const gss_OID desired_mech,
OM_uint32 overwrite_cred,
OM_uint32 default_cred,
gss_const_cred_store_t cred_store,
gss_OID_set *elements_stored,
gss_cred_usage_t *cred_usage_stored);

Projects/Credential Store extensions

2012-05-03T20:50:42Z

Simo:

{{project-early}}

This project is about adding a set of extensions to GSSAPI to more easily handle credentials in a mechanism agnostic way.

== Background ==

During the development of the [https://fedorahosted.org/gss-proxy GSS-Proxy project] in connection with the [[Projects/ProxyGSSAPI]] project it became evident that the application implementing the proxy needs to be able to be configured to use different credentials depending on what application is connecting to the proxy.
Using the normal defaults of GSSAPI is not possible because the proxy application does not run in the same security context as the proxied application and it may run multiple concurrent tasks on behalf of different applications with different trust/credentials.

A method to pass a set of default credentials to use on behalf of these application is necessary. This method should not be mechanism specific, as the proxy tries to be mechanism agnostic as much as possible.

In this light a 'Credential Stores' Extension has been [http://www.ietf.org/mail-archive/web/kitten/current/msg03013.html proposed] on the Kitten IETF Mailing list.

== Requirements ==

* Abstract interface to pass credential store configuration to GSSAPI mechanisms.
* The credentials need to be specified in configuration files so no security sensitive information (like passwords) must be exposed there.
* Mechanisms can define their own key/value pairs
* New Key/Value pairs can be easily added in future
* The actual API need not to know how to interpret Key/Value pairs, they are passed directly to mechanisms

== Architecture ==

The exposed public functions are paired with an analogous one in the mechglue SPI to give mechanisms access to the Credentials Store.
The implementation provides functions only for mechanisms for which it makes sense, initially krb5 but not SPNEGO

== New APIs ==

Functions:
* GSS_Acquire_cred_from()
* GSS_Add_cred_from()
* GSS_Store_cred_into()

Structures:
* gss_cred_store_element_struct
* gss_cred_store_struct

If the cred store structure does not contain a mechanism specific configuration for the mechanism at hand gthe usual defaults are applied.

=== gss_aqcuire_cred_from() ===

Acquires new credentials using the provided store. The store can specify both the actual credentials and/or the credential cache.
In the Krb5 mechanism case it could specify a keytab and a ccache location.

=== gss_add_cred_from() ===

Same as above but can target a specific mechanism. The credential store need not be mechanism specific and re mains abstract.

=== gss_strore_cred_into() ===

This is analogous to gss_cred_store() except that a specific credential store can be specified (In the krb5 case generally a ccache file).

=== gss_cred_store_element_struct ===

A urn/value pair.
Example:
URN = 'ccache'
Value = 'FILE:/tmp/somecc'

=== gss_cred_store_struct ===

A counter and an array of elements.

== C bindings ==

/* Extension for credential stores */
typedef struct gss_cred_store_element_struct {
const char *urn;
const char *value;
} gss_cred_store_element, *gss_cred_store_element_t;
typedef const struct gss_cred_store_element gss_const_cred_store_element_t;

typedef struct gss_cred_store_struct {
OM_uint32 count;
gss_const_cred_store_element_t *elements;
} gss_cred_store, *gss_cred_store_t;
typedef const struct gss_cred_store_struct *gss_const_cred_store_t;

#define GSS_C_NO_CRED_STORE ((gss_const_cred_store_t) 0)

OM_uint32 gss_acquire_cred_from(
OM_uint32 *minor_status,
const gss_name_t desired_name,
OM_uint32 time_req,
const gss_OID_set desired_mechs,
gss_cred_usage_t cred_usage,
gss_const_cred_store_t cred_store,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *time_rec);

OM_uint32 gss_add_cred_from (
OM_uint32 *minor_status,
const gss_cred_id_t input_cred_handle,
const gss_name_t desired_name,
const gss_OID desired_mech,
gss_cred_usage_t cred_usage,
OM_uint32 initiator_time_req,
OM_uint32 acceptor_time_req,
gss_const_cred_store_t cred_store,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 *initiator_time_rec,
OM_uint32 *acceptor_time_rec);

OM_uint32 gss_store_cred_into(
OM_uint32 *minor_status,
gss_cred_id_t input_cred_handle,
gss_cred_usage_t cred_usage,
const gss_OID desired_mech,
OM_uint32 overwrite_cred,
OM_uint32 default_cred,
gss_const_cred_store_t cred_store,
gss_OID_set *elements_stored,
gss_cred_usage_t *cred_usage_stored);

Projects/Credential Store extensions

2012-05-03T20:48:31Z

Simo:

Projects/Credential Store extensions

2012-05-03T20:33:39Z

Simo: New page: {{project-early}} This project is about adding a set of extensions to GSSAPI to more easily handle credentials in a mechanism agnostic way. == Background == During the development of th...

Projects/ProxyGSSAPI

2012-05-03T20:15:37Z

Simo: /* RPC mechanism */

{{project-early}}

This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without giving access to long term keys to an application.
The proxy would be created at the mechglue layer so that any mechanism can be proxied.

= Background =

We have identified two main scenarios that benefit from this approach.

One is the ability to lock long term keys (especially the host/ key when the krb5 mechanism is used) into a trusted service on the system so that "less" trusted applications do not have direct access to the keys. This is a form of privilege separation that allows better control of the keys and reduces the attack surface of the system when it comes to gaining access to such keys.

The other is about trusting data being carried through, for example, krb5 tickets. In systems that use signed authorization data, it is fundamental for a "trusted" service to directly handle accepting a context so that it is impossible for an application to "fake" Authorization data by having access to the host keys and therefore being able to sign authorization data blobs.
As an example think of a user accessing a FTP daemon and sending a user credentials (MS-PAC/PAD) in the ticket. A trusted service need to be able to verify that the KDC actually did sign this data in order to trust its authenticity and allow the system to create a user out of this data. A way to fully trust this data when it is signed by the long term key is to not allow the FTP service to have access to the long term keys, so that a subverted service is not allowed to create fake data and sign it in order to perform privilege elevation attacks.

= Requirements =

In order to be able to implement this proxy it is fundamental to be able to create an IPC mechanism to transfer data from the process handling the GSSAPI exchange to the trusted service holding the keys and negotiating the security context.

This IPC mechanism should use a defined protocol so that independent implementations of the trusted service can be created.

Interface stability either at an API level (if an endpoint library is created) or at the protocol level is highly desirable but not fundamental.

= Considerations on the design =

There are a few challenges that need to be considered for this project.

== Access privileges ==

Currently access to credentials is determined base on file permissions. If the user/application have access to the keytab/credentials then it is allowed to use them for any purpose. By adding an IPC mechanism we need to also add a mechanism to determine what privileges the calling in process have.

One way to do this is by replicating the permission model on keytab files as permission on the directories containing the unix socket. One directory per credential/keytab with file system permissions et so only processes belonging to the user owner can access the IPC pipe.
On some systems it is also possible to inspect the credentials of the connecting process via special system calls on the socket. On those systems it is possible to decide to use a single socket and perform access control in the daemon.

== What to proxy ? ==

There are a few ways the proxy code can be designed.

a) Proxy everything unconditionally in any case
b) Have a flag or method call that can tell which mechanisms to proxy
c) Proxy on a per application based on per application configuration

Each of them may be desirable but there are a few drawbacks with each approach:

With (a) it may turn out that the mechanism will need access to long term secrets even after the security context has been established. That could be handled by passing in the long term keys with the export/import credentials function that is needed to transfer session keys.
This would render privilege separation useless though. Another option would be to provide extensions so mechanism can delegate these operation to the proxy, but this looks tricky.

With (b), mechanisms that cannot easily be proxied could be marked as such and not proxied. The issue here is that there are meta-mechs like SPNEGO that would have to deal with the saem flags and change behavior dynamically based on which mech is being probed. It is not unconceivable to make meta-mechs smart enough to do that but probably too much for a first release.

The problem with (c) is that it may require application changes to add the desired option, and in general you want a global policy. However a simplistic method to check whether to proxy or not could be for the GSSAPI to check if direct access to credentials is available and skip proxying in case direct access is possible.

== RPC mechanism ==

In order to proxy data around the IPC pipes need to be able to (un)marshal data back and forth.
There are a few options I can see to handle messaging.

After careful considreation it has been decided to use SUNRPC/XDR as the transport. The actual proxy server does not register to a RPC endpoint mapper but otherwise uses full RPC format on the wire and XDR encoding.

The actual protocol has been assigned number 400112 and is being documented in the [https://fedorahosted.org/gss-proxy/wiki/ProtocolDocumentation gss-proxy project]

The resons for choosing RPC/XDR were multiple.
* It is a wellknown encoding with a reasonable description language and a compiler for RPC stubs.
* Most krb5 projects already have bultin facilities to handle this protocol.
* Most kernels also already have support for handling SUNRPC/XDR from the NFS code.

The last point is relevant due to the fact that the Gss-Proxy concept aligns quite well also to the Kernel case where supporting GSSAPI authentication for NFS or CIFS server/clients is valuable but embedding a whle gss library is excessive. In this case using the gss-proxy protocol directly allows to use basic gssapi services easily without having to implement a full gssapi library in kernel.
A proof of concept implementation for using part of the protocol in the Linux kernel has been implemented and posted to LKML.

== Additional Considerations ==

The GSSAPI design is currently completely synchronous. By adding an IPC communication venue we increase the risk of stalling the application by blocking on socket operations while waiting for the trusted service to be scheduled and perform the needed operations.
Although this is not always desirable as it add latency, other parts of GSSAPI can add latency during accept/init phases. Some mechanism for example may perform blocking netowrk operations like DNS lookups as well.
Considering that the accept/init phases usually represent a very tiny amount of time compared to the life of a secured connection and considering that most of the time the connection setup already suffers from network latencies we think this is acceptable at this stage. Application can mitigate issues with blocking operations by confining GSSAPI related handling into a separate thread.

= Design =
(Draft)

The two main hooks for this functionality will be implemented in gss_accept_sec_context() for accepting 3rd party initiate security negotiations and gss_init_sec_context() for initializing a security context on the application behalf.

= Milestones =

* Introduce new RPC library with stub generator/IDL compiler
* Define the RPC interfaces to be implemented
* Introduce a new meta-mechanism that implements the client side of the proxy
* Create a simple server program for testing purposes

= Documentation =

TBD

= Dependencies =

TBD, potentially needs to rupdate the RPC code.

= Goal =

Have a working prototype for the 1.11 release

= Testing Plan =

TBD

Projects/ProxyGSSAPI

2011-08-23T20:04:23Z

Simo:

{{project-early}}

This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without giving access to long term keys to an application.
The proxy would be created at the mechglue layer so that any mechanism can be proxied.

= Background =

We have identified two main scenarios that benefit from this approach.

One is the ability to lock long term keys (especially the host/ key when the krb5 mechanism is used) into a trusted service on the system so that "less" trusted applications do not have direct access to the keys. This is a form of privilege separation that allows better control of the keys and reduces the attack surface of the system when it comes to gaining access to such keys.

The other is about trusting data being carried through, for example, krb5 tickets. In systems that use signed authorization data, it is fundamental for a "trusted" service to directly handle accepting a context so that it is impossible for an application to "fake" Authorization data by having access to the host keys and therefore being able to sign authorization data blobs.
As an example think of a user accessing a FTP daemon and sending a user credentials (MS-PAC/PAD) in the ticket. A trusted service need to be able to verify that the KDC actually did sign this data in order to trust its authenticity and allow the system to create a user out of this data. A way to fully trust this data when it is signed by the long term key is to not allow the FTP service to have access to the long term keys, so that a subverted service is not allowed to create fake data and sign it in order to perform privilege elevation attacks.

= Requirements =

In order to be able to implement this proxy it is fundamental to be able to create an IPC mechanism to transfer data from the process handling the GSSAPI exchange to the trusted service holding the keys and negotiating the security context.

This IPC mechanism should use a defined protocol so that independent implementations of the trusted service can be created.

Interface stability either at an API level (if an endpoint library is created) or at the protocol level is highly desirable but not fundamental.

= Considerations on the design =

There are a few challenges that need to be considered for this project.

== Access privileges ==

Currently access to credentials is determined base on file permissions. If the user/application have access to the keytab/credentials then it is allowed to use them for any purpose. By adding an IPC mechanism we need to also add a mechanism to determine what privileges the calling in process have.

One way to do this is by replicating the permission model on keytab files as permission on the directories containing the unix socket. One directory per credential/keytab with file system permissions et so only processes belonging to the user owner can access the IPC pipe.
On some systems it is also possible to inspect the credentials of the connecting process via special system calls on the socket. On those systems it is possible to decide to use a single socket and perform access control in the daemon.

== What to proxy ? ==

There are a few ways the proxy code can be designed.

a) Proxy everything unconditionally in any case
b) Have a flag or method call that can tell which mechanisms to proxy
c) Proxy on a per application based on per application configuration

Each of them may be desirable but there are a few drawbacks with each approach:

With (a) it may turn out that the mechanism will need access to long term secrets even after the security context has been established. That could be handled by passing in the long term keys with the export/import credentials function that is needed to transfer session keys.
This would render privilege separation useless though. Another option would be to provide extensions so mechanism can delegate these operation to the proxy, but this looks tricky.

With (b), mechanisms that cannot easily be proxied could be marked as such and not proxied. The issue here is that there are meta-mechs like SPNEGO that would have to deal with the saem flags and change behavior dynamically based on which mech is being probed. It is not unconceivable to make meta-mechs smart enough to do that but probably too much for a first release.

The problem with (c) is that it may require application changes to add the desired option, and in general you want a global policy. However a simplistic method to check whether to proxy or not could be for the GSSAPI to check if direct access to credentials is available and skip proxying in case direct access is possible.

== RPC mechanism ==

In order to proxy data around the IPC pipes need to be able to (un)marshal data back and forth.
There are a few options I can see to handle messaging.

a) Stick all data in a flat structure that uses no pointers and just shove a copy of the structure down the socket. If proper alignment is used for the structure than even hybrid32/64 bit systems should be able to exchange data between 32 bit and 64 bit processes without issues. On the other hand it is very easy to break such a protocol by simply changing the structure. It is also somewhat difficult to deal with variable size buffers and optional values.

b) Manually (un)marshal data in a custom crafted protocol. Not really appealing unless the data to be transfered is really simple and the variations/type of messages are very few and well defined.

c) Use an RPC library that has an IDL compiler/stub generator and all the tools necessary to automatically serialize structures and data. This is definitely the preferred solution when complex structures need to be passed around. Unfortunately the current MIT libraries lack an IDL compiler, so some updates/new dependencies would need to be introduced.

d) Defer the actual RPC mechanism by offloading data transfer to a pluggable library mechanism. This would offload the problem on the trusted service implementers. But it would also mean problems with interoperability and problems with testing in tree. Testing is especially important in order to prevent breakage.

The GSSAPI interfaces include some complex structures like channel bindings and session crdentials that need to be passed back and forth. So option (c) looks like the soundest approach.

== Additional Considerations ==

The GSSAPI design is currently completely synchronous. By adding an IPC communication venue we increase the risk of stalling the application by blocking on socket operations while waiting for the trusted service to be scheduled and perform the needed operations.
Although this is not always desirable as it add latency, other parts of GSSAPI can add latency during accept/init phases. Some mechanism for example may perform blocking netowrk operations like DNS lookups as well.
Considering that the accept/init phases usually represent a very tiny amount of time compared to the life of a secured connection and considering that most of the time the connection setup already suffers from network latencies we think this is acceptable at this stage. Application can mitigate issues with blocking operations by confining GSSAPI related handling into a separate thread.

= Design =
(Draft)

The two main hooks for this functionality will be implemented in gss_accept_sec_context() for accepting 3rd party initiate security negotiations and gss_init_sec_context() for initializing a security context on the application behalf.

= Milestones =

* Introduce new RPC library with stub generator/IDL compiler
* Define the RPC interfaces to be implemented
* Introduce a new meta-mechanism that implements the client side of the proxy
* Create a simple server program for testing purposes

= Documentation =

TBD

= Dependencies =

TBD, potentially needs to rupdate the RPC code.

= Goal =

Have a working prototype for the 1.11 release

= Testing Plan =

TBD

Projects/ProxyGSSAPI

2011-08-23T19:53:37Z

Simo:

{{project-early}}

This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without giving access to long term keys to an application.
The proxy would be created at the mechglue layer so that any mechanism can be proxied.

= Background =

We have identified two main scenarios that benefit from this approach.

One is the ability to lock long term keys (especially the host/ key when the krb5 mechanism is used) into a trusted service on the system so that "less" trusted applications do not have direct access to the keys. This is a form of privilege separation that allows better control of the keys and reduces the attack surface of the system when it comes to gaining access to such keys.

The other is about trusting data being carried through, for example, krb5 tickets. In systems that use signed authorization data, it is fundamental for a "trusted" service to directly handle accepting a context so that it is impossible for an application to "fake" Authorization data by having access to the host keys and therefore being able to sign authorization data blobs.
As an example think of a user accessing a FTP daemon and sending a user credentials (MS-PAC/PAD) in the ticket. A trusted service need to be able to verify that the KDC actually did sign this data in order to trust its authenticity and allow the system to create a user out of this data. A way to fully trust this data when it is signed by the long term key is to not allow the FTP service to have access to the long term keys, so that a subverted service is not allowed to create fake data and sign it in order to perform privilege elevation attacks.

= Requirements =

In order to be able to implement this proxy it is fundamental to be able to create an IPC mechanism to transfer data from the process handling the GSSAPI exchange to the trusted service holding the keys and negotiating the security context.

This IPC mechanism should use a defined protocol so that independent implementations of the trusted service can be created.

Interface stability either at an API level (if an endpoint library is created) or at the protocol level is highly desirable but not fundamental.

= Considerations on the design =

There are a few challenges that need to be considered for this project.

== Access privileges ==

Currently access to credentials is determined base on file permissions. If the user/application have access to the keytab/credentials then it is allowed to use them for any purpose. By adding an IPC mechanism we need to also add a mechanism to determine what privileges the calling in process have.

One way to do this is by replicating the permission model on keytab files as permission on the directories containing the unix socket. One directory per credential/keytab with file system permissions et so only processes belonging to the user owner can access the IPC pipe.
On some systems it is also possible to inspect the credentials of the connecting process via special system calls on the socket. On those systems it is possible to decide to use a single socket and perform access control in the daemon.

== What to proxy ? ==

There are a few ways the proxy code can be designed.

a) Proxy everything unconditionally in any case
b) Have a flag or method call that can tell which mechanisms to proxy
c) Proxy on a per application based on per application configuration

Each of them may be desirable but there are a few drawbacks with each approach:

With (a) it may turn out that the mechanism will need access to long term secrets even after the security context has been established. That could be handled by passing in the long term keys with the export/import credentials function that is needed to transfer session keys.
This would render privilege separation useless though. Another option would be to provide extensions so mechanism can delegate these operation to the proxy, but this looks tricky.

With (b), mechanisms that cannot easily be proxied could be marked as such and not proxied. The issue here is that there are meta-mechs like SPNEGO that would have to deal with the saem flags and change behavior dynamically based on which mech is being probed. It is not unconceivable to make meta-mechs smart enough to do that but probably too much for a first release.

The problem with (c) is that it may require application changes to add the desired option, and in general you want a global policy. However a simplistic method to check whether to proxy or not could be for the GSSAPI to check if direct access to credentials is available and skip proxying in case direct access is possible.

== RPC mechanism ==

In order to proxy data around the IPC pipes need to be able to (un)marshal data back and forth.
There are a few options I can see to handle messaging.

a) Stick all data in a flat structure that uses no pointers and just shove a copy of the structure down the socket. If proper alignment is used for the structure than even hybrid32/64 bit systems should be able to exchange data between 32 bit and 64 bit processes without issues. On the other hand it is very easy to break such a protocol by simply changing the structure. It is also somewhat difficult to deal with variable size buffers and optional values.

b) Manually (un)marshal data in a custom crafted protocol. Not really appealing unless the data to be transfered is really simple and the variations/type of messages are very few and well defined.

c) Use an RPC library that has an IDL compiler/stub generator and all the tools necessary to automatically serialize structures and data. This is definitely the preferred solution when complex structures need to be passed around. Unfortunately the current MIT libraries lack an IDL compiler, so some updates/new dependencies would need to be introduced.

d) Defer the actual RPC mechanism by offloading data transfer to a pluggable library mechanism. This would offload the problem on the trusted service implementers. But it would also mean problems with interoperability and problems with testing in tree. Testing is especially important in order to prevent breakage.

The GSSAPI interfaces include some complex structures like channel bindings and session crdentials that need to be passed back and forth. So option (c) looks like the soundest approach.

= Milestones =

* Introduce new RPC library with stub generator/IDL compiler
* Define the RPC interfaces to be implemented
* Introduce a new meta-mechanism that implements the client side of the proxy
* Create a simple server program for testing purposes

= Documentation =

TBD

= Dependencies =

TBD, potentially needs to rupdate the RPC code.

= Goal =

Have a working prototype for the 1.11 release

= Testing Plan =

TBD

Projects/ProxyGSSAPI

2011-08-23T19:40:09Z

Simo:

Projects/ProxyGSSAPI

2011-08-23T19:27:34Z

Simo: New page: {{project-early}} This project is about creating a mechanism by which it is possible to proxy accepting and initializing a security context to a separate trusted system service without gi...

Pkinit configuration

2010-10-29T19:40:08Z

Simo: /* Configuring a KDC */

'''Pkinit''' provides support for using public-key authentication with Kerberos. Pkinit is useful in the following situations:
# Using smart cards for Kerberos authentication
# Authentication based on soft tokens (or certificates stored on a computer) instead of passwords
# In conjunction with [[anonymous kerberos]] and [[Projects/FAST | FAST]] protecting password exchanges to remove the possibility of [[dictionary attacks]]

This article describes minimal Pkinit configuration for a KDC and clients. It assumes you already have a Kerberos realm functioning and that you have the <tt>openssl</tt> command available.

The following steps are involved:
# Setting up a certificate authority
# Generating a KDC certificate
# Generating client certificates
# Configuring the KDC and clients
# Testing

== Background ==

Pkinit requires a public key infrastructure. The simplest use of
Pkinit ([[anonymous kerberos]]) requires a certificate authority (CA)
certificate and a KDC certificate. The certificate authority
certificate is known by all clients; any certificates signed by this
certificate are trusted by the clients. The KDC certificate is signed
by the certificate authority certificate (and thus trusted by the
clients) and identifies the KDC.

If Pkinit is used with smart cards or for other forms of user authentication, then each user will need a certificate as well.

This document discusses how to set up Pkinit for the EXAMPLE.COM realm by hand. This sort of by-hand setup may be appropriate for anonymous usage. However if a realm is going to provide certificates to each client then some sort of automated certificate authority will be required to manage certificates. Configuring an automated certificate authority will depend on what certificate authority is chosen.

== Generating the certificate authority certificate ==

In this document we will use OpenSSL to generate a simple self-signed certificate to use for the certificate authority.

First, generate a private key:
<pre> openssl genrsa -out cakey.pem 2048 </pre>
This will generate a 2048-bit RSA key and write it to file <tt>cakey.pem</tt>. In a production environment, this private key should be carefully protected.
Now, generate the CA certificate:
<pre>
openssl req -key cakey.pem -new -x509 -out cacert.pem
</pre>
This command will ask for the name of the CA and output a CA certificate into <tt>cacert.pem</tt> using the previously generated key.

== Generating Kerberos certificates ==

Kerberos certificates take advantage of two uncommon features of
certificates. First, an extended key usage is used to indicate that
the certificate should be used with Pkinit. An extended key usage is
an object identifier placed in a certificate to indicate what the
public key should be used for. Secondly, an otherName form of a
subjectAlternativeName is used to describe the Kerberos principal
associated with the certificate. An otherName is a way of including
types of names in certificates that were not part of the original
X.509 architecture. Unfortunately, including these elements in a
certificate requires the use of an OpenSSL extensions file. This
file provides configuration for the certificate generation process. However the mechanisms for providing user data such as the name of the realm and the client principal to the otherName component are primitive.

This article includes a sample OpenSSL extensions file; see
[[#Extensions file]]. Paste that section of the article into a filed called <tt>pkinit_extensions</tt>. That file uses environment variables to set the
client and realm name.

=== Generating KDC certificate ===

First, generate the KDC key:
<pre>
openssl genrsa -out kdckey.pem 2048
</pre>
Then, generate a certificate request
<pre>
openssl req -new -out kdc.req -key kdckey.pem
</pre>
Enter in the KDC name information.
To generate the certificate:
<pre>
REALM=EXAMPLE.COM; export REALM

openssl x509 -req -in kdc.req -CAkey cakey.pem -CA cacert.pem -out kdc.pem -extfile pkinit_extensions -extensions kdc_cert -CAcreateserial
</pre>
This will generate a certificate, <tt>kdc.pem</tt>, for the KDC. The
first two lines set environment variables used by the extensions
file. The REALM variable should be set to the name of your
realm.

=== Generating client certificates ===

For use with anonymous Kerberos, no additional certificates are needed. For other uses of Pkinit, generate a certificate for each client. Typically on the client machine, the private key is generated:
<pre>
openssl genrsa -out clientkey.pem 2048
</pre>
The certificate request is also typically generated on the client machine:
<pre>
openssl req -new -key clientkey.pem -out client.req
</pre>
The <tt>client.req</tt> file needs to be copied to the machine with the certificate authority key. Then, sign the certificate:
<pre>
REALM=EXAMPLE.COM; export REALM
CLIENT=alice; export CLIENT
openssl x509 -CAkey cakey.pem -CA cacert.pem -req -in client.req -extensions client_cert -extfile pkinit_extensions -out client.pem
</pre>
That will sign a certificate for <tt>alice@EXAMPLE.COM</tt>. The resulting <tt>client.pem</tt> needs to be copied back to the client.

== Configuring a KDC ==
Insert the following entries into the kdcdefaults or a realms section of the <tt>kdc.conf</tt> or <tt>krb5.conf</tt> used by the KDC:
<pre>
pkinit_identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem
pkinit_anchors = FILE:/var/lib/krb5kdc/cacert.pem
</pre>
Of course, adjust the directory to where the files are stored on your system.
Then, for each client principal that uses pkinit, set the requires_preauth attribute from within kadmin:
<pre>
modprinc +requires_preauth alice@EXAMPLE.COM
</pre>

== Configuring a client ==
Add the following to the appropriate realm section of <tt>krb5.conf</tt>
<pre>
[realms]
EXAMPLE.COM = {
pkinit_anchors = FILE:/etc/krb5/cacert.pem

pkinit_identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem
}
</pre>
Of course, <tt>clientkey.pem</tt> needs to be protected .
After this point, using kinit as the appropriate client principal should not require a password.

== Advanced Configuration ==
=== Including pkinit options in a certificate request ===
Note that in the above example, the client name was not actually set
in the certificate request but was
set when the certificate was
generated. In a production
situation, it would be desirable
to include the client name in a
certificate request. There is an
option to do this: the
-extenios option to the
openssl req command is
intended for this purpose.
Unfortunately, the openssl
req command does not have a
-extfile option. It seems
that a special file for input to
the -config option could be
constructed to accomplish this.

In theory, if the options were included in the certificate request,
then a traditional certificate authority could be used to issue the
certificate. Common practice is not to copy the requested extensions
into the issued certificate, so special configuration would probably
be required on the part of the certificate authority.

=== Client identity on the command line ===
The -X X509_user_identity option to kinit allows users
to specify what Pkinit idenity and key should be used. It provides an
alternative to specifying this information in <tt>krb5.conf</tt>.

=== Smart card configuration ===
The [http://web.mit.edu/Kerberos/krb5-1.6/krb5-1.6.3/doc/krb5-admin.html#pkinit-client-options Kerberos administration manual]
describes how to configure Pkinit to use PKCS11 smart cards and how to configure the selection of the correct identity.

== Debugging Pkinit ==
By default, the MIT Kerberos Pkinit plugin does not support debugging output. Debugging can be enabled but requires changing the source and rebuilding the plugin. Add the following line to the top of <tt>src/plugins/preauth/pkinit.h</tt>
<pre>
#define DEBUG
</pre>
Then, rebuild the sources. Copy the generated <tt>pkinit.so</tt> into place to get debugging output.
==Extensions file==
<pre>
[ kdc_cert ]
basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
keyUsage = nonRepudiation, digitalSignature, keyEncipherment, keyAgreement

#Pkinit EKU
extendedKeyUsage = 1.3.6.1.5.2.3.5

subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

# Copy subject details

issuerAltName=issuer:copy

# Add id-pkinit-san (pkinit subjectAlternativeName)
subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:kdc_princ_name

[kdc_princ_name]
realm = EXP:0, GeneralString:${ENV::REALM}
principal_name = EXP:1, SEQUENCE:kdc_principal_seq

[kdc_principal_seq]
name_type = EXP:0, INTEGER:1
name_string = EXP:1, SEQUENCE:kdc_principals

[kdc_principals]
princ1 = GeneralString:krbtgt
princ2 = GeneralString:${ENV::REALM}

[ client_cert ]

# These extensions are added when 'ca' signs a request.

basicConstraints=CA:FALSE

keyUsage = digitalSignature, keyEncipherment, keyAgreement

extendedKeyUsage = 1.3.6.1.5.2.3.4
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name

# Copy subject details

issuerAltName=issuer:copy

[princ_name]
realm = EXP:0, GeneralString:${ENV::REALM}
principal_name = EXP:1, SEQUENCE:principal_seq

[principal_seq]
name_type = EXP:0, INTEGER:1
name_string = EXP:1, SEQUENCE:principals

[principals]
princ1 = GeneralString:${ENV::CLIENT}
</pre>