jcsutil

Documentation

Overview

Package jcsutil provides JSON Canonicalization Scheme (JCS) per RFC 8785.

JCS defines a deterministic serialization of JSON values, ensuring that semantically identical JSON documents produce byte-for-byte identical output. This is essential for cryptographic operations like signing and hashing.

Key transformations performed:

• Object keys are sorted by UTF-16 code unit lexicographic order
• Numbers are formatted per ECMAScript rules (no trailing zeros, etc.)
• Whitespace is removed
• String escaping follows minimal JSON escaping rules

Index

• Constants
• func Canonicalize(data []byte) ([]byte, error)
• func CanonicalizeAndHash(data []byte) (canonical []byte, digest string, err error)
• func CanonicalizeAndHashWithOptions(data []byte, opts Options) (canonical []byte, digest string, err error)
• func CanonicalizeWithOptions(data []byte, opts Options) ([]byte, error)
• type NumberPolicy
• type Options
  • func DefaultOptions() Options

Constants

const MaxSafeInt int64 = (1 << 53) - 1

MaxSafeInt is the maximum integer value that can be exactly represented in IEEE 754 double-precision floating point (2^53 - 1).

Functions

func Canonicalize

func Canonicalize(data []byte) ([]byte, error)

Canonicalize transforms JSON into its canonical form per RFC 8785. It uses default options (duplicate keys allowed, finite IEEE numbers).

func CanonicalizeAndHash

func CanonicalizeAndHash(data []byte) (canonical []byte, digest string, err error)

CanonicalizeAndHash canonicalizes JSON and computes its SHA-256 hash. Returns the canonical form, the digest as "sha256:{hex}", and any error.

func CanonicalizeAndHashWithOptions

func CanonicalizeAndHashWithOptions(data []byte, opts Options) (canonical []byte, digest string, err error)

CanonicalizeAndHashWithOptions canonicalizes JSON with the specified options and computes its SHA-256 hash. Returns the canonical form, the digest as "sha256:{hex}", and any error.

func CanonicalizeWithOptions

func CanonicalizeWithOptions(data []byte, opts Options) ([]byte, error)

CanonicalizeWithOptions transforms JSON into its canonical form per RFC 8785 using the specified options.

Types

type NumberPolicy

type NumberPolicy int

NumberPolicy controls how numbers are validated and formatted during canonicalization.

const (
	// NumberPolicyFiniteIEEE accepts any finite IEEE 754 number (rejects NaN and Infinity).
	// This is the standard JCS behavior per RFC 8785.
	NumberPolicyFiniteIEEE NumberPolicy = iota

	// NumberPolicySafeIntNonNegative restricts numbers to non-negative integers
	// within JavaScript's safe integer range [0, 2^53-1]. Rejects negative numbers,
	// fractions, and values exceeding MaxSafeInt.
	NumberPolicySafeIntNonNegative
)

type Options

type Options struct {
	// RejectDuplicateKeys causes canonicalization to fail if the input JSON
	// contains duplicate object keys. By default (false), the last value wins
	// per standard JSON parsing behavior.
	RejectDuplicateKeys bool

	// NumberPolicy controls number validation and formatting.
	NumberPolicy NumberPolicy
}

Options configures JCS canonicalization behavior.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default canonicalization options: duplicate keys allowed, finite IEEE numbers accepted.