The secure-random Reference Manual

Table of Contents

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

The secure-random Reference Manual

This is the secure-random Reference Manual, version 0.1.0, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 15:42:54 2018 GMT+0.


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

1 Introduction

Overview.
~~~~~~~~~

secure-random provides a cryptographically secure pseudo-random 
number generator (CSPRNG) for Common Lisp.

Example: (SECURE-RANDOM:NUMBER 10) => 9

We define an abstract interface for CSPRNG and provide a default 
implementation of that interface.

The library API.
~~~~~~~~~~~~~~~~

Class SECURE-RANDOM:GENERATOR. 
      The base class for all the possible implementations 
      of a secure random number generator.

Special variable SECURE-RANDOM:*GENERATOR*.
      Current value of the random number generator. Used as 
      the default value for the library functions parameter GENERATOR.

Generic function BYTES (COUNT GENERATOR) => random bytes.
      The only generic function which needs to be implemented 
      by a subclass of SECURE-RANDOM:GENERATOR. Generates COUNT 
      cryptographically strong pseudo-random bytes using the random 
      number generator GENERATOR. Returns the bytes as a SIMPLE-ARRAY 
      with ELEMENT-TYPE '(UNSIGNED-BYTE 8). Signals an ERROR in case 
      of problems (for example when the random number generator 
      failed to initialize itself with enough entrophy).

Function NUMBER (LIMIT &optional (GENERATOR *GENERATOR*)) => random number.
      Returns a cryptographically strong pseudo-random number that 
      is a non-negative number less than LIMIT and of the same 
      type as LIMIT (in the current implementation, only INTEGER 
      type is supporeted). LIMIT is a positive number. GENERATOR is an 
      instance of a subclass of the SECURE-RANDOM:GENERATOR. Signals 
      an ERROR in case of problems (for example when the random 
      number generator failed to initialize itself with enough entrophy).

Implementation notes.
~~~~~~~~~~~~~~~~~~~~~

The default implementation uses OpenSSL random number generator (via cl+ssl
library). We started from the OpenSSL usage because it's the simplest way.

Implementation of a pure Common Lisp CSPRNG is desirable, but it would 
require to write much more code. The problem is not in the CSPRNG algorithms 
themself, which are relatively simple (just read for example the Wikipedia article, 
and use Ironclad for the required building blocks). But the problem is in 
initialization of CSPRNG. Any CSPRNG needs to be initialized by some unguessable 
value. OpenSSL can gather the initial value from a platform specific service 
(/dev/random on Unix'es where it present, Windows Crypto API, 
Entropy Gathering Daemon, etc.). The pure Lisp CSPRNG library would need to 
re-implement all this code for gathering a truly unguessable initial value.

Contact.
~~~~~~~~

Send questions or comments to avodonosov@yandex.ru


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 secure-random

Author

Anton Vodonosov <avodonosov@yandex.ru>

License

MIT

Description

Cryptographically secure pseudo-random number generator for Common Lisp

Version

0.1.0

Dependency

cl+ssl

Source

secure-random.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 secure-random.asd

Location

secure-random.asd

Systems

secure-random (system)


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

3.1.2 secure-random/package.lisp

Parent

secure-random (system)

Location

package.lisp

Packages

secure-random


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

3.1.3 secure-random/secure-random.lisp

Dependency

package.lisp (file)

Parent

secure-random (system)

Location

secure-random.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 secure-random

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 Special variables

Special Variable: *generator*
Package

secure-random

Source

secure-random.lisp (file)


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

5.1.2 Functions

Function: number LIMIT &optional GENERATOR

Returns a cryptographically strong pseudo-random number that is a non-negative number less than LIMIT and of the same type as LIMIT (in the current implementation, only INTEGER type is supporeted). LIMIT is a positive number. GENERATOR is an instance of a
subclass of the SECURE-RANDOM:GENERATOR. Signals an ERROR in case of problems (for example when the random number generator has not been initialized with enough entrophy).

Package

secure-random

Source

secure-random.lisp (file)


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

5.1.3 Generic functions

Generic Function: bytes COUNT GENERATOR

The only generic function which needs to be implemented by a subclass
of SECURE-RANDOM:GENERATOR. Generates COUNT cryptographically strong pseudo-random bytes using the random number generator GENERATOR. Returns the bytes as a SIMPLE-ARRAY with ELEMENT-TYPE ’(UNSIGNED-BYTE 8). Signals
an ERROR in case of problems (for example when the random number
generator has not been initialized with enough entrophy).

Package

secure-random

Source

secure-random.lisp (file)

Methods
Method: bytes COUNT (GENERATOR open-ssl-generator)

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

5.1.4 Classes

Class: generator ()

The base class for all the possible implementations of secure random number generator.

Package

secure-random

Source

secure-random.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

open-ssl-generator (class)


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

5.2 Internal definitions


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

5.2.1 Functions

Function: octets-to-integer OCTETS-VEC
Package

secure-random

Source

secure-random.lisp (file)


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

5.2.2 Classes

Class: open-ssl-generator ()
Package

secure-random

Source

secure-random.lisp (file)

Direct superclasses

generator (class)

Direct methods

bytes (method)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, secure-random.asd: The secure-random<dot>asd file
File, Lisp, secure-random/package.lisp: The secure-random/package<dot>lisp file
File, Lisp, secure-random/secure-random.lisp: The secure-random/secure-random<dot>lisp file

L
Lisp File, secure-random.asd: The secure-random<dot>asd file
Lisp File, secure-random/package.lisp: The secure-random/package<dot>lisp file
Lisp File, secure-random/secure-random.lisp: The secure-random/secure-random<dot>lisp file

S
secure-random.asd: The secure-random<dot>asd file
secure-random/package.lisp: The secure-random/package<dot>lisp file
secure-random/secure-random.lisp: The secure-random/secure-random<dot>lisp file

Jump to:   F   L   S  

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

A.2 Functions

Jump to:   B   F   G   M   N   O  
Index Entry  Section

B
bytes: Exported generic functions
bytes: Exported generic functions

F
Function, number: Exported functions
Function, octets-to-integer: Internal functions

G
Generic Function, bytes: Exported generic functions

M
Method, bytes: Exported generic functions

N
number: Exported functions

O
octets-to-integer: Internal functions

Jump to:   B   F   G   M   N   O  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*generator*: Exported special variables

S
Special Variable, *generator*: Exported special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   C   G   O   P   S  
Index Entry  Section

C
Class, generator: Exported classes
Class, open-ssl-generator: Internal classes

G
generator: Exported classes

O
open-ssl-generator: Internal classes

P
Package, secure-random: The secure-random package

S
secure-random: The secure-random system
secure-random: The secure-random package
System, secure-random: The secure-random system

Jump to:   C   G   O   P   S