E2kSecurityDescriptor

E2kSecurityDescriptor — Windows Security Descriptor

Synopsis




struct      E2kSecurityDescriptor;
E2kSecurityDescriptor* e2k_security_descriptor_new
                                            (xmlNodePtr xml_form,
                                             GByteArray *binary_form);
GByteArray* e2k_security_descriptor_to_binary
                                            (E2kSecurityDescriptor *sd);

GList*      e2k_security_descriptor_get_sids
                                            (E2kSecurityDescriptor *sd);
E2kSid*     e2k_security_descriptor_get_default
                                            (E2kSecurityDescriptor *sd);
void        e2k_security_descriptor_remove_sid
                                            (E2kSecurityDescriptor *sd,
                                             E2kSid *sid);

enum        E2kPermissionsRole;
const char* e2k_permissions_role_get_name   (E2kPermissionsRole role);
guint32     e2k_permissions_role_get_perms  (E2kPermissionsRole role);
E2kPermissionsRole e2k_permissions_role_find
                                            (guint perms);

guint32     e2k_security_descriptor_get_permissions
                                            (E2kSecurityDescriptor *sd,
                                             E2kSid *sid);
void        e2k_security_descriptor_set_permissions
                                            (E2kSecurityDescriptor *sd,
                                             E2kSid *sid,
                                             guint32 perms);
#define     E2K_PERMISSION_READ_ANY
#define     E2K_PERMISSION_CREATE
#define     E2K_PERMISSION_EDIT_OWNED
#define     E2K_PERMISSION_DELETE_OWNED
#define     E2K_PERMISSION_EDIT_ANY
#define     E2K_PERMISSION_DELETE_ANY
#define     E2K_PERMISSION_CREATE_SUBFOLDER
#define     E2K_PERMISSION_OWNER
#define     E2K_PERMISSION_CONTACT
#define     E2K_PERMISSION_FOLDER_VISIBLE
#define     E2K_PERMISSION_EDIT_MASK
#define     E2K_PERMISSION_DELETE_MASK

Object Hierarchy


  GObject
   +----E2kSecurityDescriptor

Description

Every object in the Exchange database has a security descriptor that controls access to it. (This includes both folders and items, but security descriptors for items are virtually always inherited from their parent folders in well-defined ways, so we don’t bother thinking about them.)

The Exchange 2000 Web Storage System has a nifty sytem for translating Windows security descriptors into XML and back, which unfortunately we cannot use, because it's buggy. So we have to generate binary format security descriptors, as described below.

When considering folder permissions, it is important to remember that while the Exchange database looks like a file system when accessed via WebDAV, it does not behave like a filesystem internally. In particular, access to an object is controlled only by its own security descriptor; you do not need to have “folder visible” permission on an object’s parent in order to be able to access the object.

Details

struct E2kSecurityDescriptor

struct E2kSecurityDescriptor;

This represents a Windows SECURITY_DESCRIPTOR


e2k_security_descriptor_new ()

E2kSecurityDescriptor* e2k_security_descriptor_new
                                            (xmlNodePtr xml_form,
                                             GByteArray *binary_form);

Constructs an E2kSecurityDescriptor from the data in xml_form and binary_form.

xml_form : the XML form of the folder's security descriptor (The "http://schemas.microsoft.com/exchange/security/descriptor" property, aka E2K_PR_EXCHANGE_SD_XML)
binary_form : the binary form of the folder's security descriptor (The "http://schemas.microsoft.com/exchange/ntsecuritydescriptor" property, aka E2K_PR_EXCHANGE_SD_BINARY)
Returns : the security descriptor, or NULL if the data could not be parsed.

e2k_security_descriptor_to_binary ()

GByteArray* e2k_security_descriptor_to_binary
                                            (E2kSecurityDescriptor *sd);

Converts sd back to binary (E2K_PR_EXCHANGE_SD_BINARY) form so it can be PROPPATCHed back to the server.

sd : an E2kSecurityDescriptor
Returns : the binary form of sd.

e2k_security_descriptor_get_sids ()

GList*      e2k_security_descriptor_get_sids
                                            (E2kSecurityDescriptor *sd);

Returns a GList containing the SIDs of each user or group represented in sd. You can pass these SIDs to e2k_security_descriptor_get_permissions(), e2k_security_descriptor_set_permissions(), and e2k_security_descriptor_remove_sid.

sd : a security descriptor
Returns : a list of SIDs. The caller must free the list with g_list_free(), but should not free the contents.

e2k_security_descriptor_get_default ()

E2kSid*     e2k_security_descriptor_get_default
                                            (E2kSecurityDescriptor *sd);

Returns an E2kSid corresponding to the default permissions associated with sd. You can pass this to e2k_security_descriptor_get_permissions() and e2k_security_descriptor_set_permissions().

sd : a security descriptor
Returns : the "Default" SID

e2k_security_descriptor_remove_sid ()

void        e2k_security_descriptor_remove_sid
                                            (E2kSecurityDescriptor *sd,
                                             E2kSid *sid);

Removes sid from sd. If sid is a user, this means s/he will now have only the default permissions on sd (unless s/he is a member of a group that is also present in sd.)

sd : a security descriptor
sid : a SID

enum E2kPermissionsRole

typedef enum {
	E2K_PERMISSIONS_ROLE_OWNER,
	E2K_PERMISSIONS_ROLE_PUBLISHING_EDITOR,
	E2K_PERMISSIONS_ROLE_EDITOR,
	E2K_PERMISSIONS_ROLE_PUBLISHING_AUTHOR,
	E2K_PERMISSIONS_ROLE_AUTHOR,
	E2K_PERMISSIONS_ROLE_NON_EDITING_AUTHOR,
	E2K_PERMISSIONS_ROLE_REVIEWER,
	E2K_PERMISSIONS_ROLE_CONTRIBUTOR,
	E2K_PERMISSIONS_ROLE_NONE,

	E2K_PERMISSIONS_ROLE_NUM_ROLES,
	E2K_PERMISSIONS_ROLE_CUSTOM = -1
} E2kPermissionsRole;

These identify some predefined sets of permissions; specifically, the ones used by Outlook’s Folder Permissions dialog.


e2k_permissions_role_get_name ()

const char* e2k_permissions_role_get_name   (E2kPermissionsRole role);

Returns the localized name corresponding to role

role : a permissions role
Returns : the name

e2k_permissions_role_get_perms ()

guint32     e2k_permissions_role_get_perms  (E2kPermissionsRole role);

Returns the MAPI permissions associated with role. role may not be E2K_PERMISSIONS_ROLE_CUSTOM.

role : a permissions role
Returns : the MAPI permissions

e2k_permissions_role_find ()

E2kPermissionsRole e2k_permissions_role_find
                                            (guint perms);

Finds the E2kPermissionsRole value associated with perms. If perms don't describe any standard role, the return value will be E2K_PERMISSIONS_ROLE_CUSTOM

perms : MAPI permissions
Returns : the role

e2k_security_descriptor_get_permissions ()

guint32     e2k_security_descriptor_get_permissions
                                            (E2kSecurityDescriptor *sd,
                                             E2kSid *sid);

Computes the MAPI permissions associated with sid. (Only the permissions *directly* associated with sid, not any acquired via group memberships or the Default SID.)

sd : a security descriptor
sid : a SID
Returns : the MAPI permissions

e2k_security_descriptor_set_permissions ()

void        e2k_security_descriptor_set_permissions
                                            (E2kSecurityDescriptor *sd,
                                             E2kSid *sid,
                                             guint32 perms);

Updates or sets sid's permissions on sd.

sd : a security descriptor
sid : a SID
perms : the MAPI permissions

E2K_PERMISSION_READ_ANY

#define     E2K_PERMISSION_READ_ANY

This grants access to read any item in the folder, corresponding to Outlook’s “Read items” permission.


E2K_PERMISSION_CREATE

#define     E2K_PERMISSION_CREATE

This grants access to create new items (but not subfolders) in the folder, corresponding to Outlook’s “Create items” permission.


E2K_PERMISSION_EDIT_OWNED

#define     E2K_PERMISSION_EDIT_OWNED

This grants access to edit items in the folder that you created, corresponding to Outlook’s “Edit Own” permission.


E2K_PERMISSION_DELETE_OWNED

#define     E2K_PERMISSION_DELETE_OWNED

This grants access to delete items in the folder that you created, corresponding to Outlook’s “Delete Own” permission.


E2K_PERMISSION_EDIT_ANY

#define     E2K_PERMISSION_EDIT_ANY

This grants access to edit any item in the folder, corresponding to Outlook’s “Edit All” permission.


E2K_PERMISSION_DELETE_ANY

#define     E2K_PERMISSION_DELETE_ANY

This grants access to delete any item in the folder, corresponding to Outlook’s “Delete All” permission.


E2K_PERMISSION_CREATE_SUBFOLDER

#define     E2K_PERMISSION_CREATE_SUBFOLDER

This grants access to create new subfolders in the folder, corresponding to Outlook’s “Create subfolders” permission.


E2K_PERMISSION_OWNER

#define     E2K_PERMISSION_OWNER

This makes the user an owner of the folder, corresponding to Outlook’s “Owner” permission. Among other things, this allows the user to edit the permissions on the folder.


E2K_PERMISSION_CONTACT

#define     E2K_PERMISSION_CONTACT

This makes the user a contact person for the folder, corresponding to Outlook’s “Folder contact” permission. This does not actually grant any permissions per se.


E2K_PERMISSION_FOLDER_VISIBLE

#define     E2K_PERMISSION_FOLDER_VISIBLE

This grants access to see the folder and its contents, corresponding to Outlook’s “Folder visible” permission.


E2K_PERMISSION_EDIT_MASK

#define     E2K_PERMISSION_EDIT_MASK

This is a mask of the bits that control item-editing permissions. To give the user “Edit None” permission, clear the bits in this mask.


E2K_PERMISSION_DELETE_MASK

#define     E2K_PERMISSION_DELETE_MASK

This is a mask of the bits that control item-deleting permissions. To give the user “Delete None” permission, clear the bits in this mask.

See Also

E2kSid