Documentation
Overview
API Reference
Getting Started
Installation
Configuration Options
Command Line Interface (CLI)

API Reference

GET
/api/v1/key/list/user
List all dabih users, more specifically users who have uploaded a public key to dabih.

Response:

{
  "users": [
    "<sub1>",
    "..."
  ],
  "unconfirmed": [
    "<sub2>",
    "..."
  ]
}
POST
/api/v1/key/add
Event:KEY_ADD
Upload a new public key to dabih. The key will start of a with a state of unconfirmed and needs to be unlocked by an admin. Keys are transfered using the JSON Web Key Format

Request Body:

{
  "name": "<new name>",
  "publicKey": "{public key in jwk format}"
}
POST
/api/v1/key/check

Request Body:

{
  "keyHash": "jg94g...."
}
keyHash is the sha-256 hash of the users public key

Response:

If the key is valid and confirmed the response will be
{
  "valid": true
}
else the response will be an error.
GET
/api/v1/dataset/list
List all datasets where you have a least read permission, including all their members.

Response:

[
  {
    "mnemonic": <dataset id>,
    "name": <dataset name>,
    "fileName": <name of the file in the dataset>,
    "hash": <sha-256 hash of all hashes of chunks>,
    "size": <total size in bytes>,
    "keyHash": <sha-256 hash of the AES key>,
    "permission": <your permission>
    "members": [{
      "sub": <user id>,
      "permission": <either 'read', 'write' or 'none'>,
    }, ...],
  }, ...
]
GET
/api/v1/dataset/:mnemonic
Get the information for the dataset mnemonic

Response:

{
    "mnemonic": <dataset id>,
    "name": <dataset name>,
    "fileName": <name of the file in the dataset>,
    "hash": <sha-256 hash of all hashes of chunks>,
    "size": <total size in bytes>,
    "keyHash": <sha-256 hash of the AES key>,
    "chunks": [{
      "id": <db id>,
      "hash": <sha-256 hash of the unencrypted data>,
      "iv": <AES initialization vector>,
      "crc": <CRC32 checksum of the encrypted data (hex)>,
      "start": <byte positon of the chunk start (inclusive)>,
      "end": <byte positon of the chunk end (non-inclusive)>,
    }, ...],
}
POST
/api/v1/dataset/:mnemonic/remove
Event:DATASET_REMOVE
Remove the dataset mnemonic The dataset can still be recovered by an admin.
POST
/api/v1/dataset/:mnemonic/member/add
Event:DATASET_MEMBER_ADD
Add a new members to the dataset mnemonic

You need to have write permission for the dataset for this call to succeed

Request Body:

{
  "key": "<decrypted AES key>",
  "members": [
    "<sub1>",
    "<sub2>",
    "..."
  ]
}
POST
/api/v1/dataset/:mnemonic/member/set
Event:DATASET_MEMBER_SET
Change the permission of a member of the dataset mnemonic

You need to have write permission for the dataset for this call to succeed

Request Body:

{
  "user": "<sub>",
  "permission": "<new permission read, write or none>"
}
POST
/api/v1/dataset/:mnemonic/reencrypt
Event:DATASET_REENCRYPT
Drop the existing AES encryption key for the dataset and reencrypt it with a newly generated key.

Request Body:

{
  "key": "<decrypted AES key>"
}
POST
/api/v1/dataset/:mnemonic/rename
Event:DATASET_RENAME
Set a new name for the dataset, it is not guaranteed to be unique but can be used for searching.

Request Body:

{
  "name": "<new name>"
}
POST
/api/v1/dataset/:mnemonic/key
Event:DATASET_KEY_FETCH

Request Body:

{
  "keyHash": "jg94g...."
}
keyHash is the sha-256 hash of the users public key

Response:

The response will contain the encrypted AES key.
POST
/api/v1/upload/start
Event:UPLOAD_START
Start the upload of a new dataset

Request Body:

{
  "name": "The name of the uploaded file"
}

Response:

The response contains the newly created dataset, the size and hash will be null because they can only be determined after the upload is complete.
{
    "mnemonic": <dataset id>,
    "name": <dataset name>,
    "fileName": <name of the file in the dataset>,
    "hash": null,
    "size": null,
    "keyHash": <sha-256 hash of the AES key>,
}
PUT
/api/v1/upload/:mnemonic
Add a new chunk to the dataset mnemonic

Request:

The request is special and needs to be of type multipart/form-data Only a single file is supported and should be part of the form data. We also require the HTTP headers Content-Range and Digest . Content-Range should indicate with bytes of the complete file the chunk contains. All chunks (except the last one should be 2MiB in size. Digest should be the sha256 hash of the chunk data.
POST
/api/v1/upload/finish/:mnemonic
Event:UPLOAD_FINISH
Finish the upload for the dataset mnemonic No request data is needed, but after this call the upload will be considered finished and the size and hash of the dataset mnemonic will be calculated.
GET
/api/v1/dataset/:mnemonic/chunk/:chunkHash
Download the encrypted data chunk with hash chunkHash for the dataset mnemonic
The list of chunks and their hashes can be obtained by calling /api/v1/dataset/:mnemonic

Response:

The chunk of the encrypted data as an application/octet-stream the client is resposible for decrypting the data

Admin API Reference

GET
/api/v1/admin/key/list
List all public keys for all users.

Response:

[{
    "id": <key id>
    "hash": <sha256 hash of the key data>
    "name": <key name>,
    "sub": <key owner>,
    "data": {
        "alg": "RSA-OAEP-256",
        "e": "AQAB",
        "ext": true,
        "key_ops": ["encrypt"],
        "kty": "RSA",
        "n": "<key data>"
    },
    "isRootKey": false,
    "confirmedBy": <admin user or null>,
    "confirmed": <date or null>,
}, ...
POST
/api/v1/admin/key/confirm
Event:KEY_CONFIRM
Set the confirmed flag for a public Key

Request Body:

{
    "keyId": <key id>,
    "confirmed": <true or false>,
}
POST
/api/v1/admin/key/remove
Event:KEY_REMOVE
Remove a public key.

Request Body:

{
    "keyId": <key id>,
}
GET
/api/v1/admin/dataset/list
List all datasets, including deleted ones.

Response:

[
  {
    "mnemonic": <dataset id>,
    "name": <dataset name>,
    "fileName": <name of the file in the dataset>,
    "hash": <sha-256 hash of all hashes of chunks>,
    "size": <total size in bytes>,
    "keyHash": <sha-256 hash of the AES key>,
    "deleted": <null or date>,
  }, ...
]
POST
/api/v1/admin/dataset/:mnemonic/remove
Event:DATASET_REMOVE
Remove the dataset mnemonic
POST
/api/v1/admin/dataset/:mnemonic/recover
Event:DATASET_RECOVER
Recover the dataset mnemonic after it has been deleted.
POST
/api/v1/admin/dataset/:mnemonic/destroy
Event:DATASET_DESTROY
Irreversibly delete the dataset mnemonic
GET
/api/v1/admin/events
List all dates that have events.

["2022-10-27", "2022-10-26", ...]
GET
/api/v1/admin/events/:date
List all events on the day date 
[{
"sub": <event user sub>,
"mnemonic": <dataset id>,
"event": <event type>,
"message": <event message>,
"day": <event day>,
"createdAt": <event timestamp>,
}, ...]

Institute of functional genomics-Statistical Bioinformatics

University of Regensburg

©2023 · Version 1.12.14

Contact/Impressum · Privacy Policy · Data Policy · Documentation