The cl-one-time-passwords Reference Manual

Table of Contents

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

The cl-one-time-passwords Reference Manual

This is the cl-one-time-passwords Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:27:32 2018 GMT+0.


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

1 Introduction

Introduction

One time passwords provide a way to do authentication based on a shared secret without revealing that secret to spies on the communciation channel.

Two well specified ways of generating OTPs are:

These are commonly used as one factor in two factor authentication systems. For example Google uses these. For example Google's Authenticator App for most smart phones will generate one time passwords once it has been configured with the shared secret(s) for your account(s).

Cl-one-time-passwords implements HOTP and TOTP in Common Lisp.

Example

  1. Load the code into your lisp image.

  2. Share a secret with Google's Authenticator App on your smart phone by scanning this QDR code:
    QR Code

  3. Compair the values that Authenticator is generating with the ones this code generates:

  (totp:totp "48656C6C6F21DEADBEEF48656C6C6F21DEADBEEF")

They ought to be the same, but if your phone and computer clock are out of sync by a N seconds then every 30 seconds for N seconds they won't be the same.

That QR encodes this URL otpauth://totp/test@example.com?secret=jbswy3dpehpk3pxpjbswy3dpehpk3pxp where the secret is the base32 encoding of the secret we passed to totp:totp in step 3, there the value was a 40 character hex number, i.e. 20 bytes.

API

hotp:*digits*

The number of digits to return in the htop values, defaults to six. See the RFC for details.

hotp:*hmac-sha-mode*

The kind of hmac to use. This defaults to :sha1. You can set other values ironclad supports; but my testing currrently indicates it doesn't work. This isn't part of the HOTP spec, but the TOTP spec extends HOTP ... even if nobody usest this extension.

(hotp:hotp <secret> <counter>)

is a string of 20 characters hex digits; more if your using a different hmac sha.

totp:*time-zero*

Defaults to zero, a unix time. See the RFC for details.

totp:*time-step-in-seconds*

Defaults to 30, a unix time interval. See the RFC for details.

(totp:totp <secret> &optional offset unix-time)

as in hotp:hotp. The offset defaults to zero. The unix-time defaults to the current unix-time. The offset is used to get totp values nearby times slots, it is in seconds.

See also:

Warning

This code as not yet been used in production. I look forward to reports back from the field. :)


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-one-time-passwords

Author

Ben Hyde <bhyde@pobox.com>

License

Apache 2.0

Description

One time passwords (hotp rfc4226, totp rfc6238) as used in two factor authentication systems such as Google’s.

Dependency

ironclad

Source

cl-one-time-passwords.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-one-time-passwords.asd

Location

cl-one-time-passwords.asd

Systems

cl-one-time-passwords (system)


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

3.1.2 cl-one-time-passwords/packages.lisp

Parent

cl-one-time-passwords (system)

Location

packages.lisp

Packages

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

3.1.3 cl-one-time-passwords/hotp.lisp

Dependency

packages.lisp (file)

Parent

cl-one-time-passwords (system)

Location

hotp.lisp

Exported Definitions
Internal Definitions

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

3.1.4 cl-one-time-passwords/totp.lisp

Dependency

hotp.lisp (file)

Parent

cl-one-time-passwords (system)

Location

totp.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-totp

Source

packages.lisp (file)

Nickname

totp

Use List

common-lisp

Exported Definitions
Internal Definitions

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

4.2 cl-hotp

Source

packages.lisp (file)

Nickname

hotp

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: *digits*
Package

cl-hotp

Source

hotp.lisp (file)

Special Variable: *hmac-sha-mode*
Package

cl-hotp

Source

hotp.lisp (file)

Special Variable: *time-step-in-seconds*
Package

cl-totp

Source

totp.lisp (file)

Special Variable: *time-zero*
Package

cl-totp

Source

totp.lisp (file)


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

5.1.2 Functions

Function: hotp KEY-STRING COUNTER
Package

cl-hotp

Source

hotp.lisp (file)

Function: totp KEY-HEXSTRING &optional OFFSET TIME
Package

cl-totp

Source

totp.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Constants

Constant: .unix-epoch-zero.
Package

cl-totp

Source

totp.lisp (file)


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

5.2.2 Macros

Macro: time-step UNIX-TIME
Package

cl-totp

Source

totp.lisp (file)


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

5.2.3 Functions

Function: hmac-sha-n KEY-STRING COUNTER
Package

cl-hotp

Source

hotp.lisp (file)

Function: hotp-truncate 20-BYTES
Package

cl-hotp

Source

hotp.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-one-time-passwords.asd: The cl-one-time-passwords<dot>asd file
cl-one-time-passwords/hotp.lisp: The cl-one-time-passwords/hotp<dot>lisp file
cl-one-time-passwords/packages.lisp: The cl-one-time-passwords/packages<dot>lisp file
cl-one-time-passwords/totp.lisp: The cl-one-time-passwords/totp<dot>lisp file

F
File, Lisp, cl-one-time-passwords.asd: The cl-one-time-passwords<dot>asd file
File, Lisp, cl-one-time-passwords/hotp.lisp: The cl-one-time-passwords/hotp<dot>lisp file
File, Lisp, cl-one-time-passwords/packages.lisp: The cl-one-time-passwords/packages<dot>lisp file
File, Lisp, cl-one-time-passwords/totp.lisp: The cl-one-time-passwords/totp<dot>lisp file

L
Lisp File, cl-one-time-passwords.asd: The cl-one-time-passwords<dot>asd file
Lisp File, cl-one-time-passwords/hotp.lisp: The cl-one-time-passwords/hotp<dot>lisp file
Lisp File, cl-one-time-passwords/packages.lisp: The cl-one-time-passwords/packages<dot>lisp file
Lisp File, cl-one-time-passwords/totp.lisp: The cl-one-time-passwords/totp<dot>lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   F   H   M   T  
Index Entry  Section

F
Function, hmac-sha-n: Internal functions
Function, hotp: Exported functions
Function, hotp-truncate: Internal functions
Function, totp: Exported functions

H
hmac-sha-n: Internal functions
hotp: Exported functions
hotp-truncate: Internal functions

M
Macro, time-step: Internal macros

T
time-step: Internal macros
totp: Exported functions

Jump to:   F   H   M   T  

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

A.3 Variables

Jump to:   *   .  
C   S  
Index Entry  Section

*
*digits*: Exported special variables
*hmac-sha-mode*: Exported special variables
*time-step-in-seconds*: Exported special variables
*time-zero*: Exported special variables

.
.unix-epoch-zero.: Internal constants

C
Constant, .unix-epoch-zero.: Internal constants

S
Special Variable, *digits*: Exported special variables
Special Variable, *hmac-sha-mode*: Exported special variables
Special Variable, *time-step-in-seconds*: Exported special variables
Special Variable, *time-zero*: Exported special variables

Jump to:   *   .  
C   S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-hotp: The cl-hotp package
cl-one-time-passwords: The cl-one-time-passwords system
cl-totp: The cl-totp package

P
Package, cl-hotp: The cl-hotp package
Package, cl-totp: The cl-totp package

S
System, cl-one-time-passwords: The cl-one-time-passwords system

Jump to:   C   P   S