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 gchar *       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;

### 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;

### e2k_permissions_role_get_name ()

    const gchar *       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

### E2K_PERMISSION_CREATE

    #define E2K_PERMISSION_CREATE           0x002

### E2K_PERMISSION_EDIT_OWNED

    #define E2K_PERMISSION_EDIT_OWNED       0x008

### E2K_PERMISSION_DELETE_OWNED

    #define E2K_PERMISSION_DELETE_OWNED     0x010

### E2K_PERMISSION_EDIT_ANY

    #define E2K_PERMISSION_EDIT_ANY         0x020

### E2K_PERMISSION_DELETE_ANY

    #define E2K_PERMISSION_DELETE_ANY       0x040

### E2K_PERMISSION_CREATE_SUBFOLDER

    #define E2K_PERMISSION_CREATE_SUBFOLDER 0x080

### E2K_PERMISSION_OWNER

    #define E2K_PERMISSION_OWNER            0x100

### E2K_PERMISSION_CONTACT

    #define E2K_PERMISSION_CONTACT          0x200

### E2K_PERMISSION_FOLDER_VISIBLE

    #define E2K_PERMISSION_FOLDER_VISIBLE   0x400

### E2K_PERMISSION_EDIT_MASK

    #define E2K_PERMISSION_EDIT_MASK (E2K_PERMISSION_EDIT_ANY | E2K_PERMISSION_EDIT_OWNED)

### E2K_PERMISSION_DELETE_MASK

    #define E2K_PERMISSION_DELETE_MASK (E2K_PERMISSION_DELETE_ANY | E2K_PERMISSION_DELETE_OWNED)

## See Also

E2kSid