-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added ECDSA384 and RSASSAPSS docs (#30)
* Added ECDSA384 and RSASSAPSS docs * fixed typos * fix overview --------- Co-authored-by: Artem Chystiakov <[email protected]>
- Loading branch information
1 parent
37acda7
commit 8dd9020
Showing
3 changed files
with
230 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Name</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><code>curveParams</code></td> | ||
| <td>struct ECDSA384.Parameters</td> | ||
| <td>The 384-bit curve parameters. <code>lowSmax</code> is <code>n/2</code></td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>hashedMessage</code></td> | ||
| <td>bytes</td> | ||
| <td>The already hashed message to be verified</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>signature</code></td> | ||
| <td>bytes</td> | ||
| <td>The ECDSA signature. Equals to <code>bytes(r) + bytes(s)</code></td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>pubKey</code></td> | ||
| <td>bytes</td> | ||
| <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> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| #### 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Name</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><code>params</code></td> | ||
| <td>struct RSASSAPSS.Parameters</td> | ||
| <td>The parameters to specify the hash length, salt length, and hash function of choice</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>message</code></td> | ||
| <td>bytes</td> | ||
| <td>The arbitrary message to be verified</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>s</code></td> | ||
| <td>bytes</td> | ||
| <td>The "encrypted" signature</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>e</code></td> | ||
| <td>bytes</td> | ||
| <td>The public key exponent. <code>65537</code> is a recommended value</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>n</code></td> | ||
| <td>bytes</td> | ||
| <td>The modulus of a public key</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ##### Where RSASSAPSS.Parameters consist of: | ||
|
|
||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Name</th> | ||
| <th>Type</th> | ||
| <th>Description</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| <tr> | ||
| <td><code>hashLength</code></td> | ||
| <td>uint256</td> | ||
| <td>The hash function output length in bytes</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>saltLength</code></td> | ||
| <td>uint256</td> | ||
| <td>The pss encoding salt length in bytes</td> | ||
| </tr> | ||
| <tr> | ||
| <td><code>hasher</code></td> | ||
| <td>function (bytes) pure returns (bytes)</td> | ||
| <td>The function-pointer to a custom hash function</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> |