diff options
Diffstat (limited to 'lib/csapi/keys.h')
| -rw-r--r-- | lib/csapi/keys.h | 74 |
1 files changed, 65 insertions, 9 deletions
diff --git a/lib/csapi/keys.h b/lib/csapi/keys.h index 621945eb..b28de305 100644 --- a/lib/csapi/keys.h +++ b/lib/csapi/keys.h @@ -4,8 +4,11 @@ #pragma once +#include "csapi/definitions/cross_signing_key.h" #include "csapi/definitions/device_keys.h" +#include "e2ee/e2ee.h" + #include "jobs/basejob.h" namespace Quotient { @@ -14,7 +17,7 @@ namespace Quotient { * * Publishes end-to-end encryption keys for the device. */ -class UploadKeysJob : public BaseJob { +class QUOTIENT_API UploadKeysJob : public BaseJob { public: /*! \brief Upload end-to-end encryption keys. * @@ -29,14 +32,32 @@ public: * by the [key algorithm](/client-server-api/#key-algorithms). * * May be absent if no new one-time keys are required. + * + * \param fallbackKeys + * The public key which should be used if the device's one-time keys + * are exhausted. The fallback key is not deleted once used, but should + * be replaced when additional one-time keys are being uploaded. The + * server will notify the client of the fallback key being used through + * `/sync`. + * + * There can only be at most one key per algorithm uploaded, and the + * server will only persist one key per algorithm. + * + * When uploading a signed key, an additional `fallback: true` key should + * be included to denote that the key is a fallback key. + * + * May be absent if a new fallback key is not required. */ explicit UploadKeysJob(const Omittable<DeviceKeys>& deviceKeys = none, - const QHash<QString, QVariant>& oneTimeKeys = {}); + const OneTimeKeys& oneTimeKeys = {}, + const OneTimeKeys& fallbackKeys = {}); // Result properties /// For each key algorithm, the number of unclaimed one-time keys /// of that type currently held on the server for this device. + /// If an algorithm is not listed, the count for that algorithm + /// is to be assumed zero. QHash<QString, int> oneTimeKeyCounts() const { return loadFromJson<QHash<QString, int>>("one_time_key_counts"_ls); @@ -47,7 +68,7 @@ public: * * Returns the current devices and identity keys for the given users. */ -class QueryKeysJob : public BaseJob { +class QUOTIENT_API QueryKeysJob : public BaseJob { public: // Inner data structures @@ -114,6 +135,38 @@ public: return loadFromJson<QHash<QString, QHash<QString, DeviceInformation>>>( "device_keys"_ls); } + + /// Information on the master cross-signing keys of the queried users. + /// A map from user ID, to master key information. For each key, the + /// information returned will be the same as uploaded via + /// `/keys/device_signing/upload`, along with the signatures + /// uploaded via `/keys/signatures/upload` that the requesting user + /// is allowed to see. + QHash<QString, CrossSigningKey> masterKeys() const + { + return loadFromJson<QHash<QString, CrossSigningKey>>("master_keys"_ls); + } + + /// Information on the self-signing keys of the queried users. A map + /// from user ID, to self-signing key information. For each key, the + /// information returned will be the same as uploaded via + /// `/keys/device_signing/upload`. + QHash<QString, CrossSigningKey> selfSigningKeys() const + { + return loadFromJson<QHash<QString, CrossSigningKey>>( + "self_signing_keys"_ls); + } + + /// Information on the user-signing key of the user making the + /// request, if they queried their own device information. A map + /// from user ID, to user-signing key information. The + /// information returned will be the same as uploaded via + /// `/keys/device_signing/upload`. + QHash<QString, CrossSigningKey> userSigningKeys() const + { + return loadFromJson<QHash<QString, CrossSigningKey>>( + "user_signing_keys"_ls); + } }; template <> @@ -139,7 +192,7 @@ struct JsonObjectConverter<QueryKeysJob::DeviceInformation> { * * Claims one-time keys for use in pre-key messages. */ -class ClaimKeysJob : public BaseJob { +class QUOTIENT_API ClaimKeysJob : public BaseJob { public: /*! \brief Claim one-time encryption keys. * @@ -174,9 +227,12 @@ public: /// /// See the [key algorithms](/client-server-api/#key-algorithms) section for /// information on the Key Object format. - QHash<QString, QHash<QString, QVariant>> oneTimeKeys() const + /// + /// If necessary, the claimed key might be a fallback key. Fallback + /// keys are re-used by the server until replaced by the device. + QHash<QString, QHash<QString, OneTimeKeys>> oneTimeKeys() const { - return loadFromJson<QHash<QString, QHash<QString, QVariant>>>( + return loadFromJson<QHash<QString, QHash<QString, OneTimeKeys>>>( "one_time_keys"_ls); } }; @@ -193,14 +249,14 @@ public: * * added new device identity keys or removed an existing device with * identity keys, between `from` and `to`. */ -class GetKeysChangesJob : public BaseJob { +class QUOTIENT_API GetKeysChangesJob : public BaseJob { public: /*! \brief Query users with recent device key updates. * * \param from * The desired start point of the list. Should be the `next_batch` field * from a response to an earlier call to - * [`/sync`](/client-server-api/#get_matrixclientr0sync). Users who have not + * [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not * uploaded new device identity keys since this point, nor deleted * existing devices with identity keys since then, will be excluded * from the results. @@ -208,7 +264,7 @@ public: * \param to * The desired end point of the list. Should be the `next_batch` * field from a recent call to - * [`/sync`](/client-server-api/#get_matrixclientr0sync) - typically the + * [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the * most recent such call. This may be used by the server as a hint to check * its caches are up to date. */ |