Skip to content

Releases: 317787106/java-tron

Signed HTTP Requests with TRON

12 Feb 15:28
@317787106 317787106
TIP-8128
c158599
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Signed HTTP Requests with TRON Pre-release
Pre-release 
tip: 8128
title: Signed HTTP Requests with TRON
author: 317787106@qq.com
status: Draft
type: Standards Track 
category: TRC
created: 2026-02-13

Abstract

A standard to authenticate HTTP requests with TRON accounts using HTTP Message Signatures.

Motivation

HTTP APIs are commonly authenticated using bearer credentials (cookies, API keys, JWTs) or IPC. These mechanisms authenticate the caller but do not provide request integrity, and typically require servers to issue and protect shared secrets. HTTP message signatures improve this by binding a cryptographic proof to the HTTP request itself: the client signs selected request components so the server can verify request integrity and authorization without issuing or storing bearer credentials.

Applications lack a secure mechanism to authenticate generic HTTP traffic (e.g. API clients, servers, and agents) without bespoke sign-up flows, session issuance, or long-lived bearer credentials. As agentic workflows and crypto-native applications increasingly interact through APIs, a standard way to authenticate and authorize requests becomes necessary.

TRON accounts provide a stateful, globally verifiable identity. Using them as the signing authority for HTTP message signatures allows requests to be authorized by proving control of an address. This approach enables richer authorization models (delegation, session modules, scoped policies, onchain composability) and supports payment-aware flows.

The proposal standardizes TRON-based authentication for HTTP requests, aligned with the HTTP Message Signatures model where practical.

Traditional authentication systems place security policy primarily on the server: the server issues credentials, defines scopes, and enforces risk centrally. The specification intentionally inverts that model. The signer chooses the cryptographic guarantees attached to each request by selecting which request components to bind and whether to enable replay protection. The verifier evaluates those guarantees against its acceptance rules, but does not impose a single security posture on all clients.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

HTTP fields, derived components, and signature parameters are to be interpreted as defined in RFC 9421.

Overview

This specification defines a TRON authentication scheme for HTTP requests using HTTP Message Signatures.

Unless explicitly stated otherwise, implementations MUST reuse RFC 9421 for covered components, canonicalization, signature base construction, and the Signature-Input / Signature header syntax.

The specification defines the TRON bindings: required signature parameters, the keyid format, and signing and verification semantics for normal account and Smart Contract Accounts (SCAs).

Security semantics are expressed directly through two orthogonal dimensions:

  • request binding (how tightly a signature is bound to a specific request)
  • replay protection (whether a signature can be reused).

No out-of-band negotiation or capability discovery is required. A signer selects which components and parameters to sign. A verifier evaluates whether the resulting signature satisfies the acceptance rules defined by the specification.

In this model, the signer explicitly chooses the security posture of each request by deciding what to cryptographically bind and whether to enable replay protection. The verifier does not issue credentials or negotiate risk levels, but simply evaluates the guarantees presented in the request.

1. Definitions

  • Normal Account: any normal TRON account (AccountType = 0) with private key, exclude smart contract.
  • SCA: a Smart Contract Account (AccountType = 2) which can validates signatures using PrecompiledContracts ecRecover.
  • Signer: the HTTP client generating a signature for a request.
  • Verifier: the HTTP server (or gateway such as trongrid) verifying a signature on a received request.
  • Request-Bound: a binding model in which a signature authorizes exactly one concrete HTTP request by covering all request components required to uniquely identify that request, such that any change to the method, target, query, or body causes verification to fail.
  • Class-Bound: a binding model in which a signature authorizes a class of requests defined by the covered components and any application-specific parameters, rather than a single concrete request.
  • Non-Replayable: a property of a signature that ensures it cannot be validly reused.
  • Replayable: a property of a signature that allows reuse within its validity window.

2. Headers

Signers MUST attach signatures to HTTP requests using the RFC 9421 header fields:

  • Signature-Input: carries the list of covered components and signature parameters.
  • Signature: carries the signature bytes for the corresponding label.

The specification RECOMMENDS using the label eth (e.g., Signature-Input: tron=... and Signature: tron=...), but any valid RFC 9421 label MAY be used.

Signature-Input: tron=("@method" "@authority" \
  @path @query "content-digest" "cache-control");\
  created=1700000000;expires=1700000060;nonce="b64url_r4Nd0mN0nCEK0YQY4d4r7A";\
  keyid="trc8128:1:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Signature: tron=:dmSonRcA8ydqKFPQ+/f/dN2I0XviLbXIO4VPl9/41l5byGyBYO1SXY9eWixdKvB6cOaw96kUKFg50LZ60255jhs=:

3. Signature

3.1 Security Model

The profile expresses all security semantics directly through two orthogonal dimensions: request binding and replay protection.

3.1.1 Request Binding

A signature is Request-Bound if it binds authorization to a specific HTTP request.

A Request-Bound signature MUST cover at minimum the following components:

  1. @authority
  2. @method
  3. @path

If the request contains a query component, the signature MUST also cover:

  1. @query

If the request contains an HTTP message body, the signature MUST also cover:

  1. content-digest

A signature that omits one or more components from the Request-Bound list is Class-Bound. A Class-Bound signature authorizes a class of requests defined by the covered components and any application-specific parameters.

Verifiers MUST accept signatures that satisfy the Request-Bound requirements in this section.

Verifiers MAY require additional application-specific components as a condition for acceptance.

3.1.2 Replay Protection

A signature is Non-Replayable if it cannot be validly reused.

  • Non-Replayable signatures MUST include the nonce parameter.
  • Verifiers MUST enforce uniqueness of (keyid, nonce) within an application-defined nonce retention window.
  • Verifiers MUST reject a Non-Replayable signature if expires - created exceeds the application-defined nonce retention window.
  • Once a nonce has been accepted, it MUST NOT be accepted again within that window.

A signature that omits nonce is Replayable and may be reused within its validity window, subject to verifier policy.

3.2 Conformance and Acceptance Rules

3.2.1 Baseline Requirement

To claim conformance with the proposal, implementations MUST accept signatures that are:

  • Request-Bound, and
  • Non-Replayable.

This guarantees that a signer who chooses the strongest security posture — Request-Bound and Non-Replayable — can always interoperate with any compliant verifier.

Any implementation that does not accept signatures satisfying both properties is NOT compliant with the proposal.

3.2.2 Optional Acceptance

In addition to the baseline requirement, verifiers MAY accept signatures that relax one or both security dimensions:

  • Replayable signatures,
  • Class-Bound signatures, or
  • signatures that are both Replayable and Class-Bound.

Verifiers that accept Replayable signatures MUST implement the early invalidation mechanisms defined in Section 5.2.

Except for signatures that satisfy the baseline requirement in Section 3.2.1, a verifier MAY reject any signature that does not satisfy its acceptance policy, even if the signature is otherwise valid under the specification.

3.3 Signature Parameters

3.3.1 keyid

keyid MUST identify an TRON account with explicit chain context:

keyid="trc8128:<chain-id>:<address>"

Where:

  • <chain-id> is a base-10 long, responses to last 4 bytes of genesis block hash. for example, nile is 3448148188 for 0xcd8690dc.
  • <address> is a 20-byte TRON address encoded as 0x + 40 hex characters without prefix 0x41.

Signers SHOULD serialize <address> using lowercase hex. Verifiers MUST treat address hex as case-insensitive.

<chain-id> determines the chain context for:

  • determining whether <address> is a normal account or SCA,
  • performing verification where applicable.

The trc8128 namespace reuses the CAIP-10 account identifier syntax, including chain scoping and replay-domain separation; it differs only in its namespace prefix to explicitly bind signatures to this specification.

3.3.2 created, expires
  • created is an integer Unix timestamp (seconds).
  • expires is an integer Unix timestamp (seconds) and MUST be greater than created.

Verifiers MUST reject...

Read more
Loading