JSON Canonicalization Scheme (JCS)

This project provides a .NET implementation of ES6-compatible JSON number serialization. It is a port of the logic used in Mozilla's JavaScript engine (Rhino) to ensure that numbers are serialized in a way that is consistent with ECMAScript standards.

To ensure correctness, the implementation has been verified against a dataset of 100 million random and selected values.

The JSON Canonicalization Scheme (JCS), defined in RFC 8785, provides a method for serializing JSON data into a unique, deterministic string representation. This is essential for cryptographic operations like hashing and signing, where the target data must remain identical during serialization, transport, or parsing.

JCS achieves determinism through three main mechanisms:

1. Primitive Serialization: Uses methods compatible with ECMAScript's JSON.stringify().
2. Property Sorting: Performs a recursive, lexicographic sorting of JSON Object properties.
3. Array Handling: JSON Array data is canonicalized, but the original element order is preserved.

To ensure platform interoperability, the resulting canonical JSON string should be converted to UTF-8.

To canonicalize Python data structures according to RFC 8785 (JCS), import the canonicalize function from org.webpki.json.Canonicalize.

Important details:

• Input: The function accepts standard Python data structures (e.g., dictionaries, lists).
• Output: The function returns a UTF-8 formatted bytes object representing the canonicalized JSON.

from org.webpki.json.Canonicalize import canonicalize

data = canonicalize({"tag":4})

To canonicalize a JSON string or byte array, instantiate JsonCanonicalizer with your input. You can then retrieve the canonicalized result as either a String or a UTF-8 encoded byte[] array.

Supported Input Types:

• String containing JSON data.
• byte[] array holding JSON data in UTF-8 format.

Supported Output Formats:

• getEncodedString(): Returns the canonicalized JSON as a String.
• getEncodedUTF8(): Returns the canonicalized JSON as a byte[] array.

import org.webpki.jcs.JsonCanonicalizer;

// Canonicalize from a String
JsonCanonicalizer jsonCanonicalizer = new JsonCanonicalizer(jsonString);
String result = jsonCanonicalizer.getEncodedString();

// Alternatively, get the result as a byte array
byte[] utf8Result = jsonCanonicalizer.getEncodedUTF8();

To build and run the tests for the Go implementation, follow these steps:

1. Set your GOPATH to the current directory.
2. (Optional) For running verify-numbers.go, download the 3Gb+ test data file described in the root ../testdata directory and update the file path within verify-numbers.go to point to your local copy.
3. Execute the following commands from the test directory:

$ cd test
$ go build webpki.org/jsoncanonicalizer
$ go run verify-canonicalization.go
$ go run verify-numbers.go

To create JSON objects that can be signed, your classes must implement the ISigned interface. This involves defining a constant for the signature property name and a method to return it. You should also include a property to hold the signature string, using JsonProperty with NullValueHandling.Ignore to ensure the signature field is omitted when it is null (e.g., before the object is signed).

public class MyObject : ISigned
{
    const String SIGNATURE_PROPERTY = "signature";
    
    // Other properties

    [JsonProperty(SIGNATURE_PROPERTY, NullValueHandling = NullValueHandling.Ignore)]
    public string Signature { get; set; }
    
    public string GetSignatureProperty()
    {
        return SIGNATURE_PROPERTY;
    }
}

To build and run the tests for the Python implementation located in src/org/webpki/json:

1. Set Environment: Set your PYTHONPATH to the src directory.
2. Large Data Testing: To run verify-numbers.py, you must download the 3Gb+ test data file located in the ../testdata directory. You will need to update the file path within verify-numbers.py to point to your downloaded file.
3. Run Tests: Navigate to the test directory and execute the verification scripts.

# Set PYTHONPATH to the src directory first
$ cd test
$ python verify-canonicalization.py
$ python verify-numbers.py