Copyright © 2023 World Wide Web Consortium. W3C^{®} liability, trademark and permissive document license rules apply.
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 section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.
This document was published by the Verifiable Credentials Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 2 November 2021 W3C Process Document.
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.
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.
id
property in a controller document.
Anything can be a subject: person, group, organization, physical thing, digital
thing, logical thing, etc.
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."
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.
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.
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].
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.
{
"@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"
}
}]
}
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.
{
"id": "https://example.com/issuer/123#key-0",
"type": "Multikey",
"controller": "https://example.com/issuer/123",
"publicKeyMultibase": "u7ljnAxKdp7YVqJvcMU9GtnmrMc1XZztXHsTsZ2LsmGJ67SsdbmNc
S2SDs0daEPfhVXgODk0IVrgguJ-TJACHyXYa9Ae8DaxcvRy89KLgmWsyOOJn2oY7vCE2gt
JoebMJiQsdbmNcS2SDs0daEPfhVXgODk0IVrgguJ-TJACHyXYa9Ae8DaxcvRy89KLgm"
}
{
"@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.
{
"@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 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-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.
{
"@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.
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.
canonicalDocument
be the result of applying the
Universal RDF Dataset Canonicalization Algorithm
[RDF-CANON] to the unsecuredDocument
.
output
to the value of canonicalDocument
.
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.
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.
Specify how proofConfigHash
is generated.
Specify how hashData
is composed in a way that can be signed over in
3.1.6 Proof Serialization.
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.
proofConfig
be an empty object.
proofConfig
.type
to
options
.type
.
options
.cryptosuite
is set, set
proofConfig
.cryptosuite
to its value.
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.
proofConfig
.created
to
options
.created
. If the value is not a valid
[XMLSCHEMA11-2] datetime, an INVALID_PROOF_DATETIME
error MUST be raised.
proofConfig
.verificationMethod
to
options
.verificationMethod
.
proofConfig
.proofPurpose
to
options
.proofPurpose
.
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.
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.
Specify how proofBytes
is generated and consumed by Section
3.1.7 Proof Verification.
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.
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.
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
.
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.
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.
Document how this function works, with special care to explaining blank node transformations.
Document how to verify a derived proof, with special consideration for blank node transformations and mandatory to disclose fields.
Document how the derived proof secured document is transformed in to messages that can be verified with the provided proofValue
.
Describe if / how hashing is relevant to this ciphersuite.
Define how the Data Integrity Proof side of (bbs-proof-2023) are expressed.
Define how the Data Integrity Proof side of (bbs-proof-2023) are expressed.
Define how the Data Integrity Proof side of (bbs-proof-2023) are expressed.
TODO: We need to add a complete list of privacy considerations.
TODO: We need to add a complete list of security considerations.
Portions of the work on this specification have been funded by the United States Department of Homeland Security's (US DHS) Silicon Valley Innovation Program under contracts 70RSAT20T00000003, and 70RSAT20T00000033. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.