16    Metadata

16.1   Access Control

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).

16.1.1   ACL and ACE Structure

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.

ACEs are composed of four fields: type, who, flags, and access_mask, as per RFC 3530. The type, flags, and access_mask shall be specified as either unsigned integers in hex string representation or as a comma-delimited list of bit mask string form values taken from Table 112, Table 114, and Table 115.

16.1.2   ACE Types

Table 112 defines the following ACE types, following NFSv4.

Table 112 - ACE Types

String Form

Description

Constant

Bit Mask

"ALLOW"

Allow access rights for a principal

CDMI_ACE_ACCESS_ALLOW

0x00000000

"DENY"

Deny access rights for a principal

CDMI_ACE_ACCESS_DENY

0x00000001

"AUDIT"

Generate an audit record when the principal attempts to exercise the specified access rights

CDMI_ACE_SYSTEM_AUDIT

0x00000002

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.

16.1.3   ACE Who

The special "who" identifiers need to be understood universally, rather than in the context of a particular external security domain (see Table 113). 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.

Table 113 - Who Identifiers

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

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

16.1.4   ACE Flags

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 114 govern this behavior

Table 114 - ACE Flags

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

.

16.1.5   ACE Mask Bits

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

Table 115 - ACE Bit Masks

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

0x00100000

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.

16.1.6   ACL Evaluation

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

   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

   log an event indicating what has happened.

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:

"cdmi_acl":

[

   {

       "acetype": "ALLOW",

       "identifier": "OWNER@",

       "aceflags": "OBJECT_INHERIT, CONTAINER_INHERIT",

       "acemask": "ALL_PERMS"

   },

   {

       "acetype": "ALLOW",

       "identifier": "AUTHENTICATED@",

       "aceflags": "OBJECT_INHERIT, CONTAINER_INHERIT",

       "acemask": "READ"

   }

]

As ACLs are storage system metadata, they are stored and retrieved through the metadata field included in a PUT or GET request. The syntax is as follows, using the constant strings from Table 112, Table 114, and Table 115, above. 

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

ACE = { acetype , identifier , aceflags , acemask }

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 ...]

acemaskitem    =   acereaditem | acewriteitem |
   aceappenditem | acereadmetaitem |
   acewritemetaitem | acedeleteitem |
   acedelselfitem | acereadaclitem |
    acewriteaclitem | aceexecuteitem |
    acereadattritem | acewriteattritem |
   aceretentionitem

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:

"cdmi_acl":

[

   {

       "acetype": "ALLOW",

       "identifier": "OWNER@",

       "aceflags": "OBJECT_INHERIT, CONTAINER_INHERIT",

       "acemask": "ALL_PERMS"

   }

]

16.1.7   Example ACE Mask Expressions

EXAMPLE 1   

"READ_ALL" | 0x02

evaluates to 0x09 | 0x02 == 0x0

EXAMPLE 2   

0x001F07FF

evaluates to 0x001F07FF == "ALL_PERMS"

EXAMPLE 3   

"RW_ALL" | DELETE

evaluates to 0x000601DF | 0x00100000 == 0x000701DF

16.1.8   Canonical Format for ACE Hexadecimal Quantities

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 before 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:

0x001F07FF    "ALL_PERMS"       "ALL_PERMS"

0x0006006F    "RW_ALL"          "RW_ALL"

0x0000001F    "RW"              "RW"

                ...

0x00000002    "WRITE_OBJECT"    "ADD_OBJECT"

0x00000001    "READ_OBJECT"     "LIST_CONTAINER"

Given an access mask M, the following is repeated until M == 0:

1   Select the highest mask m from the table such that M & m == m.

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

3   Bitwise subtract m from M, i.e., set M = M xor m.

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.

16.1.9   JSON Format for ACLs

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".

ACLs containing one or more ACEs shall be represented in JSON as follows:

{

   "cdmi_acl" : [

       {

           "acetype" : "0xnn",

           "identifier" : "<user-or-group-name>",

           "aceflags" : "0xnn",

           "acemask" : "0xnn"

       },

       {

           "acetype" : "0xnn",

           "identifier" : "<user-or-group-name>",

           "aceflags" : "0xnn",

           "acemask" : "0xnn"

        }

   ]

}

ACEs in such an ACL shall be evaluated in order as they appear.

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

HTTP/1.1 200 OK

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "objectType" : "/application/cdmi-object",

   "objectID" : "0000706D0010734CE0BAEB29DD542B51",

   "objectName" : "MyDataItem.txt",

   "parentURI" : "/MyContainer/",

   "domainURI" : "/cdmi_domains/MyDomain/",

   "capabilitiesURI" : "/cdmi_capabilities/dataobject/",

   "completionStatus" : "Complete",

   "mimetype" : "text/plain",

   "metadata" : {

       "cdmi_size" : "17",

       "cdmi_acl" : [

           {

               "acetype" : "0x00",

               "identifier" : "EVERYONE@",

               "aceflags" : "0x00",

               "acemask" : "0x00020089"

            }

        ]

   },

   "valuerange" : "0-16",

    "value" : "Hello CDMI World!"

}

16.2   Support for User Metadata

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".

16.3   Support for Storage System Metadata

After an object has been created, the storage system metadata, as described in Table 116, 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.

Table 116 - Storage System Metadata

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 base 16 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

16.4   Support for Data System Metadata

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 117) 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.

Table 117 - Data System Metadata

Metadata Name

Type

Description

Requirement

cdmi_data_redundancy

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting a desired number of complete copies. Additional copies may be made to satisfy demand for the value. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

cdmi_immediate_redundancy

JSON String

If this data system metadata item is present and set to "true", it indicates that the client is requesting that at least the number of copies indicated in cdmi_data_redundancy  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. When this data system metadata item is absent, or is present and is not set to "true", this data system metadata item shall not be used.

If the requested number of copies cannot be created within the HTTP timeout period, the transaction shall complete, but the cdmi_immediate_redundancy_provided data system metadata shall be set to "false".  

Optional

cdmi_assignedsize

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is specifying the size in bytes that is desired to be reported for a container object exported via other protocols (see 9.1.1). The system is not required to reserve this space and may thin-provision the requested space. Thus, the requested value may be greater than the actual storage space consumed. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

This data system metadata item is only applied against container objects and is not inherited by child objects.

Optional

cdmi_infrastructure_redundancy

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting a desired number of independent storage infrastructures supporting the multiple copies of data. This metadata is used to convey that, of the copies specified in cdmi_data_redundancy, these copies shall be stored on this many separate infrastructures. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

cdmi_data_dispersion

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting a minimum desired distance (in 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. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

cdmi_geographic_placement

JSON Array of JSON Strings

If this data system metadata item is present and set to zero or more geopolitical identifiers, it indicates that the client is requesting restrictions on the geographic regions where the object is permitted to be stored. Each geopolitical identifier shall be in the form of either a string containing a valid ISO 3166 country/country-subdivision code, which indicates that storage is permitted within that geopolitical region, or in the form of a string starting with the "!" character in front of a valid ISO 3166 country/country-subdivision code, which excludes that country/country-subdivision from the previous list of geopolitical regions.

The list is evaluated, in order, from left to right, with evaluation of each candidate storage location stopping when the candidate location is a permitted or prohibited region or is contained within a permitted or prohibited region. In addition to the ISO 3166 codes, "*" shall indicate all regions. If a candidate location does not match any of the entries in the list, the candidate location shall be considered to be prohibited.

   When this data system metadata item is absent, this data system metadata item shall not be used.

   When this data system metadata item is present and does not contain valid geopolitical identifiers, the create, update, or deserialize operation shall fail with an HTTP status code of 400 Bad Request.

   When this data system metadata item is present and valid, but no available storage locations are permitted, the create, update, or deserialize operation shall fail with an HTTP status code of 403 Forbidden.

Optional

cdmi_retention_id

JSON String

If this data system metadata item is present and not an empty string, it indicates that the client is requesting that the string be used to tag a given object as being managed by a specific retention policy. This data system metadata item 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. When this data system metadata item is absent, or is present and an empty string, this data system metadata item shall not be used.

Optional

cdmi_retention_period

JSON String

If this data system metadata item is present and contains a valid ISO 8601:2004 time interval (as described in 5.14), it indicates that the client is requesting that an object be placed under retention (see 17.3). When this data system metadata item is absent, this data system metadata item shall not be used. When this data system metadata item is present but does not contain a valid ISO 8601:2004 time interval, the create, update, or deserialize operation shall fail with an HTTP status code of 400 Bad Request.

If this data system metadata item is updated and the new end date is before the current end date, the update operation shall fail with an HTTP status code of 403 Forbidden.

Optional

cdmi_retention_autodelete

JSON String

If this data system metadata item is present and set to "true", it indicates that the client is requesting that an object under retention be automatically deleted when retention expires. When this data system metadata item is absent, or is present and is not set to "true", this data system metadata item shall not be used.

Optional

cdmi_hold_id

JSON Array of JSON Strings

If this data system metadata item is present and not an empty array, it indicates that the client is requesting that an object be placed under hold (see 17.4). Each string in the array shall contain a unique user-specified hold identifier.

When this data system metadata item is absent, or is present and is an empty JSON array, this data system metadata item shall not be used.

If this data system metadata item is updated, and a previously existing hold string has been removed or changed in the update, the update operation shall fail with an HTTP status code of 403 Forbidden. (See 17.4 concerning releasing holds.)

Optional

cdmi_encryption

JSON String

If this data system metadata item is present and not an empty string, it indicates that the client is requesting that the object be encrypted while at rest. If encrypted, all data and metadata related to the object shall be encrypted. Supported algorithm/mode/length values are provided by the cdmi_encryption capability.

When this data system metadata item is absent, this data system metadata item shall not be used.

If this data system metadata item is present but does not contain a valid encryption algorithm/mode/length string, the system is free to choose to ignore the data system metadata, to fail with an HTTP status code of 400 Bad Request, or to select an encryption algorithm/mode/length of the system's choice.

Supported encryption algorithms are expressed as a string in the form of ALGORITHM_MODE_KEYLENGTH, where:

   "ALGORITHM" is the encryption algorithm (e.g., "AES" or "3DES").

   "MODE" is the mode of operation (e.g., "XTS", "CBC", or "CTR").

   "KEYLENGTH" is the key size in bytes (e.g., "128", "192", "256").

To improve interoperability between CDMI implementations, the following designators should be used for the more common encryption combinations:

   "3DES_ECB_168" for the three-key TripleDES algorithm, the Electronic Code Book (ECB) mode of operation, and a key size of 168 bits;

   "3DES_CBC_168" for the three-key TripleDES algorithm, the Cipher Block Chaining (CBC) mode of operation, and a key size of 168 bits;

   "AES_CBC_128" for the AES algorithm, the CBC mode of operation, and a key size of 128 bits;

   "AES_CBC_256" for the AES algorithm, the CBC mode of operation, and a key size of 256 bits;

   "AES_XTS_128" for the AES algorithm, the XTS mode of operation, and a key size of 128 bits; and

   "AES_XTS_256" for the AES algorithm, the XTS mode of operation, and a key size of 256 bits.

Optional

cdmi_value_hash

JSON String

If this data system metadata item is present and not an empty string, it indicates that the client is requesting that the system hash the object value using the hashing algorithm and length requested. The result of the hash shall be provided in the cdmi_hash storage system metadata item. Supported algorithm/length values are provided by the cdmi_value_hash capability.

When this data system metadata item is absent, this data system metadata item shall not be used.

If this data system metadata item is present but does not contain a valid hash algorithm/length string, the system is free to choose to ignore the data system metadata, to fail with an HTTP status code of 400 Bad Request, or to select a hash algorithm/length of the system's choice.

Supported hash algorithms are expressed as a string in the form of ALGORITHM LENGTH, where:

   "ALGORITHM" is the hash algorithm (e.g., "SHA").

   "LENGTH" is the hash size in bytes (e.g., "160", "256").

To improve interoperability between CDMI implementations, the following designators should be used for the more common encryption combinations:

   "SHA160" for SHA-1, and

   "SHA256" for SHA-2.

Optional

cdmi_latency

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting a desired maximum time to first byte, in milliseconds. This metadata is the desired latency (in milliseconds) to the first byte of data, 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 data may be served. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

cdmi_throughput

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting a desired maximum data rate on retrieve, in bytes per second. This metadata is the desired bandwidth to the 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 data in locations where there is sufficient bandwidth to accommodate a maximum usage. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

cdmi_sanitization_method

JSON String

If this data system metadata item is present and not an empty string, it indicates that the client is requesting that the system use a specific sanitization method to delete data such that the data is unrecoverable after an update or delete operation. Supported sanitization method values are provided by the cdmi_sanitization_method capability.

When this data system metadata item is absent, this data system metadata item shall not be used.

If this data system metadata item is present but does not contain a valid sanitization method string, the system is free to choose to ignore the data system metadata, to fail with an HTTP status code of 400 Bad Request, or to select a sanitization method of the system's choice.

Supported sanitization methods are defined as system-specific strings.

Optional

cdmi_RPO

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting a largest acceptable duration in time between an update or create and when the object may be recovered, specified in seconds. This metadata is used to indicate the desired backup frequency from the primary copy or copies of the data to the secondary copy or copies. It is the maximum acceptable time period before a failure or disaster during which changes to data may be lost as a consequence of recovery. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

cdmi_RTO

JSON String

If this data system metadata item is present and set to a positive numeric string, it indicates that the client is requesting 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 or copies of the data from a secondary backup copy or copies. When this data system metadata item is absent, or is present and is not set to a positive numeric string, this data system metadata item shall not be used.

Optional

16.5   Support for Provided Data System Metadata

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 118.

Table 118 - Provided Values of Data Systems Metadata Items

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

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 117 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