kych

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

vp.md (5454B)

      1 ## Swiyu VP Format
      2 The Verifiable Presentation is generated by the Swiyu Wallet.
      3 The process of creating a Verifiable Presentation (VP) is orchestrated by the `CreateVcSdJwtVerifiablePresentationImpl.kt` file, located at `openid4vc/src/main/java/ch/admin/foitt/openid4vc/domain/usecase/vcSdJwt/implementation/` in the swiyu wallet codebase. The primary methods involved are `invoke` and `createKeyBindingJwt`.
      4 
      5 The resulting VP is a string containing the original SD-JWT Verifiable Credential (VC) and, if required by the verifier, a newly created Key Binding JWT. The Key Binding JWT proves possession of the private key associated with the public key in the VC's `cnf` claim.
      6 
      7 The final VP string is structured as follows:
      8 ```
      9 <vc_sd_jwt>~<kb_header>.<kb_payload>.<kb_signature>
     10 ```
     11 Where `<vc_sd_jwt>` is constituted by
     12 ```
     13 <header>.<payload›.<signature>~<disclosures> 
     14 ```
     15 See the Verifiable Credential [breakdown](vc.md) for more details.
     16 
     17 ##### Key Binding Header (kb_header)
     18 ```JSON
     19 { "alg": "ES256", "typ": "kb+jwt" }
     20 ```
     21 
     22 #### Key Binding Payload (kb_payload)
     23 The payload contains claims that bind the presentation to the specific transaction.
     24 
     25 ```JSON
     26 {
     27   "sd_hash": [hash of sd-jwt]
     28   "aud": "https://verifier.example.com/callback",
     29   "nonce": "1234567890",
     30   "iat": 1754581412
     31 }
     32 ```
     33 Where:
     34 * sd_hash (SD-JWT Digest)
     35   * A Base64url-encoded SHA-256 of the SD-JWT VC (including disclosures). This cryptographically links the Key Binding JWT to the credential being presented.
     36   * Mandatory.
     37 
     38 * aud (Audience)
     39   * Identifies the recipient for which the JWT is intended.
     40   * Mandatory.
     41 
     42 * nonce (Nonce)
     43   * Mandatory.
     44 
     45 * iat (Issued At)
     46   * Represents the time at which the Key Binding JWT was issued. Unix timestamp.
     47   * Mandatory.
     48 
     49 ### Full SD-JWT VP Example (b64 Encoded)
     50 The final output is a string. It starts with the full SD-JWT VC (header, payload, signature, separated by `.`, and disclosures, separated by `~`), followed by another `~` and the signed Key Binding JWT.
     51 The final output is a string encoded in base 64 with the format: `<header>.<payload›.<signature>~<disclosures>~<kb_header>.<kb_payload>.<kb_signature>`
     52 
     53 ```
     54 ewogICJhbGciOiJFUzI1NiIsIAogICJraWQiOiJkaWQ6ZXhhbXBsZTppc3N1ZXIxMjMja2V5LTEiLCAKICAidHlwIjoidmMrc2Qtand0Igp9.ewogICJpc3MiOiAiZGlkOnRkdzpleGFtcGxlIiwKICAidmN0IjogImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vaWQ0dmNpL3ZjdC9teS12Y3QtdjAxIiwKICAidmN0I2ludGVncml0eSI6ICJzaGEyNTYtU1ZITGZLZi4uLmQweXNNY2s9IiwKICAiaWF0IjogMTc1NDU4MTQxMiwKICAibmJmIjogMTc1NDU4MTM3OCwKICAiZXhwIjogMTc1NDU4MTUwOCwKICAiX3NkIjogWwogICAgIjJFRzhueTY1T2NUYzA2MUhrVG1uNzNDSVd4R09sRVVaTG1JMXNwdjVTZjAiLAogICAgInNKNXNaZ2wyU1VIU18zOGJwOXJYMnpHQ0hjcHlXQ0EtcUpOaE1UWlZvXzgiLAogICAgInptbkdFR1N3c1Z2U2FUWk9nXzNHRDVYcjJvN3BLYXNGcXpMWG1EZDNPaW8iCiAgXSwKICAiX3NkX2FsZyI6ICJzaGEtMjU2IiwKICAiY25mIjogewogICAgImp3ayI6IHsKICAgICAgImNydiI6ICJQLTI1NiIsCiAgICAgICJpYXQiOiAxNzU0NTgxMzg4LAogICAgICAia2lkIjogIlRlc3QtS2V5IiwKICAgICAgImt0eSI6ICJFQyIsCiAgICAgICJ1c2UiOiAic2lnIiwKICAgICAgIngiOiAiZnlMeE9WWkpqTnZ1bndRMl8tZ3JnMWpWcEljNWRYSEdwcFJUNVF1VVdJNCIsCiAgICAgICJ5IjogImxYMXZLRTl5dEF0MkZTazRKV2NwcW9UbzQ5bW52MGpva0NoMUZXdWEyamsiCiAgICB9CiAgfSwKICAic3RhdHVzIjogewogICAgInN0YXR1c19saXN0IjogewogICAgICAiaWR4IjogMCwKICAgICAgInR5cGUiOiAiU3dpc3NUb2tlblN0YXR1c0xpc3QtMS4wIiwKICAgICAgInVyaSI6ICJodHRwczovL2xvY2FsaG9zdDo4MDgwL3N0YXR1cyIKICAgIH0KICB9Cn0.SIGNATURE~WyJzYWx0XzEyMyIsICJnaXZlbl9uYW1lIiwgIkpvaG4iXQo=~WyJzYWx0XzQ1NiIsICJmYW1pbHlfbmFtZSIsICJEb2UiXQ==~WyJzYWx0Xzc4OSIsICJiaXJ0aGRhdGUiLCAiMTk5MC0wMS0wMSJd
     55 ~
     56 eyAiYWxnIjogIkVTMjU2IiwgInR5cCI6ICJrYitqd3QiIH0=
     57 .
     58 ewogICJzZF9oYXNoIjogW2hhc2ggb2Ygc2Qtand0XQogICJhdWQiOiAiaHR0cHM6Ly92ZXJpZmllci5leGFtcGxlLmNvbS9jYWxsYmFjayIsCiAgIm5vbmNlIjogIjEyMzQ1Njc4OTAiLAogICJpYXQiOiAxNzU0NTgxNDEyCn0=
     59 .
     60 KB_SIGNATURE
     61 ```
     62 Note: The example above has newlines (`\n`) to highlight the separation between each component of the VP.
     63 
     64 The final string would actually be:
     65 ```
     66 ewogICJhbGciOiJFUzI1NiIsIAogICJraWQiOiJkaWQ6ZXhhbXBsZTppc3N1ZXIxMjMja2V5LTEiLCAKICAidHlwIjoidmMrc2Qtand0Igp9.ewogICJpc3MiOiAiZGlkOnRkdzpleGFtcGxlIiwKICAidmN0IjogImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9vaWQ0dmNpL3ZjdC9teS12Y3QtdjAxIiwKICAidmN0I2ludGVncml0eSI6ICJzaGEyNTYtU1ZITGZLZi4uLmQweXNNY2s9IiwKICAiaWF0IjogMTc1NDU4MTQxMiwKICAibmJmIjogMTc1NDU4MTM3OCwKICAiZXhwIjogMTc1NDU4MTUwOCwKICAiX3NkIjogWwogICAgIjJFRzhueTY1T2NUYzA2MUhrVG1uNzNDSVd4R09sRVVaTG1JMXNwdjVTZjAiLAogICAgInNKNXNaZ2wyU1VIU18zOGJwOXJYMnpHQ0hjcHlXQ0EtcUpOaE1UWlZvXzgiLAogICAgInptbkdFR1N3c1Z2U2FUWk9nXzNHRDVYcjJvN3BLYXNGcXpMWG1EZDNPaW8iCiAgXSwKICAiX3NkX2FsZyI6ICJzaGEtMjU2IiwKICAiY25mIjogewogICAgImp3ayI6IHsKICAgICAgImNydiI6ICJQLTI1NiIsCiAgICAgICJpYXQiOiAxNzU0NTgxMzg4LAogICAgICAia2lkIjogIlRlc3QtS2V5IiwKICAgICAgImt0eSI6ICJFQyIsCiAgICAgICJ1c2UiOiAic2lnIiwKICAgICAgIngiOiAiZnlMeE9WWkpqTnZ1bndRMl8tZ3JnMWpWcEljNWRYSEdwcFJUNVF1VVdJNCIsCiAgICAgICJ5IjogImxYMXZLRTl5dEF0MkZTazRKV2NwcW9UbzQ5bW52MGpva0NoMUZXdWEyamsiCiAgICB9CiAgfSwKICAic3RhdHVzIjogewogICAgInN0YXR1c19saXN0IjogewogICAgICAiaWR4IjogMCwKICAgICAgInR5cGUiOiAiU3dpc3NUb2tlblN0YXR1c0xpc3QtMS4wIiwKICAgICAgInVyaSI6ICJodHRwczovL2xvY2FsaG9zdDo4MDgwL3N0YXR1cyIKICAgIH0KICB9Cn0.SIGNATURE~WyJzYWx0XzEyMyIsICJnaXZlbl9uYW1lIiwgIkpvaG4iXQo=~WyJzYWx0XzQ1NiIsICJmYW1pbHlfbmFtZSIsICJEb2UiXQ==~WyJzYWx0Xzc4OSIsICJiaXJ0aGRhdGUiLCAiMTk5MC0wMS0wMSJd~eyAiYWxnIjogIkVTMjU2IiwgInR5cCI6ICJrYitqd3QiIH0=.ewogICJzZF9oYXNoIjogW2hhc2ggb2Ygc2Qtand0XQogICJhdWQiOiAiaHR0cHM6Ly92ZXJpZmllci5leGFtcGxlLmNvbS9jYWxsYmFjayIsCiAgIm5vbmNlIjogIjEyMzQ1Njc4OTAiLAogICJpYXQiOiAxNzU0NTgxNDEyCn0=.KB_SIGNATURE
     67 ```