logo_kerberos.gif

Difference between revisions of "Projects/Export import cred"

From K5Wiki
Jump to: navigation, search
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{project-early}}
 +
{{project-rel|1.11}}
−
{{project-target|1.11}}
  
   
 
This project is to add gss_export_cred and gss_import_cred extensions.
  
This project is to add gss_export_cred and gss_import_cred extensions.
Line 23: Line 23:
 
== Token format ==
  
== Token format ==
   
−
TODO:
  
  +
The mechglue token format will be the same as Heimdal's, which is one or more repetitions of the following sequence:
   
−
1. Specify mechglue token format
  
  +
# A four-byte big-endian number giving the length of the mechanism OID
  +
# The mechanism OID
  +
# A four-byte big-endian number giving the length of the mechanism token
  +
# The mechanism token
   
−
2. Specify SPNEGO token format as mechglue token format
 +
A SPNEGO mechanism token will be the mechglue token for SPNEGO's underlying mechglue cred.
   
−
3. Specify krb5 token format
  
  +
A krb5 mechanism token will use JSON to represent each of the credential's structure fields, except for the destroy_ccache flag. The credential's rcache and keytab will be marshalled by name. The credential's ccache will be marshalled by name unless it is a memory keytab, in which case it will be marshalled by contents. Binary fields within the marshalled character (such as encryption keys) will be encoded in base64 and marshalled as JSON strings. The exported credential will be wrapped in a JSON array whose first element is "K5C1" in order to gracefully detect attempts to import a token in the wrong format.
   
−
NOTES:
  
  +
Here is an example of a krb5 mechanism token representing a default acceptor credential:
   
−
* Heimdal's mechglue token format is <mech oid><mech token> repeated for each mech, where the mech oid and mech token are each represented as a four-byte length followed by the content.
  
  +
["K5C1",[2,null,null,true,false,"FILE:/me/krb5/build/testdir/keytab",
  +
null,null,null,false,0,0,null,null]]
   
−
* Heimdal's krb5 token format begins with a four-byte tag which is 0 for a memory ccache and 1 for anything else. If the tag is 0, it is followed by a serialization of the TGT from the cache (the serialization is performed by krb5_store_creds() and krb5_ret_creds()). If the tag is 1, it is followed by the full name of the ccache, which is assumed to be in external storage. Only initiator creds are supported.
  
  +
Here is an example of a krb5 mechanism token representing a delegated credential (which uses a memory ccache, so we must marshal the ccache contents):
  +
  +
["K5C1",[1,["user@KRBTEST.COM",null,null],null,false,false,null,null,
  +
["user@KRBTEST.COM",["user@KRBTEST.COM","krbtgt/KRBTEST.COM@KRBTEST.COM",
  +
[18,"vJUpxAKHH2R3Tq93lLMjaespN1/3O7ojcR04mCRXaow="],1346687370,1346687450,1346773770,
  +
0,false,1611202560,null,"YYIBUDCCAUygAwIBBaENGwtLUkJURVNULkNPTaIgMB6gAwIBAqEXMBUbBmty
  +
YnRndBsLS1JCVEVTVC5DT02jggESMIIBDqADAgESoQMCAQGiggEABIH9czTdh8TsTHoFCo6bQSlWVk0lYUJ1F
  +
vdJBSl/t/R/91SY0UVNEu3fiZOfLEP3+e3fnWO5n/rFg4shDHH32PRA2NgHZIneFKF/jqwPPJUsvu6wDEXG9x
  +
J3qj1FvD2kMCWAYbdpmHlh/JViQ37CfIsLVT6aXIWvfh+HQ8sJO9OoMMJCwwpxbZx0l6GJ3SnuQ9R98+Jlcr4
  +
WFxAqko+KFPh2F4HquqklmDolklRoDxBg9sQaBTRdKbG89PX2oQoqxifLP+aBpSfZAABPlmBl6GvEoh5FtqBn
  +
Nt7jVE+2dErFatbYaREmiFv6tl4TU9BnqNvpqUNH6wMqtHaNzmuIUw==","",null]],
  +
null,false,1346773770,0,null,null]]
   
 
== Design ==
  
== Design ==
   
−
TODO: outline code alterations
  
  +
First, we will add internal facilities for base64 and JSON. Declarations will be in include/k5-base64.h and include/k5-json.h; code will be in util/support/base64.c and util/support/json.c. The code will be loosely based on the equivalent facilities in Heimdal. The JSON infrastructure will include a very simple dynamic type system in order to represent JSON values.
  +
  +
The mechglue code will be relatively simple. To export, we will invoke each mechanism's gss_export cred function, then add the length and value for the mech OID and token to a k5buf. When importing, we will use a helper function to parse out the lengths and values for each mech OID and mech token, then invoke the appropriate mech's import_token function and add the result to a mechglue credential.
  +
  +
The SPNEGO code will export by simply calling the mechglue gss_export_cred function on its mechglue cred. To import, it will use the mechglue to import the token as a mechglue cred, then construct a SPNEGO credential wrapper.
  +
  +
The krb5 code will export by recursively translating the krb5 cred record into a JSON value, then encoding the value. To import, it will decode the JSON value, then recursively translate it into a krb5 cred record. This methodology may eventually be used to replace the current libkrb5 serialization code, but that is beyond the scope of this project.
   
 
== Testing ==
  
== Testing ==
  +
  +
A test program will acquire initiator and acceptor creds, export and re-import each one, then perform a single-token GSSAPI exchange with credential delegation. The delegated cred will be exported and re-imported, then stored to the default ccache. A Python wrapper will invoke the test program with various permutations of mechanism choices and names.
   
 
== Documentation ==
  
== Documentation ==
  +
  +
gssapi.rst will be amended to document the new extension.
  +
  +
== Mailing list discussions ==
  +
  +
* http://mailman.mit.edu/pipermail/krbdev/2012-May/010859.html
  +
* http://mailman.mit.edu/pipermail/krbdev/2012-September/011216.html
   
 
== Release notes ==
  
== Release notes ==
  +
  +
Developer experience:
  +
  +
* Add new APIs gss_export_cred and gss_import_cred to serialize and unserialize GSSAPI credentials.

Latest revision as of 18:30, 17 September 2012

This project was completed in release 1.11.


This project is to add gss_export_cred and gss_import_cred extensions.

Requirements

The GSS-Proxy project allows GSS operations to be proxied through a daemon. The proxy daemon can be much more robust if it is stateless. To achieve statelessness, the daemon must be able to respond to a caller's gss_acquire_cred() call with an object containing the actual credential information (or a reference to its on-disk representation). For this, we need a way to serialize and deserialize a GSS credential object.

There are two pieces of prior work in this area: an expired internet draft from 2003(draft-engert-ggf-gss-extensions-00) and a Heimdal implementation. The Heimdal API signatures do not match the draft's proposal (Heimdal's signatures are much simpler). We will follow Heimdal's API rather than the draft's. However, we are not required to match Heimdal's token format.

API extensions

The GSS extensions to be implemented are: 

   OM_uint32 gss_export_cred(OM_uint32 *minor_status, gss_cred_id_t cred_handle,
                             gss_buffer_t token);
   
   OM_uint32 gss_import_cred(OM_uint32 *minor_status, gss_buffer_t token,
                             gss_cred_id_t *cred_handle);

A mechglue credential containing multiple mech credentials exports to a token containing all of the serialized mech credentials, each tagged so that it can be imported by the proper mechanism. If any of the mechanisms cannot export its mech credential, exporting the mechglue credential fails.

Token format

The mechglue token format will be the same as Heimdal's, which is one or more repetitions of the following sequence:

  1. A four-byte big-endian number giving the length of the mechanism OID
  2. The mechanism OID
  3. A four-byte big-endian number giving the length of the mechanism token
  4. The mechanism token

A SPNEGO mechanism token will be the mechglue token for SPNEGO's underlying mechglue cred.

A krb5 mechanism token will use JSON to represent each of the credential's structure fields, except for the destroy_ccache flag. The credential's rcache and keytab will be marshalled by name. The credential's ccache will be marshalled by name unless it is a memory keytab, in which case it will be marshalled by contents. Binary fields within the marshalled character (such as encryption keys) will be encoded in base64 and marshalled as JSON strings. The exported credential will be wrapped in a JSON array whose first element is "K5C1" in order to gracefully detect attempts to import a token in the wrong format.

Here is an example of a krb5 mechanism token representing a default acceptor credential: 

   ["K5C1",[2,null,null,true,false,"FILE:/me/krb5/build/testdir/keytab",
   null,null,null,false,0,0,null,null]]

Here is an example of a krb5 mechanism token representing a delegated credential (which uses a memory ccache, so we must marshal the ccache contents): 

   ["K5C1",[1,["user@KRBTEST.COM",null,null],null,false,false,null,null,
   ["user@KRBTEST.COM",["user@KRBTEST.COM","krbtgt/KRBTEST.COM@KRBTEST.COM",
   [18,"vJUpxAKHH2R3Tq93lLMjaespN1/3O7ojcR04mCRXaow="],1346687370,1346687450,1346773770,
   0,false,1611202560,null,"YYIBUDCCAUygAwIBBaENGwtLUkJURVNULkNPTaIgMB6gAwIBAqEXMBUbBmty
   YnRndBsLS1JCVEVTVC5DT02jggESMIIBDqADAgESoQMCAQGiggEABIH9czTdh8TsTHoFCo6bQSlWVk0lYUJ1F
   vdJBSl/t/R/91SY0UVNEu3fiZOfLEP3+e3fnWO5n/rFg4shDHH32PRA2NgHZIneFKF/jqwPPJUsvu6wDEXG9x
   J3qj1FvD2kMCWAYbdpmHlh/JViQ37CfIsLVT6aXIWvfh+HQ8sJO9OoMMJCwwpxbZx0l6GJ3SnuQ9R98+Jlcr4
   WFxAqko+KFPh2F4HquqklmDolklRoDxBg9sQaBTRdKbG89PX2oQoqxifLP+aBpSfZAABPlmBl6GvEoh5FtqBn
   Nt7jVE+2dErFatbYaREmiFv6tl4TU9BnqNvpqUNH6wMqtHaNzmuIUw==","",null]],
   null,false,1346773770,0,null,null]]

Design

First, we will add internal facilities for base64 and JSON. Declarations will be in include/k5-base64.h and include/k5-json.h; code will be in util/support/base64.c and util/support/json.c. The code will be loosely based on the equivalent facilities in Heimdal. The JSON infrastructure will include a very simple dynamic type system in order to represent JSON values.

The mechglue code will be relatively simple. To export, we will invoke each mechanism's gss_export cred function, then add the length and value for the mech OID and token to a k5buf. When importing, we will use a helper function to parse out the lengths and values for each mech OID and mech token, then invoke the appropriate mech's import_token function and add the result to a mechglue credential.

The SPNEGO code will export by simply calling the mechglue gss_export_cred function on its mechglue cred. To import, it will use the mechglue to import the token as a mechglue cred, then construct a SPNEGO credential wrapper.

The krb5 code will export by recursively translating the krb5 cred record into a JSON value, then encoding the value. To import, it will decode the JSON value, then recursively translate it into a krb5 cred record. This methodology may eventually be used to replace the current libkrb5 serialization code, but that is beyond the scope of this project.

Testing

A test program will acquire initiator and acceptor creds, export and re-import each one, then perform a single-token GSSAPI exchange with credential delegation. The delegated cred will be exported and re-imported, then stored to the default ccache. A Python wrapper will invoke the test program with various permutations of mechanism choices and names.

Documentation

gssapi.rst will be amended to document the new extension.

Mailing list discussions

Release notes

Developer experience:

  • Add new APIs gss_export_cred and gss_import_cred to serialize and unserialize GSSAPI credentials.
Retrieved from "https://k5wiki.kerberos.org/wiki?title=Projects/Export_import_cred&oldid=4831"