crypit

The crypit package is a simple, fast, and secure cryptographic library. It is made to help you write secure applications, without using complex libraries (which can be really easy to mess up with).

Features

• Unique identification generators (microsecond precision)
• Secure random number generation
• Hashing functions

Installation

$ npm install crypit --save

Initialization

The main crypit class must be constructed before you can run any of crypit's methods.

const crypit = new (require('crypit'))();
// ... or if you don't want it to look horrible ...
const Crypit = require('crypit');
const crypit = new Crypit();

Table of Contents

• 🚩 Examples - Start here!
• Unique identifiers
  • Short UIDs - Generate short unique identifiers
  • Secure UIDs - Generate secure unique identifiers
  • Hashed UIDs - Hashed secure unique identifiers
• Singly-unique identifiers
  • Short SUIDs - Generate short singly-unique identifiers
  • Secure SUIDs - Generate secure singly-unique identifiers
  • Hashed SUIDs - Hashed secure singly-unique identifiers
• Password hashing
  • Hash a password - Hash a password
  • Verify a hash - Verify a crypit password hash
• Message digests
  • ⚠️ MD5 - Hash a string with MD5
  • ⚠️ SHA-1 - Hash a string with SHA-1
  • SHA-256 - Hash a string with SHA-256
  • SHA-384 - Hash a string with SHA-384
  • SHA-512 - Hash a string with SHA-512
• Randomness generators
  • Integer - Generate a random integer
  • String - Generate a random string using the given charset
  • Buffer - Generate a buffer filled with random bytes
  • Hexadecimal - Generate a random hexadecimal string
  • Base64 - Generate a random base64 string
  • Binary - Generate a string full of random binary values
• More information
  • UIDs v. SUIDs: What's the difference?
  • Why you should hash passwords
  • Why using MD5 or SHA-1 is such a bad idea

Examples

Generating a unique ID for a user

⚠️ This method is not cryptographically secure. Do not use it for anything that must not be in any way guessable by any party.

crypit.id.unique.short() // 5snoz116482wn23t3a

Generating a token for a user

crypit.id.unique.hashed() // da5a43ca44a0d5a864ecb6dff1093d3d00c19e40e3d894b505ca3f5616829107fcb368628bc1a9003beade593d0a3390

Hashing a user's password

// -> user sends their password ({password}) to your server
let hash = await crypit.hash.password.hash(password);
// -> your server stores the hash to a database

Verifying a user's password

// -> user sends their password ({password}) to your server
// -> your server fetches the hash ({hash}) from the database
let isValid = await crypit.hash.password.verify(password, hash);
// -> if true is returned, the password is correct

Unique identifiers

short(options?)

Generates a short-ish, unique identifier. This uses one of your system's MAC addresses, the process's PID, and the current timestamp (in microseconds, not milliseconds).

⚠️ This method is not cryptographically secure. Do not use it for anything that must not be in any way guessable by any party.

Example

crypit.id.unique.short() // 5snoz116482wn23t3a

secure(options?)

Generates a secure unique identifier. This uses one of your system's MAC addresses, the process's PID, and the current timestamp (in microseconds, not milliseconds) to make it random cross-machine/cross-process, and also adds a cryptographically secure random value to it.

Options

• count: The length of the random value. Defaults to 12.

Example

crypit.id.unique.secure() // 5snoz2922wpzvzl7478f85e3237aafb5e321b0fb

hashed(options?)

Generates a secure unique identifier, and then hashes it using SHA-384. This uses one of your system's MAC addresses, the process's PID, and the current timestamp (in microseconds, not milliseconds) to make it random cross-machine/cross-process, and also adds a cryptographically secure random value to it.

Options

• count: The length of the random value. Defaults to 16.

Example

crypit.id.unique.hashed() // da5a43ca44a0d5a864ecb6dff1093d3d00c19e40e3d894b505ca3f5616829107fcb368628bc1a9003beade593d0a3390

Singly-unique identifiers

short(options?)

Generates a tiny unique identifier that is only unique to this machine and process. This uses the current timestamp (in microseconds, not milliseconds).

⚠️ This method is not cryptographically secure. Do not use it for anything that must not be in any way guessable by any party.

Example

crypit.id.single.short() // 2wviurtn

secure(options?)

Generates a secure unique identifier that is only unique to this machine and process. This uses the current timestamp (in microseconds, not milliseconds), and also adds a cryptographically secure random value to it.

Options

• count: The length of the random value. Defaults to 12.

Example

crypit.id.single.secure() // 2wwvu0z1ed8e5faf9e4d92bc19ad5a0d

hashed(options?)

Generates a secure unique identifier that is only unique to this machine and process, and then hashes it using SHA-256. This uses the current timestamp (in microseconds, not milliseconds), and also adds a cryptographically secure random value to it.

Options

• count: The length of the random value. Defaults to 16.

Example

crypit.id.single.hashed() // c3e8ce20bd34556a27c343033a8b9c350fe9c915d1abe47403b63745bac60410

Password hashing

hash(password, options?)

Hashes a password and returns a crypit string that can be verified with verify().

Options

• iterations: The number of times to itterate the hash. Increasing this value can increase security, but at a cost of performence. Defaults to 3.
• saltLength: The length of the salt. Defaults to 16.
• algorithm: The algorithm to use. Can be sha256, sha384, or sha512 (SHA-1 and MD5 are not supported due to security concerns). Defaults to sha384.

Example

await crypit.hash.password.hash('password') // $crypit;...
// ... or if you need a synchronous version ...
crypit.hash.password.hashSync('password') // $crypit;...

verify(password, hash)

Verifies a crypit hash string generated by hash() against a password.

Example

await crypit.hash.password.verify('password', '$crypit;...') // true
// ... or if you need a synchronous version ...
crypit.hash.password.verifySync('password', '$crypit;...') // true

Message digests

md5.hash(string)

Hashes a string with MD5¹.

⚠️ This method is not cryptographically secure. Multiple vulnerabilities have been found in the MD5 hashing algorithm. Consider using SHA-256 instead.

Example

await crypit.hash.md.md5.hash('wew')
// ... or if you need a synchronous version ...
crypit.hash.md.md5.hashSync('wew')

sha1.hash(string)

Hashes a string with SHA-1¹.

⚠️ This method is not cryptographically secure. Multiple vulnerabilities have been found in the SHA-1 hashing algorithm. Consider using SHA-256 instead.

Example

await crypit.hash.md.sha1.hash('wew')
// ... or if you need a synchronous version ...
crypit.hash.md.sha1.hashSync('wew')

sha256.hash(string)

Hashes a string with SHA-256¹.

Example

await crypit.hash.md.sha256.hash('wew')
// ... or if you need a synchronous version ...
crypit.hash.md.sha256.hashSync('wew')

sha384.hash(string)

Hashes a string with SHA-384¹.

Example

await crypit.hash.md.sha384.hash('wew')
// ... or if you need a synchronous version ...
crypit.hash.md.sha384.hashSync('wew')

sha512.hash(string)

Hashes a string with SHA-512¹.

Example

await crypit.hash.md.sha512.hash('wew')
// ... or if you need a synchronous version ...
crypit.hash.md.sha512.hashSync('wew')

Randomness generators

int(min?, max?)

Generates a random integer between min and max. If min is not specified, it defaults to 0. If max is not specified, it defaults to 1.

Example

crypit.random.int(0, 10) // 3

string(length, charset?)

Generates a random string using the charset provided. If no charset is provided, it defaults to abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.

Example

crypit.random.string(8) // Q9wBkxs1

bytes(length)

Generates a buffer of random bytes.

Example

crypit.random.buffer(18) // <Buffer 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18>

hex(length)

Generates a string full of random hexadecimal characters.

Example

crypit.random.hex(8) // 0a0b0c0d0e0f10

base64(length)

Generates a string full of random base64 characters.

Example

crypit.random.base64(8) // aGVsbG8gd29ybGQ=

binary(length)

Generates a string full of random binary values.

Example

crypit.random.binary(4) // 10101010101010101010101010101010

More Information

UIDs v. SUIDs: What's the difference?

A UID (or a unique identifier) is an ID that is unique cross-machine and cross-process. In crypit, it uses a highly-precise time (in microseconds, not milliseconds) to make it unique. On the other hand, a SUID (or a single-unique identifier) is an ID that is only unique to the process (and machine) it is generated on.

Why you should hash passwords

Hashing a password is a very important security measure. It is a way to make sure that a password is not stored in plain text. This is important. Imagine if your database was hacked, and you stored passwords in plain text. Now, tons of email and password combinations are out there, in the wild. Hashing passwords protects your users, and should always be done, even if you're a small company, even if you don't think you're a target.

Why using MD5 or SHA-1 is such a bad idea

To put it simply, the security of the MD5 hashing algorithm is severely compromised: it is not cryptographically secure as a collision attack exists which can find hash collisions in seconds, even on mediocre hardware. SHA-1 on the other hand is simply outdated. Its length is its disadvantage (in more ways than one: collisions have been found), and it is no longer seen as cryptographically secure.

The crypit library does not support SHA-1 or MD5 due to these security concerns. Upgrading to SHA-256 or higher is worth it.

Dependencies

The crypit library depends on the following libraries:

• node-forge for cryptographic functions

License

Copyright (c) 2021, Chargeless and contributors

https://github.com/Chargeless/crypit

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

 
 

¹ Directly calls node-forge methods for you.