The cl-diceware Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-diceware Reference Manual

This is the cl-diceware Reference Manual, version 1.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:14:24 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-diceware

This is a Common Lisp implementation of the Diceware passphrase generation algorithm.

You can find a description of the algorithm at http://diceware.com

MIT license in LICENSE, and at the bottom of source files.

It's a lot more effort to get cryptographically secure random numbers in Windows, so I didn't bother.

Pretty standard lisp package. System definition in cl-diceware.asd.

Tested in Clozure Common Lisp (CCL) and Steel Bank Common Lisp (SBCL).

Command-line script

The "diceware" file is a bash script to print passphrases in a shell.

;; Run in CCL (assuming "ccl" will start the lisp).
./diceware [<count>]

;; Run in SBCL
LISP=sbcl ./diceware [<count>]

;; Run in other lisp
LISP=whatever LISP_OPTIONS="--noprint options" ./diceware [<count>]

<count> defaults to 5. Non-integer , e.g. "-h" or "--help", prints help.

;; Use /dev/random instead of the default of /dev/urandom
;; (Or set CL_DICEWARE_REAL_RANDOM=t in your shell init file)
CL_DICEWARE_REAL_RANDOM=t ./diceware [<count>]

Function reference

All functions and variables below are exported from the cl-diceware package. Random bytes are fetched from /dev/random, except on Windows, where it uses cl:random.

with-/dev/random (&optional stream) &body body

A macro to bind an (unsigned-byte 8) stream to STREAM around the execution of BODY. Wrap calls to the RANDOM-xxx functions with this to prevent multiple opening and closing of /dev/random.

random-byte

Returns a random integer between 0 and 255 (inclusive).

random-integer limit

Returns a random integer >= 0 and < limit. Same as cl:random, but better randomness.

random-word

Returns a random word from the Diceware word list.

random-words count

Returns a list of COUNT random words from the Diceware word list.

random-words-string count

Returns a string containing COUNT random words, separated by spaces.

*real-random-p*

Variable controls whether to use /dev/random or /dev/urandom for random numbers. If true and not :USE-FEATURES, will use /dev/random, otherwise /dev/urandom. If EQ to :USE-FEATURES, will use /dev/random only if :CL-DICEWARE-REAL-RANDOM-P is in *FEATURES*. cl-diceware.asd pushes :CL-DICEWARE-REAL-RANDOM-P onto *FEATURES* if the CL_DICEWARE_REAL_RANDOM environment variable is non-blank.

Default: use /dev/urandom

Bill St. Clair <billstclair@gmail.com>
4 September 2015


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-diceware

Author

Bill St. Clair <bill@billstclair.com>

License

MIT

Description

Diceware in Lisp

Version

1.0

Source

cl-diceware.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-diceware.asd

Location

cl-diceware.asd

Systems

cl-diceware (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-diceware/package.lisp

Parent

cl-diceware (system)

Location

package.lisp

Packages

cl-diceware


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-diceware/random.lisp

Dependency

package.lisp (file)

Parent

cl-diceware (system)

Location

random.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-diceware/diceware-word-list.lisp

Dependency

random.lisp (file)

Parent

cl-diceware (system)

Location

diceware-word-list.lisp

Internal Definitions

*diceware-words* (special variable)


Previous: , Up: Lisp files   [Contents][Index]

3.1.5 cl-diceware/diceware.lisp

Dependency

diceware-word-list.lisp (file)

Parent

cl-diceware (system)

Location

diceware.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-diceware

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: with-/dev/random (&optional STREAM) &body BODY

Evaluate BODY with STREAM bound to a binary input stream to /dev/random.

Package

cl-diceware

Source

random.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: random-byte ()

Return one random byte.

Package

cl-diceware

Source

random.lisp (file)

Function: random-integer LIMIT

Return a random integer >= 0 and < limit. Same as ‘cl:random’, but better randomness.

Package

cl-diceware

Source

random.lisp (file)

Function: random-word ()

Return a random Diceware word.

Package

cl-diceware

Source

diceware.lisp (file)

Function: random-words COUNT

Return a list of COUNT random Diceware words.

Package

cl-diceware

Source

diceware.lisp (file)

Function: random-words-string &optional COUNT

Return a string containing COUNT random Diceware words, separated by spaces. COUNT default to 5.

Package

cl-diceware

Source

diceware.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: */dev/random-stream*
Package

cl-diceware

Source

random.lisp (file)

Special Variable: *diceware-hash*
Package

cl-diceware

Source

diceware.lisp (file)

Special Variable: *diceware-words*
Package

cl-diceware

Source

diceware-word-list.lisp (file)

Special Variable: *real-random-p*

Control whether we use /dev/random or /dev/urandom. See documentation for ‘real-random-p’.

Package

cl-diceware

Source

random.lisp (file)

Special Variable: *remainder*
Package

cl-diceware

Source

random.lisp (file)

Special Variable: *remainder-bits*
Package

cl-diceware

Source

random.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: with-shift-in &body BODY
Package

cl-diceware

Source

random.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: %random-bits COUNT S
Package

cl-diceware

Source

random.lisp (file)

Function: %random-byte S
Package

cl-diceware

Source

random.lisp (file)

Function: %shift-in ACCUM FIX-ACCUM FIX-ACCUM-BITS FIX-ACCUM-SIZE VALUE BITS
Package

cl-diceware

Source

random.lisp (file)

Function: %shift-value ACCUM FIX-ACCUM FIX-ACCUM-BITS
Package

cl-diceware

Source

random.lisp (file)

Function: /dev/random-path ()
Package

cl-diceware

Source

random.lisp (file)

Function: call-with-/dev/random THUNK

Helper function for ‘with-dev/random’.

Package

cl-diceware

Source

random.lisp (file)

Function: diceware-gethash KEY

Get the Diceware word for KEY, which should be a five-digit (base 10) integer, with digits from 1 to 6.

Package

cl-diceware

Source

diceware.lisp (file)

Function: init-diceware-hash ()

Initialize and return ‘*diceware-hash*’.

Package

cl-diceware

Source

diceware.lisp (file)

Function: maybe-init-diceware-hash ()

Initialize ‘*diceware-hash*’, if its null, and return it.

Package

cl-diceware

Source

diceware.lisp (file)

Function: random-bits COUNT

Return an integer containing COUNT random bits.

Package

cl-diceware

Source

random.lisp (file)

Function: random-diceware-key ()

Compute a random Diceware key, a five-digit (base 10) integer with digits from 1 to 6.

Package

cl-diceware

Source

diceware.lisp (file)

Function: real-random-p ()

True if ‘*real-random-p*’ is true or ‘*real-random-p*’ is :USE-FEATURES and :CL-DICEWARE-REAL-RANDOM is on ‘*features*’, which it will be if
you load cl-diceware.asd with a non-null value for the CL_DICEWARE_REAL_RANDOM environment variable.

Package

cl-diceware

Source

random.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-diceware.asd: The cl-diceware<dot>asd file
cl-diceware/diceware-word-list.lisp: The cl-diceware/diceware-word-list<dot>lisp file
cl-diceware/diceware.lisp: The cl-diceware/diceware<dot>lisp file
cl-diceware/package.lisp: The cl-diceware/package<dot>lisp file
cl-diceware/random.lisp: The cl-diceware/random<dot>lisp file

F
File, Lisp, cl-diceware.asd: The cl-diceware<dot>asd file
File, Lisp, cl-diceware/diceware-word-list.lisp: The cl-diceware/diceware-word-list<dot>lisp file
File, Lisp, cl-diceware/diceware.lisp: The cl-diceware/diceware<dot>lisp file
File, Lisp, cl-diceware/package.lisp: The cl-diceware/package<dot>lisp file
File, Lisp, cl-diceware/random.lisp: The cl-diceware/random<dot>lisp file

L
Lisp File, cl-diceware.asd: The cl-diceware<dot>asd file
Lisp File, cl-diceware/diceware-word-list.lisp: The cl-diceware/diceware-word-list<dot>lisp file
Lisp File, cl-diceware/diceware.lisp: The cl-diceware/diceware<dot>lisp file
Lisp File, cl-diceware/package.lisp: The cl-diceware/package<dot>lisp file
Lisp File, cl-diceware/random.lisp: The cl-diceware/random<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   /  
C   D   F   I   M   R   W  
Index Entry  Section

%
%random-bits: Internal functions
%random-byte: Internal functions
%shift-in: Internal functions
%shift-value: Internal functions

/
/dev/random-path: Internal functions

C
call-with-/dev/random: Internal functions

D
diceware-gethash: Internal functions

F
Function, %random-bits: Internal functions
Function, %random-byte: Internal functions
Function, %shift-in: Internal functions
Function, %shift-value: Internal functions
Function, /dev/random-path: Internal functions
Function, call-with-/dev/random: Internal functions
Function, diceware-gethash: Internal functions
Function, init-diceware-hash: Internal functions
Function, maybe-init-diceware-hash: Internal functions
Function, random-bits: Internal functions
Function, random-byte: Exported functions
Function, random-diceware-key: Internal functions
Function, random-integer: Exported functions
Function, random-word: Exported functions
Function, random-words: Exported functions
Function, random-words-string: Exported functions
Function, real-random-p: Internal functions

I
init-diceware-hash: Internal functions

M
Macro, with-/dev/random: Exported macros
Macro, with-shift-in: Internal macros
maybe-init-diceware-hash: Internal functions

R
random-bits: Internal functions
random-byte: Exported functions
random-diceware-key: Internal functions
random-integer: Exported functions
random-word: Exported functions
random-words: Exported functions
random-words-string: Exported functions
real-random-p: Internal functions

W
with-/dev/random: Exported macros
with-shift-in: Internal macros

Jump to:   %   /  
C   D   F   I   M   R   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*/dev/random-stream*: Internal special variables
*diceware-hash*: Internal special variables
*diceware-words*: Internal special variables
*real-random-p*: Internal special variables
*remainder*: Internal special variables
*remainder-bits*: Internal special variables

S
Special Variable, */dev/random-stream*: Internal special variables
Special Variable, *diceware-hash*: Internal special variables
Special Variable, *diceware-words*: Internal special variables
Special Variable, *real-random-p*: Internal special variables
Special Variable, *remainder*: Internal special variables
Special Variable, *remainder-bits*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-diceware: The cl-diceware system
cl-diceware: The cl-diceware package

P
Package, cl-diceware: The cl-diceware package

S
System, cl-diceware: The cl-diceware system

Jump to:   C   P   S