From a64fb34c5b39427a06f8839a82ef3dd6c16b1a45 Mon Sep 17 00:00:00 2001 From: rugk Date: Mon, 12 Dec 2016 15:34:01 +0100 Subject: [PATCH] improve documentation, fixes https://github.com/PrivateBin/PrivateBin/issues/141 --- API.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/API.md b/API.md index a0123c6..5629157 100644 --- a/API.md +++ b/API.md @@ -39,3 +39,21 @@ Error on any of the above | N/A | N/A | N/A | `{"status":1, "message": * **formatID:** format key as defined in the [configuration file](https://github.com/PrivateBin/PrivateBin/blob/master/cfg/conf.ini#L69) of the service * **metadata:** various properties of the [paste](https://raw.githubusercontent.com/PrivateBin/PrivateBin/master/js/pastemeta.jsonld) or the [comment](https://raw.githubusercontent.com/PrivateBin/PrivateBin/master/js/commentmeta.jsonld). * **deletetoken:** the delete token is returned only on creation of a paste and can be used to delete it and its comments + +## Encryption + +PrivateBin [uses](https://github.com/PrivateBin/PrivateBin/blob/master/lib/Sjcl.php) the [SJCL library](https://github.com/bitwiseshiftleft/sjcl) for de- and encryption. If you do not want to use it, you can find all properties for the JSON encryption result it below. +The validation logic can be found [in the Sjcl.php file](https://github.com/PrivateBin/PrivateBin/blob/master/lib/Sjcl.php#L31-L102) and some examples for valid requests can be found in the [unit tests](https://github.com/PrivateBin/PrivateBin/blob/master/tst/SjclTest.php) + +## JSON object properties + +* **iv**: random initialization vector, encoded as base64 string +* **v**: version number of the SJCL data format, currently always 1 +* **iter**: number of iterations, by default 1000 +* **ks**: key size in bits, should ideally be 256, but SJCL also supports 128 bit keys +* **ts**: authentication strength in bits, should ideally be 128, but SJCL also supports 64 +* **mode**: encryption mode, we just switched to gcm by default, but before v1.0 it was ccm +* **adata**: optional clear text authentication data (of which we currently make no use) +* **cipher**: cipher algorithm, only aes is supported by SJCL for symmetric encryption +* **salt**: the salt, encoded as base64 string +* **ct**: cipher text, encoded as base64 string \ No newline at end of file