API Documentation
Creating Secure Objects and collections

This page describes how to use Covata's API to:

Notes:

  • Before creating either a Secure Object or a collection (collectively called an item), your application must have a valid access token obtained by authenticating and authorizing a Covata user to the Covata Platform, where this user has the appropriate role and/or permissions to create either:
    • their own items or
    • items within another Covata user's collection.
    For more information about authenticating and authorizing Covata users to the Covata Platform, see Authorizing your application on the Authentication and authorization page of this guide and the Configuring client applications page of the Covata Platform Administrator's Guide.
  • The Supported roles (and permissions) sections of each API endpoint page (linked to from the procedures below) contain details about the roles and permissions that a Covata user requires for a successful request to the endpoint (along with a valid access token representing this user).

Definitions

Secure Object

A Secure Object (in its Created or 'completed' state) represents a file's data which has been encrypted (according to Covata's encryption requirements), along with the encrypted file's associated attributes/metadata (which are recorded by the Covata Platform's Access Service).

A Secure Object's content is only handled either by the Covata Platform's Content Service or externally by your application. A Secure Object's content is not handled by the Covata Platform's Access Service. However, a Secure Object's associated attributes/metadata can be retrieved from the Access Service, which in turn can assist in:

  • downloading the Secure Object's content from storage (either in its encrypted or unencrypted form) from the Covata Platform's Content Service,
  • obtaining the necessary key required to decrypt a Secure Object's content, which has been encrypted, handled and/or stored externally (e.g. by your application).

Tip: Conceptually and in Covata's Safe Share applications, Secure Objects represent files.

Notes:

  • A Secure Object in an Incomplete state is one that has been initialized (and associated with a key), although is not yet associated with any encrypted data (which would change the Secure Object's state to Created).
  • When using Covata Safe Share applications, an incomplete Secure Object could also result from a failure in either encrypting the Secure Object's data or uploading its content to storage.
  • In Covata Administration, a Secure Object's current state can be seen through the Files page. For more information, see the Covata Platform Administrator's Guide.

Collection

A collection:

  • Represents a container for organizing one or more Secure Objects and/or other collections.
  • Like a Secure Object, also has its own associated attributes/metadata.

Collections are:

  • Analogous to an operating system's folders/directories on a file system and
  • Used for logically organizing Secure Objects and other collections. The Covata Platform's Content Service uses collections for this purpose.

Tip: In Covata's Safe Share applications, collections represent folders.

Item

An item (in the context of Secure Objects and collections) is a generic term that refers to either a Secure Object or a collection.

Every item, regardless of whether it is a Secure Object or a collection has a unique identifier (or ID).

Obtaining a cryptographic key

A cryptographic key is required to encrypt data into a complete Secure Object.

To obtain a cryptographic key from the Covata Platform's Access Service (which is the first step before creating a new Secure Object), make a POST request to the <access-service>/api/v1/keys API endpoint with a JSON object in the body of the request that either:

  • contains the optional keyLength parameter (as a name/value pair) which determines the bit length of the cryptographic key to be returned from the Covata Platform. Specify a value of 128, 192 or 256.
    OR
  • is empty. Specifying an empty JSON object implicitly sets the keyLength parameter's value to 256.

Example request: Initiating a request to obtain a cryptographic key:

curl https://access-service.xy-company.com/api/v1/keys \
-H 'Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6' \
-H 'Content-Type: application/json' \
-d '{}' \
-X POST

Note: As indicated in this example, the access token obtained when you authorized your application must be included in the header of this request (as the bearer token) for the request to succeed.

If your request (above) was sent successfully, the Covata Platform responds by sending back a JSON object containing the key's ID value (required to associate a cryptographic key with a Secure Object), other information about the key's characteristics and a date and time stamp of when the key was created.

Example response: Response from the Covata Platform upon successfully processing a client application's request for a cryptographic key:

{
"keys": [
{
"id": "123456789012345678",
"keyValue": "2VCZkPeYPhvL4VkzrEqIVGaW2AGmRM1uwuXiPRbe8NU=",
"initializationVector": "fpEIYIk+dnMw7rgFA+Bz8g==",
"cryptographicAlgorithm": "AES",
"keyLength": 256,
"createdAt": "2014-09-24T06:08:40.416Z",
"modifiedAt": "2014-09-24T06:08:40.416Z"
}
]
}

Next step: Now that you have a cryptographic key, you can begin the process of creating a new Secure Object. This involves either:

Initializing a new 'Incomplete' Secure Object

Initializing a new Secure Object (whose state is Incomplete):

  • associates the cryptographic key with a new Secure Object, which results in an incomplete Secure Object and
  • is a requirement for (and often the first step in) creating the Secure Object itself.

To do this, make a POST request to the <access-service>/api/v1/objects API endpoint with a JSON object in the body of the request that contains the keyId parameter (as a name/value pair) whose value is the ID of the key (obtained above).

The ID of the incomplete Secure Object is returned in the response to this request.

Tip: Your application may wish to temporarily store this ID value as it is used for completing a Secure Object, either by locally encrypting its data and then uploading it for storage, or by uploading its unencrypted data for encryption and storage.

Next step: Now that you have initialized your Secure Object, you can begin encrypting its data. Depending on your application's requirements, this involves either:

  • Creating a completed Secure Object (data encrypted locally), whose encrypted data can then be either uploaded to remote storage (via the Covata Platform's Content Service) or handled independently by your application.
  • Creating a completed Secure Object (uploading unencrypted data), whose unencrypted data can then be uploaded for encryption by the Content Service, which in turn transfers the encrypted data to remote storage.
    Choosing which of these approaches is right for you
    The connection between a client's machine (that stores locally unencrypted data) and the Covata Platform's Content Service (which can encrypt this data) is secured using HTTPS.
    However, if you do not wish a Secure Object's locally stored data to be sent from the client's machine over any type of connection in its unencrypted form, your application can encrypt this data on the client machine first and then upload the encrypted data to remote storage via the Content Service, or store it elsewhere.
    Alternative solutions for storing a Secure Object's encrypted data to that provided by the Covata Platform's Content Service are beyond the scope of this documentation.

Creating a completed Secure Object (data encrypted locally)

Creating a completed Secure Object from locally-encrypted data involves the following steps:

  1. Ensuring you obtained a cryptographic key for the Secure Object (and optionally, initialized the Secure Object with this cryptographic key).
  2. Using this cryptographic key to encrypt the Secure Object's data locally and obtaining the SHA-512 value of this encrypted data.
  3. Associating this encrypted data with the Secure Object by assigning this SHA-512 value to the Secure Object. This step 'completes' the Secure Object, which changes its state from Incomplete to Created.
    Note: If the Secure Object was not initialized earlier, it can be both initialized and completed during this step.

Requirements for encrypting data locally

When encrypting your data using the cryptographic key (obtained above), then ensure that this data is encrypted using:

If you do not follow these requirements, then either your attempt to upload your encrypted data may fail or if successful, any attempt to download the Secure Object's data in its decrypted form will result in the retrieval of garbled data.

Completing the Secure Object

To complete a Secure Object (whose state is Created) from its locally encrypted data, make either a:

  • PUT request to the <access-service>/api/v1/objects/{objectId} endpoint with:
    • the ID of the incomplete Secure Object (obtained in the response for initializing the Secure Object above) in this request's URL
      and
    • a JSON object in the body of this request that contains the sha512 parameter (name/value pair) whose value is the SHA-512 value of locally encrypted data.
    OR
  • POST request to the <access-service>/api/v1/objects API endpoint with a JSON object in the body of the request that contains:
    • the keyId parameter (as a name/value pair) whose value is the ID of the key (obtained above)
      and
    • the sha512 parameter (name/value pair) whose value is the SHA-512 of the locally encrypted data,

In both of these cases, a SHA-512 value must be associated with the Secure Object to set its state to Created.

Next step: Depending on your application's requirements, follow one of these procedures:

Uploading a completed Secure Object's encrypted data

Once a Secure Object's data has been encrypted locally (above) and the Secure Object's state has changed to Created, your application can send this encrypted data to remote storage via the Covata Platform's Content Service.

To upload a completed Secure Object's encrypted data to the Content Service, make a POST request to the <content-service>/api/v1/objects/{objectId}/contents API endpoint, along with the actual encrypted data to be uploaded.

When making this request, the value of the format URL parameter must be encrypted. See Required parameters on POST of <content-service>/api/v1/objects/{objectId}/contents for more information.

Note: If the data being uploaded is larger than the upload chunk size permitted by the Covata Platform (whose default value is 10 mebibytes), then the data must be uploaded in multiple requests to this endpoint. For more information, see Required parameters for multi-chunk uploads of <content-service>/api/v1/objects/{objectId}/contents.

Next step: Depending on your application's requirements, follow one of these procedures:

Creating a completed Secure Object (uploading unencrypted data)

Creating a completed Secure Object from unencrypted data stored locally involves the following steps:

  1. Ensuring you obtained a cryptographic key for the Secure Object and initialized the Secure Object with this cryptographic key.
  2. Uploading the Secure Object's unencrypted data to remote storage via the Content Service. This step 'completes' the Secure Object, which changes its state from Incomplete to Created.

To upload an incomplete Secure Object's unencrypted data to the Content Service, make a POST request to the <content-service>/api/v1/objects/{objectId}/contents API endpoint, along with the actual unencrypted data to be uploaded.

However, when making this request, the value of the format URL parameter must be plaintext. See Required parameters on POST of <content-service>/api/v1/objects/{objectId}/contents for more information.

Note: If the data being uploaded is larger than the upload chunk size permitted by the Covata Platform (whose default value is 10 mebibytes), then the data must be uploaded in multiple requests to this endpoint. For more information, see Required parameters for multi-chunk uploads of <content-service>/api/v1/objects/{objectId}/contents.

After completing all required requests to upload the unencrypted data, the Content Service automatically:

  1. Encrypts the data.
  2. Calculates the SHA-512 value of this encrypted data.
  3. Transfers the encrypted data to remote storage.
  4. Associates this SHA-512 value with the Secure Object, which:

Note: For a multi-chunk upload, steps 1 to 3 above are conducted for each chunk and after the last chunk has been uploaded, the final SHA-512 value (for the entire encrypted data) is calculated and associated with the Secure Object.

Next step: Depending on your application's requirements, follow one of these procedures:

Creating a collection for managing Secure Objects

Collections are used for logically organizing Secure Objects and other collections, which the Covata Platform's Content Service utilizes for organise files and folders for Covata users.

To create a collection, make a POST request to the <access-service>/api/v1/collections API endpoint with the name of the collection and the parentId value, both of which are parameters (each specified as name/value pairs) within a JSON object in the body of the request. The parentId value should be:

  • 0 to specify that the new collection will be created at the logical root level, or
  • the ID value of the collection that will become the parent of this new collection. For more information about retrieving an existing collection, see retrieving-an-existing-collection.

Tip: A new Secure Object can be created within an existing collection by specifying the parentId value when making the appropriate API endpoint call to either:

  • Initialize the Secure Object or
  • Complete the Secure Object by encrypting its data locally.

If a Secure Object's unencrypted data is to be uploaded to the Covata Platform's Content Service, specify the parentId value when initializing the Secure Object.