This specification describes the BabyJubjub 2021 Signature Suite, created in 2021 for the Verifiable Credentials Data Integrity Proof specification. The Signature Suite is designed to be zk-friendly, allowing the implementation of an additional security layer that can offer enhence privacy through zero-knowledge signature proofs.

This document is a draft specification developed by Polygon and is provided for public review and feedback. The current version of the document is a work in progress and may be subject to changes or updates based on community input, technical advancements, or further research. The specification has not yet been submitted to, reviewed, or approved by any formal standards organization such as the W3C. However, it is intended to align closely with the existing W3C recommendations, specifications, and best practices related to decentralized identifiers, verifiable credentials, and digital signatures.

Introduction

This specification presents the BabyJubjub 2021 Signature Suite, created in 2021 for the Verifiable Credentials Data Integrity Proof specification. The suite employs EdDSA on the BabyJubJub curve as the signature algorithm, providing an efficient structure for signing and verifying credentials while being zk-friendly. Although the signature suite itself does not actively involve zero-knowledge proofs, its design is conducive to privacy-preserving computations and can be easily integrated with zkSNARKs and other zero-knowledge proof systems. This document details the components, structure, and implementation guidance for the BabyJubjub 2021 Signature Suite, catering to developers, implementers, and users.

Terminology

The following terms are used to describe concepts involved in the generation and verification of the Linked Data Proof signature suite.

signature suite
A specified set of cryptographic primitives typically consisting of a canonicalization algorithm, a message digest algorithm, and a signature algorithm that are bundled together by cryptographers for developers for the purposes of safety and convenience.
canonicalization algorithm
An algorithm that takes an input document that has more than one possible representation and always transforms it into a canonical form. This process is sometimes also called normalization.
message digest algorithm
An algorithm that takes a message, preferably in some canonical form and produces a cryptographic output called a digest that is often many orders of magnitude smaller than the input message. These algorithms are often 1) very fast, 2) non-reversible, 3) cause the output to change significantly when even one bit of the input message changes, and 4) make it infeasible to find two different inputs for the same output.
canonical form
The output of applying a canonicalization algorithm to an input document.
signature algorithm
An algorithm that takes an input message and produces an output value where the receiver of the message can mathematically verify that the message has not been modified in transit and came from someone possessing a particular secret.
linked data document
A document comprised of linked data.
linked data proof
A proof which is a set of attributes that represent a linked data digital proof and the parameters required to verify it as defined by RDF-N-Quads.
linked data proof document
A linked data document featuring one or more linked data proofs.
BJJSignature2021
The type of the linked data proof for the signature suite BabyJubjub 2021.
Iden3StateInfo2023
The type representing state information, a method for maintaining the issuer's state information and validating proofs against this data to ensure secure and efficient identity management within decentralized systems.

Suite Definition

The BabyJubjub 2021 signature suite MUST be used in conjunction with the signing and verification algorithms in the Linked Data Signatures [[LD-SIGNATURES]] specification. The suite consists of the following algorithms:

Parameter Value Specification
canonicalizationAlgorithm https://w3id.org/security#URDNA2015 [[RDF-DATASET-NORMALIZATION]]
digestAlgorithm Poseidon [[GKR+19]]
signatureAlgorithm EdDSA-BabyJubJub [[BB19]]

Modification to Algorithms

The hash function in the signature algorithm has been repleaced to Poseidon[[GKR+19]] hash function.

Document Merklization Algorithm

TODO: Verify correctness

The signature suite incorporates a Document Merkleization algorithm to provide enhanced zero-knowledge compatibility support. This feature enables efficient querying of individual entries within JSON-LD documents in the context of zk-SNARK proofs. By constructing a Sparse Merkle Tree from the document, the algorithm supports selective disclosure of Verifiable Credential (VC) entries, efficiently prove membership, non-membership, and other predicate satisfactions related to the JSON-LD document, while maintaining the privacy and integrity of the data.

Prior to applying the Merkleization algorithm, the document must be in its expanded and canonicalized form.

The Merklization algorithm works as follow:

  1. Obtain a list of RDF Quads from the canonicalized document.
  2. For each Quad, construct a key-value pair where the key represents the complete type path, and the value corresponds to the entry's value.
  3. Insert each key-value pair into the Merkle Tree, with the key serving as the path in the tree and the leaf's value being the hash of the pair's value, computed using the designated message digest algorithm.
  4. For each key-value pair, first hash the key using the designated message digest algorithm, and use the hashed key as the path in the Merkle Tree. Then, hash the value using the same message digest algorithm, and set the resulting hash as the value of the corresponding leaf node in the tree.

For a detailed illustration of the Merkleization algorithm applied to a JSON-LD document, please refer to the example provided in the Examples section of this document.

Selective Disclosure

To better comprehend how the signature suite enables selective disclosure, let us examine the underlying mechanism. In this process, a credential undergoes Merkleization, during which each entry of the document is stored in a leaf. Subsequently, the root is signed by the issuer. To facilitate selective disclosure, the prover can share the following information with the verifier:

  1. The root of the Merkleized credential.
  2. The issuer's signature on the root.
  3. The relevant authentication paths for the selectively disclosed entries.
By providing this information, the prover demonstrates the possession of a valid credential containing specific entries without revealing the entire credential content. Consequently, this enables the prover to confirm the issuance of a credential of a particular type that contains specific values while preserving the confidentiality of other credential details. This approach aligns with W3C's official specifications and ensures data privacy during the verification process.

BJJSignature2021

All verifiable credentials issued with the BabyJubjub 2021 signature suite must include a proof object with "BJJSignature2021" as the proof type. The BJJSignature2021 proof contains the issuer's data, the core claim, and a signature created using the issuer's private key. The following example demonstrates a BJJSignature2021 proof:


        {
            "type": "BJJSignature2021",
            "issuerData": {
                "id": "did:iden3:polygon:wz7EXpsG9jdQC4edi3kyXC5SroZfqbcPKTYaJc5t6",
								...
            },
            "coreClaim": "c9b2370371b7fa8b3dab2a5ba81b68382a00000000000000000000000000000001129e344820de5301d7ae7f88ba5143f4ab9a9506e82331ec7ae8b21a830d006059621a4a3ed91795fc7919557e41c793ddbe93a30bc970f005cc72f89760270000000000000000000000000000000000000000000000000000000000000000c913b95700000000281cdcdf0200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
            "signature": "588a56edc9862e0c7e2dbddade2ab30a156a36ac491205e82c6c1c9dfb5cd82c3bb51070c25a7f34cebf732013f11ef2c48a7c2e7cf706ec305d25b1bccffa05"
        }

The proof contains the signature of the coreClaim which is a serialization of the whole VC document except for the proof. The signature is created using the issuer's private key.

Proof Generation

The BJJSignature2021 proof generation process follows a specific algorithm to ensure the integrity and authenticity of JSON-LD documents. The steps of the algorithm are as follows:

  1. Expand the JSON-LD document using the JSON-LD 1.1 Processing Algorithms.
  2. Canonicalize the document using the URDNA2015 algorithm [[RDF-DATASET-NORMALIZATION]].
  3. Apply the Document Merklization Algorithm to create a Merkle tree from the canonicalized document.
  4. Sign the root of the document's Merkle tree using the associated private key.

Iden3StateInfo2023

The Iden3StateInfo2023 object is defined in the issuer's DID document and holds essential information about the issuer's state, such as state roots and related data. This object plays a crucial role in the verification process of verifiable credentials.


        {
            "id": "did:polygonid:polygon:2qL4AhwQThPWJ8QH9mxH41CDgKj9chrHN92azh5wkx?state=f3ed43e7fa950d746331b143bf16eae2dd97a1876704cbb8c620913421ea2f12",
            "type": "Iden3StateInfo2023",
            "blockchainAccountId": "80001:0x134B1BE34911E39A8397ec6289782989729807a4",
            "published": true,
            "info": {
                "id": "did:polygonid:polygon:2qL4AhwQThPWJ8QH9mxH41CDgKj9chrHN92azh5wkx",
                "state": "f3ed43e7fa950d746331b143bf16eae2dd97a1876704cbb8c620913421ea2f12",
                "replacedByState": "0000000000000000000000000000000000000000000000000000000000000000",
                "createdAtTimestamp": "1677691329",
                "replacedAtTimestamp": "0",
                "createdAtBlock": "32582097",
                "replacedAtBlock": "0"
            },
            "global": {
                "root": "d5a1afd7dd885ca97493c29640c8d43bc1af1ce165186974a42ddddfdea4182d",
                "replacedByRoot": "0000000000000000000000000000000000000000000000000000000000000000",
                "createdAtTimestamp": "1677691329",
                "replacedAtTimestamp": "0",
                "createdAtBlock": "32582097",
                "replacedAtBlock": "0"
            }
        }

The issuer stores their public key in the state tree. During the verification of the verifiable credential, the verifier must check that the public key used to sign the document has an authentication path from the root specified in the Iden3StateInfo2023 object in the DID document.

To see an example of Iden3StateInfo2023 object in a DID document, please refer to the example provided in the Examples section of this document.

Proof Verification

TODO: Verify correctness

To verify the authenticity and integrity of a selectively disclosed credential, the following steps should be performed:

  1. Retrieve the issuer's DID document and locate the Iden3StateInfo2023 object containing the state root and other relevant information.
  2. Verify that the issuer's public key, which signed the document, has a valid authentication path from the state root specified in the Iden3StateInfo2023 object within the DID document.
  3. Obtain the root of the Merkleized credential, the issuer's signature on the root, and the relevant authentication paths for the selectively disclosed entries from the prover.
  4. Validate the issuer's signature on the VC root using the issuer's public key.
  5. Reconstruct the Merkle tree based on the selectively disclosed entries and their corresponding authentication paths.
  6. Ensure that the reconstructed Merkle tree's root matches the root provided by the prover, thereby confirming the integrity and authenticity of the selectively disclosed credential.

Security Considerations

When implementing the BabyJubjub 2021 Signature Suite, several security considerations must be taken into account to ensure the integrity, confidentiality, and availability of the system.

Key Management

Proper key management practices must be followed to ensure the security of private keys. This includes secure key generation, storage, and destruction. It is essential to protect private keys from unauthorized access, as the loss or compromise of a private key could lead to impersonation or unauthorized access to signed documents.

Cryptographic Algorithms

The security of the BabyJubjub 2021 Signature Suite is dependent on the underlying cryptographic algorithms (Poseidon hash function and BabyJubJub signature algorithm). It is crucial to ensure that the chosen algorithms have been thoroughly analyzed and deemed secure by the cryptographic community.

Document Merklization

The Merklization process should be carefully implemented and reviewed to ensure that it preserves the integrity of the document while allowing for efficient zero-knowledge proofs. Any vulnerabilities in the Merklization algorithm could compromise the integrity of the signed document or the privacy of the zkSNARK proofs.

Side Channel Attacks

Implementations of the BabyJubjub 2021 Signature Suite should be designed to be resistant to side-channel attacks. These attacks could involve timing, power consumption, or electromagnetic radiation analysis to extract secret information from the system. Proper countermeasures should be employed to prevent such attacks.

Examples

DID Document


          {
            "@context": [
                "https://www.w3.org/ns/did/v1",
                "https://schema.iden3.io/core/jsonld/auth.jsonld"
            ],
            "id": "did:polygonid:polygon:2qL4AhwQThPWJ8QH9mxH41CDgKj9chrHN92azh5wkx",
            "authentication": [
                {
                    "id": "did:polygonid:polygon:2qL4AhwQThPWJ8QH9mxH41CDgKj9chrHN92azh5wkx?state=f3ed43e7fa950d746331b143bf16eae2dd97a1876704cbb8c620913421ea2f12",
                    "type": "Iden3StateInfo2023",
                    "blockchainAccountId": "80001:0x134B1BE34911E39A8397ec6289782989729807a4",
                    "published": true,
                    "info": {
                        "id": "did:polygonid:polygon:2qL4AhwQThPWJ8QH9mxH41CDgKj9chrHN92azh5wkx",
                        "state": "f3ed43e7fa950d746331b143bf16eae2dd97a1876704cbb8c620913421ea2f12",
                        "replacedByState": "0000000000000000000000000000000000000000000000000000000000000000",
                        "createdAtTimestamp": "1677691329",
                        "replacedAtTimestamp": "0",
                        "createdAtBlock": "32582097",
                        "replacedAtBlock": "0"
                    },
                    "global": {
                        "root": "d5a1afd7dd885ca97493c29640c8d43bc1af1ce165186974a42ddddfdea4182d",
                        "replacedByRoot": "0000000000000000000000000000000000000000000000000000000000000000",
                        "createdAtTimestamp": "1677691329",
                        "replacedAtTimestamp": "0",
                        "createdAtBlock": "32582097",
                        "replacedAtBlock": "0"
                    }
                }
            ]
        }

Document Merkleization

Consider the following JSON-LD document as an example:


        {
          "@context": "http://schema.org/",
          "@type": "Person",
          "name": "Jane Doe",
          "jobTitle": "Professor",
          "telephone": "(425) 123-4567"
        }

After expanding and canonicalizing the JSON-LD document, we obtain the list of RDF Quads. The key-value pairs derived from these RDF Quads can be represented in the following table:

Path Value
http://schema.org/jobTitle Professor
http://schema.org/name Jane Doe
http://schema.org/telephone (425) 123-4567
http://www.w3.org/1999/02/22-rdf-syntax-ns#type http://schema.org/Person

Following the extraction of key-value pairs from the RDF Quads, we construct a Merkle tree using these pairs. For each key-value pair, the key is hashed using the designated message digest algorithm to obtain the path in the Merkle tree. The value is also hashed using the same algorithm, and the resulting hash serves as the value of the corresponding leaf node in the tree.

The following image represents the resulting Merkle tree constructed using the hashed paths and values derived from the key-value pairs in the table above:

Description of the image