Implement RSA verification (#4952)

Co-authored-by: Ernesto García <ernestognw@gmail.com>
Co-authored-by: cairo <cairoeth@protonmail.com>

.changeset/curvy-crabs-repeat.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`RSA`: Library to verify signatures according to RFC 8017 Signature Verification Operation

contracts/mocks/Stateless.sol

@@ -27,6 +27,7 @@ import {MerkleProof} from "../utils/cryptography/MerkleProof.sol";
 import {MessageHashUtils} from "../utils/cryptography/MessageHashUtils.sol";
 import {Panic} from "../utils/Panic.sol";
 import {Packing} from "../utils/Packing.sol";
+import {RSA} from "../utils/cryptography/RSA.sol";
 import {SafeCast} from "../utils/math/SafeCast.sol";
 import {SafeERC20} from "../token/ERC20/utils/SafeERC20.sol";
 import {ShortStrings} from "../utils/ShortStrings.sol";

contracts/utils/cryptography/RSA.sol

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Math} from "../math/Math.sol";
+
+/**
+ * @dev RSA PKCS#1 v1.5 signature verification implementation according to https://datatracker.ietf.org/doc/html/rfc8017[RFC8017].
+ *
+ * This library supports PKCS#1 v1.5 padding to avoid malleability via chosen plaintext attacks in practical implementations.
+ * The padding follows the EMSA-PKCS1-v1_5-ENCODE encoding definition as per section 9.2 of the RFC. This padding makes
+ * RSA semanticaly secure for signing messages.
+ *
+ * Inspired by https://github.com/adria0/SolRsaVerify[Adrià Massanet's work]
+ */
+library RSA {
+    /**
+     * @dev Same as {pkcs1} but using SHA256 to calculate the digest of `data`.
+     */
+    function pkcs1Sha256(
+        bytes memory data,
+        bytes memory s,
+        bytes memory e,
+        bytes memory n
+    ) internal view returns (bool) {
+        return pkcs1(sha256(data), s, e, n);
+    }
+
+    /**
+     * @dev Verifies a PKCSv1.5 signature given a digest according the verification
+     * method described in https://datatracker.ietf.org/doc/html/rfc8017#section-8.2.2[section 8.2.2 of RFC8017].
+     *
+     * IMPORTANT: Although this function allows for it, using n of length 1024 bits is considered unsafe.
+     * Consider using at least 2048 bits.
+     *
+     * WARNING: PKCS#1 v1.5 allows for replayability given the message may contain arbitrary optional parameters in the
+     * DigestInfo. Consider using an onchain nonce or unique identifier to include in the message to prevent replay attacks.
+     *
+     * @param digest the digest to verify
+     * @param s is a buffer containing the signature
+     * @param e is the exponent of the public key
+     * @param n is the modulus of the public key
+     */
+    function pkcs1(bytes32 digest, bytes memory s, bytes memory e, bytes memory n) internal view returns (bool) {
+        unchecked {
+            // cache and check length
+            uint256 length = n.length;
+            if (
+                length < 0x40 || // PKCS#1 padding is slightly less than 0x40 bytes at the bare minimum
+                length != s.length // signature must have the same length as the finite field
+            ) {
+                return false;
+            }
+
+            // Verify that s < n to ensure there's only one valid signature for a given message
+            for (uint256 i = 0; i < length; i += 0x20) {
+                uint256 p = Math.min(i, length - 0x20);
+                bytes32 sp = _unsafeReadBytes32(s, p);
+                bytes32 np = _unsafeReadBytes32(n, p);
+                if (sp < np) {
+                    // s < n in the upper bits (everything before is equal) → s < n globally: ok
+                    break;
+                } else if (sp > np || p == length - 0x20) {
+                    // s > n in the upper bits (everything before is equal) → s > n globally: fail
+                    // or
+                    // s = n and we are looking at the lower bits → s = n globally: fail
+                    return false;
+                }
+            }
+
+            // RSAVP1 https://datatracker.ietf.org/doc/html/rfc8017#section-5.2.2
+            // The previous check guarantees that n > 0. Therefore modExp cannot revert.
+            bytes memory buffer = Math.modExp(s, e, n);
+
+            // Check that buffer is well encoded:
+            // buffer ::= 0x00 | 0x01 | PS | 0x00 | DigestInfo
+            //
+            // With
+            // - PS is padding filled with 0xFF
+            // - DigestInfo ::= SEQUENCE {
+            //    digestAlgorithm AlgorithmIdentifier,
+            //      [optional algorithm parameters]
+            //    digest OCTET STRING
+            // }
+
+            // Get AlgorithmIdentifier from the DigestInfo, and set the config accordingly
+            // - params: includes 00 + first part of DigestInfo
+            // - mask: filter to check the params
+            // - offset: length of the suffix (including digest)
+            bytes32 params; // 0x00 | DigestInfo
+            bytes32 mask;
+            uint256 offset;
+
+            // Digest is expected at the end of the buffer. Therefore if NULL param is present,
+            // it should be at 32 (digest) + 2 bytes from the end. To those 34 bytes, we add the
+            // OID (9 bytes) and its length (2 bytes) to get the position of the DigestInfo sequence,
+            // which is expected to have a length of 0x31 when the NULL param is present or 0x2f if not.
+            if (bytes1(_unsafeReadBytes32(buffer, length - 50)) == 0x31) {
+                offset = 0x34;
+                // 00 (1 byte) | SEQUENCE length (0x31) = 3031 (2 bytes) | SEQUENCE length (0x0d) = 300d (2 bytes) | OBJECT_IDENTIFIER length (0x09) = 0609 (2 bytes)
+                // SHA256 OID = 608648016503040201 (9 bytes) | NULL = 0500 (2 bytes) (explicit) | OCTET_STRING length (0x20) = 0420 (2 bytes)
+                params = 0x003031300d060960864801650304020105000420000000000000000000000000;
+                mask = 0xffffffffffffffffffffffffffffffffffffffff000000000000000000000000; // (20 bytes)
+            } else if (bytes1(_unsafeReadBytes32(buffer, length - 48)) == 0x2F) {
+                offset = 0x32;
+                // 00 (1 byte) | SEQUENCE length (0x2f) = 302f (2 bytes) | SEQUENCE length (0x0b) = 300b (2 bytes) | OBJECT_IDENTIFIER length (0x09) = 0609 (2 bytes)
+                // SHA256 OID = 608648016503040201 (9 bytes) | NULL = <implicit> | OCTET_STRING length (0x20) = 0420 (2 bytes)
+                params = 0x00302f300b060960864801650304020104200000000000000000000000000000;
+                mask = 0xffffffffffffffffffffffffffffffffffff0000000000000000000000000000; // (18 bytes)
+            } else {
+                // unknown
+                return false;
+            }
+
+            // Length is at least 0x40 and offset is at most 0x34, so this is safe. There is always some padding.
+            uint256 paddingEnd = length - offset;
+
+            // The padding has variable (arbitrary) length, so we check it byte per byte in a loop.
+            // This is required to ensure non-malleability. Not checking would allow an attacker to
+            // use the padding to manipulate the message in order to create a valid signature out of
+            // multiple valid signatures.
+            for (uint256 i = 2; i < paddingEnd; ++i) {
+                if (bytes1(_unsafeReadBytes32(buffer, i)) != 0xFF) {
+                    return false;
+                }
+            }
+
+            // All the other parameters are small enough to fit in a bytes32, so we can check them directly.
+            return
+                bytes2(0x0001) == bytes2(_unsafeReadBytes32(buffer, 0x00)) && // 00 | 01
+                // PS was checked in the loop
+                params == _unsafeReadBytes32(buffer, paddingEnd) & mask && // DigestInfo
+                // Optional parameters are not checked
+                digest == _unsafeReadBytes32(buffer, length - 0x20); // Digest
+        }
+    }
+
+    /// @dev Reads a bytes32 from a bytes array without bounds checking.
+    function _unsafeReadBytes32(bytes memory array, uint256 offset) private pure returns (bytes32 result) {
+        // Memory safetiness is guaranteed as long as the provided `array` is a Solidity-allocated bytes array
+        // and `offset` is within bounds. This is the case for all calls to this private function from {pkcs1}.
+        assembly ("memory-safe") {
+            result := mload(add(add(array, 0x20), offset))
+        }
+    }
+}

docs/modules/ROOT/pages/utilities.adoc

@@ -8,6 +8,10 @@ Here are some of the more popular ones.
 
 === Checking Signatures On-Chain
 
+At a high level, signatures are a set of cryptographic algorithms that allow for a _signer_ to prove himself owner of a _private key_ used to authorize an piece of information (generally a transaction or `UserOperation`). Natively, the EVM supports the Elliptic Curve Digital Signature Algorithm (https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm[ECDSA]) using the secp256r1 field, however other signature algorithms such as RSA are supported.
+
+==== Ethereum Signatures (secp256r1)
+
 xref:api:utils.adoc#ECDSA[`ECDSA`] provides functions for recovering and managing Ethereum account ECDSA signatures. These are often generated via https://web3js.readthedocs.io/en/v1.7.3/web3-eth.html#sign[`web3.eth.sign`], and are a 65 byte array (of type `bytes` in Solidity) arranged the following way: `[[v (1)], [r (32)], [s (32)]]`.
 
 The data signer can be recovered with xref:api:utils.adoc#ECDSA-recover-bytes32-bytes-[`ECDSA.recover`], and its address compared to verify the signature. Most wallets will hash the data to sign and add the prefix `\x19Ethereum Signed Message:\n`, so when attempting to recover the signer of an Ethereum signed message hash, you'll want to use xref:api:utils.adoc#MessageHashUtils-toEthSignedMessageHash-bytes32-[`toEthSignedMessageHash`].
@@ -26,6 +30,32 @@ function _verify(bytes32 data, bytes memory signature, address account) internal
 
 WARNING: Getting signature verification right is not trivial: make sure you fully read and understand xref:api:utils.adoc#MessageHashUtils[`MessageHashUtils`]'s and xref:api:utils.adoc#ECDSA[`ECDSA`]'s documentation.
 
+==== RSA
+
+RSA a public-key cryptosystem that was popularized by corporate and governmental public key infrastructures (https://en.wikipedia.org/wiki/Public_key_infrastructure[PKIs]) and https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions[DNSSEC]. 
+
+This cryptosystem consists of using a private key that's the product of 2 large prime numbers. The message is signed by applying a modular exponentiation to its hash (commonly SHA256), where both the exponent and modulus compose the public key of the signer.
+
+RSA signatures are known for being less efficient than elliptic curve signatures given the size of the keys, which are big compared to ECDSA keys with the same security level. Using plain RSA is considered unsafe, this is why the implementation uses the `EMSA-PKCS1-v1_5` encoding method from https://datatracker.ietf.org/doc/html/rfc8017[RFC8017] to include padding to the signature.
+
+To verify a signature using RSA, you can leverage the xref:api:utils.adoc#RSA[`RSA`] library that exposes a method for verifying RSA with the PKCS 1.5 standard:
+
+[source,solidity]
+----
+using RSA for bytes32;
+
+function _verify(
+    bytes32 data,
+    bytes memory signature,
+    bytes memory e,
+    bytes memory n
+) internal pure returns (bool) {
+    return data.pkcs1(signature, e, n);
+}
+----
+
+IMPORTANT: Always use keys of at least 2048 bits. Additionally, be aware that PKCS#1 v1.5 allows for replayability due to the possibility of arbitrary optional parameters. To prevent replay attacks, consider including an onchain nonce or unique identifier in the message.
+
 === Verifying Merkle Proofs
 
 Developers can build a Merkle Tree off-chain, which allows for verifying that an element (leaf) is part of a set by using a Merkle Proof. This technique is widely used for creating whitelists (e.g. for airdrops) and other advanced use cases.

test/utils/cryptography/RSA.helper.js

@@ -0,0 +1,17 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function* parse(file) {
+  const cache = {};
+  const data = fs.readFileSync(path.resolve(__dirname, file), 'utf8');
+  for (const line of data.split('\r\n')) {
+    const groups = line.match(/^(?<key>\w+) = (?<value>\w+)(?<extra>.*)$/)?.groups;
+    if (groups) {
+      const { key, value, extra } = groups;
+      cache[key] = value;
+      if (groups.key === 'Result') {
+        yield Object.assign({ extra: extra.trim() }, cache);
+      }
+    }
+  }
+};

test/utils/cryptography/RSA.test.js

@@ -0,0 +1,97 @@
+const { ethers } = require('hardhat');
+const { expect } = require('chai');
+const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
+
+const parse = require('./RSA.helper');
+
+async function fixture() {
+  return { mock: await ethers.deployContract('$RSA') };
+}
+
+describe('RSA', function () {
+  beforeEach(async function () {
+    Object.assign(this, await loadFixture(fixture));
+  });
+
+  // Load test cases from file SigVer15_186-3.rsp from:
+  // https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Algorithm-Validation-Program/documents/dss/186-2rsatestvectors.zip
+  describe('SigVer15_186-3.rsp tests', function () {
+    for (const test of parse('SigVer15_186-3.rsp')) {
+      const { length } = Buffer.from(test.S, 'hex');
+
+      /// For now, RSA only supports digest that are 32bytes long. If we ever extend that, we can use these hashing functions for @noble:
+      // const { sha1 } = require('@noble/hashes/sha1');
+      // const { sha224, sha256 } = require('@noble/hashes/sha256');
+      // const { sha384, sha512 } = require('@noble/hashes/sha512');
+
+      if (test.SHAAlg === 'SHA256') {
+        const result = test.Result === 'P';
+
+        it(`signature length ${length} ${test.extra} ${result ? 'works' : 'fails'}`, async function () {
+          const data = '0x' + test.Msg;
+          const sig = '0x' + test.S;
+          const exp = '0x' + test.e;
+          const mod = '0x' + test.n;
+
+          expect(await this.mock.$pkcs1(ethers.sha256(data), sig, exp, mod)).to.equal(result);
+          expect(await this.mock.$pkcs1Sha256(data, sig, exp, mod)).to.equal(result);
+        });
+      }
+    }
+  });
+
+  describe('others tests', function () {
+    it('openssl', async function () {
+      const data = ethers.toUtf8Bytes('hello world');
+      const sig =
+        '0x079bed733b48d69bdb03076cb17d9809072a5a765460bc72072d687dba492afe951d75b814f561f253ee5cc0f3d703b6eab5b5df635b03a5437c0a5c179309812f5b5c97650361c645bc99f806054de21eb187bc0a704ed38d3d4c2871a117c19b6da7e9a3d808481c46b22652d15b899ad3792da5419e50ee38759560002388';
+      const exp =
+        '0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010001';
+      const mod =
+        '0xdf3edde009b96bc5b03b48bd73fe70a3ad20eaf624d0dc1ba121a45cc739893741b7cf82acf1c91573ec8266538997c6699760148de57e54983191eca0176f518e547b85fe0bb7d9e150df19eee734cf5338219c7f8f7b13b39f5384179f62c135e544cb70be7505751f34568e06981095aeec4f3a887639718a3e11d48c240d';
+      expect(await this.mock.$pkcs1Sha256(data, sig, exp, mod)).to.be.true;
+    });
+
+    // According to RFC4055, pg.5 and RFC8017, pg. 64, for SHA-1, and the SHA-2 family,
+    // the algorithm parameter has to be NULL and both explicit NULL parameter and implicit
+    // NULL parameter (ie, absent NULL parameter) are considered to be legal and equivalent.
+    it('rfc8017 implicit null parameter', async function () {
+      const data = ethers.toUtf8Bytes('hello world!');
+      const sig =
+        '0xa0073057133ff3758e7e111b4d7441f1d8cbe4b2dd5ee4316a14264290dee5ed7f175716639bd9bb43a14e4f9fcb9e84dedd35e2205caac04828b2c053f68176d971ea88534dd2eeec903043c3469fc69c206b2a8694fd262488441ed8852280c3d4994e9d42bd1d575c7024095f1a20665925c2175e089c0d731471f6cc145404edf5559fd2276e45e448086f71c78d0cc6628fad394a34e51e8c10bc39bfe09ed2f5f742cc68bee899d0a41e4c75b7b80afd1c321d89ccd9fe8197c44624d91cc935dfa48de3c201099b5b417be748aef29248527e8bbb173cab76b48478d4177b338fe1f1244e64d7d23f07add560d5ad50b68d6649a49d7bc3db686daaa7';
+      const exp = '0x03';
+      const mod =
+        '0xe932ac92252f585b3a80a4dd76a897c8b7652952fe788f6ec8dd640587a1ee5647670a8ad4c2be0f9fa6e49c605adf77b5174230af7bd50e5d6d6d6d28ccf0a886a514cc72e51d209cc772a52ef419f6a953f3135929588ebe9b351fca61ced78f346fe00dbb6306e5c2a4c6dfc3779af85ab417371cf34d8387b9b30ae46d7a5ff5a655b8d8455f1b94ae736989d60a6f2fd5cadbffbd504c5a756a2e6bb5cecc13bca7503f6df8b52ace5c410997e98809db4dc30d943de4e812a47553dce54844a78e36401d13f77dc650619fed88d8b3926e3d8e319c80c744779ac5d6abe252896950917476ece5e8fc27d5f053d6018d91b502c4787558a002b9283da7';
+      expect(await this.mock.$pkcs1Sha256(data, sig, exp, mod)).to.be.true;
+    });
+
+    it('returns false for a very short n', async function () {
+      const data = ethers.toUtf8Bytes('hello world!');
+      const sig = '0x0102';
+      const exp = '0x03';
+      const mod = '0x0405';
+      expect(await this.mock.$pkcs1Sha256(data, sig, exp, mod)).to.be.false;
+    });
+
+    it('returns false for a signature with different length to n', async function () {
+      const data = ethers.toUtf8Bytes('hello world!');
+      const sig = '0x00112233';
+      const exp = '0x03';
+      const mod =
+        '0xe932ac92252f585b3a80a4dd76a897c8b7652952fe788f6ec8dd640587a1ee5647670a8ad4c2be0f9fa6e49c605adf77b5174230af7bd50e5d6d6d6d28ccf0a886a514cc72e51d209cc772a52ef419f6a953f3135929588ebe9b351fca61ced78f346fe00dbb6306e5c2a4c6dfc3779af85ab417371cf34d8387b9b30ae46d7a5ff5a655b8d8455f1b94ae736989d60a6f2fd5cadbffbd504c5a756a2e6bb5cecc13bca7503f6df8b52ace5c410997e98809db4dc30d943de4e812a47553dce54844a78e36401d13f77dc650619fed88d8b3926e3d8e319c80c744779ac5d6abe252896950917476ece5e8fc27d5f053d6018d91b502c4787558a002b9283da7';
+      expect(await this.mock.$pkcs1Sha256(data, sig, exp, mod)).to.be.false;
+    });
+
+    it('returns false if s >= n', async function () {
+      // this is the openssl example where sig has been replaced by sig + mod
+      const data = ethers.toUtf8Bytes('hello world');
+      const sig =
+        '0xe6dacb53450242618b3e502a257c08acb44b456c7931988da84f0cda8182b435d6d5453ac1e72b07c7dadf2747609b7d544d15f3f14081f9dbad9c48b7aa78d2bdafd81d630f19a0270d7911f4ec82b171e9a95889ffc9e740dc9fac89407a82d152ecb514967d4d9165e67ce0d7f39a3082657cdfca148a5fc2b3a7348c4795';
+      const exp =
+        '0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010001';
+      const mod =
+        '0xdf3edde009b96bc5b03b48bd73fe70a3ad20eaf624d0dc1ba121a45cc739893741b7cf82acf1c91573ec8266538997c6699760148de57e54983191eca0176f518e547b85fe0bb7d9e150df19eee734cf5338219c7f8f7b13b39f5384179f62c135e544cb70be7505751f34568e06981095aeec4f3a887639718a3e11d48c240d';
+      expect(await this.mock.$pkcs1Sha256(data, sig, exp, mod)).to.be.false;
+    });
+  });
+});