Cryptography

A collection of contracts and libraries that implement various signature validation schemes and cryptographic primitives. These utilities enable secure authentication, multisignature operations, and advanced cryptographic operations in smart contracts.

• ZKEmailUtils: Library for ZKEmail signature validation utilities, enabling email-based authentication through zero-knowledge proofs.
• WebAuthn: Library for verifying WebAuthn Authentication Assertions.
• DKIMRegistry: Implementation of ERC-7969 to enable onchain verification of DomainKeys Identified Mail (DKIM) signatures.
• SignerZKEmail: Implementation of an AbstractSigner that enables email-based authentication through zero-knowledge proofs.
• SignerWebAuthn: Implementation of SignerP256 that supports WebAuthn authentication assertions.
• ERC7913ZKEmailVerifier, ERC7913WebAuthnVerifier: Ready to use ERC-7913 signature verifiers for ZKEmail and WebAuthn.

Utils

ZKEmailUtils

WebAuthn

DKIMRegistry

Abstract Signers

SignerZKEmail

SignerWebAuthn

Verifiers

ERC7913ZKEmailVerifier

ERC7913WebAuthnVerifier

import "@openzeppelin/contracts/utils/cryptography/DKIMRegistry.sol";

Implementation of the ERC-7969 interface for registering and validating DomainKeys Identified Mail (DKIM) public key hashes onchain.

This contract provides a standard way to register and validate DKIM public key hashes, enabling email-based account abstraction and secure account recovery mechanisms. Domain owners can register their DKIM public key hashes and third parties can verify their validity.

The contract stores mappings of domain hashes to DKIM public key hashes, where:

• Domain hash: keccak256 hash of the lowercase domain name
• Key hash: keccak256 hash of the DKIM public key

Example of usage:

contract MyDKIMRegistry is DKIMRegistry, Ownable {
    function setKeyHash(bytes32 domainHash, bytes32 keyHash) public onlyOwner {
        _setKeyHash(domainHash, keyHash);
    }

    function setKeyHashes(bytes32 domainHash, bytes32[] memory keyHashes) public onlyOwner {
        _setKeyHashes(domainHash, keyHashes);
    }

    function revokeKeyHash(bytes32 domainHash, bytes32 keyHash) public onlyOwner {
        _revokeKeyHash(domainHash, keyHash);
    }
}

import "@openzeppelin/contracts/utils/cryptography/WebAuthn.sol";

Library for verifying WebAuthn Authentication Assertions.

WebAuthn enables strong authentication for smart contracts using P256 as an alternative to traditional secp256k1 ECDSA signatures. This library verifies signatures generated during WebAuthn authentication ceremonies as specified in the WebAuthn Level 2 standard.

For blockchain use cases, the following WebAuthn validations are intentionally omitted:

• Origin validation: Origin verification in clientDataJSON is omitted as blockchain contexts rely on authenticator and dapp frontend enforcement. Standard authenticators implement proper origin validation.
• RP ID hash validation: Verification of rpIdHash in authenticatorData against expected RP ID hash is omitted. This is typically handled by platform-level security measures. Including an expiry timestamp in signed data is recommended for enhanced security.
• Signature counter: Verification of signature counter increments is omitted. While useful for detecting credential cloning, on-chain operations typically include nonce protection, making this check redundant.
• Extension outputs: Extension output value verification is omitted as these are not essential for core authentication security in blockchain applications.
• Attestation: Attestation object verification is omitted as this implementation focuses on authentication (webauthn.get) rather than registration ceremonies.

Inspired by:

• daimo-eth implementation
• base implementation

import "@openzeppelin/contracts/utils/cryptography/ZKEmailUtils.sol";

Library for ZKEmail Groth16 proof validation utilities.

ZKEmail is a protocol that enables email-based authentication and authorization for smart contracts using zero-knowledge proofs. It allows users to prove ownership of an email address without revealing the email content or private keys.

The validation process involves several key components:

• A DKIMRegistry (DomainKeys Identified Mail) verification mechanism to ensure the email was sent from a valid domain. Defined by an IDKIMRegistry interface.
• A command template validation mechanism to ensure the email command matches the expected format and parameters.
• A zero-knowledge proof verification mechanism to ensure the email was actually sent and received without revealing its contents. Defined by an IGroth16Verifier interface.

import "@openzeppelin/contracts/utils/cryptography/signers/SignerWebAuthn.sol";

Implementation of SignerP256 that supports WebAuthn authentication assertions.

This contract enables signature validation using WebAuthn authentication assertions, leveraging the P256 public key stored in the contract. It allows for both WebAuthn and raw P256 signature validation, providing compatibility with both signature types.

The signature is expected to be an abi-encoded WebAuthn.WebAuthnAuth struct.

Example usage:

contract MyAccountWebAuthn is Account, SignerWebAuthn, Initializable {
    function initialize(bytes32 qx, bytes32 qy) public initializer {
        _setSigner(qx, qy);
    }
}

or during initialization (if used as a clone) may leave the signer either front-runnable or unusable.

import "@openzeppelin/contracts/utils/cryptography/signers/SignerZKEmail.sol";

Implementation of AbstractSigner using ZKEmail signatures.

ZKEmail enables secure authentication and authorization through email messages, leveraging DKIM signatures from a DKIMRegistry and zero-knowledge proofs enabled by a SignerZKEmail.verifier contract that ensures email authenticity without revealing sensitive information. The DKIM registry is trusted to correctly update DKIM keys, but users can override this behaviour and set their own keys. This contract implements the core functionality for validating email-based signatures in smart contracts.

Developers must set the following components during contract initialization:

• SignerZKEmail.accountSalt - A unique identifier derived from the user's email address and account code.
• DKIMRegistry - An instance of the DKIM registry contract for domain verification.
• SignerZKEmail.verifier - An instance of the Groth16Verifier contract for zero-knowledge proof validation.

Example of usage:

contract MyAccountZKEmail is Account, SignerZKEmail, Initializable {
  function initialize(
      bytes32 accountSalt,
      IDKIMRegistry registry,
      IGroth16Verifier groth16Verifier
  ) public initializer {
      // Will revert if the signer is already initialized
      _setAccountSalt(accountSalt);
      _setDKIMRegistry(registry);
      _setVerifier(groth16Verifier);
  }
}

either during construction (if used standalone) or during initialization (if used as a clone) may leave the signer either front-runnable or unusable.

import "@openzeppelin/contracts/utils/cryptography/verifiers/ERC7913WebAuthnVerifier.sol";

ERC-7913 signature verifier that supports WebAuthn authentication assertions.

This verifier enables the validation of WebAuthn signatures using P256 public keys. The key is expected to be a 64-byte concatenation of the P256 public key coordinates (qx || qy). The signature is expected to be an abi-encoded WebAuthn.WebAuthnAuth struct.

Uses WebAuthn-verifyMinimal for signature verification, which performs the essential WebAuthn checks: type validation, challenge matching, and cryptographic signature verification.

NOTE: Wallets that may require default P256 validation may install a P256 verifier separately.

import "@openzeppelin/contracts/utils/cryptography/verifiers/ERC7913ZKEmailVerifier.sol";

ERC-7913 signature verifier that supports ZKEmail accounts.

This contract verifies signatures produced through ZKEmail's zero-knowledge proofs which allows users to authenticate using their email addresses.

The key decoding logic is customizable: users may override the ERC7913ZKEmailVerifier._decodeKey function to enforce restrictions or validation on the decoded values (e.g., requiring a specific verifier or registry). To remain compliant with ERC-7913's statelessness, it is recommended to enforce such restrictions using immutable variables only.

Example of overriding _decodeKey to enforce a specific verifier, registry:

  function _decodeKey(bytes calldata key) internal view override returns (
      IDKIMRegistry registry,
      bytes32 accountSalt,
      IGroth16Verifier verifier
  ) {
      (registry, accountSalt, verifier) = super._decodeKey(key);
      require(verifier == _verifier, "Invalid verifier");
      require(registry == _registry, "Invalid registry");
      return (registry, accountSalt, verifier);
  }

bytes memory signature = abi.encode(EmailProof({
    domainName: "example.com", // The domain name of the email sender
    publicKeyHash: bytes32(0x...), // Hash of the DKIM public key used to sign the email
    timestamp: block.timestamp, // When the email was sent
    maskedCommand: "signHash 12345...", // The command being executed, with sensitive data masked
    emailNullifier: bytes32(0x...), // Unique identifier for the email to prevent replay attacks
    accountSalt: bytes32(0x...), // Unique identifier derived from email and account code
    isCodeExist: true, // Whether the account code exists in the proof
    proof: bytes(0x...) // The zero-knowledge proof verifying the email's authenticity
}));

bytes memory key = abi.encode(registry, accountSalt, verifier);