Digital Signature SDK

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

This NodeJS 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
• Logging
• 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 IETF standards.

• RFC 9421 HTTP Message Signatures
• RFC 9530 Digest Fields

Features

This SDK is intended to generate required message signature headers, as per the above IETF standards, and also provides a way to verfiy signature headers. There is also an example NodeJS service 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 RFC 9530 Digest Fields), 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 RFC 9421 HTTP Message Signatures
  • Signature: The value of the Signature header is created as described in Section 3.1, Creating a Signature, of RFC9421. 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
• signMessage method to sign the incoming request object
• validateSignature method to validate the signature of the incoming request object
• There are individual methods as well to generate and validate the headers:
  • generateDigestHeader
  • generateSignature
  • generateSignatureInput
  • generateSignatureKey
  • validateDigestHeader
  • validateSignatureHeader

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

Usage

Prerequisites

NodeJS: v16 or higher
NPM: v7 or higher

Install

Using npm:

npm install digital-signature-nodejs-sdk

Using yarn:

yarn add digital-signature-nodejs-sdk

Configure

In order to run the example application (signing-only) the example-config.json needs to be updated.

{
  "digestAlgorithm": "<Algorithm used for generating content digest>",
  "jwe": "<JWE generated using Key Management API>",
  "privateKey": "<Private key generated using Key Management API>",
  "signatureComponents": "<Signature components for generating the base string>",
  "signatureParams": "<List of signature params>"
}

For both signing and signature validation, use example-config-full.json.

{
  "digestAlgorithm": "<Algorithm used for generating content digest>",
  "jweHeaderParams": "<The JWE header params>",
  "jwtExpiration": "<The JWT expiration in years>",
  "jwtPayload": "<The JWT  payload params>",
  "masterKey": "<The symmetric key used for JWE encryption and decryption>",
  "privateKey": "<Private key generated using Key Management API>",
  "publicKey": "<Public key generated using Key Management API>",
  "signatureComponents": "<Signature components for generating the base string>",
  "signatureParams": "<List of signature params>"
}

Parameters

Name	Type	Description
digestAlgorithm	string	The algorithm for generating the Content-Digest header. Supported vales are sha256 and sha512
jwe	string	The JWE generated using the Key Management API
jweHeaderParams	JSON object	The JWE header params. This is required only if a JWE is not provided in the config.
jwtExpiration	number	The JWT expiration in years. This is required only if a JWE is not provided in the config.
jwtPayload	JSON object	The JWT payload params. This is required only if a JWE is not provided in the config.
masterKey	string	The symmetric key. This is only needed for testing purposes. Ideally the JWE should be generated using the Key Management API
privateKey	string	The privateKey generated using the Key Management API
publicKey	string	The publicKey generated using the Key Management API
signatureComponents	JSON object	The signature components that are a part of the signatureParams. These are used to generate the base string which is used to generate the signature header
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.js for an example of how to setup an express server and use the SDK.

Running the example

Using npm:

npm start

Using yarn:

yarn start

• Signing Configuration Sample (JWE is provided in the config): example-config.json.
• Full Configuration Sample (generates JWE): example-config-full.json.

Note for Production deployment

For production, please host with HTTPS enabled.

Logging

Uses standard console logging.

License

Copyright 2022 eBay Inc. Developer: Lokesh Rishi

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.