eBay Digital Signatures for APIs Done

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

“Due to regulatory requirements applicable to our EU/UK sellers, for certain APIs, developers need to add digital signatures to the respective HTTP call. This document specifies how these signatures are created and added to HTTP payloads.“

More details available here - https://developer.ebay.com/develop/guides/digital-signatures-for-apis

eBay are adding additional headers which we need to include in some of our requests. The changes will take effect by the end of January 2023.

Signatures are required when the call is made for EU- or UK-domiciled sellers, and only for the following APIs/methods:

• All methods in the Finances API
• issueRefund in the Fulfillment API
• GetAccount in the Trading API
• The following methods in the Post-Order API:
  • Issue Inquiry Refund
  • Issue case refund
  • Issue return refund
  • Process Return Request
  • Create Cancellation Request
  • Approve Cancellation Request

Please note that signatures may be added for other APIs and/or for other sellers. eBay's system will ignore the signatures, but the API call will be accepted and handled in an ordinary manner.

At the moment our eBay integration is using the issueRefund and Post-Order API calls.

They are also adding a new request which we have to use in order to generate the x-ebay-signature-key.

1. Key Management API

API Call: POST https://apiz.ebay.com/developer/key_management/v1/signing_key

API Docs: https://developer.ebay.com/api-docs/developer/key-management/resources/signing_key/methods/createSigningKey#h2-samples

Sample Request: URL - POST https://apiz.ebay.com/developer/key_management/v1/signing_key Headers- Authorization, Content-Type Body -

{
    "signingKeyCipher": "ED25519"
}

OR

{
    "signingKeyCipher": "RSA"
}

Sample Response:

{
    "signingKeyId": "daa85f0a-d62e-4914-941d-ad6b4320b538",
    "signingKeyCipher": "ED25519",
    "publicKey": "MCowBQYDK2VwAyEAzwwQImoUiByEznP+cQZ77D+Nda/zymzIJwIRz02UMAk=",
    "privateKey": "MC4CAQAwBQYDK2VwBCIEIK7aOaAmUXkpd03Tx/zHBvn12mM85C7SVkHLkaXcxwvf",
    "jwe": "eyJ6aXAiOiJERUYiLCJraWQiOiJiNmI4ZWY2MC0zODU4LTRiMGUtYTI5My1mZjQyOGJkZmMyZmMiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiU0E3dHFVX21TQ0pxRVFyZkRlZFc1USIsImFsZyI6IkEyNTZHQ01LVyIsIml2IjoiNDB4ajF0VE1PaGtvdVBUcCJ9.yjwTCX3EQHM59QDhtraS0NamXvN-Mwki4rCbI7thLy4.WE4PeLiJ12_m4QAn.fDO0QNoK9ad7bfEjb2sufz5lvE95C4y8S61OysAa3B7AoJ0ksJqRGPltv7kdGUa8kN9SidAGMXEvEIXoQz7tnx4Khu--U0qUsaGtFEygtzySJQ5RbA2UpK8ZF13toqD-b7qOzVw2buT9rHhJI0HYIRadM7Bp9v8usklH9WDROWof0H9OUuZHDkSheknUYm9wmGnoHSwI-k43a42MaSd8unDnu361GoxaOGCQZ-UYBMLcWhkMJfMFppKLxEXH1Of4A6977_nQ.QPCP-wXFOoocUeoXlgxFMg",
    "creationTime": 1672664880,
    "expirationTime": 1767272880
}

From the response we need to use the jwe as x-ebay-signature-key. Please note it is up to the dev team to decide where to store the new details. The key is valid for 3 years after that it need to be re-generated.

2. Create the Content-Digest header

NOTE: When no HTTP payload is included (e.g., for a GET call,) this header is not required.

When an HTTP payload is included, this header provides an SHA-256 digest over the HTTP payload.

To add the Content-Digest header, calculate an SHA-256 digest over the HTTP payload (in UTF-8 character encoding). While the specification allows adding more than one digest (e.g., both SHA-256 and SHA-512,) only the SHA-256 is needed in our case.

For complete information about how to add the Content-Digest header, refer to Section 2, The Content-Digest Field, of IETF draft-ietf-httpbis-digest-headers-10.

To review an example of adding a Content-Digest header, refer to Section B.1. Server Returns Full Representation Data, of IETF draft-ietf-httpbis-digest-headers-10.

Consider the following payload:

{"hello": "world"}

In this case, the value of the Content-Digest header will be:

sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:

3. Create the signature base

The signature base is a US-ASCII string containing standard HTTP message components covered by the signature. To create the signature base, the signer or verifier concatenates together entries for each component identifier in the signature's covered components (including their parameters).

For complete information, including the detailed algorithm to create the signature base, refer to Section 2.5, Creating the Signature Base, of IETF draft-ietf-httpbis-message-signatures-15.

For additional information about creating individual pseudo headers that may be part of the signature base, refer to Section 2.2, Derived Components, of draft-ietf-httpbis-message-signatures-15.

4. Create the Signature header

The Signature header is created using the Private Key value generated by the Key Management API (x-ebay-signature-key header) and the signature base.

The value of the Signature header is created as described in Section 3.1, Creating a Signature, of IETF draft-ietf-httpbis-message-signatures-15.

Depending on the cipher that is to be used, refer to the following specific sections of IETF draft-ietf-httpbis-message-signatures-15 for complete information:

• RSASSA-PKCS1-v1_5 using SHA-256
• EdDSA using curve edwards25519

To review examples illustrating how signature headers are created, refer to Appendix B, Examples, of IETF draft-ietf-httpbis-message-signatures-15.

Important! In order to further ensure the security of confidential client information, eBay does not store Private Key values in any system. If a developer loses their Private Key they must generate new keypairs using the Key Management API.

5: Create the Signature-Input header

This header indicates which headers and pseudo-headers are included, as well as the order in which they are used when calculating the signature.

For complete information about creating the Signature-Input header refer to Section 4, Including a message Signature in a Message, of IETF draft-ietf-httpbis-message-signatures-15.

The value of the Signature-Input header is:

sig1=("content-digest" "x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308

NOTE: The value assigned to the parameter created is the Unix timestamp when the signature is first created.

If no HTTP payload is included, the header would be:

sig1=("x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308

More details about signature is available here - https://qubitsandbytes.co.uk/ebay-developer-api/ebay-digital-signatures-explained/