BBS Cryptosuite v2023

Abstract

This specification describes the BBS+ Signature Suite created in 2023 for the Data Integrity specification. The Signature Suite utilizes BBS+ signatures to provide the capability of zero knowledge proof disclosures.

This specification defines a set of cryptographic suites for the purpose of creating, verifying and deriving proofs for BBS+ Signatures in conformance with the Data Integrity [VC-DATA-INTEGRITY] specification.

In general the suites uses the RDF Dataset Normalization Algorithm [RDF-DATASET-NORMALIZATION] to transform an input document into its canonical form. It then uses the statement digest algorithm to digest each statement to be signed individually, finally the digested statements are signed using the defined signature algorithm.

BBS+ signatures [CFRG-BBS-SIGNATURE] are compatible with any pairing friendly elliptic curve, however the cryptographic suites defined in this document elect to only allow the usage of the BLS12-381 for interoperability purposes.

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

This section defines the terms used in this specification. A link to these terms is included whenever they appear in this specification.

data integrity proof

A set of attributes that represent a digital proof and the parameters required to verify it.

private key

Cryptographic material that can be used to generate digital proofs.

challenge

A random or pseudo-random value used by some authentication protocols to mitigate replay attacks.

domain

A string value that specifies the operational domain of a digital proof. This could be an Internet domain name like example.com, an ad-hoc value such as mycorp-level3-access, or a very specific transaction value like 8zF6T8J34qP3mqP. A signer could include a domain in its digital proof to restrict its use to particular target, identified by the specified domain.

cryptographic suite

A specification defining the usage of specific cryptographic primitives in order to achieve a particular security goal. These documents are often used to specify verification methods, digital signature types, their identifiers, and other related properties.

decentralized identifier (DID)

A globally unique persistent identifier that does not require a centralized registration authority and is often generated and/or registered cryptographically. The generic format of a is defined in [DID-CORE]. Many—but not all—methods make use of distributed ledger technology (DLT) or some other form of decentralized network.

controller

An entity that has the capability to make changes to a controller document.

controller document

A set of data that specifies one or more relationships between a controller and a set of data, such as a set of public cryptographic keys.

subject

The entity identified by the id property in a controller document. Anything can be a subject: person, group, organization, physical thing, digital thing, logical thing, etc.

distributed ledger (DLT)

A non-centralized system for recording events. These systems establish sufficient confidence for participants to rely upon the data recorded by others to make operational decisions. They typically use distributed databases where different nodes use a consensus protocol to confirm the ordering of cryptographically signed transactions. The linking of digitally signed transactions over time often makes the history of the ledger effectively immutable.

verification method

A set of parameters that can be used together with a process to independently verify a proof. For example, a cryptographic public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated cryptographic private key.

"Verification" and "proof" in this definition are intended to apply broadly. For example, a cryptographic public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof."

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.
canonical form: The output of applying a canonicalization algorithm to an input document.
statement: n-quads statements are a sequence of RDF terms representing the subject, predicate, object and graph label. See the grammar definition here.
statement digest algorithm: An algorithm that takes a statement and produces a cryptographic output message 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.
statement digest: The result of the application of the statement digest algorithm to a statement
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.
selective disclosure: An information disclosure technique which is the process of deciding and disclosing a sub-set of information from an original information set.
data integrity proof document: A linked data document featuring one or more data integrity proofs.
revealed statements: The set of statements produced by applying the canonicalization algorithm to the reveal document.
derive proof algorithm: An algorithm that takes in a data integrity proof document featuring a data integrity proof that supports a derive proof algorithm along side a reveal document and derives a proof only revealing the statements defined in the reveal document.
derived proof: The product of apply the derive proof algorithm to an data integrity proof document and reveal document.
quad: A quad as specified by [RDF-DATASET-NORMALIZATION]
n-quad: An n-quad which is a line based, plain text format encoding of a quad as defined by [RDF-N-Quads].
linked data document: A document comprised of linked data.
curve name: The name defining a particular cryptographic curve.
frame: A frame as specified by [JSON-LD-FRAMING] is a JSON-LD document, which describes the form for transforming another JSON-LD document using matching and embedding rules. A frame document allows additional keywords and certain map entries to describe the matching and transforming process.
JSON-LD document: A JSON-LD document as specified by [JSON-LD-FRAMING] is a is a serialization of an RDF dataset
framing algorithm: A Framing Algorithm as specified by [JSON-LD-FRAMING] is an algorithm that accomplishes the process of framing an input document to a given frame.
blank node: A blank node as specified by [RDF-CONCEPTS]. In short, it is a node in a graph that is neither an IRI, nor a literal.
reveal document: A JSON-LD document in the form of a frame which describes the desired transform to apply to the input proof document using the framing algorithm defined in [JSON-LD-FRAMING].
revealed document: A data integrity proof document which is the product of the derive proof algorithm.
input proof document: A data integrity proof document featuring a data integrity proof that supports proof derivation.

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Issue

TODO: Add paragraph

The following sections outline the data model that is used by this specification for verification methods and data integrity proof formats.

The cryptographic material used to verify a data integrity proof is called the verification method. This suite relies on public key material represented using [MULTIBASE], [MULTICODEC], JSON Web Key [RFC7517], and [BLS-JOSE-COSE].

This suite MAY be used to verify Data Integrity Proofs [VC-DATA-INTEGRITY] produced by BLS12-381 public key material encoded as a JsonWebKey. Loss-less key transformation processes that result in equivalent cryptographic material MAY be utilized.

Issue

This definition should go in the Data Integrity specification and referenced from there.

The type of the verification method MUST be JsonWebKey.

The controller of the verification method MUST be a URL.

The publicKeyJwk property of the verification method MUST be a public key encoded according to [RFC7517].

Issue

The specific encoding of public keys is still being refined in [BLS-JOSE-COSE].

Developers are advised to not accidentally publish a representation of a private key. Implementations of this specification MUST raise errors if expression of public key information includes a key parameter that is marked as Private in the IANA JSON Web Key Parameters registry.

Example 1: A BLS12-381 public key containing the G1 and G2 values, encoded as a JsonWebKey in a controller document

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/data-integrity/v1"
  ],
  "id": "https://example.com/issuer/123",
  "verificationMethod": [{
    "id": "https://example.com/issuer/123#key-0",
    "type": "JsonWebKey",
    "controller": "https://example.com/issuer/123",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Bls12381G1",
      "x": "Ed4GBGLVasEp4ejPz44CvllbTldfLLcm2QcIJluBL6p_SQmRrZvJNa3YaJ-Wx8Im",
      "y": "AbdYAsAb20CHzlVW6VBO9i16BcGOmcYiMLlBEh9DfAiDu_1ZIAd1zewSi9f6517g"
    }
  }, {
    "id": "https://example.com/issuer/123#key-1",
    "type": "JsonWebKey",
    "controller": "https://example.com/issuer/123",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Bls12381G2",
      "x": "Ajs8lstTgoTgXMF6QXdyh3m8k2ixxURGYLMaYylVK_x0F8HhE8zk0YWiGV3CHwpQ
    Ea2sH4PBZLaYCn8se-1clmCORDsKxbbw3Js_Alu4OmkV9gmbJsy1YF2rt7Vxzs6S",
      "y": "BVkkrVEib-P_FMPHNtqxJymP3pV-H8fCdvPkoWInpFfM9tViyqD8JAmwDf64zU2h
    BV_vvCQ632ScAooEExXuz1IeQH9D2o-uY_dAjZ37YHuRMEyzh8Tq-90JHQvicOqx"
    }
  }]
}

Issue

This definition should go in the Data Integrity specification and referenced from there.

The type of the verification method MUST be Multikey.

The controller of the verification method MUST be a URL.

The publicKeyMultibase property of the verification method MUST be a public key encoded according to [MULTICODEC] and formatted according to [MULTIBASE]. The multicodec encoding of a BLS12-381 public key that combines both the G1 and G2 fields is the byte prefix 0xee followed by the 48-byte G1 public key data, which is then followed by the 96-byte G2 public key data. The 145 byte value is then encoded using base64url with no padding (u) as the prefix. Any other encodings MUST NOT be used.

Developers are advised to not accidentally publish a representation of a private key. Implementations of this specification will raise errors in the event of a [MULTICODEC] value other than 0xee being used in a publicKeyMultibase value.

Example 2: An BLS12-381 public key containing the G1 and G2 values, encoded as a Multikey

{
  "id": "https://example.com/issuer/123#key-0",
  "type": "Multikey",
  "controller": "https://example.com/issuer/123",
  "publicKeyMultibase": "u7ljnAxKdp7YVqJvcMU9GtnmrMc1XZztXHsTsZ2LsmGJ67SsdbmNc
    S2SDs0daEPfhVXgODk0IVrgguJ-TJACHyXYa9Ae8DaxcvRy89KLgmWsyOOJn2oY7vCE2gt
    JoebMJiQsdbmNcS2SDs0daEPfhVXgODk0IVrgguJ-TJACHyXYa9Ae8DaxcvRy89KLgm"
}

Example 3: A BLS12-381 public key containing the G1 and G2 values, encoded as a Multikey in a controller document

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/data-integrity/v1"
  ],
  "id": "https://example.com/issuer/123",
  "verificationMethod": [{
    "id": "https://example.com/issuer/123#key-1",
    "type": "Multikey",
    "controller": "https://example.com/issuer/123",
    "publicKeyMultibase": "u7ljnAxKdp7YVqJvcMU9GtnmrMc1XZztXHsTsZ2LsmGJ67SsdbmNc
      S2SDs0daEPfhVXgODk0IVrgguJ-TJACHyXYa9Ae8DaxcvRy89KLgmWsyOOJn2oY7vCE2gt
      JoebMJiQsdbmNcS2SDs0daEPfhVXgODk0IVrgguJ-TJACHyXYa9Ae8DaxcvRy89KLgm"
  }]
}

This suite relies on detached digital signatures represented using [MULTIBASE].

The verificationMethod property of the proof MUST be a URL. Dereferencing the verificationMethod MUST result in an object containing a type property with the value set to Multikey or JsonWebKey.

The type property of the proof MUST be DataIntegrityProof.

The cryptosuite property of the proof MUST be bbs-signature-2023.

The created property of the proof MUST be an [XMLSCHEMA11-2] formated date string.

The proofPurpose property of the proof MUST be a string, and MUST match the verification relationship expressed by the verification method controller.

The proofValue property of the proof MUST be a detached BBS Signature produced according to Sign, encoded according to [MULTIBASE] using the base64 base encoding with no padding.

Example 4: An BBS digital signature expressed as a DataIntegrityProof

{
  "@context": [
    {"title": "https://schema.org/title"},
    "https://w3id.org/security/data-integrity/v1"
  ],
  "title": "Hello world!",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "bbs-signature-2023",
    "created": "2020-11-05T19:23:24Z",
    "verificationMethod": "https://example.com/issuer/123#key-2",
    "proofPurpose": "assertionMethod",
    "proofValue": "uU6i3dTz5yFfWJ8zgsamuyZa4yAHPm75tUOOXddR6krCvCYk77sbCOuEVcdB
      Dd/l6tIYkTTbA3pmDa6Qia/JkOnIXDLmoBz3vsi7L5t3DWySI/VLmBqleJ/Tbus5RoyiDERDB
      5rnACXlnOqJ/U8yFQFtcp/mBCc2FtKNPHae9jKIv1dm9K9QK1F3GI1AwyGoUfjLWrkGDObO1o
      AhpEd0+et+qiOf2j8p3MTTtRRx4Hgjcl0jXCq7C7R5/nLpgimHAAAAdAx4ouhMk7v9dXijCIM
      0deicn6fLoq3GcNHuH5X1j22LU/hDu7vvPnk/6JLkZ1xQAAAAIPd1tu598L/K3NSy0zOy6oba
      Enaqc1R5Ih/6ZZgfEln2a6tuUp4wePExI1DGHqwj3j2lKg31a/6bSs7SMecHBQdgIYHnBmCYG
      nu/LZ9TFV56tBXY6YOWZgFzgLDrApnrFpixEACM9rwrJ5ORtxAAAAAgE4gUIIC9aHyJNa5TBk
      Oh6ojlvQkMVLXa/vEl+3NCLXblxjgpM7UEMqBkE9/aGQcoD3Tgmy+z0hN+4elMky1RnJEhCuN
      QNsEg"
  }
}

This suite relies on detached digital signatures represented using [MULTIBASE].

The type property of the proof MUST be DataIntegrityProof.

The cryptosuite property of the proof MUST be bbs-proof-2023.

The created property of the proof MUST be an [XMLSCHEMA11-2] formated date string.

The proofPurpose property of the proof MUST be a string, and MUST match the verification relationship expressed by the verification method controller.

The proofValue property of the proof MUST be a detached BBS Signature produced according to ProofGen, encoded according to [MULTIBASE] using the base64 base encoding with no padding.

Example 5: An BBS zero-knowledge proof-of-knowledge of a signature expressed as a DataIntegrityProof

{
  "@context": [
    {"title": "https://schema.org/title"},
    "https://w3id.org/security/data-integrity/v1"
  ],
  "title": "Hello world!",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "bbs-proof-2023",
    "created": "2020-11-05T19:23:24Z",
    "verificationMethod": "https://example.com/issuer/123#key-2",
    "proofPurpose": "assertionMethod",
    "generators": 3,
    "disclosed": [ 2 ],
    "proofValue": "uU6i3dTz5yFfWJ8zgsamuyZa4yAHPm75tUOOXddR6krCvCYk77sbCOuEVcdB
      Dd/l6tIYkTTbA3pmDa6Qia/JkOnIXDLmoBz3vsi7L5t3DWySI/VLmBqleJ/Tbus5RoyiDERDB
      5rnACXlnOqJ/U8yFQFtcp/mBCc2FtKNPHae9jKIv1dm9K9QK1F3GI1AwyGoUfjLWrkGDObO1o
      AhpEd0+et+qiOf2j8p3MTTtRRx4Hgjcl0jXCq7C7R5/nLpgimHAAAAdAx4ouhMk7v9dXijCIM
      0deicn6fLoq3GcNHuH5X1j22LU/hDu7vvPnk/6JLkZ1xQAAAAIPd1tu598L/K3NSy0zOy6oba
      Enaqc1R5Ih/6ZZgfEln2a6tuUp4wePExI1DGHqwj3j2lKg31a/6bSs7SMecHBQdgIYHnBmCYG
      nu/LZ9TFV56tBXY6YOWZgFzgLDrApnrFpixEACM9rwrJ5ORtxAAAAAgE4gUIIC9aHyJNa5TBk
      Oh6ojlvQkMVLXa/vEl+3NCLXblxjgpM7UEMqBkE9/aGQcoD3Tgmy+z0hN+4elMky1RnJEhCuN
      QNsEg"
  }
}

The following section describes multiple Data Integrity cryptographic suites that utilize the BBS Signature Algorithm [CFRG-BBS-SIGNATURE].

The bbs-signature-2023 cryptographic suite takes an input document, canonicalizes the document using the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof. The algorithms in this section also include the verification of such a data integrity proof.

To generate a proof, the algorithm in Section 4.1: Add Proof in the Data Integrity [VC-DATA-INTEGRITY] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section 3.1.3 Transformation, the hashing algorithm is defined in Section 3.1.4 Hashing, and the proof serialization algorithm is defined in Section 3.1.6 Proof Serialization.

To verify a proof, the algorithm in Section 4.2: Verify Proof in the Data Integrity [VC-DATA-INTEGRITY] specification MUST be executed. For that algorithm, the cryptographic suite specific transformation algorithm is defined in Section 3.1.3 Transformation, the hashing algorithm is defined in Section 3.1.4 Hashing, and the proof verification algorithm is defined in Section 3.1.7 Proof Verification.

The following algorithm specifies how to transform an unsecured input document into a transformed document that is ready to be provided as input to the hashing algorithm in Section 3.1.4 Hashing.

Required inputs to this algorithm are an unsecured data document (unsecuredDocument) and transformation options (options). The transformation options MUST contain a type identifier for the cryptographic suite (type) and a cryptosuite identifier (cryptosuite). A transformed data document is produced as output. Whenever this algorithm encodes strings, it MUST use UTF-8 encoding.

If options.type is not set to the string DataIntegrityProof and options.cryptosuite is not set to the string bbs-signature-2023 then a PROOF_TRANSFORMATION_ERROR MUST be raised.
Let canonicalDocument be the result of applying the Universal RDF Dataset Canonicalization Algorithm [RDF-CANON] to the unsecuredDocument.
Set output to the value of canonicalDocument.
Return canonicalDocument as the transformed data document.

The following algorithm specifies how to cryptographically hash a transformed data document and proof configuration into cryptographic hash data that is ready to be provided as input to the algorithms in Section 3.1.6 Proof Serialization or Section 3.1.7 Proof Verification.

The required inputs to this algorithm are a transformed data document (transformedDocument) and proof configuration (proofConfig). A single hash data value represented as series of bytes is produced as output.

Issue
Specify how each item in the canonicalized input is hashed and included a set that is then signed over in 3.1.6 Proof Serialization.
Issue
Specify how proofConfigHash is generated.
Issue
Specify how hashData is composed in a way that can be signed over in 3.1.6 Proof Serialization.
Return hashData as the hash data.

The following algorithm specifies how to generate a proof configuration from a set of proof options that is used as input to the proof hashing algorithm.

The required inputs to this algorithm are proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MUST contain a cryptosuite identifier (cryptosuite). A proof configuration object is produced as output.

Let proofConfig be an empty object.
Set proofConfig.type to options.type.
If options.cryptosuite is set, set proofConfig.cryptosuite to its value.
If options.type is not set to DataIntegrityProof and proofConfig.cryptosuite is not set to bbs-signature-2023, an INVALID_PROOF_CONFIGURATION error MUST be raised.
Set proofConfig.created to options.created. If the value is not a valid [XMLSCHEMA11-2] datetime, an INVALID_PROOF_DATETIME error MUST be raised.
Set proofConfig.verificationMethod to options.verificationMethod.
Set proofConfig.proofPurpose to options.proofPurpose.
Return proofConfig.

The following algorithm specifies how to serialize a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData) and proof options (options). The proof options MUST contain a type identifier for the cryptographic suite (type) and MAY contain a cryptosuite identifier (cryptosuite). A single digital proof value represented as series of bytes is produced as output.

Let privateKeyBytes be the result of retrieving the private key bytes associated with the options.verificationMethod value as described in the Data Integrity [VC-DATA-INTEGRITY] specification.
Issue
Specify how proofBytes is generated and consumed by Section 3.1.7 Proof Verification.
Return proofBytes as the digital proof.

The following algorithm specifies how to verify a digital signature from a set of cryptographic hash data. This algorithm is designed to be used in conjunction with the algorithms defined in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Algorithms. Required inputs are cryptographic hash data (hashData), a digital signature (proofBytes) and proof options (options). A verification result represented as a boolean value is produced as output.

Let publicKeyBytes be the result of retrieving the public key bytes associated with the options.verificationMethod value as described in the Data Integrity [VC-DATA-INTEGRITY] specification, Section 4: Retrieving Cryptographic Material.
Let verificationResult be the result of applying the verification algorithm defined in the BBS Signature specification [CFRG-BBS-SIGNATURE], with hashData as the data to be verified against the proofBytes using the public key specified by publicKeyBytes.
Return verificationResult as the verification result.

The bbs-proof-2023 cryptographic suite takes an input document, that has previously been secured using bbs-signature-2023, derives from this original document a set of messages to be disclosed representing a redacted form of the original document, and applies the Proof Gen algorithm to produce a proof of knowledge for the disclosed messages. The result is a new proof, containing the following attributes:

generators
disclosed
proofValue

This operation can be applied by any holder of a bbs-signature-2023 secured document, and as such, bbs-proof-2023 MUST be implemented with awareness of the mandatory to disclose fields the original issuer required.

Issue 3: Included rationale for `requiredRevealStatements` ready-for-pr

In a BBS Signature we must define the term requiredRevealStatements which communicates which statments must be revealed when generating a proof as according to the issuer.

Issue 81: Define: Add Proof (bbs-proof-2023)

Document how this function works, with special care to explaining blank node transformations.

Issue 82: Define: Verify Proof (bbs-proof-2023)

Document how to verify a derived proof, with special consideration for blank node transformations and mandatory to disclose fields.

Issue 83: Define: Transformation (bbs-proof-2023)

Document how the derived proof secured document is transformed in to messages that can be verified with the provided proofValue.

Issue 84: Hashing (bbs-proof-2023)

Describe if / how hashing is relevant to this ciphersuite.

Issue 85: Define: Proof Configuration, Serialization, Verification (bbs-proof-2023)

Define how the Data Integrity Proof side of (bbs-proof-2023) are expressed.

Issue 85: Define: Proof Configuration, Serialization, Verification (bbs-proof-2023)

Define how the Data Integrity Proof side of (bbs-proof-2023) are expressed.

Issue 85: Define: Proof Configuration, Serialization, Verification (bbs-proof-2023)

Define how the Data Integrity Proof side of (bbs-proof-2023) are expressed.

BBS Cryptosuite v2023

Securing Verifiable Credentials with Selective Disclosure using BBS Signatures

Abstract

Status of This Document

1. Introduction

1.1 Terminology

1.2 Conformance

2. Data Model

2.1 Verification Methods

2.1.1 JsonWebKey

2.1.2 Multikey

2.2 Data Integrity Proof

2.2.1 bbs-signature-2023

2.2.2 bbs-proof-2023

3. Algorithms

3.1 bbs-signature-2023

3.1.1 Add Proof

3.1.2 Verify Proof

3.1.3 Transformation

3.1.4 Hashing

3.1.5 Proof Configuration

3.1.6 Proof Serialization

3.1.7 Proof Verification

3.2 bbs-proof-2023

3.2.1 Add Proof

3.2.2 Verify Proof

3.2.3 Transformation

3.2.4 Hashing

3.2.5 Proof Configuration

3.2.6 Proof Serialization

3.2.7 Proof Verification

4. Privacy Considerations

5. Security Considerations

A. Acknowledgements

B. References

B.1 Normative references

B.2 Informative references