ARC-60 Algorand Wallet Structured Data Signing API #284

deanstef · 2024-03-05T17:42:58Z

An API for signing structured bytes with Algorand wallets. It unlocks many use cases ranging from self-custodial digital identities, authentication, document signing etc.

The API provides a standard interface for a signData() function that takes as an argument a structured data object and metadata and returns the requested digital signature. ~~It is compatible with rekeyed accounts, multi-signature and HD wallets.~~

This API is inspired and based on ARC-1. It has been conceived to be secure by design with semantics and security controls. It does not allow the signing of canonical Algorand transactions or Groups.

assets/arc-0060/types.ts

ehanoc

Made a few comments.

I think we need a schema for 32 bytes signing auth challenge requests

assets/arc-0060/types.ts

ARCs/arc-0060.md

ehanoc · 2024-03-06T09:46:24Z

assets/arc-0060/wallet.ts

We could add a matching wallet.spec.ts file with a small test suite so that we can test the functions of the reference implementation

ehanoc · 2024-03-06T09:47:48Z

assets/arc-0060/lsig-schema.json

@joe-p can you validate this schema?

deanstef · 2024-03-06T16:06:33Z

Made a few comments.

I think we need a schema for 32 bytes signing auth challenge requests

@ehanoc Thank you for your comments. The JSON schema for authentication challenge will be provided by ARC-31 as an extension of ARC-60.

deanstef · 2024-03-12T15:29:16Z

With 7447a0d and 8d8cef3 I updated ARC-60 with a simpler signBytes interface. It now takes three arguments: data, metadata, and signer. I removed the msig, authaddr and hdWallet functionalities to keep it simple.

@ehanoc @pbennett @yigitguler @k13n @joe-p PTAL

assets/arc-0060/wallet.ts

ehanoc · 2024-03-20T15:14:45Z

ARCs/arc-0060.md

+
+| ScopeType | Description |
+| --- | --- |
+| PLAIN | Signature of a simple byte string. This is the most generic scope. |


PLAIN is the same as ARBITRARY, doesn't specify WHY we are signing

Agreed. I would like to keep a generic Scope for a generic message signing. What about SIGMSG?

But generic is problematic because we don't know what we are signing. SIGMSG still doesn't state what we are signing.

I removed generic scopes. We only have AUTH and LSIG now.

k13n

Thanks @deanstef for putting together ARC-60!

k13n · 2024-03-25T06:28:33Z

ARCs/arc-0060.md

+    metadata: StdSignMetadata,
+    signer: Ed25519Pk,
+}
+    => Promise<(SignedDataStr | null)>;


In which cases can signData return null? Further below, it is defined that if signData fails, it should throw an error, not return null. So shouldn't the function either return SigendDataStr or throw an error?

Yes you are right. This is a leftover from a previous design with bulk signatures.

Actually - in the reference implemnetation, I am returning null if the user does not confimr the signature: https://github.com/deanstef/ARCs/blob/a8de5d08f3c558bedeb8c1addbacc25362eda7b5/assets/arc-0060/wallet.ts#L79C4-L79C5

k13n · 2024-03-25T06:52:44Z

ARCs/arc-0060.md

+`SignedDataStr` is the produced 64-byte array, ed25519 digital signature, of the signed data.
+
+```tsx
+export type SignedDataStr = Uint8Array;


The naming is a little confusing to me. Why does SignedDataStr include the term Str when it is defined as an Uint8Array. Conversely, StdData is also defined as a string but does not contain the term Str.

Yeah the naming got a bit messy when we changed stuff from String to Uint8Array. I will align the naming such that only string objects names will end with the Str term

k13n · 2024-03-25T07:00:36Z

ARCs/arc-0060.md

+
+#### Interface `SignedDataStr`
+
+`SignedDataStr` is the produced 64-byte array, ed25519 digital signature, of the signed data.


According to this definition, SigendDataStr is purely the signature (64 bytes long). In the reference implementation, nacl.sign is used which returns the signature and the original message.

If SignedDataStr represents purely the signature, wouldn't something like Signature be a more appropriate name for this type?

Good catch. Here b244ed6 I updated both the naming and the reference implementation. I am using nacl.sign.detached now.

k13n · 2024-03-25T07:04:42Z

ARCs/arc-0060.md

+    /**
+    * Canonical representation of the JSON schema for the signing data.
+    */
+    schema: string;


Why is the schema (which is a JSON object) represented as a canonicalized JSON string?

In a very first version of ARC60 I was using canonicalized versions of JSON objects to produce signatures of the entire objects. In the new version this is not needed anymore. We can get rid of the canonicalized stuff indeed.

k13n · 2024-03-25T07:05:22Z

ARCs/arc-0060.md

+    /**
+    * Optional encoding used to represent the signing data.
+    */
+    encoding?: string;


What are possible encodings that should be supported?

+1 to clarifying this

k13n · 2024-03-25T07:12:31Z

ARCs/arc-0060.md

+export interface SignDataError extends Error {
+  code: number;
+  data?: any;
+  failingSignData: (StdData | null);
+}


In which case could failingSignData be null?

If the error was caused by a missing StdData object.

k13n · 2024-03-25T07:15:14Z

ARCs/arc-0060.md

+
+### Semantic Requirements
+
+The call `signData(data, metadata, signer)` **MUST** either return the signed data `ret` or reject the call throwing an error `err`.


According to the definition of SignDataFunction above, it seems a null return value is also possible (which I don't think is required as I mentioned earlier).

ARCs/arc-0060.md

k13n · 2024-03-25T07:17:20Z

ARCs/arc-0060.md

+Upon calling `signData(data, metadata, signer)`:
+
+- the `data`, `metadata`, and `signer` **MUST NOT** be `null`, otherwise the wallet **MUST** reject the call.
+- `data` **MUST** be validated with respect to the JSON schema `metadata.schema`. If the validation fails, the call **MUST** be rejected with a `4300` error.


According to the table above an invalid schema is a 4601 error code, or is this a different schema?

Error code 4601 means that the JSON schema does not comply with ARC-60 (the required fields ARC60Domain and bytes are missing).

In this case, we are failing because data is not a valid object according to the schema metadata.schema.

k13n · 2024-03-25T07:24:12Z

ARCs/arc-0060.md

+- the `bytes` must be a valid byte string:
+  - the wallet **MUST** reject if `bytes` is prepended with a forbidden domain separator `TX` or `TG`.


Is this validation here independent of the ARC60Domain validation? Because if ARC60Domain is set to arc60 (or anything other than "", "TX", or "TG"), wouldn't it be fine if bytes started with TX or TG? Because the wallet would have to concatenate the value of ARC60Domain and bytes and hence no malicious payload could be signed?

Setting ARC60Domain to "" would make the concatenation not effective. I suggest to always validate bytes against malicious payloads (prepended with TX or TG) to avoid problems.

ehanoc · 2024-03-25T08:33:12Z

ARCs/arc-0060.md

+
+| ScopeType | Description |
+| --- | --- |
+| MSGSIG | Signature of a simple message. This is the most generic scope. |


I don't think we should have generic scopes. They should be VERY Specific.

A generic scope doesn't tell you what schema to enforce and could potentially be used to trick the user or even the wallet.

The spec doesn't make it generic. It says that the bytes must not be certain things, such as transactions. The spec says "most generic", i.e., that narrower scopes might be defined. I think the problem then becomes how to specify what things should not be. For example, specifying a scope that allows 32 arbitrary bytes to be signed for auth purposes does not preclude a 32 byte arbitrary document from being signed.

We only have AUTH and LSIG scopes now.

ehanoc · 2024-04-03T10:44:51Z

ARCs/arc-0060.md

+
+> This section is non-normative
+
+Signatures of bytes are processed with the `signData(data, metadata, signer)` function.


@deanstef requiring the public key (a.k.a signer) would be somewhat cumbersome for HDWallets to find the correct address to use. Would have to do a recursive search.

Legacy algorand wallets are single address, with HDWallets they will support BIP44 and providing the path as optional would suit best.

Thoughts?

I think signData(data, metadata, keyInfo

Where keyInfo can contain information of where to find the key, what keyType, hashing function to use would be extendable and offer future proof with HDWallets

In the first version of ARC-60 there was the possibility of passing a HDWallet derivation path as signer parameter (see https://github.com/deanstef/ARCs/blob/67754a89ff9e211cfee6f29ebd7aa4f016b19243/ARCs/arc-0060.md?plain=1#L122)

Then we decided to keep it simple and just opt for passing the public key of the signer. I'd be happy to re-introduce HDWallets support though

I understand. Although just the public key is ambiguous when you have N possible key pairs in a BIP32 / BIP44 path scheme.

mxmauro · 2024-04-09T14:55:02Z

Hi, I cannot figure out if, on the latest revision, data to sign is Uint8Array or a string. (I prefer the former because data & platform-independant)

jasonpaulos · 2024-04-09T18:21:30Z

ARCs/arc-0060.md

+    /**
+    * Optional encoding used to represent the signing data.
+    */
+    encoding?: string;


+1 to clarifying this

jasonpaulos · 2024-04-09T18:28:08Z

ARCs/arc-0060.md

+The `StdDataStr` object is a string that comply with the `metadata` JSON schema.
+
+```tsx
+export type StdDataStr = string;


I don't understand how this can contain an logicsig program if it's a string

Yes, I prefer a Buffer or Uint8Array.

The way I read the spec is that the StdDataStr is a stringified JSON object that must comply with the metadata supplied as an argument to the sign function, of type StdSignMetadata. The metadata specifies which field contains data to be signed, and not the whole json object. Part of the problem is this line in the first paragraphs:

data is a string representing the structured data being signed.

This is not true according to the rest of the spec. The data being signed is whichever field of the StdDataStr json object is specified to be signed.

Another problem is that there is not defined here the standard encoding for JSON bytes data. Typically in web applications it is Base64 encoded strings, and OpenAPI spec clients/servers will work with that, but it's only by common convention, and I don't know the base specs like JSON Schema say anything about it (off the top of my head)

In general I find the spec confusing because of a) the use of both TypeScript types and JSON types, and I don't like the use of things like UInt8Array at all, as they are TS domain specific concepts and don't belong in language agnostic specs. b) slightly misleading terminology, like "Scope" instead of "Schema"...

Thank you @FrankSzendzielarz

This commit c08b995 should fix the issue you raised.

Also, @jasonpaulos @mxmauro please refer to the Backwards Compatibility section of the ARC.

FrankSzendzielarz · 2024-04-11T13:53:01Z

Hi, I cannot figure out if, on the latest revision, data to sign is Uint8Array or a string. (I prefer the former because data & platform-independant)

The data to sign is an encoded field of the input JSON text. It will always be a string, of course, as the input is JSON. What encoding depends on the metadata (and I am informed that the spec will be updated to clarify this). What does seem to be clear though, given the comments like this one, is that either the spec is not being read, or not being understood, so I'd suggest specs like these get plain English TLDRs at the top.

- spellcheck

k13n

I made another pass through the ARC, please see my comments below. The ARC is making good progress!

k13n · 2024-05-06T11:11:17Z

ARCs/arc-0060.md

+```json
+{
+  "ARC60Domain" : "arc60",
+  "bytes" : "[99, 50, 97, 57, 51, 99, ..., 57, 49, 53]"


Should the bytes here really be a string or rather a proper array like so:
"bytes" : [99, 50, 97, 57, 51, 99, ..., 57, 49, 53]

k13n · 2024-05-06T11:18:10Z

ARCs/arc-0060.md

+`signingData` is a `StdSigData` object composed of the signing `data` that instantiates a known JSON Schema and the `signer`'s public key.
+
+`metadata` is a `StdSignMetadata` object that describes the signature `scope`, the JSON `schema`, and the `encoding` used to represent the signing bytes. The JSON schema takes two elements: the `bytes` being signed and an optional `prefix`.


Is it intentional that the letter "n" is missing in StdSigData / present in StdSignMetadata? Should it be StdSignData and StdSignMetadata?

k13n · 2024-05-06T11:20:28Z

ARCs/arc-0060.md

+{
+  "data": "/{.../}",
+  "signer": "xxxx"
+}
+{
+  "scope": "...",
+  "schema": "/{.../}",
+  "encoding": "..."
+}


Can we give those objects a name? For example:

signingData = { "data": "{...}", "signer": "xxxx" }; metadata = { "scope": "...", "schema": "{...}", "encoding": "..." };

Also, should it be "data": "{...}" rather than "data": "/{.../}"? (same for schema)

k13n · 2024-05-06T11:22:13Z

ARCs/arc-0060.md

+```json
+{
+  "data": "/{.../}",
+  "signer": "xxxx",
+  "hdPath": {
+    "purpose": 44,
+    "coinType": 0,
+    "account": 0,
+    "change": 0,
+    "addrIdx": 0
+  }
+}
+{
+  "scope": "...",
+  "schema": "/{.../}",
+  "encoding": "..."
+}
+```


same as above:

signingData = { "data": "{...}", "signer": "xxxx", "hdPath": { "purpose": 44, "coinType": 0, "account": 0, "change": 0, "addrIdx": 0 } }; metadata = { "scope": "...", "schema": "{...}", "encoding": "..." };

k13n · 2024-05-06T11:35:59Z

ARCs/arc-0060.md

+- `schema` JSON schema to be used according to the `scope`. ARC-60 compliant JSON schemas must have two mandatory fields:
+  - `ARC60Domain` domain separator for the signing bytes.
+  - `bytes` signing bytes.
+- `encoding` specifies the encoding used for the `schema.bytes` field. If not specified, encoding should be `base64`.


I have two questions here:

Does this encoding apply to (metadata.)schema.bytes or (signingData.)data.bytes? Could it be that when you write schema.bytes you implicitly mean data.bytes?

Since encoding is an optional parameter, this means if no encoding is provided it should be considered base64? In your wallet.ts example no encoding is specified, but the bytes array is represented as a JSON array of integers, not a base64-string

k13n · 2024-05-06T12:18:53Z

ARCs/arc-0060.md

+    - the wallet **MUST** reject if `ARC60Domain="TX"`.
+    - the wallet **MUST** reject if `ARC60Domain="TG"`.


Same as above: are there any other forbidden tags like "Program"?

k13n · 2024-05-06T12:19:37Z

ARCs/arc-0060.md

+  - `data.bytes` must be a valid byte string:
+    - it **MUST** be encoded as `metadata.encoding` if present, otherwise `base64`.
+    - the wallet **MUST** throw a `4602` error if the decoding fails with the given encoding value.
+    - the wallet **MUST** reject if `data.bytes` field is prepended with a forbidden domain separator `TX` or `TG`.


Just marking this for completeness -- same as above

k13n · 2024-05-06T12:25:49Z

ARCs/arc-0060.md

+
+This API was not designed to sign Algorand transactions or a group of transactions (see ARC-1 instead).
+
+## Backwards Compatibility


I'm wondering if we should even mention ARC-47 in this ARC here. I'm inclined to remove it for the sake of simplicity and to keep this ARC as short and concise as possible. If there's demand for signing lsigs with ARC-60, somebody can propose a new ARC, specify the scope, and define the schema, etc.

k13n · 2024-05-06T12:31:18Z

ARCs/arc-0060.md

+
+Users must be aware of what they are signing and for what purpose. The wallet **MUST** always compute a new message dynamically according to the received `signingData` and `metadata`. This prevents the injection of malicious or misleading messages and provides a clear scope of the signing action.
+
+Wallets only support known `ScopeTypes` and schemas. It ensures that signing actions have a clear scope and mitigates the risk of producing unexpected signatures.


I agree that wallets need to hard-code the ScopeTypes and schemas that they support. But this raises the question for me if we even need to include the schema in the metadata field?

Given the ScopeType, the wallet could look up its hard-coded schema and match the signingData against this schema.

Perhaps it's nice to have the schema also in the metadata to make the request self-descriptive. But in an implementation I'd likely ignore metadata.schema and match signingData.bytes against my hard-coded schema. Would that be a problem?

k13n · 2024-05-06T12:52:32Z

ARCs/arc-0060.md

+  - the wallet **MUST** follow the ARC-47 specification: compile the program from the received template and check its integrity with the `hash`.
+  - the compiled program **MUST** be used with the prefix to compute the signing message `msg`, as `msg="Program" || <compiled_lsig>`.
+
+## Test Cases


Once the ARC is stable and about to be finalized, it'd be nice to add some test cases. We could specify a keypair, a message (according to the AUTH schema) and show the resulting signature as a test case.

In another test case we could have a keypair derived from a hd-wallet.

deanstef added 2 commits March 5, 2024 18:38

byte signing arc

70dd6d3

rm ds_store

e17febd

github-actions bot added c-new s-draft t-interface labels Mar 5, 2024

ehanoc reviewed Mar 6, 2024

View reviewed changes

assets/arc-0060/types.ts Outdated Show resolved Hide resolved

ehanoc reviewed Mar 6, 2024

View reviewed changes

deanstef added 3 commits March 6, 2024 11:37

ARC Validator CR

92ded6a

ARC Validator CR 2

f33ae41

bump bulk sigs

67754a8

SudoWeezy and others added 2 commits March 11, 2024 12:14

Fix linting

df31e97

arc60 review

7447a0d

simplified schema + nits

8d8cef3

deanstef changed the title ~~ARC-60 Algorand Wallet Structured Arbitrary Data Signing API~~ ARC-60 Algorand Wallet Structured Data Signing API Mar 16, 2024

leftovers

2472440

ehanoc reviewed Mar 16, 2024

View reviewed changes

assets/arc-0060/wallet.ts Show resolved Hide resolved

ehanoc reviewed Mar 20, 2024

View reviewed changes

deanstef added 3 commits March 21, 2024 10:56

fix ref impl + nits

90a15d7

check tag in bytes

e92a668

nit

dc9b230

k13n reviewed Mar 25, 2024

View reviewed changes

ehanoc reviewed Mar 25, 2024

View reviewed changes

ehanoc reviewed Apr 3, 2024

View reviewed changes

deanstef added 4 commits April 8, 2024 11:15

removed canonicalized stuff

045de9e

typo

a8de5d0

remove unused dep

cafda81

bump message

4a7173d

jasonpaulos reviewed Apr 9, 2024

View reviewed changes

deanstef added 6 commits April 25, 2024 18:01

- clarify data object in Overview

c08b995

- spellcheck

nit

a33817e

add AUTH scope and example + update ref impl + clarity nits

b244ed6

HD wallets support

88c3c32

nit

17c149e

fix auth-schema.json ref

282aac4

k13n reviewed May 6, 2024

View reviewed changes


		#### Interface `SignedDataStr`

		`SignedDataStr` is the produced 64-byte array, ed25519 digital signature, of the signed data.


		### Semantic Requirements

		The call `signData(data, metadata, signer)` MUST either return the signed data `ret` or reject the call throwing an error `err`.

		- the `bytes` must be a valid byte string:
		- the wallet MUST reject if `bytes` is prepended with a forbidden domain separator `TX` or `TG`.


		> This section is non-normative

		Signatures of bytes are processed with the `signData(data, metadata, signer)` function.

		`signingData` is a `StdSigData` object composed of the signing `data` that instantiates a known JSON Schema and the `signer`'s public key.

		`metadata` is a `StdSignMetadata` object that describes the signature `scope`, the JSON `schema`, and the `encoding` used to represent the signing bytes. The JSON schema takes two elements: the `bytes` being signed and an optional `prefix`.

		- the wallet MUST reject if `ARC60Domain="TX"`.
		- the wallet MUST reject if `ARC60Domain="TG"`.


		This API was not designed to sign Algorand transactions or a group of transactions (see ARC-1 instead).

		## Backwards Compatibility


		Users must be aware of what they are signing and for what purpose. The wallet MUST always compute a new message dynamically according to the received `signingData` and `metadata`. This prevents the injection of malicious or misleading messages and provides a clear scope of the signing action.

		Wallets only support known `ScopeTypes` and schemas. It ensures that signing actions have a clear scope and mitigates the risk of producing unexpected signatures.

ARC-60 Algorand Wallet Structured Data Signing API #284

Are you sure you want to change the base?

ARC-60 Algorand Wallet Structured Data Signing API #284

Conversation

deanstef commented Mar 5, 2024 • edited

ehanoc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deanstef commented Mar 6, 2024 • edited

deanstef commented Mar 12, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

k13n left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deanstef Apr 8, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deanstef Apr 8, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mxmauro commented Apr 9, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FrankSzendzielarz Apr 10, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FrankSzendzielarz commented Apr 11, 2024

k13n left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deanstef commented Mar 5, 2024 •

edited

deanstef commented Mar 6, 2024 •

edited

deanstef commented Mar 12, 2024 •

edited

deanstef Apr 8, 2024 •

edited

deanstef Apr 8, 2024 •

edited

FrankSzendzielarz Apr 10, 2024 •

edited