Concepts Specifications API Downloads
SpecificationsHTTP/REST Store

HTTP/REST Store mature

A Condensation HTTP store exposes 5 HTTP/REST calls: three for storing and retrieving objects, and two for modifying and listing boxes.

Retrieving an object

Request
GET /objects/HASH
[Range: range-specifier]
Response
200 OK
Content-Type: application/condensation-object

The object's content.

Returns the object identified by HASH (64 hexadecimal digits). If the object exists, the server replies with status code 200 OK, and sends the object's content. Otherwise, a 404 Not Found status code is returned.

Submitting an object

Request
PUT /objects/HASH
Condensation-Date: DATE
Condensation-Actor: PUBLIC KEY HASH
Condensation-Signature: SIGN(PRIVATE KEY, SHA256(DATE|"\0"|METHOD|"\0"|HOST|PATH))
Content-Type: application/condensation-object

The object's content.
Response
204 No Content

Stores a new object. Upon success, the server replies with 204 No Content. Note that the operation is also successful if the object exists already.

If the indicated HASH does not correspond to the SHA-256 sum of the received content, the server discards the object and returns status code 400 Bad Request.

If the signature is wrong, or the date too old, the server responds with 403 Forbidden. Condensation servers only accept objects from users that have an account. Note that the signature protects the storage provider, not the user, who's data is protected through end-to-end encryption.

Booking an object

Request
POST /objects/HASH
Condensation-Date: DATE
Condensation-Actor: PUBLIC KEY HASH
Condensation-Signature: SIGN(PRIVATE KEY, SHA256(DATE|"\0"|METHOD|"\0"|HOST|PATH))
Response
204 No Content

Books an existing object. The server replies with 204 No Content upon success, or 404 Not Found if the object does not exist.

Signatures are validated as for object submission.

Listing a box

Request
GET /accounts/ACCOUNT/BOX
Response
200 OK
Content-Type: application/condensation-box
Last-Modified: DATE

HASH HASH HASH ...

Returns the set of hashes currently held in BOX. Each hash is 32 bytes long. The set is not ordered, and may contain duplicates.

Note that everybody can read boxes, not just the owner.

Modifying boxes

Request
POST /accounts
Condensation-Date: DATE
Condensation-Actor: PUBLIC KEY HASH
Condensation-Signature: SIGN(PRIVATE KEY, SHA256(DATE|"\0"|METHOD|"\0"|HOST|PATH|"\0"|CONTENT))
Content-Type: application/condensation-box-modifications

MODIFICATIONS RECORD
Response
204 No Content

Adds and removes object hashes and messages. The payload is a record with the following structure:

envelopes
  ENVELOPE HASH*
    ENVELOPE OBJECT BYTES
add
  ACCOUNT HASH*
    BOX LABEL*
      HASH*
remove
  ACCOUNT HASH*
    BOX LABEL*
      HASH*

Records marked with a star (*) can be repeated as many times as necessary. Empty sections may be skipped. Hashes are stored as 32 bytes (not as hashes).

The operation is executed in four steps, following the account modification procedure:

  1. The server verifies signature and date of the request, and responds with 403 Forbidden if the request is not valid.
  2. The server first attempts to add hashes. If the envelope is submitted, it is put onto the store. Otherwise, the existing envelope is booked. Additions may be processed in any order. If an addition fails, the server stops processing, and responds with an error.
  3. The server then attempts to remove hashes, ignoring all errors.
  4. The server responds with 204 No Content.

The error code returned should reflect the reason of failure. The server may respond with 500 Internal Server Error if the failure is related to the underlying storage system or its configuration, 403 Forbidden if the user is not allowed to modify the indicated box, or 400 Bad Request if the record cannot be parsed.

On the private and public boxes, only the account owner is allowed to add and remove hashes. On the in-queue box, anybody is allowed to add envelopes, and the signature is optional. Only the account owner or the message sender is allowed to remove hashes from an in-queue.

Boxes

A server must support the following boxes:

It may support other boxes as well.

Other URIs

For any URI not specified above, the server should return 404 Not Found. This also applies to URIs with incomplete hashes, or unsupported boxes.

Signatures mature

The user signs object PUT and box POST request to authenticate himself/herself with the server. This protects the storage service provider (server) – who may want to charge for the service – from unauthorized access. As part of signing up with the service provider, the user submits his public key(s).

It is important to understand that request signatures do not protect the user's data in any way. Their data is protected through end-to-end encryption and end-to-end signatures, and does not need any additional protection.

Object PUT signature

The signature for submitting an object is calculated as follows:

Condensation-Date 0 Method 0 Host header PUT Hash to signSHA-256 of  2013-12-11T16:04:22.000Z condensation.iolocalhost:8080 /objects/7df84cd2f426a2c34d50deaa6cc1a7b17f2085350a3aaebcecbb11a2987b62cd Key Private key of Condensation-Actor Byte 0 Condensation-Signature RSA/PSS signature of Hash to sign using Key Absolute path

and added to the HTTP header as shown in the following example:

PUT /objects/7df84cd2f426a2c34d50deaa6cc1a7b17f2085350a3aaebcecbb11a2987b62cd HTTP/1.1
Host: condensation.io
Condensation-Date: 2013-12-11T16:04:22.000Z
Condensation-Actor: f056974f4efd71246917314c1cb878c1af3e81057df5692b992f2a9cec8f3828
Condensation-Signature: 80810b874799341789fcf033935e2d6272c284581ca9b47228260bc4ccaada77465dadd44a0d2e4fed58fb2fdc26ffaa21f9bca01882d7f937f80271d7d4401ef24e554e2e15474cc928b6ddcd80d6d2a3f163f90e1d38f9452276e62e74b1c249bd76d11827e59cc9270e29dff595d4fd2344d66ed903aed0a56da98d7252295e1d031be861d8ae8a7106cb446fe0fafbb74576625bdf1c1cf23232c0050827bf7fdf7c202a4f8764b643a995c4e7744cdddcef5b5e5f90344872236f7333086c3cd71a8ea7aef05339ce32eb32057590797550a41c816113a75c190b82812b7224874d03f720bc2139843627161bf02d7f579620edf5bac29d1be1a6aa67b9
...

Object POST signature

The signature for booking an object is calculated in the same way, except that the method is POST instead of PUT.

Account POST signature

The signature for posting on an account is calculated as follows:

Condensation-Date 0 0 POST Hash to signSHA-256 of Host header Absolute path condensation.iolocalhost:8080 /accounts Key Private key of Condensation-Actor Byte 0 Condensation-Signature RSA/PSS signature of Hash to sign using Key 0 Post data Method  2013-12-11T16:04:22.000Z ...

and added to the HTTP header as shown in the following example:

POST /accounts HTTP/1.1
Host: condensation.io
Condensation-Date: 2013-12-11T16:04:22.000Z
Condensation-Actor: f056974f4efd71246917314c1cb878c1af3e81057df5692b992f2a9cec8f3828
Condensation-Signature: d626ea5f0af9560e9f5113fa724c6fab65b5235d178824a19ef246b13a5d165bbf390ffa3fc0efb182a390422a980e36f17a377624d07e402cdc428a5c641a15b9b68a23f2dec1a34859572db1b83388a37f12c5956fe03bc7f2e95b9bef33dd40c158b7c91469dc9c7f17c07a148d5415e70d5f895beb4a2b8936c4acc4753e09c9f8d7d644cc194556e6ea91d66ed9b6b665236cd15ed0a75484b7324a63013759a6a1383f81edb9206bbe45e2c55dd9093bfbf02111a582f773ce9ed84a7861d7d9efd0bf236d003571d1c967dcb6c37d67850e106a7fb5a425b2692058e934ed9ab91e7d21ec2145383ea4c0f11e5fc3a970ab7a0dd8643fc7b66fddd15e
...

Dates mature

Besides verifying the signature, servers should also check the date. Requests with a date that is more than a few minutes off should be rejected. Clock-less servers should reject dates older than when they were deployed.

The date is indicated using the Condensation-Date header, since some clients (e.g. JavaScript within the web browser) do not have access to the standard Date header field. Clients may of course send the Date header, too.

The date is written in the ISO 8601 format YYYY-MM-DDTmm:hh:ss.sssZ.

HTTP or HTTPS?

Since all content is end-to-end encrypted, using HTTPS does not substantially improve security and privacy:

HTTP HTTPS
Exposed data No No
Exposed object hashes On network and storage On storage only
Exposed access pattern Yes Yes
Connection setup overhead small big
Encryption overhead small bigger

Unless the Condensation store is completely under your control, it is recommended to stick to plain HTTP, as HTTPS offers only little additional security, but a substantial overhead.