From 20f6ca7941eb45dbc78b0b886dfbea7acaccd605 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Thu, 1 Feb 2024 21:43:31 +1000 Subject: [PATCH] add more discussion --- core/cap-0051.md | 95 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 76 insertions(+), 19 deletions(-) diff --git a/core/cap-0051.md b/core/cap-0051.md index f9b68036e..92418e0f3 100644 --- a/core/cap-0051.md +++ b/core/cap-0051.md @@ -37,21 +37,37 @@ This CAP is aligned with the following Stellar Network Goals: ## Abstract -One function `verify_sig_ecdsa_secp256r1` is added to the Soroban environment's -exported function interface that accepts the parameters needed to verify a -secp256r1 signature of a payload for a public key. +This proposal adds one function to the Soroban environment's exported interface +that accepts the parameters needed to verify a secp256r1 signature of a payload +for a public key. ## Specification -### XDR Changes +A new function `verify_sig_ecdsa_secp256r1` with export name `3` in module `c` +is added to the Soroban environment's exported interface. -None. +It accepts a public key, message, and signature, and verifies that the signature +was produced using the ecdsa signing algorithm with the provided message and the +private key on the secp256r1 curve corresponding to the provided public key. -### Host Function Changes +It returns if the signature is verified, and traps if verification fails. + +The `public_key` parameters is a `BytesObject` that must have a length of +65-bytes, being the ecdsa secp256r1 public key SEC-1 encoded. + +The `msg_digest` parameters is a `BytesObject` that must be a hash of the +message, and must have been produced using a secure cryptographic hash function, +otherwise an attacker can potentially forge signatures. + +The `signature` parameters is a `BytesObject` that must have a length of +64-bytes, with the first 32-bytes being the R-value big endian integer, and the +second 32-bytes being the S-value big endian integer. + +The `env.json` in `rs-soroban-env` will be modified as so: ```diff mddiffcheck.ignore=true mddiffcheck.base=v20.1.0 diff --git a/soroban-env-common/env.json b/soroban-env-common/env.json -index df7d5c4..32cd1c3 100644 +index df7d5c4..d1d7760 100644 --- a/soroban-env-common/env.json +++ b/soroban-env-common/env.json @@ -1958,6 +1958,26 @@ @@ -68,7 +84,7 @@ index df7d5c4..32cd1c3 100644 + "type": "BytesObject" + }, + { -+ "name": "message", ++ "name": "msg_digest", + "type": "BytesObject" + }, + { @@ -77,17 +93,15 @@ index df7d5c4..32cd1c3 100644 + } + ], + "return": "Void", -+ "docs": "Verifies that the signature of the message was produced using the secret key of the public key." ++ "docs": "Verifies that the signature of the prehashed message using the secret key of the public key. The prehash must have been produced by a cryptographic hash function, otherwise an attacker can potentially forge signatures." } ] }, ``` -### Semantics - -#### Host Function Changes +### Design Rationale -A function is added to the host interface for verifying ecdsa secp256r1 signatures. +#### Verify vs Recovery The interface of the function is different to the existing ecdsa secp256k1 interface because the latter is a recovery interface that recovers a public key given a message, signature, and a recovery ID. @@ -107,7 +121,7 @@ systems, such as browsers or phones implementing webauthn/passkeys. A motivation to use the alternative recovery interfaces is that it will likely that contract that use secp256r1 verification will store a public key on chain, -or communicate the public key in invocation arguments. In both cases a +or communicate the public key in invocation parameters. In both cases a verification interface will require transmission and storage of the full 65-byte public key. A recovery interface would allow for hashing and truncating the transmitted or stored public key to 32-bytes if hashed with SHA-256, or 20-bytes @@ -115,6 +129,30 @@ if hashed and truncated similar to how Ethereum addresses are produced. This space reduction would lower the read/write resource usages as well as transactions size, for an increase in instruction cost. +#### Webauthn / Passkeys + +The secp256r1 verify interface is largely motivated by the webauthn use case. Webauthn involves an application registering with a client, that produces a private key, and provides the public key back to the application. The application can then engage the client to sign data that the application can verify using the public key shared earlier. + +The client may be a browser, phone, secret manager, or other software. + +The application could be a dapp, application, browser extension, or any other +software. + +The public key could be an EdDSA (ed25519), ES256 (ecdsa secp256r1), PS256, or RS256, where the last two are both RSA signing algorithms. + +In all signing algorithms the payload to sign is produced by concatenating the +webauthn authenticator data, and a SHA-256 hash of the client data JSON. The +client data JSON contains several fields, one being the `challenge` field, that +an application requesting a signature can set. The challenge provided by an +application is base64url encoded in the `challenge` field of the client data +JSON. For Stellar transactions intended to be authenticated by a webauthn +signature in a Soroban custom account, this challenge can be the SHA-256 hash of +the `HashIDPreimage` `ENVELOPE_TYPE_SOROBAN_AUTHORIZATION`. + +In the ed25519 algorithm the payload as-is is passed to the signature verification function. + +In the ecdsa secp256r1 algorithm the payload is hashed using SHA-256, and the hash is passed to the verification function. + ## Protocol Upgrade Transition ### Backwards Incompatibilities @@ -123,14 +161,33 @@ This proposal is completely backwards compatible. ### Resource Utilization +#### Metering + An ecdsa secp256r1 verification takes approximately 2ms in current tests. It -would be appropriate metered. +must be appropriately metered. + +#### Storage + +The use of a verify interface rather than a recovery interface requires that the 65-byte public key be stored or transmitted into the host for verification. It could be reasonable to present, or later add, a recovery interface that could more efficiently work with a truncated hash of the public key. See the Design Rationale section for more details. + +## Security + +### Prehash + +The `msg_digest` parameter must be a prehash produced by a secure cryptographic +hash function per the ecdsa specification. The non-specification of the hashing +function by the host function could be a weakness if developers use the +flexibility to build logic that produce signatures not using such a hash +function, but to require the use of a specific hash function would be +unreasonable as it would be unnecessarily restrictive and would require +transmission of the entire message that may not be desirable for a number of +reasons, such as resource cost or privacy. -### Security +### Audited Implementations -The only secp256r1 pure-Rust crate that the Soroban environment could embed is -the [p256] and [ecdsa] crates. The two crates have never been independently -audited. +The only ecdsa secp256r1 pure-Rust crates that the Soroban environment could +embed are the [p256] and [ecdsa] crates. The two crates have never been +independently audited. ## Test Cases