Clef - Security Architecture Overview

Clef replaces the traditional two-factor authentication model with public-key cryptography. We offer two different service architectures:Standard Authentication, which is optimized for ease of integration and relies on Clef as a central auditor of identity, and DistributedAuthentication, which is optimized for high-security deployments and minimizes Clef’s role as a trusted party.

Standard Authentication

Overview

Standard Clef Authentication leverages Clef’s internal public-key infrastructure to verify user logins and integrates with 3rd party businesses through a standard implementation of OAuth 2.0.

Glossary of Terms‍

• Clef is a service provider.‍
• An Integrating business is a relying party.‍
• A user’s private key is generated and stored on the user’s smartphone (iOS or Android).
• The corresponding public key is generated on the phone and stored on the Clef server.
• Every user also has a user ID which is stored on the smartphone, and connected to the public key on the Clef server.
• The Clef Wave displays a session ID which is generated on the Clef server and displayed on the relying party website.

Architecture

Provisioning

When a user signs up for Clef, they are provisioned with a 2048-bit RSA key pair, which is generated and stored on their iOS or Android device.

The private key is stored in the device’s secure keychain and never transmitted off the device.On iOS devices, they key is stored in Apple’s Secure Enclave. On Android devices, we leverage any encrypted storage methods a given device provides and fallback to a standard key-based encryption with a key derived from the user PIN.

The public key is sent to Clef’s central servers where it is stored.

Login

When a user logs in, they are using the private key stored on their device to generate a unique login signature. The public key stored on the Clef servers verifies that signature before logging the user in. The parts of the login process are:

1. The user initiates a login request by visiting a login page or clicking on a “log in with Clef”button.
2. A Clef iframe on the relying party requests a session ID from the Clef server, which will be unique per browser session, and then displays it in the form of a Clef Wave.
3. Using the Clef smartphone app, the user verifies their fingerprint or PIN, then scans the ClefWave to get the session ID on their phone.
4. The Clef smartphone app uses the private key to sign a payload of information including the user ID and session ID and create a unique signature.
5. The Clef smartphone app sends the payload and signature to the Clef server.
6. The Clef server verifies the signature matches the payload using the public key corresponding to the user ID.

At the end of this process, the user login has been verified by Clef.

OAuth handshake

The OAuth handshake is used to transfer the user login verification from Clef, the service provider, to a given relying party. We implement OAuth 2.0, which is the widely accepted standard for this transfer. The parts of this process are:

1. Once the signature has been verified, the Clef server sends an OAuth Code to the Clef iframe on the relying party.
2. The Clef iframe sends the OAuth Code to the relying party.
3. The relying party uses the OAuth Code to initiate an OAuth handshake with the Clef server in order to receive the user’s information, including a site-specific User ID.
4. The relying party uses the site-specific User ID to look up the user and log them in.

At the end of this process, the user login has been transferred to the relying party and the user has been logged in.

Credential Storage

In the Standard Authentication architecture, cryptographic information is stored both on the device and on Clef’s servers.

Private credential storage

The user private key is the only cryptographically private credential and it is only stored on the user’s smartphone.

Public credential storage

The user public key is stored on Clef’s servers.

Distributed Authentication

Overview

Distributed Authentication is an extension of Standard Authentication that leverages a distributed public-key infrastructure to identify users. With Distributed Authentication, businesses verify a user login signature after completing the standard OAuth handshake.

Every Distributed Authentication login signature is verified by the relying party, so Clef is no longer a trusted party in the login handshake. For high security businesses, this trustless approach is critical.

Glossary of Terms

• Clef is a service provider.‍
• An Integrating business is a relying party.‍
• A user’s private key is generated and stored on the user’s smartphone (iOS or Android).
• The corresponding public key is generated on the phone and stored on the Clef server.
• Every user also has a user ID which is stored on the smartphone, and connected to the public key on the Clef server.
• The Clef Wave displays a session ID which is generated on the Clef server and displayed on the relying party website.
• A distributed validation payload is a payload of information created by a relying party to uniquely identify a user login.
• A user payload signature is a signature of the distributed validation payload created by the user.
• A relying party payload signature is a signature of the distributed validation payload created by the relying party.
• A relying party private key is generated and stored on the relying party server.
• A relying party public key is generated on the relying party server and stored on the Clef server.

‍Architecture

Provisioning

When a user signs up for Clef, they are provisioned with a 2048-bit RSA key pair, which is generated and stored on their iOS or Android device.

The private key is stored in the device’s secure keychain and never transmitted off the device.On iOS devices, they key is stored in Apple’s Secure Enclave. On Android devices, we leverage any encrypted storage methods a given device provides and fallback to a standard key-based encryption with a key derived from the user PIN.

The public key is sent to Clef’s central servers where it is stored.

Login

When a user logs in, they are using the private key stored on their device to generate a unique login signature. The public key stored on the Clef servers verifies that signature before logging the user in. The parts of the login process are:

1. The user initiates a login request by visiting a login page or clicking on a “log in with Clef”button.
2. A Clef iframe on the relying party requests a session ID from the Clef server, which will be unique per browser session, and then displays it in the form of a Clef Wave.
3. Using the scanner in the Clef smartphone app, the user verifies their fingerprint or PIN, then scans the Clef Wave to get the session ID on their phone.
4. The Clef smartphone app uses the private key to sign a payload of information including the user ID and session ID and create a unique signature.
5. The Clef smartphone app sends the payload and signature to the Clef server.
6. The Clef server verifies the signature matches the payload using the public key corresponding to the user ID.

At the end of this process, the user login has been verified by Clef.

OAuth handshake

The OAuth handshake is used to transfer the user login verification from Clef, the service provider, to a given relying party. We implement OAuth 2.0, which is the widely accepted standard for this transfer. The parts of this process are:

1. Once the signature has been verified, the Clef server sends an OAuth Code to the Clef iframe on the relying party.
2. The Clef iframe sends the OAuth Code to the relying party.
3. The relying party uses the OAuth Code to initiate an OAuth handshake with the Clef server in order to receive the user’s information, including a site-specific User ID.
4. The relying party uses the site-specific User ID to look up the user and log them in.

At the end of this process, the user login has been transferred to the relying party and the user has been logged in.

OAuth 2.0 extension

After the initial OAuth handshake, the user is prompted to confirm the login and their device generates a second signature which is verified by the relying party. The parts of this process are:

1. The relying party completes the OAuth 2.0 handshake and receives a site-specific User ID.If this a new user, the relying party also receives the user public key, which it stores and pins to the site-specific User ID.
2. The relying party creates a distributed validation payload and signs it to create a relying party payload signature using the relying party private key.
3. The relying party passes the distributed validation payload and payload signature to theClef server.
4. The Clef server verifies the payload signature using the relying party public key.
5. The Clef server passes the distributed validation payload to the user’s smartphone.
6. The user sees a notification from the Clef smartphone app asking for confirmation that they are attempting to log into the relying party.
7. When they confirm the login attempt in the app, the app creates a user payload signature from the distributed validation payload using the user private key.
8. The Clef smartphone app sends the payload signature back to the Clef server, which passes it through to the relying party server.
9. The relying party server verifies the payload signature using the user’s public key.
10. The relying party now has confirmation of the user’s intent and verification, and can log the user in.

‍Credential Storage

In the Standard Authentication architecture, cryptographic information is stored both on the device and on Clef’s servers.

Private credential storage

The user private key is the only cryptographically private credential and it is only stored on the user’s smartphone.

Public credential storage

The user public key is stored on Clef’s servers.
The user public key is replicated to the relying party servers.

Next Steps

By offering both, Standard Authentication and Distributed Authentication, Clef is able to serve a range of customer needs, including low-friction integrations and high-security deployments.

To discuss the right deployment for your business, contact our sales team at sales@getclef.com

‍

‍

‍

‍

‍

‍