Introduction

The following is a description of how Veriable Credentials (VCs) and Veriable Presentations (VPs) are encoded and signed in EBSI. This process is based on JSON Web Signatures (JWS) and Verifiable Credentials Data Model (VCDM) v1.1, with additional considerations for the EBSI ecosystem.

Securing VCs and VPs using JWS

A common way of securing VCs and Verifiable Presentations is by signing them using JWS.

A JWS is a compact representation of a digital signature or message authentication code (MAC) for securing data transmitted in JavaScript Object Notation (JSON) format. JWS ensures the integrity and authenticity of the data within a JSON object. It is part of the JSON Web Token (JWT) standard, used in the EBSI ecosystem for securely transmitting information between parties, in the context of web applications and APIs.

A JWS typically consists of three parts:

1. Header: Contains metadata related to the token, including information about the cryptographic operations applied to the JWS, such as the signing algorithm used (e.g., HMAC, RSA or ECDSA).
2. Payload: Contains the actual data secured by the JWS. This data can include various claims or pieces of information depending on the use case.
3. Signature: The cryptographic representation of the header and payload, used to verify the authenticity and integrity of the JWS. JWS can be used in various contexts, including user authentication, authorisation and data transfer between different components of a system.

The contents of a VP or VC are encoded as claims in the JWS payload. The resulting JWS can be serialised using JWS JSON Serialisation or JWS Compact Serialisation. Multiple libraries exist to work with JWTs and JWSs; see here for examples.

Components and syntaxes

Section	Usage
JWS Protected Header	Contains the secured metadata for the whole JWS, including the signer's signature details, key qualities, timestamps, types for full JWS and payload and signer attributes.
JWS Unprotected Header	Can carry data related to the JWS Payload, such as disclosures, which may be done as values or links.
JWS Payload	Must be self-contained and not depend on other sections. The Unprotected Header may enrich the payload by providing external links to additional data, like selective disclosure (SD) disclosures.
JWS Signature	Digital signature or MAC over the JWS Protected Header and the JWS Payload. The signature can be validated using properties of the Protected Header. Claims within the Unprotected Header and Payload must not be used for signature validation purposes. Input octects for the signing algorithm defined in alg header are prepared as follows: ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload))

These logical components can be encoded in three different syntaxes. The applicability of each syntax depends on the number of signatures required and types of headers they can express.

General JWS JSON Serialisation

In general JWS JSON Serialisation, the result is a JSON object that allows multiple signatures, each with its own protected and unprotected headers.

{
  "payload":"<BASE64URL(JWS Payload)>",
  "signatures":[{
      "protected":"<BASE64URL(UTF8(JWS Protected Header 1))>",
      "header":<JWS Unprotected Header 1>,
      "signature":"<BASE64URL(JWS Signature 1)>"
    },...,{
      "protected":"<BASE64URL(UTF8(JWS Protected Header N))>",
      "header":<JWS Unprotected Header N>,
      "signature":"<BASE64URL(JWS Signature N)>"
    }]
}

Flattened JWS JSON Serialisation

JWS JSON Serialisation can also be encoded in a flattened form, resulting in a more concise object but allowing only one signature.

{
  "payload":"<BASE64URL(JWS Payload)>",
  "protected":"<BASE64URL(UTF8(JWS Protected Header))>",
  "header":<JWS Unprotected Header>,
  "signature":"<BASE64URL(JWS Signature)>"
}

JWS Compact Serialisation

The third and most common syntax is the JWS Compact Serialisation. In this syntax, the components are encoded into a single dot-delimited URL-safe string. The example '||' denotes concatenation. JWS Compact Serialisation is limited to only one signature and does not allow a JWS Unprotected Header. These limitations reduce its applicability in scenarios requiring multiple signatures or certain scenarios that us JSON Advanced Electronic Signature (JAdES).

BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)

Signature profile

The signature profile follows VCDM 1.1. For instructions on encoding and decoding a VC in a JWS, refer to the relevant sections in VCDM 1.1 specifications.

Referring to keys in VCs and VPs

EBSI VCs and VPs may be signed by Legal Entities or Natural Persons. Legal Entities are registered in the EBSI DID Registry with a DID Document, which is publicly available. The DID Document contains the public parts of the signing keys used by the Legal Entity. The signing keys are referred to with a DID URI and a fragment that identifies the key within the DID Document.

For example did:ebsi:zz7XsC9ixAXuZecoD9sZEM1#kLMMwMvg_MAJG6tPqUUARrNQhqxUSPGvBg2smCrL_c0 refers to DID did:ebsi:zz7XsC9ixAXuZecoD9sZEM1 and a key identified by kLMMwMvg_MAJG6tPqUUARrNQhqxUSPGvBg2smCrL_c0 in the DID Document.

Information about Natural Persons is not registered in the EBSI DID Registry. Therefore, for Natural Persons, the public part is encoded as part of the DID URI. See here for instructions on how to encode the public key.

DID:KEY example

did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbrDt4zxXoDrBWYFiATYZ8G9JMeEXC7Kki24fbTwtsJbGe5qcbkYFunSzcDokMRmj8UJ1PbdCGh33mf97K3To89bMzd15qrYq3VkDztoZqfmujkJVpvTbqoXWXqxmzNDbvMJ.

Supported digital signatures

Digital Signature Algorithm	Supported curves/parameters	Implementation Requirements
ECDSA	NIST P-256 and SHA-256	Required
ECDSA	NIST P-384 and SHA-384	Optional
ECDSA	NIST P-521 and SHA-512	Optional
ECDSA	secp256k1 and SHA-256	Optional
ECDSA	secp256k1 and SHA-256 with recovery bit	Optional
EdDSA	Curve25519 and SHA-512	Optional
RSASSA	PKCS1-v1_5 using SHA-256	Optional