![](\"http://i.imgur.com/gPwPP4u.png\")
![](\"http://i.imgur.com/qRyNMx4.png\")
\n\n[](https://travis-ci.org/speakeasyjs/speakeasy)\n[](https://www.npmjs.com/package/speakeasy)\n[](https://coveralls.io/github/speakeasyjs/speakeasy?branch=v2)\n[](https://www.npmjs.com/package/speakeasy)\n\n---\n\n**Jump to** — [Install](#install) · [Demo](#demo) · [Two-Factor Usage](#two-factor) · [General Usage](#general-usage) · [Documentation](#documentation) · [Contributing](#contributing) · [License](#license)\n\n---\n\nSpeakeasy is a one-time passcode generator, ideal for use in two-factor\nauthentication, that supports Google Authenticator and other two-factor devices.\n\nIt is well-tested and includes robust support for custom token lengths,\nauthentication windows, hash algorithms like SHA256 and SHA512, and other\nfeatures, and includes helpers like a secret key generator.\n\nSpeakeasy implements one-time passcode generators as standardized by the\n[Initiative for Open Authentication (OATH)][oath]. The HMAC-Based One-Time\nPassword (HOTP) algorithm defined by [RFC 4226][rfc4226] and the Time-Based\nOne-time Password (TOTP) algorithm defined in [RFC 6238][rfc6238] are\nsupported. This project incorporates code from [passcode][], originally a\nfork of Speakeasy, and [notp][].\n\n\n\n## Install\n\n```sh\nnpm install --save speakeasy\n```\n\n\n## Demo\n\nThis demo uses the `generateSecret` method of Speakeasy to generate a secret key,\ndisplays a Google Authenticator–compatible QR code which you can scan into your\nphone's two-factor app, and shows the token, which you can verify with your\nphone. Includes sample code. https://sedemo-mktb.rhcloud.com/\n\n\n\n\n## Two-Factor Usage\n\nLet's say you have a user that wants to enable two-factor authentication, and you intend to do two-factor authentication using an app like Google Authenticator, Duo Security, Authy, etc. This is a three-step process:\n\n1. Generate a secret\n2. Show a QR code for the user to scan in\n3. Authenticate the token for the first time\n\n### Generating a key\n\nUse Speakeasy's key generator to get a key.\n\n```js\nvar secret = speakeasy.generateSecret();\n// Returns an object with secret.ascii, secret.hex, and secret.base32.\n// Also returns secret.otpauth_url, which we'll use later.\n```\n\nThis will generate a secret key of length 32, which will be the secret key for the user.\n\nNow, we want to make sure that this secret works by validating the token that the user gets from it for the first time. In other words, we don't want to set this as the user's secret key just yet – we first want to verify their token for the first time. We need to persist the secret so that we can use it for token validation later.\n\nSo, store one of the encodings for the secret, preferably `secret.base32`, somewhere temporary, since we'll use that in the future to authenticate the user's first token.\n\n```js\n// Example for storing the secret key somewhere (varies by implementation):\nuser.two_factor_temp_secret = secret.base32;\n```\n\n### Displaying a QR code\n\nNext, we'll want to display a QR code to the user so they can scan in the secret into their app. Google Authenticator and similar apps take in a QR code that holds a URL with the protocol `otpauth://`, which you get automatically from `secret.otpauth_url`.\n\nUse a QR code module to generate a QR code that stores the data in `secret.otpauth_url`, and then display the QR code to the user. This is one simple way to do it, which generates a PNG data URL which you can put into an `![](\"http://i.imgur.com/hD9w41T.png\")
\n\n### Functions\n\nBufferDigest the one-time passcode options.
\nStringGenerate a counter-based one-time token.
\nObjectVerify a counter-based one-time token against the secret and return the delta.
\nBooleanVerify a counter-based one-time token against the secret and return true if it\nverifies.
\nStringGenerate a time-based one-time token.
\nObjectVerify a time-based one-time token against the secret and return the delta.
\nBooleanVerify a time-based one-time token against the secret and return true if it\nverifies.\n
Object | GeneratedSecretGenerates a random secret with the set A-Z a-z 0-9 and symbols, of any length\n(default 32).
\nStringGenerates a key of a certain length (default 32) from A-Z, a-z, 0-9, and\nsymbols (if requested).
\nStringGenerate an URL for use with the Google Authenticator app.
\nObjectBuffer\nDigest the one-time passcode options.\n\n**Kind**: function \n\n**Returns**: Buffer - The one-time passcode as a buffer. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.counter | Integer | | Counter value |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n| [options.key] | String | | (DEPRECATED. Use `secret` instead.) Shared secret key |\n\n\n### hotp(options) ⇒ String\n\nGenerate a counter-based one-time token. Specify the key and counter, and\nreceive the one-time password for that counter position as a string. You can\nalso specify a token length, as well as the encoding (ASCII, hexadecimal, or\nbase32) and the hashing algorithm to use (SHA1, SHA256, SHA512).\n\n**Kind**: function \n\n**Returns**: String - The one-time passcode. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.counter | Integer | | Counter value |\n| [options.digest] | Buffer | | Digest, automatically generated by default |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n| [options.key] | String | | (DEPRECATED. Use `secret` instead.) Shared secret key |\n| [options.length] | Integer | 6 | (DEPRECATED. Use `digits` instead.) The number of digits for the one-time passcode. |\n\n\n### hotp․verifyDelta(options) ⇒ Object\nVerify a counter-based one-time token against the secret and return the delta.\nBy default, it verifies the token at the given counter value, with no leeway\n(no look-ahead or look-behind). A token validated at the current counter value\nwill have a delta of 0.\n\nYou can specify a window to add more leeway to the verification process.\nSetting the window param will check for the token at the given counter value\nas well as `window` tokens ahead (one-sided window). See param for more info.\n\n`verifyDelta()` will return the delta between the counter value of the token\nand the given counter value. For example, if given a counter 5 and a window\n10, `verifyDelta()` will look at tokens from 5 to 15, inclusive. If it finds\nit at counter position 7, it will return `{ delta: 2 }`.\n\n**Kind**: function \n\n**Returns**: Object - On success, returns an object with the counter\n difference between the client and the server as the `delta` property (i.e.\n `{ delta: 0 }`). \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.token | String | | Passcode to validate |\n| options.counter | Integer | | Counter value. This should be stored by the application and must be incremented for each request. |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. |\n| [options.window] | Integer | 0 | The allowable margin for the counter. The function will check \"W\" codes in the future against the provided passcode, e.g. if W = 10, and C = 5, this function will check the passcode against all One Time Passcodes between 5 and 15, inclusive. |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n\n\n### hotp․verify(options) ⇒ Boolean\nVerify a counter-based one-time token against the secret and return true if it\nverifies. Helper function for `hotp.verifyDelta()`` that returns a boolean\ninstead of an object. For more on how to use a window with this, see\nhotp.verifyDelta.\n\n**Kind**: function \n\n**Returns**: Boolean - Returns true if the token matches within the given\n window, false otherwise. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.token | String | | Passcode to validate |\n| options.counter | Integer | | Counter value. This should be stored by the application and must be incremented for each request. |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. |\n| [options.window] | Integer | 0 | The allowable margin for the counter. The function will check \"W\" codes in the future against the provided passcode, e.g. if W = 10, and C = 5, this function will check the passcode against all One Time Passcodes between 5 and 15, inclusive. |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n\n\n### totp(options) ⇒ String\n\nGenerate a time-based one-time token. Specify the key, and receive the\none-time password for that time as a string. By default, it uses the current\ntime and a time step of 30 seconds, so there is a new token every 30 seconds.\nYou may override the time step and epoch for custom timing. You can also\nspecify a token length, as well as the encoding (ASCII, hexadecimal, or\nbase32) and the hashing algorithm to use (SHA1, SHA256, SHA512).\n\nUnder the hood, TOTP calculates the counter value by finding how many time\nsteps have passed since the epoch, and calls HOTP with that counter value.\n\n**Kind**: function \n\n**Returns**: String - The one-time passcode. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| [options.time] | Integer | | Time in seconds with which to calculate counter value. Defaults to `Date.now()`. |\n| [options.step] | Integer | 30 | Time step in seconds |\n| [options.epoch] | Integer | 0 | Initial time since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset). |\n| [options.counter] | Integer | | Counter value, calculated by default. |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n| [options.key] | String | | (DEPRECATED. Use `secret` instead.) Shared secret key |\n| [options.initial_time] | Integer | 0 | (DEPRECATED. Use `epoch` instead.) Initial time since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset). |\n| [options.length] | Integer | 6 | (DEPRECATED. Use `digits` instead.) The number of digits for the one-time passcode. |\n\n\n### totp․verifyDelta(options) ⇒ Object\nVerify a time-based one-time token against the secret and return the delta.\nBy default, it verifies the token at the current time window, with no leeway\n(no look-ahead or look-behind). A token validated at the current time window\nwill have a delta of 0.\n\nYou can specify a window to add more leeway to the verification process.\nSetting the window param will check for the token at the given counter value\nas well as `window` tokens ahead and `window` tokens behind (two-sided\nwindow). See param for more info.\n\n`verifyDelta()` will return the delta between the counter value of the token\nand the given counter value. For example, if given a time at counter 1000 and\na window of 5, `verifyDelta()` will look at tokens from 995 to 1005,\ninclusive. In other words, if the time-step is 30 seconds, it will look at\ntokens from 2.5 minutes ago to 2.5 minutes in the future, inclusive.\nIf it finds it at counter position 1002, it will return `{ delta: 2 }`.\nIf it finds it at counter position 997, it will return `{ delta: -3 }`.\n\n**Kind**: function \n\n**Returns**: Object - On success, returns an object with the time step\n difference between the client and the server as the `delta` property (e.g.\n `{ delta: 0 }`). \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.token | String | | Passcode to validate |\n| [options.time] | Integer | | Time in seconds with which to calculate counter value. Defaults to `Date.now()`. |\n| [options.step] | Integer | 30 | Time step in seconds |\n| [options.epoch] | Integer | 0 | Initial time since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset). |\n| [options.counter] | Integer | | Counter value, calculated by default. |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. |\n| [options.window] | Integer | 0 | The allowable margin for the counter. The function will check \"W\" codes in the future and the past against the provided passcode, e.g. if W = 5, and C = 1000, this function will check the passcode against all One Time Passcodes between 995 and 1005, inclusive. |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n\n\n### totp․verify(options) ⇒ Boolean\nVerify a time-based one-time token against the secret and return true if it\nverifies. Helper function for verifyDelta() that returns a boolean instead of\nan object. For more on how to use a window with this, see totp.verifyDelta.\n\n**Kind**: function\n\n**Returns**: Boolean - Returns true if the token matches within the given\n window, false otherwise. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.token | String | | Passcode to validate |\n| [options.time] | Integer | | Time in seconds with which to calculate counter value. Defaults to `Date.now()`. |\n| [options.step] | Integer | 30 | Time step in seconds |\n| [options.epoch] | Integer | 0 | Initial time since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset). |\n| [options.counter] | Integer | | Counter value, calculated by default. |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. |\n| [options.window] | Integer | 0 | The allowable margin for the counter. The function will check \"W\" codes in the future and the past against the provided passcode, e.g. if W = 5, and C = 1000, this function will check the passcode against all One Time Passcodes between 995 and 1005, inclusive. |\n| [options.encoding] | String | "ascii" | Key encoding (ascii, hex, base32, base64). |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n\n\n### generateSecret(options) ⇒ Object | [GeneratedSecret](#GeneratedSecret)\nGenerates a random secret with the set A-Z a-z 0-9 and symbols, of any length\n(default 32). Returns the secret key in ASCII, hexadecimal, and base32 format,\nalong with the URL used for the QR code for Google Authenticator (an otpauth\nURL). Use a QR code library to generate a QR code based on the Google\nAuthenticator URL to obtain a QR code you can scan into the app.\n\n**Kind**: function \n\n**Returns**: A [`GeneratedSecret`](#GeneratedSecret) object\n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| [options.length] | Integer | 32 | Length of the secret |\n| [options.symbols] | Boolean | false | Whether to include symbols |\n| [options.otpauth_url] | Boolean | true | Whether to output a Google Authenticator-compatible otpauth:// URL (only returns otpauth:// URL, no QR code) |\n| [options.name] | String | | The name to use with Google Authenticator. |\n| [options.qr_codes] | Boolean | false | (DEPRECATED. Do not use to prevent leaking of secret to a third party. Use your own QR code implementation.) Output QR code URLs for the token. |\n| [options.google_auth_qr] | Boolean | false | (DEPRECATED. Do not use to prevent leaking of secret to a third party. Use your own QR code implementation.) Output a Google Authenticator otpauth:// QR code URL. |\n\n\n### generateSecretASCII([length], [symbols]) ⇒ String\nGenerates a key of a certain length (default 32) from A-Z, a-z, 0-9, and\nsymbols (if requested).\n\n**Kind**: function \n\n**Returns**: String - The generated key. \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| [length] | Integer | 32 | The length of the key. |\n| [symbols] | Boolean | false | Whether to include symbols in the key. |\n\n\n### otpauthURL(options) ⇒ String\nGenerate a Google Authenticator-compatible otpauth:// URL for passing the\nsecret to a mobile device to install the secret.\n\nAuthenticator considers TOTP codes valid for 30 seconds. Additionally,\nthe app presents 6 digits codes to the user. According to the\ndocumentation, the period and number of digits are currently ignored by\nthe app.\n\nTo generate a suitable QR Code, pass the generated URL to a QR Code\ngenerator, such as the `qr-image` module.\n\n**Kind**: function \n\n**Throws**: Error if secret or label is missing, or if hotp is used and a\n counter is missing, if the type is not one of `hotp` or `totp`, if the\n number of digits is non-numeric, or an invalid period is used. Warns if\n the number of digits is not either 6 or 8 (though 6 is the only one\n supported by Google Authenticator), and if the hashihng algorithm is\n not one of the supported SHA1, SHA256, or SHA512.\n\n**Returns**: String - A URL suitable for use with the Google Authenticator. \n\n**See**: https://github.com/google/google-authenticator/wiki/Key-Uri-Format \n\n| Param | Type | Default | Description |\n| --- | --- | --- | --- |\n| options | Object | | |\n| options.secret | String | | Shared secret key |\n| options.label | String | | Used to identify the account with which the secret key is associated, e.g. the user's email address. |\n| [options.type] | String | "totp" | Either \"hotp\" or \"totp\". |\n| [options.counter] | Integer | | The initial counter value, required for HOTP. |\n| [options.issuer] | String | | The provider or service with which the secret key is associated. |\n| [options.algorithm] | String | "sha1" | Hash algorithm (sha1, sha256, sha512). |\n| [options.digits] | Integer | 6 | The number of digits for the one-time passcode. Currently ignored by Google Authenticator. |\n| [options.period] | Integer | 30 | The length of time for which a TOTP code will be valid, in seconds. Currently ignored by Google Authenticator. |\n| [options.encoding] | String | | Key encoding (ascii, hex, base32, base64). If the key is not encoded in Base-32, it will be reencoded. |\n\n\n### GeneratedSecret : Object\n\n**Kind**: global typedef \n\n**Properties**\n\n| Name | Type | Description |\n| --- | --- | --- |\n| ascii | String | ASCII representation of the secret |\n| hex | String | Hex representation of the secret |\n| base32 | String | Base32 representation of the secret |\n| qr_code_ascii | String | URL for the QR code for the ASCII secret. |\n| qr_code_hex | String | URL for the QR code for the hex secret. |\n| qr_code_base32 | String | URL for the QR code for the base32 secret. |\n| google_auth_qr | String | URL for the Google Authenticator otpauth URL's QR code. |\n| otpauth_url | String | Google Authenticator-compatible otpauth URL. |\n\n\n## Contributing\n\nWe're very happy to have your contributions in Speakeasy.\n\n**Contributing code** — First, make sure you've added tests if adding new functionality. Then, run `npm test` to run all the tests to make sure they pass. Next, make a pull request to this repo. Thanks!\n\n**Filing an issue** — Submit issues to the [GitHub Issues][issues] page.\n\n**Maintainers** —\n\n- Mark Bao ([markbao][markbao])\n- Michael Phan-Ba ([mikepb][mikepb])\n\n## License\n\nThis project incorporates code from [passcode][], which was originally a\nfork of speakeasy, and [notp][], both of which are licensed under MIT.\nPlease see the [LICENSE](LICENSE) file for the full combined license.\n\nIcons created by Gregor Črešnar, iconoci, and Danny Sturgess from the Noun\nProject.\n\n[issues]: https://github.com/speakeasyjs/speakeasy\n[passcode]: http://github.com/mikepb/passcode\n[notp]: https://github.com/guyht/notp\n[oath]: http://www.openauthentication.org/\n[rfc4226]: https://tools.ietf.org/html/rfc4226\n[rfc6238]: https://tools.ietf.org/html/rfc6238\n[markbao]: https://github.com/markbao\n[mikepb]: https://github.com/mikepb\n","homepage":"http://github.com/speakeasyjs/speakeasy","keywords":["authentication","google authenticator","hmac","hotp","multi-factor","one-time password","passwords","totp","two factor","two-factor","two-factor authentication"],"bugs":{"url":"https://github.com/speakeasyjs/speakeasy/issues"},"readmeFilename":"README.md","contributors":[{"name":"Michael Phan-Ba","email":"michael@mikepb.com"},{"name":"Guy Halford-Thompson","email":"guy@cach.me"}],"license":"MIT"}