Skip to main content

Passkeys

Passkeys can be used to secure onchain smart accounts using fingerprint, face recognition, or the device PIN code. Users no longer need to manage and remember complex private keys; instead, they can effortlessly access their digital wallets using passkey-enabled devices, synced across devices via Apple's iCloud Keychain, or other cross-platform password managers like Proton Pass and Bitwarden.

In the context of an Ethereum wallet, Passkeys serve as substitutes for traditional seedphrase backups. Unlike the default curve (secp256k1) used for Externally Owned Accounts (EOA), Passkeys generate unique digital keys using the secp256r1 curve. These keys benefit from device secure enclave cryptography, which enhances security by preventing password reuse. Passkeys are built on the WebAuthn standard, leveraging public-key cryptography. Developed collaboratively by the FIDO Alliance, which includes Apple, Google, Microsoft, and others, Passkeys strictly adhere to WebAuthn standards.

Demo with Safe Accounts​

This example showcases a Safe Smart Account deployment utilizing 4337 and Passkeys, and minting an NFT. It employs experimental and unaudited contracts (at the moment of writing), such as WebAuthnSigner and FCLP256Verifier, developed by the Safe and FreshCryptoLib Teams.

Create Passkeys Account​

npm i abstractionkit@0.1.12
note

We're installing v0.1.12 of abstractionkit, an alpha version that includes the Passkeys plugin, only on Sepolia Testnet.

We will often import WebAuthn API helper functions and classes from /webauthn. Make sure to copy it and using it during your developement.

Step 1: Create WebAuthn credentials​

Create WebAuthn credentials using the navigator.credentials API. This includes defining parameters such as the relying party (RP) name and ID, user details, and challenge.

import ethers from "ethers";
import { WebAuthnCredentials } from './webauthn';

const navigator = {
    credentials: new WebAuthnCredentials(),
}

const credential = navigator.credentials.create({
    publicKey: {
        rp: {
            name: 'Candide',
            id: 'candide.dev',
        },
        user: {
            id: ethers.getBytes(ethers.id('chucknorris')),
            name: 'chucknorris',
            displayName: 'Chuck Norris',
        },
        challenge: ethers.toBeArray(Date.now()),
        pubKeyCredParams: [{ type: 'public-key', alg: -7 }],
    },
})

Step 2: Extract Public Key​

Extract the public key from the generated WebAuthn credential response

import { extractPublicKey } from "./webauthn";
import { WebauthPublicKey } from "abstractionkit";

const publicKey = extractPublicKey(credential.response)

const webauthPublicKey: WebauthPublicKey = {
    x: publicKey.x,
    y: publicKey.y,
}

Step 4: Initialize Smart Account​

Initialize the Safe Smart Account as usual. The SafeAccountWebAuth class uses the same methods as the other for everything related to creating a userOp.

import { SafeAccountWebAuth as SafeAccount } from "abstractionkit";

const smartAccount = SafeAccount.initializeNewAccount([webauthPublicKey])
Combine Signature Types

You can combine an EOA public address and a webauthPublicKey in the initializing function to create a multisig secured by both types.

Create Passkey UserOp​

This step follows the same flow as the normal Safe flow with createUserOperation, with the addition of the webauthn dummy signature. 

import { DummySignature } from "abstractionkit";

let userOperation = await smartAccount.createUserOperation(
    [transaction] // constructed MetaTransaction 
    jsonRpcNodeProvider, //the node rpc.
    bundlerUrl, //the bundler rpc.
    {
        dummySignatures:[DummySignature.webAuthn]
    }
)

Sign with Passkeys​

Step1: Calculate the EIP712 hash​

Calculate the Safe EIP712 hash for the UserOp

const entrypoint = "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"

const safeInitOpHash = SafeAccount.getUserOperationEip712Hash(
    userOperation,
    chainId,
    0n, // validAfter
    0n, // validUntil
    entrypoint
)

Step 2: Request a WebAuthn assertion​

Using the navigator.credentials API

import { UserVerificationRequirement } from "./webauthn";

const assertion = navigator.credentials.get({
    publicKey: {
        challenge: ethers.getBytes(safeInitOpHash),
        rpId: 'candide.dev',
        allowCredentials: [{ type: 'public-key', id: new Uint8Array(credential.rawId) }],
        userVerification: UserVerificationRequirement.required,
    },
})

Step 3: Extract WebAuthn signature data​

Extract WebAuthn signature data from the assertion response and create a signature from the extracted signature data

import { WebauthSignatureData } from "abstractionkit";
import { extractClientDataFields, extractSignature } from "./webauthn";

const webauthSignatureData: WebauthSignatureData = {
    authenticatorData: assertion.response.authenticatorData,
    clientDataFields: extractClientDataFields(assertion.response),
    rs: extractSignature(assertion.response),
}

const webauthSignature: string = SafeAccount.createWebAuthnSignature(webauthSignatureData)

Step 4: Create a Signer Signature Pair and Format​

Create a SignerSignaturePair containing the webauthPublicKey and webauthSignature, and format the SignerSignaturePair into the expected format for the userOperation signature

import { SignerSignaturePair } from "abstractionkit";

const signerSignaturePair: SignerSignaturePair = {
    signer: webauthPublicKey,
    signature: webauthSignature,
}

userOperation.signature = SafeAccount.formatSignaturesToUseroperationSignature(
    [signerSignaturePair],
    userOperation.nonce == 0n
)

Additional Notes​

Saving Public Credentials​

It's crucial to securely store the Passkey's public credentials, specifically x, y, and rawId, in a retrievable location. Losing this data would mean users can't recover their accounts with Passkeys. This information isn't sensitive, so you can set up a server using @simplewebauthn/server for this purpose.

Sync & Recovery​

Apple​

Passkey recovery on Apple devices involves iCloud Keychain escrow. In case of device loss, users authenticate through their iCloud account using standard procedure. After authentication, they enter their device passcode. Apple users also has the option to add an account recovery contact for additional support. Learn more on Apple Passkeys security

Google​

Google Password Manager seamlessly syncs passkeys across devices, with plans to extend syncing support to a broader range of operating systems. Learn more on Google Passkeys security

Yubikey​

YubiKey is compatible with passkeys through its support for the authentication protocol. Passkeys can be protected and managed using YubiKey's hardware-based security features. Learn more on Yubico

Password Managers​

Passkey backups are not limited to hardware manufactures, they are supported across different password managers like Windows Hello, Bitwarden, ProtonPass, 1Password, LastPass and others.

Device Support​

Passkeys are widely available across devices such as:

  • Apple Devices: iPhones & iPads (iOS 16+), Mac (macOS 13+)
  • Android Devices: Phones and tablets (Android 9+)
  • Windows (10/11/+): Supported on Chrome, Brave, Edge, and Firefox browsers
  • Linux: Supported on Chrome, Firefox, Edge, and Brave browsers

For a comprehensive list of supported systems, please visit passkeys.dev/device-support