kych

OAuth 2.0 API for Swiyu to enable Taler integration of Swiyu for KYC (experimental)
Log | Files | Refs

vc.md (6630B)

      1 ## Swiyu VC Format
      2 The Verifiable Credential is generated by the Swiyu Verifier.
      3 The process is orchestrated by the `getCredential method` in the `issuer-service/src/main/java/ch/admin/bj/swiyu/issuer/service/SdJwtCredential.java` file. It uses the functions `addTechnicalData`, `prepareDisclosures`, `addHolderBinding` and `addStatusReferences`.
      4 
      5 This is JWT the format of a VC generated by the swiyu-issuer:
      6 `<header>.<payload>.<signature>~<disclosure1>~<disclosure2>~<disclosure3>`
      7 
      8 #### JWT Header
      9 ```JSON
     10 { "alg":"ES256", "kid":"did:example:issuer123#key-1", "typ":"vc+sd-jwt" }
     11 ```
     12 
     13 #### JWT Payload
     14 ```JSON
     15 {
     16   "iss": "did:tdw:example",
     17   "vct": "http://localhost:8080/oid4vci/vct/my-vct-v01",
     18   "vct#integrity": "sha256-SVHLfKf...d0ysMck=",
     19   "iat": 1754581412,
     20   "nbf": 1754581378,
     21   "exp": 1754581508,
     22   "_sd": [
     23     "2EG8ny65OcTc061HkTmn73CIWxGOlEUZLmI1spv5Sf0",
     24     "sJ5sZgl2SUHS_38bp9rX2zGCHcpyWCA-qJNhMTZVo_8",
     25     "zmnGEGSwsVvSaTZOg_3GD5Xr2o7pKasFqzLXmDd3Oio"
     26   ],
     27   "_sd_alg": "sha-256",
     28   "cnf": {
     29     "jwk": {
     30       "crv": "P-256",
     31       "iat": 1754581388,
     32       "kid": "Test-Key",
     33       "kty": "EC",
     34       "use": "sig",
     35       "x": "fyLxOVZJjNvunwQ2_-grg1jVpIc5dXHGppRT5QuUWI4",
     36       "y": "lX1vKE9ytAt2FSk4JWcpqoTo49mnv0jokCh1FWua2jk"
     37     }
     38   },
     39   "status": {
     40     "status_list": {
     41       "idx": 0,
     42       "type": "SwissTokenStatusList-1.0",
     43       "uri": "https://localhost:8080/status"
     44     }
     45   }
     46 }
     47 ```
     48 ##### Field Explanation
     49 * iss (Issuer)
     50     * Identifies the entity that issued the JWT.
     51     * Mandatory (per JWT specification RFC 7519).
     52 
     53 * vct (Verifiable Credential Type)
     54     * A URI that identifies the type of VC. This helps verifiers understand the schema, context, and expected claims of the credential.
     55     * Mandatory (per SD-JWT VC specification).
     56 
     57 * vct#integrity
     58     * A hash of the content found at the vct URI. This provides an integrity check, ensuring that the credential type definition has not been tampered with or changed since the credential was issued.
     59     * Optional (per SD-JWT VC specification).
     60 
     61 * iat (Issued At)
     62     * Represents the time at which the JWT was issued. Unix timestamp.
     63     * Mandatory (per JWT specification RFC 7519).
     64 
     65 * nbf (Not Before)
     66     * Specifies the time before which the JWT MUST NOT be accepted for processing. Unix timestamp.
     67     * Optional (per JWT specification RFC 7519).
     68 
     69 * exp (Expiration Time)
     70     * Defines the expiration time on or after which the JWT MUST NOT be accepted for processing. Unix timestamp.
     71     * Optional (per JWT specification RFC 7519).
     72 
     73 * \_sd (Selective Disclosure Digests)
     74     * An array containing Base64url-encoded SHA-256 hashes of the claims that can be selectively disclosed.
     75     * Mandatory.
     76 
     77 * \_sd_alg (Selective Disclosure Algorithm)
     78     * Indicates the hashing algorithm used to generate the digests found in the \_sd array.
     79     * Mandatory if \_sd is present (per SD-JWT specification).
     80 
     81 * cnf (Confirmation)
     82     * Used to cryptographically bind the credential to a specific holder. It contains a JSON Web Key (JWK) representing the holder's public key. The holder uses this key to sign Verifiable Presentations, proving they are the legitimate owner of the credential.
     83     * Optional, (per SD-JWT VC specification), in practice Mandatory.
     84 
     85 * status
     86     * Provides information about the current status of the credential, such as revoked or suspended. Points to a status list.
     87     * Optional (per SD-JWT VC specification).
     88 
     89 #### Full SD-JWT VC
     90 The final output is a string encoded in base 64 with the format: `<header>.<payload>.<signature>~<disclosure1>~<disclosure2>~<disclosure3>`
     91 
     92 For example with the JWT defined above and the disclosures:
     93 ```JSON
     94 ["salt_123", "given_name", "John"]
     95 ["salt_456", "family_name", "Doe"]
     96 ["salt_789", "birthdate", "1990-01-01"]
     97 ```
     98 
     99 ```
    100 ewogICJhbGciOiJFUzI1NiIsIAogICJraWQiOiJkaWQ6ZXhhbXBsZTppc3N1ZXIxMjMja2V5LTEiLCAKICAidHlwIjoidmMrc2Qtand0Igp9
    101 .
    102 ewogICJpc3MiOiAiZGlkOnRkdzpleGFtcGxlIiwKICAidmN0IjogImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vaWQ0dmNpL3ZjdC9teS12Y3QtdjAxIiwKICAidmN0I2ludGVncml0eSI6ICJzaGEyNTYtU1ZITGZLZi4uLmQweXNNY2s9IiwKICAiaWF0IjogMTc1NDU4MTQxMiwKICAibmJmIjogMTc1NDU4MTM3OCwKICAiZXhwIjogMTc1NDU4MTUwOCwKICAiX3NkIjogWwogICAgIjJFRzhueTY1T2NUYzA2MUhrVG1uNzNDSVd4R09sRVVaTG1JMXNwdjVTZjAiLAogICAgInNKNXNaZ2wyU1VIU18zOGJwOXJYMnpHQ0hjcHlXQ0EtcUpOaE1UWlZvXzgiLAogICAgInptbkdFR1N3c1Z2U2FUWk9nXzNHRDVYcjJvN3BLYXNGcXpMWG1EZDNPaW8iCiAgXSwKICAiX3NkX2FsZyI6ICJzaGEtMjU2IiwKICAiY25mIjogewogICAgImp3ayI6IHsKICAgICAgImNydiI6ICJQLTI1NiIsCiAgICAgICJpYXQiOiAxNzU0NTgxMzg4LAogICAgICAia2lkIjogIlRlc3QtS2V5IiwKICAgICAgImt0eSI6ICJFQyIsCiAgICAgICJ1c2UiOiAic2lnIiwKICAgICAgIngiOiAiZnlMeE9WWkpqTnZ1bndRMl8tZ3JnMWpWcEljNWRYSEdwcFJUNVF1VVdJNCIsCiAgICAgICJ5IjogImxYMXZLRTl5dEF0MkZTazRKV2NwcW9UbzQ5bW52MGpva0NoMUZXdWEyamsiCiAgICB9CiAgfSwKICAic3RhdHVzIjogewogICAgInN0YXR1c19saXN0IjogewogICAgICAiaWR4IjogMCwKICAgICAgInR5cGUiOiAiU3dpc3NUb2tlblN0YXR1c0xpc3QtMS4wIiwKICAgICAgInVyaSI6ICJodHRwczovL2xvY2FsaG9zdDo4MDgwL3N0YXR1cyIKICAgIH0KICB9Cn0
    103 .
    104 SIGNATURE
    105 ~
    106 WyJzYWx0XzEyMyIsICJnaXZlbl9uYW1lIiwgIkpvaG4iXQo=
    107 ~
    108 WyJzYWx0XzQ1NiIsICJmYW1pbHlfbmFtZSIsICJEb2UiXQ==
    109 ~
    110 WyJzYWx0Xzc4OSIsICJiaXJ0aGRhdGUiLCAiMTk5MC0wMS0wMSJd
    111 ```
    112 Note: The example above has newlines (`\n`) to highlight the separation between each component of the sd-jwt VC.
    113 
    114 The final string would actually be:
    115 ```
    116 ewogICJhbGciOiJFUzI1NiIsIAogICJraWQiOiJkaWQ6ZXhhbXBsZTppc3N1ZXIxMjMja2V5LTEiLCAKICAidHlwIjoidmMrc2Qtand0Igp9.ewogICJpc3MiOiAiZGlkOnRkdzpleGFtcGxlIiwKICAidmN0IjogImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vaWQ0dmNpL3ZjdC9teS12Y3QtdjAxIiwKICAidmN0I2ludGVncml0eSI6ICJzaGEyNTYtU1ZITGZLZi4uLmQweXNNY2s9IiwKICAiaWF0IjogMTc1NDU4MTQxMiwKICAibmJmIjogMTc1NDU4MTM3OCwKICAiZXhwIjogMTc1NDU4MTUwOCwKICAiX3NkIjogWwogICAgIjJFRzhueTY1T2NUYzA2MUhrVG1uNzNDSVd4R09sRVVaTG1JMXNwdjVTZjAiLAogICAgInNKNXNaZ2wyU1VIU18zOGJwOXJYMnpHQ0hjcHlXQ0EtcUpOaE1UWlZvXzgiLAogICAgInptbkdFR1N3c1Z2U2FUWk9nXzNHRDVYcjJvN3BLYXNGcXpMWG1EZDNPaW8iCiAgXSwKICAiX3NkX2FsZyI6ICJzaGEtMjU2IiwKICAiY25mIjogewogICAgImp3ayI6IHsKICAgICAgImNydiI6ICJQLTI1NiIsCiAgICAgICJpYXQiOiAxNzU0NTgxMzg4LAogICAgICAia2lkIjogIlRlc3QtS2V5IiwKICAgICAgImt0eSI6ICJFQyIsCiAgICAgICJ1c2UiOiAic2lnIiwKICAgICAgIngiOiAiZnlMeE9WWkpqTnZ1bndRMl8tZ3JnMWpWcEljNWRYSEdwcFJUNVF1VVdJNCIsCiAgICAgICJ5IjogImxYMXZLRTl5dEF0MkZTazRKV2NwcW9UbzQ5bW52MGpva0NoMUZXdWEyamsiCiAgICB9CiAgfSwKICAic3RhdHVzIjogewogICAgInN0YXR1c19saXN0IjogewogICAgICAiaWR4IjogMCwKICAgICAgInR5cGUiOiAiU3dpc3NUb2tlblN0YXR1c0xpc3QtMS4wIiwKICAgICAgInVyaSI6ICJodHRwczovL2xvY2FsaG9zdDo4MDgwL3N0YXR1cyIKICAgIH0KICB9Cn0.SIGNATURE~WyJzYWx0XzEyMyIsICJnaXZlbl9uYW1lIiwgIkpvaG4iXQo=~WyJzYWx0XzQ1NiIsICJmYW1pbHlfbmFtZSIsICJEb2UiXQ==~WyJzYWx0Xzc4OSIsICJiaXJ0aGRhdGUiLCAiMTk5MC0wMS0wMSJd
    117 ```