diff options
Diffstat (limited to 'doc/sphinx/reducer.rst')
-rw-r--r-- | doc/sphinx/reducer.rst | 228 |
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: | |||
1459 | } | 1459 | } |
1460 | } | 1460 | } |
1461 | 1461 | ||
1462 | - **body**: Here, the server provided an HTTP reply for | 1462 | - **body**: Here, the server provided an HTTP reply for |
1463 | how to solve the challenge, but the reducer could not parse | 1463 | how to solve the challenge, but the reducer could not parse |
1464 | them into a known format. A mime-type may be provided and may | 1464 | them into a known format. A mime-type may be provided and may |
1465 | help parse the details. | 1465 | help parse the details. |
1466 | 1466 | ||
1467 | .. code-block:: json | 1467 | .. code-block:: json |
1468 | 1468 | ||
1469 | { | 1469 | { |
1470 | "recovery_state": "CHALLENGE_SOLVING", | 1470 | "recovery_state": "CHALLENGE_SOLVING", |
1471 | "recovery_information": { | 1471 | "recovery_information": { |
1472 | "...": "..." | 1472 | "...": "..." |
1473 | } | 1473 | } |
1474 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | 1474 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", |
1475 | "challenge_feedback": { | 1475 | "challenge_feedback": { |
1476 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | 1476 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { |
1477 | "state": "body", | 1477 | "state": "body", |
1478 | "body": "CROCKFORDBASE32ENCODEDBODY", | 1478 | "body": "CROCKFORDBASE32ENCODEDBODY", |
1479 | "http_status": 403, | 1479 | "http_status": 403, |
1480 | "mime_type" : "anything/possible" | 1480 | "mime_type" : "anything/possible" |
1481 | } | 1481 | } |
1482 | } | 1482 | } |
1483 | } | 1483 | } |
1484 | 1484 | ||
1485 | - **hint**: Here, the server provided human-readable hint for | 1485 | - **hint**: Here, the server provided human-readable hint for |
1486 | how to solve the challenge. Note that the ``hint`` provided this | 1486 | how to solve the challenge. Note that the ``hint`` provided this |
1487 | time is from the Anastasis provider and may differ from the ``instructions`` | 1487 | time is from the Anastasis provider and may differ from the ``instructions`` |
1488 | for the challenge under ``recovery_information``: | 1488 | for the challenge under ``recovery_information``: |
1489 | 1489 | ||
1490 | .. code-block:: json | 1490 | .. code-block:: json |
1491 | 1491 | ||
1492 | { | 1492 | { |
1493 | "recovery_state": "CHALLENGE_SOLVING", | 1493 | "recovery_state": "CHALLENGE_SOLVING", |
1494 | "recovery_information": { | 1494 | "recovery_information": { |
1495 | "...": "..." | 1495 | "...": "..." |
1496 | } | 1496 | } |
1497 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | 1497 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", |
1498 | "challenge_feedback": { | 1498 | "challenge_feedback": { |
1499 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | 1499 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { |
1500 | "state": "hint", | 1500 | "state": "hint", |
1501 | "hint": "Recovery TAN send to email mail@DOMAIN", | 1501 | "hint": "Recovery TAN send to email mail@DOMAIN", |
1502 | "http_status": 403 | 1502 | "http_status": 403 |
1503 | } | 1503 | } |
1504 | } | ||
1505 | } | ||
1506 | |||
1507 | - **details**: Here, the server provided a detailed JSON status response | ||
1508 | related to solving the challenge: | ||
1509 | |||
1510 | .. code-block:: json | ||
1511 | |||
1512 | { | ||
1513 | "recovery_state": "CHALLENGE_SOLVING", | ||
1514 | "recovery_information": { | ||
1515 | "...": "..." | ||
1516 | } | ||
1517 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | ||
1518 | "challenge_feedback": { | ||
1519 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | ||
1520 | "state": "details", | ||
1521 | "details": { | ||
1522 | "code": 8111, | ||
1523 | "hint": "The client's response to the challenge was invalid.", | ||
1524 | "detail" : null | ||
1525 | }, | ||
1526 | "http_status": 403 | ||
1504 | } | 1527 | } |
1505 | } | 1528 | } |
1529 | } | ||
1506 | 1530 | ||
1507 | - **details**: Here, the server provided a detailed JSON status response | 1531 | - **redirect**: To solve the challenge, the user must visit the indicated |
1508 | related to solving the challenge: | 1532 | Web site at ``redirect_url``, for example to perform video authentication: |
1509 | 1533 | ||
1510 | .. code-block:: json | 1534 | .. code-block:: json |
1511 | 1535 | ||
1512 | { | 1536 | { |
1513 | "recovery_state": "CHALLENGE_SOLVING", | 1537 | "recovery_state": "CHALLENGE_SOLVING", |
1514 | "recovery_information": { | 1538 | "recovery_information": { |
1515 | "...": "..." | 1539 | "...": "..." |
1516 | } | 1540 | } |
1517 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | 1541 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", |
1518 | "challenge_feedback": { | 1542 | "challenge_feedback": { |
1519 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | 1543 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { |
1520 | "state": "details", | 1544 | "state": "redirect", |
1521 | "details": { | 1545 | "redirect_url": "https://videoconf.example.com/", |
1522 | "code": 8111, | 1546 | "http_status": 303 |
1523 | "hint": "The client's response to the challenge was invalid.", | ||
1524 | "detail" : null | ||
1525 | }, | ||
1526 | "http_status": 403 | ||
1527 | } | ||
1528 | } | 1547 | } |
1529 | } | 1548 | } |
1549 | } | ||
1530 | 1550 | ||
1531 | - **redirect**: To solve the challenge, the user must visit the indicated | 1551 | - **server-failure**: This indicates that the Anastasis provider encountered |
1532 | Web site at ``redirect_url``, for example to perform video authentication: | 1552 | a failure and recovery using this challenge cannot proceed at this time. |
1553 | Examples for failures might be that the provider is unable to send SMS | ||
1554 | messages at this time due to an outage. The body includes details about | ||
1555 | the failure. The user may try again later or continue with other challenges. | ||
1533 | 1556 | ||
1534 | .. code-block:: json | 1557 | .. code-block:: json |
1535 | 1558 | ||
1536 | { | 1559 | { |
1537 | "recovery_state": "CHALLENGE_SOLVING", | 1560 | "recovery_state": "CHALLENGE_SELECTING", |
1538 | "recovery_information": { | 1561 | "recovery_information": { |
1539 | "...": "..." | 1562 | "...": "..." |
1540 | } | ||
1541 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | ||
1542 | "challenge_feedback": { | ||
1543 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | ||
1544 | "state": "redirect", | ||
1545 | "redirect_url": "https://videoconf.example.com/", | ||
1546 | "http_status": 303 | ||
1547 | } | ||
1548 | } | ||
1549 | } | 1563 | } |
1564 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | ||
1565 | "challenge_feedback": { | ||
1566 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | ||
1567 | "state": "server-failure", | ||
1568 | "http_status": "500", | ||
1569 | "error_code": 52 | ||
1570 | } | ||
1571 | } | ||
1572 | } | ||
1550 | 1573 | ||
1551 | - **server-failure**: This indicates that the Anastasis provider encountered | 1574 | - **truth-unknown**: This indicates that the Anastasis provider is unaware of |
1552 | a failure and recovery using this challenge cannot proceed at this time. | 1575 | the specified challenge. This is typically a permanent failure, and user |
1553 | Examples for failures might be that the provider is unable to send SMS | 1576 | interfaces should not allow users to re-try this challenge. |
1554 | messages at this time due to an outage. The body includes details about | ||
1555 | the failure. The user may try again later or continue with other challenges. | ||
1556 | 1577 | ||
1557 | .. code-block:: json | 1578 | .. code-block:: json |
1558 | 1579 | ||
1559 | { | 1580 | { |
1560 | "recovery_state": "CHALLENGE_SELECTING", | 1581 | "recovery_state": "CHALLENGE_SELECTING", |
1561 | "recovery_information": { | 1582 | "recovery_information": { |
1562 | "...": "..." | 1583 | "...": "..." |
1563 | } | 1584 | } |
1564 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | 1585 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", |
1565 | "challenge_feedback": { | 1586 | "challenge_feedback": { |
1566 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | 1587 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { |
1567 | "state": "server-failure", | 1588 | "state": "truth-unknown", |
1568 | "http_status": "500", | 1589 | "error_code": 8108 |
1569 | "error_code": 52 | 1590 | } |
1570 | } | 1591 | } |
1571 | } | 1592 | } |
1572 | } | ||
1573 | 1593 | ||
1574 | - **truth-unknown**: This indicates that the Anastasis provider is unaware of | 1594 | - **rate-limit-exceeded**: |
1575 | the specified challenge. This is typically a permanent failure, and user | ||
1576 | interfaces should not allow users to re-try this challenge. | ||
1577 | 1595 | ||
1578 | .. code-block:: json | 1596 | .. code-block:: json |
1579 | 1597 | ||
@@ -1585,13 +1603,13 @@ that applications must all handle. States other than ``solved`` are: | |||
1585 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | 1603 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", |
1586 | "challenge_feedback": { | 1604 | "challenge_feedback": { |
1587 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | 1605 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { |
1588 | "state": "truth-unknown", | 1606 | "state": "rate-limit-exceeded", |
1589 | "error_code": 8108 | 1607 | "error_code": 8121 |
1590 | } | 1608 | } |
1591 | } | 1609 | } |
1592 | } | 1610 | } |
1593 | 1611 | ||
1594 | - **rate-limit-exceeded**: | 1612 | - **authentication-timeout**: |
1595 | 1613 | ||
1596 | .. code-block:: json | 1614 | .. code-block:: json |
1597 | 1615 | ||
@@ -1603,12 +1621,24 @@ that applications must all handle. States other than ``solved`` are: | |||
1603 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", | 1621 | "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", |
1604 | "challenge_feedback": { | 1622 | "challenge_feedback": { |
1605 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { | 1623 | "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { |
1606 | "state": "rate-limit-exceeded", | 1624 | "state": "authentication-timeout", |
1607 | "error_code": 8121 | 1625 | "error_code": 8122 |
1608 | } | 1626 | } |
1609 | } | 1627 | } |
1610 | } | 1628 | } |
1611 | 1629 | ||
1630 | |||
1631 | **poll:** | ||
1632 | |||
1633 | 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: | ||
1634 | |||
1635 | .. code-block:: json | ||
1636 | |||
1637 | { | ||
1638 | "timeout" : { "d_ms" : 5000 }, | ||
1639 | } | ||
1640 | |||
1641 | |||
1612 | **pay:** | 1642 | **pay:** |
1613 | 1643 | ||
1614 | With a ``pay`` transition, the application indicates to the reducer that | 1644 | With a ``pay`` transition, the application indicates to the reducer that |