Skip to content

Commit

Permalink
add more discussion
Browse files Browse the repository at this point in the history
  • Loading branch information
leighmcculloch committed Feb 1, 2024
1 parent 0e8f6c3 commit 20f6ca7
Showing 1 changed file with 76 additions and 19 deletions.
95 changes: 76 additions & 19 deletions core/cap-0051.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 @@
Expand All @@ -68,7 +84,7 @@ index df7d5c4..32cd1c3 100644
+ "type": "BytesObject"
+ },
+ {
+ "name": "message",
+ "name": "msg_digest",
+ "type": "BytesObject"
+ },
+ {
Expand All @@ -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.

Expand All @@ -107,14 +121,38 @@ 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
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
Expand All @@ -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

Expand Down

0 comments on commit 20f6ca7

Please sign in to comment.