philippmdoerner / nimword

A simple library with a simple interface to do password hashing with different algorithms

Nimword

A mini password hashing collection

• API index

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:

• PBKDF2 - HMAC with SHA256 from openssl
• PBKDF2 - HMAC with SHA512 from openssl
• Argon2 from libsodium

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

nimword's Issues

Add bcrypt support

So far only pbkdf2 and argon are supported.

A new module under src/nimword could be added to provide a module with the following procs for bcrypt support:

proc hashEncodePassword*(password: string, iterations: int, <whatever optional additional parameters>): string
proc isValidPassword*(password: string, encodedHash: string): bool

proc hashPassword*( <whatever parameters>): string
proc encodeHash*( <whatever parameters>): string

Where:

1. hashPassword is the core hashing proc that hashes a password with scrypt and has whatever parameters it needs
2. encodeHash is a way to encode the output of bcrypt into a string that can be stored in a db and be used with isValidPassword
3. hashEncodePassword a way to call 1) and 2) together for convenience
4. isValidPassword to be able to validate whether a given clear-text password when hashed equal the hash included somewhere within the output of encodeHash

That module should also touch nimword.nim in order to include bcrypt into the overarching hashEncodePassword and isValidPassword procs there.

Add support for scrypt

So far only pbkdf2 and argon are supported.

A new module under src/nimword could be added to provide a module with the following procs:

proc hashEncodePassword*(password: string, iterations: int, <whatever optional additional parameters>): string
proc isValidPassword*(password: string, encodedHash: string): bool

proc hashPassword*( <whatever parameters>): string
proc encodeHash*( <whatever parameters>): string

Where:

1. hashPassword is the core hashing proc that hashes a password with scrypt and has whatever parameters it needs
2. encodeHash is a way to encode the output of scrypt into a string that can be stored in a db and be used with isValidPassword
3. hashEncodePassword a way to call 1) and 2) together for convenience
4. isValidPassword to be able to validate whether a given clear-text password when hashed equal the hash included somewhere within the output of encodeHash

That module should also touch nimword.nim in order to include scrypt into the overarching hashEncodePassword and isValidPassword procs there.

Refactor input/output API

As recommended by mratsim for better practicces:

1. Change the API of each hashPassword to return seq[byte]
2. Change the input to be a type Password = distinct string, write a converter that auto-converts string to Password

The purpose of having the distinct Password type is to make it harder to accidentally print/echo it.
Export the Password type as well.

not compat with {.gcsafe.}?

hi,
I'm trying to use nimword with Guildenstern and my program won't compile . It seems to me that it's breaking the {.gcsafe.} from Guildenstern.
thanks