A web service that performs hashing, encryption, encoding, and compression.

Full Description

hashsrv is a web service that performs hashing, encryption, encoding, and compression.

A configuration file in TOML format is used to set up hashsrv,but environment variables and command-line options may be used as well.

Using hashsrv

hashsrv URLs are composed of commands that describe what to do with the given data. For instance, posting data to:

/md5/hex

will calculate the MD5 hash of the posted data, convert it to hex encoding, and respond with the result.

hashsrv implements a simple processing engine that has a stack and a dictionary to store variables. Initially, the data posted via HTTP is pushed onto the stack. Most operations consume data from the stack and push their results onto the stack.

Additional arguments to operations can be placed onto the stack as literals. For instance, to generate 20 bytes of cryptographically random data and convert it to base64, use:

/20/rand/base64

You should issue a GET request for that because no POST data is required.

Items in the URL that are not keywords are placed onto the stack. At the end of the list of commands, the stack should have a single value to use as the result of the request, or else an error occurs.

Named variables can be saved and loaded from a dictionary. See the load and save commands. The dictionary is initialized with HTTP headers that begin with Hashsrv- (with the prefix removed). So, to pass a variable called key into the dictionary, you can send an HTTP header called Hashsrv-Key.

As a convenience, the dictionary is initialized with the following values:

body - the original request body

key - initialized with a default key

A number of standard combinations that you can invoke with the call command.

Debug Mode

To output a debug view instead of the result, add ?debug=1 to the URL.

Note: When using HMAC, it is customary to hash the key using the same hash function defined for that version of HMAC. You must do that yourself. For instance, when using hmac-sha256, the key should be hashed with sha256 and then used for HMAC.

Compresses data using the lzw algorithm - stack contains the number of bits to use for literal codes, typically 8 but can be 2-8. This version uses least significant bit ordering as used in the GIF file format.

unlzw-lsb

Compressed, Bits

Data

Decompresses data using the lzw algorithm - stack contains the number of bits to use for literal codes, typically 8 but can be 2-8. This version uses least significant bit ordering as used in the GIF file format.

lzw-msb

Data, Bits

Compressed

Compresses data using the lzw algorithm - stack contains the number of bits to use for literal codes, typically 8 but can be 2-8. This version uses most significant bit ordering as used in the TIFF and PDF file formats.

unlzw-msb

Compressed, Bits

Compressed

Decompresses data using the lzw algorithm - stack contains the number of bits to use for literal codes, typically 8 but can be 2-8. This version uses most significant bit ordering as used in the TIFF and PDF file formats.

Control Functions

Command

Stack in

Stack out

Description

push

Data

Data, Data

Duplicates the value on the top of the stack

pop

Data

Pops the value off the top of the stack (effectively discarding)

load

Name

Value

Pushes a named value from the dictinary onto the stack

save

Value, Name

Pops a value from the stack and places it into the dictionary

swap

Val1, Val2

Val2, Val1

Swaps the two values at the top of the stack

append

Val1, Val2

Appended

Appends the value on the top of the stack to the previous value on the stack

slice

Data

SliceOfData

Slices the value on the stack, taking elements from start to end on the stack. Use -1 for values from the beginning or end. One example is /9/20/slice which takes elements 9 through 19, or /2/-1/slice which takes elements 2 through the end.

len

Data

Data, Length

Pushes the length of the value on the stack in bytes onto the stack

left

Data, Count

SliceOfData

Takes the leftmost bytes of data

right

Data, Count

SliceOfData

Takes the rightmost bytes of data

snip

Data, Pos

Data1, Data2

Snips the data in half at the given position, resulting in two values on the stack

eq

Data1, Data2

Fails the command unless the two data elements are equal

neq

Data1, Data2

Fails the command unless the two data elements are not equal

call

Name

(Varies)

Loads the named value from the dictionary and executes the commands contained there (formatted like normal - /md5/hex for example)

Crypto Functions

Encrypts data using the given IV and 16-byte Key, placing the ciphertext back on the stack. Uses AES encryption and the CFB block mode.

unaes-cfb

Data, IV, Key

Data

Decrypts data using the given IV and 16-byte Key, placing the plaintext back on the stack. Uses AES encryption and the CFB block mode.

aes-ofb

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 16-byte Key, placing the result back on the stack. Uses AES encryption and the OFB block mode.

aes-ctr

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 16-byte Key, placing the result back on the stack. Uses AES encryption and the CTR block mode.

des-blocksize

8

Pushes the DES block size on the stack

des-cfb

Data, IV, Key

Data

Encrypts data using the given IV and 8-byte Key, placing the ciphertext back on the stack. Uses DES encryption and the CFB block mode.

undes-cfb

Data, IV, Key

Data

Decrypts data using the given IV and 8-byte Key, placing the plaintext back on the stack. Uses DES encryption and the CFB block mode.

des-ofb

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 8-byte Key, placing the result back on the stack. Uses DES encryption and the OFB block mode.

des-ctr

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 8-byte Key, placing the result back on the stack. Uses DES encryption and the CTR block mode.

3des-blocksize

8

Pushes the Triple DES block size on the stack

3des-cfb

Data, IV, Key

Data

Encrypts data using the given IV and 24-byte Key, placing the ciphertext back on the stack. Uses Triple DES encryption and the CFB block mode.

un3des-cfb

Data, IV, Key

Data

Decrypts data using the given IV and 24-byte Key, placing the plaintext back on the stack. Uses Triple DES encryption and the CFB block mode.

3des-ofb

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 24-byte Key, placing the result back on the stack. Uses Triple DES encryption and the OFB block mode.

3des-ctr

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 24-byte Key, placing the result back on the stack. Uses Triple DES encryption and the CTR block mode.

blowfish-blocksize

8

Pushes the blowfish block size on the stack

blowfish-cfb

Data, IV, Key

Data

Encrypts data using the given IV and 1 to 56-byte Key, placing the ciphertext back on the stack. Uses Blowfish encryption and the CFB block mode.

unblowfish-cfb

Data, IV, Key

Data

Decrypts data using the given IV and 1 to 56-byte Key, placing the plaintext back on the stack. Uses Blowfish encryption and the CFB block mode.

blowfish-ofb

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 1 to 56-byte Key, placing the result back on the stack. Uses Blowfish encryption and the OFB block mode.

blowfish-ctr

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 1 to 56-byte Key, placing the result back on the stack. Uses Blowfish encryption and the CTR block mode.

blowfish-salt-cfb

Data, IV, Key, Salt

Data

Encrypts data using the given IV and 1 to 56-byte Key, placing the ciphertext back on the stack. Uses Blowfish encryption and the CFB block mode.

unblowfish-salt-cfb

Data, IV, Key, Salt

Data

Decrypts data using the given IV and 1 to 56-byte Key, placing the plaintext back on the stack. Uses Blowfish encryption and the CFB block mode.

blowfish-salt-ofb

Data, IV, Key, Salt

Data

Encrypts or decrypts data using the given IV and 1 to 56-byte Key, placing the result back on the stack. Uses Blowfish encryption and the OFB block mode.

blowfish-salt-ctr

Data, IV, Key, Salt

Data

Encrypts or decrypts data using the given IV and 1 to 56-byte Key, placing the result back on the stack. Uses Blowfish encryption and the CTR block mode.

twofish-blocksize

16

Pushes the twofish block size on the stack

twofish-cfb

Data, IV, Key

Data

Encrypts data using the given IV and 16, 24, or 32-byte Key, placing the ciphertext back on the stack. Uses Twofish encryption and the CFB block mode.

untwofish-cfb

Data, IV, Key

Data

Decrypts data using the given IV and 16, 24, or 32-byte Key, placing the plaintext back on the stack. Uses Twofish encryption and the CFB block mode.

twofish-ofb

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 16, 24, or 32-byte Key, placing the result back on the stack. Uses Twofish encryption and the OFB block mode.

twofish-ctr

Data, IV, Key

Data

Encrypts or decrypts data using the given IV and 16, 24, or 32-byte Key, placing the result back on the stack. Uses Twofish encryption and the CTR block mode.

Notes on encryption

The initialization vector (IV) is used by many routines. It does not need to be kept secure, but it should generally be random and different for each different encryption run. It can easily be generated with the rand function. However, you need to keep it for decryption. It is customary to put it at the beginning of the encrypted data. These routines don't do that for you.

Each encryption routine supports several block modes. Some of the block modes are symmetrical - so you use the same function to encrypt and decrypt. Others are not.

Some routines require fixed key sizes, others are variable. Keys can be any data. It is usually considered more secure when these keys are relatively random or hashed.

On the todo list

Control - loop (to go through lines of text and do batch operations)

Specialized - protect, unprotect

Examples

URL

Result

POST /

Returns what you posted

POST /sha256

Returns SHA256 hash as binary data

POST /sha256/hex

Returns SHA256 hash as hex encoding

POST /unhex/snappy/hex

Decodes hex data, compresses it using Snappy, and encodes the result to hex

GET /Hello%20World/32/rand/md5/hmac-md5/hex

Pushes "Hello World" on the stach, generates 32 bytes of random data as the HMAC key (which is then hashed with md5), computes the HMAC-MD5 hash, and converts the result to hex. Try It!

POST /MyKeyHere/sha512/hmac-sha512/base64-url

Hashes the data with HMAC-SHA512 using the the sha512 hash of the key "MyKeyHere" and returns it as base64.

Running hashsrv

All you need is your configuration file and the hashsrv binary for your platform. You can run it manually or as a service on Windows or Linux (see below).

nohup is a Linux utility that keeps a process going after you log off.

Installation

The only required files are the hashsrv binary and the configuration file. The hashsrv has minimal dependencies - just a few shared libraries that should already be on the operating system.

On all operating systems, you may override the configuration file location using the HASHSRV_CONFIG environment variable or the -config command-line option, which takes precedence. See below for where to place the configuration file when none of these are present.

The location of the configuration file is based on the location of the hashsrv binary. /usr/bin and /bin locations are replaced with /etc - so effectively, the configuration file is located in the etc folder that corresponds to the bin folder. If the binary is not in a bin folder, then the configuration file is expected to be in the same folder as the binary. Some examples are shown below.

hashsrv binary location

Default configuration file location

/bin/hashsrv

/etc/hashsrv.config

/usr/bin/hashsrv

/etc/hashsrv.config

/usr/local/bin/hashsrv

/usr/local/etc/hashsrv.config

/usr/local/bin/foo/hashsrv

/usr/local/etc/foo/hashsrv.config

/usr/local/foo/bin/hashsrv

/usr/local/foo/etc/hashsrv.config

c:\hashsrv\bin\hashsrv.exe

c:\hashsrv\etc\hashsrv.config

c:\files\hashsrv.exe

c:\files\hashsrv.config

/home/michael/hashsrv

/home/michael/hashsrv.config

Running as a service

You can install the hashsrv as a service on Windows or Linux with Upstart. Use the -install and -remove options to install or remove the hashsrv.

Linux

On Linux, the -install option created a HashSrv.conf file in /etc/init. To start or stop the hashsrv, you can use:

sudo start HashSrv
sudo stop HashSrv

If the service doesn't start, most likely the configuration file has a problem.

Windows

On Windows, the hashsrv uses the Service API. Use the Service administration tool to start or stop the hashsrv.

Also, you will need to use the -run option if you want to run the application standalone (not as a service).