ZEBRA-API

README

Zebra Sharing System

Zebra Sharing System is open-source software for secured data exchange. You can run it and as docker containers or as regular software.

Components

• Zebra API - Go app, which handles server-side part of the functionality. https://github.com/charger88/zebra-api
• Zebra Client - HTML single page app which may be served by web server or may be opened as HTML file from local disc. https://github.com/charger88/zebra-client
• Zebra docker images - possible way to run Zebra API and Zebra Client. https://github.com/charger88/zebra-docker

Zebra API

Requirements

• Go language
• Go packages:
  • github.com/go-yaml/yaml
  • github.com/mediocregopher/radix.v2/redis
  • golang.org/x/crypto/bcrypt
• Redis server

How to run it

Make sure that you meet all requirement, made all required changes in the configuration and run this application with command like:

go run *.go

Please, don't expose the app into internet without nginx or other web server with enabled SSL in front of it.

Also this web server may serve web client files. Example of nginx configuration: https://github.com/charger88/zebra-docker/blob/master/zebra-client/default.conf

Configuration

There are two way to change Zebra API configuration:

• Create file config/config.yaml and override in it values of config/default.yaml
• Define environmental variables (my-var in config file transforms to ZEBRA_MY_VAR in environment)

File config/config.yaml has more priority than environmental variables.

Config file overview

Redis configuration

• redis-host (string, "127.0.0.1") - redis host
• redis-port (integer, 6379) - redis port
• redis-password (string, "") - redis password
• redis-database (integer, 0) - redis database number
• redis-pool (integer, 16) - number of redis connections in the pool
• redis-key-prefix (string, "") - redis key prefix

HTTP configuration

• http-interface (string, "") - interface for listening by API application. Provide IP or hostname. Leave empty value for listening on all interfaces
• http-port (integer, 8080) - port for listening by API application
• trusted-proxy (string[], - "127.0.0.1/32") - list of trusted proxies (your web server IP)

Key generation policy

• minimal-key-length (integer, 4) - minimal length of key for shared text
• expected-stripes-per-hour (integer, 1000) - expected number of shared text in one hour
• appropriate-chance-to-guess (integer, 1000000000) - the greater this value is, the longer key will be generated

Rate limiting

• allowed-bad-attempts (integer, 5) - number of allowed failed attempts to retrieve text in one minute
• allowed-shares-period (integer, 60) - rate limit period for text sharing (seconds)
• allowed-shares-number-in-period (integer, 5) - rate limit for text sharing (number in allowed-shares-period seconds)

Security configuration

• max-expiration-time (integer, 86400) - maximal text's expiration time (in seconds)
• max-text-length (integer, 50000) - total text length limit in bytes (so it is not accurate after encryption)
• password-policy (string, "allowed") - possible values are:
  • allowed - password for shared text is optional
  • required - password for shared text is required
  • disabled - password for shared text not allowed
• encryption-password-policy (string, "allowed") - option for client application, possible values are:
  • allowed - (different) encryption password for shared text is optional
  • required - (different) encryption password for shared text is required
  • disabled - (different) encryption password for shared text not allowed
• require-api-key (boolean, false) - require X-Api-Key
• require-api-key-for-post-only (boolean, true) - require X-Api-Key for text sharing only (require-api-key should be true)
• allowed-api-keys (string[]) - list of appropriate values of X-Api-Key header
• guest-one-time-key (boolean, false) - if X-Api-Key required you can use this feature to generate one-time keys (for guests) which will work instead of X-Api-Key (one time each)
• guest-one-time-key-expiration-time (integer, 3600) - expiration of one-time keys (in seconds)

Configuration for client

• public-name (string, "Zebra Sharing Service") - name of the instance
• public-color (string, "#425766") - color of header in client
• public-url (string, "https://127.0.0.1/") - URL of your web server which serves client and proxy API
• public-email (string, "") - email of current instance administrator

System configuration

• version (string, "1.0.0") - API version. You don't need to override it.
• config-reload-time (string, 60) - time in seconds for configs reload (this option, as well as http-interface and http-port will not being updated without app restart)
• extended-logs (boolean, false) - log all events from Zebra API. Don't enable if you are not absolutely sure about protection of log files.

API Overview

This is JSON REST API.

API allows header X-Api-Key for API Key (optional, see require-api-key, require-api-key-for-post-only and allowed-api-keys configurations).

All API routes also support OPTIONS HTTP method.

/

GET

Response (json)

• routes - list of REST API resources (routes) and allowed methods
  • %route name% - list of allowed HTTP methods

/ping

GET

Response (json)

• timestamp - UNIX timestamp current

/config

GET

Response (json)

• version - API version (from config version)
• name - instance name (from config public-name)
• url - URL of web server (from config public-url)
• email - administrator's email (from config public-email)
• color - color for client (from config public-color)
• max-expiration-time - max expiration time (from config max-expiration-time)
• max-text-length - total text length limit in bytes (so it is not accurate after encryption)
• encryption-password-policy - client-side encryption password policy (from config password-policy)
• password-policy - password policy (from config password-policy)
• require-api-key - require API key configuration (from config require-api-key)
• require-api-key-for-post-only - require API key for POST only configuration (from config require-api-key-for-post-only)

/stripe

GET

Request query string

• key - key
• password - password (optional)
• check-key - special key which allows to ignore rate limiting. It is being generated when text is deleted (optional)

Response (json)

• key - key
• data - share data
• expiration - expiration timestamp
• burn - true if text will be deleted after this opening (actually it is already deleted)

POST

Request (json)

• data - sharing data
• burn - true to delete after the first opening
• expiration - expiration in seconds
• mode - key generation mode (uppercase-lowercase-digits, uppercase-digits, uppercase, digits)
• encrypted-with-client-side-password - confirmation of encryption on client-side with client-side password
• password - password (optional)

Response (json)

• key - key
• expiration - expiration timestamp
• owner-key - owner's key (required for deleting)

DELETE

Request query string

• key - key
• owner-key - owner's key

Response (json)

• success - boolean value of deletion's success
• check-key - string key which allows to ignore rate limiting for attempt to load the text (so you can check text's non-existence without rate limit)