From 4882e30c1bc117fdc6db1f7837e990ec6e9111b9 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Fri, 29 Jan 2010 23:51:00 +0000 Subject: [PATCH] Correct the DAL documentation for how modules should handle referrals git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@23678 dc483132-0cff-0310-8789-dd5450dbe970 --- src/include/kdb.h | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/src/include/kdb.h b/src/include/kdb.h index 1b1141bd2..187aa4679 100644 --- a/src/include/kdb.h +++ b/src/include/kdb.h @@ -988,16 +988,22 @@ typedef struct _kdb_vftabl { * Mandatory: Fill in *entries with the entry for the principal search_for. * The module must allocate each entry field separately, as callers may * free individual fields using db_free. If the principal is not found, - * set *nentries to 0 and return success. The meaning of flags are as - * follows (some of these may be processed by db_invoke methods such as - * KRB5_KDB_METHOD_SIGN_AUTH_DATA rather than by db_get_principal): + * set *nentries to 0 and return success. * - * KRB5_KDB_FLAG_CANONICALIZE: Indicates that a KDC client requested name - * canonicalization. The module may return an out-of-realm referral by - * filling in an out-of-realm principal name in entries->princ and null - * values elsewhere. The module may return an in-realm alias by - * filling in an in-realm principal name in entries->princ other than - * the one requested. + * The nentries and more arguments appear to be intended to account for + * multiple entries for a principal, but this functionality is neither + * implemented nor used. *nentries is set to 1 by all callers and should + * be set to 0 or 1 on return; *more sould be set to FALSE on return. + * Callers will typically error out if modules behave otherwise. + * + * The meaning of flags are as follows (some of these may be processed by + * db_invoke methods such as KRB5_KDB_METHOD_SIGN_AUTH_DATA rather than by + * db_get_principal): + * + * KRB5_KDB_FLAG_CANONICALIZE: Set by the KDC when looking up entries for + * an AS or TGS request with canonicalization requested. Affects + * whether the module should return out-of-realm referrals and aliases + * (see below). * * KRB5_KDB_INCLUDE_PAC: Set by the KDC during an AS request when the * client requested PAC information during padata, and during most TGS @@ -1005,9 +1011,9 @@ typedef struct _kdb_vftabl { * when generating authorization data. * * KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY: Set by the KDC when looking up the - * client entry in an AS request. Indicates that the module should - * return out-of-realm referral information in lieu of cross-realm TGT - * information. + * client entry in an AS request. Affects how the module should return + * out-of-realm referrals and whether the module should return in-realm + * aliases (see below). * * KRB5_KDB_FLAG_MAP_PRINCIPALS: Set by the KDC when looking up the client * entry during TGS requests, except for S4U TGS requests and requests @@ -1028,11 +1034,17 @@ typedef struct _kdb_vftabl { * during a TGS request, if the client principal is not part of the * realm being served. * - * The nentries and more arguments appear to be intended to account for - * multiple entries for a principal, but this functionality is neither - * implemented nor used. *nentries is set to 1 by all callers and should - * be set to 0 or 1 on return; the module should always set *more to FALSE. - * Callers will typically error out if modules behave otherwise. + * A module can return in-realm aliases if KRB5_KDB_FLAG_CANONICALIZE is + * set, or if KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY is not set (because + * aliases are always okay for TGS requests). To return an in-realm alias, + * fill in a different value for entries->princ than the one requested. + * + * A module can return out-of-realm referrals if KRB5_KDB_FLAG_CANONICALIZE + * is set. For AS request clients (KRB5_KDB_FLAG_CLIENT_REFERRALS_ONLY is + * also set), the module should do so by simply filling in an out-of-realm + * name in entries->princ and setting all other fields to NULL. Otherwise, + * the module should return the entry for the cross-realm TGS of the + * referred-to realm. */ krb5_error_code (*db_get_principal)(krb5_context kcontext, krb5_const_principal search_for, -- 2.26.2