12
API
rugk edited this page 2017-02-17 13:42:50 +01:00
Table of Contents
PrivateBin uses AJAX requests for certain operations.
As of Version 0.22
All JSON-API requests need to be sent with the HTTP header X-Requested-With: JSONHttpRequest. The query strings below would be appended after the ? in the URL, i.e. query string foo on the site URL of https://example.com/privatebin/ would become https://example.com/privatebin/?foo.
| Action | Type | Query String | Data to send | Result (JSON-LD) |
|---|---|---|---|---|
| retrieve paste (and its comments) | GET | [pasteID] |
(no data) | paste.jsonld |
| create paste | PUT | [pasteID] |
data=[cipherdata]& expire=[expireID]& formatter=[formatID]& burnafterreading=[1/0]& opendiscussion=[1/0] |
paste.jsonld (including deletetoken) |
| create paste | POST | (empty query string) | data=[cipherdata]& expire=[expireID]& formatter=[formatID]& burnafterreading=[1/0]& opendiscussion=[1/0] |
paste.jsonld (including deletetoken) |
| create comment | PUT | [commentID] |
data=[cipherdata]& parentid=[parentID]& pasteid=[pasteID]& nickname=[cipherdata] |
{"status":0, "id":"[commentID]"} |
| create comment | POST | (empty query string) | data=[cipherdata]& parentid=[parentID]& pasteid=[pasteID]& nickname=[cipherdata] |
{"status":0, "id":"[commentID]"} |
| delete paste (burn after reading) | DELETE | (empty query string) | pasteid=[pasteID]& deletetoken=burnafterreading |
{"status":0, "id":"[pasteID]"} |
| delete paste (burn after reading) | POST | (empty query string) | pasteid=[pasteID]& deletetoken=burnafterreading |
{"status":0, "id":"[pasteID]"} |
| delete paste | DELETE | (empty query string) | pasteid=[pasteID]& deletetoken=[deletetoken] |
{"status":0, "id":"[pasteID]"} |
| delete paste | POST | (empty query string) | pasteid=[pasteID]& deletetoken=[deletetoken] |
{"status":0, "id":"[pasteID]"} |
| Error on any of the above | N/A | N/A | N/A | {"status":1, "message":"[errormessage]"} |
Until Version 0.21.1
The query strings below would be appended after the ? in the URL, i.e. query string foo on the site URL of https://example.com/privatebin/ would become https://example.com/privatebin/?foo.
| Action | Type | Query String | Data to send (JSON) | Result (JSON) |
|---|---|---|---|---|
| retrieve paste (and its comments) | GET | [pasteID]&json |
(no data) | {"status":0, "id":"[pasteID]", "messages": [array of one paste and its comments if any]} |
| create paste | POST | (empty query string) | {"data":"[cipherdata]", "expire":"[expireID]", "burnafterreading":[1/0], "opendiscussion":[1/0]} |
{"status":0, "id":"[pasteID]", "deletetoken":[token]} |
| create comment | POST | (empty query string) | {"data":"[cipherdata]", "parentid":"[parentID]", "pasteid":[pasteID], "nickname":[cipherdata]} |
{"status":0, "id":"[pasteID]"} |
| delete paste (only for burn after reading pastes) | GET | pasteid=[pasteID]&deletetoken=burnafterreading |
(no data) | {"status":0, "id":"[pasteID]"} |
| Error on any of the above | N/A | N/A | N/A | {"status":1, "message":"[errormessage]"} |
Legend
- pasteID: ID of the paste, 16 characters long, hexadecimal
- parentID: ID of the comments parent (paste ID or comment ID), 16 characters long, hexadecimal
- commentID: ID of the comment, 16 characters long, hexadecimal
- cipherdata: JSON string containing format and base64 encoded data, output of the encryption function
- expireID: expiration key as defined in the configuration file of the service
- formatID: format key as defined in the configuration file of the service
- metadata: various properties of the paste or the comment.
- 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 the SJCL library 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 and some examples for valid requests can be found in the unit tests.
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
More information
…can be found on [this wiki page](Encryption format).