From cdd786ac0c8da91037e5ee2ba7ed0d3f0bffc974 Mon Sep 17 00:00:00 2001 From: Thomas Letan Date: Wed, 9 Jul 2025 13:37:25 +0200 Subject: [PATCH] EVM Node: Add GCP KMS module interface documentation * What Added comprehensive documentation to the `gcp_kms.mli` interface. This includes descriptions for types `t` and `hash_algorithm`, and functions like `from_gcp_key`, `gcp_key`, `public_key`, `sign`, and `ethereum_address_opt`. * Why To improve clarity and understanding of the GCP KMS module's public interface. To provide detailed explanations on how to use the functions, their expected inputs and outputs, and any specific behaviors or limitations, such as the digest algorithm note for `sign`. This enhances maintainability and makes it easier for developers to interact with the module correctly. * How OCaml documentation comments were added directly into the `.mli` file. All public types and functions now have clear, concise, and accurate descriptions. Specific details were included regarding supported key types for `from_gcp_key` and the implications of using different hash algorithms for `sign`. --- etherlink/bin_node/lib_dev/gcp_kms.mli | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/etherlink/bin_node/lib_dev/gcp_kms.mli b/etherlink/bin_node/lib_dev/gcp_kms.mli index ce4b3b3edb1a..db36c3be1766 100644 --- a/etherlink/bin_node/lib_dev/gcp_kms.mli +++ b/etherlink/bin_node/lib_dev/gcp_kms.mli @@ -5,17 +5,36 @@ (* *) (*****************************************************************************) +(** A handler to a key held by a GCP KMS allowing to sign arbitrary payload. *) type t +(** The hash algorithm to be used to compute the digest sent to GCP. *) type hash_algorithm = Blake2B | Keccak256 +(** [from_gcp_key config key] creates a new handler for the given [key]. + + Are currently supported [EC_SIGN_P256_SHA256] and + [EC_SIGN_SECP256K1_SHA256] keys. Returns an error when providing details + about a key of an unsupported algorithm. *) val from_gcp_key : Configuration.gcp_kms -> Configuration.gcp_key -> t tzresult Lwt.t +(** Give back the key identifier *) val gcp_key : t -> Configuration.gcp_key +(** [public_key kms] returns the public key of the KMS cryptographic material + encoded to be compatible with the Tezos blockchain. *) val public_key : t -> Signature.Public_key.t +(** [sign kms algorithm payload] computes the signature of [payload] using the + requested [algorithm] for computing the digest. + + To be noted that while GCP officially only support Sha256 digests, it will + happily sign any 32-byte input which is why we can use it to sign + blueprints (Blake2B) and Ethereum transactions (Keccak256). However, it + means that arbitrary third-party tools recomputing the hash themselves will + likely assume they need to use SHA256 to verify the signature of the + original payload. *) val sign : t -> hash_algorithm -> bytes -> Signature.t tzresult Lwt.t (** [ethereum_address_opt kms] returns the Ethereum address of the key managed -- GitLab