dynata-sig-java

Java library for Dynata request-signing primitives. It provides the following:

• URL canonicalization for signing
• Signing-string generation (SHA-256 lowercase hex of METHOD + canonical_url + body)
• Signature generation via the 3-step HMAC-SHA256 chain

It does not include an HTTP client integration layer.

Getting Started

Credentials

Before sending signed requests you will need credentials for Dynata APIs. These consist of:

• Access key: used locally to compute the dynata-signature and also sent in the dynata-access-key request header.
• Secret key: never sent as a header; used locally to compute the dynata-signature.

Installation

This package is published to GitHub Packages. GitHub Packages requires authentication even for read access, so you need a GitHub personal access token (classic) with the read:packages scope.

1. Minimal pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>maven-app</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <repositories>
    <repository>
      <id>github-dynata</id>
      <url>https://maven.pkg.github.com/dynata/dynata-sig-java</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>com.dynata.arch</groupId>
      <artifactId>dynata-sig</artifactId>
      <version>1.3.0</version>
    </dependency>
  </dependencies>
</project>

2. Configure credentials

Add a matching server entry to your Maven settings.xml (usually ~/.m2/settings.xml) so Maven can authenticate against GitHub Packages. The id must match the repository id in the pom.xml (github-dynata):

<settings>
  <servers>
    <server>
      <id>github-dynata</id>
      <username>${env.GITHUB_ACTOR}</username>
      <password>${env.GITHUB_TOKEN}</password>
    </server>
  </servers>
</settings>

Then export your credentials and build:

export GITHUB_ACTOR=your-github-username
export GITHUB_TOKEN=ghp_your_PAT_with_read:packages
cd maven-app && mvn install

Algorithm

Generating Signing Strings

Each Dynata signature starts from a signing string, which is built from:

{METHOD}{URI}{BODY}

with no delimiter between segments, then hashed as SHA-256 and encoded as lowercase hex.

Method

Use the exact HTTP method sent on the wire (GET, POST, DELETE, etc.).

URI

Use the URI (scheme + host + path + query) in canonical form.

• Scheme: advertised scheme of the receiving application.
• Host: domain name only (do not include port).
• Path: target resource path, including the leading /.
• Query: use a canonical query string.

Canonical query construction:

1. Sort parameter names by character code point ascending.
2. URI-encode each name and value using RFC 3986 rules.
3. Do not encode unreserved characters: A-Z, a-z, 0-9, -, _, ., ~.
4. Percent-encode all other characters as uppercase hex (%XY).
5. Encode spaces as %20 (never +).
6. Build pairs as name=value, then join with &.
7. Use an empty string when a parameter has no value.

Body

Use the exact body text/bytes sent with the request. Whitespace, ordering, and encoding must be preserved exactly.

Signature Computation

After generating the signing string, compute the signature using a three-step HMAC-SHA256 chain:

1. HMAC with expiration timestamp as key and signing string as message.
2. HMAC with access key as key and step 1 output as message.
3. HMAC with secret key as key and step 2 output as message.

Implementation notes:

• The final signing string digest is always a 64-character lowercase SHA-256 hex value.
• If there is no body, use an empty body segment.
• Use UTF-8 for all key and message conversions.
• Use lowercase hex output for each HMAC digest.
• Reuse the exact RFC3339 expiration value from the dynata-expiration header.

Contribution Notes