logo_kerberos.gif

Samba4 port: libkdc Interface

From K5Wiki
Jump to: navigation, search

libkdc Entry Points

libkdc is a Heimdal API that Samba4 uses to talk to the Heimdal KDC. For Samba4, libkdc's main purpose is for Samba4 to pass a client's KDC-request packet to the KDC as a function-parameter, and to receive the KDC's response packet as an output parameter.

This page's purpose is to help understand how much work it will take to write for MIT-krb a libkdc interface resembling Heimdal's.

Entry Point Samba4 file Samba4 callers
kdc_log() heimdal/kdc/log.c no
kdc_log_msg() heimdal/kdc/log.c no
kdc_log_msg_va() heimdal/kdc/log.c no
kdc_openlog() heimdal/kdc/log.c no
krb5_kdc_get_config() heimdal/kdc/default_config.c kdc/kdc.c
krb5_kdc_process_krb5_request() heimdal/kdc/process.c kdc/kdc.c
krb5_kdc_process_request() heimdal/kdc/process.c no
krb5_kdc_set_dbinfo() kdc/set_dbinfo.c no
krb5_kdc_save_request() heimdal/kdc/process.c no
krb5_kdc_update_time() heimdal/kdc/process.c kdc/kdc.c
krb5_kdc_windc_init() heimdal/kdc/windc.c kdc/kdc.c

The following subsections describe primarily the four libkdc entry-points that Samba4 uses.


krb5_kdc_process_krb5_request()

Samba4 passes client-requests to the KDC by calling the libkdc entry-point krb5_kdc_process_krb5_request(), which invokes the following Heimdal KDC functions:

Protocol Heimdal fcn MIT-krb fcn
AS decode_AS_REQ() decode_krb5_as_req()
AS free_AS_REQ() krb5_free_kdc_req()
AS _kdc_as_rep() process_as_req()
TGS decode_TGS_REQ() decode_krb5_tgs_req()
TGS free_TGS_REQ() krb5_free_kdc_req()
TGS _kdc_tgs_rep() process_tgs_req()

Caution: libkdc has another similarly-named function, but Samba4 uses only one of these two functions:

  1. krb5_kdc_process_krb5_request() gets used by Samba4
  2. krb5_kdc_process_request() doesn't (see below).

krb5_kdc_get_config()

Heimdal has a run-time apparatus for managing the KDC's configuration, while MIT-krb uses a simple configuration file. Samba4 doesn't yet update the KDC's config at runtime.

  1. Samba4 reads the KDC's config-settings from a config-file, and then passes the settings to the KDC, using the krb5_kdc_configuration{} structure.
  2. Samba4 uses the libkdc entry-point krb5_kdc_get_config() to initialize the krb5_kdc_configuration{} structure;
  3. As of Sept '09, Samba4 does not change this config structure's contents at runtime, except in one place:
  4. If hx509 fails to find a user cert, hx509 turns itself off by resetting a flag in the config-structure..

krb5_kdc_update_time()

libkdc's krb5_kdc_update_time() is kind of trivial, and doesn't necessarily need to be exposed as part of the API:

  1. krb5_kdc_update_time() just sets the kdc's clock with gettimeofday();
  2. krb5_kdc_update_time() gets called only by kdc_process();
  3. kdc_process() calls krb5_kdc_update_time() at ticket-request time, just before kdc_process() calls krb5_kdc_process_krb5_request();

So, this entry point requires no porting effort. Samba4 does use this function.


krb5_kdc_windc_init()

This entry-point loads and initializes the windc plugin. The windc plugin handles AD-style account-authorization controls, and MIT-krb doesn't yet have a windc plugin. Samba4 does use this function.

The krb5_kdc_windc_init() entry point calls several Heimdal functions that MIT-krb lacks:

  1. _krb5_plugin_find()
  2. _krb5_plugin_get_next()
  3. _krb5_plugin_get_symbol()
  4. _krb5_plugin_free()

Though MIT-krb lacks these calls, MIT-krb does have plugin-handling code for loading preauthentication plugins. Presumably, MIT's version of krb5_kdc_windc_init() should load the windc plugin with plugin code that resembles the preauth-plugin stuff.


krb5_kdc_process_request()

Samba4 doesn't use this function. The Heimdal KDC catches client-requests by calling the libkdc entry-point krb5_kdc_process_request(), which invokes the following Heimdal KDC functions:

Protocol Heimdal fcn MIT-krb fcn
AS decode_AS_REQ() decode_krb5_as_req()
AS free_AS_REQ() krb5_free_kdc_req()
AS _kdc_as_rep() process_as_req()
TGS decode_TGS_REQ() decode_krb5_tgs_req()
TGS free_TGS_REQ() krb5_free_kdc_req()
TGS _kdc_tgs_rep() process_tgs_req()
krb524 decode_ticket() krb5_decode_ticket()
krb524 _kdc_do_524 <deprecated>
krb524 free_Ticket() no
digest auth decode_DigestREQ() no
digest auth free_DigestREQ() no
digest auth _kdc_do_digest() no
kx509 _kdc_try_kx509_request() no
kx509 _kdc_do_kx509() no
kx509 free_Kx509Request() no
krb v4 _kdc_maybe_version4 deprecated?
krb v4 _kdc_do_version4 deprecated
AFS _kdc_do_kaserver() deprecated?

It's not clear that the MIT port needs to support anything more than the usual AS & TGS protocols:

  1. MIT-krb no longer supports v4 operation, as of MIT v1.7;
  2. Samba4 doesn't actually use the Windows "digest auth" protocols;
  3. U.Michigan's hx509 protocol may not be necessary for Samba4;
  4. Carnegie-Mellon's AFS project seems to have deprecated kaserver.

Caution: libkdc has another similarly-named function, but Samba4 uses only one of these two functions:

  1. krb5_kdc_process_krb5_request() gets used by Samba4
  2. krb5_kdc_process_request() doesn't.