16-Metadata

Access control comprises the mechanisms by which various types of access to objects and containers are authorized and permitted or denied. CDMI™ uses the well-known mechanism of an Access Control List (ACL) as defined in the NFSv4 standard (see RFC 3530). ACLs are lists of permissions-granting or permissions-denying entries called access control entries (ACEs).

An ACL is an ordered list of ACEs. The two types of ACEs in CDMI are ALLOW and DENY. An ALLOW ACE grants some form of access to a principal. Principals are either users or groups and are represented by identifiers. A DENY ACE denies access of some kind to a principal. For instance, a DENY ACE may deny the ability to write the metadata or ACL of an object but may remain silent on other forms of access. In that case, if another ACE ALLOWs write access to the object, the principal is allowed to write the object's data, but nothing else.

While the type, flags, and access_mask are specified as unsigned integers, for efficiency, each defined bit in them has a corresponding string (in C, the label-pasted form of the macro), which may be used where desired for readability.

Note: The reason that the string forms may be safely abbreviated is that they are local to the ACE structure type, as opposed to constants, which are relatively global in scope.

The client is responsible for ordering the ACEs in an ACL. The server shall not enforce any ordering and shall store and evaluate the ACEs in the order given by the client.

The special "who" identifiers need to be understood universally, rather than in the context of a particular external security domain (see Table 114). Some of these identifiers may not be understood when a CDMI client accesses the server, but they may have meaning when a local process accesses the file. The ability to display and modify these permissions is permitted over CDMI, even if none of the access methods on the server understands the identifiers.

To avoid name conflicts, these special identifiers are distinguished by an appended "@" (with no domain name).

CDMI allows for nested containers and mandates that objects and subcontainers be able to inherit access permissions from their parent containers. However, it is not enough to simply inherit all permissions from the parent; it might be desirable, for example, to have different default permissions on child objects and subcontainers of a given container. The flags in Table 115 govern this behavior

String Form	Description	Constant	Bit Mask
"NO_FLAGS"	No flags are set	CDMI_ACE_FLAGS_NONE	0x00000000
"OBJECT_INHERIT"	An ACE on which OBJECT_INHERIT is set is inherited by objects as an effective ACE: OBJECT_INHERIT is cleared on the child object. When the ACE is inherited by a container, OBJECT_INHERIT is retained for the purpose of inheritance, and additionally, INHERIT_ONLY is set.	CDMI_ACE_FLAGS_OBJECT_INHERIT_ACE	0x00000001
"CONTAINER_INHERIT"	An ACE on which CONTAINER_INHERIT is set is inherited by a subcontainer as an effective ACE. Both INHERIT_ONLY and CONTAINER_INHERIT are cleared on the child container.	CDMI_ACE_FLAGS_CONTAINER_INHERIT_ACE	0x00000002
"NO_PROPAGATE"	An ACE on which NO_PROPAGATE is set is not inherited by any objects or subcontainers. It applies only to the container on which it is set.	CDMI_ACE_FLAGS_NO_PROPAGATE_ACE	0x00000004
"INHERIT_ONLY"	An ACE on which INHERIT_ONLY is set is propagated to children during ACL inheritance as specified by OBJECT_INHERIT and CONTAINER_INHERIT. The ACE is ignored when evaluating access to the container on which it is set and is always ignored when set on objects.	CDMI_ACE_FLAGS_INHERIT_ONLY_ACE	0x00000008
"IDENTIFIER_GROUP"	An ACE on which IDENTIFIER_GROUP is set indicates that the "who" refers to a group identifier.	CDMI_ACE_FLAGS_IDENTIFIER_GROUP	0x00000040
"INHERITED"	An ACE on which INHERITED is set indicates that this ACE is inherited from a parent directory. A server that supports automatic inheritance will place this flag on any ACEs inherited from the parent directory when creating a new object.	CDMI_ACE_FLAGS_INHERITED_ACE	0x00000080

The mask field of an ACE contains 32 bits. Table 116 defines the ACE bit masks in CDMI; their values are taken from the IETF NFSv4 RFC 3530

String Form	Description	Constant	Bit Mask
"READ_OBJECT"	Permission to read the value of a data object	CDMI_ACE_READ_OBJECT	0x00000001
"LIST_CONTAINER"	Permission to list the children of a container object	CDMI_ACE_LIST_CONTAINER	0x00000001
"WRITE_OBJECT"	Permission to modify the value of a data object	CDMI_ACE_WRITE_OBJECT	0x00000002
"ADD_OBJECT"	Permission to add a new child data object or queue object to a container object	CDMI_ACE_ADD_OBJECT	0x00000002
"APPEND_DATA"	Permission to append data to the value of a data object	CDMI_ACE_APPEND_DATA	0x00000004
"ADD_SUBCONTAINER"	Permission to create a child container object in a container object	CDMI_ACE_ADD_SUBCONTAINER	0x00000004
"READ_METADATA"	Permission to read non-ACL metadata of an object	CDMI_ACE_READ_METADATA	0x00000008
"WRITE_METADATA"	Permission to write non-ACL metadata of an object	CDMI_ACE_WRITE_METADATA	0x00000010
"EXECUTE"	Permission to execute an object	CDMI_ACE_EXECUTE	0x00000020
"DELETE_OBJECT"	Permission to delete a child data object or queue object from a container object	CDMI_ACE_DELETE_OBJECT	0x00000040
"DELETE_SUBCONTAINER"	Permission to delete a child container object from a container object	CDMI_ACE_DELETE_SUBCONTAINER	0x00000040
"READ_ATTRIBUTES"	Permission to read non-metadata and non-value/children fields of an object	CDMI_ACE_READ_ATTRIBUTES	0x00000080
"WRITE_ATTRIBUTES"	Permission to change non-metadata and non-value/children fields of an object	CDMI_ACE_WRITE_ATTRIBUTES	0x00000100
"WRITE_RETENTION"	Permission to change retention attributes of an object	CDMI_ACE_WRITE_RETENTION	0x00000200
"WRITE_RETENTION_HOLD"	Permission to change hold attributes of an object	CDMI_ACE_WRITE_RETENTION_HOLD	0x00000400
"DELETE"	Permission to delete an object	CDMI_ACE_DELETE	0x00010000
"READ_ACL"	Permission to Read the ACL of an object	CDMI_ACE_READ_ACL	0x00020000
"WRITE_ACL"	Permission to Write the ACL of an object	CDMI_ACE_WRITE_ACL	0x00040000
"WRITE_OWNER"	Permission to change the owner of an object	CDMI_ACE_WRITE_OWNER	0x00080000
"SYNCHRONIZE"	Permission to access an object locally at the server with synchronous reads and writes	CDMI_ACE_SYNCHRONIZE	0x0010000

Implementations shall use the correct string form to display permissions, if the object type is known. If the object type is unknown, the "object" version of the string shall be used.

When evaluating whether access to a particular object O by a principal P shall be granted, the server traverses the object's logical ACL (its ACL after processing inheritance from ancestor containers) in list order, using a temporary permissions bitmask m, initially empty (all zeroes).

• If the ACL timestamp is nonexistent or is older than that of some parent (see foregoing discussion in previous subclause), use get_acl(O, P) to set the physical ACL equal to the logical ACL.

• If the object still does not contain an ACL, the algorithm terminates and access is denied for all users and groups. This condition is not expected, as CDMI implementations should require an inheritable default ACL on all root containers.

• ACEs that do not refer to the principal P requesting the operation are ignored.

• If an ACE is encountered that denies access to P for any of the requested mask bits, access is denied and the algorithm terminates.

• If an ACE is encountered that allows access to P, the permissions mask m for the operation is XORed with the permissions mask from the ACE. If m is sufficient for the operation, access is granted and the algorithm terminates.

• If the end of the ACL list is reached and permission has neither been granted nor explicitly denied, access is denied and the algorithm terminates, unless the object is a container root. In this case, the server shall:

— allow access to the container owner, ADMINISTRATOR@, and any member of ADMINUSERS@; and

When permission for the desired access is not explicitly given, even ADMINISTRATOR@ and equivalents are denied for objects that aren't container roots. When an admin needs to access an object in such an instance, the root container shall be accessed and its inheritable ACEs changed in a way as to allow access to the original object. The resulting log entry then provides an audit trail for the access.

When a root container is created and no ACL is supplied, the server shall place an ACL containing the following ACEs on the container:

As ACLs are metadata, they are stored and retrieved through the metadata field included in a PUT or GET request. The syntax is as follows:

ACL = { ACE [, ACE ...] }

ACE = { acetype , identifier , aceflags , acemask , acetime }

acetype = uint_t | acetypeitem

identifier = utf8string_t

aceflags = uint_t | aceflagsstring

acemask = uint_t | acemaskstring

acetypeitem = aceallowedtype |

acedeniedtype |

aceaudittype

aceallowedtype = "CDMI_ACE_ACCESS_ALLOWED_TYPE" | 0x0

acedeniedtype = "CDMI_ACE_ACCESS_DENIED_TYPE" | 0x01

aceaudittype = "CDMI_ACE_SYSTEM_AUDIT_TYPE" | 0x02

aceflagsstring = aceflagsitem [| aceflagsitem ...]

aceflagsitem = aceobinherititem |

acecontinherititem |

acenopropagateitem |

aceinheritonlyitem

aceobinherititem = "CDMI_ACE_OBJECT_INHERIT_ACE" | 0x01

acecontinherititem = "CDMI_ACE_CONTAINER_INHERIT_ACE" | 0x02

acenopropagateitem = "CDMI_ACE_NO_PROPAGATE_INHERIT_ACE" | 0x04

aceinheritonlyitem = "CDMI_ACE_INHERIT_ONLY_ACE" | 0x08

acemaskstring = acemaskitem [| acemaskitem ...]

acereaditem = "CDMI_ACE_READ_OBJECT" |

"CDMI_ACE_LIST_CONTAINER" | 0x01

acewriteitem = "CDMI_ACE_WRITE_OBJECT" |

"CDMI_ACE_ADD_OBJECT" | 0x02

aceappenditem = "CDMI_ACE_APPEND_DATA" |

"CDMI_ACE_ADD_SUBCONTAINER" | 0x04

acereadmetaitem = "CDMI_ACE_READ_METADATA" | 0x08

acewritemetaitem = "CDMI_ACE_WRITE_METADATA" | 0x10

acedeleteitem = "CDMI_ACE_DELETE_OBJECT" |

"CDMI_ACE_DELETE_SUBCONTAINER" | 0x40

acedelselfitem = "CDMI_ACE_DELETE" | 0x10000

acereadaclitem = "CDMI_ACE_READ_ACL" | 0x20000

acewriteaclitem = "CDMI_ACE_WRITE_ACL" | 0x40000

aceexecuteitem = "CDMI_ACE_EXECUTE" | 0x80000

acereadattritem = "CDMI_ACE_READ_ATTRIBUTES" | 0x00080

acewriteattritem = "CDMI_ACE_WRITE_ATTRIBUTES" | 0x00100

aceretentionitem = "CDMI_ACE_SET_RETENTION" | 0x10000000

When ACE masks are presented in numeric format, they shall, at all times, be specified in hexadecimal notation with a leading "0x". This format allows both servers and clients to quickly determine which of the two forms of a given constant is being used. When masks are presented in string format, they shall be converted to numeric format and then evaluated using standard bitwise operators.

When an object is created, no ACL is supplied, and an ACL is not inherited from the parent container (or there is no parent container), the server shall place an ACL containing the following ACEs on the object:

ACE mask expressions shall always be evaluated and converted to a single hexadecimal value before transmission in an HTTP protocol datagram. Applications or utilities that display them to users should convert them into a text expression prior to display and accept user input in text format as well. The C bitwise operators "|" and "&" should be used for textual representations of bitmask entities.

The following technique should be used to decompose masks into strings. A table of masks and string equivalents should be maintained and ordered from greatest to least:

• If the object is a container, select the string from the 3rd column; otherwise, select the string from the 2nd column.

The complete textual representation is then all the selected strings concatenated with " | " between them, e.g., "ALL_PERMS | WRITE_OWNER". The strings should appear in the order they are selected.

A similar technique should be used for all other sets of hex/string equivalents.

This algorithm, properly coded, requires only one (often partial) pass through the corresponding string equivalents table.

ACE flags and masks are members of a 32-bit quantity that is widely understood in its hexadecimal representations. The JSON data format does not support hexadecimal integers, however. For this reason, all hexadecimal integers in CDMI ACLs shall be represented as quoted strings containing a leading "0x".

EXAMPLE An example of an ACL embedded in a response to a GET request is as follows:

All CDMI objects that support metadata shall permit the inclusion of arbitrary user-defined metadata items, with the restriction that the name of a user-defined metadata item shall not start with the prefix "cdmi_".

• The maximum number of user-defined metadata items is specified by the capability "cdmi_metadata_maxitems".

• The maximum size of each user-defined metadata item is specified by the capability "cdmi_metadata_maxsize".

After an object has been created, the storage system metadata, as described in Table 117, shall be generated by the cloud storage system and shall immediately be made available to a CDMI client in the metadata that is returned as a result of the create operation and any subsequent retrievals.

Metadata Name	Type	Description	Requirement
cdmi_size	JSON String	The number of bytes consumed by the object. This storage system metadata item is computed by the storage system, and any attempts to set or modify it will be ignored.	Optional
cdmi_ctime	JSON String	The time when the object was created, in ISO-8601 point-in-time format, as described in 5.14.	Optional
cdmi_atime	JSON String	The time when the object was last accessed in ISO-8601 point-in-time format, as described in 5.14. The access or modification of a child is not considered an access of a parent container (access/modify times do not propagate up the tree).	Optional
cdmi_mtime	JSON String	The time when the object was last modified, in ISO-8601 point-in-time format, as described in 5.14. The modification of a child is not considered a modification of a container (modification times do not propagate up the tree).	Optional
cdmi_acount	JSON String	The number of times that the object has been accessed since it was originally created. Accesses include all reads, writes, and lists.	Optional
cdmi_mcount	JSON String	The number of times that the object has been modified since it was originally created. Modifications include all value and metadata changes. Modifications to metadata resulting from reads (such as updates to atime) do not count as a modification.	Optional
cdmi_hash	JSON String	The hash of the value of the object, encoded using Base16 encoding rules described in RFC 4648. This metadata field shall be present when the "cdmi_value_hash" data system metadata for the object or a parent object indicates that the value of the object should be hashed.	Optional
cdmi_owner	JSON String	The name of the principal that has owner privileges for the object.	Mandatory
cdmi_acl	JSON Array of JSON Objects	Standard ACL metadata. If not specified when the object is created, this metadata shall be filled in by the system.	Optional

When specified, data system metadata provides guidelines to the cloud storage system on how to provide storage data services for data managed through the CDMI interface.

Data system metadata (see Table 118) is inherited from parent objects to any children. If a child explicitly contains data system metadata, the metadata value of the child data system shall override the metadata value of the parent data system.

Metadata Name	Type	Description	Requirement
cdmi_data_redundancy	JSON String	Contains the desired number of complete copies of the data object to be maintained. This number determines the minimum number of primary copies of the data that the cloud shall maintain. Additional primary copies may be made to satisfy demand for the value.	Optional
cdmi_immediate_redundancy	JSON String	If present and set to the value "true", indicates that at least a cdmi_data_redundancy number of copies shall contain the newly written value before the operation completes. This metadata is used to make sure that multiple copies of the data are written to permanent storage to prevent possible data loss.	Optional
cdmi_assignedsize (only valid for a container.) See Clause 9.	JSON String	Contains the number of bytes that are reported via exported protocols (and may be thin provisioned by the system). This number may limit cdmi_size for the container. This metadata is the size that shall be shown through any number of data path protocols that are used to export a container. If the container is thin provisioned, this may be greater than the actual storage consumed.	Optional
cdmi_infrastructure_redundancy	JSON String	Contains the number of desired independent storage infrastructures supporting the data. This metadata is used to convey that, of the primary copies specified in cdmi_data_redundancy, these copies shall be stored on this many separate infrastructures. Any two infrastructures may not share common elements, such as a network or power source.	Optional
cdmi_data_dispersion	JSON String	Contains the desired distance (km) between the infrastructures supporting the multiple copies of data. This metadata is used to separate the (cdmi_infrastructure_redundancy number of) infrastructures by a minimum geographic distance to prevent data loss due to site disasters.	Optional
cdmi_geographic_placement	JSON Array of JSON Strings	Contains a list of geopolitical identifiers, each specifying a region where the object is permitted or not permitted to be stored. Geopolitical boundaries are a list of ISO 3166 country codes. A "!" in front of a country code excludes that country from the previous list of geopolitical boundaries. This metadata limits where the object is permitted to be stored. If this data system metadata item is supported and the cloud is not able to guarantee that the data will be stored within the specified geographic placement restrictions, create or update operations shall fail with an HTTP 403 status code. Specified geographic placement restrictions only apply within the context of a cloud storage system that supports this data system metadata item. This metadata takes precedent over other metadata, such as cdmi_data_dispersion.	Optional
cdmi_retention_id	JSON String	Contains a user-specified retention identifier. This metadata is a user-specified text field that is used to tag a given object as being managed by a specific retention policy. It is not required to place an object under retention but is useful when needing to be able to perform a query to find all objects under a specific retention policy.	Optional
cdmi_retention_period	JSON String	Contains an ISO 8601:2004 time interval (as described in 5.14) during which the object is under retention. Only the end-date may be altered when updated. If an object is under retention, the object may not be deleted and its value may not be altered. After the retention date has passed, the object may be deleted.	Optional
cdmi_retention_autodelete	JSON String	This metadata is used to indicate if the object is to be automatically deleted when retention expires. The value of this metadata item shall be "true" when set.	Optional
cdmi_hold_id	JSON Array of JSON Strings	This metadata is used to indicate if the object is to be placed under a retention hold. If the array is not empty, the object is under a hold, with each string in the array containing a user-specified hold identifier. If an object is under one or more holds, the object is completely immutable.	Optional
cdmi_encryption	JSON String	This metadata shall be set by the client to indicate that the server shall encrypt the object using the encryption algorithm and key length specified. All data related to the data object/container shall be encrypted when this value is set, including metadata. Supported algorithm/length values are provided by the cdmi_encryption capability.	Optional
cdmi_encryption	JSON String		Optional
cdmi_value_hash	JSON String	This metadata shall be set by the client to indicate that the server shall hash the object value using the hashing algorithm and length specified. The result of the hash shall be provided in the cdmi_hash storage system metadata item. If absent or when an algorithm or length that is not supported by the server is specified, the cdmi_hash storage system metadata item shall not be provided. Supported algorithm/length values are provided by the cdmi_value_hash capability.	Optional
cdmi_latency	JSON String	Contains the desired maximum time to first byte, in milliseconds. This metadata is the desired latency (in milliseconds) to the first byte of data in a primary copy, as measured from the edge of the cloud and factoring out any propagation latency between the client and the cloud. For example, this metadata may be used to determine, in an interoperable way, from what type of storage medium the primary copy(s) of the data may be served.	Optional
cdmi_throughput	JSON String	Contains the desired maximum data rate on retrieve, in bytes per second. This metadata is the desired bandwidth to the primary copy of data, as measured from the edge of the cloud and factoring out any bandwidth capability between the client and the cloud. This metadata is used to stage the primary data copies in locations where there is sufficient bandwidth to accommodate a maximum usage.	Optional
cdmi_sanitization_method	JSON String	If present, this metadata specifies the sanitization method selected from the list in the cdmi_sanitization_method capability list. If absent, objects shall not be securely sanitized.	Optional
cdmi_RPO	JSON String	Contains the largest acceptable duration in time between an update and when the update may be recovered, specified in seconds. This metadata is used to indicate the desired backup frequency from the primary copy(s) of the data to the secondary copy(s). It is the maximum acceptable duration between a write to the primary copy and the backup to the secondary copy during which a failure of the primary copy(s) shall result in data loss.	Optional
cdmi_RTO	JSON String	Contains the largest acceptable duration in time to restore data, specified in seconds. This metadata is used to indicate the desired maximum acceptable duration to restore the primary copy(s) of the data from a secondary backup copy(s).	Optional

For each metadata item in a data system, there is an actual value that the offering is able to achieve at this time, as shown in Table 119.

Metadata Name	Type	Description	Requirement
cdmi_data_redundancy_provided	JSON String	Contains the current number of complete copies of the data object at this time	Optional
cdmi_immediate_redundancy_provided	JSON String	If present and set to "true", indicates if immediate redundancy is provided for the object	Optional
cdmi_infrastructure_redundancy_provided	JSON String	Contains the current number of independent storage infrastructures supporting the data currently operating.	Optional
cdmi_data_dispersion_provided	JSON String	Contains the current lowest distance (km) between any two infrastructures hosting the data	Optional
cdmi_geographic_placement_provided	JSON Array of JSON Strings	Each string contains an ISO-3166 identifier that corresponds to a geopolitical region where the object is stored.	Optional
cdmi_retention_period_provided	JSON String	Contains an ISO 8601:2004 time interval (as described in 5.14) specifying the period the object is protected by retention	Optional
cdmi_retention_autodelete_provided	JSON String	Contains "true" if the object will automatically be deleted when retention expires	Optional
cdmi_hold_id_provided	JSON Array of JSON Strings	Contains the user-specified hold identifiers for active holds	Optional
cdmi_encryption_provided	JSON String	Contains the algorithm used for encryption, the mode of operation, and the key size. (See cdmi_encryption in Table 118 for the format.)	Optional
cdmi_value_hash_provided	JSON String	Contains the algorithm and length being used to hash the object value	Optional
cdmi_latency_provided	JSON String	Contains the provided maximum time to first byte	Optional
cdmi_throughput_provided	JSON String	Contains the provided maximum data rate on retrieve	Optional
cdmi_sanitization_method_provided	JSON String	Contains the sanitization method used	Optional
cdmi_RPO_provided	JSON String	Contains the provided duration, in seconds, between an update and when the update may be recovered	Optional
cdmi_RTO_provided	JSON String	Contains the provided duration, in seconds, to restore data	Optional

Who	Description
"OWNER@"	The owner of the file
"GROUP@"	The group associated with the file
"EVERYONE@"	The world
"ANONYMOUS@"	Accessed without any authentication
"AUTHENTICATED@"	Any authenticated user (opposite of ANONYMOUS)
"ADMINISTRATOR@"	A user with administrative status, e.g., root
"ADMINUSERS@"	A group whose members are given administrative status