From b6a5e89de7e01299c4246dc4a69ec248e773aa23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ernesto=20Garc=C3=ADa?= Date: Wed, 4 Jun 2025 18:23:02 -0600 Subject: [PATCH] Fix docs references to cryptographic utilities (#5717) --- contracts/utils/cryptography/ERC7739Utils.sol | 6 +++--- .../cryptography/signers/AbstractSigner.sol | 4 ++-- contracts/utils/cryptography/signers/ERC7739.sol | 4 ++-- .../utils/cryptography/signers/SignerECDSA.sol | 2 +- .../utils/cryptography/signers/SignerP256.sol | 2 +- .../utils/cryptography/signers/SignerRSA.sol | 4 ++-- docs/modules/ROOT/pages/utilities.adoc | 16 ++++++++-------- 7 files changed, 19 insertions(+), 19 deletions(-) diff --git a/contracts/utils/cryptography/ERC7739Utils.sol b/contracts/utils/cryptography/ERC7739Utils.sol index e7b720ea0..ec79fdd22 100644 --- a/contracts/utils/cryptography/ERC7739Utils.sol +++ b/contracts/utils/cryptography/ERC7739Utils.sol @@ -9,7 +9,7 @@ import {Calldata} from "../Calldata.sol"; * that are specific to an EIP-712 domain. * * This library provides methods to wrap, unwrap and operate over typed data signatures with a defensive - * rehashing mechanism that includes the application's xref:api:utils#EIP712-_domainSeparatorV4[EIP-712] + * rehashing mechanism that includes the app's xref:api:utils/cryptography#EIP712-_domainSeparatorV4[EIP-712] * and preserves readability of the signed content using an EIP-712 nested approach. * * A smart contract domain can validate a signature for a typed data structure in two ways: @@ -20,8 +20,8 @@ import {Calldata} from "../Calldata.sol"; * NOTE: A provider for a smart contract wallet would need to return this signature as the * result of a call to `personal_sign` or `eth_signTypedData`, and this may be unsupported by * API clients that expect a return value of 129 bytes, or specifically the `r,s,v` parameters - * of an xref:api:utils#ECDSA[ECDSA] signature, as is for example specified for - * xref:api:utils#EIP712[EIP-712]. + * of an xref:api:utils/cryptography#ECDSA[ECDSA] signature, as is for example specified for + * xref:api:utils/cryptography#EIP712[EIP-712]. */ library ERC7739Utils { /** diff --git a/contracts/utils/cryptography/signers/AbstractSigner.sol b/contracts/utils/cryptography/signers/AbstractSigner.sol index 40803518c..a269df855 100644 --- a/contracts/utils/cryptography/signers/AbstractSigner.sol +++ b/contracts/utils/cryptography/signers/AbstractSigner.sol @@ -15,8 +15,8 @@ abstract contract AbstractSigner { * * WARNING: Implementing a signature validation algorithm is a security-sensitive operation as it involves * cryptographic verification. It is important to review and test thoroughly before deployment. Consider - * using one of the signature verification libraries (xref:api:utils#ECDSA[ECDSA], xref:api:utils#P256[P256] - * or xref:api:utils#RSA[RSA]). + * using one of the signature verification libraries (xref:api:utils/cryptography#ECDSA[ECDSA], + * xref:api:utils/cryptography#P256[P256] or xref:api:utils/cryptography#RSA[RSA]). */ function _rawSignatureValidation(bytes32 hash, bytes calldata signature) internal view virtual returns (bool); } diff --git a/contracts/utils/cryptography/signers/ERC7739.sol b/contracts/utils/cryptography/signers/ERC7739.sol index 6d714e84b..ff0bd4e38 100644 --- a/contracts/utils/cryptography/signers/ERC7739.sol +++ b/contracts/utils/cryptography/signers/ERC7739.sol @@ -18,8 +18,8 @@ import {ShortStrings} from "../../ShortStrings.sol"; * This contract requires implementing the {_rawSignatureValidation} function, which passes the wrapped message hash, * which may be either an typed data or a personal sign nested type. * - * NOTE: xref:api:utils#EIP712[EIP-712] uses xref:api:utils#ShortStrings[ShortStrings] to optimize gas - * costs for short strings (up to 31 characters). Consider that strings longer than that will use storage, + * NOTE: xref:api:utils/cryptography#EIP712[EIP-712] uses xref:api:utils/cryptography#ShortStrings[ShortStrings] to + * optimize gas costs for short strings (up to 31 characters). Consider that strings longer than that will use storage, * which may limit the ability of the signer to be used within the ERC-4337 validation phase (due to * https://eips.ethereum.org/EIPS/eip-7562#storage-rules[ERC-7562 storage access rules]). */ diff --git a/contracts/utils/cryptography/signers/SignerECDSA.sol b/contracts/utils/cryptography/signers/SignerECDSA.sol index fd1002148..c9a543343 100644 --- a/contracts/utils/cryptography/signers/SignerECDSA.sol +++ b/contracts/utils/cryptography/signers/SignerECDSA.sol @@ -6,7 +6,7 @@ import {AbstractSigner} from "./AbstractSigner.sol"; import {ECDSA} from "../ECDSA.sol"; /** - * @dev Implementation of {AbstractSigner} using xref:api:utils#ECDSA[ECDSA] signatures. + * @dev Implementation of {AbstractSigner} using xref:api:utils/cryptography#ECDSA[ECDSA] signatures. * * For {Account} usage, a {_setSigner} function is provided to set the {signer} address. * Doing so is easier for a factory, who is likely to use initializable clones of this contract. diff --git a/contracts/utils/cryptography/signers/SignerP256.sol b/contracts/utils/cryptography/signers/SignerP256.sol index dc94e7caa..1d6587662 100644 --- a/contracts/utils/cryptography/signers/SignerP256.sol +++ b/contracts/utils/cryptography/signers/SignerP256.sol @@ -6,7 +6,7 @@ import {AbstractSigner} from "./AbstractSigner.sol"; import {P256} from "../P256.sol"; /** - * @dev Implementation of {AbstractSigner} using xref:api:utils#P256[P256] signatures. + * @dev Implementation of {AbstractSigner} using xref:api:utils/cryptography#P256[P256] signatures. * * For {Account} usage, a {_setSigner} function is provided to set the {signer} public key. * Doing so is easier for a factory, who is likely to use initializable clones of this contract. diff --git a/contracts/utils/cryptography/signers/SignerRSA.sol b/contracts/utils/cryptography/signers/SignerRSA.sol index 5deb77493..e5aadfd98 100644 --- a/contracts/utils/cryptography/signers/SignerRSA.sol +++ b/contracts/utils/cryptography/signers/SignerRSA.sol @@ -6,7 +6,7 @@ import {AbstractSigner} from "./AbstractSigner.sol"; import {RSA} from "../RSA.sol"; /** - * @dev Implementation of {AbstractSigner} using xref:api:utils#RSA[RSA] signatures. + * @dev Implementation of {AbstractSigner} using xref:api:utils/cryptography#RSA[RSA] signatures. * * For {Account} usage, a {_setSigner} function is provided to set the {signer} public key. * Doing so is easier for a factory, who is likely to use initializable clones of this contract. @@ -44,7 +44,7 @@ abstract contract SignerRSA is AbstractSigner { /** * @dev See {AbstractSigner-_rawSignatureValidation}. Verifies a PKCSv1.5 signature by calling - * xref:api:utils.adoc#RSA-pkcs1Sha256-bytes-bytes-bytes-bytes-[RSA.pkcs1Sha256]. + * xref:api:utils/cryptography.adoc#RSA-pkcs1Sha256-bytes-bytes-bytes-bytes-[RSA.pkcs1Sha256]. * * IMPORTANT: Following the RSASSA-PKCS1-V1_5-VERIFY procedure outlined in RFC8017 (section 8.2.2), the * provided `hash` is used as the `M` (message) and rehashed using SHA256 according to EMSA-PKCS1-v1_5 diff --git a/docs/modules/ROOT/pages/utilities.adoc b/docs/modules/ROOT/pages/utilities.adoc index 6fe2de63b..91bb320c1 100644 --- a/docs/modules/ROOT/pages/utilities.adoc +++ b/docs/modules/ROOT/pages/utilities.adoc @@ -12,9 +12,9 @@ At a high level, signatures are a set of cryptographic algorithms that allow for ==== Ethereum Signatures (secp256k1) -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 form a 65-byte array (of type `bytes` in Solidity) arranged the following way: `[[v (1)], [r (32)], [s (32)]]`. +xref:api:utils/cryptography.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 form 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`]. +The data signer can be recovered with xref:api:utils/cryptography.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/cryptography.adoc#MessageHashUtils-toEthSignedMessageHash-bytes32-[`toEthSignedMessageHash`]. [source,solidity] ---- @@ -28,7 +28,7 @@ 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. +WARNING: Getting signature verification right is not trivial: make sure you fully read and understand xref:api:utils/cryptography.adoc#MessageHashUtils[`MessageHashUtils`]'s and xref:api:utils/cryptography.adoc#ECDSA[`ECDSA`]'s documentation. ==== P256 Signatures (secp256r1) @@ -79,7 +79,7 @@ This cryptosystem consists of using a private key that's the product of 2 large 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: +To verify a signature using RSA, you can leverage the xref:api:utils/cryptography.adoc#RSA[`RSA`] library that exposes a method for verifying RSA with the PKCS 1.5 standard: [source,solidity] ---- @@ -103,11 +103,11 @@ Developers can build a Merkle Tree off-chain, which allows for verifying that an TIP: OpenZeppelin Contracts provides a https://github.com/OpenZeppelin/merkle-tree[JavaScript library] for building trees off-chain and generating proofs. -xref:api:utils.adoc#MerkleProof[`MerkleProof`] provides: +xref:api:utils/cryptography.adoc#MerkleProof[`MerkleProof`] provides: -* xref:api:utils.adoc#MerkleProof-verify-bytes32---bytes32-bytes32-[`verify`] - can prove that some value is part of a https://en.wikipedia.org/wiki/Merkle_tree[Merkle tree]. +* xref:api:utils/cryptography.adoc#MerkleProof-verify-bytes32---bytes32-bytes32-[`verify`] - can prove that some value is part of a https://en.wikipedia.org/wiki/Merkle_tree[Merkle tree]. -* xref:api:utils.adoc#MerkleProof-multiProofVerify-bytes32-bytes32---bytes32---bool---[`multiProofVerify`] - can prove multiple values are part of a Merkle tree. +* xref:api:utils/cryptography.adoc#MerkleProof-multiProofVerify-bytes32-bytes32---bytes32---bool---[`multiProofVerify`] - can prove multiple values are part of a Merkle tree. For an on-chain Merkle Tree, see the xref:api:utils.adoc#MerkleTree[`MerkleTree`] library. @@ -482,4 +482,4 @@ function _setTargetAdminDelay(address target, uint32 newDelay) internal virtual emit TargetAdminDelayUpdated(target, newDelay, effect); } ----- \ No newline at end of file +----