From 18bc97287cbaffb03a54c0b1e635d443a3d54d8d Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Thu, 17 Jul 2008 13:32:28 +0200 Subject: Some doxygen comments for idmap (This used to be commit adecc6d91338e7e34afd0672aada5d0e47247a33) --- source3/winbindd/idmap.c | 101 +++++++++++++++++++++++++++++++++++++---- source3/winbindd/idmap_cache.c | 71 +++++++++++++++++++++++++++-- 2 files changed, 157 insertions(+), 15 deletions(-) diff --git a/source3/winbindd/idmap.c b/source3/winbindd/idmap.c index bace38876b..c23919fb18 100644 --- a/source3/winbindd/idmap.c +++ b/source3/winbindd/idmap.c @@ -28,37 +28,59 @@ static_decl_idmap; +/** + * Pointer to the backend methods. Modules register themselves here via + * smb_register_idmap. + */ + struct idmap_backend { const char *name; struct idmap_methods *methods; struct idmap_backend *prev, *next; }; +static struct idmap_backend *backends = NULL; +/** + * Pointer to the alloc backend methods. Modules register themselves here via + * smb_register_idmap_alloc. + */ struct idmap_alloc_backend { const char *name; struct idmap_alloc_methods *methods; struct idmap_alloc_backend *prev, *next; }; +static struct idmap_alloc_backend *alloc_backends = NULL; +/** + * The idmap alloc context that is configured via "idmap alloc + * backend". Defaults to "idmap backend" in case the module (tdb, ldap) also + * provides alloc methods. + */ struct idmap_alloc_context { struct idmap_alloc_methods *methods; }; +static struct idmap_alloc_context *idmap_alloc_ctx = NULL; -/* - * Lists for the module initializations +/** + * Default idmap domain configured via "idmap backend". */ -static struct idmap_backend *backends = NULL; -static struct idmap_alloc_backend *alloc_backends = NULL; - - static struct idmap_domain *default_idmap_domain; + +/** + * Passdb idmap domain, not configurable. winbind must always give passdb a + * chance to map ids. + */ static struct idmap_domain *passdb_idmap_domain; +/** + * List of specially configured idmap domains. This list is filled on demand + * in the winbind idmap child when the parent winbind figures out via the + * special range parameter or via the domain SID that a special "idmap config + * domain" configuration is present. + */ static struct idmap_domain **idmap_domains = NULL; static int num_domains = 0; -static struct idmap_alloc_context *idmap_alloc_ctx = NULL; - static struct idmap_methods *get_methods(struct idmap_backend *be, const char *name) { @@ -126,7 +148,8 @@ NTSTATUS smb_register_idmap(int version, const char *name, for (entry = backends; entry != NULL; entry = entry->next) { if (strequal(entry->name, name)) { - DEBUG(0,("Idmap module %s already registered!\n", name)); + DEBUG(0,("Idmap module %s already registered!\n", + name)); return NT_STATUS_OBJECT_NAME_COLLISION; } } @@ -151,7 +174,7 @@ NTSTATUS smb_register_idmap(int version, const char *name, } /********************************************************************** - Allow a module to register itself as a method. + Allow a module to register itself as an alloc method. **********************************************************************/ NTSTATUS smb_register_idmap_alloc(int version, const char *name, @@ -249,6 +272,14 @@ static bool parse_idmap_module(TALLOC_CTX *mem_ctx, const char *param, return true; } +/** + * Initialize a domain structure + * @param[in] mem_ctx memory context for the result + * @param[in] domainname which domain is this for + * @param[in] modulename which backend module + * @param[in] params parameter to pass to the init function + * @result The initialized structure + */ static struct idmap_domain *idmap_init_domain(TALLOC_CTX *mem_ctx, const char *domainname, const char *modulename, @@ -303,6 +334,15 @@ fail: return NULL; } +/** + * Initialize the default domain structure + * @param[in] mem_ctx memory context for the result + * @result The default domain structure + * + * This routine takes the module name from the "idmap backend" parameter, + * passing a possible parameter like ldap:ldap://ldap-url/ to the module. + */ + static struct idmap_domain *idmap_init_default_domain(TALLOC_CTX *mem_ctx) { struct idmap_domain *result; @@ -337,6 +377,16 @@ fail: return NULL; } +/** + * Initialize a named domain structure + * @param[in] mem_ctx memory context for the result + * @param[in] domname the domain name + * @result The default domain structure + * + * This routine looks at the "idmap config " parameters to figure out + * the configuration. + */ + static struct idmap_domain *idmap_init_named_domain(TALLOC_CTX *mem_ctx, const char *domname) { @@ -371,6 +421,14 @@ fail: return NULL; } +/** + * Initialize the passdb domain structure + * @param[in] mem_ctx memory context for the result + * @result The default domain structure + * + * No config, passdb has its own configuration. + */ + static struct idmap_domain *idmap_init_passdb_domain(TALLOC_CTX *mem_ctx) { if (passdb_idmap_domain != NULL) { @@ -386,6 +444,21 @@ static struct idmap_domain *idmap_init_passdb_domain(TALLOC_CTX *mem_ctx) return passdb_idmap_domain; } +/** + * Find a domain struct according to a domain name + * @param[in] domname Domain name to get the config for + * @result The default domain structure that fits + * + * This is the central routine in the winbindd-idmap child to pick the correct + * domain for looking up IDs. If domname is NULL or empty, we use the default + * domain. If it contains something, we try to use idmap_init_named_domain() + * to fetch the correct backend. + * + * The choice about "domname" is being made by the winbind parent, look at the + * "have_idmap_config" of "struct winbindd_domain" which is set in + * add_trusted_domain. + */ + static struct idmap_domain *idmap_find_domain(const char *domname) { struct idmap_domain *result; @@ -449,6 +522,14 @@ void idmap_close(void) num_domains = 0; } +/** + * Initialize the idmap alloc backend + * @param[out] ctx Where to put the alloc_ctx? + * @result Did it work fine? + * + * This routine first looks at "idmap alloc backend" and if that is not + * defined, it uses "idmap backend" for the module name. + */ static NTSTATUS idmap_alloc_init(struct idmap_alloc_context **ctx) { const char *backend; diff --git a/source3/winbindd/idmap_cache.c b/source3/winbindd/idmap_cache.c index b818d0dafb..496f70ab45 100644 --- a/source3/winbindd/idmap_cache.c +++ b/source3/winbindd/idmap_cache.c @@ -1,11 +1,8 @@ -/* +/* Unix SMB/CIFS implementation. ID Mapping Cache - based on gencache - - Copyright (C) Simo Sorce 2006 - Copyright (C) Rafal Szczesniak 2002 + Copyright (C) Volker Lendecke 2008 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -23,6 +20,16 @@ #include "includes.h" #include "winbindd.h" +/** + * Find a sid2uid mapping + * @param[in] sid the sid to map + * @param[out] puid where to put the result + * @param[out] expired is the cache entry expired? + * @retval Was anything in the cache at all? + * + * If *puid == -1 this was a negative mapping. + */ + bool idmap_cache_find_sid2uid(const struct dom_sid *sid, uid_t *puid, bool *expired) { @@ -54,6 +61,16 @@ bool idmap_cache_find_sid2uid(const struct dom_sid *sid, uid_t *puid, return ret; } +/** + * Find a uid2sid mapping + * @param[in] uid the uid to map + * @param[out] sid where to put the result + * @param[out] expired is the cache entry expired? + * @retval Was anything in the cache at all? + * + * If "is_null_sid(sid)", this was a negative mapping. + */ + bool idmap_cache_find_uid2sid(uid_t uid, struct dom_sid *sid, bool *expired) { char *key; @@ -81,6 +98,18 @@ bool idmap_cache_find_uid2sid(uid_t uid, struct dom_sid *sid, bool *expired) return ret; } +/** + * Store a mapping in the idmap cache + * @param[in] sid the sid to map + * @param[in] uid the uid to map + * + * If both parameters are valid values, then a positive mapping in both + * directions is stored. If "is_null_sid(sid)" is true, then this will be a + * negative mapping of uid, we want to cache that for this uid we could not + * find anything. Likewise if "uid==-1", then we want to cache that we did not + * find a mapping for the sid passed here. + */ + void idmap_cache_set_sid2uid(const struct dom_sid *sid, uid_t uid) { time_t now = time(NULL); @@ -111,6 +140,16 @@ void idmap_cache_set_sid2uid(const struct dom_sid *sid, uid_t uid) } } +/** + * Find a sid2gid mapping + * @param[in] sid the sid to map + * @param[out] pgid where to put the result + * @param[out] expired is the cache entry expired? + * @retval Was anything in the cache at all? + * + * If *pgid == -1 this was a negative mapping. + */ + bool idmap_cache_find_sid2gid(const struct dom_sid *sid, gid_t *pgid, bool *expired) { @@ -142,6 +181,16 @@ bool idmap_cache_find_sid2gid(const struct dom_sid *sid, gid_t *pgid, return ret; } +/** + * Find a gid2sid mapping + * @param[in] gid the gid to map + * @param[out] sid where to put the result + * @param[out] expired is the cache entry expired? + * @retval Was anything in the cache at all? + * + * If "is_null_sid(sid)", this was a negative mapping. + */ + bool idmap_cache_find_gid2sid(gid_t gid, struct dom_sid *sid, bool *expired) { char *key; @@ -169,6 +218,18 @@ bool idmap_cache_find_gid2sid(gid_t gid, struct dom_sid *sid, bool *expired) return ret; } +/** + * Store a mapping in the idmap cache + * @param[in] sid the sid to map + * @param[in] gid the gid to map + * + * If both parameters are valid values, then a positive mapping in both + * directions is stored. If "is_null_sid(sid)" is true, then this will be a + * negative mapping of gid, we want to cache that for this gid we could not + * find anything. Likewise if "gid==-1", then we want to cache that we did not + * find a mapping for the sid passed here. + */ + void idmap_cache_set_sid2gid(const struct dom_sid *sid, gid_t gid) { time_t now = time(NULL); -- cgit