diff --git a/docs/arc42/images/VPP-Flow.png b/docs/arc42/images/VPP-Flow.png new file mode 100644 index 000000000..2484455f4 Binary files /dev/null and b/docs/arc42/images/VPP-Flow.png differ diff --git a/docs/arc42/images/VVP-Flow.puml b/docs/arc42/images/VVP-Flow.puml new file mode 100644 index 000000000..d198ed4dc --- /dev/null +++ b/docs/arc42/images/VVP-Flow.puml @@ -0,0 +1,313 @@ +title Verifiable Presentation Protocol (VPP) + +header WIP | DRAFT 20231121 + +footer WIP | DRAFT 20231121 + + +autonumber + +box \n\t\t Data Provider \t\t\n + + database "\n\n CS \n\n" as CS_Provider + control "\n\n STS \n\n" as STS_Provider + actor "\n\n EDC \n\n" as EDC_Provider + +end box + + +box \n\t\t Data Consumer \t\t\n + + actor "\n\n EDC \n\n" as EDC_Consumer + control "\n\n STS \n\n" as STS_Consumer + database "\n\n CS \n\n" as CS_Consumer + +end box + +rnote across + +end note + +rnote across + The Verifiable Presentation Protocol (VPP) is designed to + address the problem of resolving Verifiable Presentations and + other claims when they cannot be passed as part of a client request. +end note +rnote across + The VPP is represented in publicly known policies defining what to + grant by the Data Consumer to enable the Data Provider. +end note + +rnote across + The Data Consumer wants exchange data with a yet foreign Data Provider. +end note +rnote across + Hence, the Data Consumer creates a permission for the Data Provider + containing all grants and information needed. +end note +rnote across + The example requested demanding the preparing grant is: + GETcatalog + And data consumer wants to issue that request against the data provider. +end note +rnote across + Self-issued: no external CA involved in ceation and/ or validation of exchanged tokens! +end note + +rnote across + IMPORTANT + This intpretation of to the concept for Verifiable Presentation Protocol (VPP) requires standard JWT for all self-issued tokens used. + + REMARK + I.e. custom tokens holding permissions are OMITTED +end note + +rnote across + +end note + +rnote across + EDC: Eclipse Dataspace Connector + STS: Secure Token Service + CS: Credential Service (e.g. MIW) +end note + +rnote across + +end note + +rnote across + The Data Provider uses that permission to obtain all information + needed to fulfill the future request of the Data Consumer. +end note + +rnote across + +end note + +== START == + + +== Data Consumer creates data access permission for Data Provider == + +note over EDC_Consumer, STS_Consumer + BPN, DID, scopes +end note + +EDC_Consumer -> STS_Consumer : Request for self-issued JWT + + +STS_Consumer ->> STS_Consumer : Self-issue JWT-Access-Token as PERMISSION +note right + Set these values: + \t iss = DID Consumer + \t sub = DID Provider + \t aud = DID Provider + \t jti = claim for security + \t exp = expiration date of token + \t scope = granted scopes/ permissions/ rights +end note + +STS_Consumer -> CS_Consumer : Sign JWT Access Token + +CS_Consumer ->> CS_Consumer : sign JWT Access Token +note right + private key of key pair of Consumer + determined by BPN/ DID +end note + +CS_Consumer --> STS_Consumer : Signed JWT Access Token + +STS_Consumer ->> STS_Consumer : Self-issue JWT ID Token as ENVELOPE +note right + Set these values: + \t iss = DID Consumer + \t sub = DID Consumer + \t aud = DID Provider + \t client_id = DID Consumer + \t jti = claim for security + \t exp = expiration date of token + \t access_token = signed JWT Access Token (PERMISSION) +end note + +STS_Consumer -> CS_Consumer : Sign JWT ID Token + +CS_Consumer ->> CS_Consumer : Return sign JWT ID Token +note right + private key of key pair + of Consumer determined by BPN/ DID +end note + +CS_Consumer --> STS_Consumer : Signed JWT ID Token + +STS_Consumer --> EDC_Consumer : Signed JWT ID Token + +== Data consumer issues request for target data, e.g GET catalog == + +EDC_Consumer -> EDC_Provider : GET catalog +note right + The request that is the reason to grant permissions in the first place. + ~~JWT as Authorization Header Bearer Scheme~~ +end note + + +== Data Provider processes permission request == + +EDC_Provider -> CS_Provider : Validate signed JWT ID Token + +CS_Provider ->> CS_Provider : Validate signature of JWT ID Token +note left +public key of key pair +of Consumer determined by BPN/ DID +end note + +CS_Provider --> EDC_Provider : Approval of signature + +EDC_Provider ->> EDC_Provider : Check values of JWT ID Token +note left + Check that these values are set: + \t iss = DID Consumer + \t sub = DID Consumer + \t aud = DID Provider + \t client_id = DID Consumer + \t jti = claim for security + \t exp = expiration date of token + + jti and exp need to be stored to prevent replay attacks (until exp runs out) +end note + +EDC_Provider ->> EDC_Provider: Extract JWT --ID-- Access Token from JWT ID Token + +EDC_Provider ->> EDC_Provider : Extract permission + +EDC_Provider ->> EDC_Provider: if consumer's permission is a signed JWT Access Token +note left + Check that these values are set: + \t iss = DID Consumer + \t sub = DID Consumer + \t aud = DID Provider + \t exp = expiration date of token + \t scope = granted scopes/ permissions/ rights + + Remark: scope must not be empty + +!!! Remark + Not suitable for custom permissions, + i.e. non-JWT-Access-Tokens +!!! +end note + +== Data provider prepares request to obtain VP from data consumer == + +EDC_Provider -> STS_Provider : request self-issued JWT ID Token as ENVELOPE + +STS_Provider ->> STS_Provider : self-issue JWT ID Token as ENVELOPE +note left + Set these values: + \t iss = DID Provider + \t sub = DID Provider + \t aud = DID Consumer + \t client_id = DID Provider + \t jti = claim for security + \t exp = expiration date of token + \t access_token = signed Consumer PERMISSION +end note + +STS_Provider -> CS_Provider : Request to sign JWT ID Token + +CS_Provider ->> CS_Provider : Sign JWT ID Token +note left + private key of key pair + of Provider determined by BPN/ DID +end note + +STS_Provider -> EDC_Provider : return self-issued JWT ID Token as ENVELOPE + +== Data provider issues request against data consumer for required target data == + +EDC_Provider -> CS_Consumer : Request for Verifiable Presentation (VP) with permission +note left + Request delivers JWT ID Token signed by data provider + with permission of data consumer +end note + + +== CS of data provider process request for target data with permission == + +CS_Consumer ->> CS_Consumer : validate signature of JWT ID Token +note right + public key of key pair + of Provider determined by BPN/ DID +end note + +CS_Consumer ->> CS_Consumer : Check values of JWT ID Token +note right + Check that these values are set: + \t iss = DID Provider + \t sub = DID Provider + \t aud = DID Consumer + \t client_id = DID Provider + \t jti = claim for security + \t exp = expiration date of token +end note + +CS_Consumer ->> CS_Consumer : Extract permission, here JWT Access Token + +CS_Consumer ->> CS_Consumer : Validate signature of JWT Access Token +note right + public key of key pair + of Consumer determined by BPN/ DID +end note + +CS_Consumer ->> CS_Consumer : If permission is a signed JWT Access Token +note right + Check that these values are set: + \t iss = DID Consumer + \t sub = DID Provider + \t aud = DID Provider + \t jti = claim for security + \t exp = expiration date of token + \t scope = granted scopes/ permissions/ rights + +!!! Remark + Not suitable for custom permissions, + i.e. non-JWT-Access-Tokens +!!! +end note + +CS_Consumer ->> CS_Consumer : Extract granted permissions from payload of \nJWT Access Token +note right + Permissions granted are contained in payload as + value of key: + \t scope = granted scopes/ permissions/ rights +end note + +CS_Consumer ->> CS_Consumer : Process data request using granted scope + + +== Data Consumer delivers target data to data provider == + +CS_Consumer --> EDC_Provider : Return target response with VP + + +== Provider validates VP == + + + +EDC_Provider -> CS_Provider : Validate VP +CS_Provider --> EDC_Provider + +note left +how does the edc get the policies / which VCs are needed? +end note + +== Data provider responses to Data consumers request == + +EDC_Provider --> EDC_Consumer : Catalog as requested + + +== END == +rnote across + DONE: + \t GET catalog successfully conducted. +end note diff --git a/docs/arc42/main.md b/docs/arc42/main.md index 010b8515e..a56720345 100644 --- a/docs/arc42/main.md +++ b/docs/arc42/main.md @@ -879,6 +879,35 @@ requirements where relevant and applicable: - CX-Credentials are not consistent - Only Summary Credential will be used because of the http header limition of 8KB +## Verifiable Presentation Protocol (VVP) + +The *Verifiable Presentation Protocol (VPP)* is designed to address the problem of resolving Verifiable Presentations +and other claims when they cannot be passed as part of a client request. +The *VPP* is represented +The *Data Consumer* wants exchange data with a yet *foreign* *Data Provider*. +Hence, the *Data Consumer* creates a *permission* for the *Data Provider* +containing all grants and information needed. +The *Data Consumer* wants exchange data with a yet *foreign* *Data Provider*. +Hence, the *Data Consumer* creates a *permission* for the *Data Provider* +containing all grants and information needed. + +REMARK: +*Self-issued:* no external CA involved in creation and/ or validation of exchanged tokens! + +### Secure Token Service (STS) +The *Secure Token Service* is supposed the supply the tokens required to realise the VVP. + +### Example Use Case Illustrated +The example requested demanding the preparing grant is: +*GET catalog* +And data consumer wants to issue that request against the data provider. + +Image: +![VPP Flow Diagram](images/VPP-Flow.png) + +Declaring file: +[VVP Flow Declaration](images/VVP-Flow.puml) + ## SSI Library - No validation for JsonWebSignature2020 with RSA key