Expand description
ic_siwe is a Rust library that facilitates the integration of Ethereum wallet-based authentication with applications on the Internet Computer (ICP) platform. The library provides all necessary tools for integrating Sign-In with Ethereum (SIWE) into ICP canisters, from generating SIWE messages to creating delegate identities.
ic_siwe is part of the ic-siwe project. The goal of the project is to enhance the interoperability between Ethereum and the Internet Computer platform, enabling developers to build applications that leverage the strengths of both platforms.
§Key Features
- Ethereum Wallet Sign-In: Enables Ethereum wallet sign-in for ICP applications. Sign in with any eth wallet to generate an ICP identity and session.
- Session Identity Uniqueness: Ensures that session identities are specific to each application’s context, preventing cross-app identity misuse.
- Consistent Principal Generation: Guarantees that logging in with an Ethereum wallet consistently produces the same Principal, irrespective of the client used.
- Direct Ethereum Address to Principal Mapping: Creates a one-to-one correlation between Ethereum addresses and Principals within the scope of the current application.
- Timebound Sessions: Allows developers to set expiration times for sessions, enhancing security and control.
§Table of Contents
- Key Features
- Table of Contents
- Prebuilt
ic_siwe_providercanister - React demo application
- The SIWE Standard
- Login flow
- Crate features
- Updates
- Contributing
- Author
- License
§Prebuilt ic_siwe_provider canister
While the ic_siwe library can be integrated with any Rust based ICP project, using the pre built ic-siwe-provider canister is the easiest way to integrate Ethereum wallet authentication into your application.
The canister is designed as a plug-and-play solution for developers, enabling easy integration into existing ICP applications with minimal coding requirements. By adding the pre built ic_siwe_provider canister to the dfx.json of an ICP project, developers can quickly enable Ethereum wallet-based authentication for their applications. The canister simplifies the authentication flow by managing the creation and verification of SIWE messages and handling user session management.
§React demo application
A demo application that uses the ic_siwe_provider canister to demonstrate the full login flow is available at ic-siwe-react-demo-rust. The demo uses another package from the ic-siwe project, ic-use-siwe-identity, a React hook and context provider for easy frontend integration with SIWE enabled Internet Computer canisters.
§The SIWE Standard
ERC-4361: Sign-In with Ethereum - Off-chain authentication for Ethereum accounts to establish sessions
The SIWE standard defines a protocol for off-chain authentication of Ethereum accounts. The protocol is designed to enable Ethereum wallet-based authentication for applications on other platforms, such as the Internet Computer. At the core of the protocol is the SIWE message, which is a signed message that contains the Ethereum address of the user and some additional metadata. The SIWE message is signed by the user’s Ethereum wallet and then sent to the application’s backend. The backend verifies the signature and Ethereum address and then creates a session for the user.
ic_siwe implements most parts of the Sign In with Ethereum (SIWE standard,
EIP-4361 with some notable exceptions:
not-before,request-id,resources- Not implemented. These fields are marked as OPTIONAL in the SIWE standard and are not required for current implementation.
§Login flow
Creating a delegate identity using ic_siwe is a three-step process that consists of the following steps:
- Prepare login
- Login
- Get delegation
An implementing canister is free to implement these steps in any way it sees fit. It is recommended though that implementing canisters follow the login flow described below and implement the SIWE canister interface. Doing so ensures that the canister is compatible with the ic-use-siwe-identity React hook and context provider.
The login flow is illustrated in the following diagram:
┌────────┐ ┌────────┐ ┌─────────┐
│Frontend│ │Canister│ │EthWallet│
User └───┬────┘ └───┬────┘ └────┬────┘
│ Push login button ┌┴┐ │ │
│ ────────────────────────────>│ │ │ │
│ │ │ │ │
│ │ │ siwe_prepare_login(eth_address) ┌┴┐ │
│ │ │ ─────────────────────────────────────────────>│ │ │
│ │ │ └┬┘ │
│ │ │ OK, siwe_message │ │
│ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ │ │ │ │
│ │ │ Sign siwe_message ┌┴┐
│ │ │ ──────────────────────────────────────────────────────────────────────────────────────>│ │
│ │ │ │ │ │
│ │ │ Ask user to confirm │ │ │
│ <───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────│ │
│ │ │ │ │ │
│ │ │ OK │ │ │
│ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ >│ │
│ │ │ │ └┬┘
│ │ │ OK, signature │
│ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
│ │ │ │ │
│ │ │────┐ │ │
│ │ │ │ Generate random session_identity │ │
│ │ │<───┘ │ │
│ │ │ │ │
│ │ │ siwe_login(eth_address, │ │
│ │ │ signature, session_identity) ┌┴┐ │
│ │ │ ─────────────────────────────────────────────>│ │ │
│ │ │ │ │ │
│ │ │ │ │────┐ │
│ │ │ │ │ │ Verify signature and eth_address │
│ │ │ │ │<───┘ │
│ │ │ │ │ │
│ │ │ │ │────┐ │
│ │ │ │ │ │ Prepare delegation │
│ │ │ │ │<───┘ │
│ │ │ └┬┘ │
│ │ │ OK, canister_pubkey, delegation_expires │ │
│ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ │ │ │ │
│ │ │ siwe_get_delegation(delegation_expires) ┌┴┐ │
│ │ │ ─────────────────────────────────────────────>│ │ │
│ │ │ └┬┘ │
│ │ │ OK, delegation │ │
│ │ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│ │ │ │ │
│ │ │────┐ │ │
│ │ │ │ Create delegation identity │ │
│ │ │<───┘ │ │
│ └┬┘ │ │
│ OK, logged in with │ │ │
│ Principal niuiu-iuhbi...-oiu │ │ │
│ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │ │
User ┌───┴────┐ ┌───┴────┐ ┌────┴────┐
│Frontend│ │Canister│ │EthWallet│
└────────┘ └────────┘ └─────────┘
§siwe_prepare_login
- The
siwe_prepare_loginmethod is called by the frontend application to initiate the login flow. The method takes the user’s Ethereum address as a parameter and returns a SIWE message together with a nonce. The frontend application uses the SIWE message to prompt the user to sign the message with their Ethereum wallet. - See:
login::prepare_login
§siwe_login
- The
siwe_loginmethod is called by the frontend application after the user has signed the SIWE message. The method takes the user’s Ethereum address, signature, session identity and nonce as parameters. The method verifies the signature and Ethereum address and prepares the delegation to be fetched in the next step, thesiwe_get_delegationfunction. - See:
login::login
§siwe_get_delegation
- The
siwe_get_delegationmethod is called by the frontend application after a successful login. The method takes the delegation expiration time as a parameter and returns a delegation. - The
siwe_get_delegationmethod is not mirrored by one function in theic_siwelibrary. The creation of delegate identities requires setting the certified data of the canister. This should not be done by the library, but by the implementing canister. - Creating a delegate identity involves interacting with the following
ic_siwefunctions:delegation::generate_seed,delegation::create_delegation,delegation::create_delegation_hash,delegation::witness,delegation::create_certified_signature. - For a full implementation example, see the
ic_siwe_providercanister.
§Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
§[0.1.1] - 2024-08-28
§Changed
- Updated dependencies: ic-cdk
§[0.1.0] - 2024-08-22
This is a breaking change release that makes the nonce feature standard. The nonce feature is now enabled by default and the nonce feature flag is deprecated. This version also includes fixes to increase login flow security.
§Added
§Changed
§Fixed
§[0.0.7] - 2024-07-05
§Changed
- Updated dependencies: candid, ic-cdk, ic-cdk-timers
§[0.0.6] - 2024-03-25
§Added
- Runtime feature flag that allow for customization of the library behavior:
IncludeUriInSeed. See settings.rs for details.
§[0.0.5] - 2024-02-22
§Fixed
- Pre-built provider canister did not include metadata, now fixed.
§[0.0.4] - 2024-01-31
Aligning version numbers with ic_siwe_provider
§Added
EthAddressandEthSignaturestructs for type safety.- Added basic validation of delegation targets. Duplicate targets are now rejected.
§Changed
- Library functions now mostly returns custom error types instead of strings. As a result, many error messages now differ slighlty to previous version.
prepare_loginandloginnow requiresEthAddressandEthSignaturestructs instead of strings.- Replaced
create_user_canister_pubkeywith a more readable implementation.
§
§[0.0.1] - 2024-01-23
§Added
- First release.
ic_siwev0.0.1 should be regarded as alpha software.
§Contributing
Contributions are welcome. Please submit your pull requests or open issues to propose changes or report bugs.
§Author
- kristofer@fmckl.se
- Twitter: @kristoferlund
- Discord: kristoferkristofer
- Telegram: @kristoferkristofer
§License
This project is licensed under the MIT License. See the LICENSE file for more details.
Modules§
Macros§
- A macro to access global
Settingsconveniently within a closure.
Functions§
- Initializes the SIWE library with the provided settings. Must be called before any other SIWE functions. Use the SettingsBuilder to create a Settings object.