# README
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
callcommand.
Debug Mode
To output a debug view instead of the result, add ?debug=1 to the URL.
Hash Functions
| Command | Stack in | Stack out | Description |
|---|---|---|---|
| md5 | Data | Hash | Hashes data using MD5 |
| sha1 | Data | Hash | Hashes data using SHA1 |
| sha224 | Data | Hash | Hashes data using SHA224 |
| sha256 | Data | Hash | Hashes data using SHA256 |
| sha384 | Data | Hash | Hashes data using SHA384 |
| sha512 | Data | Hash | Hashes data using SHA512 |
| ripemd160 | Data | Hash | Hashes data using RIPEMD160 |
| hmac-md5 | Data, Key | Hash | HMAC hashes data using MD5 |
| hmac-sha1 | Data, Key | Hash | HMAC hashes data using SHA1 |
| hmac-sha224 | Data, Key | Hash | HMAC hashes data using SHA2 224-bit |
| hmac-sha256 | Data, Key | Hash | HMAC hashes data using SHA2 256-bit |
| hmac-sha384 | Data, Key | Hash | HMAC hashes data using SHA2 384-bit |
| hmac-sha512 | Data, Key | Hash | HMAC hashes data using SHA2 512-bit |
| hmac-ripemd160 | Data, Key | Hash | HMAC hashes data using RIPEMD160 |
| md5-len | 16 | Returns the number of bytes for MD5 | |
| sha1-len | 20 | Returns the number of bytes for SHA1 | |
| sha224-len | 28 | Returns the number of bytes for SHA224 | |
| sha256-len | 32 | Returns the number of bytes for SHA256 | |
| sha384-len | 48 | Returns the number of bytes for SHA384 | |
| sha512-len | 64 | Returns the number of bytes for SHA512 | |
| ripemd160-len | 20 | Returns the number of bytes for RIPEMD160 |
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.
Encoding Functions
| Command | Stack in | Stack out | Description |
|---|---|---|---|
| hex | Data | EncodedData | Encode the data as hex |
| unhex | EncodedData | Data | Decode the data as hex |
| ascii85 | Data | EncodedData | Encode data as ASCII-85 |
| unascii85 | EncodedData | Data | Decode data as ASCII-85 |
| base32 | Data | EncodedData | Encode data as BASE-32 |
| unbase32 | EncodedData | Data | Decode data as BASE-32 |
| base32-hex | Data | EncodedData | Encode data as BASE-32 Hex |
| unbase32-hex | EncodedData | Data | Decode data as BASE-32 Hex |
| base64 | Data | EncodedData | Encode data as BASE-64 |
| unbase64 | EncodedData | Data | Decode data as BASE-64 |
| base64-url | Data | EncodedData | Encode data as BASE-64 URL |
| unbase64-url | EncodedData | Data | Decode data as BASE-64 URL |
Checksum Functions
| Command | Stack in | Stack out | Description |
|---|---|---|---|
| adler32 | Data | Checksum | Compute the Adler-32 checksum |
| crc32 | Data | Checksum | Compute the CRC-32 checksum using the IEEE polynomial |
| crc32-ieee | Data | Checksum | Compute the CRC-32 checksum using the IEEE polynomial |
| crc32-castagnoli | Data | Checksum | Compute the CRC-32 checksum using the Castagnoli polynomial |
| crc32-koopman | Data | Checksum | Compute the CRC-32 checksum using the Koopman polynomial |
| crc64-iso | Data | Checksum | Compute the CRC-64 checksum using the ISO polynomial |
| crc64-ecma | Data | Checksum | Compute the CRC-64 checksum using the ECMA polynomial |
| fnv32 | Data | Hash | Compute the FNV-1 non-cryptographic hash for 32-bits |
| fnv32a | Data | Hash | Compute the FNV-1a non-cryptographic hash for 32-bits |
| fnv64 | Data | Hash | Compute the FNV-1 non-cryptographic hash for 64-bits |
| fnv64a | Data | Hash | Compute the FNV-1a non-cryptographic hash for 64-bits |
Compression Functions
| Command | Stack in | Stack out | Description |
|---|---|---|---|
| snappy | Data | Compressed | Compresses data using the Snappy algorithm |
| unsnappy | Compressed | Data | Decompresses data using the Snappy algorithm |
| zlib | Data | Compressed | Compresses data using the zlib algorithm |
| unzlib | Compressed | Data | Decompresses data using the zlib algorithm |
| deflate | Data, Factor | Compressed | Compresses data using the flate algorithm - stack contains a compression factor where -1 is default and 0-9 controls compression (0 is none, and 9 is the most) |
| inflate | Compressed | Data | Decompresses data using the flate algorithm |
| gzip | Data, Factor | Compressed | Compresses data using the gzip algorithm - stack contains a compression factor where -1 is default, 0 is none, 1 is best speed, and 9 is best size |
| ungzip | Compressed | Data | Decompresses data using the gzip algorithm |
| unbzip2 | Compressed | Data | Decompresses data using the bzip2 algorithm |
| lzw-lsb | 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 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
| Command | Stack in | Stack out | Description |
|---|---|---|---|
| rand | Count | Data | Generates cryptographically random bytes given the count on the stack |
| aes-blocksize | 16 | Pushes the AES block size on the stack | |
| aes-cfb | Data, IV, Key | Data | 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).
To test with the default configuration file and logging:
./hashsrv -run
To run in the background:
./hashsrv -run &
To keep it running after you log off:
nohup ./hashsrv -run &
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).
Environment Variables
| Option | Default | Description |
|---|---|---|
| HASHSRV_CONFIG | hashsrv.config (see above) | Specifies the default location of the configuration file |
Command-Line Parameters
| Option | Default | Description |
|---|---|---|
| -addr | ":9009" | Address to serve |
| -config | HASHSRV_CONFIG environment variable | Use to override the configuration file |
| -cpuprofile | Write CPU profile to file | |
| -memprofile | Write memory profile to file | |
| -help | false | Show command help |
| -noisy | false | Enable logging |
| -install | false | Install hashsrv as a service |
| -remove | false | Remove the hashsrv service |
| -run | false | Run hashsrv standalone (not as a service) |
| -start | false | Start the hashsrv service |
| -stop | false | Stop the hashsrv service |
Configuration File Parameters
| Option | Default | Description |
|---|---|---|
| addr | ":9009" | Web server address |