Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Status Attestation Responses #221

Merged
merged 3 commits into from
Mar 4, 2024
Merged

Status Attestation Responses #221

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4d1e5e8
refactor
balanza Mar 1, 2024
8fbe8e4
remove line
balanza Mar 1, 2024
fdd6d6f
clarify error code meaning
balanza Mar 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 87 additions & 50 deletions docs/en/revocation-lists.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,42 +200,65 @@ The Revocation Endpoint MUST be provided by the Issuer within its Metadata.
Credential Revocation HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The response MUST be an HTTP Response using the status code set to *204 (No-Content)* in the case of successful revocation. If the Digital Credential could not be found by the Issuer, an HTTP Response with status code *404 (Not Found)* MUST be returned. Otherwise an HTTP error response MUST be provided by the Issuer to the Wallet Instance. This response MUST use *application/json* as the content type and MUST include the following parameters:
In case of successful revocation, the Issuer MUST return an HTTP Response with status code *204 No Content*.
Otherwise, an HTTP error response MUST be provided by the Issuer using status codes according to the table below.

- *error*. The error code.
- *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered.

Below a non-normative example of an HTTP Response with an error.

.. code::
To revoke an already revoked Digital Credential will result in a successful response.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error": "invalid_request"
"error_description": "The signature of credential_pop JWT is not valid"
}

The following HTTP Status Codes and Error Codes MUST be supported:
The following HTTP Status Codes MUST be supported:

.. list-table::
:widths: 20 20 60
:header-rows: 1

* - **Status Code**
- **Error Code**
- **Body**
- **Description**
* - *204 No Content*
-
- The Digital Credential has been successfully revoked.
* - *400 Bad Request*
- *invalid_request*
- The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`).
- Error code and description
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this intended to be here?

if yes, why it is not in the similar errors below?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand this comment.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, maybe I understood what you meant.

The response body is required only for the cases in which it effectively adds information for the user. That is, there's no value in sending "server error" as a payload to a 500 Server Error response.

Also, 5xx errors are not always handled by the application but rather by gateways and proxies, so it may be impractical to customize them. As it brings no value, I'd rather not consider the body.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @balanza , the only status code that makes sense to include a body in is the 400 Bad Request status code. Having said that, probably we could remove the body column saying that only the 400 (Bad Request) status Code MUST include a body encoded in application/json format and MUST contain the following parameters: [...].

@peppelinux WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, since we have server_error in RFC 6749
https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes but here probably we can omit it as in the RFC6749 I read:

(This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.)

Am I missing something?
Anyway, if we don't reach a consensus now, I suggest to put this PR to the next release if you agree.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can add the error payload if we feel it's worth it, it doesn't affect the way the communication works.

Let me just point out that:

  • RFC6749 does not design the endpoint to use multiple http codes as error, that's why it needs to differentiate by payload
  • In RFC6749, the http response's content type is application/x-www-form-urlencoded, we are using application/json
  • 5xx will usually be generated by systems other than the resource server (ex: load balancers, api gateways, firewalls, etc), so it's probable we will have payload not in the expected format.

- The issuer cannot fulfill the request because of invalid parameters.
* - *404 Not Found*
-
- The Digital Credential to be revoked can not be found by the Issuer.
* - *500 Internal Server Error*
- *server_error*
-
- The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`).
* - *503 Service Unavailable*
- *temporarily_unavailable*
-
- The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`).

For HTTP error responses that involve a body, the body MUST be encoded in ``application/json`` format and MUST contain the following parameters:

- *error*. The error code, as registerd in the table below.
- *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered.

The following Error Codes MUST be supported:

.. list-table::
:widths: 20 80
:header-rows: 1

* - **Error Code**
- **Description**
* - ``invalid_request``
- The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`).


Below a non-normative example of an HTTP Response with an error.

.. code::

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error": "invalid_request"
"error_description": "The signature of credential_pop JWT is not valid"
}



Status Attestation Flows
Expand Down Expand Up @@ -313,7 +336,7 @@ A non-normative example of Credential Proof of Possession is provided :ref:`in t

.. code::

HTTP/1.1 201 OK
HTTP/1.1 201 Created
Content-Type: application/json

{
Expand Down Expand Up @@ -345,7 +368,7 @@ The *Credential status endpoint* MUST be provided by the Issuers within their Me
Status Attestation HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The *Credential status endpoint* MUST return a response with a *HTTP status code 201 OK* if the Credential is valid at the time of the request. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims.
The *Credential status endpoint* MUST return a HTTP response with status code *201 Created* if the Credential is valid at the time of the request. The responses MUST be encoded in ``application/json`` format. It MUST contain the following mandatory claims.

.. _table_http_response_claim:
.. list-table::
Expand All @@ -359,48 +382,62 @@ The *Credential status endpoint* MUST return a response with a *HTTP status code
- It MUST contain the Status Attestation as a signed JWT.
- `[OAuth Status Attestation draft 01] <https://datatracker.ietf.org/doc/draft-demarco-status-attestations/01/>`_.

If the Digital Credential could not be found by the Issuer, an HTTP Response with status code 404 (Not Found) MUST be returned. In all other cases the Issuer MUST return an HTTP Response Error using *application/json* as the content type, and including the following parameters:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why it was removed?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is simply moved below, @balanza is it right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Details on every possible response have been moved in the response table: https://github.com/italia/eudi-wallet-it-docs/pull/221/files/fdd6d6fa93100f45a71fbab1dc082a5f85c176fa#diff-d3bfad4aa613161f55b96d232893081a0ac30d5127aca04dda54925b43aceb1eR401

Rationale: it gives the same information in a structured way, using fewer words. Implementers may like it.


- *error*. The error code.
- *error_description*. Text in human-readable form that offers more details to clarify the nature of the error encountered (for instance, changes in some attributes, reasons for revocation, other).

Below a non-normative example of an HTTP Response with an error.

.. code::

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error": "invalid_request"
"error_description": "The signature of credential_pop JWT is not valid"
}

The following HTTP Status Codes and Error Codes MUST be supported:
The following HTTP Status Codes MUST be supported:

.. list-table::
:widths: 20 20 60
:header-rows: 1

* - **Status Code**
- **Error Code**
- **Body**
- **Description**
* - *201 Created*
- Status Attestation response
- The Status Attestation has been successfully created and it has been returned.
* - *400 Bad Request*
- *invalid_request*
- The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`).
- Error code and description
- The issuer cannot fulfill the request because of invalid parameters.
* - *404 Not Found*
-
- The Digital Credential can not be found by the Issuer.
* - *500 Internal Server Error*
- *server_error*
-
Comment on lines -392 to +403
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is RFC6749

https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1

- The Issuer encountered an internal problem. (:rfc:`6749#section-5.2`).
* - *503 Service Unavailable*
- *temporarily_unavailable*
-
- The Issuer is temporary unavailable. (:rfc:`6749#section-5.2`).
* - *400 Bad Request*
- *credential_revoked*

For HTTP error responses that involve a body, the body MUST be encoded in ``application/json`` format and MUST contain the following parameters:

- *error*. The error code, as registerd in the table below.
- *error_description*. Text in human-readable form providing further details to clarify the nature of the error encountered.

The following Error Codes MUST be supported:

.. list-table::
:widths: 20 80
:header-rows: 1

* - **Error Code**
- **Description**
* - ``invalid_request``
- The request is not valid due to the lack or incorrectness of one or more parameters. (:rfc:`6749#section-5.2`).
* - ``credential_revoked``
- The Digital Credential is revoked. The reason of revocation MUST be provided in the *error_description* field.
* - *400 Bad Request*
- *credential_updated*
* - ``credential_updated``
- One or more attributes contained in the Digital Credential are changed. The *error_description* field MUST contain a list of updated attributes.

Below a non-normative example of an HTTP Response with an error.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

duplicated: https://github.com/italia/eudi-wallet-it-docs/pull/221/files#diff-d3bfad4aa613161f55b96d232893081a0ac30d5127aca04dda54925b43aceb1eR250

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are the same snippets but they apply to different endpoints.

I think it's ok to have examples when you expect them, even if they are duplicated

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can approve and merge as it is

in the future we'll try to make some editorials to make the text shorter and use more references


.. code::

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
"error": "invalid_request"
"error_description": "The signature of credential_pop JWT is not valid"
}

.. _sec_revocation_nra_presentation:

Expand Down
Loading