Categorygithub.com/ancientlore/hashsrv
module
1.11.0
Repository: https://github.com/ancientlore/hashsrv.git
Documentation: pkg.go.dev

# README

hashsrv

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

Go Reference

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.

Try It!

Hash Functions

CommandStack inStack outDescription
md5DataHashHashes data using MD5
sha1DataHashHashes data using SHA1
sha224DataHashHashes data using SHA224
sha256DataHashHashes data using SHA256
sha384DataHashHashes data using SHA384
sha512DataHashHashes data using SHA512
ripemd160DataHashHashes data using RIPEMD160
hmac-md5Data, KeyHashHMAC hashes data using MD5
hmac-sha1Data, KeyHashHMAC hashes data using SHA1
hmac-sha224Data, KeyHashHMAC hashes data using SHA2 224-bit
hmac-sha256Data, KeyHashHMAC hashes data using SHA2 256-bit
hmac-sha384Data, KeyHashHMAC hashes data using SHA2 384-bit
hmac-sha512Data, KeyHashHMAC hashes data using SHA2 512-bit
hmac-ripemd160Data, KeyHashHMAC hashes data using RIPEMD160
md5-len16Returns the number of bytes for MD5
sha1-len20Returns the number of bytes for SHA1
sha224-len28Returns the number of bytes for SHA224
sha256-len32Returns the number of bytes for SHA256
sha384-len48Returns the number of bytes for SHA384
sha512-len64Returns the number of bytes for SHA512
ripemd160-len20Returns 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

CommandStack inStack outDescription
hexDataEncodedDataEncode the data as hex
unhexEncodedDataDataDecode the data as hex
ascii85DataEncodedDataEncode data as ASCII-85
unascii85EncodedDataDataDecode data as ASCII-85
base32DataEncodedDataEncode data as BASE-32
unbase32EncodedDataDataDecode data as BASE-32
base32-hexDataEncodedDataEncode data as BASE-32 Hex
unbase32-hexEncodedDataDataDecode data as BASE-32 Hex
base64DataEncodedDataEncode data as BASE-64
unbase64EncodedDataDataDecode data as BASE-64
base64-urlDataEncodedDataEncode data as BASE-64 URL
unbase64-urlEncodedDataDataDecode data as BASE-64 URL

Checksum Functions

CommandStack inStack outDescription
adler32DataChecksumCompute the Adler-32 checksum
crc32DataChecksumCompute the CRC-32 checksum using the IEEE polynomial
crc32-ieeeDataChecksumCompute the CRC-32 checksum using the IEEE polynomial
crc32-castagnoliDataChecksumCompute the CRC-32 checksum using the Castagnoli polynomial
crc32-koopmanDataChecksumCompute the CRC-32 checksum using the Koopman polynomial
crc64-isoDataChecksumCompute the CRC-64 checksum using the ISO polynomial
crc64-ecmaDataChecksumCompute the CRC-64 checksum using the ECMA polynomial
fnv32DataHashCompute the FNV-1 non-cryptographic hash for 32-bits
fnv32aDataHashCompute the FNV-1a non-cryptographic hash for 32-bits
fnv64DataHashCompute the FNV-1 non-cryptographic hash for 64-bits
fnv64aDataHashCompute the FNV-1a non-cryptographic hash for 64-bits

Compression Functions

CommandStack inStack outDescription
snappyDataCompressedCompresses data using the Snappy algorithm
unsnappyCompressedDataDecompresses data using the Snappy algorithm
zlibDataCompressedCompresses data using the zlib algorithm
unzlibCompressedDataDecompresses data using the zlib algorithm
deflateData, FactorCompressedCompresses 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)
inflateCompressedDataDecompresses data using the flate algorithm
gzipData, FactorCompressedCompresses 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
ungzipCompressedDataDecompresses data using the gzip algorithm
unbzip2CompressedDataDecompresses data using the bzip2 algorithm
lzw-lsbData, BitsCompressedCompresses 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-lsbCompressed, BitsDataDecompresses 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-msbData, BitsCompressedCompresses 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-msbCompressed, BitsCompressedDecompresses 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

CommandStack inStack outDescription
pushDataData, DataDuplicates the value on the top of the stack
popDataPops the value off the top of the stack (effectively discarding)
loadNameValuePushes a named value from the dictinary onto the stack
saveValue, NamePops a value from the stack and places it into the dictionary
swapVal1, Val2Val2, Val1Swaps the two values at the top of the stack
appendVal1, Val2AppendedAppends the value on the top of the stack to the previous value on the stack
sliceDataSliceOfDataSlices 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.
lenDataData, LengthPushes the length of the value on the stack in bytes onto the stack
leftData, CountSliceOfDataTakes the leftmost bytes of data
rightData, CountSliceOfDataTakes the rightmost bytes of data
snipData, PosData1, Data2Snips the data in half at the given position, resulting in two values on the stack
eqData1, Data2Fails the command unless the two data elements are equal
neqData1, Data2Fails the command unless the two data elements are not equal
callName(Varies)Loads the named value from the dictionary and executes the commands contained there (formatted like normal - /md5/hex for example)

Crypto Functions

CommandStack inStack outDescription
randCountDataGenerates cryptographically random bytes given the count on the stack
aes-blocksize16Pushes the AES block size on the stack
aes-cfbData, IV, KeyDataEncrypts 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-cfbData, IV, KeyDataDecrypts 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-ofbData, IV, KeyDataEncrypts 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-ctrData, IV, KeyDataEncrypts 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-blocksize8Pushes the DES block size on the stack
des-cfbData, IV, KeyDataEncrypts 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-cfbData, IV, KeyDataDecrypts 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-ofbData, IV, KeyDataEncrypts 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-ctrData, IV, KeyDataEncrypts 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-blocksize8Pushes the Triple DES block size on the stack
3des-cfbData, IV, KeyDataEncrypts 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-cfbData, IV, KeyDataDecrypts 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-ofbData, IV, KeyDataEncrypts 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-ctrData, IV, KeyDataEncrypts 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-blocksize8Pushes the blowfish block size on the stack
blowfish-cfbData, IV, KeyDataEncrypts 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-cfbData, IV, KeyDataDecrypts 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-ofbData, IV, KeyDataEncrypts 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-ctrData, IV, KeyDataEncrypts 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-cfbData, IV, Key, SaltDataEncrypts 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-cfbData, IV, Key, SaltDataDecrypts 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-ofbData, IV, Key, SaltDataEncrypts 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-ctrData, IV, Key, SaltDataEncrypts 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-blocksize16Pushes the twofish block size on the stack
twofish-cfbData, IV, KeyDataEncrypts 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-cfbData, IV, KeyDataDecrypts 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-ofbData, IV, KeyDataEncrypts 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-ctrData, IV, KeyDataEncrypts 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

URLResult
POST /Returns what you posted
POST /sha256Returns SHA256 hash as binary data
POST /sha256/hexReturns SHA256 hash as hex encoding
POST /unhex/snappy/hexDecodes hex data, compresses it using Snappy, and encodes the result to hex
GET /Hello%20World/32/rand/md5/hmac-md5/hexPushes "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-urlHashes 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 locationDefault 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.exec:\hashsrv\etc\hashsrv.config
c:\files\hashsrv.exec:\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

OptionDefaultDescription
HASHSRV_CONFIGhashsrv.config (see above)Specifies the default location of the configuration file

Command-Line Parameters

OptionDefaultDescription
-addr":9009"Address to serve
-configHASHSRV_CONFIG environment variableUse to override the configuration file
-cpuprofileWrite CPU profile to file
-memprofileWrite memory profile to file
-helpfalseShow command help
-noisyfalseEnable logging
-installfalseInstall hashsrv as a service
-removefalseRemove the hashsrv service
-runfalseRun hashsrv standalone (not as a service)
-startfalseStart the hashsrv service
-stopfalseStop the hashsrv service

Configuration File Parameters

OptionDefaultDescription
addr":9009"Web server address

# Packages

No description provided by the author
No description provided by the author