E2kSecurityDescriptor

## 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         0x001

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

### E2K_PERMISSION_CREATE

    #define E2K_PERMISSION_CREATE           0x002

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       0x008

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     0x010

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         0x020

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       0x040

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 0x080

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

### E2K_PERMISSION_OWNER

    #define E2K_PERMISSION_OWNER            0x100

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          0x200

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   0x400

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	(E2K_PERMISSION_EDIT_ANY | E2K_PERMISSION_EDIT_OWNED)

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	(E2K_PERMISSION_DELETE_ANY | E2K_PERMISSION_DELETE_OWNED)

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