--- ./SAM-interface_handles.txt Wed Jul 31 14:53:56 2002 +++ ./SAM-interface-handles.txt Sat Aug 10 20:28:50 2002 @@ -1,52 +1,113 @@ +/* General notices about the SAM interface */ +/** + * - no information passed through the SAM interface is UNIX related. It is all direct smb information, + * including e.g. user / group names, security descriptors, ... + * The information might be generated based upon UNIX data, but this is backend dependent and + * fully transparent to the interface. + * + * - the interface described in this text is the default external interface to the SAMdb. There are two + * other interfaces (context based external interface and internal backend interface) related to SAMdb, + * differing in some aspects and are treated in different documents. Backend writers should consolidate + * the internal backend interface. For special SAM maintenance utilities that need different SAM instances + * (e.g. sam2sam) the context based SAM interface should be considered. For all other purposes using + * the SAMdb specified in smb.conf (i.e. all code in smbd), the functions described below apply. + * + * - all functions of the SAM interface are checked for access rights. Functions taking a valid + * handle on a SAM object do the access checking against the desired access stored in the handle (s. below). + * Other functions not having a valid handle need to know the user credentials of the caller. + * The user credentials are given to the function by the NT_USER_TOKEN and are checked against the security + * descriptor associated with the SAM object. + * + * - all functions accepting an access_desired parameter return a handle to a SAM object. This desired + * access is stored with the handle and represents the maximum allowed access to this handle. + * All get and set functions taking handles will check access against the desired access stored with + * the handle. If a get or set function needs more access rights than requested in desired access of + * the handle it will fail with with NT_STATUS_ACCESS_DENIED even if the user credentials would allow + * the operation. If more access is desired than the user credentials specify (NT_USER_TOKEN) the + * function will also fail and no handle is returned. + * + * - all pointers to data structures being returned, will point to newly allocated data structures. + * Therefore NULL pointers should be passed in. After having finished using them, the data structures need + * to be freed to prevent memory leakage. + * Memory allocated within the handles is freed by calling the appropriate sam_close_ functions. + * +**/ + + + SAM API -NTSTATUS sam_get_sec_obj(NT_USER_TOKEN *access, DOM_SID *sid, SEC_DESC **sd) -NTSTATUS sam_set_sec_obj(NT_USER_TOKEN *access, DOM_SID *sid, SEC_DESC *sd) - -NTSTATUS sam_lookup_name(NT_USER_TOKEN *access, DOM_SID *domain, char *name, DOM_SID **sid, uint32 *type) -NTSTATUS sam_lookup_sid(NT_USER_TOKEN *access, DOM_SID *sid, char **name, uint32 *type) +/* sam_get_sec_desc returns the security descriptor associated with the object identified by "sid" */ +NTSTATUS sam_get_sec_desc(const NT_USER_TOKEN *access, const DOM_SID *sid, SEC_DESC **sd) +/* sam_set_sec_desc sets the security descriptor of the object identified by "sid" to "sd" */ +NTSTATUS sam_set_sec_desc(const NT_USER_TOKEN *access, const DOM_SID *sid, const SEC_DESC *sd) + +/* sam_lookup_name looks up the object "domain, name" and returns its "sid" as well as its "type" (user, domain group or alias) */ +NTSTATUS sam_lookup_name(const NT_USER_TOKEN *access, const DOM_SID *domain, const char *name, DOM_SID **sid, uint32 *type) +/* sam_lookup_name looks up the object "sid" and returns its "name" as well as its "type" (user, domain group or alias) */ +NTSTATUS sam_lookup_sid(const NT_USER_TOKEN *access, const DOM_SID *sid, char **name, uint32 *type) Domain API -NTSTATUS sam_update_domain(SAM_DOMAIN_HANDLE *domain) +/* sam_update_domain writes the changes made to "domain" into the SAMdb */ +NTSTATUS sam_update_domain(const SAM_DOMAIN_HANDLE *domain) -NTSTATUS sam_enum_domains(NT_USER_TOKEN *access, int32 *domain_count, DOM_SID **domains, char **domain_names) -NTSTATUS sam_lookup_domain(NT_USER_TOKEN *access, char *domain, DOM_SID **domainsid) +/* sam_enum_domains returns a list of all "domains" with their "domain_names" the SAMdb is responsible for */ +NTSTATUS sam_enum_domains(const NT_USER_TOKEN *access, int32 *domain_count, DOM_SID **domains, char **domain_names) +/* sam_lookup_domain returns the "domainsid" of "domain" */ +NTSTATUS sam_lookup_domain(const NT_USER_TOKEN *access, const char *domain, DOM_SID **domainsid) -NTSTATUS sam_get_domain_by_sid(NT_USER_TOKEN *access, uint32 access_desired, DOM_SID *domainsid, SAM_DOMAIN_HANDLE **domain) +/* sam_get_domain_by_sid reads domain information of the domain identified by "domainsid" from the SAMdb and returns a handle on it */ +NTSTATUS sam_get_domain_by_sid(const NT_USER_TOKEN *access, const uint32 access_desired, const DOM_SID *domainsid, SAM_DOMAIN_HANDLE **domain) User API - -NTSTATUS sam_create_user(NT_USER_TOKEN *access, uint32 access_desired, SAM_USER_HANDLE **user) -NTSTATUS sam_add_user(SAM_USER_HANDLE *user) -NTSTATUS sam_update_user(SAM_USER_HANDLE *user) -NTSTATUS sam_delete_user(SAM_USER_HANDLE * user) - -NTSTATUS sam_enum_users(NT_USER_TOKEN *access, DOM_SID *domain, int32 *user_count, SAM_USER_ENUM **users) - -NTSTATUS sam_get_user_by_sid(NT_USER_TOKEN *access, uint32 access_desired, DOM_SID *usersid, SAM_USER_HANDLE **user) -NTSTATUS sam_get_user_by_name(NT_USER_TOKEN *access, uint32 access_desired, char *domain, char *name, SAM_USER_HANDLE **user) - - -Group API - -NTSTATUS sam_create_group(NT_USER_TOKEN *access, uint32 access_desired, uint32 typ, SAM_GROUP_HANDLE **group) -NTSTATUS sam_add_group(SAM_GROUP_HANDLE *samgroup) -NTSTATUS sam_update_group(SAM_GROUP_HANDLE *samgroup) -NTSTATUS sam_delete_group(SAM_GROUP_HANDLE *groupsid) - -NTSTATUS sam_enum_groups(NT_USER_TOKEN *access, DOM_SID *domainsid, uint32 typ, uint32 *groups_count, SAM_GROUP_ENUM **groups) - -NTSTATUS sam_get_group_by_sid(NT_USER_TOKEN *access, uint32 access_desired, DOM_SID *groupsid, SAM_GROUP_HANDLE **group) -NTSTATUS sam_get_group_by_name(NT_USER_TOKEN *access, uint32 access_desired, char *domain, char *name, SAM_GROUP_HANDLE **group) + +/* sam_create_user creates a user handle and initialises its read only data (e.g. sid). It does not write it to the db */ +NTSTATUS sam_create_user(const NT_USER_TOKEN *access, const uint32 access_desired, SAM_USER_HANDLE **user) +/* sam_add_user adds "user" with all its information to the SAMdb */ +NTSTATUS sam_add_user(const SAM_USER_HANDLE *user) +/* sam_update_user updates the changes in "user" to the SAMdb */ +NTSTATUS sam_update_user(const SAM_USER_HANDLE *user) +/* sam_delete_user deletes "user" from the SAMdb and invalidates its handle */ +NTSTATUS sam_delete_user(SAM_USER_HANDLE **user) + +/* sam_enum_users returns a list of all users (along with some frequently used information) in "domain". It does not return handles */ +NTSTATUS sam_enum_users(const NT_USER_TOKEN *access, const DOM_SID *domain, int32 *user_count, SAM_USER_ENUM **users) + +/* sam_get_user_by_sid reads user information of user identified by "usersid" from the SAMdb and returns a handle on it. */ +NTSTATUS sam_get_user_by_sid(const NT_USER_TOKEN *access, const uint32 access_desired, const DOM_SID *usersid, SAM_USER_HANDLE **user) +/* sam_get_user_by_sid reads user information of user identified by "domain, name" from the SAMdb and returns a handle on it. */ +NTSTATUS sam_get_user_by_name(const NT_USER_TOKEN *access, const uint32 access_desired, const char *domain, const char *name, SAM_USER_HANDLE **user) + + +Group API + +/* sam_create_group creates a group handle and initialises its read only data (e.g. sid). It does not write it to the db */ +NTSTATUS sam_create_group(const NT_USER_TOKEN *access, const uint32 access_desired, const uint32 type, SAM_GROUP_HANDLE **group) +/* sam_add_group adds "group" with all its information to the SAMdb */ +NTSTATUS sam_add_group(const SAM_GROUP_HANDLE *group) +/* sam_update_group updates the changes in "group" to the SAMdb */ +NTSTATUS sam_update_group(const SAM_GROUP_HANDLE *group) +/* sam_delete_group deletes "group" from the SAMdb and invalidates its handle */ +NTSTATUS sam_delete_group(SAM_GROUP_HANDLE **groupsid) + +/* sam_enum_groups returns a list of all groups of "type" (local or global) within the domain identified by "domainsid" */ +NTSTATUS sam_enum_groups(const NT_USER_TOKEN *access, const DOM_SID *domainsid, const uint32 type, uint32 *groups_count, SAM_GROUP_ENUM **groups) + +/* sam_get_group_by_sid reads group information of a group identified by "groupsid" from the SAMdb and returns a handle on it */ +NTSTATUS sam_get_group_by_sid(const NT_USER_TOKEN *access, const uint32 access_desired, const DOM_SID *groupsid, SAM_GROUP_HANDLE **group) +/* sam_get_group_by_sid reads group information of a group identified by "domain, name" from the SAMdb and returns a handle on it */ +NTSTATUS sam_get_group_by_name(const NT_USER_TOKEN *access, const uint32 access_desired, const char *domain, const char *name, SAM_GROUP_HANDLE **group) NTSTATUS sam_add_member_to_group(SAM_GROUP_HANDLE *group, SAM_GROUP_MEMBER *member) NTSTATUS sam_delete_member_from_group(SAM_GROUP_HANDLE *group, SAM_GROUP_MEMBER *member) -NTSTATUS sam_enum_groupmembers(SAM_GROUP_HANLDE *group, uint32 *members_count, SAM_GROUP_MEMBER **members) - -NTSTATUS sam_get_groups_of_user(SAM_USER_HANDLE *user, uint32 typ, uint32 *group_count, SAM_GROUP_ENUM **groups) +/* sam_enum_groupmembers returns a list of all direct members of "group" */ +NTSTATUS sam_enum_groupmembers(const SAM_GROUP_HANLDE *group, uint32 *members_count, SAM_GROUP_MEMBER **members) + +/* sam_get_groups_of_user returns a list of all groups "user" is in. Depending upon "type" it will return global, local or nested groups. */ +NTSTATUS sam_get_groups_of_user(const SAM_USER_HANDLE *user, const uint32 type, uint32 *group_count, SAM_GROUP_ENUM **groups) @@ -117,7 +178,7 @@ NTSTATUS sam_{get,set}_user_unknown_4(SAM_USER_HANDLE *user, uint32 *unknown_4) NTSTATUS sam_get_group_sid(SAM_GROUP_HANDLE *group, DOM_SID **sid) -NTSTATUS sam_get_group_typ(SAM_GROUP_HANDLE *group, uint32 *typ) +NTSTATUS sam_get_group_type(SAM_GROUP_HANDLE *group, uint32 *type) NTSTATUS sam_{get,set}_group_name(SAM_GROUP_HANDLE *group, char **group_name) NTSTATUS sam_{get,set}_group_comment(SAM_GROUP_HANDLE *group, char **comment) NTSTATUS sam_{get,set}_group_priv_set(SAM_GROUP_HANDLE *group, PRIVILEGE_SET *priv_set) \ No newline at end of file