Skip to content

Commit 8dd9020

Browse files
aritkulovaArvolear
aritkulova
and
Arvolear
authored
Added ECDSA384 and RSASSAPSS docs (#30)
* Added ECDSA384 and RSASSAPSS docs * fixed typos * fix overview --------- Co-authored-by: Artem Chystiakov <artem.ch31@gmail.com>
1 parent 37acda7 commit 8dd9020

File tree

3 files changed

+230
-8
lines changed

3 files changed

+230
-8
lines changed

‎docs/getting-started/Overview.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,19 @@
44

55
## Solidity Library for Savvies by Distributed Lab
66

7-
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**.
7+
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**.
88

9-
* Implementation of [**Contracts Registry**](https://eips.ethereum.org/EIPS/eip-6224) pattern
9+
* Implementation of the [**Contracts Registry**](https://eips.ethereum.org/EIPS/eip-6224) pattern
10+
* State-of-the-art cryptography primitives (**ECDSA over 384-bit curves**, **RSASSA-PSS**)
11+
* Advanced data structures (**Vector**, **DynamicSet**, **PriorityQueue**, **AVLTree**)
12+
* 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
1013
* Versatile **RBAC** and **MultiOwnable** smart contracts
1114
* Enhanced and simplified [**Diamond**](https://eips.ethereum.org/EIPS/eip-2535) pattern
12-
* Heap based priority queue library
13-
* Memory data structures (Vector)
14-
* Optimized [**Incremental Merkle Tree**](https://github.com/runtimeverification/deposit-contract-verification/blob/master/deposit-contract-verification.pdf) data structure
15+
* Flexible finance instruments (**Staking**, **Vesting**)
1516
* Novel **ReturnDataProxy** contract
17+
* Robust UniswapV2 and UniswapV3 oracles
1618
* Lightweight **SBT** implementation
17-
* Flexible UniswapV2 and UniswapV3 oracles
18-
* Utilities to ease work with ERC20 decimals, arrays, sets and ZK proofs
19+
* Utilities to ease work with memory, types, ERC20 decimals, arrays, sets, and ZK proofs
1920

2021
Checkout guides section for detailed explanations with usage examples for each module.
2122

@@ -51,4 +52,4 @@ We are open to contributions to our [solidity-lib](https://github.com/dl-solarit
5152

5253
### License
5354

54-
The library is released under the MIT License
55+
The library is released under the MIT License.

‎docs/getting-started/guides/libs/crypto/ecdsa384.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# ╭╯ ECDSA384
2+
3+
## Introduction
4+
5+
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.
6+
7+
The approach is Strauss-Shamir double scalar multiplication with 4 bits of precompute + projective points.
8+
9+
## Functions
10+
11+
To use the `ECDSA384` library, you need to import it.
12+
13+
```solidity
14+
import "@solarity/solidity-lib/libs/crypto/ECDSA384.sol";
15+
```
16+
17+
And optionally bind it to the type with the `using` statement.
18+
19+
```solidity
20+
using ECDSA384 for *;
21+
```
22+
23+
### verify
24+
25+
```solidity
26+
function verify(
27+
ECDSA384.Parameters memory curveParams_,
28+
bytes memory hashedMessage_,
29+
bytes memory signature_,
30+
bytes memory pubKey_
31+
) internal view returns (bool)
32+
```
33+
34+
#### Description
35+
36+
The function to verify the ECDSA signature
37+
38+
##### Parameters:
39+
40+
<table>
41+
<thead>
42+
<tr>
43+
<th>Name</th>
44+
<th>Type</th>
45+
<th>Description</th>
46+
</tr>
47+
</thead>
48+
<tbody>
49+
<tr>
50+
<td><code>curveParams</code></td>
51+
<td>struct ECDSA384.Parameters</td>
52+
<td>The 384-bit curve parameters. <code>lowSmax</code> is <code>n/2</code></td>
53+
</tr>
54+
<tr>
55+
<td><code>hashedMessage</code></td>
56+
<td>bytes</td>
57+
<td>The already hashed message to be verified</td>
58+
</tr>
59+
<tr>
60+
<td><code>signature</code></td>
61+
<td>bytes</td>
62+
<td>The ECDSA signature. Equals to <code>bytes(r) + bytes(s)</code></td>
63+
</tr>
64+
<tr>
65+
<td><code>pubKey</code></td>
66+
<td>bytes</td>
67+
<td>The full public key of a signer. Equals to <code>bytes(x) + bytes(y)</code>. Note that signatures only from the lower part of the curve are accepted. If your <code>s > n / 2</code>, change it to <code>s = n - s</code></td>
68+
</tr>
69+
</tbody>
70+
</table>
71+
72+
#### Example
73+
74+
```solidity
75+
function verifySECP384r1(
76+
bytes calldata message_,
77+
bytes calldata signature_,
78+
bytes calldata pubKey_
79+
) external view returns (bool) {
80+
ECDSA384.Parameters memory curveParams_ = ECDSA384.Parameters({
81+
a: hex"fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffff0000000000000000fffffffc",
82+
b: hex"b3312fa7e23ee7e4988e056be3f82d19181d9c6efe8141120314088f5013875ac656398d8a2ed19d2a85c8edd3ec2aef",
83+
gx: hex"aa87ca22be8b05378eb1c71ef320ad746e1d3b628ba79b9859f741e082542a385502f25dbf55296c3a545e3872760ab7",
84+
gy: hex"3617de4a96262c6f5d9e98bf9292dc29f8f41dbd289a147ce9da3113b5f0b8c00a60b1ce1d7e819d7a431d7c90ea0e5f",
85+
p: hex"fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffeffffffff0000000000000000ffffffff",
86+
n: hex"ffffffffffffffffffffffffffffffffffffffffffffffffc7634d81f4372ddf581a0db248b0a77aecec196accc52973",
87+
lowSmax: hex"7fffffffffffffffffffffffffffffffffffffffffffffffe3b1a6c0fa1b96efac0d06d9245853bd76760cb5666294b9"
88+
});
89+
90+
return curveParams_.verify(abi.encodePacked(sha256(message_)), signature_, pubKey_);
91+
}
92+
```
93+
94+
## 🖩 U384
95+
96+
### Introduction
97+
98+
The `U384` low-level utility library that implements unsigned 384-bit arithmetics. It provides various functions that are used in the ECDSA384 library.

‎docs/getting-started/guides/libs/crypto/rsassapss.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# 👨🏻‍💻 RSASSAPSS
2+
3+
## Introduction
4+
5+
The RSASSAPSS library provides functionality to verify RSASSA-PSS signatures with MGF1 mask generation function.
6+
7+
Users may provide custom hash functions via `Parameters` struct. However, the usage of `sha256` is recommended.
8+
The RSASSA-PSS signature verification costs ~340k gas.
9+
10+
Learn more about the algorithm [here](https://datatracker.ietf.org/doc/html/rfc3447#section-8.1).
11+
12+
## Functions
13+
14+
To use the `RSASSAPSS` library, you need to import it.
15+
16+
```solidity
17+
import "@solarity/solidity-lib/libs/crypto/RSASSAPSS.sol";
18+
```
19+
20+
And optionally bind it to the type with the `using` statement.
21+
22+
```solidity
23+
using RSASSAPSS for *;
24+
```
25+
26+
### verifySha256
27+
28+
```solidity
29+
function verifySha256(
30+
bytes memory message_,
31+
bytes memory s_,
32+
bytes memory e_,
33+
bytes memory n_
34+
) internal view returns (bool)
35+
```
36+
37+
#### Description
38+
39+
Same as `verify` but with `sha256` hash function preconfiguration.
40+
41+
### verify
42+
43+
```solidity
44+
function verify(
45+
RSASSAPSS.Parameters memory params_,
46+
bytes memory message_,
47+
bytes memory s_,
48+
bytes memory e_,
49+
bytes memory n_
50+
) internal view returns (bool)
51+
```
52+
53+
#### Description
54+
55+
Verifies RSAPSS-SSA signature with custom parameters.
56+
57+
##### Parameters:
58+
59+
<table>
60+
<thead>
61+
<tr>
62+
<th>Name</th>
63+
<th>Type</th>
64+
<th>Description</th>
65+
</tr>
66+
</thead>
67+
<tbody>
68+
<tr>
69+
<td><code>params</code></td>
70+
<td>struct RSASSAPSS.Parameters</td>
71+
<td>The parameters to specify the hash length, salt length, and hash function of choice</td>
72+
</tr>
73+
<tr>
74+
<td><code>message</code></td>
75+
<td>bytes</td>
76+
<td>The arbitrary message to be verified</td>
77+
</tr>
78+
<tr>
79+
<td><code>s</code></td>
80+
<td>bytes</td>
81+
<td>The "encrypted" signature</td>
82+
</tr>
83+
<tr>
84+
<td><code>e</code></td>
85+
<td>bytes</td>
86+
<td>The public key exponent. <code>65537</code> is a recommended value</td>
87+
</tr>
88+
<tr>
89+
<td><code>n</code></td>
90+
<td>bytes</td>
91+
<td>The modulus of a public key</td>
92+
</tr>
93+
</tbody>
94+
</table>
95+
96+
##### Where RSASSAPSS.Parameters consist of:
97+
98+
<table>
99+
<thead>
100+
<tr>
101+
<th>Name</th>
102+
<th>Type</th>
103+
<th>Description</th>
104+
</tr>
105+
</thead>
106+
<tbody>
107+
<tr>
108+
<td><code>hashLength</code></td>
109+
<td>uint256</td>
110+
<td>The hash function output length in bytes</td>
111+
</tr>
112+
<tr>
113+
<td><code>saltLength</code></td>
114+
<td>uint256</td>
115+
<td>The pss encoding salt length in bytes</td>
116+
</tr>
117+
<tr>
118+
<td><code>hasher</code></td>
119+
<td>function (bytes) pure returns (bytes)</td>
120+
<td>The function-pointer to a custom hash function</td>
121+
</tr>
122+
</tbody>
123+
</table>

0 commit comments

Comments
 (0)