otplib

Time-based (TOTP) and HMAC-based (HOTP) One-Time Password library

• About
• Demo and Documentation
• Installation
• Upgrading
• Getting Started
  • In node
  • In browser
• Notes
  • Setting Custom Options
    • Available Options
  • Google Authenticator
    • Base32 Keys and RFC3548
    • Seed / secret length
  • Browser Compatibility
• Advanced Usage
• Related
• Contributing
• License

About

otplib is a JavaScript One Time Password (OTP) library. It provides both functions and classes for dealing with OTP generation and verification.

It was initially created for me to understand how One Time Passwords work in implementation.

It implements:

• RFC 4226 - HOTP
• RFC 6238 - TOTP

The implementations provided here are tested against test vectors provided in their respective RFC specifications. These datasets can be found in the tests/helpers folder.

• RFC 4226 Dataset
• RFC 6238 Dataset

This library is also compatible with Google Authenticator, and includes additional methods to allow you to work with Google Authenticator.

Demo and Documentation

• Documentation
• Demo

Installation

Install the library via:

$ npm install otplib --save

or

$ yarn add otplib

Upgrading

This library follows semver. As such, major version bumps usually mean API changes or behavior changes. Please check upgrade notes for more information, especially before making any major upgrades.

You might also want to check out the release notes associated with each tagged versions in the releases page.

Getting Started

In node

import otplib from 'otplib';

const secret = otplib.authenticator.generateSecret();

const token = otplib.authenticator.generate(secret);

const isValid = otplib.authenticator.check(123456, secret);

// or

const isValid = otplib.authenticator.verify({
  secret,
  token: 123456
});

If you want to include a specific OTP specification, you can import it directly:

import hotp from 'otplib/hotp';
import totp from 'otplib/totp';
import authenticator from 'otplib/authenticator';

For ease of use, the default exports are all instantiated instances of their respective classes. You may access the original classes via:

import {HOTP} from 'otplib/hotp';
import {TOTP} from 'otplib/totp';
import {Authenticator} from 'otplib/authenticator';

Do note that if you're using require, you will need to do const otplib = require('otplib').default as the sources are compiled with babel. Alternatively, the library provides ES5 compat files for some of the main entry points to the library. i.e.

const otplib = require('otplib').default;
const totp = require('otplib/totp').default;

// same as

const otplib = require('otplib/compat');
const totp = require('otplib/compat/totp');

All these can be found in the compat folder.

In browser

Compiled versions of the library are also available, which can be useful for quick proof-of-concepts or even login implementations.

You'll need to add the following scripts to your code:

<!-- required: common lib -->
<script src="otplib-commons.js"></script>

<!-- replace with any of the available files below -->
<script src="otplib.js"></script>

<script type="text/javascript">
   // window.otplib or window.otplib_hotp etc
</script>

Available files:

• otplib.js - (hotp / totp / google authenticator)
• otplib-hotp.js - (hotp)
• otplib-totp.js - (totp)
• otplib-ga.js - (google authenticator)
• otplib-otputils.js - (utilites)
• otplib-legacy.js - (v2 interface)

You can find these files in node_modules/otplib/dist after you install. Alternatively, you can get the latest here.

For a live example, the project site has been built using otplib.js. The source code can be found here.

Notes

Setting Custom Options

All instantiated classes will have their options inherited from their respective options generator. i.e. HOTP from hotpOptions and TOTP/Authenticator from totpOptions.

All OTP classes have an object setter and getter method to override these default options.

For example,

import otplib from 'otplib';

// setting
otplib.authenticator.options = {
   step: 30
}

// getting
const opts = otplib.authenticator.options;

Available Options

Google Authenticator

Base32 Keys and RFC3548

Google Authenticator requires keys to be base32 encoded. It also requires the base32 encoder to be RFC 3548 compliant.

OTP calculation will still work should you want to use other base32 encoding methods (like Crockford's Base 32) but it will NOT be compatible with Google Authenticator.

import authenticator from 'otplib/authenticator';

const secret = authenticator.generateSecret(); // base 32 encoded user secret key
const token = authenticator.generate(secret);

Seed / secret length

In RFC 6238, the secret / seed length for different algorithms is predefined:

HMAC-SHA1 - 20 bytes
HMAC-SHA256 - 32 bytes
HMAC-SHA512 - 64 bytes

As such, the length of the secret is padded and sliced according to the expected length for respective algrorithms. However, Google Authenticator does not seem to pad the secret, resulting in issue #7 As such, for Google Authenticator, the createHmacSecret has been defaulted to the hotpSecret function as of v5.0.0

Browser Compatibility

In order to reduce the size of the browser package, the crypto package has been replaced with a alternative implementation. The current implementation depends on Uint8Array and the browser's native crypto methods, which may only be available in recent browser versions.

To find out more about the replacements, you can take a look at src/utils/crypto.js

Output sizes:

• with node crypto: ~311Kb
• with alternative crypto: ~94.2Kb

If you prefer to use node's crypto module instead, you can set the environment variable OTPLIB_WEBPACK_USE_NODE_CRYPTO=true and rebuild the browser distribution.

i.e. OTPLIB_WEBPACK_USE_NODE_CRYPTO=true npm run build:dist

Advanced Usage

By default, classes are provided to wrap functionalities and methods into logical groups. However, they are ultimately just syntax-sugar to the underlying functional steps in OTP generation.

If you prefer a more functional approach compared to classes, you may import them from their respective folders.

• functions can be found in otplib/core/<FILENAME>
• classes can be found in otplib/classes/<FILENAME>
• utils can be found in otplib/utils/<FILENAME>

Most of the core functions will take in an object options as their last argument.

For more information about the functions and available files, check out the documentation.

Related

• otplib-cli - Command-line OTP

Contributing

• Check out: CONTRIBUTING.md

License

otplib is MIT licensed