Define the e-signing and e-sealing of Verifiable Accreditations and Attestations

The following subsection will guide you on designing the e-signing and e-sealing methods for the steps that require it in your user journey. The goal is to identify each step that requires a signature and define its profile for every instance.

Securing Verifiable Credentials and Verifiable Presentations using JSON Web Signatures (JWS)

A common way of securing Verifiable Credentials and Verifiable Presentations is by signing them using JSON Web Signatures (JWS).

A JSON Web Signature (JWS) is a compact representation of a digital signature or message authentication code (MAC) for securing data transmitted in JSON format. JWS provides a way to ensure the integrity and authenticity of the data within a JSON object. It is one of the components of the JSON Web Token (JWT) standard, used in the EBSI ecosystem for securely transmitting information between parties in web applications and APIs.

A JWS typically consists of three parts:

1. Header: contains metadata related to the token, and information about the cryptographic operations applied to the JWS, such as the signing algorithm being used (e.g., HMAC, RSA, ECDSA).
2. Payload: contains the actual data that is being 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, authorization, 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. Carries signer's signature details, used key qualities, timestamps, types for full JWS and payload, signer attributes, etc.
JWS Unprotected header	Can carry data related to the JWS Payload, like disclosures, either as values or links.
JWS Payload	Must be self-contained and not depend on other sections. Unprotected header may enrich the payload by giving external links of more data like SD disclosures.
JWS Signature	Digital signature or MAC over the JWS Protected Header and the JWS Payload. Signature may be validated with properties from 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.

In JWS JSON Serialisation, the result is a JSON object allowing multiple signatures, each with their own protected and unprotected headers.

General JWS JSON Serialisation

{
  "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)>"
    }]
}

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

Flattened JWS JSON Serialisation

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

The third and the most common syntax is the JWS Compact Serialisation. In this syntax the components are encoded into a single dot delimited URL-safe string. In the example, '||' denotes concatenation. JWS Compact Serialisation is limited to only one signature and a JWS Unprotected Header is not allowed. These aspects limit the applicability of the compact serialisation in scenarios where multiple signatures are required and in certain scenarios using JAdES.

JWS Compact Serialisation

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

Further details of for the JWS components can be found on this page.

Referring to keys in VCs and VPs

EBSI Verifiable Credentials and Presentations 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 with 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

Hands on!

• Identify the steps in the user journey that require signature creation and the actors that create the signature.
• For every signature, define a profile.

Please use the table in Section 2 Template #11 below to guide you with the key management, access and authorisations.

Section 2 Template #11

Authorised parties	Key-generation and management	Key location	Key access	Signing	Supported algorithms	E-Signing / E-sealing framework (optional)	Selective disclosure (informational)
Who can perform the actions (LE-related signing)	Software (HSM) Software + secure hardware store Hardware HSM (Cloud) KMS	Local Remote	No authentication OS-level authentication HSM/KMS-level authentication	Local Remote	ES256 Other?	eIDAS: JAdES	State your intent about testing/using selective disclosure

With secure signing methods of information exchange established among all actors of your trust chain, it's essential to implement secure identification and authentication methods between agents and devices within your trust chain.

After completing Section 2 Template #11, proceed to Authenticate & Identify.