[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated (6d525ba -> 2062174)
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated (6d525ba -> 2062174) |
|
Date: |
Wed, 07 Apr 2021 10:58:14 +0200 |
This is an automated email from the git hooks/post-receive script.
ttn pushed a change to branch master
in repository docs.
from 6d525ba create order fixed
new 7188d2b change markup for Anastasis-Account-Signature from " to ``
new c8f07b0 add comma
new 6977f86 mark up ‘kdf_id’
new 20b80e4 mark up ‘eddsa_priv’
new cbc54b0 mark up ‘nonce’ and ‘kdf_id’
new 6962ada add comma
new 2a95bda change ‘code-block’ type from ‘none’ to ‘c’
new e821317 use ‘:=’ instead of ‘=’ in pseudocode code-block (four
instances)
new 9b28844 use ‘:=’ instead of ‘=’ in pseudocode code-block (three
instances)
new d8c4044 capitalize first word in sentence (three instances)
new 56bd30a use ‘:=’ instead of ‘=’ in pseudocode code-block (two
instances)
new 5ac931e use ‘:=’ instead of ‘=’ in pseudocode code-block (two
instances)
new 229f7c9 fix typo: s/and/an/
new 122ac95 capitalize first word in sentence; add period at end of
sentence (two instances)
new f7d01c0 capitalize first word in sentence
new 6b60dc3 capitalize first word in sentence; add period at end of
sentence
new 051bf8d capitalize first word in sentence; add period at end of
sentence
new cf0e971 add period at end of sentence
new 134b1ca fix typo: s/poliy/policy/
new 968a305 change markup of ‘version’ from " to `` (three instances)
new 5e000bd change markup of ‘If-None-Match’ from " to ``
new 2d9b698 change markup of ‘304’ from " to ``
new e0ff50b mark up ‘$ACCOUNT_PUB’
new 66033d5 mark up ‘200 OK’
new 336995e change markup of ‘Expect: 100-Continue’ from " to ``
new 65accd8 change markup of ‘100 continue’ from " to ``
new 95af36b change markup of ‘304’ from " to ``
new 6516884 mark up of ‘402’ (two instances)
new 95fe935 change markup of ‘Anastasis-Version’ from " to ``
new 891e607 change markup of ‘Anastasis-UUID’ from " to ``
new 6968654 change markup of ‘Anastasis-Version’ from " to ``
new 8f3d08a add period at end of sentence
new 5a54c66 add period at end of sentence (two instances)
new a5d13b8 add period at end of sentence (two instances)
new b7ccaf1 mark up ‘/truth/’; add period at end of sentence
new 35ceaa3 fix typo: s/uuid/UUID/
new dbd395f mark up ‘TruthUploadRequest’ and ‘RecoveryDocument’
new 98eec82 mark up ‘encrypted_truth’; add period at end of sentence
new 8d79088 fix typo: s/mime/MIME/
new 5d3512c mark up ‘TruthUploadRequest’
new 02bbcb9 mark up ‘encrypted_truth’
new 82ca682 mark up ‘EncryptedKeyShare’
new 67a203f change markup of ‘Location’ from " to ``
new ad77076 change markup of ‘truth’ from ' to ``
new 29bc97a mark up ‘TruthUploadRequest’ (two instances)
new 78cb6da mark up ‘EscrowMethod’
new 420d110 add period at end of sentence
new c5bf3d4 add period at end of sentence
new 7411727 fix typo: s/uuid/UUID/
new 5659ed2 mark up ‘key_share’
new f5558ed change markup of ‘select_continent’ from " to ``
new 32a6e02 fix typo: s/lead/led/
new 613e53b change markup of ‘continents_i18n’ from " to ``
new a8ec79b change markup of ‘continents’ from " to ``
new d8ff348 change markup of ‘countries’ from " to ``
new 51e1747 change markup of ‘selected_continent’ from " to ``
new c930df6 change markup of ‘code’ from " to ``
new e73729d change markup of ‘continent’ from " to ``
new 023ff38 change markup of ‘selected_continent’ from " to ``
new 10b3084 change markup of ‘name’ from " to ``
new 9b0b7ad change markup of ‘name_i18n’ from " to ``
new f18ece1 change markup of ‘currency’ from " to ``
new e5bdc8a change markup of ‘country_code’ from " to ``
new 10be927 change markup of ‘countries’ from " to ``
new 594b548 change markup of ‘currency’ from " to ``
new 067c7df change markup of ‘required_attributes’ from " to ``
new 5da2ca9 capitalize first word in sentence
new 50da246 change markup of ‘string’, ‘date’ from ' to ``
new 4806f63 add period at end of sentence
new fd3457d capitalize first word in sentence (seven instances)
new 4f005a2 mark up ‘200’
new 71698f1 capitalize first word in sentence (eight instances)
new d0ab21a change markup of ‘USER_ATTRIBUTES_COLLECTING’ from " to ``
new a95ab3b add comma
new dc506f3 fix typo: s/statisfy/satisfy/
new 5d0778f mark up ‘ERROR’
new 4ff5cec change markup of ‘AUTHENTICATIONS_EDITING’ from " to ``
new 161bfec add link to bug #6760
new 6553f66 mark up ‘ERROR’
new 56e1197 fix typo: s/add/adds/
new 76850a6 add comma
new 5adc9e3 mark up ‘ERROR’
new 10a7583 mark up ‘ERROR’
new 1ee7fb2 change markup of ‘POLICIES_REVIEWING’ from " to ``
new 681ca29 mark up ‘ERROR’
new 0b1deab add missing close-brace
new 8dee9f1 fix typo: add backtick
new cbe8883 add period at end of sentence (three instances)
new c307288 fix typo: use ** instead of __ to end markup
new 7b49f06 capitalize first word in sentence (four instances)
new f2d2f39 add comma
new 99940bd change markup of ‘anastasis’ from " to ``
new a641188 change markup of ‘the latest version’ from `` to "
new 2062174 diction: s/information about per/personal information/
The 94 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
anastasis.rst | 240 +++++++++++++++++++++++++++++-----------------------------
1 file changed, 121 insertions(+), 119 deletions(-)
diff --git a/anastasis.rst b/anastasis.rst
index a8ed7a4..7adeb0b 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 [...]
+ *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 [...]
**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
@@ -1561,7 +1561,8 @@ providers:
..note::
- This is currently not supported (#6760), the current implementation of the
+ This is currently not supported (see `bug 6760
<https://bugs.gnunet.org/view.php?id=6760>`_),
+ the current implementation of the
reducer ignores this optional argument.
The resulting state provides the suggested recovery policies in a way suitable
@@ -1614,7 +1615,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**:
@@ -1699,9 +1700,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.
@@ -1763,11 +1764,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.
@@ -1782,7 +1783,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:**
@@ -1798,9 +1799,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
@@ -1880,9 +1882,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.
@@ -1897,7 +1899,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
@@ -1964,21 +1966,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
@@ -1997,7 +1999,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.
@@ -2018,7 +2020,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.
@@ -2339,7 +2341,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
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated (6d525ba -> 2062174),
gnunet <=
- [taler-docs] 02/94: add comma, gnunet, 2021/04/07
- [taler-docs] 01/94: change markup for Anastasis-Account-Signature from " to ``, gnunet, 2021/04/07
- [taler-docs] 03/94: mark up ‘kdf_id’, gnunet, 2021/04/07
- [taler-docs] 05/94: mark up ‘nonce’ and ‘kdf_id’, gnunet, 2021/04/07
- [taler-docs] 20/94: change markup of ‘version’ from " to `` (three instances), gnunet, 2021/04/07
- [taler-docs] 07/94: change ‘code-block’ type from ‘none’ to ‘c’, gnunet, 2021/04/07
- [taler-docs] 06/94: add comma, gnunet, 2021/04/07
- [taler-docs] 21/94: change markup of ‘If-None-Match’ from " to ``, gnunet, 2021/04/07
- [taler-docs] 04/94: mark up ‘eddsa_priv’, gnunet, 2021/04/07
- [taler-docs] 12/94: use ‘:=’ instead of ‘=’ in pseudocode code-block (two instances), gnunet, 2021/04/07