Digital Signature SDK

HTTP message signatures provide a mechanism for end-to-end authenticity and integrity for components of an HTTP message.

This PHP SDK is designed to simplify the process of generating digital signature headers and also provides a method to validate the digital signature headers.

Table of contents

• Digital Signatures for Public API Calls
• Features
• Usage
• License

Digital Signatures for Public API Calls

Due to regulatory requirements emanating from SCA for our European/UK sellers, we are requiring our developers to add a digital signature for every HTTP call that is made on behalf of a EU/UK seller to certain APIs.

This SDK is generic and the signature scheme is compliant with these upcoming IETF standards (currently not yet RFCs).

• draft-ietf-httpbis-message-signatures-15
• draft-ietf-httpbis-digest-headers-10

Features

This SDK is intended to generate required message signature headers, as per the above IETF standards. There is also an example included with the SDK.

This SDK incorporates

• Generation of the following HTTP message signature headers:
  • Content-Digest: This header includes a SHA-256 digest over the HTTP payload (as specified in draft-ietf-httpbis-digest-headers-10), if any. It is not required to be sent for APIs that do not include a request payload (e.g. GET requests).
  • Signature-Input: This header indicates which headers and pseudo-headers are included, as well as the order in which they are used when calculating the signature. It is created as specified in draft-ietf-httpbis-message-signatures-15
  • Signature: 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. It uses the Private Key value generated by the Key Management API.
  • x-ebay-signature-key: This header includes the JWE that is created using the Key Management API
• generateSignatureHeaders method to generate all required headers

For more details on Digital Signatures for eBay APIs please refer to the documentation.

Usage

Prerequisites

PHP: 7.4 or higher

Install

In order to use this SDK, add it to your PHP application via composer:

composer require ebay/digital-signature-php-sdk
composer update

In your code, add this line to return all headers including signature headers:

$headers = $signature->generateSignatureHeaders($yourHeaders, $apiUrl, $method, $body);

Please also check the example

Configure

In order to run the example application the example-config.json needs to be updated.

{
  "digestAlgorithm": "<Algorithm used for generating content digest>",
  "algorithm": "<Algorithm used for signature>",
  "jwe": "<JWE generated using Key Management API>",
  "privateKey": "<Path to private key generated using Key Management API>",
  "privateKeyStr": "<(alternative to privateKey) Private key generated using Key Management API, including -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- key headers>",
  "signatureParams": "<List of signature params>"
}

Parameters

Name	Type	Description
digestAlgorithm	string	The algorithm for generating the Content-Digest header. Supported vales are sha-256 and sha-512
algorithm	string	The algorithm for signature. Supported vales are Ed25519 and RSA
jwe	string	The JWE generated using the Key Management API
privateKey	string	The privateKey generated using the Key Management API
privateKeyStr	string	(alternative to privateKey) Private key generated using Key Management API, surrounded by -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- key headers
signatureParams	Array	The list of headers that indicates which headers and pseudo-headers are included, as well as the order in which they are used when calculating the signature

Note: You can refer to example.php for an example of how to use the SDK.

Running the example

cd examples
composer update
php example.php

• Signing Configuration Sample: example-config.json.

License

Copyright 2022 eBay Inc. Developer: Ulrich Herberg and Arturas Sendrauskas

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.