<chapter id="sam"> <chapterinfo> <author> <firstname>Andrew</firstname><surname>Bartlett</surname> </author> <pubdate>1 October 2002</pubdate> </chapterinfo> <title>The Upcoming SAM System</title> <sect1> <title>Security in the 'new SAM'</title> <para>One of the biggest problems with passdb is it's implementation of 'security'. Access control is on a 'are you root at the moment' basis, and it has no concept of NT ACLs. Things like ldapsam had to add 'magic' 'are you root' checks.</para> <para>We took this very seriously when we started work, and the new structure is designed with this in mind, from the ground up. Each call to the SAM has a NT_TOKEN and (if relevant) an 'access desired'. This is either provided as a parameter, or implicitly supplied by the object being accessed.</para> <para> For example, when you call </para> <programlisting> NTSTATUS sam_get_account_by_name(const SAM_CONTEXT *context, const NT_USER_TOKEN *access_token, uint32 access_desired, const char *domain, const char *name, SAM_ACCOUNT_HANDLE **account) </programlisting> <para> The context can be NULL (and is used to allow import/export by setting up 2 contexts, and allowing calls on both simultaneously) </para> <para> The access token *must* be specified. Normally the user's token out of current_user, this can also be a global 'system' context. </para> <para> The access desired is as per the ACL, for passing to the seaccess stuff. </para> <para> The domain/username are standard. Even if we only have one domain, keeping this ensures that we don't get 'unqualified' usernames (same problem as we had with unqualified SIDs). </para> <para> We return a 'handle'. This is opaque to the rest of Samba, but is operated on by get/set routines, all of which return NTSTATUS. </para> <para> The access checking is done by the SAM module. The reason it is not done 'above' the interface is to ensure a 'choke point'. I put a lot of effort into the auth subsystem to ensure we never 'accidentally' forgot to check for null passwords, missed a restriction etc. I intend the SAM to be written with the same caution. </para> <para> The reason the access checking is not handled by the interface itself is due to the different implementations it make take on. For example, on ADS, you cannot set a password over a non-SSL connection. Other backends may have similar requirements - we need to leave this policy up to the modules. They will naturally have access to 'helper' procedures and good examples to avoid mishaps. </para> <para> (Furthermore, some backends my actually chose to push the whole ACL issue to the remote server, and - assuming ldap for this example - bind as the user directly) </para> <para> Each returned handle has an internal 'access permitted', which allows the 'get' and 'set' routines to return 'ACCESS_DENIED' for things that were not able to be retrieved from the backend. This removes the need to specify the NT_TOKEN on every operation, and allows for 'object not present' to be easily distinguished from 'access denied'. </para> <para> When you 'set' an object (calling sam_update_account) the internal details are again used. Each change that has been made to the object has been flagged, so as to avoid race conditions (on unmodified components) and to avoid violating any extra ACL requirements on the actual data store (like the LDAP server). </para> <para> Finally, we have generic get_sec_desc() and set_sec_desc() routines to allow external ACL manipulation. These do lookups based on SID. </para> </sect1> <sect1> <title>Standalone from UNIX</title> <para> One of the primary tenants of the 'new SAM' is that it would not attempt to deal with 'what unix id for that'. This would be left to the 'SMS' (Sid Mapping System') or SID farm, and probably administered via winbind. We have had constructive discussion on how 'basic' unix accounts like 'root' would be handled, and we think this can work. Accounts not preexisting in unix would be served up via winbind. </para> <para> This is an *optional* part, and my preferred end-game. We have a fare way to go before things like winbind up to it however. </para> </sect1> <sect1> <title>Handles and Races in the new SAM</title> <para> One of the things that the 'new SAM' work has tried to face is both compatibility with existing code, and a closer alignment to the SAMR interface. I consider SAMR to be a 'primary customer' to the this work, because if we get alignment with that wrong, things get more, rather than less complex. Also, most other parts of Samba are much more flexible with what they can allow. </para> <para> In any case, that was a decision taken as to how the general design would progress. BTW, my understanding of SAMR may be completely flawed. </para> <para> One of the most race-prone areas of the new code is the conflicting update problem. We have taken two approaches: </para> <itemizedlist> <listitem> <para>'Not conflicting' conflicts. Due to the way usrmgr operates, it will open a user, display all the properties and *save* them all, even if you don't change any. </para> <para> For this, see what I've done in rpc_server/srv_samr_util.c. I intend to take this one step further, and operate on the 'handle' that the values were read from. This should mean that we only update things that have *really* changed. </para> </listitem> <listitem> <para> 'conflicting' updates: Currently we don't deal with this (in passdb or the new sam stuff), but the design is sufficiently flexible to 'deny' a second update. I don't foresee locking records however. </para> </listitem> </itemizedlist> </sect1> <sect1> <title>Layers</title> <sect2> <title>Application</title> <para> This is where smbd, samtest and whatever end-user replacement we have for pdbedit sits. They use only the SAM interface, and do not get 'special knowledge' of what is below them. </para> </sect2> <sect2> <title>SAM Interface</title> <para> This level 'owns' the various handle structures, the get/set routines on those structures and provides the public interface. The application layer may initialize a 'context' to be passed to all interface routines, else a default, self-initialising context will be supplied. This layser finds the appropriate backend module for the task, and tries very hard not to need to much 'knowledge'. It should just provide the required abstraction to the modules below, and arrange for their initial loading. </para> <para> We could possibly add ACL checking at this layer, to avoid discrepancies in implementation modules. </para> </sect2> <sect2> <title>SAM Modules</title> <para> These do not communicate with the application directly, only by setting values in the handles, and receiving requests from the interface. These modules are responsible for translating values from the handle's .private into (say) an LDAP modification list. The module is expected to 'know' things like it's own domain SID, domain name, and any other state attached to the SAM. Simpler modules may call back to some helper routine. </para> </sect2> </sect1> <sect1> <title>SAM Modules</title> <sect2> <title>Special Module: sam_passdb</title> <para> In order for there to be a smooth transition, kai is writing a module that reads existing passdb backends, and translates them into SAM replies. (Also pulling data from the account policy DB etc). We also intend to write a module that does the reverse - gives the SAM a passdb interface. </para> </sect2> <sect2> <title>sam_ads</title> <para> This is the first of the SAM modules to be committed to the tree - mainly because I needed to coordinate work with metze (who authored most of it). This module aims to use Samba's libads code to provide an Active Directory LDAP client, suitable for use on a mixed-mode DC. While it is currently being tested against Win2k servers (with a password in the smb.conf file) it is expected to eventually use a (possibly modified) OpenLDAP server. We hope that this will assist in the construction of an Samba AD DC. </para> <para> We also intend to construct a Samba 2.2/3.0 compatible ldap module, again using libads code. </para> </sect2> </sect1> <sect1> <title>Memory Management</title> <para> The 'new SAM' development effort also concerned itself with getting a sane implementation of memory management. It was decided that we would be (as much as possible) talloc based, using an 'internal talloc context' on many objects. That is, the creation of an object would initiate it's own internal talloc context, and this would be used for all operations on that object. Much of this is already implemented in passdb. Also, like passdb, it will be possible to specify that some object actually be created on a specified context. </para> <para> Memory management is important here because the APIs in the 'new SAM' do not use 'pdb_init()' or an equivalent. They always allocate new objects. Enumeration's are slightly different, and occur on a supplied context that 'owns' the entire list, rather than per-element. (the enumeration functions return an array of all elements - not full handles just basic (and public) info) Likewise for things that fill in a char **. </para> <para>For example:</para> <para><programlisting> NTSTATUS sam_lookup_sid(const SAM_CONTEXT *context, const NT_USER_TOKEN *access_token, TALLOC_CTX *mem_ctx, const DOM_SID *sid, char **name, uint32 *type) </programlisting></para> <para>Takes a context to allocate the 'name' on, while:</para> <para><programlisting> NTSTATUS sam_get_account_by_sid(const SAM_CONTEXT *context, const NT_USER_TOKEN *access_token, uint32 access_desired, const DOM_SID *accountsid, SAM_ACCOUNT_HANDLE **account) </programlisting></para> <para>Allocates a handle and stores the allocation context on that handle.</para> <para>I think that the following:</para> <para><programlisting> NTSTATUS sam_enum_accounts(const SAM_CONTEXT *context, const NT_USER_TOKEN *access_token, const DOM_SID *domainsid, uint16 acct_ctrl, int32 *account_count, SAM_ACCOUNT_ENUM **accounts) </programlisting></para> </sect1> <sect1> <title>Testing</title> <para> Testing is vital in any piece of software, and Samba is certainly no exception. In designing this new subsystem, we have taken care to ensure it is easily tested, independent of outside protocols. </para> <para> To this end, Jelmer has constructed 'samtest'. </para> <para> This utility (see torture/samtest.c) is structured like rpcclient, but instead operates on the SAM subsystem. It creates a 'custom' SAM context, that may be distinct from the default values used by the rest of the system, and can load a separate configuration file. </para> <para> A small number of commands are currently implemented, but these have already proved vital in testing. I expect SAM module authors will find it particularly valuable. </para> <para>Example useage:</para> <para><prompt>$</prompt> <command>bin/samtest</command></para> <para><programlisting> > context ads:ldap://192.168.1.96 </programlisting> (this loads a new context, using the new ADS module. The parameter is the 'location' of the ldap server) </para> <para><programlisting> > lookup_name DOMAIN abartlet </programlisting> (returns a sid). </para> <para> Because the 'new SAM' is NT ACL based, there will be a command to specify an arbitrary NT ACL, but for now it uses 'system' by default. </para> </sect1> </chapter>