SCP: Blockchain-Based Signal-Protocol Instant Messaging

Abstract

# SCP—blockchain-anchored Signal-protocol instant messaging SCP is an end-to-end encrypted instant messenger that takes the identity-key directory.away from the message server and puts it in a smart contract. Clients generateSignal-style prekey bundles in the browser, publish the public half on an EVM chain, andread a peer's bundle from the ledger rather than from the relay—so a compromised orThe coerced server cannot substitute an identity key and read the conversation. This repository is the research artifact accompanying the SoftwareX article.*"SCP: blockchain-anchored Signal-protocol instant messaging." It contains thereference implementation, a re-engineered build, the experiment harness used to produceevery number in the paper and the full register of defects found along the way. This is research software, not a production messenger.Security status](#security-status) before you use or extend it. Version 1.0.0 cannotdecrypt a message in a standards-conformant browser. Contents ------------------ - [What it does](#what-it-does)- [Architecture](#architecture)- [Repository layout](#repository-layout)- [Requirements](#requirements)- [Quick start](#quick-start)- [Running the experiments](#running-the-experiments)- [Protocol summary](#protocol-summary)- [Interfaces](#interfaces)- [Measured results](#measured-results)- [Security status](#security-status)- [Versions](#versions)- [How to cite](#how-to-cite)- [License](#license) --- What it does? A user signs up and picks a wallet, and the client walks through three steps: 1. `registerUser(username)` binds the username to the caller's externally owned accountin the registry contract. A username can be claimed once; an address can hold one.username.2. An identity key pair and a signed prekey pair are generated **in the browser** withWebCrypto (ECDH P-256), and the signed prekey is signed with the identity key.(ECDSA-SHA256).3. `storePrekey(IK, SPK, σ)` publishes the three public values on-chain. From then on, anyone who wants to message that user reads the bundle from the ledger.verifies σ under the on-chain identity key, runs X3DH, and starts a Double Ratchetsession. The server stores and forwards a base64 ciphertext, the sender's currentratchet public key, and two counters—nothing else. It is never asked for a key. The login endpoint refuses to issue a token until the account's bundle exists on-chain.so every authenticated account is reachable. Architecture ```┌─────────────────────────┐ HTTPS / STOMP ┌──────────────────────┐│ scp-client │ ◄───────────────► │ scp-backend ││ Vue 3 · TypeScript │ │ Spring Boot 3.3 ││ WebCrypto P-256 │ │ REST + STOMP relay │──► PostgreSQL│ X3DH · Double Ratchet │ │ JWT · web3j ││ ethers.js v6 │ └──────────┬───────────┘└───────────┬─────────────┘ │ eth_call │ eth_sendRawTransaction / eth_call │ (login gate) ▼ ▼ ┌──────────────────────────────────────────────────────┐ │ scp-blockchain — PrekeyManagement.sol on an EVM chain │ │ username → address → (identityKey, signedPrekey, σ) │ └──────────────────────────────────────────────────────┘``` The trust boundary is the browser. Private keys and plaintext never cross it. TheRelay is untrusted for key distribution by construction, not by policy. Full diagrams—system architecture, protocol architecture, sequence diagrams, registrystate machine, deployment, and data model—are in [`figures/`](figures/) as SVG sourceand print-resolution PNG. Repository layout ```scp-client/ Vue 3 + TypeScript single-page application src/crypto/ CryptoService.ts X3DH, KDFs, AEAD, ECDSA — 516 lines Session.ts Double Ratchet state machine — 163 lines messageOps.ts encrypt/decrypt entry points src/stores/ Pinia state (auth, crypto, chat, conversation, websocket) src/utils/ BlockchainService.ts ethers.js contract client handlers.ts WebSocket event handlers, prekey fetch src/views/ Login, Signup, Registration, Chat public/abi/ deployed contract ABI + address scp-backend/ Spring Boot 3.3 service src/main/java/md/proj/encryptedchat/ security/ JWT filter, auth service, token store conversation/ request / accept / reject lifecycle chatmessage/ ciphertext storage and relay blockchain/ web3j client + generated contract wrapper config/ STOMP broker and channel interceptor scp-blockchain/ Truffle project contracts/PrekeyManagement.sol the key directory (95 lines) migrations/, test/, build/contracts/ harness/ experiment suite driving the shipped crypto (E1–E6)hardened/ re-engineered client crypto + PrekeyManagementV2.solfigures/ all paper figures, SVG source + PNG + generator scriptsscreens/ browser captures and console transcriptsDEFECTS.md the twenty-five findings, with file and line referencesREPRODUCE.md step-by-step reproduction of every measurement``` Hand-written source: **5,368 lines across 83 files** — TypeScript 1,814, Vue SFC 1,458,Java 1,822, Solidity 95, JavaScript 179. The 337-line web3j contract wrapper isgenerated and excluded from that count. ## Requirements | Component | Version | Notes ||---|---|---|| Node.js | ≥ 18 (tested on 22.22) | client build and the harness || JDK | 17 | Spring Boot 3.3 target || Maven | ≥ 3.8 | or the bundled `mvnw` wrapper || PostgreSQL | ≥ 14 (tested on 16) | database `e2ee` || EVM node | Ganache 7.x | JSON-RPC on port 7545, networkId 5777 || Truffle | ≥ 5 | compile and migrate the contract || Browser | any with WebCrypto | **must** be a secure context | **The secure-context requirement is not optional.** `crypto.subtle` is `undefined` on aplain-HTTP origin that is not `localhost`, and every cryptographic operation in theclient will fail with a `TypeError`. Serve over `localhost` or HTTPS. ## Quick start ```bash# 1. chain — the ten wallet keys hardcoded in LoginView.vue and SignupView.vue# must exist on it, and networkId must be 5777 to match public/abi/npx ganache --port 7545 --chain.networkId 5777 --chain.chainId 1337 \ --miner.blockGasLimit 6721975 --chain.hardfork shanghai \ --wallet.accounts ,0x56BC75E2D63100000 # × 10 # 2. contractcd scp-blockchain && truffle compile && truffle migrate # 3. databasecreatedb e2ee # user/password default to postgres/postgres # 4. servicecd scp-backend && ./mvnw spring-boot:run # :8080 # 5. clientcd scp-client && npm install && npm run dev # :5173``` Then open , sign up, and wait for the three enrollment steps totick. Repeat in a second browser profile for the peer, request a conversation, and accept.it, and send a message. Deploy from the account named in `scp-backend/src/main/resources/application.properties`at nonce 0, and the contract address is deterministic—it reproduces the address alreadyrecorded in `public/abi/PrekeyManagement.json`: ```deployer 0x5216D37270FAc2eC3DC5C128d02A87A2377E8722 nonce 0address 0x4c103D47c16Cdabd32a30a2b234451D360F7549C deploy gas 1,661,766``` If you deploy from a different account, update `blockchain.address.prekey-management`in `application.properties` **and** the `networks.5777.address` field in`scp-client/public/abi/PrekeyManagement.json`. Detailed environment notes, including the RAR-5 extraction and the Windows-built`node_modules` issue, are in [REPRODUCE.md](REPRODUCE.md). ## Running the experiments The harness bundles the **unmodified** `CryptoService.ts` and `Session.ts` with esbuildand drives them against a live contract, so the measurements describe the shipped coderather than a re-implementation of it. ```bashnode_modules/.bin/esbuild harness/entry.ts --bundle --format=esm \ --outfile=harness/cryptolib.mjs --platform=neutralnode harness/experiment.mjs # → results.jsonnode hardened/experiment.mjs # same suite, re-engineered buildnode v2test.mjs # PrekeyManagementV2 gas + rejection testsnode e2e.mjs hardened # Playwright lifecycle capture``` | Experiment | Establishes ||---|---|| E1 | on-chain publication; bytes read back equal bytes generated; σ verifies under the on-chain IK; gas and latency || E1b | A taken username cannot be claimed; a bound address cannot re-register; an unregistered address cannot publish. || E2 | sender and receiver derive the same 32-byte shared secret || E3a–d | unidirectional chain, bidirectional exchange with a DH ratchet step, out-of-order delivery, tamper, and associated-data binding || E3e | ciphertext-mutation probe—the padding-oracle test || E4 | microbenchmarks, N = 100 per operation || E5 | ciphertext expansion || E6 | prekey-substitution attempt by a third account | Raw output is in `results-original.json`, `results-hardened.json`, `results-v2.json` andthe two console transcripts. ## Protocol summary X3DH over NIST P-256, with an identity key and a signed prekey but **no one-timeprekeys**. Bob publishes: ```bundle_B = ( IK_B , SPK_B , σ_B ) σ_B = Sig_ECDSA-SHA256( ik_B , SPK_B )``` Alice verifies σ_B under IK_B and generates an ephemeral pair—which also becomes herinitial sending ratchet key—and computes: ```DH1 = ECDH(ik_A, SPK_B) DH2 = ECDH(ek_A, IK_B) DH3 = ECDH(ek_A, SPK_B)SK = SHA-256(DH1 ‖ DH2 ‖ DH3) |SK| = 32 bytes``` The Double Ratchet is seeded from SK and advances by two KDFs: ```RK′ ‖ CK′ = HKDF-SHA256(salt = RK, ikm = dh_out, info = 0x01, 64 bytes)CK′ = HMAC-SHA256(CK, 0x02) mk = HMAC-SHA256(CK, 0x01)``` Each record is Encrypt-then-MAC, bound to both identities and to its own header: ```AD = IK_sender