A Demonstration of Two-Factor Cryptographic Authentication with a Familiar User Experience

As announced in this blog post, this repository contains the code of a demonstration of two-factor cryptographic authentication of a user to a web site (the relying party, RP), using a fusion credential that combines a password with an extended key-pair to provide strong security and a familiar user experience.

Demo

A live demo is no longer available. But if you have an AWS account that allows you to send mail, you can set up a demo on your own EC2 instance using the install-script included in the repository and following the instructions below.

User experience

Registration

1. The user visits the registration page in a browser and enters user data (first and last names in this demo) and an email address.

2. An email verification link is sent to the address.

3. The user opens the link in the browser; the address is verified, a cryptographic credential is installed, and the user is asked to choose a password.

4. The user enters and confirms the password.

5. The registration is completed and the user is logged in on the browser.

Login on a browser where a cryptographic credential has been installed

1. The user submits her email address and is prompted for her password.

2. The user submits her password.

3. The user is authenticated and logged in on the browser.

Login on a browser where there is no cryptographic credential

1. The user submits her email address.

2. An email verification link is sent to the address.

3. The user opens the link in the browser; the address is verified, a cryptographic credential is installed, and the user is prompted for her password.

4. The user submits her password.

5. The user is authenticated and logged in on the browser.

Authentication protocol

At registration, the JavaScript frontend of the RP:

1. Generates a cryptographic credential consisting of a key pair extended with a secret salt.

2. Hashes the user's password with the secret salt.

3. Hashes the salted password with the public key, obtaining a "fusion hash".

4. Registers the fusion hash with the backend.

To authenticate:

1. The backend sends a challenge.

2. The frontend asks the user for the password and hashes it with the secret salt.

3. The frontend signs the challenge with the private key.

4. The frontend sends the signature, the salted password, and the public key to the backend.

5. The backend verifies the signature.

6. The backend computes the fusion hash from the salted password and the public key, and verifies it against the registered fusion hash.

7. The backend deletes the salted password and the public key that it has received from the frontend.

Replication of the cryptographic credential across all browsers in all devices

The same extended key pair is used in all browsers and devices. This is achieved without credential synchronization by:

• Deriving a seed for the generation of pseudo-random bits from the email address and a master secret.

• Using pseudo-random bits derived from the seed in the generation of the cryptographic credential, upon email verification.

Code details

CSRF protection

Forms are protected against cross-site request forgery (CSRF) using the Signed Double Submit pattern.

Rotation of the master secret

The master secret can be rotated to allow a user to continue using the same email address after the credential derived from the address has been compromised. This is implemented using a database table of master record versions where each record contains an auto-incremented version number and a corresponding random value of the master record. When a user registers the latest version number is stored in the user record, causing the corresponding master record to be used to derive the cryptographic credential from the user's email address in all browsers. If that credential is compromised, the master record can be rotated to add a new master record version to the table. In this demo, for simplicity, the rotation is triggered by a GET request to "/rotateMasterRecord". In production, the user would report the compromise to an administrator who would perform the rotation and store the new version number in the user's record; that is not implemented in this demo.

Graphical pseudo-code

The slides in 2F-crypto-authn.pptx provide a step-by-step description of the code.

Technical ingredients used in the demonstration

The backend runs under Nodejs and uses a MySQL database. The Pomcor JavaScript Cryptographic Library (PJCL) is used on the frontend and the backend. A deterministic random bit generator (DRBG) initialized with entropy sources is used to generate random bits for various purposes (ECDSA signature, authentication challenge, etc.) while the same DRBG initialized with the seed is used to generate the extended key pair (ECDSA key pair generation and random generation of the secret salt).

How to set up the demo on your own Amazon AWS EC2 server

To set up the demo on your own server you need to have an Amazon AWS account that allows you to send mail using the AWS Simple Email Service.

Launch a free-tier eligible EC2 server running Amazon Linux 2 on AWS. Be sure to use Amazon Linux 2 rather than Amazon Linux 2023; Amazon Linux 2023 does not support the MySQL community server at this time.

Assign an IAM role to the server with a policy that allows it to send email using the AWS Simple Email Service (SES).

Install git (sudo yum -y install git) and clone this repository into a directory /home/ec2-user/2F-crypto-authn-demo.

Change directory to 2F-crypto-authn-demo, give execute permission to install-demo and demo.mjs (chmod a+x install-demo demo.mjs), and run the installation script (sudo ./install-demo). The script will install MySQL, Nodejs, and node modules including pjcl. The script will ask you for the public IP address of the server or a domain name that maps to the IP address, and a sender address for the email verification messages.

After installation, you can run the demo:

• As a systemd service, with the command sudo systemctl start demo.

• Or as an executable running under bash, with the command sudo node demo.mjs while in the 2F-crypto-authn-demo directory.

Server certificate

The demo comes with a self-signed certificate server-cert.pem and its associated private key server-key.pem, which you can replace with a domain certificate for your chosen hostname and its associated private key. If you don't replace them, the use of the self-signed certificate will cause the browser to produce a warning that the connection is not private, or an error that the site is not reachable. If the browser produces an error, refreshing the page will take you to the warning and you will be able to ignore the warning and proceed to the demo.

Streamlined process for getting a license to US patent 9,887,989

THE STREAMLINED PROCESS IS NO LONGER AVAILABLE.
PLEASE CONTACT US THROUGH THE POMCOR CONTACT PAGE IF YOU WOULD LIKE TO LICENSE THE PATENT.

As stated in the LICENSE, this software is provided as a demonstration of a method of user authentication to a web site or web application that incorporates an invention claimed by US patent 9,887,989, and a license to the patent may be required for non-experimental use of the software. The patent is owned by Pomcor, and you may use the contact form of the Pomcor site to request a license. A streamlined process for obtaining a patent for a particular web site is available.

See also

• The Demonstrations page of the Pomcor site.
• The Cryptographic Authentication page of the Pomcor site.