diff options
Diffstat (limited to 'anastasis.rst')
| -rw-r--r-- | anastasis.rst | 237 |
1 files changed, 119 insertions, 118 deletions
diff --git a/anastasis.rst b/anastasis.rst index 4cd1e129..9e78ee2d 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -101,7 +101,7 @@ compute the account key pair. The public account key is Crockford base32-encoded in the URI to identify the account, and used to sign requests. These signatures are also provided in base32-encoding and transmitted using the HTTP header -"Anastasis-Account-Signature". +``Anastasis-Account-Signature``. When confidential data is uploaded to an Anastasis server, the respective payload is encrypted using AES-GCM with a symmetric key and initialization @@ -165,7 +165,7 @@ Verification For users to authorize "policy" operations we need an EdDSA key pair. As we cannot assure that the corresponding private key is truly secret, such policy operations must never be destructive: Should an adversary learn the private -key, they could access (and with the **kdf_id** decrypt) the user's policy (but +key, they could access (and with the **kdf_id**, decrypt) the user's policy (but not the core secret), or upload a new version of the **encrypted recovery document** (but not delete an existing version). @@ -189,11 +189,11 @@ HKDF to ensure that the result differs from other cases where we hash **key_size**: Size of the output, here 32 bytes. -**ver_secret**: Derived key from the kdf_id, serves as intermediate step for the generation of the private key. +**ver_secret**: Derived key from the ``kdf_id``, serves as intermediate step for the generation of the private key. -**eddsa_d_to_a()**: Function which converts the ver_key to a valid EdDSA private key. Specifically, assuming the value eddsa_priv is in a 32-byte array "digest", the function clears and sets certain bits as follows: +**eddsa_d_to_a()**: Function which converts the ver_key to a valid EdDSA private key. Specifically, assuming the value ``eddsa_priv`` is in a 32-byte array "digest", the function clears and sets certain bits as follows: -.. code-block:: none +.. code-block:: c digest[0] = (digest[0] & 0x7f) | 0x40; digest[31] &= 0xf8; @@ -209,7 +209,7 @@ Encryption For symmetric encryption of data we use AES256-GCM. For this we need a symmetric key and an initialization vector (IV). To ensure that the symmetric key changes for each encryption operation, we compute the -key material using an HKDF over a nonce and the kdf_id. +key material using an HKDF over a ``nonce`` and the ``kdf_id``. .. code-block:: none @@ -249,14 +249,14 @@ From this the symmetric key is computed as described above. We use AES256-GCM for the encryption of the **recovery document** and the **key_share**. To ensure that the key derivation for the encryption of the **recovery document** differs fundamentally from that of an -individual **key share**, we use different salts ("erd" and "eks" respectively). +individual **key share**, we use different salts ("erd" and "eks", respectively). .. code-block:: none - (iv0, key0) = HKDF(key_id, nonce0, "erd", keysize + ivsize) - (encrypted_recovery_document, aes_gcm_tag) = AES256_GCM(recovery_document, key0, iv0) - (iv_i, key_i) = HKDF(key_id, nonce_i, "eks", [optional data], keysize + ivsize) - (encrypted_key_share_i, aes_gcm_tag_i) = AES256_GCM(key_share_i, key_i, iv_i) + (iv0, key0) := HKDF(key_id, nonce0, "erd", keysize + ivsize) + (encrypted_recovery_document, aes_gcm_tag) := AES256_GCM(recovery_document, key0, iv0) + (iv_i, key_i) := HKDF(key_id, nonce_i, "eks", [optional data], keysize + ivsize) + (encrypted_key_share_i, aes_gcm_tag_i) := AES256_GCM(key_share_i, key_i, iv_i) **encrypted_recovery_document**: The encrypted **recovery document** which contains the escrow methods, policies and the encrypted **core secret**. @@ -280,18 +280,18 @@ inaccessible to those who do not have the answer: .. code-block:: none - powh = POW_HASH (qsalt, answer) - ekss = HKDF("Anastasis-secure-question-uuid-salting", - powh, - uuid); - (iv_i, key_i) = HKDF(key_id, nonce_i, ekss, [optional data], keysize + ivsize) + powh := POW_HASH (qsalt, answer) + ekss := HKDF("Anastasis-secure-question-uuid-salting", + powh, + uuid); + (iv_i, key_i) := HKDF(key_id, nonce_i, ekss, [optional data], keysize + ivsize) -**qsalt**: salt value used to hash answer to satisfy the challenge to prevent the provider from determining the answer via guessing. +**qsalt**: Salt value used to hash answer to satisfy the challenge to prevent the provider from determining the answer via guessing. -**answer**: answer to the security question, in UTF-8, as entered by the user. +**answer**: Answer to the security question, in UTF-8, as entered by the user. -**powh**: result of the (expensive, proof-of-work) hash algorithm. +**powh**: Result of the (expensive, proof-of-work) hash algorithm. **uuid**: UUID of the challenge associated with the security question and the encrypted key share. @@ -307,8 +307,8 @@ algorithm is equivalent for **Anastasis-Policy-Signature**. .. code-block:: none - (anastasis-account-signature) = eddsa_sign(h_body, eddsa_priv) - ver_res = eddsa_verifiy(h_body, anastasis-account-signature, eddsa_pub) + (anastasis-account-signature) := eddsa_sign(h_body, eddsa_priv) + ver_res := eddsa_verifiy(h_body, anastasis-account-signature, eddsa_pub) **anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code ``TALER_SIGNATURE_ANASTASIS_POLICY_UPLOAD`` (1400) (see GNUnet EdDSA signature API for the use of purpose). @@ -321,8 +321,8 @@ When requesting policy downloads, the client must also provide a signature: .. code-block:: none - (anastasis-account-signature) = eddsa_sign(version, eddsa_priv) - ver_res = eddsa_verifiy(version, anastasis-account-signature, eddsa_pub) + (anastasis-account-signature) := eddsa_sign(version, eddsa_priv) + ver_res := eddsa_verifiy(version, anastasis-account-signature, eddsa_pub) **anastasis-account-signature**: Signature over the SHA-512 hash of the body using the purpose code ``TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD`` (1401) (see GNUnet EdDSA signature API for the use of purpose). @@ -356,7 +356,7 @@ leaves a strong adversary with the option of uploading many policies to exhaust the Anastasis server's capacity. We limit this attack by requiring a policy upload to include a reference to a **payment identifier** from a payment made by the user. Thus, a policy upload requires both knowledge of the -**identity** and making a payment. This effectively prevents and adversary +**identity** and making a payment. This effectively prevents an adversary from using the append-only policy storage from exhausting Anastasis server capacity. @@ -397,10 +397,10 @@ Receiving Configuration // Currency in which this provider processes payments. currency: string; - // supported authorization methods + // Supported authorization methods. methods: AuthorizationMethodConfig[]; - // maximum policy upload size supported + // Maximum policy upload size supported. storage_limit_in_megabytes: number; // Payment required to maintain an account to store policy documents for a year. @@ -410,7 +410,7 @@ Receiving Configuration // Payment required to upload truth. To be paid per upload. truth_upload_fee: Amount; - // how long until the service expires deposited truth + // How long until the service expires deposited truth // (unless refreshed via another POST)? truth_lifetime: RelativeTime; @@ -418,7 +418,7 @@ Receiving Configuration // respect to the services provided. liability_limit: Amount; - // salt value with 128 bits of entropy + // Salt value with 128 bits of entropy. // Different providers // will use different high-entropy salt values. The resulting // **provider salt** is then used in various operations to ensure @@ -432,10 +432,10 @@ Receiving Configuration .. ts:def:: AuthorizationMethodConfig interface AuthorizationMethodConfig { - // name of the authorization method + // Name of the authorization method. type: string; - // Fee for accessing key share using this method + // Fee for accessing key share using this method. cost: Amount; } @@ -456,7 +456,7 @@ Receiving Terms of Service .. http:get:: /privacy - Obtain the privacy poliy of the service provided by the escrow provider. + Obtain the privacy policy of the service provided by the escrow provider. **Response:** @@ -485,10 +485,10 @@ In the following, UUID is always defined and used according to `RFC 4122`_. .. http:get:: /policy/$ACCOUNT_PUB[?version=$NUMBER] - Get the customer's encrypted recovery document. If "version" + Get the customer's encrypted recovery document. If ``version`` is not specified, the server returns the latest available version. If - "version" is specified, returns the policy with the respective - "version". The response must begin with the nonce and + ``version`` is specified, returns the policy with the respective + ``version``. The response must begin with the nonce and an AES-GCM tag and continue with the ciphertext. Once decrypted, the plaintext is expected to contain: @@ -500,8 +500,8 @@ In the following, UUID is always defined and used according to `RFC 4122`_. The policy does provide sufficient information for the client to determine how to authorize requests for **truth**. - The client MAY provide an "If-None-Match" header with an Etag. - In that case, the server MUST additionally respond with an "304" status + The client MAY provide an ``If-None-Match`` header with an Etag. + In that case, the server MUST additionally respond with an ``304`` status code in case the resource matches the provided Etag. **Response**: @@ -511,7 +511,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. :http:statuscode:`304 Not modified`: The client requested the same resource it already knows. :http:statuscode:`400 Bad request`: - The $ACCOUNT_PUB is not an EdDSA public key. + The ``$ACCOUNT_PUB`` is not an EdDSA public key. :http:statuscode:`402 Payment Required`: The account's balance is too low for the specified operation. See the Taler payment protocol specification for how to pay. @@ -524,7 +524,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. If the client specified a version number in the header of the request, the server must return that version. If the client did not specify a version in the request, the server returns latest version of the EncryptedRecoveryDocument_. - *Etag*: Set by the server to the Base32-encoded SHA512 hash of the body. Used for caching and to prevent redundancies. The server MUST send the Etag if the status code is 200 OK. + *Etag*: Set by the server to the Base32-encoded SHA512 hash of the body. Used for caching and to prevent redundancies. The server MUST send the Etag if the status code is ``200 OK``. *If-None-Match*: If this is not the very first request of the client, this contains the Etag-value which the client has received before from the server. The client SHOULD send this header with every request (except for the first request) to avoid unnecessary downloads. @@ -563,23 +563,23 @@ In the following, UUID is always defined and used according to `RFC 4122`_. backend may return a response immediately. *If-None-Match*: This header MUST be present and set to the SHA512 hash (Etag) of the body by the client. - The client SHOULD also set the "Expect: 100-Continue" header and wait for "100 continue" + The client SHOULD also set the ``Expect: 100-Continue`` header and wait for ``100 continue`` before uploading the body. The server MUST use the Etag to check whether it already knows the encrypted recovery document that is about to be uploaded. - The server MUST refuse the upload with a "304" status code if the Etag matches + The server MUST refuse the upload with a ``304`` status code if the Etag matches the latest version already known to the server. *Anastasis-Policy-Signature*: The client must provide Base-32 encoded EdDSA signature over hash of body with ``$ACCOUNT_PRIV``, affirming desire to upload an encrypted recovery document. - *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see 402 status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a 402 response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. + *Payment-Identifier*: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see ``402`` status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the **kdf_id** might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a ``402`` response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. **Response**: :http:statuscode:`204 No content`: - The encrypted recovery document was accepted and stored. "Anastasis-Version" and "Anastasis-UUID" headers + The encrypted recovery document was accepted and stored. ``Anastasis-Version`` and ``Anastasis-UUID`` headers indicate what version and UUID was assigned to this encrypted recovery document upload by the server. :http:statuscode:`304 Not modified`: - The same encrypted recovery document was previously accepted and stored. "Anastasis-Version" header + The same encrypted recovery document was previously accepted and stored. ``Anastasis-Version`` header indicates what version was previously assigned to this encrypted recovery document. :http:statuscode:`400 Bad request`: The ``$ACCOUNT_PUB`` is not an EdDSA public key or mandatory headers are missing. @@ -603,7 +603,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. // encrypted_compressed_recovery_document. nonce: [32]; //bytearray - // Authentication tag + // Authentication tag. aes_gcm_tag: [16]; //bytearray // Variable-size encrypted recovery document. After decryption, @@ -625,10 +625,10 @@ In the following, UUID is always defined and used according to `RFC 4122`_. // to the details of how this is ultimately encoded. backup_account: []; //bytearray of undefined length - // List of escrow providers and selected authentication method + // List of escrow providers and selected authentication method. methods: EscrowMethod[]; - // List of possible decryption policies + // List of possible decryption policies. policy: DecryptionPolicy[]; } @@ -637,17 +637,17 @@ In the following, UUID is always defined and used according to `RFC 4122`_. .. ts:def:: EscrowMethod interface EscrowMethod { - // URL of the escrow provider (including possibly this Anastasis server) + // URL of the escrow provider (including possibly this Anastasis server). provider_url : string; - // Type of the escrow method (e.g. security question, SMS etc.) + // Type of the escrow method (e.g. security question, SMS etc.). escrow_type: string; // UUID of the escrow method (see /truth/ API below). uuid: string; // Key used to encrypt the `Truth` this `EscrowMethod` is related to. - // Client has to provide this key to the server when using /truth/ + // Client has to provide this key to the server when using ``/truth/``. truth_encryption_key: [32]; //bytearray // Salt used to encrypt the truth on the Anastasis server. @@ -679,7 +679,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. // escrow methods identified by UUID. encrypted_master_key: [32]; //bytearray - // List of escrow methods identified by their uuid. + // List of escrow methods identified by their UUID. uuid: string[]; } @@ -702,7 +702,7 @@ charge per truth operation using GNU Taler. .. http:post:: /truth/$UUID - Upload a TruthUploadRequest_-Object according to the policy the client created before (see RecoveryDocument_). + Upload a `TruthUploadRequest`_-Object according to the policy the client created before (see `RecoveryDocument`_). If request has been seen before, the server should do nothing, and otherwise store the new object. **Request:** @@ -748,7 +748,7 @@ charge per truth operation using GNU Taler. // encrypted_truth. nonce: [32]; //bytearray - // Authentication tag of encrypted_truth + // Authentication tag of ``encrypted_truth``. aes_gcm_tag: [16]; //bytearray // Variable-size truth. After decryption, @@ -760,7 +760,7 @@ charge per truth operation using GNU Taler. // string "ECT". encrypted_truth: [80]; //bytearray - // mime type of truth, i.e. text/ascii, image/jpeg, etc. + // MIME type of truth, i.e. text/ascii, image/jpeg, etc. truth_mime: string; } @@ -768,7 +768,7 @@ charge per truth operation using GNU Taler. .. http:get:: /truth/$UUID[?response=$H_RESPONSE] Get the stored encrypted key share. If ``$H_RESPONSE`` is specified by the client, the server checks - if ``$H_RESPONSE`` matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth). + if ``$H_RESPONSE`` matches the expected response specified before within the `TruthUploadRequest`_ (see ``encrypted_truth``). Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share. The encrypted key share is returned simply as a byte array and not in JSON format. @@ -776,7 +776,7 @@ charge per truth operation using GNU Taler. **Response**: :http:statuscode:`200 OK`: - EncryptedKeyShare_ is returned in body (in binary). + `EncryptedKeyShare`_ is returned in body (in binary). :http:statuscode:`202 Accepted`: The escrow provider will respond out-of-band (i.e. SMS). The body may contain human-readable instructions on next steps. @@ -786,7 +786,7 @@ charge per truth operation using GNU Taler. :http:statuscode:`303 See other`: The provider redirects for authentication (i.e. video identification/WebRTC). If the client is not a browser, it should launch a browser at the URL - given in the "Location" header and allow the user to re-try the operation + given in the ``Location`` header and allow the user to re-try the operation after successful authorization. :http:statuscode:`402 Payment required`: The service requires payment for access to truth. @@ -800,14 +800,14 @@ charge per truth operation using GNU Taler. The server has not (recently) issued a challenge under the given UUID, but a reply was provided. (This does not apply for secure question.) :http:statuscode:`417 Expectation Failed`: - The decrypted 'truth' does not match the expectations of the authentication + The decrypted ``truth`` does not match the expectations of the authentication backend, i.e. a phone number for sending an SMS is not a number, or an e-mail address for sending an E-mail is not a valid e-mail address. :http:statuscode:`503 Service Unavailable`: Server is out of Service. - *Truth-Decryption-Key*: Key used to encrypt the **truth** (see encrypted_truth within TruthUploadRequest_) and which has to provided by the user. The key is stored with - the according EscrowMethod_. The server needs this key to get the info out of TruthUploadRequest_ needed to verify the ``$RESPONSE``. + *Truth-Decryption-Key*: Key used to encrypt the **truth** (see encrypted_truth within `TruthUploadRequest`_) and which has to provided by the user. The key is stored with + the according `EscrowMethod`_. The server needs this key to get the info out of `TruthUploadRequest`_ needed to verify the ``$RESPONSE``. **Details:** @@ -818,7 +818,7 @@ charge per truth operation using GNU Taler. // Nonce used to compute the decryption (iv,key) pair. nonce_i: [32]; //bytearray - // Authentication tag + // Authentication tag. aes_gcm_tag_i: [16]; //bytearray // Encrypted key-share in base32 encoding. @@ -831,7 +831,7 @@ charge per truth operation using GNU Taler. // Depending on the method, // the HKDF may additionally include // bits from the response (i.e. some hash over the - // answer to the security question) + // answer to the security question). encrypted_key_share_i: [32]; //bytearray } @@ -844,7 +844,7 @@ charge per truth operation using GNU Taler. // the key to decrypt the master key. key_share: [32]; //bytearray - // Signature over method, uuid, and key_share. + // Signature over method, UUID, and ``key_share``. account_sig: EddsaSignature; } @@ -880,7 +880,7 @@ arguments given to the reducer. A **transition argument** also is a statement in } The new state returned by the reducer with the state and transition argument defined -above would look like following for the transition action_ "select_continent": +above would look like following for the transition action_ ``select_continent``: .. code-block:: json @@ -927,7 +927,7 @@ States Overall, the reducer knows the following states: - - **ERROR**: The transition lead to an error. No further transitions are possible from + - **ERROR**: The transition led to an error. No further transitions are possible from this state, but the client may want to continue from a previous state. - **CONTINENT_SELECTING**: The user should specify the continent where they are living, so that we can show a list of countries to choose from. @@ -1034,7 +1034,7 @@ continents which contain countries for which Anastasis could function (based on having providers that are known to operate and rules being provided for user attributes from those countries). -For internationalization, another field "continents_i18n" may be present. +For internationalization, another field ``continents_i18n`` may be present. This field would be a map of language names to arrays of translated continent names: @@ -1075,7 +1075,7 @@ Here the user specifies the continent they live on. Arguments (example): "continent": "Europe" } -The continent must be given using the English name from the "continents" array. +The continent must be given using the English name from the ``continents`` array. Using a translated continent name is invalid and may result in failure. The reducer returns an updated state with a list of countries to choose from, @@ -1117,12 +1117,12 @@ for example: ] } -Here "countries" is an array of countries on the "selected_continent". For -each country, the "code" is the ISO 3166-1 alpha-2 country code. The -"continent" is only present because some countries span continents, the -information is redundant and will always match "selected_continent". The -"name" is the name of the country in English, internationalizations of the -name may be provided in "name_i18n". The "currency" is **an** official +Here ``countries`` is an array of countries on the ``selected_continent``. For +each country, the ``code`` is the ISO 3166-1 alpha-2 country code. The +``continent`` is only present because some countries span continents, the +information is redundant and will always match ``selected_continent``. The +``name`` is the name of the country in English, internationalizations of the +name may be provided in ``name_i18n``. The ``currency`` is **an** official currency of the country, if a country has multiple currencies, it may appear multiple times in the list. In this case, the user should select the entry with the currency they intend to pay with. It is also possible for users @@ -1146,8 +1146,8 @@ Arguments (example): "currency": "EUR" } -The "country_code" must be an ISO 3166-1 alpha-2 country code from -the array of "countries" of the reducer's state. The "currency" +The ``country_code`` must be an ISO 3166-1 alpha-2 country code from +the array of ``countries`` of the reducer's state. The ``currency`` field must be a valid currency accepted by the Taler payment system. The reducer returns a new state with the list of attributes the @@ -1255,32 +1255,32 @@ providers that accept payments in the selected currency: } } -The array of "required_attributes" contains attributes about the user +The array of ``required_attributes`` contains attributes about the user that must be provided includes: - - **type**: the type of the attribute, for now only 'string' and 'date' are - supported - - **name**: the name of the attribute, this is the key under which the + - **type**: The type of the attribute, for now only ``string`` and ``date`` are + supported. + - **name**: The name of the attribute, this is the key under which the attribute value must be provided later. The name must be unique per response. - - **label**: a human-readable description of the attribute in English. + - **label**: A human-readable description of the attribute in English. Translated descriptions may be provided under **label_i18n**. - - **uuid**: a UUID that uniquely identifies identical attributes across + - **uuid**: A UUID that uniquely identifies identical attributes across different countries. Useful to preserve values should the user enter some attributes, and then switch to another country. Note that attributes must not be preserved if they merely have the same **name**, only the **uuid** will be identical if the semantics is identicial. - - **widget**: an optional name of a widget that is known to nicely render + - **widget**: An optional name of a widget that is known to nicely render the attribute entry in user interfaces where named widgets are supported. - - **validation-regex**: an optional extended POSIX regular expression + - **validation-regex**: An optional extended POSIX regular expression that is to be used to validate (string) inputs to ensure they are well-formed. - - **validation-logic**: optional name of a function that should be called + - **validation-logic**: Optional name of a function that should be called to validate the input. If the function is not known to the particular client, the respective validation can be skipped (at the expense of typos by users not being detected, possibly rendering secrets irrecoverable). - - **optional**: optional boolean field that, if ``true``, indicates that + - **optional**: Optional boolean field that, if ``true``, indicates that this attribute is not actually required but optional and users MAY leave it blank in case they do not have the requested information. Used for common fields that apply to some large part of the population but are @@ -1290,25 +1290,25 @@ The authentication providers are listed under a key that is the base URL of the service. For each provider, the following information is provided if the provider was successfully contacted: - - **http_status**: HTTP status code, always 200 on success. - - **methods**: array of authentication methods supported by this + - **http_status**: HTTP status code, always ``200`` on success. + - **methods**: Array of authentication methods supported by this provider. Includes the **type** of the authentication method and the **usage_fee** (how much the user must pay for authorization using this method during recovery). - - **annual_fee**: fee the provider charges to store the recovery + - **annual_fee**: Fee the provider charges to store the recovery policy for one year. - - **truth_upload_fee**: fee the provider charges to store a key share. + - **truth_upload_fee**: Fee the provider charges to store a key share. - **truth_lifetime**: Taler-style relative time that specifies how long the provider will store truth data (key shares) after an upload. - - **liability_limit**: amount the provider can be held liable for in + - **liability_limit**: Amount the provider can be held liable for in case a key share or recovery document cannot be recovered due to provider failures. - - **currency**: currency in which the provider wants to be paid, + - **currency**: Currency in which the provider wants to be paid, will match all of the fees. - - **storage_limit_in_megabytes**: maximum size of an upload (for + - **storage_limit_in_megabytes**: Maximum size of an upload (for both recovery document and truth data) in megabytes. - - **provider_name**: human-readable name of the provider's business. - - **salt**: salt value used by the provider, used to derive the + - **provider_name**: Human-readable name of the provider's business. + - **salt**: Salt value used by the provider, used to derive the user's identity at this provider. Should be unique per provider, and must never change for a given provider. The salt is base32 encoded. @@ -1322,7 +1322,7 @@ If contacting the provider failed, the information returned is: **add_provider**: -This operation can be performed in state "USER_ATTRIBUTES_COLLECTING". It +This operation can be performed in state ``USER_ATTRIBUTES_COLLECTING``. It adds one or more Anastasis providers to the list of providers the reducer should henceforth consider. Note that removing providers is not possible at this time. @@ -1434,7 +1434,7 @@ to it: } If required attributes are missing, do not match the required regular -expression or fail the custom validation logic, the reducer SHOULD transition +expression, or fail the custom validation logic, the reducer SHOULD transition to an error state indicating what was wrong about the input. A reducer that does not support some specific validation logic MAY accept the invalid input and proceed anyway. The error state will include a Taler error code that @@ -1450,7 +1450,7 @@ is specific to the failure, and optional details. Example: } Clients may safely repeat this transition to validate the user's inputs -until they statisfy all of the constraints. This way, the user interface +until they satisfy all of the constraints. This way, the user interface does not have to perform the input validation directly. @@ -1537,10 +1537,10 @@ response: } If the index is invalid, the reducer will instead -transition into an ERROR state. +transition into an ``ERROR`` state. -**next** (from "AUTHENTICATIONS_EDITING"): +**next** (from ``AUTHENTICATIONS_EDITING``): This transition confirms that the user has finished adding (or removing) authentication methods, and that the system should now automatically compute @@ -1613,7 +1613,7 @@ policy. The ``methods`` array specifies the index of the the provider that was selected to supervise this authentication. If no authentication method was provided, the reducer will transition into an -ERROR state instead of suggesting policies. +``ERROR`` state instead of suggesting policies. **add_policy**: @@ -1698,9 +1698,9 @@ the "policies" array, returning an updated state: ] } -If the new policy is invalid, for example because it add an unknown -authentication method or the selected provider does not support the type of -authentication, the reducer will transition into an ERROR state instead of +If the new policy is invalid, for example because it adds an unknown +authentication method, or the selected provider does not support the type of +authentication, the reducer will transition into an ``ERROR`` state instead of adding the new policy. @@ -1762,11 +1762,11 @@ be: ] } -If the index given is invalid, the reducer will transition into an ERROR state +If the index given is invalid, the reducer will transition into an ``ERROR`` state instead of deleting a policy. -**next** (from "POLICIES_REVIEWING"): +**next** (from ``POLICIES_REVIEWING``): Using this transition, the user confirms that the policies in the current state are acceptable. The transition does not take any arguments. @@ -1781,7 +1781,7 @@ The reducer will simply transition to the ``SECRET_EDITING`` state: If the array of ``policies`` is currently empty, the reducer will transition -into an ERROR state instead of allowing the user to continue. +into an ``ERROR`` state instead of allowing the user to continue. **enter_secret:** @@ -1797,9 +1797,10 @@ for example: "secret": { "value": "EDJP6WK5EG50", "mime" : "text/plain" + } } -If the application is unaware of the format, it set the ``mime`` field to ``null`. +If the application is unaware of the format, it set the ``mime`` field to ``null``. After adding a secret, the reducer may transition into different states depending on whether payment(s) are necessary. If payments are needed, the @@ -1879,9 +1880,9 @@ final error state would be: Here, the fields have the following meaning: - - **http_status** is the HTTP status returned by the Anastasis provider - - **upload_status** is the Taler error code return by the provider - - **provider_url** is the base URL of the failing provider + - **http_status** is the HTTP status returned by the Anastasis provider. + - **upload_status** is the Taler error code return by the provider. + - **provider_url** is the base URL of the failing provider. In the above example, 52 would thus imply that the Anastasis provider failed to store information into its database. @@ -1896,7 +1897,7 @@ This transition provides the user's personal attributes. The specific set of attributes required depends on the country of residence of the user. Some attributes may be optional, in which case they should be omitted entirely (that is, not simply be set to ``null`` or an empty string). The -arguments are identical to the **enter_user_attributes__ transition from +arguments are identical to the **enter_user_attributes** transition from the backup process. Example arguments would thus be: .. code-block:: json @@ -1963,21 +1964,21 @@ to be recovered. The ``provider_url`` from where the recovery document was obtained and its ``version`` are also provided. Each challenge comes with four mandatory fields: - - **uuid**: a unique identifier of the challenge; this is what the + - **uuid**: A unique identifier of the challenge; this is what the UUIDs in the policies array refer to, but also this UUID may be included in messages sent to the user. They allow the user to distinguish different PIN/TANs should say the same phone number be used for SMS-authentication with different providers. - - **cost**: this is the amount the Anastasis provider will charge + - **cost**: This is the amount the Anastasis provider will charge to allow the user to pass the challenge. - - **type**: this is the type of the challenge, as a string. - - **instructions**: contains additional important hints for the user + - **type**: This is the type of the challenge, as a string. + - **instructions**: Contains additional important hints for the user to allow the user to satisfy the challenge. It typically includes an abbreviated form of the contact information or the security question. Details depend on ``type``. If a recovery document was not found, either the user never performed -a backup, entered incorrect attributes or used a provider not yet in +a backup, entered incorrect attributes, or used a provider not yet in the list of Anastasis providers. Hence, the user must now either select a different provider, or go ``back`` and update the identity attributes. In the case a recovery document was not found, the @@ -1996,7 +1997,7 @@ Here, the ``error_code`` is from the ``enum ANASTASIS_RecoveryStatus`` and describes precisely what failed about the download, while the ``error_message`` is a human-readable (English) explanation of the code. Applications may want to translate the message using GNU gettext; -translations should be available in the "anastasis" text domain. +translations should be available in the ``anastasis`` text domain. However, in general it should be sufficient to display the slightly more generic Taler error code that is returned with the new state. @@ -2017,7 +2018,7 @@ which takes a provider URL and policy version as arguments: "version": 2 } -Note that using a version of 0 implies fetching ``the latest version``. The +Note that using a version of 0 implies fetching "the latest version". The resulting states are the same as those of the ``enter_user_attributes`` transition, except that the recovery document version is not necessarily the latest available version at the provider. @@ -2338,7 +2339,7 @@ Video identification (vid) Requires the user to identify via video-call. In the video-call, the user is told the code (prefixed with ``A-``) needed to authenticate. -The user is expected to delete all metadata revealing information about per +The user is expected to delete all metadata revealing personal information from the images before uploading them. Since the respective images must be passed on to the video identification service in the event of password recovery, it should be ensured that no further information about the user can |