From c35f23b7f88cc5fbe925fd5631470660ee6259ae Mon Sep 17 00:00:00 2001 From: Anton Dalgren Date: Tue, 15 Aug 2023 09:39:12 +0200 Subject: [PATCH 1/3] feat: Adds CAIP-122 standard for XRP Ledger. (#2) * feat: Adds CAIP-122 standard for XRP Ledger. * fix: Add some clarifications and follow the ripple-keypairs implementations for signing and verification * fix: Branch was renamed from master to main * fix: Remove double --- xrpl/README.md | 4 +- xrpl/caip122.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 1 deletion(-) create mode 100644 xrpl/caip122.md diff --git a/xrpl/README.md b/xrpl/README.md index e8747320..6a471f00 100644 --- a/xrpl/README.md +++ b/xrpl/README.md @@ -6,7 +6,8 @@ discussions-to: https://github.com/ChainAgnostic/namespaces/pull/57/ status: Draft type: Informational created: 2023-02-23 -requires: ["CAIP-2", "CAIP-10"] +updated: 2023-08-12 +requires: ["CAIP-2", "CAIP-10", "CAIP-122"] --- # Namespace for XRP Ledger @@ -24,6 +25,7 @@ networks. - [XRP Ledger documentation](https://xrpl.org/docs.html) - [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md) - [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md) +- [CAIP-122](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-122.md) ## Rights diff --git a/xrpl/caip122.md b/xrpl/caip122.md new file mode 100644 index 00000000..1d186703 --- /dev/null +++ b/xrpl/caip122.md @@ -0,0 +1,104 @@ +--- +namespace-identifier: xrpl-caip122 +title: XRP Ledger Namespace - SIWx +author: Anton Dalgren (@antondalgren) +discussions-to: https://github.com/ChainAgnostic/namespaces/pull/57/ +status: Draft +type: Standard +created: 2023-08-12 +requires: ["CAIP-122", "CAIP-2", "CAIP-10"] +--- + +## CAIP-122 + +For context, see the [CAIP-122][CAIP-122] specification. + +## Rationale + +This specification provides the signing algorithm to use, the `type` of the signing algorithm to identify it, and a method for signature creation and verification as required by [CAIP-122][CAIP-122]. + +## Specification + +### Signing Algorithm + +XRPL uses the ECDSA [secp256k1][secp256k1] or EdDSA [Ed25519][Ed25519] signing algorithm for signing and verifying messages depending on the type of the keypair that is being used. A [secp256k1][secp256k1] keypair will be using the [secp256k1][secp256k1] algorithm and a [Ed25519][Ed25519] keypair will be using the [Ed25519][Ed25519] algorithm. + +Prior to the message being signed using [secp256k1][secp256k1], it needs to be hashed using the SHA-512/2 algorithm. Correspondingly it needs to be converted to bytes prior to signing it using the [Ed25519][Ed25519] algorithm. + +### Signature Type + +We propose using the signature type `xrpl:secp256k1` and `xrpl:ed25519` to refer to the chain and algorithm used uniquely. + +### Signature Creation + +The abstract data model must be converted into a string representation in an unambigious format, and then the string converted to the proper format mentioned in [signing algorithm](#signing-algorithm) to be signed over with the proper algorithm. +Depending on the method used for signatures, this conversion may or may not happen automatically. For example, if using [ripple-keypairs][ripple-keypairs] you need to convert it to a byte representation before signing using [Ed25519][Ed25519] and for [secp256k1][secp256k1] the library will handle hashing and signing. + +We propose the following string format, inspired by [EIP-4361][EIP-4361]. + +``` +${domain} wants you to sign in with your XRPL account: +${address} + +${statement} + +URI: ${uri} +Version: ${version} +Chain ID: ${chain-id} +Nonce: ${nonce} +Issued At: ${issued-at} +Expiration Time: ${expiration-time} +Not Before: ${not-before} +Request ID: ${request-id} +Resources: +- ${resources[0]} +- ${resources[1]} +... +- ${resources[n]} +``` + +For example, + +``` +service.org wants you to sign in with your XRPL account: +r4FTvnahbUfhe1WK2EK5Jz4cNvdFvT8Dzt + +I accept the ServiceOrg Terms of Service: https://service.org/tos + +URI: https://service.org/login +Version: 1 +Chain ID: 0 +Nonce: 32891757 +Issued At: 2021-09-30T16:25:24.000Z +Resources: +- ipfs://Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu +- https://example.com/my-web2-claim.json +``` + +The preceeding example would be hashed to `4beb3f7d5c8bf8deab467de033628274a9053f688f82e0f023cddcb0564cfc9a` prior to being signed using the [secp256k1][secp256k1] algorithm. + +The conversion to bytes prior to signing with [Ed25519][Ed25519] would be: +``` +736572766963652e6f72672077616e747320796f7520746f207369676e20696e207769746820796f7572205852504c206163636f756e743a0a72344654766e6168625566686531574b32454b354a7a34634e766446765438447a740a0a49206163636570742074686520536572766963654f7267205465726d73206f6620536572766963653a2068747470733a2f2f736572766963652e6f72672f746f730a0a5552493a2068747470733a2f2f736572766963652e6f72672f6c6f67696e0a56657273696f6e3a20310a436861696e2049443a20300a4e6f6e63653a2033323839313735370a4973737565642041743a20323032312d30392d33305431363a32353a32342e3030305a0a5265736f75726365733a0a2d20697066733a2f2f516d653773733341525667787636725871565069696b4d4a3875324e4c676d67737a673133705972444b456f69750a2d2068747470733a2f2f6578616d706c652e636f6d2f6d792d776562322d636c61696d2e6a736f6e +``` +### Signature Verification + +Signature verification behaves similarly. We can use standard [secp256k1][secp256k1]/[Ed25519][Ed25519] signature verification. We convert the input message to a bytes representation of the string format, then verify the signature over that using the public key. These verification methods are also available in the [ripple-keypairs][ripple-keypairs] library. + +## References + +[EIP-4361]: https://eips.ethereum.org/EIPS/eip-4361 +[caip-10]: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md +[caip-2]: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md +[caip-122]: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-122.md +[ed25519]: https://ed25519.cr.yp.to/ +[secp256k1]: https://en.bitcoin.it/wiki/Secp256k1 +[ripple-keypairs]: https://www.npmjs.com/package/ripple-keypairs + +- [EIP-4361][]: Sign-In with Ethereum +- [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md): Account ID Specification +- [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md): Blockchain ID Specification +- [CAIP-122](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-122.md): Sign in With X Specification +- [Ed25519](https://ed25519.cr.yp.to/): Ed25519: high-speed high-security signatures +- [secp256k1](https://en.bitcoin.it/wiki/Secp256k1): secp256k1 algorithm. +- [ripple-keypairs](https://www.npmjs.com/package/ripple-keypairs): Ripple keypairs From 2895f6bc1ce486e7a92560eaf796ebf83db9fab9 Mon Sep 17 00:00:00 2001 From: Bumblefudge Date: Wed, 23 Aug 2023 00:36:56 -0700 Subject: [PATCH 2/3] minor editorial (#3) --- xrpl/caip122.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/xrpl/caip122.md b/xrpl/caip122.md index 1d186703..6dd878f4 100644 --- a/xrpl/caip122.md +++ b/xrpl/caip122.md @@ -21,9 +21,10 @@ This specification provides the signing algorithm to use, the `type` of the sign ### Signing Algorithm -XRPL uses the ECDSA [secp256k1][secp256k1] or EdDSA [Ed25519][Ed25519] signing algorithm for signing and verifying messages depending on the type of the keypair that is being used. A [secp256k1][secp256k1] keypair will be using the [secp256k1][secp256k1] algorithm and a [Ed25519][Ed25519] keypair will be using the [Ed25519][Ed25519] algorithm. +XRPL uses the ECDSA [secp256k1][] or EdDSA [Ed25519][] signing algorithm for signing and verifying messages depending on the type of the keypair that is being used. A [secp256k1][] keypair will be using the [secp256k1][] algorithm and a [Ed25519][] keypair will be using the [Ed25519][] algorithm. -Prior to the message being signed using [secp256k1][secp256k1], it needs to be hashed using the SHA-512/2 algorithm. Correspondingly it needs to be converted to bytes prior to signing it using the [Ed25519][Ed25519] algorithm. +Prior to the message being signed using [secp256k1][], it needs to be hashed using the 512bit digest of the SHA-2 algorithm, commonly referred to as [SHA-512][] and specified in [RFC4634][]. +Correspondingly, a message needs to be serialized to bytes prior to signing it with the [Ed25519][] algorithm. ### Signature Type @@ -31,10 +32,11 @@ We propose using the signature type `xrpl:secp256k1` and `xrpl:ed25519` to refer ### Signature Creation -The abstract data model must be converted into a string representation in an unambigious format, and then the string converted to the proper format mentioned in [signing algorithm](#signing-algorithm) to be signed over with the proper algorithm. -Depending on the method used for signatures, this conversion may or may not happen automatically. For example, if using [ripple-keypairs][ripple-keypairs] you need to convert it to a byte representation before signing using [Ed25519][Ed25519] and for [secp256k1][secp256k1] the library will handle hashing and signing. +The abstract data model must be canonicalized to a string representation in an unambigious format, and then the string serialized to the proper binary format mentioned [above](#signing-algorithm) to be signed over with the proper algorithm. +Depending on the method or libraries used for signatures, this conversion may or may not happen automatically. +For example, if using [ripple-keypairs][], you will need to convert the key to a byte representation before signing using [Ed25519][] and for [secp256k1][] the library will handle hashing and signing internally. -We propose the following string format, inspired by [EIP-4361][EIP-4361]. +We propose the following string format, inspired by the ABNF in [EIP-4361][]. ``` ${domain} wants you to sign in with your XRPL account: @@ -75,15 +77,17 @@ Resources: - https://example.com/my-web2-claim.json ``` -The preceeding example would be hashed to `4beb3f7d5c8bf8deab467de033628274a9053f688f82e0f023cddcb0564cfc9a` prior to being signed using the [secp256k1][secp256k1] algorithm. +The preceeding example would be hashed to `4beb3f7d5c8bf8deab467de033628274a9053f688f82e0f023cddcb0564cfc9a` prior to being signed using the [secp256k1][] algorithm. -The conversion to bytes prior to signing with [Ed25519][Ed25519] would be: +The serialization of this string prior to signing with [Ed25519][Ed25519] would produce: ``` 736572766963652e6f72672077616e747320796f7520746f207369676e20696e207769746820796f7572205852504c206163636f756e743a0a72344654766e6168625566686531574b32454b354a7a34634e766446765438447a740a0a49206163636570742074686520536572766963654f7267205465726d73206f6620536572766963653a2068747470733a2f2f736572766963652e6f72672f746f730a0a5552493a2068747470733a2f2f736572766963652e6f72672f6c6f67696e0a56657273696f6e3a20310a436861696e2049443a20300a4e6f6e63653a2033323839313735370a4973737565642041743a20323032312d30392d33305431363a32353a32342e3030305a0a5265736f75726365733a0a2d20697066733a2f2f516d653773733341525667787636725871565069696b4d4a3875324e4c676d67737a673133705972444b456f69750a2d2068747470733a2f2f6578616d706c652e636f6d2f6d792d776562322d636c61696d2e6a736f6e ``` ### Signature Verification -Signature verification behaves similarly. We can use standard [secp256k1][secp256k1]/[Ed25519][Ed25519] signature verification. We convert the input message to a bytes representation of the string format, then verify the signature over that using the public key. These verification methods are also available in the [ripple-keypairs][ripple-keypairs] library. +Signature verification behaves similarly. We can use standard [secp256k1][] or[Ed25519][] signature verification. +We convert the input message to a bytes representation of the string format, then verify the signature over that using the public key. +Both of these verification methods are available in the [ripple-keypairs][] library. ## References @@ -94,6 +98,8 @@ Signature verification behaves similarly. We can use standard [secp256k1][secp25 [ed25519]: https://ed25519.cr.yp.to/ [secp256k1]: https://en.bitcoin.it/wiki/Secp256k1 [ripple-keypairs]: https://www.npmjs.com/package/ripple-keypairs +[SHA-512]: https://csrc.nist.gov/projects/hash-functions +[RFC4634]: https://datatracker.ietf.org/doc/html/rfc4634 - [EIP-4361][]: Sign-In with Ethereum - [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md): Account ID Specification @@ -102,3 +108,5 @@ Signature verification behaves similarly. We can use standard [secp256k1][secp25 - [Ed25519](https://ed25519.cr.yp.to/): Ed25519: high-speed high-security signatures - [secp256k1](https://en.bitcoin.it/wiki/Secp256k1): secp256k1 algorithm. - [ripple-keypairs](https://www.npmjs.com/package/ripple-keypairs): Ripple keypairs +- [SHA-512]: NIST.gov overview of SHA-2 family of algorithms +- [RFC4634]: IETF RFC including the SHA-512 implementation \ No newline at end of file From 992d70264ffff9fb591669eac3097f6c9ea02524 Mon Sep 17 00:00:00 2001 From: Anton Dalgren Date: Mon, 6 Nov 2023 15:41:11 +0100 Subject: [PATCH 3/3] fix: Added a signature metadata object to the response It is used to verify the that the signature originates from the provided public key --- xrpl/caip122.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/xrpl/caip122.md b/xrpl/caip122.md index 6dd878f4..17538451 100644 --- a/xrpl/caip122.md +++ b/xrpl/caip122.md @@ -30,6 +30,16 @@ Correspondingly, a message needs to be serialized to bytes prior to signing it w We propose using the signature type `xrpl:secp256k1` and `xrpl:ed25519` to refer to the chain and algorithm used uniquely. +### Signature Meta + +We propose that the signature meta contains the public key of the signer. This is to allow for the requester to verify that the signature belongs to the specified public key. The requester is also responsible for verifying that the public key that was used to sign the message is properly associated with the address in the payload. + +``` +type SignatureMeta struct { + SigningPubKey String +} +``` + ### Signature Creation The abstract data model must be canonicalized to a string representation in an unambigious format, and then the string serialized to the proper binary format mentioned [above](#signing-algorithm) to be signed over with the proper algorithm.