lambda_argon

README

Lambda Argon

Utilize the Argon2ID cryptographically secure hashing algorithm with parameters tuned specifically to run optimally on AWS Lambda.

Originally forked from github.com/alexedwards/argon2id but modified significantly to work optimally with AWS Lambda, cleanup test cases, and add new test cases.

Original README

This package provides a convenience wrapper around Go's argon2 implementation, making it simpler to securely hash and verify passwords using Argon2. It enforces use of the Argon2id algorithm variant and cryptographically-secure random salts.

How to Build locally

1. make build

How to Test locally

1. make test

How to Use

1. go get github.com/seantcanavan/lambda_argon@latest
2. import github.com/seantcanavan/lambda_argon
3. Steps for adding or updating a password for a user:
   1. Get the user password input from your lambda req: req.Body.password or req.QueryStringParameters["password"] or similar
   2. Hash the password to store in your database: hash, err := lambda_argon.Hash(password)
   3. Store the hash in your database: user.UpdatePassword(ctx, hash)
4. Steps for validating passwords / logging in for a user:
   1. Get the user password input from your lambda req: req.Body.password or req.QueryStringParameters["password"] or similar
   2. Get the hash for the user in your database: hash, err := user.GetHash(ctx, userID)
   3. Try to match the user input against the hash: match, err := lambda_argon.Match(password, hash)

Sample Login Lambda Handler Example

func LoginLambda(ctx context.Context, lambdaReq events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
	var loginReq LoginReq
	err := json.Unmarshal(lambdaReq.Body, &loginReq)
	if err != nil {
		return ERROR - internal server
	}

	adminByEmail, err := admin.GetByEmail(ctx, loginReq.Email)
	if err != nil {
		return ERROR - not found
	}

	// check if the password provided matches the hashed one saved in this admin
	match, err := lambda_argon.Match(loginReq.Password, adminByEmail.Password)
	if err != nil {
		return ERROR - bad request
	}

	// check if the password matches
	if !match {
		return ERROR - unauthorized
	}

	return SUCCESS
}

Sample Update Password Lambda Handler Example

func UpdatePasswordLambda(ctx context.Context, lambdaReq events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
	var updatePasswordReq UpdatePasswordReq
	err := json.Unmarshal(lambdaReq.Body, &updatePasswordReq)
	if err != nil {
		return ERROR - internal server
	}

    adminByEmail, err := admin.GetByEmail(ctx, loginReq.Email)
	if err != nil {
		return ERROR - not found
	}

	match, err := lambda_argon.Match(updatePasswordReq.Password, adminByEmail.Password)
	if err != nil {
		return ERROR - bad request
	}

	// check if the password matches
	if !match {
		return ERROR - unauthorized
	}

	hash, err := argon2id.Hash(updatePasswordReq.NewPassword)
	if err != nil {
		return ERROR - bad request
	}

	httpStatus, err = admin.SetPassword(ctx, adminById.ID, hash)
	if err != nil {
		return ERROR - conflict
	}

    return SUCCESS
}

Documentation

Overview

Package lambda_argon provides a convenient wrapper around Go's golang.org/x/crypto/argon2 implementation, making it simpler to securely hash and verify passwords using the Argon2id algorithm while running on AWS Lambda. Cryptographically-secure and randomized salts are used by default.

Index

• Constants
• Variables
• func Hash(password string) (string, error)
• func Match(password, hash string) (bool, error)

Constants

const MaxPasswordLength = 128

const MinPasswordLength = 12

Variables

var (
	ErrInvalidHashFormat        = errors.New("lambda_argon: invalid hash format")           // returned if the provided hash isn't in the expected format.
	ErrUnsupportedArgonVersion  = errors.New("lambda_argon: unsupported version of argon2") // returned if the provided hash was created using an unsupported variant of Argon2.
	ErrNonMatchingArgonVersions = errors.New("lambda_argon: argon2 versions do not match")  // returned if the provided hash was created using a different version of Argon2.
	ErrPasswordTooShort         = errors.New("lambda_argon: password is too short. Please see MinPasswordLength")
	ErrPasswordTooLong          = errors.New("lambda_argon: password is too long. Please see MaxPasswordLength")
)

Functions

func Hash

func Hash(password string) (string, error)

Hash accepts a string and hashes it using cryptographically-secure defaults. The secure hash is returned as a string and is secure to store inside your database. The hash contains the hash of the password as well as the hashing parameters used.

func Match

func Match(password, hash string) (bool, error)

Match compares a user password input against a known hash value to see if they're equal. The hash input should come from your database and the password input from the user.