summaryrefslogtreecommitdiff
path: root/doc/sphinx
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-08-19 14:43:39 +0200
committerChristian Grothoff <christian@grothoff.org>2021-08-19 14:43:39 +0200
commit677c7e87a5da584e68194c9cca19a91191c3140c (patch)
tree33425fd28b6580c29d2f5fd80ab7241a5a643f13 /doc/sphinx
parent4067891ed9f66eb5e47a709d3ea21c2ed36a1e86 (diff)
downloadanastasis-677c7e87a5da584e68194c9cca19a91191c3140c.tar.gz
anastasis-677c7e87a5da584e68194c9cca19a91191c3140c.tar.bz2
anastasis-677c7e87a5da584e68194c9cca19a91191c3140c.zip
-implement 'poll' transition in state machine
Diffstat (limited to 'doc/sphinx')
-rw-r--r--doc/sphinx/reducer.rst228
1 files changed, 129 insertions, 99 deletions
diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst
index e5f1699..68df5b1 100644
--- a/doc/sphinx/reducer.rst
+++ b/doc/sphinx/reducer.rst
@@ -1459,121 +1459,139 @@ that applications must all handle. States other than ``solved`` are:
}
}
- - **body**: Here, the server provided an HTTP reply for
- how to solve the challenge, but the reducer could not parse
- them into a known format. A mime-type may be provided and may
- help parse the details.
+ - **body**: Here, the server provided an HTTP reply for
+ how to solve the challenge, but the reducer could not parse
+ them into a known format. A mime-type may be provided and may
+ help parse the details.
- .. code-block:: json
+ .. code-block:: json
- {
- "recovery_state": "CHALLENGE_SOLVING",
- "recovery_information": {
- "...": "..."
- }
- "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
- "challenge_feedback": {
- "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "body",
- "body": "CROCKFORDBASE32ENCODEDBODY",
- "http_status": 403,
- "mime_type" : "anything/possible"
- }
- }
- }
+ {
+ "recovery_state": "CHALLENGE_SOLVING",
+ "recovery_information": {
+ "...": "..."
+ }
+ "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "challenge_feedback": {
+ "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+ "state": "body",
+ "body": "CROCKFORDBASE32ENCODEDBODY",
+ "http_status": 403,
+ "mime_type" : "anything/possible"
+ }
+ }
+ }
- - **hint**: Here, the server provided human-readable hint for
- how to solve the challenge. Note that the ``hint`` provided this
- time is from the Anastasis provider and may differ from the ``instructions``
- for the challenge under ``recovery_information``:
+ - **hint**: Here, the server provided human-readable hint for
+ how to solve the challenge. Note that the ``hint`` provided this
+ time is from the Anastasis provider and may differ from the ``instructions``
+ for the challenge under ``recovery_information``:
- .. code-block:: json
+ .. code-block:: json
- {
- "recovery_state": "CHALLENGE_SOLVING",
- "recovery_information": {
- "...": "..."
- }
- "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
- "challenge_feedback": {
- "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "hint",
- "hint": "Recovery TAN send to email mail@DOMAIN",
- "http_status": 403
- }
+ {
+ "recovery_state": "CHALLENGE_SOLVING",
+ "recovery_information": {
+ "...": "..."
+ }
+ "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "challenge_feedback": {
+ "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+ "state": "hint",
+ "hint": "Recovery TAN send to email mail@DOMAIN",
+ "http_status": 403
+ }
+ }
+ }
+
+ - **details**: Here, the server provided a detailed JSON status response
+ related to solving the challenge:
+
+ .. code-block:: json
+
+ {
+ "recovery_state": "CHALLENGE_SOLVING",
+ "recovery_information": {
+ "...": "..."
+ }
+ "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "challenge_feedback": {
+ "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+ "state": "details",
+ "details": {
+ "code": 8111,
+ "hint": "The client's response to the challenge was invalid.",
+ "detail" : null
+ },
+ "http_status": 403
}
}
+ }
- - **details**: Here, the server provided a detailed JSON status response
- related to solving the challenge:
+ - **redirect**: To solve the challenge, the user must visit the indicated
+ Web site at ``redirect_url``, for example to perform video authentication:
- .. code-block:: json
+ .. code-block:: json
- {
- "recovery_state": "CHALLENGE_SOLVING",
- "recovery_information": {
- "...": "..."
- }
- "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
- "challenge_feedback": {
- "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "details",
- "details": {
- "code": 8111,
- "hint": "The client's response to the challenge was invalid.",
- "detail" : null
- },
- "http_status": 403
- }
+ {
+ "recovery_state": "CHALLENGE_SOLVING",
+ "recovery_information": {
+ "...": "..."
+ }
+ "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "challenge_feedback": {
+ "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+ "state": "redirect",
+ "redirect_url": "https://videoconf.example.com/",
+ "http_status": 303
}
}
+ }
- - **redirect**: To solve the challenge, the user must visit the indicated
- Web site at ``redirect_url``, for example to perform video authentication:
+ - **server-failure**: This indicates that the Anastasis provider encountered
+ a failure and recovery using this challenge cannot proceed at this time.
+ Examples for failures might be that the provider is unable to send SMS
+ messages at this time due to an outage. The body includes details about
+ the failure. The user may try again later or continue with other challenges.
- .. code-block:: json
+ .. code-block:: json
- {
- "recovery_state": "CHALLENGE_SOLVING",
- "recovery_information": {
- "...": "..."
- }
- "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
- "challenge_feedback": {
- "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "redirect",
- "redirect_url": "https://videoconf.example.com/",
- "http_status": 303
- }
- }
+ {
+ "recovery_state": "CHALLENGE_SELECTING",
+ "recovery_information": {
+ "...": "..."
}
+ "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "challenge_feedback": {
+ "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+ "state": "server-failure",
+ "http_status": "500",
+ "error_code": 52
+ }
+ }
+ }
- - **server-failure**: This indicates that the Anastasis provider encountered
- a failure and recovery using this challenge cannot proceed at this time.
- Examples for failures might be that the provider is unable to send SMS
- messages at this time due to an outage. The body includes details about
- the failure. The user may try again later or continue with other challenges.
+ - **truth-unknown**: This indicates that the Anastasis provider is unaware of
+ the specified challenge. This is typically a permanent failure, and user
+ interfaces should not allow users to re-try this challenge.
.. code-block:: json
- {
- "recovery_state": "CHALLENGE_SELECTING",
- "recovery_information": {
- "...": "..."
- }
- "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
- "challenge_feedback": {
- "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "server-failure",
- "http_status": "500",
- "error_code": 52
- }
- }
- }
+ {
+ "recovery_state": "CHALLENGE_SELECTING",
+ "recovery_information": {
+ "...": "..."
+ }
+ "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "challenge_feedback": {
+ "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+ "state": "truth-unknown",
+ "error_code": 8108
+ }
+ }
+ }
- - **truth-unknown**: This indicates that the Anastasis provider is unaware of
- the specified challenge. This is typically a permanent failure, and user
- interfaces should not allow users to re-try this challenge.
+ - **rate-limit-exceeded**:
.. code-block:: json
@@ -1585,13 +1603,13 @@ that applications must all handle. States other than ``solved`` are:
"selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
"challenge_feedback": {
"TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "truth-unknown",
- "error_code": 8108
+ "state": "rate-limit-exceeded",
+ "error_code": 8121
}
}
}
- - **rate-limit-exceeded**:
+ - **authentication-timeout**:
.. code-block:: json
@@ -1603,12 +1621,24 @@ that applications must all handle. States other than ``solved`` are:
"selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
"challenge_feedback": {
"TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
- "state": "rate-limit-exceeded",
- "error_code": 8121
+ "state": "authentication-timeout",
+ "error_code": 8122
}
}
}
+
+**poll:**
+
+With a ``poll`` transition, the application indicates that it wants to wait longer for one or more of the challenges that are in state ``authentication-timeout`` to possibly complete. While technically optional, the ``timeout`` argument should really be provided to enable long-polling, for example:
+
+.. code-block:: json
+
+ {
+ "timeout" : { "d_ms" : 5000 },
+ }
+
+
**pay:**
With a ``pay`` transition, the application indicates to the reducer that