Documentation
Overview
API Reference
Getting Started
Installation
Configuration Options

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

Contact/Impressum · Privacy Policy · Data Policy