Skip to content

Latest commit

 

History

History
61 lines (43 loc) · 3.16 KB

README.md

File metadata and controls

61 lines (43 loc) · 3.16 KB
Raw

Nimword

A mini password hashing collection

Run Tests

github pages

This package is a collection of functions for password hashing implemented by other packages, presented with a unified interface. It is currently only tested for Linux, but should work for Windows as well assuming the same libraries are installed.

Currently available hashing algorithms:

Installation

Install Nimword with Nimble:

$ nimble install -y nimword

Add Nimword to your .nimble file:

requires "nimword"

If you want to use argon2, ensure you have libsodium installed.

If you want to use pbkdf2, ensure you have OpenSSL version 1 or 3 installed

Basic usage

The following will work for every module:

let password: string = "my-super-secret-password"
let iterations: int = 3 # For Argon2 this is sensible, for pbkdf2 consider a number above 100.000
let encodedHash: string = hashEncodePassword(password, iterations)

assert password.isValidPassword(encodedHash) == true

Core-API

The core module of nimword provides the simple api of hashEncodePassword and isValidPassword:

  • hashEncodePassword: Proc to create base64 encoded hashes and further encodes them in a specific format that can be stored in e.g. a database and used with isValidPassword. Always takes the plain-text password, the algorithm to use for hashing and a number of iterations for the algorithm. Any further values needed by the algorithm will use sensible defaults. The salts for hashing will be generated and returned as part of the encoded string.
  • isValidPassword: Proc to validate if a given password is identical to the one that was used to create an encoded hash.

These core procs are also available in the individual modules for each algorithm, there hashEncodePassword may expose further options depending on the algorithm.

The individual algorithm-modules further provide 2 procs in case some customization is needed:

  • hashPassword: Proc to create unencoded raw hashes like hashEncodePassword, but returns the hash-bytes directly from there without turning it into a specific format like hashEncodePassword does.
  • encodeHash: Proc to generate strings of the format that hashEncodePassword outputs, but without doing any of the hashing itself. The output can be used with isValidPassword.

Running tests

You can run the tests either locally or in a container:

  • nimble test
  • nimble containerTest - This assumes you have docker and docker-compose installed