passphrase

README

Passphrase

Better passwords by combining random words.

Passphrase is a Go library, command-line interface, Google App Engine application and AWS Lambda function to generate a random sequence of words.

It is inspired by Randall Munroe's xkcd webcomic #936 with the title "Password Strength":

Installation

The passphrase command-line interface can be installed via go get:

go get github.com/blueimp/passphrase/passphrase

Usage

By default, passphrase prints four space-separated words, but also accepts an argument for the number of words to generate:

passphrase [number]

The concurrency limit for random number generation (default: 128) can be adjusted with the environment variable PASSPHRASE_MAX_WORKER_COUNT:

PASSPHRASE_MAX_WORKER_COUNT=1000 passphrase 1000

Import

The passphrase library can be imported and used with any type implementing the io.Writer interface, e.g. os.Stdout:

package main

import (
	"fmt"
	"os"

	"github.com/blueimp/passphrase"
)

var exit = os.Exit

func main() {
	_, err := passphrase.Write(os.Stdout, 4)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		exit(1)
	}
	fmt.Println()
}

Or alternatively with a simple string return value:

package main

import (
	"fmt"
	"os"

	"github.com/blueimp/passphrase"
)

var exit = os.Exit

func main() {
	pass, err := passphrase.String(4)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		exit(1)
	}
	fmt.Println(pass)
}

Word list

This repository includes the word list google-10000-english-usa-no-swears.txt from Josh Kaufman's repository google-10000-english, but passphrase can also be compiled with another list of newline separated words.

The words module can be generated the following way:

WORD_LIST_URL=words.txt MIN_WORD_LENGTH=3 make words

The WORD_LIST_URL variable can point to a URL or a local file path and falls back to words.txt.

Words shorter than MIN_WORD_LENGTH (defaults to a minimum word length of 3 characters) are filtered out.

The updated word list module can then be used in a new build.

Build

First, clone the project and then switch into its source directory:

git clone https://github.com/blueimp/passphrase.git
cd passphrase

Please note:
This project relies on Go modules for automatic dependency resolution.

To build the CLI binary, run Make in the repository:

make

The locally built binary can be installed at $GOPATH/bin/passphrase with the following command:

make install

The uninstall command removes the binary from $GOPATH/bin/passphrase:

make uninstall

To clean up all build artifacts, run the following:

make clean

Test

All components come with unit tests, which can be executed the following way:

make test

Google App Engine

Passphrase can be deployed as Google App Engine application.

The application accepts a query parameter n to define the number of words to generate, but limits the sequence to 100 words, e.g.:

https://PROJECT.appspot.com/?n=100

Requirements

App engine development and deployment requires the Google Cloud SDK with the app-engine-go component.

On MacOS, google-cloud-sdk can be installed via Homebrew Cask.

brew cask install google-cloud-sdk
gcloud components install app-engine-go

To make dev_appserver.py available in the PATH, a symlink has to be added:

ln -s /usr/local/Caskroom/google-cloud-sdk/latest/google-cloud-sdk/bin/dev_* \
	/usr/local/bin/

The local watch task requires entr to be installed, which is available in the repositories of popular Linux distributions and can be installed on MacOS via Homebrew:

brew install entr

Environment variables

The following variables have to be set, e.g. by adding them to a .env file, which gets included in the provided Makefile:

# The App Engine project:
PROJECT=passphrasebot
# The App Engine project version:
VERSION=1

Deploy

To deploy the application, execute the following:

make deploy

To open the URL of the application in a browser tab, run the following:

make browse

Local development

To start a local App Engine server, run the following:

make start

On MacOS, to also automatically reload the active Chrome/Safari/Firefox tab, run the following:

[BROWSER=chrome|safari|firefox] make watch

AWS Lambda

Passphrase can be deployed as AWS lambda function with an API Gateway triggger.

The function accepts a query parameter n to define the number of words to generate, but limits the sequence to 100 words, e.g.:

https://API_GW_ID.execute-api.REGION.amazonaws.com/Prod?n=100

Requirements

Deployment requires the AWS CLI as well as aws-vault for secure credentials access.
Alternatively, it's also possible to reset the wrapped aws CLI command by exporting AWS_CLI=aws as environment variable.

Local invocations require AWS SAM Local.

The local watch task requires entr to be installed, which is available in the repositories of popular Linux distributions and can be installed on MacOS via Homebrew:

brew install entr

Environment variables

The following variables have to be set, e.g. by adding them to a .env file, which gets included in the provided Makefile:

# Platform to use for local development and deployment (appengine or lambda):
PLATFORM=lambda
# The AWS profile to use for aws-vault:
AWS_PROFILE=default
# The S3 bucket where the lambda package can be uploaded:
DEPLOYMENT_BUCKET=example-bucket
# The S3 object prefix for the lambda package:
DEPLOYMENT_PREFIX=passphrase
# The CloudFormation stack name:
STACK_NAME=passphrase
# The name of an existing IAM role for AWS Lambda with
# AWSLambdaBasicExecutionRole attached:
LAMBDA_ROLE=arn:aws:iam::000000000000:role/aws-lambda-basic-execution-role
# The AWS service region, required to construct the API Gateway URL:
AWS_REGION=eu-west-1

Build

To build the AWS Lambda function binary, run the following:

make lambda

Deploy

To package and deploy the function, execute the following:

make deploy

After the deployment succeeds, the API Gateway URL is printed.

This URL can also be retrieved later with the following command:

make url

To remove the AWS Lambda function and API Gateway configuration, execute the following:

make destroy

Local development

Using AWS SAM Local, the function can also be invoked and served locally.

A sample API Gateway event can be generated the following way:

make event

To invoke the function locally, execute the following:

make invoke

To start the local API Gateway along with a watch process for source file changes, run the following:

[BROWSER=chrome|safari|firefox] make watch

The watch task recompiles the lambda binary on changes.
On MacOS, it also automatically reloads the active Chrome/Safari/Firefox tab.

License

Released under the MIT license.

Documentation

Overview

Code generated by go generate; DO NOT EDIT. This file was auto-generated at 2018-11-17 22:46:09.610588 +0100 CET m=+0.002312625 using data from words.txt.

Index

• Variables
• func String(numberOfWords int) (str string, err error)
• func Write(writer io.Writer, numberOfWords int) (n int, err error)

Variables

var MaxWorkerCount = 128

MaxWorkerCount sets the concurrency limit for random number generation.

var MinWordLength = 3

MinWordLength defines the minimum length for the individual passphrase words.

var Words = [...]string{}/* 9467 elements not displayed */

Words is the list of strings used for the random passphrase generation.

Functions

func String

func String(numberOfWords int) (str string, err error)

String returns a passphrase with the given number of words.

func Write

func Write(writer io.Writer, numberOfWords int) (n int, err error)

Write writes a passphrase with the given number of words.