This specification describes Data Integrity cryptographic suites for use when creating or verifying a digital signature using the the secp256k1 instantiation of the Schnorr Signature Algorithm as defined in [[BIP340]].
This specification defines a cryptographic suite for the purpose of creating, verifying proofs for Schnorr signatures over secp256k1 in conformance with the Data Integrity [[VC-DATA-INTEGRITY]] specification.
The suites described in this specification use the RDF Dataset Canonicalization Algorithm [[RDF-CANON]] or the JSON Canonicalization Scheme [[RFC8785]] to transform an input document into its canonical form. The canonical representation is then hashed and signed with a detached signature algorithm.
Terminology used throughout this document is defined in the Terminology section of the [[[VC-DATA-INTEGRITY]]] specification.
A conforming proof is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections [[[#data-model]]] and [[[#algorithms]]] of this document MUST be enforced.
A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming proof. Conforming processors MUST produce errors when non-conforming documents are consumed.
This document contains examples of JSON and JSON-LD data. Some of these examples are invalid JSON, as they include features such as inline comments (`//`) explaining certain portions and ellipses (`...`) indicating the omission of information that is irrelevant to the example. These parts would have to be removed in order to treat the examples as valid JSON or JSON-LD.
The following sections outline the data model that is used by this specification to express verification methods, such as cryptographic public keys, and data integrity proofs, such as digital signatures.
This cryptographic suite is used to verify Data Integrity Proofs [[VC-DATA-INTEGRITY]] produced using secp256k1 cryptographic key material. The encoding formats for those key types are provided in this section. Lossless cryptographic key transformation processes that result in equivalent cryptographic key material MAY be used for the processing of digital signatures.
The Multikey format, defined in [[[CID]]], is used to express public keys for the cryptographic suites defined in this specification.
The `publicKeyMultibase` value of the verification method MUST be a a base-58-btc Multibase encoding of a Multikey encoded secp256k1 x-only public key. The Multikey encoding of a secp256k1 x-only 256-bit public key MUST start with the two-byte prefix 0xe14a (the varint expression of 0x2561) followed by the 32-byte x-only public key data. The resulting 34-byte value MUST then be encoded using the base-58-btc alphabet, according to Section 2.4 Multibase of [[[CID]]], and then prepended with the base-58-btc Multibase header (z). Any other encoding MUST NOT be allowed.
Developers are advised to not accidentally publish a representation of a private key. Implementations of this specification will raise errors if they encounter a Multikey prefix value other than `0xe14a` in a `publicKeyMultibase` value.
{
"id": "https://example.com/issuer/123#key-0",
"type": "Multikey",
"controller": "https://example.com/issuer/123",
"publicKeyMultibase": "z66PwJnYvwJLhGrVc8vcuUkKs99sKCzYRM2HQ2gDCGTAStHk"
}
{
"id": "did:example:123",
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"verificationMethod": [
{
"id": "did:example:123#initialKey",
"type": "Multikey",
"controller": "did:example:123",
"publicKeyMultibase": "z66PwJnYvwJLhGrVc8vcuUkKs99sKCzYRM2HQ2gDCGTAStHk"
}
],
"authentication": [
"did:example:123#initialKey"
],
"assertionMethod": [
"did:example:123#initialKey"
],
"capabilityInvocation": [
"did:example:123#initialKey"
],
"capabilityDelegation": [
"did:example:123#initialKey"
]
}
TODO: Do we want to define a secretKeyMultibase value for secp256k1 keys?
Developers are advised to prevent accidental publication of a representation of a secret key, and to not export the `secretKeyMultibase` property by default, when serializing key pairs to Multikey.
This section details the proof representation formats that are defined by this specification.
A proof contains the attributes specified in the Proofs section of [[VC-DATA-INTEGRITY]] with the following restrictions.
The `type` property MUST be `DataIntegrityProof`.
The `cryptosuite` property of the proof MUST be `schnorr-secp256k1-jcs-2025` or `schnorr-secp256k1-rdfc-2025`.
The `proofValue` property of the proof MUST be a detached Schnorr signature produced according to [[BIP340]], encoded using the base-64-url header and alphabet as described in the Multibase section of [[[controller-document]]].
{
"@context": [
{"myWebsite": "https://vocabulary.example/myWebsite"},
"https://www.w3.org/ns/credentials/v2"
],
"myWebsite": "https://hello.world.example/",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "schnorr-secp256k1-jcs-2024",
"verificationMethod": "did:btc1:k1q2ddta4gt5n7u6d3xwhdyua57t6awrk55ut82qvurfm0qnrxx5nw7vnsy65#initialKey",
"proofPurpose": "assertionMethod",
"proofValue": "zsxM9je5iKynKyN6rRPi9QjTWpG6inJ1umwGfnCo4fiu4MqYf46PLd4TE2wVZvdZegDuC6xL6n3Kj8S1PbC8tmTm"
}
}
TODO: Make example a valid proof. Currently it is a realy proof, but not over that content
The following section describes multiple Data Integrity cryptographic suites that use the Schnorr Signature for secp256k1 Algorithm [[BIP340]].
This algorithm is used to configure a cryptographic suite to be used by the Add Proof and Verify Proof functions in [[[VC-DATA-INTEGRITY]]]. The algorithm takes an options object ([=map=] |options|) as input and returns a [=data integrity cryptographic suite instance|cryptosuite instance=] ([=struct=] |cryptosuite|).
The `schnorr-secp256k1-rdfc-2025` cryptographic suite takes an input document, canonicalizes the document using the 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.
When the RDF Dataset Canonicalization Algorithm [[RDF-CANON]] is used, implementations will detect dataset poisoning by default, and abort processing upon such detection.
The following algorithm specifies how to create a [=data integrity proof=] given an unsecured data document. Required inputs are an unsecured data document ([=map=] |unsecuredDocument|), and a set of proof options ([=map=] |options|). A [=data integrity proof=] ([=map=]), or an error, is produced as output.
The following algorithm specifies how to verify a [=data integrity proof=] given an secured data document. Required inputs are an secured data document ([=map=] |securedDocument|). This algorithm returns a verification result, which is a [=struct=] whose [=struct/items=] are:
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 [[[#hashing-schnorr-secp256k1-rdfc-2025]]].
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.
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 [[[#proof-serialization-schnorr-secp256k1-rdfc-2025]]] or Section [[[#proof-verification-schnorr-secp256k1-rdfc-2025]]].
The required inputs to this algorithm are a transformed data document (`transformedDocument`) and canonical proof configuration (`canonicalProofConfig`). A single hash data value represented as series of bytes is produced as output.
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 the document (|unsecuredDocument|) and the 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.
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.
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.
The `schnorr-secp256k1-jcs-2025` cryptographic suite takes an input document, canonicalizes the document using the JSON Canonicalization Scheme [[RFC8785]], and then cryptographically hashes and signs the output resulting in the production of a data integrity proof.
The following algorithm specifies how to create a [=data integrity proof=] given an unsecured data document. Required inputs are an unsecured data document ([=map=] |unsecuredDocument|), and a set of proof options ([=map=] |options|). A [=data integrity proof=] ([=map=]), or an error, is produced as output.
The following algorithm specifies how to verify a [=data integrity proof=] given an secured data document. Required inputs are an secured data document ([=map=] |securedDocument|). This algorithm returns a [=verification result=], which is a [=struct=] whose [=struct/items=] are:
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 [[[#hashing-schnorr-secp256k1-jcs-2025]]].
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.
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 [[[#proof-serialization-schnorr-secp256k1-jcs-2025]]] or Section [[[#proof-verification-schnorr-secp256k1-jcs-2025]]].
The required inputs to this algorithm are a transformed data document (`transformedDocument`) and canonical proof configuration (`canonicalProofConfig`). A single hash data value represented as series of bytes is produced as output.
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.
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.
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.
Before reading this section, readers are urged to familiarize themselves with general security advice provided in the Security Considerations section of the Data Integrity specification.
The following section describes security considerations that developers implementing this specification should be aware of in order to create secure software.
Before reading this section, readers are urged to familiarize themselves with general privacy advice provided in the Privacy Considerations section of the Data Integrity specification.
The following section describes privacy considerations that developers implementing this specification should be aware of in order to avoid violating privacy assumptions.
The cryptographic suites described in this specification do not support [=selective disclosure=] or [=unlinkable disclosure=]. If [=selective disclosure=] is a desired feature, readers might find the [[[?VC-DI-ECDSA]]] specification useful. If [=unlinkable disclosure=] is of interest, the [[[?VC-DI-BBS]]] specification provides an unlinkable digital signature mechanism.
This section contains the substantive changes that have been made to this specification over time.