sha224/README.md

A Javascript implementation of SHA-224 for Node.js.

# A _Node.js_ module for SHA-224

 This Javascript module implements the **SHA-224** cryptographic hash function designed by _the United States National Security Agency (NSA)_. **This module is a wrapper of [the `sha2` module](https://www.npmjs.com/package/sha2).**


## Installation ⤓

```
npm install sha224
```


## Usage

### Importing

 Import the module with

```javascript
const SHA224 = require("sha224");
```

### Available input types

 It basically takes a [`Buffer`](https://nodejs.org/api/buffer.html). Everything other than a [`Buffer`](https://nodejs.org/api/buffer.html) as its input turns into a [`Buffer`](https://nodejs.org/api/buffer.html) with `Buffer.from()` internally. Reading these would help you understand it:

- [`Buffer.from(string[, encoding])`](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_string_encoding)
- [`Buffer.from(arrayBuffer[, byteOffset[, length]])`](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_arraybuffer_byteoffset_length)
- [`Buffer.from(array)`](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_array)
- [`Buffer.from(object[, offsetOrEncoding[, length]])`](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_object_offsetorencoding_length)

```javascript
// SHA-224
const SHA224 = require("sha224");

// Input: "Green chá" in UTF-8.
console.log(SHA224("Green chá"));
console.log(SHA224("Green chá", "utf8"));
console.log(SHA224("477265656e206368c3A1", "hex"));
console.log(SHA224("R3JlZW4gY2jDoQ==", "base64"));
console.log(SHA224([
	0x47, 0x72, 0x65, 0x65, 0x6E, 0x20, 0x63, 0x68, 0xC3, 0xA1
]));
// All of them give `<Buffer 09 11 cc 3f 17 06 19 1a de 7b
// cb ad fa 95 14 28 f6 09 ca a2 f1 76 e5 f7 e4 fe d6 e7>`.

// Input: 0xC0FFEE.
console.log(SHA224(Buffer.from([0xC0, 0xFF, 0xEE])));
console.log(SHA224((new Uint8Array([0xC0, 0xFF, 0xEE])).buffer));
console.log(SHA224(
	(new Uint8Array([0xC0, 0x01, 0xC0, 0xFF, 0xEE])).buffer,
	2
));
console.log(SHA224("C0ffee", "hex"));
console.log(SHA224("wP/u", "base64"));
console.log(SHA224([0xC0, 0xFF, 0xEE]));
// All of them give `<Buffer 26 fb 46 cb 82 2b a8 2f 43 33
// 9c b2 47 ec d1 11 77 07 83 f5 72 a9 b9 a5 cf 34 cd 46>`.
```

### Working with the outputs

 It returns a `Buffer`, so you may do what you may do with a `Buffer`.

```javascript
// SHA-224
const SHA224 = require("sha224");

const nyanbuffer = SHA224(`
░░░░░░░▄▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▄░░░░░░
░░░░░░█░░▄▀▀▀▀▀▀▀▀▀▀▀▀▀▄░░█░░░░░
░░░░░░█░█░▀░░░░░▀░░▀░░░░█░█░░░░░
░░░░░░█░█░░░░░░░░▄▀▀▄░▀░█░█▄▀▀▄░
█▀▀█▄░█░█░░▀░░░░░█░░░▀▄▄█▄▀░░░█░
▀▄▄░▀██░█▄░▀░░░▄▄▀░░░░░░░░░░░░▀▄
░░▀█▄▄█░█░░░░▄░░█░░░▄█░░░▄░▄█░░█
░░░░░▀█░▀▄▀░░░░░█░██░▄░░▄░░▄░███
░░░░░▄█▄░░▀▀▀▀▀▀▀▀▄░░▀▀▀▀▀▀▀░▄▀░
░░░░█░░▄█▀█▀▀█▀▀▀▀▀▀█▀▀█▀█▀▀█░░░
░░░░▀▀▀▀░░▀▀▀░░░░░░░░▀▀▀░░▀▀░░░░
`);
console.log(nyanbuffer);
// <Buffer e9 2b e7 21 c9 22 10 0b c8 81 65 2a 63
// 11 c4 f9 29 03 76 68 05 e1 7f 1b d2 af 31 34>

console.log(nyanbuffer.toString("hex"));
// "e92be721c922100bc881652a6311c4f92903766805e17f1bd2af3134"

console.log(nyanbuffer.toString("base64"));
// "6SvnIckiEAvIgWUqYxHE+SkDdmgF4X8b0q8xNA=="

console.log(Array.from(nyanbuffer));
// [233, 43, 231, 33, 201, 34, 16, 11, 200, 129, 101, 42, 99, 17,
// 196, 249, 41, 3, 118, 104, 5, 225, 127, 27, 210, 175, 49, 52]

console.log(nyanbuffer.equals(nyanbuffer));
// true
```


## Warning ⚠️

### Hashing passwords

 Making a hash of a password with one of the algorithms of the SHA-2 family and keeping it, is **not recommended**.
For that purpose, use slow hash functions which are slow by design such as [PBKDF2](http://en.wikipedia.org/wiki/PBKDF2), [bcrypt](https://en.wikipedia.org/wiki/bcrypt), and [scrypt](http://www.tarsnap.com/scrypt.html), instead.

- [How to securely hash passwords? <sub>(_Information security Stack Exchange_)</sub>](https://security.stackexchange.com/a/31846/135187)
- [Salted Password Hashing - Doing it Right <sub>(_CrackStation_)</sub>](https://crackstation.net/hashing-security.htm)
- [How To Safely Store A Password <sub>(_Coda Hale_)</sub>](https://codahale.com/how-to-safely-store-a-password/)

### Hashing huge data

 [This module is not appropriate for hashing huge binary data](https://stackoverflow.com/questions/8974375/whats-the-maximum-size-of-a-node-js-buffer), such as that of a 1 GB file.


## Specification reference 📖

### [Request for Comments #6234<sup>(RFC 6234)</sup> <sub>‘US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)’</sub>](https://tools.ietf.org/html/rfc6234)

- **§1**: Overview of Contents.
- **§2**: Notation for Bit Strings and Integers.
- **§3**: Operations on Words.
- **§4**: Message Padding and Parsing.
- **§5**: Functions and Constants Used.
- **§6**: Computing the Message Digest.

written by _Donald E. Eastlake 3rd_, and _Tony Hansen_ in May 2011.

### [Federal Information Processing Standards Publication 180-4<sup>(FIPS PUB 180-4)</sup> <sub>‘Secure Hash Standard (SHS)’</sub>](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf)

- **§5.3.6**: SHA-512/t.

published by _National Institute of Standards and Technology (NIST)_ in August 2015.


## License 📜

 This Javascript module has been licensed under **the MIT license**.