commit d7498cd182862d7aee84b3fd09238ef26d0c36a9
parent a81b944eebc4f09337da5962c6218ae497e9b30e
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 29 Jul 2026 21:36:00 +0200
document version use/limitations
Diffstat:
1 file changed, 28 insertions(+), 0 deletions(-)
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst
@@ -548,6 +548,13 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
upload_time: Timestamp;
}
+ .. note::
+
+ Both the version numbers used as keys and the ``upload_time`` are stated by
+ the provider and are not covered by any signature. See the warning under
+ ``GET /policy/$ACCOUNT_PUB`` below before using either of them to decide
+ which recovery document is the most recent one.
+
.. http:get:: /policy/$ACCOUNT_PUB[?version=$NUMBER]
Get the customer's encrypted recovery document. If ``version``
@@ -587,6 +594,27 @@ 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_.
+ .. warning::
+
+ The version number is **not** authenticated. The ``Anastasis-Policy-Signature``
+ of the upload covers the hash of the body and nothing else, so a provider can
+ serve an older but perfectly well-signed recovery document while labelling it
+ with any version number it likes, and it can withhold newer versions entirely.
+ Clients MUST NOT treat the version --- or the ``upload_time`` reported by the
+ ``/meta`` endpoint --- as a trustworthy statement about which document is the
+ most recent one. A client SHOULD still refuse a response whose version does
+ not match the version it explicitly asked for, as that is a mismatch it can
+ detect locally.
+
+ This is an accepted limitation of the protocol, not an oversight: the version
+ is assigned by the provider *after* the upload, so a client cannot sign a
+ value it does not choose. Version numbers are also assigned per provider, so
+ the same document may well carry different version numbers at different
+ providers. A client that needs to determine which of several backups is the
+ newest should place a timestamp, or a comparable ordering value, **inside**
+ the recovery document, where it is covered by the account signature and can
+ be compared across providers.
+
*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.
