# jsSHA
A pure JavaScript streaming implementation of the complete Secure Hash Standard
family (SHA-1, SHA-224, SHA3-224, SHA-256, SHA3-256, SHA-384, SHA3-384, SHA-512,
SHA3-512, SHAKE128, and SHAKE256) as well as HMAC.
[](https://travis-ci.org/Caligatio/jsSHA)
## Usage
### Installation
#### Browser
Include the desired JavaScript file (sha.js, sha1.js, sha256.js, sha512.js, or
sha3.js) in your header (sha.js used below):
<script type="text/javascript" src="/path/to/sha.js"></script>
#### Node.js
jsSHA is available through NPM and be installed by simply doing
npm install jssha
To use the module, first require it using:
jsSHA = require("jssha");
### Hashing
Instantiate a new jsSHA object with the desired hash type, input type, and
options as parameters. The hash type can be one of SHA-1, SHA-224, SHA3-224,
SHA-256, SHA3-256, SHA-384, SHA3-384, SHA-512, SHA3-512, SHAKE128, or SHAKE256.
The input type can be one of HEX, TEXT, B64, BYTES, or ARRAYBUFFER. You can
then stream in input using the `update` object function, calling it multiple
times if needed. Finally, simply call `getHash` with the output type as a
parameter (B64, HEX, BYTES, or ARRAYBUFFER). Example to calculate the SHA-512
of "This is a test":
var shaObj = new jsSHA("SHA-512", "TEXT");
shaObj.update("This is a ");
shaObj.update("test");
var hash = shaObj.getHash("HEX");
The constructor takes a hashmap as a optional third argument with possible
properties of `numRounds` and `encoding`. `numRounds` controls the number of
hashing iterations/rounds performed and defaults to a value of 1 if not
specified. `encoding` specifies the encoding used to encode TEXT-type inputs.
Valid options are "UTF8", "UTF16BE", and "UTF16LE", it defaults to "UTF8".
`getHash` also takes a hashmap as an optional second argument. By default the
hashmap is `{"outputUpper" : false, "b64Pad" : "="}`. These options are
intelligently interpreted based upon the chosen output format. **Important**:
SHAKE128 and SHAKE256 require `shakeLen` to be included in the hashmap where
`shakeLen` is the desired output length of the SHAKE algorithm in a multiple
of 8 bits.
### HMAC
Instantiate a new jsSHA object the same way as for hashing. Then set the HMAC
key to be used by calling `setHMACKey` with the key and its input type (this
MUST be done before calling update). You can stream in the input using the
`update` object function just like hashing. Finally, get the HMAC by calling
the `getHMAC` function with the output type as its argument. Example to
calculate the SHA-512 HMAC of the string "This is a test" with the key "abc":
var shaObj = new jsSHA("SHA-512", "TEXT");
shaObj.setHMACKey("abc", "TEXT");
shaObj.update("This is a ");
shaObj.update("test");
var hmac = shaObj.getHMAC("HEX");
`setHMACKey` takes the same input types as the constructor and `getHMAC` takes the
same inputs as `getHash` as described above.
Note: You cannot calculate both the hash and HMAC using the same object.
## Files
**src/sha\_dev.js**
A commented implementation of the entire SHA family of hashes. Not to be used
in production.
**src/sha.js**
A Google Closure Compiler optimized version of the entire library.
**src/sha1.js**
A Google Closure Compiler optimized version the library with non SHA-1
functionality removed.
**src/sha256.js**
A Google Closure Compiler optimized version the library with non SHA-224/SHA-256
functionality removed.
**src/sha3.js**
A Google Closure Compiler optimized version the library with non SHA-3
functionality removed.
**src/sha512.js**
A Google Closure Compiler optimized version the library with non SHA-384/SHA-512
functionality removed.
## Compiling
This library makes use of the [Google Closure Compiler](https://developers.google.com/closure/compiler)
to both boost performance and reduce filesizes. To compile sha\_dev.js into a customized output file,
use a command like the following:
java -jar compiler.jar --define="SUPPORTED_ALGS=<FLAG>" \
--externs /path/to/build/externs.js --warning_level VERBOSE \
--compilation_level ADVANCED_OPTIMIZATIONS \
--js /path/to/sha_dev.js --js_output_file /path/to/sha.js
where FLAG is a bitwise OR of the following values:
* 8 for SHA3
* 4 for SHA-384/SHA-512
* 2 for SHA-224/256
* 1 for SHA-1
## Contact Info
The project's website is located at [https://caligatio.github.com/jsSHA/](https://caligatio.github.com/jsSHA/)
## Donations
Feel like donating? We're now accepting donations through [Pledgie](https://pledgie.com/campaigns/31646) and [Bitcoin](bitcoin:12VMZgRAP2jCP1YCR3vFNAtLR9MvzHzJZb?message=jsSHA%20Donation)!
