logo_kerberos.gif

Difference between revisions of "Samba4 port: libkdc Interface"

From K5Wiki
Jump to: navigation, search
(→‎libkdc Entry Points)
 
(57 intermediate revisions by the same user not shown)
Line 1: Line 1:
  +
== 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.
  +
 
{| class="wikitable sortable" width="100%" border="1" style="border-collapse: collapse; border: 1px solid #dfdfdf;"
  
{| class="wikitable sortable" width="100%" border="1" style="border-collapse: collapse; border: 1px solid #dfdfdf;"
 
| bgcolor="#cc0000" |<font color="#ffffff">'''Entry Point''' </font>
  
| bgcolor="#cc0000" |<font color="#ffffff">'''Entry Point''' </font>
⚫
| bgcolor="#cc0000" |<font color="#ffffff">'''Heimdal file'''</font>
  
 
| bgcolor="#cc0000" |<font color="#ffffff">'''Samba4 file'''</font>
  
| bgcolor="#cc0000" |<font color="#ffffff">'''Samba4 file'''</font>
 
| bgcolor="#cc0000" |<font color="#ffffff">'''Samba4 callers'''</font>
  
| bgcolor="#cc0000" |<font color="#ffffff">'''Samba4 callers'''</font>
Line 7: Line 15:
 
|-
  
|-
 
| kdc_log()
  
| kdc_log()
−
| kdc/log.c
 +
| heimdal/kdc/log.c
−
|
  
 
| no
  
| no
   
 
|-
  
|-
 
| kdc_log_msg()
  
| kdc_log_msg()
−
| kdc/log.c
 +
| heimdal/kdc/log.c
−
|
  
 
| no
  
| no
   
 
|-
  
|-
 
| kdc_log_msg_va()
  
| kdc_log_msg_va()
−
| kdc/log.c
 +
| heimdal/kdc/log.c
−
|
  
 
| no
  
| no
   
 
|-
  
|-
 
| kdc_openlog()
  
| kdc_openlog()
−
| kdc/log.c
 +
| heimdal/kdc/log.c
−
|
  
 
| no
  
| no
   
 
|-
  
|-
−
| krb5_kdc_get_config()
 +
| '''krb5_kdc_get_config()'''
−
| kdc/default_config.c
 +
| heimdal/kdc/default_config.c
−
| kdc/kdc.c
  
 
| kdc/kdc.c
  
| kdc/kdc.c
   
 
|-
  
|-
−
| krb5_kdc_process_krb5_request()
 +
| '''krb5_kdc_process_krb5_request()'''
−
| kdc/process.c
  
 
| heimdal/kdc/process.c
  
| heimdal/kdc/process.c
 
| kdc/kdc.c
  
| kdc/kdc.c
Line 37: Line 45:
 
|-
  
|-
 
| krb5_kdc_process_request()
  
| krb5_kdc_process_request()
−
| kdc/process.c
  
 
| heimdal/kdc/process.c
  
| heimdal/kdc/process.c
  +
| no
  +
  +
|-
  +
| krb5_kdc_set_dbinfo()
  +
| [[kdc/set_dbinfo.c]]
 
| no
  
| no
   
 
|-
  
|-
 
| krb5_kdc_save_request()
  
| krb5_kdc_save_request()
−
| kdc/process.c
  
 
| heimdal/kdc/process.c
  
| heimdal/kdc/process.c
 
| no
  
| no
   
 
|-
  
|-
−
| krb5_kdc_update_time()
 +
| '''krb5_kdc_update_time()'''
−
| kdc/process.c
  
 
| heimdal/kdc/process.c
  
| heimdal/kdc/process.c
 
| kdc/kdc.c
  
| kdc/kdc.c
   
 
|-
  
|-
−
| krb5_kdc_windc_init()
 +
| '''krb5_kdc_windc_init()'''
−
| kdc/windc.c
  
 
| heimdal/kdc/windc.c
  
| heimdal/kdc/windc.c
 
| kdc/kdc.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:
  +
  +
{| class="wikitable sortable" width="100%" border="1" style="border-collapse: collapse; border: 1px solid #dfdfdf;"
  +
| bgcolor="#ff6600" |<font color="#ffffff">'''Protocol'''</font>
  ⚫
| bgcolor="#ff6600" |<font color="#ffffff">'''Heimdal fcn''' </font>
  +
| bgcolor="#ff6600" |<font color="#ffffff">'''MIT-krb fcn'''</font>
  +
  +
|-
  +
| 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
  +
[http://k5wiki.kerberos.org/wiki/Task-List_for_Samba4_Port_(Andrew_Bartlett)#.2A_Appendix_2:_windc_KDC_Plugin_for_Account-AuthZ '''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:
  +
  +
{| class="wikitable sortable" width="100%" border="1" style="border-collapse: collapse; border: 1px solid #dfdfdf;"
  +
| bgcolor="#CCCCCC" |<font color="#ffffff">'''Protocol'''</font>
  +
| bgcolor="#CCCCCC" |<font color="#ffffff">'''Heimdal fcn''' </font>
  +
| bgcolor="#CCCCCC" |<font color="#ffffff">'''MIT-krb fcn'''</font>
  +
  +
|-
  +
| 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.
   
 
----
  
----

Latest revision as of 13:02, 11 September 2009

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.
Retrieved from "https://k5wiki.kerberos.org/wiki?title=Samba4_port:_libkdc_Interface&oldid=2408"