aph

README

aph
=====
Copyright 2020 Jordan Ocokoljic
Version 0.1.0, 7.6.2020

aph is a small command line tool that allows users to generate argon2id hashes
from the command line. It also includes utilities to measure how much time the
hash took to generate with the provided settings and the length of the
resulting as it would need to be stored in a database.

It allows users to be able to determine what parameters are safe to use on each
machine they may generate hashes on, as well as rougly gauging the performance
impact of the parameters they choose.


Usage
-------
When calling aph, you must provide the necessary parameters to use for the
generation of the hash. These are, the time, threads, memory and hash length.
For example:

aph 1s 2 64MB 32 mypassword

This call would generate a hash with the time parameter set to 1 second (the 
command line can also parse ms for milliseconds), the thread count parameter
set to 2 the memory parameter set to 64 megabytes (the command line can also
parse GB for gigabytes and KB for kilobytes), and a length of 32 bytes. The
basis of the hash is the final parameter "mypassword".

Optionally, a salt can be provided to be used in the hashing, rather than a
random salt being generated. For example:

aph 1s 2 64MB 32 mypassword mysalt

This call would use the salt "mysalt" when generating the hash.


Building
----------
To build aph, use the Go build command.

go build -o aph ./cmd

This will create an executable called aph.

Documentation

Index

• Variables
• func ParseMemory(stamp string) (int, error)
• func ParseTime(stamp string) (int, error)
• type ResultSet
  • func GenerateHash(seconds int, threads int, memory int, length int, key string) (ResultSet, error)
  • func GenerateHashWithSalt(seconds int, threads int, memory int, length int, key string, salt string) (ResultSet, error)

Variables

var (
	// ErrorMalformedStamp is returned by the Parse functions when the stamp
	// provided that doesn't match the format necessary for parsing.
	ErrorMalformedStamp = errors.New("aph: provided stamp was malformed")

	// ErrorSplitAtomic is returned by the Parse functions when the stamp
	// provided has a fractional value for an atomic type (KB or ms).
	ErrorSplitAtomic = errors.New("aph: cannot use fractional value with type")
)

Functions

func ParseMemory

func ParseMemory(stamp string) (int, error)

ParseMemory will take a string in the form of one of XKB, XMB, or XGB where X is a number. It will return the corresponding number of KB that the stamp represents or an error if the string is malformed.

func ParseTime

func ParseTime(stamp string) (int, error)

ParseTime will take a string in either Xs or Xms where X is an number. It will return the corresponding number of milliseconds that the time reprsents or an error if the string is malformed.

Types

type ResultSet

type ResultSet struct {
	Time       int
	Threads    int
	Memory     int
	Length     int
	Key        string
	Hash       string
	Characters int
	Duration   time.Duration
	Salt       string
}

ResultSet is a collection of information about the generation of a hash, it includes details such as how long generation took and what the overall size of the hash is.

func GenerateHash

func GenerateHash(
	seconds int,
	threads int,
	memory int,
	length int,
	key string,
) (ResultSet, error)

GenerateHash will generate a hash and store the details and result into a ResultSet and return the set.

func GenerateHashWithSalt

func GenerateHashWithSalt(
	seconds int,
	threads int,
	memory int,
	length int,
	key string,
	salt string,
) (ResultSet, error)

GenerateHashWithSalt will generate a hash and use the provided salt and store the details and result into a ResultSet and return the set.