Key Service RESTfull API

Four operations are currently supported in both online and offline versions:

Online Encryption
  • Create Key: POST passphrase
  • Get Messages: GET token,passphrase
  • Send Message: PUT token, message, [files]
  • Delete Key: DELETE token, passphrase
Offline Encryption
  • Upload Key: POST publickey, privatekey (optional) privatekeyhash
  • Get Encrypted Messages: GET token,privatekeyhash
  • Send Encrypted Message: PUT token, encryptedmessage,encryptionkey
  • Delete Key: DELETE token, privatekeyhash

The sample implementation below uses jQuery and knockout.js. The service supports CORS, so you can call it from any URL without the need for JSONP.

Offline API:

Offline Key Creation
publickey: RSA public key
privatekey: RSA private key encrypted with the passphrase. This is optional - only needed if you want to allow online decryption
privatekeyhash: Any string accepted when using offline decryption, when using online must be SHA256 hash of the RSA private key

Offline Messaging
encryptedmessage is a GZIP compressed message which is then encrypted using AES256 with a random passphrase
encryptionkey is that random passphrase encrypted using the RSA public key

Offline Decryption
privatekeyhash: If the key was created online, this must be the SHA256 hash of the private key. If it was created offline, any string can be used as long as it matches the original value specified for the private key. The function of the privatekeyhash is to authenticate the message request so that the message meta-data (size and date) cannot be retrieved. (Message size and date are stored in plaintext in the database.)

Refer to the source code of the desktop apps for an example of the offline implementation.

The response format (xml or json) can be specified in requests using either the Accept header or adding "format=" to the request URI. If no response format is specified, JSON is the default.

Response status codes are: 200 (OK), 304 (No messages sent), 400 (Invalid operation) and 500 (Server error).

If you do not send a version string, the latest version is assumed. If your are consuming the service from an application you should append v={version} as a paramater.
The current version is 1.


(Alternative: send publickey as a parameter for offline decryption.)


(Files can be sent as form data; offline encryption support coming soon.)



Server Response:

  • MessageId: Message: Send On: IsFile: