<access-service>/api/v1/keys

URL structure

https://access-service.xy-company.com/api/v1/keys

Supported methods and overview

• POST - generates a cryptographic key.

Detailed description

This API endpoint generates a cryptographic key, which in turn is required to encrypt the data of a file object.

A file object (i.e. Secure Object) is created through the <access-service>/api/v1/organisations/{orgGroupId}/objects endpoint.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

• Originator - when this user will be either creating their own file object or uploading a new version of a file (whose data is encrypted locally).
• Collaborator and Ad hoc - when this user will be either creating a file object or uploading a new version of a file (whose data is encrypted locally), within a folder on which the user has the Upload File permission.

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...
  where the Bearer token is the appropriate access token.
• Content-Type: application/json

Required body

If none of the Optional parameters below are specified, then an empty JSON object must be passed in the body of the request:

• {}

Optional parameters

The following optional parameters can be sent in the body of the POST request, each as individual members of a JSON object:

• keyLength - The bit length of the cryptographic key to be returned from the Cocoon Data Platform. This key is used to encrypt data using an Advanced Encryption Standard (AES) cryptographic algorithm whose mode of operation is CipherBlock Chaining (CBC). Valid values for this parameter are: 128, 192 or 256. If this parameter is not specified, a value of 256 is assumed.
  Example (request):

  {
    "keyLength": 128
  }

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.

For successful requests only, a JSON-formatted response is also returned, which contains a keys array that has the following elements:

• id - The ID value associated with the cryptographic key value returned below.
  Important: Retain this value as it is required during the initial stages of creating a file object or one of its versions - i.e. this key ID value is used:
  • to associate the cryptographic key with the new file object itself,
  • to associate the cryptographic key with a file object's version (if encrypting the file object's data locally), or,
  • if the key needs to be deleted as a result of too many failed attempts to associate cryptographic keys with file objects or their versions.
• keyValue - The cryptographic key value itself. The length of this key may differ depending on the keyLength value submitted as part of the request's optional parameters above.
  Note: This value is returned for the purposes of local/client-side encryption (i.e. if your client application does not rely on the Cocoon Data Platform's server-side encryption). The keyValue value should be retained by your client application after associating this key with an initialized file object (see <access-service>/api/v1/organisations/{orgGroupId}/objects for more information), until you have performed local/client-side encryption.
• initializationVector - The initialization vector required to begin local/client-side encryption using the AES algorithm (in CBC mode).
  Note: Like keyValue above, this value is also returned for the purposes of local/client-side encryption. The initializationVector value should be retained after associating keyValue (above) with an initialized file object (see <access-service>/api/v1/organisations/{orgGroupId}/objects for more information), until you have performed local/client-side encryption.
• cryptographicAlgorithm - The cryptographic algorithm supported by the Cocoon Data Platform. This should be AES.
• keyLength - The bit length of the cryptographic key value returned above. This should be 256 or match the value of the keyLength submitted as part of the request's optional parameters above.
• createdAt - The date and time when the cryptographic key was created.

• modifiedAt - This value should match the createdAt value above.

  Example (response):

  {
      "keys": [{
          "id": "732857710936506368",
          "keyValue": "eAQ5SC/Txsva85kBzHVTM2LsT9WOgRA1y1lzYbzGrbQ=",
          "initializationVector": "0GlFPnFNErU18PUFGDIQ4Q==",
          "cryptographicAlgorithm": "AES",
          "keyLength": 256,
          "createdAt": "2016-07-15T07:14:54.125Z",
          "modifiedAt": "2016-07-15T07:14:54.125Z"
      }]
  }