El RIDO edited this page Jul 29, 2018 · 13 revisions

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.