-
Notifications
You must be signed in to change notification settings - Fork 65
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Adds CAIP-122 standard for XRP Ledger. (#84)
- Loading branch information
Showing
2 changed files
with
125 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| --- | ||
| 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][] 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][], 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 | ||
|
|
||
| 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. | ||
| 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 the ABNF in [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][] algorithm. | ||
|
|
||
| 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][] 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 | ||
|
|
||
| [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 | ||
| [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 | ||
| - [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 | ||
| - [SHA-512]: NIST.gov overview of SHA-2 family of algorithms | ||
| - [RFC4634]: IETF RFC including the SHA-512 implementation |