Skip to content

Latest commit

 

History

History
157 lines (116 loc) · 7.19 KB

README.md

File metadata and controls

157 lines (116 loc) · 7.19 KB
Raw

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

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.

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

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.