From c2616e2fd5c945b26cf3867854f6efb3262e8f16 Mon Sep 17 00:00:00 2001 From: Jake Urban Date: Fri, 6 Jan 2023 16:46:58 -0800 Subject: [PATCH 1/3] SEP 6,12,24,31: replace `X-Stellar-Signature` with `Signature` --- ecosystem/sep-0006.md | 15 ++++++++------- ecosystem/sep-0012.md | 15 ++++++++------- ecosystem/sep-0024.md | 15 ++++++++------- ecosystem/sep-0031.md | 15 ++++++++------- 4 files changed, 32 insertions(+), 28 deletions(-) diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index 1adb4d7ce..cf6901ce1 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -6,8 +6,8 @@ Title: Deposit and Withdrawal API Author: SDF Status: Active (Interactive components are deprecated in favor of SEP-24) Created: 2017-10-30 -Updated: 2022-11-18 -Version 3.16.0 +Updated: 2023-01-06 +Version 4.0.0 ``` ## Simple Summary @@ -159,8 +159,8 @@ This protocol involves the transfer of value, and so HTTPS is required for all e ## Callback signature This protocol involves the optional use of callbacks that the Anchor can issue to update the wallet on ```status``` of a transaction. -In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in an additional HTTP Header `X-Stellar-Signature`. -This Header MUST follow the specification: `X-Stellar-Signature: t=, s=` where: +In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in an additional HTTP Header `Signature`. +This Header MUST follow the specification: `Signature: t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Wallet hostname will be part of the signature to prevent replay and relay attacks. @@ -171,7 +171,7 @@ It is the wallet's responsability to: ### VERIFY signature -* Check that callback request has `X-Stellar-Signature` header +* Check that callback request has `Signature` header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -197,8 +197,8 @@ It is the wallet's responsability to: * The callback request body * Sign the payload `..` using the Anchor private key * Base64 encode the signature -* Build the `X-Stellar-Signature` header: - * `X-Stellar-Signature: t=, s=` +* Build the `Signature` header: + * `Signature: t=, s=` ## Asset Exchanges @@ -1411,6 +1411,7 @@ If the information was malformed, or if the sender tried to update data that isn ## Changelog +* `v4.0.0`: Replace `X-Stellar-Signature` with `Signature` ([]()) * `v3.16.0`: Add `refund_memo` and `refund_memo_type` to requests initiating transactions. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v3.15.0`: Add `lang` to `/transactions` & `/transaction` parameters, update format to [RFC 4646]. ([#1320](https://github.com/stellar/stellar-protocol/pull/1320)) * `v3.14.0`: Add `quote_id` to the transaction object schema. ([#1268](https://github.com/stellar/stellar-protocol/pull/1268)) diff --git a/ecosystem/sep-0012.md b/ecosystem/sep-0012.md index 6c03433b3..db3c4076f 100644 --- a/ecosystem/sep-0012.md +++ b/ecosystem/sep-0012.md @@ -6,8 +6,8 @@ Title: KYC API Author: Interstellar Status: Active Created: 2018-09-11 -Updated: 2022-08-29 -Version 1.10.0 +Updated: 2023-01-06 +Version 2.0.0 ``` ## Abstract @@ -509,8 +509,8 @@ POST [url from PUT request] See [`GET /customer reponse`](#response) for the POST request fields. -In order to validate the integrity and provenance of the request, the Anchor MUST include a signature in an additional HTTP Header `X-Stellar-Signature`. -This Header MUST follow the specification: `X-Stellar-Signature: t=, s=` where: +In order to validate the integrity and provenance of the request, the Anchor MUST include a signature in an additional HTTP Header `Signature`. +This Header MUST follow the specification: `Signature: t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Wallet hostname will be part of the signature to prevent replay and relay attacks. @@ -521,7 +521,7 @@ It is the wallet's responsability to: ### VERIFY signature -* Check that callback request has `X-Stellar-Signature` header +* Check that callback request has `Signature` header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -547,8 +547,8 @@ It is the wallet's responsability to: * The callback request body * Sign the payload `..` using the Anchor private key * Base64 encode the signature -* Build the `X-Stellar-Signature` header: - * `X-Stellar-Signature: t=, s=` +* Build the `Signature` header: + * `Signature: t=, s=` ## Customer Files @@ -667,6 +667,7 @@ All responses should return `200 OK`. If no files are found for the identifer us ## Changelog +* `v2.0.0`: Replace `X-Stellar-Signature` with `Signature` ([]()) * `v1.10.0`: Clarify that the `account` and `memo` fields should be inferred from the decoded SEP-10 JWT's `sub` value even when not provided in the request body. * `v1.9.1`: Callback signature: using expected host instead of HTTP Header to validate signature * `v1.9.0`: Added signature requirement for the [`callback`](#customer-callback-put) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index dbf068a2e..3055bf1d7 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -6,8 +6,8 @@ Title: Hosted Deposit and Withdrawal Author: SDF Status: Active Created: 2019-09-18 -Updated: 2022-12-22 -Version 2.8.0 +Updated: 2023-01-06 +Version 3.0.0 ``` ## Simple Summary @@ -92,8 +92,8 @@ This protocol involves the transfer of value, and so HTTPS is required for all e _Note that the signature discussed here is only for **URL callbacks** and does not apply to **`postMessage` callbacks**_ This protocol involves the optional use of URL callbacks that the Anchor can issue to update the wallet on ```status``` of a transaction. -In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in an additional HTTP Header `X-Stellar-Signature`. -This Header MUST follow the specification: `X-Stellar-Signature: t=, s=` where: +In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in an additional HTTP Header `Signature`. +This Header MUST follow the specification: `Signature: t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Wallet hostname will be part of the signature to prevent replay and relay attacks. @@ -104,7 +104,7 @@ It is the wallet's responsability to: ### VERIFY signature -* Check that callback request has `X-Stellar-Signature` header +* Check that callback request has `Signature` header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -130,8 +130,8 @@ It is the wallet's responsability to: * The callback request body * Sign the payload `..` using the Anchor private key * Base64 encode the signature -* Build the `X-Stellar-Signature` header: - * `X-Stellar-Signature: t=, s=` +* Build the `Signature` header: + * `Signature: t=, s=` ## Content Type @@ -1018,6 +1018,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ## Changelog +* `v3.0.0`: Rename `X-Stellar-Signature` to `Signature` ([]()) * `v2.8.0`: Add `updated_at` to transaction records. ([#1329](https://github.com/stellar/stellar-protocol/pull/1329)) * `v2.7.0`: Add `refund_memo` and `refund_memo_type` parameters to withdraw endpoint. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v2.6.3`: Clarify `lang` defaults to `en` when specified value is not supported. ([#1320](https://github.com/stellar/stellar-protocol/pull/1320)) diff --git a/ecosystem/sep-0031.md b/ecosystem/sep-0031.md index d8c84ac46..80d707fd9 100644 --- a/ecosystem/sep-0031.md +++ b/ecosystem/sep-0031.md @@ -6,8 +6,8 @@ Title: Cross-Border Payments API Author: SDF Status: Active Created: 2020-04-07 -Updated: 2022-11-16 -Version 2.2.0 +Updated: 2023-01-06 +Version 3.0.0 ``` ## Simple Summary @@ -846,8 +846,8 @@ POST [url from PUT request] See the response to [`GET /transaction/:id`](#get-transaction) for the POST request fields. -In order to validate the integrity and provenance of the request, the Receiving Anchor MUST include a signature in an additional HTTP Header `X-Stellar-Signature`. -This Header MUST follow the specification: `X-Stellar-Signature: t=, s=` where: +In order to validate the integrity and provenance of the request, the Receiving Anchor MUST include a signature in an additional HTTP Header `Signature`. +This Header MUST follow the specification: `Signature: t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the Receiving Anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Sending Anchor hostname will be part of the signature to prevent replay and relay attacks. @@ -858,7 +858,7 @@ It is the Sending Anchor's responsability to: ### VERIFY signature -* Check that callback request has `X-Stellar-Signature` header +* Check that callback request has `Signature` header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -884,8 +884,8 @@ It is the Sending Anchor's responsability to: * The callback request body * Sign the payload `..` using the Receiving Anchor private key * Base64 encode the signature -* Build the `X-Stellar-Signature` header: - * `X-Stellar-Signature: t=, s=` +* Build the `Signature` header: + * `Signature: t=, s=` #### Response @@ -897,6 +897,7 @@ It is important to note that the Receiving Anchor is not obligated, at least by ## Changelog +* `v3.0.0`: Replace `X-Stellar-Signature` with `Signature` ([]()) * `v2.2.0`: Add `refund_memo` & `refund_memo_type` to `POST /transactions` request. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v2.1.0`: Add the `refunded` status and updated the Detailed Receiving Anchor Flow. ([#1311](https://github.com/stellar/stellar-protocol/pull/1311)) * `v2.0.0`: Make `stellar_account_id`, `stellar_memo`, & `stellar_memo_type` optional in the `POST /transactions` response. Add the `status_message` attribute to `GET /transactions/:id`. ([#1294](https://github.com/stellar/stellar-protocol/pull/1294)) From 07ef7ee91043e8ff2ce7f205f4dbf7d69f71d5d7 Mon Sep 17 00:00:00 2001 From: Jake Urban Date: Fri, 6 Jan 2023 16:52:05 -0800 Subject: [PATCH 2/3] add PR link in changelogs --- ecosystem/sep-0006.md | 2 +- ecosystem/sep-0012.md | 2 +- ecosystem/sep-0024.md | 2 +- ecosystem/sep-0031.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index cf6901ce1..3cfedc21e 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -1411,7 +1411,7 @@ If the information was malformed, or if the sender tried to update data that isn ## Changelog -* `v4.0.0`: Replace `X-Stellar-Signature` with `Signature` ([]()) +* `v4.0.0`: Replace `X-Stellar-Signature` with `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v3.16.0`: Add `refund_memo` and `refund_memo_type` to requests initiating transactions. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v3.15.0`: Add `lang` to `/transactions` & `/transaction` parameters, update format to [RFC 4646]. ([#1320](https://github.com/stellar/stellar-protocol/pull/1320)) * `v3.14.0`: Add `quote_id` to the transaction object schema. ([#1268](https://github.com/stellar/stellar-protocol/pull/1268)) diff --git a/ecosystem/sep-0012.md b/ecosystem/sep-0012.md index db3c4076f..e7c6f94fa 100644 --- a/ecosystem/sep-0012.md +++ b/ecosystem/sep-0012.md @@ -667,7 +667,7 @@ All responses should return `200 OK`. If no files are found for the identifer us ## Changelog -* `v2.0.0`: Replace `X-Stellar-Signature` with `Signature` ([]()) +* `v2.0.0`: Replace `X-Stellar-Signature` with `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v1.10.0`: Clarify that the `account` and `memo` fields should be inferred from the decoded SEP-10 JWT's `sub` value even when not provided in the request body. * `v1.9.1`: Callback signature: using expected host instead of HTTP Header to validate signature * `v1.9.0`: Added signature requirement for the [`callback`](#customer-callback-put) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 3055bf1d7..2b5746846 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -1018,7 +1018,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ## Changelog -* `v3.0.0`: Rename `X-Stellar-Signature` to `Signature` ([]()) +* `v3.0.0`: Rename `X-Stellar-Signature` to `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v2.8.0`: Add `updated_at` to transaction records. ([#1329](https://github.com/stellar/stellar-protocol/pull/1329)) * `v2.7.0`: Add `refund_memo` and `refund_memo_type` parameters to withdraw endpoint. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v2.6.3`: Clarify `lang` defaults to `en` when specified value is not supported. ([#1320](https://github.com/stellar/stellar-protocol/pull/1320)) diff --git a/ecosystem/sep-0031.md b/ecosystem/sep-0031.md index 80d707fd9..e4408cca3 100644 --- a/ecosystem/sep-0031.md +++ b/ecosystem/sep-0031.md @@ -897,7 +897,7 @@ It is important to note that the Receiving Anchor is not obligated, at least by ## Changelog -* `v3.0.0`: Replace `X-Stellar-Signature` with `Signature` ([]()) +* `v3.0.0`: Replace `X-Stellar-Signature` with `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v2.2.0`: Add `refund_memo` & `refund_memo_type` to `POST /transactions` request. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v2.1.0`: Add the `refunded` status and updated the Detailed Receiving Anchor Flow. ([#1311](https://github.com/stellar/stellar-protocol/pull/1311)) * `v2.0.0`: Make `stellar_account_id`, `stellar_memo`, & `stellar_memo_type` optional in the `POST /transactions` response. Add the `status_message` attribute to `GET /transactions/:id`. ([#1294](https://github.com/stellar/stellar-protocol/pull/1294)) From 049a17e6f50b2167637d09856d80943e2be5278a Mon Sep 17 00:00:00 2001 From: Jake Urban Date: Mon, 9 Jan 2023 14:31:55 -0800 Subject: [PATCH 3/3] updated to keep X-Stellar-Signature as deprecated --- ecosystem/sep-0006.md | 19 +++++++++++-------- ecosystem/sep-0012.md | 14 +++++++------- ecosystem/sep-0024.md | 21 ++++++++++++--------- ecosystem/sep-0031.md | 14 +++++++------- 4 files changed, 37 insertions(+), 31 deletions(-) diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index 3cfedc21e..196f015fe 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -7,7 +7,7 @@ Author: SDF Status: Active (Interactive components are deprecated in favor of SEP-24) Created: 2017-10-30 Updated: 2023-01-06 -Version 4.0.0 +Version 3.17.0 ``` ## Simple Summary @@ -158,20 +158,22 @@ This protocol involves the transfer of value, and so HTTPS is required for all e ## Callback signature -This protocol involves the optional use of callbacks that the Anchor can issue to update the wallet on ```status``` of a transaction. -In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in an additional HTTP Header `Signature`. -This Header MUST follow the specification: `Signature: t=, s=` where: +This protocol involves the optional use of callbacks that the Anchor can issue to update the wallet on `status` of a transaction. In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in the HTTP Header `Signature` and `X-Stellar-Signature` (deprecated). + +Anchors and wallets should support both headers until the `X-Stellar-Signature` header is removed for the sake of ecosystem compatibility. + +These headers MUST follow the specification: `t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Wallet hostname will be part of the signature to prevent replay and relay attacks. -It is the wallet's responsability to: +It is the wallet's responsibility to: * Verify the signature using the corresponding Stellar `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). * Verify the freshness of the request by comparing the `timestamp` in the request with the current timestamp at the time of the reception and discard every request above a threshold of few seconds (1 or 2 minute(s) maximum). * Send a working callback URL (parameter ```on_change_callback```) to the anchor. ### VERIFY signature -* Check that callback request has `Signature` header +* Check that callback request has `Signature` and `X-Stellar-Signature` (deprecated) header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -197,8 +199,9 @@ It is the wallet's responsability to: * The callback request body * Sign the payload `..` using the Anchor private key * Base64 encode the signature -* Build the `Signature` header: +* Build the `Signature` and `X-Stellar-Signature` (deprecated) header: * `Signature: t=, s=` + * `X-Stellar-Signature: t=, s=` ## Asset Exchanges @@ -1411,7 +1414,7 @@ If the information was malformed, or if the sender tried to update data that isn ## Changelog -* `v4.0.0`: Replace `X-Stellar-Signature` with `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) +* `v3.17.0`: Deprecate `X-Stellar-Signature` in favor of `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v3.16.0`: Add `refund_memo` and `refund_memo_type` to requests initiating transactions. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v3.15.0`: Add `lang` to `/transactions` & `/transaction` parameters, update format to [RFC 4646]. ([#1320](https://github.com/stellar/stellar-protocol/pull/1320)) * `v3.14.0`: Add `quote_id` to the transaction object schema. ([#1268](https://github.com/stellar/stellar-protocol/pull/1268)) diff --git a/ecosystem/sep-0012.md b/ecosystem/sep-0012.md index e7c6f94fa..3284718a3 100644 --- a/ecosystem/sep-0012.md +++ b/ecosystem/sep-0012.md @@ -7,7 +7,7 @@ Author: Interstellar Status: Active Created: 2018-09-11 Updated: 2023-01-06 -Version 2.0.0 +Version 1.11.0 ``` ## Abstract @@ -509,19 +509,18 @@ POST [url from PUT request] See [`GET /customer reponse`](#response) for the POST request fields. -In order to validate the integrity and provenance of the request, the Anchor MUST include a signature in an additional HTTP Header `Signature`. -This Header MUST follow the specification: `Signature: t=, s=` where: +In order to validate the integrity and provenance of the request, the Anchor MUST include a signature in the HTTP Header `Signature` and `X-Stellar-Signature` (deprecated). These headers MUST follow the specification: `t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Wallet hostname will be part of the signature to prevent replay and relay attacks. -It is the wallet's responsability to: +It is the wallet's responsibility to: * Verify the signature using the corresponding Stellar `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). * Verify the freshness of the request by comparing the `timestamp` in the request with the current timestamp at the time of the reception and discard every request above a threshold of few seconds (1 or 2 minute(s) maximum). * Send a working callback URL to the anchor. ### VERIFY signature -* Check that callback request has `Signature` header +* Check that callback request has `Signature` and `X-Stellar-Signature` (deprecated) header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -547,8 +546,9 @@ It is the wallet's responsability to: * The callback request body * Sign the payload `..` using the Anchor private key * Base64 encode the signature -* Build the `Signature` header: +* Build the `Signature` and `X-Stellar-Signature` (deprecated) header: * `Signature: t=, s=` + * `X-Stellar-Signature: t=, s=` ## Customer Files @@ -667,7 +667,7 @@ All responses should return `200 OK`. If no files are found for the identifer us ## Changelog -* `v2.0.0`: Replace `X-Stellar-Signature` with `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) +* `v1.11.0`: Deprecate `X-Stellar-Signature` in favor of `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v1.10.0`: Clarify that the `account` and `memo` fields should be inferred from the decoded SEP-10 JWT's `sub` value even when not provided in the request body. * `v1.9.1`: Callback signature: using expected host instead of HTTP Header to validate signature * `v1.9.0`: Added signature requirement for the [`callback`](#customer-callback-put) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 2b5746846..eff9b90f6 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -7,7 +7,7 @@ Author: SDF Status: Active Created: 2019-09-18 Updated: 2023-01-06 -Version 3.0.0 +Version 2.9.0 ``` ## Simple Summary @@ -91,20 +91,22 @@ This protocol involves the transfer of value, and so HTTPS is required for all e _Note that the signature discussed here is only for **URL callbacks** and does not apply to **`postMessage` callbacks**_ -This protocol involves the optional use of URL callbacks that the Anchor can issue to update the wallet on ```status``` of a transaction. -In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in an additional HTTP Header `Signature`. -This Header MUST follow the specification: `Signature: t=, s=` where: +This protocol involves the optional use of URL callbacks that the Anchor can issue to update the wallet on `status` of a transaction. In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in the HTTP Header `Signature` and `X-Stellar-Signature` (deprecated). + +Anchors and wallets should support both headers until the `X-Stellar-Signature` header is removed for the sake of ecosystem compatibility. + +These headers MUST follow the specification: `t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Wallet hostname will be part of the signature to prevent replay and relay attacks. -It is the wallet's responsability to: +It is the wallet's responsibility to: * Verify the signature using the corresponding Stellar `SIGNING_KEY` field of the anchor's [`stellar.toml`](sep-0001.md). * Verify the freshness of the request by comparing the `timestamp` in the request with the current timestamp at the time of the reception and discard every request above a threshold of few seconds (1 or 2 minute(s) maximum). -* Send a working callback URL (parameter ```callback``` or ```on_change_callback```) to the anchor. +* Send a working callback URL (parameter `callback` or `on_change_callback`) to the anchor. ### VERIFY signature -* Check that callback request has `Signature` header +* Check that callback request has `Signature` and `X-Stellar-Signature` (deprecated) header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -130,8 +132,9 @@ It is the wallet's responsability to: * The callback request body * Sign the payload `..` using the Anchor private key * Base64 encode the signature -* Build the `Signature` header: +* Build the `Signature` and `X-Stellar-Signature` (deprecated) header: * `Signature: t=, s=` + * `X-Stellar-Signature: t=, s=` ## Content Type @@ -1018,7 +1021,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ## Changelog -* `v3.0.0`: Rename `X-Stellar-Signature` to `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) +* `v2.9.0`: Deprecate `X-Stellar-Signature` in favor of `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v2.8.0`: Add `updated_at` to transaction records. ([#1329](https://github.com/stellar/stellar-protocol/pull/1329)) * `v2.7.0`: Add `refund_memo` and `refund_memo_type` parameters to withdraw endpoint. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v2.6.3`: Clarify `lang` defaults to `en` when specified value is not supported. ([#1320](https://github.com/stellar/stellar-protocol/pull/1320)) diff --git a/ecosystem/sep-0031.md b/ecosystem/sep-0031.md index e4408cca3..8a657bfa9 100644 --- a/ecosystem/sep-0031.md +++ b/ecosystem/sep-0031.md @@ -7,7 +7,7 @@ Author: SDF Status: Active Created: 2020-04-07 Updated: 2023-01-06 -Version 3.0.0 +Version 2.3.0 ``` ## Simple Summary @@ -846,19 +846,18 @@ POST [url from PUT request] See the response to [`GET /transaction/:id`](#get-transaction) for the POST request fields. -In order to validate the integrity and provenance of the request, the Receiving Anchor MUST include a signature in an additional HTTP Header `Signature`. -This Header MUST follow the specification: `Signature: t=, s=` where: +In order to validate the integrity and provenance of the request, the Receiving Anchor MUST include a signature in the HTTP Header `Signature` and `X-Stellar-Signature` (deprecated). These headers MUST follow the specification: `t=, s=` where: * __timestamp__ is the current Unix timestamp (number of seconds since epoch) at the time the callback is sent. This is used to assure the freshness of the request and to prevent this request to be replayed in the future. * __base64 signature__ is the base64 encoding of the request signature. We explain below how to compute and verify this signature. The signature is computed using the Stellar private key linked to the `SIGNING_KEY` field of the Receiving Anchor's [`stellar.toml`](sep-0001.md). Note that the timestamp and the Sending Anchor hostname will be part of the signature to prevent replay and relay attacks. -It is the Sending Anchor's responsability to: +It is the Sending Anchor's responsibility to: * Verify the signature using the corresponding Stellar `SIGNING_KEY` field of the Receiving Anchor's [`stellar.toml`](sep-0001.md). * Verify the freshness of the request by comparing the `timestamp` in the request with the current timestamp at the time of the reception and discard every request above a threshold of few seconds (1 or 2 minute(s) maximum). * Send a working callback URL to the Receiving Anchor. ### VERIFY signature -* Check that callback request has `Signature` header +* Check that callback request has `Signature` and `X-Stellar-Signature` (deprecated) header * Parse the header and extract: * Key `t`: __timestamp__ * Key `s`: __base64 signature__ @@ -884,8 +883,9 @@ It is the Sending Anchor's responsability to: * The callback request body * Sign the payload `..` using the Receiving Anchor private key * Base64 encode the signature -* Build the `Signature` header: +* Build the `Signature` and `X-Stellar-Signature` (deprecated) header: * `Signature: t=, s=` + * `X-Stellar-Signature : t=, s=` #### Response @@ -897,7 +897,7 @@ It is important to note that the Receiving Anchor is not obligated, at least by ## Changelog -* `v3.0.0`: Replace `X-Stellar-Signature` with `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) +* `v2.3.0`: Deprecate `X-Stellar-Signature` in favor of `Signature` ([#1333](https://github.com/stellar/stellar-protocol/pull/1333)) * `v2.2.0`: Add `refund_memo` & `refund_memo_type` to `POST /transactions` request. ([#1321](https://github.com/stellar/stellar-protocol/pull/1321)) * `v2.1.0`: Add the `refunded` status and updated the Detailed Receiving Anchor Flow. ([#1311](https://github.com/stellar/stellar-protocol/pull/1311)) * `v2.0.0`: Make `stellar_account_id`, `stellar_memo`, & `stellar_memo_type` optional in the `POST /transactions` response. Add the `status_message` attribute to `GET /transactions/:id`. ([#1294](https://github.com/stellar/stellar-protocol/pull/1294))