Generating 2FA One-Time Passwords in JS Using Web Crypto API

Introduction

Today 2FA is everywhere. It has made stealing accounts a bit harder than just obtaining a correct password. And while by no means it makes your online assets hackproof, it requires more sophisticated and multi-leveled attacks. As with anything in this world, the more complex something is — the more likely it is to fail.

I am pretty sure that everyone who is reading this has used OTP-based 2FA in their lifetime. Today, I am inviting you to look under the hood of this simple yet such widespread technique that is guarding countless accounts today.

But before we dive in — here's the demo of what we will be building today.

The basics

When talking about OTPs first thing that should be mentioned is that there are two types of them. HOTP and TOTP. Namely, HMAC-based One Time Password and Time-based OTP. TOTP is not something completely different but an enhancement over HOTP, so let's first talk about the basic form.

HOTP algorithm is described by RFC4226. It's a small, 35 pages long spec, that contains everything from formal description to implementation example and test cases. Let's look at some of it's core concepts.

First of all, what does HMAC-based mean? HMAC stands for Hash-based Message Authentication Code.

MAC is a way of proving that a message came from the expected sender and not someone else. MAC algorithm produces a MAC tag using a secret key that is only known to the sender and the receiver. So when you receive a message, you can recalculate MAC tag yourself and if it matches to the one that was sent along — then you can be sure the message came from the expected sender and not one of those balaclava-wearing hackers, duh. As a bonus this also verifies data integrity, as in whether the data was damaged along the way. You cannot really tell one event from another but it's safe to consider the data corrupted in both cases.

I have included some graphics similar to this one in this article. It might be silly but hopefully will help illustrate some things and make this wall of text less dull. Maybe they are too silly though...

Now, what is a hash? A hash is a product of running a message through a Hash Function. Hash functions take your data and make other fixed-length data out of it. For example, there is a well-known MD5 hash function. It was widely used to verify that the data you downloaded is not damaged. Basically, you feed it some data and get a string that looks like

CCB4DB2088210…

MAC itself is not a specific algorithm, but rather a term that refers to one. HMAC, in turn, IS a specific implementation. Or, to be more precise — HMAC-X, where X is one of the crypthographic hash functions. Now, HMAC takes two parameters — a secret key and your message, mixes them together in a special way, applies a hash function of your choice twice and produces a MAC tag.

This article is not about cryptography though and you are probably wondering — how the hell is all of this related to one-time passwords? Don't worry — we are almost there.

According to the specification, HOTP is calculated based on 2 values:

• K — a secret key shared between client and server
• C — a counter or a moving factor

Secret key is a value that must be over 128 bits long, preferrably 160. It is generated when you initially setup your 2FA.

Counter is an 8-byte value that is synchronized between the server and client. It will be constantly updated as you generate passwords. In HOTP, client counter is incremented each time a new password is generated and server counter — each time a password is validated. Since we can generate some passwords without using it, server allows counter values a bit ahead of what the current one is but only within a certain window. If you played with your OTP token too much and it was an

HOTP

Alright. As you have probably noticed, there are two input arguments here, just like in the HMAC itself. RFC4226 defines HOTP like this:

HOTP(K,C) = Truncate(HMAC-SHA-1(K,C))

So, K is predictably used as our secred key and Counter is used as the message. After HMAC generates the MAC — a mysterious

Truncate

Let's start generating and learn the rest along the way as we code!

Implementation plan

We will need the following steps to get our hands on those OTPs.

• Generate HMAC-SHA1 value from our K and C parameters. This will be a 20-byte string
• Extract 4 bytes from that string in a specific way
• Convert those bytes into a number, divide that number by 10^n, where n = number of digits in the OTP and take the remainder. Usually n=6.

Doesn't seem too complicated, right? We'll start with generating the HMAC.

Generating HMAC-SHA1

This is probably the most straightforward part of our plan. We are not going to roll our own crypto, of course. Never roll your own crypto. We are going to use Web Crypto API.

Now, one thing to mention here is that by specification it is only exposed in a Secure Context. What this means is that you will be unable to tinker with it unless your scripts are running on an HTTPS website. And I doubt your localhost dev server is configured this way. Mine certainly isn't! You can read more history on why it became this way (as well as countless disappointed devs voices) here.

Luckily, in Firefox you CAN use Webcrypto in any context and don't have to reinvent the wheel or import any third-party libraries to do that. So, for the purpose of this article we are going to use FF.

Crypto API itself resides under

window.crypto.subtle

It is named SubtleCrypto to reflect the fact that many of these algorithms have subtle usage requirements in order to provide the required algorithmic security guarantees

Let's quickly run through the Crypto API methods we will be using and set everything up. NB: all the methods mentioned here are async and return promises.

First of all, we would need the

importKey

importKey(
  format
  keyData,
  algorithm,
  extractable,
  usages
);

In our case:

• format

  will be

  'raw'

  , meaning that we will supply the key as raw bytes in an

  ArrayBuffer

  .

• keyData

  is the ArrayBuffer mentioned above. We'll talk about generating it in a bit

• algorithm

  will be

  HMAC-SHA1

  as per OTP spec. This has to be an HmacImportParams object

• extractable

  can be false, since we don't plan to export the key
• And finally, of all possible

  usages

  we will only need

  'sign'

Our secret key will be a long random string. In reality it could be a sequence of bytes that are not necessarily printable but for the sake of convenience in this article let's just go with a string. To convert it to an

ArrayBuffer

TextEncoder

const encoder = new TextEncoder('utf-8');
const secretBytes = encoder.encode(secret);

Now, let's compile everything together:

  const Crypto = window.crypto.subtle;
  const encoder = new TextEncoder('utf-8');
  const secretBytes = encoder.encode(secret);

  const key = await Crypto.importKey(
    'raw',
    secretBytes,
    { name: 'HMAC', hash: { name: 'SHA-1' } },
    false,
    ['sign']
  );

Great! We have our crypto instance on standby. Now let's deal with the counter and finally sign the message.

Our counter, according to the spec, should be 8 bytes and will also come in an

ArrayBuffer

ArrayBuffer

DataView

function padCounter(counter) {
  const buffer = new ArrayBuffer(8);
  const bView = new DataView(buffer);

  const byteString = '0'.repeat(64); // 8 bytes
  const bCounter = (byteString + counter.toString(2)).slice(-64);

  for (let byte = 0; byte < 64; byte += 8) {
    const byteValue = parseInt(bCounter.slice(byte, byte + 8), 2);
    bView.setUint8(byte / 8, byteValue);
  }

  return buffer;
}

With that in place — we are ready to sign! To do that we will just need to use

sign

SubtleCrypto

const counterArray = padCounter(counter);
const HS = await Crypto.sign('HMAC', key, counterArray);

Bam! First stage complete. We have our

HS

Step 2: Generate a 4-byte string (Dynamic Truncation)
Let Sbits = DT(HS)   //  DT, defined below,
                     //  returns a 31-bit string

DT stands for Dynamic Truncation. Here's how it works:

function DT(HS) {
  // First we take the last byte of our generated HS and extract last 4 bits out of it.
  // This will be our _offset_, a number between 0 and 15.
  const offset = HS[19] & 0b1111;
  
  // Next we take 4 bytes out of the HS, starting at the offset
  const P = ((HS[offset] & 0x7f) << 24) | (HS[offset + 1] << 16) | (HS[offset + 2] << 8) | HS[offset + 3]
  
  // Finally, convert it into a binary string representation
  const pString = P.toString(2);

  return pString;
}

Note how we apply bitwise AND to the first byte of HS.

0x7f

0b01111111

Alright, we are almost there! Now we only need to convert what we got from DT to an integer and off we go to stage 3.

function truncate(uKey) {
  const Sbits = DT(uKey);
  const Snum = parseInt(Sbits, 2);

  return Snum;
}

Stage 3 is really small. All we need to do now is to divide our resulting number by

10 ** (number of digits in OTP)

Code for the final function that encompasses all functions we created above will then look like this:

async function generateHOTP(secret, counter) {
  const key = await generateKey(secret, counter);
  const uKey = new Uint8Array(key);

  const Snum = truncate(uKey);
  // Make sure we keep leading zeroes
	const padded = ('000000' + (Snum % (10 ** 6))).slice(-6);
  
  return padded;
}

Hooray! Now, how do we verify that what we just coded is, in fact, correct?

Testing

To test our implementation we will use examples provided in the RFC. Appendix D provides reference values for the secret string

"12345678901234567890"

 Count    HOTP
   0        755224
   1        287082
   2        359152
   3        969429
   ...

If you have not yet checked the demo page, now is the time. Go ahead and try some of the RFC values over there. Make sure to come back though as we are about to move on to TOTPs!

TOTP

Finally, we've made it to the more modern form of 2FA — TOTP. When you open your favourite authenticator app and see a small clock ticking backwards, counting seconds until your code expires -- that's TOTP. So what's the difference?

Time-based means that instead of a static counter, current time is used as a moving factor. Or, to be precise, current time step. To calculate this time step we take current unix epoch time (number of milliseconds since 00:00:00 UTC on 1 January 1970) and divide it by a time window (usually 30 seconds). Server usually allows for a bit of time drift to account for imperfections in time sync -- about 1 step forwards and backwards depending on the configuration.

As you can see, this is clearly more secure than plain

HOTP

Due to time-based scheme being an extension over original algorithm, no changes to the original implementation are required. We will use

requestAnimationFrame

let stepWindow = 30 * 1000; // 30 seconds in ms
let lastTimeStep = 0;

const updateTOTPCounter = () => {
  const timeSinceStep = Date.now() - lastTimeStep * stepWindow;
  const timeLeft = Math.ceil(stepWindow - timeSinceStep);

  if (timeLeft > 0) {
    return requestAnimationFrame(updateTOTPCounter);
  }

  timeStep = getTOTPCounter();
  lastTimeStep = timeStep;
	<...update counter and regenerate...>
  requestAnimationFrame(updateTOTPCounter);
}

Finishing touch -- QR support

Usually when we setup 2FA we do so by scanning a setup QR code that contains all the required data: secret, selected OTP algorithm, account name, issuer name, number of digits.

In my previous article I talked about how we can scan QR codes right from the screen using getDisplayMedia API. I ended up creating a small npm library that we can now use to easily add QR code reading support into our demo. The library in question is called stream-display and it will be accompanied by an amazing jsQR package.

URL encoded in the QR code for 2FA should be in the following format:

otpauth://TYPE/LABEL?PARAMETERS

So, for example:

otpauth://totp/label?secret=oyu55d4q5kllrwhy4euqh3ouw7hebnhm5qsflfcqggczoafxu75lsagt&algorithm=SHA1&digits=6&period=30

I will omit the setup code for the stream/recognition itself since it can be easily found in both libs' documentation. Instead, here's how we can parse this URL:

const setupFromQR = data => {
  const url = new URL(data);
  
  // drop the "//" and get TYPE and LABEL
  const [scheme, label] = url.pathname.slice(2).split('/');
  const params = new URLSearchParams(url.search);

  const secret = params.get('secret');
  let counter;

  if (scheme === 'hotp') {
    counter = params.get('counter');
  } else {
    stepWindow = parseInt(params.get('period'), 10) * 1000;
    counter = getTOTPCounter();
  }
}

In a real world scenario the secret will be a base-32 (!) encoded string, because some shared secret bytes can be non-printable. But here we once again omit that for demo purposes. Unfortunately, I cannot find any information on why exactly it was decided to be base-32, or this specific format. There seems to be no actual RFC for the

otpauth

If you want to generate your own 2FA QR codes for testing purposes you can use an amazing FreeOTP tool. I sure used it a lot while making this.

Conclusion

And with this -- we shall be done! Once again, you can check out the demo to see it in action or to see the full code driving the entire process.

I think we covered some important tech we use on a daily basis and hope that you have learned something new today. I spent much more time writing this article that I imagined it would take. But it is also very enjoyable to turn a paper spec into something working and something so familiar. We have more interesting things to talk about in the future, so stay tuned.

Until next time!