APIのデジタル署名

APIのデジタル署名 (Digital Signatures for APIs)

はじめに

EU/UKのセラー（販売者）に適用される規制要件により、特定のAPIについては、開発者がそれぞれのHTTPコールにデジタル署名を追加する必要があります。このドキュメントでは、これらの署名を作成し、HTTPペイロードに追加する方法について規定します。

対象となるAPI

署名は、EUまたはUKに居住するセラーに対してコールが行われる場合に必須となります。また、対象となるのは以下のAPI/メソッドのみです：

  • Finances APIのすべてのメソッド
  • Fulfillment APIのissueRefund
  • Trading APIのGetAccount
  • Post-Order APIの以下のメソッド：
    • Issue Inquiry Refund
    • Issue case refund
    • Issue return refund
    • Process Return Request
    • Create Cancellation Request
    • Approve Cancellation Request

その他のAPIや他の地域のセラーに対しても署名を追加することは可能です。その場合、eBayのシステムは署名を無視しますが、APIコールは通常通り受け入れられ、処理されます。

ペイロード署名の作成

eBayの署名実装は、以下のIETF標準に準拠しています：

  • RFC9421
  • RFC9530
注： 上記の標準を確認することを強く推奨します。

EU/UKに居住するセラーに代わって呼び出される対象APIの各HTTPペイロードには、以下のHTTPヘッダーが追加されます：

  • x-ebay-signature-key: 必須
  • Content-Digest: 条件付き
  • Signature: 必須
  • Signature-Input: 必須

eBayのKey Management APIは、x-ebay-signature-keyおよびSignatureヘッダーの作成に使用される暗号化されたキーペアを生成します。

上記の4つのHTTPヘッダーを作成するために必要な手順は以下の通りです：

1. x-ebay-signature-keyヘッダーの作成

x-ebay-signature-key ヘッダーは常にJWEを含みます。

開発者はKey Management APIを使用して、以下のキーペアを作成します：

  • 秘密鍵 (Private Key)
  • 公開鍵 (Public Key)
  • JWE形式の公開鍵 (Public Key as JWE)
重要： 機密性の高いクライアント情報のセキュリティを確保するため、eBayはいかなるシステムにおいても秘密鍵 (Private Key)の値を保存しません。開発者が秘密鍵を紛失した場合は、Key Management APIを使用して新しいキーペアを生成する必要があります。

x-ebay-signature-key ヘッダーの値は、Key Management APIによって作成されたJWE形式の公開鍵 (Public Key as JWE)の値となります。

例： 

x-ebay-signature-key: eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiTjZIc2ItenlIXzZ4blFHQUhOdHByZyIsImFsZyI6IkEyNTZHQ01LVyIsIml2IjoiNjQ1Z0Rzc2lOYUZFb2pOWCJ9.rSWQSIKGgu_gAhLdG87fIpRYyI57KMQKYJpgQoXhPso.jvrOE0g2Q7A8h_Rj.uZsaA0VaVjL9HiciAilnNsos7Da-Fx5W3tr9sZO4qSPD-hB9t-lacy96lyeLiixs0nHXZ21iEwFYkqOllxpqW6eyJPb6lLDrnzg8Nx5AvizLagSDT35_3xBTu6EWf6x-lWBMKiBj8zo31wdjaGWMExcaQSPpwZxbJ3Z1sM4aZmHX7sjjnIT0V9kH1kAj0kD7uGuJ8KlMvrl011z68kJt-ilYG4FZn_Z5.CZzMDhEn1jqL45bYvbO3ig

2. Content-Digestヘッダーの作成

注： HTTPペイロードが含まれない場合（例：GETコールなど）、このヘッダーは不要です。

HTTPペイロードが含まれない場合、このヘッダーは不要です。

HTTPペイロードが含まれる場合、このヘッダーはHTTPペイロードに対するSHA-256ダイジェストを提供します。

Content-Digestヘッダーを追加するには、HTTPペイロード（UTF-8文字エンコーディング）に対してSHA-256ダイジェストを計算します。仕様では複数のダイジェスト（例：SHA-256とSHA-512の両方）を追加することが許可されていますが、今回のケースではSHA-256のみが必要です。

Content-Digestヘッダーの追加方法に関する完全な情報については、RFC9530のセクション2「The Content-Digest Field」を参照してください。

Content-Digestヘッダーの追加例を確認するには、RFC9530のセクションB.1「Server Returns Full Representation Data」を参照してください。

以下のペイロードを例とします： 

{"hello": "world"}

この場合、Content-Digestヘッダーの値は以下のようになります： 

sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:

3. 署名ベース (Signature base) の作成

署名ベースは、署名の対象となる標準的なHTTPメッセージコンポーネントを含むUS-ASCII文字列です。署名ベースを作成するには、署名者または検証者が、署名の対象コンポーネント（パラメータを含む）の各コンポーネント識別子のエントリを連結します。

署名ベースを作成するための詳細なアルゴリズムを含む完全な情報については、RFC9421のセクション2.5「Creating the Signature Base」を参照してください。

署名ベースの一部となる可能性のある個々の疑似ヘッダー (pseudo headers) の作成に関する追加情報については、RFC9421のセクション2.2「Derived Components」を参照してください。

4. Signatureヘッダーの作成

Signature ヘッダーは、Key Management APIによって生成された秘密鍵 (Private Key)の値（x-ebay-signature-keyヘッダー用）と、署名ベースを使用して作成されます。

Signatureヘッダーの値は、RFC9421のセクション3.1「Creating a Signature」に記載されているとおりに作成されます。

使用する暗号スイートに応じて、以下のRFC9421の該当セクションを参照してください：

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

署名ヘッダーの作成例を確認するには、RFC9421の付録B「Example Keys」を参照してください。

重要： 機密性の高いクライアント情報のセキュリティを確保するため、eBayはいかなるシステムにおいても秘密鍵 (Private Key)の値を保存しません。開発者が秘密鍵を紛失した場合は、Key Management APIを使用して新しいキーペアを生成する必要があります。

5. Signature-Inputヘッダーの作成方法

このヘッダーは、どのヘッダーおよび疑似ヘッダーが含まれているか、また署名を計算する際にそれらがどのような順序で使用されるかを示します。

Signature-Inputヘッダーの作成に関する完全な情報については、RFC9421のセクション4「Including a Message Signature in a Message」を参照してください。

Signature-Inputヘッダーの値は以下のようになります： 

sig1=("content-digest" "x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308
注： パラメータ created に割り当てられる値は、署名が最初に作成されたときのUnixタイムスタンプです。

HTTPペイロードが含まれない場合、ヘッダーは以下のようになります： 

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

署名のテスト方法

Sandbox環境を使用して、署名メカニズムをテストできます。SandboxでKey Management APIを呼び出し、秘密鍵 (Private Key)、公開鍵 (Public Key)、およびJWE形式の公開鍵 (Public Key as JWE)を作成して、Sandboxでの署名テストを行います。

重要： Sandbox環境でデジタル署名をテストするには、Sandboxユーザーの居住地を必ずEU諸国またはUK（例: "DE" または "GB"）のいずれかに設定する必要があります。この場合にのみ、デジタル署名が必須となり、検証が行われます。

Sandboxユーザーの作成に関する追加情報については、「Create a test Sandbox user」ドキュメントを参照してください。

注： 必要に応じて、テストキーを使用して署名を検証できるオープンソースのサンプルコードが実装されています。このコードはDockerコンテナを使用してデプロイできます。詳細については、READMEファイルを参照してください。

エラーコード

本番環境 (Production) またはSandbox環境で対象APIへのコールを発行した際に、リクエストの形式が不適切であるか、必要なヘッダーが含まれていない場合、エラーが返されます。これらのエラーに関する情報は、以下の表を参照してください。

コード 意味
215000 content-digestヘッダーがありません
215001 x-ebay-signature-keyヘッダーがありません
215002 マスターキー取得時の内部エラー
215003 デジタル署名検証時の内部エラー
215101 コンテンツダイジェストがありません
215102 ペイロードがありません
215103 shaの値の解析に失敗しました
215104 shaのBase64デコードに失敗しました
215105 sha-256のコンテンツダイジェストが正しくありません
215106 sha-512のコンテンツダイジェストが正しくありません
215107 shaのコンテンツダイジェストが正しくありません
215108 コンテンツダイジェストの検証に失敗しました
215109 パラメータが不足しています（内部エラー）
215110 content-digestヘッダーがありません
215111 signatureヘッダーがありません
215112 signature-inputヘッダーがありません
215113 署名パラメータ内のタイムスタンプが無効です
215114 署名パラメータの作成時間が正しい範囲内にありません
215115 JWEの復号に失敗しました
215116 JWEの形式が正しくありません
215117 署名内のappidがトークン内のappと一致しません
215118 JWE内にpkeyがありません
215119 公開鍵のデコードに失敗しました
215120 署名の検証に失敗しました
215121 署名の検証に失敗しました
215122 署名の検証に失敗しました

デジタル署名SDK

デジタル署名ヘッダーの生成プロセスを簡素化するために、eBayは以下のSDKを開発しました。これらのSDKは、デジタル署名ヘッダーを検証するメソッドも提供します。

  • Digital Signature SDK (Java)
  • Digital Signature SDK (Node.js)
  • Digital Signature SDK (PHP)

各SDKに関する追加情報は、それぞれのREADMEファイルで確認できます。

よくある質問 (FAQ)

このセクションのFAQでは、サードパーティアプリケーション、APIセキュリティ、およびAPIのデジタル署名に関する一般的な質問にお答えします。

  • 私のアプリケーションからeBay APIを呼び出せません。助けてもらえますか？

    開発者アカウントからeBay Developer Supportにお問い合わせください。

  • 私はeBay APIを使用する独自のアプリケーションを開発したセラーです。APIコールが失敗し、返金/キャンセル/返品の承認などの実行がブロックされています。どうすればよいですか？

    APIが 403 レスポンスコードとともに失敗し、デジタル署名が必要である旨のメッセージが表示される場合は、このドキュメントの「デジタル署名」セクションを参照して、完全な情報を確認してください。

  • デジタル署名を追加しない限り、返金処理がブロックされます。これを回避することはできますか？

    いいえ、それは不可能です。返金のためのAPIコールには、デジタル署名を渡すことでセキュリティレイヤーを追加する必要があります。

  • APIコールでデジタル署名を渡していますが、まだ返金を実行できません。次のステップは何ですか？

    「デジタル署名」セクションに記載されているすべての手順を完了していることを確認してください。それでも返金APIが失敗し続ける場合は、開発者アカウントからeBay Developer Supportでチケットを開いてください。

  • なぜeBayはこの変更を行ったのですか？

    決済サービスの更新を継続する中で、eBayはEUおよびUKのユーザーに対する決済サービスの提供方法を変更しています。その結果、統合（インテグレーション）によってEU/UKのeBayセラーが返金の開始やeBayが処理した支払いに関する特定の情報の提供などの機能を実行できるようにする場合、規制要件を満たすために追加のセキュリティ対策が必要となります。

  • 質問への回答が見つかりません。API関連の質問はどこに問い合わせればよいですか？

    その他の質問がある場合は、eBay Developer Supportでチケットを開いてください。

トップに戻る