Data Types

sec_acl_handle_t
A pointer to an opaque handle bound to an ACL that is the subject of a test or examination. The handle is bound to the ACL with sec_acl_bind( ). An unbound handle has the value sec_acl_default_handle.

sec_acl_posix_semantics_t
A flag that indicates which, if any, POSIX ACL semantics an ACL manager supports. The following constants are defined for use with the sec_acl_posix_semantics_t data type:

sec_acl_posix_no_semantics
The manager type does not support POSIX semantics.

sec_acl_posix_mask_obj
The manager type supports the mask_obj entry type and POSIX 1003.6 Draft 12 ACL mask entry semantics.

sec_acl_t
This data type is the fundamental type for the ACL manager interfaces. The sec_acl_t type contains a complete access control list, made up of a list of entry fields (type sec_acl_entry_t). The default cell identifies the authentication authority for simple ACL entries (foreign entries identify their own foreign cells). The sec_acl_manager_type identifies the manager to interpret this ACL.

The sec_acl_t type is a structure containing the following fields:

default_realm
A structure of type sec_acl_id_t, this identifies the UUID and (optionally) the name of the default cell.

sec_acl_manager_type
Contains the UUID of the ACL manager type.

num_entries
An unsigned 32-bit integer containing the number of ACL entries in this ACL.

sec_acl_entries
An array containing num_entries pointers to different ACL entries, each of type sec_acl_entry_t.

sec_acl_p_t
This data type, simply a pointer to a sec_acl_t, is for use with the sec_acl_list_t data type.

sec_acl_list_t
This data type is a structure containing an unsigned 32-bit integer num_acls that describes the number of ACLs indicated by its companion array of pointers, sec_acls, of type sec_acl_p_t.

sec_acl_entry_t
The sec_acl_entry_t type is a structure made up of the following components:

perms
A set of flags of type sec_acl_permset_t that describe the permissions granted for the principals identified by this ACL entry. Note that if a principal matches more than one ACL entry, the effective permissions will be the most restrictive combination of all the entries.

entry_info
A structure containing two members:

entry_type
A flag of type sec_acl_entry_type_t, indicating the type of ACL entry.

tagged_union
A tagged union whose contents depend on the type of the entry.

The types of entries indicated by entry_type can be the following:

sec_acl_e_type_user_obj
The entry contains permissions for the implied user object. This type is described in the POSIX 1003.6 standard.

sec_acl_e_type_group_obj
The entry contains permissions for the implied group object. This type is described in the POSIX 1003.6 standard.

sec_acl_e_type_other_obj
The entry contains permissions for principals not otherwise named through user or group entries. This type is described in the POSIX 1003.6 standard.

sec_acl_e_type_user
The entry contains a key that identifies a user. This type is described in the POSIX 1003.6 standard.

sec_acl_e_type_group
The entry contains a key that identifies a group. This type is described in the POSIX 1003.6 standard.

sec_acl_e_type_mask_obj
The entry contains the maximum permissions for all entries other than mask_obj, unauthenticated, user_obj, other_obj.

sec_acl_e_type_foreign_user
The entry contains a key that identifies a user and the foreign realm.

sec_acl_e_type_foreign_group
The entry contains a key that identifies a group and the foreign realm.

sec_acl_e_type_foreign_other
The entry contains a key that identifies a foreign realm. Any user that can authenticate to the foreign realm will be allowed access.

sec_acl_e_type_any_other
The entry contains permissions to be applied to any accessor who can authenticate to any realm, but is not identified in any other entry (except sec_acl_e_type_unauthenticated).

sec_acl_e_type_unauthenticated
The entry contains permissions to be applied when the accessor does not pass authentication procedures. A privilege attribute certificate will indicate that the caller's identity is not authenticated. The identity is used to match against the standard entries, but the access rights are masked by this mask. If this mask does not exist in an ACL, the ACL is assumed to grant no access and all unauthenticated access attempts will be denied.

Great care should be exercised when allowing unauthenticated access to an object. Almost by definition, unauthenticated access is very easy to spoof. The presence of this mask on an ACL essentially means that anyone can get at least as much access as allowed by the mask.

sec_acl_e_type_extended
The entry contains additional "pickled" data. This kind of entry cannot be interpreted, but can be used by an out-of-date client when copying an ACL from one manager to another (assuming that the two managers each understand the data).

The contents of the tagged union depend on the entry type.

For the following entry types, the union contains a UUID and an optional print string (called entry_info.tagged_union.id with type sec_id_t) for an identified local principal, or for an identified foreign realm.

· sec_acl_e_type_user

· sec_acl_e_type_group

· sec_acl_type_foreign_other

For the following entry types, the union contains two UUIDs and optional print strings (called entry_info.tagged_union.foreign_id with type sec_id_foreign_t) for an identified foreign principal and its realm.

· sec_acl_e_type_foreign_user

· sec_acl_e_type_foreign_group

For an extended entry (sec_acl_e_type_extended), the union contains entry_info.tagged_union.extended_info, a pointer to an information block of type sec_acl_extend_info_t.

sec_acl_permset_t
A 32-bit set of permission flags. The flags currently represent the conventional file system permissions (read, write, execute) and the extended DFS permissions (owner, insert, delete).

The unused flags represent permissions that can only be interpreted by the manager for the object. For example, sec_acl_perm_unused_00000080 may mean to one ACL manager that withdrawals are allowed, and to another ACL manager that rebooting is allowed.

The following constants are defined for use with the sec_acl_permset_t data type:

sec_acl_perm_read
The ACL allows read access to the protected object.

sec_acl_perm_write
The ACL allows write access to the protected object.

sec_acl_perm_execute
The ACL allows execute access to the protected object.

sec_acl_perm_control
The ACL allows the ACL itself to be modified.

sec_acl_perm_insert
The ACL allows insert access to the protected object.

sec_acl_perm_delete
The ACL allows delete access to the protected object.

sec_acl_perm_test
The ACL allows access to the protected object only to the extent of being able to test for existence.

The bits from 0x00000080 to 0x80000000 are not used by the conventional ACL permission set. Constants of the form sec_acl_perm_unused_00000080 have been defined so application programs can easily use these bits for extended ACLs.

sec_acl_extend_info_t
This is an extended information block, provided for future extensibility. Primarily, this allows an out-of-date client to read an ACL from a newer manager and apply it to another (up-to-date) manager. The data cannot be interpreted by the out-of-date client without access to the appropriate "pickling" routines (that presumably are unavailable to such a client).

In general, ACL managers should not accept ACLs that contain entries the manager does not understand. The manager clearly cannot perform the security service requested by an uninterpretable entry, and it is considered a security breach to lead a client to believe that the manager is performing a particular class of service if the manager cannot do so.

The data structure is made up of the following components:

extension_type
The UUID of the extension type.

format_label
The format of the label, in ndr_format_t form.

num_bytes
An unsigned 32-bit integer indicating the number of bytes containing the "pickled" data.

pickled_data
The byte array containing the pickled data.

sec_acl_type_t
The sec_acl_type_t type differentiates among the various types of ACLs an object can possess. Most file system objects will only have one ACL controlling the access to that object, but objects that control the creation of other objects (sometimes referred to as containers) may have more. For example, a directory can have three different ACLs: the directory ACL, controlling access to the directory; the initial object (or default object) ACL, which serves as a mask when creating new objects in the directory; and the initial directory (or default directory) ACL, which serves as a mask when creating new directories (containers).

The sec_acl_type_t is an enumerated set containing one of the following values:

sec_acl_type_object
The ACL refers to the specified object.

sec_acl_type_default_object
The ACL is to be used when creating objects in the container.

sec_acl_type_default_container
The ACL is to be used when creating nested containers.

The following values are defined but not currently used. They are available for application programs that may create an application-specific ACL definition.

sec_acl_type_unspecified_3

sec_acl_type_unspecified_4

sec_acl_type_unspecified_5

sec_acl_type_unspecified_6

sec_acl_type_unspecified_7

sec_acl_printstring_t
A sec_acl_printstring_t structure contains a printable representation for a permission in a sec_acl_permset_t permission set. This allows a generic ACL editing tool to be used for application-specific ACLs. The tool need not know the printable representation for each permission bit in a given permission set. The sec_acl_get_printstring( ) function will query an ACL manager for the print strings of the permissions it supports.

The structure consists of three components:

printstring
A character string of maximum length sec_acl_printstring_len describing the printable representation of a specified permission.

helpstring
A character string of maximum length sec_acl_printstring_help_len containing some text that may be used to describe the specified permission.

permissions
A sec_acl_permset_t permission set describing the permissions that will be represented with the specified print string.

sec_acl_component_name_t
This type is a pointer to a character string, to be used to specify the entity a given ACL is protecting.