From 8dd902028526a5718c3e10715a816e0344691d43 Mon Sep 17 00:00:00 2001 From: Yuliia Aritkulova <94910987+aritkulova@users.noreply.github.com> Date: Mon, 25 Nov 2024 14:08:30 +0200 Subject: [PATCH] Added ECDSA384 and RSASSAPSS docs (#30) * Added ECDSA384 and RSASSAPSS docs * fixed typos * fix overview --------- Co-authored-by: Artem Chystiakov --- docs/getting-started/Overview.md | 17 +-- .../guides/libs/crypto/ecdsa384.md | 98 ++++++++++++++ .../guides/libs/crypto/rsassapss.md | 123 ++++++++++++++++++ 3 files changed, 230 insertions(+), 8 deletions(-) create mode 100644 docs/getting-started/guides/libs/crypto/ecdsa384.md create mode 100644 docs/getting-started/guides/libs/crypto/rsassapss.md diff --git a/docs/getting-started/Overview.md b/docs/getting-started/Overview.md index 0bac814..71dc96d 100644 --- a/docs/getting-started/Overview.md +++ b/docs/getting-started/Overview.md @@ -4,18 +4,19 @@ ## Solidity Library for Savvies by Distributed Lab -The library consists of modules and utilities that are built with a help of [Openzeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) (4.9.5) and **go far beyond mediocre solidity**. +The library consists of modules and utilities that are built leveraging [Openzeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) (4.9.6) and **go far beyond mediocre solidity**. -* Implementation of [**Contracts Registry**](https://eips.ethereum.org/EIPS/eip-6224) pattern +* Implementation of the [**Contracts Registry**](https://eips.ethereum.org/EIPS/eip-6224) pattern +* State-of-the-art cryptography primitives (**ECDSA over 384-bit curves**, **RSASSA-PSS**) +* Advanced data structures (**Vector**, **DynamicSet**, **PriorityQueue**, **AVLTree**) +* ZK-friendly [**Sparse Merkle Tree**](https://docs.iden3.io/publications/pdfs/Merkle-Tree.pdf) and [**Incremental Merkle Tree**](https://github.com/runtimeverification/deposit-contract-verification/blob/master/deposit-contract-verification.pdf) implementations * Versatile **RBAC** and **MultiOwnable** smart contracts * Enhanced and simplified [**Diamond**](https://eips.ethereum.org/EIPS/eip-2535) pattern -* Heap based priority queue library -* Memory data structures (Vector) -* Optimized [**Incremental Merkle Tree**](https://github.com/runtimeverification/deposit-contract-verification/blob/master/deposit-contract-verification.pdf) data structure +* Flexible finance instruments (**Staking**, **Vesting**) * Novel **ReturnDataProxy** contract +* Robust UniswapV2 and UniswapV3 oracles * Lightweight **SBT** implementation -* Flexible UniswapV2 and UniswapV3 oracles -* Utilities to ease work with ERC20 decimals, arrays, sets and ZK proofs +* Utilities to ease work with memory, types, ERC20 decimals, arrays, sets, and ZK proofs Checkout guides section for detailed explanations with usage examples for each module. @@ -51,4 +52,4 @@ We are open to contributions to our [solidity-lib](https://github.com/dl-solarit ### License -The library is released under the MIT License +The library is released under the MIT License. diff --git a/docs/getting-started/guides/libs/crypto/ecdsa384.md b/docs/getting-started/guides/libs/crypto/ecdsa384.md new file mode 100644 index 0000000..3b506f7 --- /dev/null +++ b/docs/getting-started/guides/libs/crypto/ecdsa384.md @@ -0,0 +1,98 @@ +# ╭╯ ECDSA384 + +## Introduction + +This library provides functionality for ECDSA verification over any 384-bit curve. Currently, this is the most efficient implementation out there, consuming ~9 million gas per call. + +The approach is Strauss-Shamir double scalar multiplication with 4 bits of precompute + projective points. + +## Functions + +To use the `ECDSA384` library, you need to import it. + +```solidity +import "@solarity/solidity-lib/libs/crypto/ECDSA384.sol"; +``` + +And optionally bind it to the type with the `using` statement. + +```solidity +using ECDSA384 for *; +``` + +### verify + +```solidity +function verify( + ECDSA384.Parameters memory curveParams_, + bytes memory hashedMessage_, + bytes memory signature_, + bytes memory pubKey_ +) internal view returns (bool) +``` + +#### Description + +The function to verify the ECDSA signature + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
curveParamsstruct ECDSA384.ParametersThe 384-bit curve parameters. lowSmax is n/2
hashedMessagebytesThe already hashed message to be verified
signaturebytesThe ECDSA signature. Equals to bytes(r) + bytes(s)
pubKeybytesThe full public key of a signer. Equals to bytes(x) + bytes(y). Note that signatures only from the lower part of the curve are accepted. If your s > n / 2, change it to s = n - s
+ +#### Example + +```solidity +function verifySECP384r1( + bytes calldata message_, + bytes calldata signature_, + bytes calldata pubKey_ +) external view returns (bool) { + ECDSA384.Parameters memory curveParams_ = ECDSA384.Parameters({ + a: hex"fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffff0000000000000000fffffffc", + b: hex"b3312fa7e23ee7e4988e056be3f82d19181d9c6efe8141120314088f5013875ac656398d8a2ed19d2a85c8edd3ec2aef", + gx: hex"aa87ca22be8b05378eb1c71ef320ad746e1d3b628ba79b9859f741e082542a385502f25dbf55296c3a545e3872760ab7", + gy: hex"3617de4a96262c6f5d9e98bf9292dc29f8f41dbd289a147ce9da3113b5f0b8c00a60b1ce1d7e819d7a431d7c90ea0e5f", + p: hex"fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffff0000000000000000ffffffff", + n: hex"ffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973", + lowSmax: hex"7fffffffffffffffffffffffffffffffffffffffffffffffe3b1a6c0fa1b96efac0d06d9245853bd76760cb5666294b9" + }); + + return curveParams_.verify(abi.encodePacked(sha256(message_)), signature_, pubKey_); +} +``` + +## 🖩 U384 + +### Introduction + +The `U384` low-level utility library that implements unsigned 384-bit arithmetics. It provides various functions that are used in the ECDSA384 library. diff --git a/docs/getting-started/guides/libs/crypto/rsassapss.md b/docs/getting-started/guides/libs/crypto/rsassapss.md new file mode 100644 index 0000000..4593a41 --- /dev/null +++ b/docs/getting-started/guides/libs/crypto/rsassapss.md @@ -0,0 +1,123 @@ +# 👨🏻‍💻 RSASSAPSS + +## Introduction + +The RSASSAPSS library provides functionality to verify RSASSA-PSS signatures with MGF1 mask generation function. + +Users may provide custom hash functions via `Parameters` struct. However, the usage of `sha256` is recommended. +The RSASSA-PSS signature verification costs ~340k gas. + +Learn more about the algorithm [here](https://datatracker.ietf.org/doc/html/rfc3447#section-8.1). + +## Functions + +To use the `RSASSAPSS` library, you need to import it. + +```solidity +import "@solarity/solidity-lib/libs/crypto/RSASSAPSS.sol"; +``` + +And optionally bind it to the type with the `using` statement. + +```solidity +using RSASSAPSS for *; +``` + +### verifySha256 + +```solidity +function verifySha256( + bytes memory message_, + bytes memory s_, + bytes memory e_, + bytes memory n_ +) internal view returns (bool) +``` + +#### Description + +Same as `verify` but with `sha256` hash function preconfiguration. + +### verify + +```solidity +function verify( + RSASSAPSS.Parameters memory params_, + bytes memory message_, + bytes memory s_, + bytes memory e_, + bytes memory n_ +) internal view returns (bool) +``` + +#### Description + +Verifies RSAPSS-SSA signature with custom parameters. + +##### Parameters: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
paramsstruct RSASSAPSS.ParametersThe parameters to specify the hash length, salt length, and hash function of choice
messagebytesThe arbitrary message to be verified
sbytesThe "encrypted" signature
ebytesThe public key exponent. 65537 is a recommended value
nbytesThe modulus of a public key
+ +##### Where RSASSAPSS.Parameters consist of: + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
hashLengthuint256The hash function output length in bytes
saltLengthuint256The pss encoding salt length in bytes
hasherfunction (bytes) pure returns (bytes)The function-pointer to a custom hash function