Digital Signature SDK

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

This Java 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 upcoming 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 Spring Boot 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
• getSignedRequest 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

Maven: version 3.5.0 
Java: 8 or higher

Install

Adding dependency:

<dependency>
    <groupId>com.ebay.developer</groupId>
    <artifactId>digital-signature-sdk</artifactId>
  <version>1.1.0-RELEASE</version>
</dependency>

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>",
  "algorithm": "<Algorithm used for signature>",
  "jwe": "<JWE generated using Key Management API>",
  "privateKey": "<Private key generated using Key Management API>",
  "signatureComponents": "<Request method details>",
  "signatureParams": "<List of signature params>"
}

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

{
  "digestAlgorithm": "<Algorithm used for generating content digest>",
  "algorithm": "<Algorithm used for signature>",
  "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 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
jweHeaderParams	JSON object	The JWE header params. This is required only if a JWE is not provided in the config.
jwtExpiration	string	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	Request JSON Object.
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 SignatureController.java for an example of how to setup an express server and use the SDK.

Running the example

Using mvn:

cd examples
mvn spring-boot:run

• 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: Dhinesh Kumar Sivakumaran

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.