Creating files and folders

• Obtain a cryptographic key from the Covata Platform’s Access Service, which is required for encrypting or decrypting a file/Secure Object’s data,
• Initialize a new ‘Incomplete’ file object within an organization by associating the cryptographic key with this new file,
• Create a completed file object by encrypting its data locally, either for:
  • Remote storage uploaded to and handled by the Covata Platform’s Content Service, or
  • Storage handled independently by your application,
• Create a completed file object by uploading its unencrypted data to the Content Service for encryption, then storage and
• Create a folder for managing (groups of) files.

​

Definitions

​

Secure Object

• downloading the Secure Object’s content from storage (either in its encrypted or unencrypted form) from the 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).

​

Collection

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

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

​

Item

​

Organization

• be a member of one or more organizations and also
• share their content with users in other organizations.

​

Obtaining a cryptographic key

• <access-service>/api/v1/keys

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

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

{
    "keys": [{
        "id": "728882421139116032",
        "keyValue": "o6rwD3MQ4Saq1g1PnSGB6jarZGa26yLW4IRd38EGnVM=",
        "initializationVector": "E2wWB9FuvOXsimgLULDZfA==",
        "cryptographicAlgorithm": "AES",
        "keyLength": 256,
        "createdAt": "2016-07-04T07:58:31.180Z",
        "modifiedAt": "2016-07-04T07:58:31.180Z"
    }]
}

• Initializing a new ‘Incomplete’ file, which allows you to encrypt the file object’s data (thereby changing its state to Created) in a separate/subsequent request.
• Creating a completed Secure Object (data encrypted locally), which initializes and completes the file object (by associating the file object with its locally encrypted data) in a single request.

​

Initializing a new ‘Incomplete’ file

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

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

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.

• The AES algorithm (in CBC mode) with PKCS #7 padding (see <access-service>/api/v1/keys for more information), as well as
• Both the cryptographic key and initialization vector (returned by calling the <access-service>/api/v1/keys API endpoint) for this Secure Object.

• 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/organisations/{orgGroupId}/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,

• Uploading a completed Secure Object’s encrypted data
• Creating a collection for managing Secure Objects

​

Uploading a completed Secure Object’s encrypted data

• Creating a collection for managing Secure Objects

​

Creating a completed Secure Object (uploading unencrypted data)

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.

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:
   • is returned in the response to the last upload request (see Returns from a POST request of <content-service>/api/v1/objects/{objectId}/contents) and
   • completes the Secure Object (changing its state from Incomplete to Created).

• Creating a collection for managing Secure Objects

​

Creating a collection for managing Secure Objects

• 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 information about items from the Covata Platform.