diff --git a/taskchampion/404.html b/taskchampion/404.html index 4484a7ff5..e13eb6887 100644 --- a/taskchampion/404.html +++ b/taskchampion/404.html @@ -83,7 +83,7 @@ diff --git a/taskchampion/data-model.html b/taskchampion/data-model.html index ae8ce68fc..6b801cdf8 100644 --- a/taskchampion/data-model.html +++ b/taskchampion/data-model.html @@ -82,7 +82,7 @@ diff --git a/taskchampion/encryption.html b/taskchampion/encryption.html new file mode 100644 index 000000000..9ae0ffbde --- /dev/null +++ b/taskchampion/encryption.html @@ -0,0 +1,228 @@ + + + + + + Encryption - TaskChampion + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + +
+
+

Encryption

+

The client configuration includes an encryption secret of arbitrary length. +This section describes how that information is used to encrypt and decrypt data sent to the server (versions and snapshots).

+

Encryption is not used for local (on-disk) sync, but is used for all cases where data is sent from the local host.

+

Key Derivation

+

The client derives the 32-byte encryption key from the configured encryption secret using PBKDF2 with HMAC-SHA256 and 100,000 iterations. +The salt value depends on the implementation of the protocol, as described in subsequent chapters.

+

Encryption

+

The client uses AEAD, with algorithm CHACHA20_POLY1305. +The client should generate a random nonce, noting that AEAD is not secure if a nonce is used repeatedly for the same key.

+

AEAD supports additional authenticated data (AAD) which must be provided for both open and seal operations. +In this protocol, the AAD is always 17 bytes of the form:

+
    +
  • app_id (byte) - always 1
  • +
  • version_id (16 bytes) - 16-byte form of the version ID associated with this data +
      +
    • for versions (AddVersion, GetChildVersion), the parent version_id
    • +
    • for snapshots (AddSnapshot, GetSnapshot), the snapshot version_id
    • +
    +
  • +
+

The app_id field is for future expansion to handle other, non-task data using this protocol. +Including it in the AAD ensures that such data cannot be confused with task data.

+

Although the AEAD specification distinguishes ciphertext and tags, for purposes of this specification they are considered concatenated into a single bytestring as in BoringSSL's EVP_AEAD_CTX_seal.

+

Representation

+

The final byte-stream is comprised of the following structure:

+
    +
  • version (byte) - format version (always 1)
  • +
  • nonce (12 bytes) - encryption nonce
  • +
  • ciphertext (remaining bytes) - ciphertext from sealing operation
  • +
+

The version field identifies this data format, and future formats will have a value other than 1 in this position.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + diff --git a/taskchampion/http.html b/taskchampion/http.html new file mode 100644 index 000000000..e33c8beb2 --- /dev/null +++ b/taskchampion/http.html @@ -0,0 +1,241 @@ + + + + + + HTTP Implementation - TaskChampion + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + +
+
+

HTTP Representation

+

The transactions in the sync protocol are realized for an HTTP server at <origin> using the HTTP requests and responses described here. +The origin should be an HTTPS endpoint on general principle, but nothing in the functonality or security of the protocol depends on connection encryption.

+

The replica identifies itself to the server using a client_id in the form of a UUID. +This value is passed with every request in the X-Client-Id header, in its dashed-hex format.

+

The salt used in key derivation is the SHA256 hash of the 16-byte form of the client ID.

+

AddVersion

+

The request is a POST to <origin>/v1/client/add-version/<parentVersionId>. +The request body contains the history segment, optionally encoded using any encoding supported by actix-web. +The content-type must be application/vnd.taskchampion.history-segment.

+

The success response is a 200 OK with an empty body. +The new version ID appears in the X-Version-Id header. +If included, a snapshot request appears in the X-Snapshot-Request header with value urgency=low or urgency=high.

+

On conflict, the response is a 409 CONFLICT with an empty body. +The expected parent version ID appears in the X-Parent-Version-Id header.

+

Other error responses (4xx or 5xx) may be returned and should be treated appropriately to their meanings in the HTTP specification.

+

GetChildVersion

+

The request is a GET to <origin>/v1/client/get-child-version/<parentVersionId>.

+

The response is determined as described above. +The not-found response is 404 NOT FOUND. +The gone response is 410 GONE. +Neither has a response body.

+

On success, the response is a 200 OK. +The version's history segment is returned in the response body, with content-type application/vnd.taskchampion.history-segment. +The version ID appears in the X-Version-Id header. +The response body may be encoded, in accordance with any Accept-Encoding header in the request.

+

On failure, a client should treat a 404 NOT FOUND as indicating that it is up-to-date. +Clients should treat a 410 GONE as a synchronization error. +If the client has pending changes to send to the server, based on a now-removed version, then those changes cannot be reconciled and will be lost. +The client should, optionally after consulting the user, download and apply the latest snapshot.

+

AddSnapshot

+

The request is a POST to <origin>/v1/client/add-snapshot/<versionId>. +The request body contains the snapshot data, optionally encoded using any encoding supported by actix-web. +The content-type must be application/vnd.taskchampion.snapshot.

+

If the version is invalid, as described above, the response should be 400 BAD REQUEST. +The server response should be 200 OK on success.

+

GetSnapshot

+

The request is a GET to <origin>/v1/client/snapshot.

+

The response is a 200 OK. +The snapshot is returned in the response body, with content-type application/vnd.taskchampion.snapshot. +The version ID appears in the X-Version-Id header. +The response body may be encoded, in accordance with any Accept-Encoding header in the request.

+

After downloading and decrypting a snapshot, a client must replace its entire local task database with the content of the snapshot. +Any local operations that had not yet been synchronized must be discarded. +After the snapshot is applied, the client should begin the synchronization process again, starting from the snapshot version.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + diff --git a/taskchampion/index.html b/taskchampion/index.html index 2888c20d0..f91458fd6 100644 --- a/taskchampion/index.html +++ b/taskchampion/index.html @@ -82,7 +82,7 @@ diff --git a/taskchampion/installation.html b/taskchampion/installation.html index 3b91fa839..4b9ab3940 100644 --- a/taskchampion/installation.html +++ b/taskchampion/installation.html @@ -82,7 +82,7 @@ diff --git a/taskchampion/internals.html b/taskchampion/internals.html index 4f8692e3d..39754787c 100644 --- a/taskchampion/internals.html +++ b/taskchampion/internals.html @@ -82,7 +82,7 @@ diff --git a/taskchampion/object-store.html b/taskchampion/object-store.html new file mode 100644 index 000000000..202d3a5ac --- /dev/null +++ b/taskchampion/object-store.html @@ -0,0 +1,202 @@ + + + + + + Object-Store Implementation - TaskChampion + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + +
+
+

Object Store Representation

+

TaskChampion also supports use of a generic key-value store to synchronize replicas.

+

In this case, the salt used in key derivation is a random 16-byte value, stored +in the object store and retrieved as needed.

+

The details of the mapping from this protocol to keys and values are private to the implementation. +Other applications should not access the key-value store directly.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + diff --git a/taskchampion/plans.html b/taskchampion/plans.html index 446e2712a..81438d532 100644 --- a/taskchampion/plans.html +++ b/taskchampion/plans.html @@ -82,7 +82,7 @@ @@ -173,7 +173,7 @@ However, purging of a task does not satisfy the necessary OT guarantees, so some