API

INTERLOCK API
=============

# Main API Objects (data types definitions from JSON.org)

partition:
  {
    "identifier":  string,   # partition identifier
    "info":        string,   # encryption information
    "total_space": number,   # size in bytes
    "free_space":  number    # size in bytes
  }

inode:
  {
    "name":        string,   # absolute file or directory path
    "dir" :        boolean,  # true => directory
    "size":        number,   # size in bytes
    "mtime":       number    # modify time in epoch
    "key_path":    boolean,  # true if path is within key storage
    "private":     boolean,  # true if path contains private keys
     ############  optional: ############
    "key":         key,      # key object
    "sha256":      string    # SHA256 message digest
  }

cipher:
  {
    "name":        string,   # method name
    "info":        string,   # method information
    "key_format":  string,   # supported key format
    "enc":         boolean,  # encryption support
    "dec":         boolean,  # decryption support
    "sig":         boolean,  # signing support
    "otp":         boolean,  # one-time password support
    "msg":         boolean,  # messaging support
    "ext":         string    # encrypted file extension
  }

key:
  {
    "identifier":  string,   # key identifier
    "key_format":  string,   # key format ("armor")
    "cipher":      string,   # name for cipher object
    "private":     boolean,  # identifies private, public keys
    "path":        string    # key path
  }

positive response:
  {
    "status":      string,   # OK
     ############  optional: ############
    "response":    {} | [{}] # response object(s)
  }

error response:
  {
    "status":      string,   # KO | INVALID_SESSION | INVALID
    "response":    string    # error string
  }

# Core API Methods

  api/
    auth/           login, refesh, logout, poweroff
    luks/           change, add, remove
    file/           list, upload, delete, move, copy, mkdir, extract, compress
    file/           encrypt, decrypt, verify
    crypto/         ciphers, keys, gen_key, upload_key, key_info
    config/         time
    status/         version, running
  static/           static HTML/JavaScript content

## POST api/auth/login

On a successful login the "INTERLOCK-Token" is returned as cookie via the
"Set-Cookie" header in HTTP response.

The XSRF protection token "X-XSRFToken" is returned in the response payload.
This token must be included by the client as HTTP header in every request to
the backend (except for GET /api/file/download?id=<download_id>).

The "dispose" boolean indicates that the LUKS password must be removed after
mounting the encrypted partition, this is possible as long as one other valid
password is configured.

request:
  {
    "volume":      string,   # encrypted volume name
    "password":    string,   # password for encrypted partition mount
    "dispose":     boolean   # dispose of the password after use
  }

response:
  {
    "status":      string,   # OK | KO | INVALID_SESSION | INVALID
    "response": {
      "volume":    string,   # encrypted volume name
      "XSRFToken": string
    }
  }

'Set-Cookie' header example:
Set-Cookie: INTERLOCK-Token=DQAAAK...Eaem_vYg; Path=/;
            Expires=Wed, 30 Jan 2015 22:23:01 GMT; Secure; HttpOnly

## GET api/auth/refresh

Return the XSRF protection token for the authenticated session.

response:
  {
    "status":      string,   # OK | KO | INVALID_SESSION | INVALID
    "response": {
      "volume":    string,   # encrypted volume name
      "XSRFToken": string
    }
  }

## POST api/auth/logout

Invalidate the current session 'INTERLOCK-Token' cookie and unmount the
encrypted partition.

## POST api/auth/poweroff

Identical to logout with the addition of performing a power down of the device
after session invalidation.

## POST api/config/time

Set the device date and time. This function is specifically designed to ensure
a correct date and time on non-routed USB armory devices (unable to set the
clock on their own). The call is a non-op by default and can be enabled with
the "set_time" configuration option.

request:
  {
    "epoch":       number    # system date and time in epoch format
  }

## POST api/luks/change

Change existing password assigned to a LUKS key slot. The password is used to
mount the encrypted partition and to perform the initial login.

request:
  {
    "volume":      string,   # encrypted volume name
    "password":    string,   # valid LUKS password
    "newpassword": string    # new LUKS password
  }

## POST api/luks/add

Add a new password to the next available LUKS key slot.

request:
  {
    "volume":      string,   # encrypted volume name
    "password":    string,   # valid LUKS password
    "newpassword": string    # added LUKS password
  }

## POST api/luks/remove

Delete an existing password from a LUKS key slots.

request:
  {
    "volume":      string,   # encrypted volume name
    "password":    string    # valid LUKS password
  }

## POST api/file/list

Get the list of all files and directories under the specified path.

request:
  {
    "path":        string,   # supports wildcards (e.g. *, ?)
    "sha256":      bool      # return SHA256 message digest
  }

response:
  {
    "status":      string,   # OK | KO
    "response": {
      "total_space": number, # partition size
      "free_space":  number, # remaining size
      "inodes":    [{inode}] # inode object(s)
    }
  }

## POST api/file/upload

Upload files using the XMLHttpRequest (XHR) API. The destination full path of
the file is specified by the "X-UploadFilename" HTTP custom header, the path
must be URL encoded.

HTTP request headers:
  X-UploadFilename: string
  X-ForceOverwrite: 'true' | 'false'

HTTP response codes:
  200: success
  400: bad request
  401: unauthorized

## POST api/file/download

Retrieve the unique id for downloading a file or directory. If a directory is
specified a zip file of its contents is downloaded. The returned id is meant to
be used with a GET to 'api/file/download?id=<download_id>'.

request:
  {
    "path":        string    # file path
  }

response:
  {
    "status":      string,    # OK | KO | INVALID_SESSION | INVALID
    "response":    number     # unique download identifier
  }

## GET api/file/download?id=<download_id>

Download a file, the file is specified by the download_id unique code returned
by the POST to 'api/file/download'. The download_id is disposed after use.
The XSRF protection token "X-XSRFToken" header is not required to be set.

HTTP response codes:
  200: success
  400: bad request
  401: unauthorized

## POST api/file/delete

Recursively delete one or more files or directories under a certain path.

request:
  {
    "path":        [string]  # absolute path for file and/or directory delete
  }

## POST api/file/move

Move/rename files or directories.

request:
  {
    "src":         [string], # absolute path for file and/or directory move
    "dst":         string    # absolute path for destination
  }

## POST api/file/copy

Copy files or directories.

request:
  {
    "src":         [string], # absolute path for file and/or directory copy
    "dst":         string    # absolute path for destination
  }

## POST api/file/mkdir

Create a new directory, path creation can include parent directories.

request:
  {
    "path":        [string]  # absolute path for directory creation
  }

## POST api/file/extract

Extract an archive file in the specified destination directory, which gets
created for decompressing the archive contents. Currently supported formats:
zip.

request:
  {
    "src":         [string], # absolute path for archive file
    "dst":         string    # absolute path for destination directory
  }

## POST api/file/compress

Compress the specified source file or directory in an archive file. Currently
supported formats: zip.

request:
  {
    "src":         [string], # absolute path for file and/or directory to zip
    "dst":         string    # absolute path for destination archive name
  }

## POST api/file/encrypt

Encrypt and/or sign one or more files.

request:
  {
    "src":         string,   # absolute path for file to encrypt
    "cipher":      string,   # name for cipher object
    "wipe_src":    boolean,  # wipe source after encryption (default: false)
    "sign":        boolean,  # sign the file (default: false)
    "password":    string,   # symmetric cipher or key password
    "key":         string,   # key path, only for asymmetric ciphers
    "sig_key":     string    # signature key identifier
  }

## POST api/file/decrypt

Decrypt one file.

request:
  {
    "src":         string,   # absolute path for file to decrypt
    "password":    string,   # symmetric cipher or key password
    "verify":      boolean,  # verify the file signature (default: false)
    "key":         string,   # key path, only for asymmetric ciphers
    "sig_key":     string,   # signature key identifier
    "cipher":      string    # name for cipher object, use ext if empty
  }

## POST api/file/sign

Sign a file using an asymmetric cipher.

request:
  {
    "src":         string,   # absolute path for file to sign
    "cipher":      string,   # name for cipher object
    "password":    string,   # key password
    "key":         string    # key path
  }

## POST api/file/verify

Verify file signature.

request:
  {
    "src":         string,   # absolute path for file to verify
    "sig":         string,   # absolute path for signature file
    "key":         string,   # signature key identifier
    "cipher":      string    # name for cipher object
  }

## GET api/crypto/ciphers

Get the list of all the available crypto algorithms.

response:
  {
    "status":      string,    # OK | KO | INVALID_SESSION | INVALID
    "response":    [{cipher}] # cipher object(s)
  }

## POST api/crypto/keys

Get the list of all the available public, private, symmetric keys.

request:
  {
    "public":      boolean,  # list public keys
    "private":     boolean,  # list private keys
     ############  optional: ############
    "filter":      string,   # case sensitive pattern match for key information
    "cipher":      cipher    # supported cipher name
  }

response:
  {
    "status":      string,   # OK | KO | INVALID_SESSION | INVALID
    "response":    [{key}]   # key object(s)
  }

## POST api/crypto/gen_key

Generate a key and/or keypair.

request:
  {
    "identifier":  string,   # key identifier
    "key_format":  string,   # key format ("armor")
    "cipher":      string,   # name for cipher object
    "email":       string    # email
  }

## POST api/crypto/upload_key

Upload a key.

request:
  {
    "key":         key,      # key object
    "data":        string    # key payload
  }

## POST api/crypto/key_info

Retrieve detailed key information supplementary to the existing standardized
attributes contained in the {key} object. The return details are dependent on
specific cipher/key parsing (e.g. OpenPGP key fingerprint).

request:
  {
    "path":        string,   # key path
  }

response:
  {
    "status":      string,   # OK | KO | INVALID_SESSION | INVALID
    "response":    string    # key information
  }

## GET api/status/version

Retrieve static backend version information.

response:
  {
    "status":      string,   # OK | KO | INVALID_SESSION | INVALID
    "response": {
      "revision" : string,   # revision
      "build":     string,   # build information
      "key_path":  string    # path for public/private key storage
    }
  }

## GET api/status/running

Retrieve dynamic backend status information.

response:
  {
    "status":      string,   # OK | KO | INVALID_SESSION | INVALID
    "response": {
      "uptime" :   number,   # Uptime
      "load_1" :   number,   # Load average for the past 1 minute
      "load_5" :   number,   # Load average for the past 5 minutes
      "load_15":   number,   # Load average for the past 15 minutes
      "freeram":   number,   # Available RAM
      "log": [
        {
          "epoch": number,   # timestamp
          "code":  number,   # RFC5424 severity level
          "msg":   string    # log message
        }
      ],
      "notification": [
        {
          "epoch": number,   # timestamp
          "code":  number,   # RFC5424 severity level
          "msg":   string    # notification message
        }
      ]
    }
  }