From 494f0a2927a7c6766730a6b4f18c8d28daa15131 Mon Sep 17 00:00:00 2001 From: Patrick St-Louis <43082425+PatStLouis@users.noreply.github.com> Date: Tue, 18 Jun 2024 15:22:20 -0400 Subject: [PATCH] Add error handling section. Co-authored-by: Ted Thibodeau Jr Co-authored-by: Manu Sporny --- holder.yml | 40 ----------------------------------- index.html | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++ issuer.yml | 4 ---- verifier.yml | 6 ------ 4 files changed, 60 insertions(+), 50 deletions(-) diff --git a/holder.yml b/holder.yml index fb2af65..36aba68 100644 --- a/holder.yml +++ b/holder.yml @@ -45,10 +45,6 @@ paths: description: Gone! There is no data here "418": description: I'm a teapot - MUST not be returned outside of pre-arranged scenarios between both parties - "500": - description: Internal Error - "501": - description: Not Implemented delete: tags: - Credentials @@ -72,10 +68,6 @@ paths: description: Credential not found "410": description: Gone! There is no data here - "500": - description: Internal Error - "501": - description: Not Implemented /credentials: get: tags: @@ -113,10 +105,6 @@ paths: description: Not Authorized "410": description: Gone! There is no data here - "500": - description: Internal Error - "501": - description: Not Implemented /credentials/derive: post: tags: @@ -144,10 +132,6 @@ paths: $ref: "#/components/schemas/DeriveCredentialResponse" "400": description: Invalid Request - "500": - description: Internal Error - "501": - description: Not Implemented /presentations/{id}: get: @@ -179,10 +163,6 @@ paths: description: Presentation not found "410": description: Gone! There is no data here - "500": - description: Internal Error - "501": - description: Not Implemented delete: tags: - Presentations @@ -206,10 +186,6 @@ paths: description: Presentation not found "410": description: Gone! There is no data here - "500": - description: Internal Error - "501": - description: Not Implemented /presentations: get: tags: @@ -247,10 +223,6 @@ paths: description: Not Authorized "410": description: Gone! There is no data here - "500": - description: Internal Error - "501": - description: Not Implemented post: summary: Creates a presentation and returns it in the response body. tags: @@ -277,8 +249,6 @@ paths: $ref: "#/components/schemas/CreatePresentationResponse" "400": description: invalid input! - "500": - description: error! /exchanges: get: summary: Provides a discovery endpoint for the exchanges supported by this server endpoint. @@ -385,8 +355,6 @@ paths: } "400": description: invalid input - "500" : - description: error /exchanges/{exchange-id}: post: @@ -434,10 +402,6 @@ paths: application/json: schema: $ref: "#/components/schemas/ErrorResponse" - "501": - description: Service not implemented. - "500": - description: Internal server error. /exchanges/{exchange-id}/{transaction-id}: post: summary: Receives information related to an existing exchange. @@ -480,10 +444,6 @@ paths: $ref: "#/components/schemas/ErrorResponse" "404": description: The associated exchange or transaction was not found. - "500": - description: Internal server error. - "501": - description: Service not implemented. components: securitySchemes: diff --git a/index.html b/index.html index 6bda6d0..32f7dbc 100644 --- a/index.html +++ b/index.html @@ -464,6 +464,7 @@

Storage Services

(Verifier) • Storage Service (Holder)

+

Workflow Service

@@ -1233,6 +1234,65 @@

Exchange Examples

+
+

Error Handling

+

+ Error handling and messaging in the VC-API aligns with Problem Details for HTTP APIs [[RFC9457]]. + Implementers SHOULD include a status and a title in the error response body + relating to the specifics of the endpoint on which the error occurs. +

+

+ Aligning on error handling and messaging will greatly improve test-suites accuracy + when identifying technical friction impacting interoperability. +

+

+ Leveraging other fields such as detail, instance and type is encouraged, + to provide more contextual feedback about the error, + while being conscious of security concerns and hence not disclosing sensitive information. +

+

+ Implementers should handle all server errors to the best of their capabilities. + Endpoints should avoid returning improperly handled 500 errors in production + environments, as these may lead to information disclosure. +

+

Relationship between verification, validation and error handling

+

+ It is recommended to avoid raising errors while performing verification, + and instead gather ProblemDetails objects to include in the verification results. +

+

Types of ProblemDetails

+ An implementer can refer to the [[VC-DATA-MODEL-2.0]] and the [[VC-BITSTRING-STATUS-LIST]] for currently defined ProblemDetails types. + 
+          {
+            "type": "https://www.w3.org/TR/vc-data-model#CRYPTOGRAPHIC_SECURITY_ERROR",
+            "status": 400,
+            "title": "CRYPTOGRAPHIC_SECURITY_ERROR",
+            "detail": "The cryptographic security mechanism couldn't be verified. This is likely due to a malformed proof or an invalid verificationMethod."
+          }
+
+

Verification Response

+
Errors and Warnings
+ Errors are `ProblemDetails` relating to cryptography, data model and malformed context. + Warnings are `ProblemDetails` relating to statuses and validity periods. + + The `VerificationResponse` object MUST have the `verified` value set to `false` if an error is included. + The `VerificationResponse` object MUST have the `verified` value set to `true` if no errors are included. + + 
+          {
+            "verified": false,
+            "document": verifiableCredential,
+            "mediaType": "application/vc",
+            "controller": issuer,
+            "controllerDocument": didDocument,
+            "warnings": [ProblemDetails],
+            "errors": [ProblemDetails]
+          }
+
+
+
diff --git a/issuer.yml b/issuer.yml index 53846a8..27d7eef 100644 --- a/issuer.yml +++ b/issuer.yml @@ -43,8 +43,6 @@ paths: The request could not be processed due to one of the following reasons: - The provided value of 'issuer' does not match the expected configuration. - Another condition that results in a Bad Request. - "500": - description: error! /credentials/status: post: summary: Updates the status of an issued credential @@ -70,8 +68,6 @@ paths: description: Bad Request "404": description: Credential not found - "500": - description: Internal Server Error components: securitySchemes: $ref: "./components/SecuritySchemes.yml#/components/securitySchemes" diff --git a/verifier.yml b/verifier.yml index 395858e..e5c1eed 100644 --- a/verifier.yml +++ b/verifier.yml @@ -40,8 +40,6 @@ paths: $ref: "#/components/schemas/VerifyCredentialResponse" "400": description: invalid input! - "500": - description: error! /presentations/verify: post: summary: Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body. @@ -75,8 +73,6 @@ paths: description: Payload too large "429": description: Request rate limit exceeded. - "500": - description: Internal Server Error /challenges: post: summary: Passing an empty body to this endpoint creates and returns a challenge string in the response body. @@ -96,8 +92,6 @@ paths: $ref: "#/components/schemas/CreateChallengeResponse" "400": description: Invalid or malformed input - "500": - description: Internal server error components: securitySchemes: $ref: "./components/SecuritySchemes.yml#/components/securitySchemes"