Introduction

Some complex actions of the DRACOON API require more than one REST call to fulfill sucessfully. We call those multi-step activites "workflows" and this document presents the most relevant of them to help you implement your own DRACOON integration.

Login workflow

Overview

This workflow is used to log on an existing user. After successful login, the client should request GET /user/account to check whether it is the user's first login. In that case, the following attributes might be set to true:

• needsToAcceptEULA: The user needs to accept the EULA immediately. This needs to be done first. 
• needsToChangePassword: The user is required to change the password. Password policies apply. 
• needsToChangeUserName: The user is required to change the user name (login). Only valid email addresses are accepted.

If at least one of these attributes is set to true, trying to use other APIs than GET /user/account, PUT /user/account, PUT /user/account/password or GET /config/settings (details in the next section) will result in an error.

The forced updates to accept the EULA and to update the username may be done in one request to PUT /user/account. At the same time, independently, a request to PUT /user/account/password may be sent before receiving the response of the first one. The only existing constraint is, that the username may not be updated without accepting the EULA.

Special case: GET /config/settings

A request to GET /config/settings is possible, however, if needsToAcceptEULA is set to true, the returned values are reduced to

• allow_system_global_weak_password and
• eula_active.

The latter one should be set to true in this case and the first one provides information for the client on the required password complexity.

Endpoint details

GET /auth/ressources

This interface provides log-on information about the environment like available languages and authentication methods (e.g. login with user name/password a.k.a "sql", ActiveDirectory, etc.). Knowledge about the available authentication methods is required to invoke the login.

POST /auth/login

A request to this endpoints logs an existing user onto DRACOON. It is necessary to provide a valid combination of user name and password as well as select one available authentication method.

GET /user/account

Retrieve all information about the current user's account. Next to basic user information (first name, last name, etc.), important information about required changes of password or user name are included as well as the whether accepting the EULA is required.

PUT /user/account

This API may be used to update the current user's account. It is used to update the user name, change first or last name, accept the EULA, etc.

PUT /user/account/password

This endpoint is only used to update the user's password. Sending the old password, however, is required.

Download workflow

Overview

Any file download for authorized users is realized with this workflow. After downloading the file, the necessary keys for decryption have to be downloaded. For more details on crypto mechanisms, please refer to TODO.

 

Endpoint details

GET /nodes/files/{file_id}

This endpoint provides meta data about the selected file.

 

POST /nodes/files/{file_id}/downloads

This request provides the URL where this file can be downloaded. This URL either points to the DRACOON API with a download token that ensures authentication and authorization or (if S3 storage is enabled) points directly to the storage interface and provides a pre-signed URL for direct download.

GET {url}

Download the file from the previously provided download URL. If a Range is requested, only that byte range is provided; otherwise the whole file is transmitted in the response. For more details on the Range header, please cf. RFC7233.

GET /nodes/files/{file_id}/user_file_key

After completing the download the decryption key for the file (a.k.a UserFileKey) that is encrypted with the current user's public key, has to be fetched.

GET /user/account/keypair

This API returns the user's keypair that consists of the public and the private key. The private key is required to decrypt the user's file key.

 

Upload workflow

Overview

This workflow is used to upload a file to a container (data room or folder). We implemented the widely used upload in three steps:

1. Provide some meta data and create an upload channel.
2. Upload the file. Chunked upload can be used optionally.
3. Finish the upload an close the upload channel.

However, for the encryption of the uploaded file(s), an additional API call to GET /user/account/keypair and some client-side crypto is necessary.

If an upload should be canceled at any time after step 1, a DELETE request should be sent to invoke the cleanup of partial uploads.

 

Please note: After completing an upload to an encrypted data room, the Key Distribution Workflow should be invoked.

Endpoint details

POST /nodes/files/uploads

A new upload channel is created with this interface. You have to provide several meta information about the uploaded file in advance. Very important is also the attribute parentId that points to the parent container in which the file should be stored. If you do not have that ID yet, you might need to call GET /nodes to retrieve the directory tree and identify the desired parent. We strongly suggest that you set the size attribute correctly to the file size you want to upload (if possible) so the API can immediately inform about any quota limitations that will prevent a successful upload.

The response contains the UploadToken that is used to upload the file. Future implementations will provide an upload URL similar to the already provided download URL.

POST /uploads/{token}

Use this API to transfer the actual payload of the file to be uploaded. However, it is necessary to encrypt the file on client-side with AES-GCM/256 with a random 256-bit key ("FileKey") before uploading it (or its chunks).

Please be aware that the content is multipart as you transmit file data.

These endpoints support chunked uploads, which means that you may send only parts of the file in several invocations. For transmitting partial files, use the Content-Range header that works as specified in RFC7233. You can transmit any desired number of chunks. Each chunk is confirmed in the response with the current total size transmitted and the md5 hash value of the chunk. If you identify any transmission errors, please simply retransmit the chunk with the same Content-Range header again.

GET /user/account/keypair

Use this endpoint to retrieve the current user's key pair that is secured with PKCS#8 and the so-called decryption password. Use the public key locally and encrypt the FileKey (the symmetric key the file was encrypted with) as you have to provide it in the next request.

PUT /nodes/files/uploads/{upload_id} and PUT /uploads/{token}

Once you completed uploading your file, you need to close the upload channel and commit your data.

The fileName is finally set with this call. However, the transmitted resolutionStrategy determines what happens in case of naming conflict:

• autorename (default behavior): The new file is renamed (appending numbers) until a name without collision is found.
• overwrite: The new file overwrites the old one. The old file is moved into the recycle bin and any existing Download Shares are removed (if not explicitly stated otherwise).
• fail: The operation fails in case of a collision and an error is returned. However the channel and the previously uploaded file data remains online and a new PUT request with another fileName or another resolutionStrategy may be sent to complete the upload operation.

If the file was encrypted, you have to provide the UserFileKey for the current user:

• key contains the client-side asymmetrical encrypted FileKey for the current user.
• IV is the initial vector for AES-GCM.
• version is the key version (Should usually be A). Please refer to the Crypto Documentation for more information.
• tag is the AES-GCM authentication tag.

Please be adviced you should invoke the Key Distribution Workflow after finishing the upload to an encrypted data room to make the new file available to other users.

Please note that a clean-up process is always active and unfinished upload channels are removed regularly.

DELETE /uploads/{token}

If an upload should be canceled at any time after creation of the upload channel (successful invocation of POST /nodes/files/uploads), clients are strongly recommended to DELETE the already created channel to support the clean-up process.

Key distribution workflow

Overview

When using a data room with client-side encryption of files, no keys are stored on DRACOON in plain. So if new users should be able to access the encrypted files, other users have to provide them with their copies of the File Keys (for details please refer to the Crypto Documentation). This workflow is used to generate those keys.

All clients should (if possible considering performance, power or bandwith limitations) regularly initiate this workflow to ensure a constant distribution of keys to all other authorized users.

 

 

Endpoint details

GET /nodes/missingFileKeys

This API provides the user with a list of files and users that copies of the corresponding FileKeys could be generated for. Two pre-conditions apply:

1. The user is able to access the relevant file (i.e. he or she has access to a copy of the FileKey that is encrypted with his or her public key ("UserFileKey")).
2. There are other users available who have been granted access rights on the file(s) but no copy of the FileKey (UserFileKey) has been provided for them yet.

Depending on the client's limitations, the API should be called with a limit parameter to reduce load on both sides.

As an optimization, the response contains a list of tuples consisting of user IDs and file IDs that represent a relation for which file keys should be created. In addition, lists of related users' public keys and the corresponding UserFileKeys for the current user are provided so no other call to retrieve public keys or file keys is necessary.

 GET /user/account/keypair

If there are some FileKeys to be generated, the user's private key is required to decrypt the UserFileKeys.

 POST /nodes/files/keys

After a bunch of FileKeys for different users have been created, the keys can be batch uploaded with this API. Please cf. the Crypto Documentation for more details about cryptographic operations.

Password reset

Overview

Whenever a user forgets his/her password for basic authentication (authMethod SQL) and needs to reset it, this workflow is required.

Endpoint details

POST /auth/reset_password

A request to this API triggers an email with reset instructions and a reset token for a user who forgot his/her password. The language can be used to localize the email text.

GET /auth/reset_password/{token}

After receiving an email with an URL (containing the reset token), some relevant additional information can be requested like the required password complexity.

PUT /auth/reset_password/{token}

A new password may be set using the token that was received by email.