Samba4 port: libkdc Interface
Contents
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:
- krb5_kdc_process_krb5_request() gets used by Samba4
- 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.
- 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.
- Samba4 uses the libkdc entry-point krb5_kdc_get_config() to initialize the krb5_kdc_configuration{} structure;
- As of Sept '09, Samba4 does not change this config structure's contents at runtime, except in one place:
- 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:
- krb5_kdc_update_time() just sets the kdc's clock with gettimeofday();
- krb5_kdc_update_time() gets called only by kdc_process();
- 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:
- _krb5_plugin_find()
- _krb5_plugin_get_next()
- _krb5_plugin_get_symbol()
- _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:
- MIT-krb no longer supports v4 operation, as of MIT v1.7;
- Samba4 doesn't actually use the Windows "digest auth" protocols;
- U.Michigan's hx509 protocol may not be necessary for Samba4;
- 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:
- krb5_kdc_process_krb5_request() gets used by Samba4
- krb5_kdc_process_request() doesn't.
