A user with multiple devices will have a different key for end-to-end encryption for each device. Other users who want to communicate securely with this user must then verify each key on each of their devices. If Alice has n devices, and Bob has m devices, then for Alice to be able to communicate with Bob on any of their devices, this involves n×m key verifications.
One way in which key verification has historically been addressed is through a web-of-trust system: if Alice trusts Bob, and Bob trusts Carol, then Alice may trust Carol even though Alice is unable to verify Carol's key directly. Cross-signing can be seen as a limited web-of-trust, in which one device can vouch for another device that belongs to the same user. For example if Alice has an Osborne 2 and a PDP-11, and Bob has a Dynabook and a VAX, then Alice can verify her Osborne 2 with her PDP-11 (and vice versa), and Bob can verify his Dynabook with his VAX (and vice versa). When Alice and Bob meet in person, Alice's Osborne 2 can verify Bob's Dynabook (and vice versa). These verifications can be published, which will allow Alice's PDP-11 to trust Bob's VAX (and vice versa) without having them directly verify each other, or even without the PDP-11 having to directly verify any of Bob's devices, or any of Alice's devices having to directly verify Bob's VAX.
See also:
When one device verifies another device, it will publish an attestation (in the form of a signed JSON object) indicating this. Attestations can also be revoked by publishing another signed JSON object. Other devices can use these attestations to trust other devices that have not been directly verified. Users will only be able to see attestations and revocations made by their own devices, or attestations and revocations made between devices belonging to the same user. That is, Alice can see attestations made by her own devices, or attestations made by Bob's devices about Bob's devices, but she cannot see attestations made by Carol's devices about Bob's devices, attestations made by Bob's devices about Carol's devices, nor attestations made by Bob nor Carol about Alice's devices.
Attestations and revocations are published by using the POST /_matrix/client/r0/keys/upload endpoint and are retrieved by using the POST /_matrix/client/r0/keys/query endpoint. When new attestations or revocations
are published, then the user who owns the device that the attestation is about
will be included in the changed array in the device_lists property of the
/sync response for all users that share a room with that user.
Attestations form a directed graph (not necessarily acyclic) in which edges go from the device making the attestation to the device that the attestation is about, as long as the signature is valid, the data in the data in the attestation matches the device key, and there is no corresponding revocation. If Device A can construct a directed path in this graph starting from a device it has verified and ending at Device B, consisting only of devices owned by either Device A's owner or Device B's owner, then it may treat Device B as trusted. Device A may do so automatically, or after prompting the user, or may allow the user to disable this functionality completely.
TODO: should Device A then publish an attestation for Device B?
This proposal will add an additional property to the request body of the POST /_matrix/client/r0/keys/upload
endpoint:
attestations([Attestation](see below)): The attestations or revocations to be published. Attestations that do not come from the user calling the endpoint MUST be discarded.
This proposal will add an additional property to the UnsignedDeviceInfo type
in the POST /_matrix/client/r0/keys/query
endpoint:
-
attestations([Attestation](see below)): The published attestations or revocations for the device. This array MUST only include the attestations or revocations made by devices belonging to the user calling the endpoint, or made by devices belonging to the owner of the device being queried. For example, when Alice calls this endpoint to fetch information about Bob's devices, this array will only include attestations or revocations made by Alice's devices or by Bob's other devices.Attestations that have the same contents (other than the
signaturesproperty) may be combined by the server by changing thesignaturesproperty to include multiple signatures for the given object contents.
Example return value:
{
"failures": {},
"device_keys": {
"@alice:example.com": {
"JLAFKJWSCS": {
"user_id": "@alice:example.com",
"device_id": "JLAFKJWSCS",
"algorithms": [
"m.olm.v1.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"keys": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
"unsigned": {
"device_display_name": "Alice's mobile phone",
"attestations": [
{
"user_id": "@alice:example.com",
"device_id": "JLAFKJWSCS",
"keys": {
"ed25519:JLAFKJWSCS": "base64+encoded+key"
},
"state": "verified",
"signatures": {
"@bob:example.org": {
"ed25519:ABCDEFG": "base64+encoded+signature"
}
}
}
]
}
}
}
}
}TODO: keys/query may need to include devices that have been logged out, in
order to avoid unexpectedly breaking trust chains, so we may want to recommend
that devices remain in the result for n days after they log out? However, we
don't want to other devices to continue to encrypt for that device, so maybe
add a flag saying that it's stale, or put stale devices in a separate parameter
(stale_device_keys instead of device_keys)?
Properties:
user_id(string): Required. The ID of the user whose device has been verifieddevice_id(string): Required. The ID of the device that has been verified.keys({string: string}): Required. The public identity keys that have been verified. This will normally just be the signing key (e.g. the ed25519 key).state(string): Required. The verification state. One of "verified" or "revoked".signatures({string: {string: string}}): A map from user ID, to a map from :<device_id> to the signature. The signature is calculated as described in Signing JSON
Example:
Alice's Osborne 2 verifies Bob's Dynabook
{
"user_id": "@bob:example.com",
"device_id": "ABCDEFG",
"keys": {
"ed25519:ABCDEFG": "base64+encoded+key"
},
"state": "verified",
"signatures": {
"@alice:example.org": {
"ed25519:ZYXWVUT": "base64+encoded+signature"
}
}
}The End-to-End encryption module defines extensions to
/sync.
This proposal will change the description of the changed parameter in the
DeviceLists type defined in those extensions to read:
List of users who have updated their device identity keys, or who now share an encrypted room with the client, or who have received additional attestations or revocations that are visible to the user since the previous sync response.
This proposal will change the [GET /_matrix/client/r0/keys/changes](GET
/_matrix/client/r0/keys/changes) endpoint to include in the changed parameter
of the result users who have new attestations that are visible to the calling
user.
This proposal will add an additional property to the UnsignedDeviceInfo type
in the POST /_matrix/federation/v1/user/keys/query
endpoint:
-
attestations([Attestation](see above)): The published attestations or revocations for the device. This array MUST only include the attestations or revocations made by devices belonging to the owner of the device being queried.Attestations that have the same contents (other than the
signaturesproperty) may be combined by the server by changing thesignaturesproperty to include multiple signatures for the given object contents.
This proposal will add an additional property to the User Device type, for
the devices return parameter in the GET /_matrix/federation/v1/user/devices/{userId}
endpoint:
-
attestations([Attestation](see above)): The published attestations or revocations for the device. This array MUST only include the attestations or revocations made by devices belonging to the owner of the device being queried.Attestations that have the same contents (other than the
signaturesproperty) may be combined by the server by changing thesignaturesproperty to include multiple signatures for the given object contents.
A new field will be added to the m.device_list_update EDU schema:
attestations([Attestation](see above)): The published attestations or revocations for the device. This array MUST only include the attestations or revocations made by devices belonging to the owner of the device being queried.
If an attacker gains access to a device, then they can send revocations for all of the user's other devices, causing it to seem like the device controlled by the attacker is the only valid device. For this reason, revocations should be treated with caution, and may require manual intervention to sort out.
TODO: we probably need to spell out in more detail how revocations should be handled.
Publishing attestations leaks metadata to server operators about what users know each other. In order to address this, clients may give users the option of whether to publish attestations or not.
A malicious hommeserver is able to prevent distribution of revocations. For example, a malicious user who takes control of a user's device and who controls the user's homeserver could prevent revocations on that device from being published, so that other users would not be aware that the device has been compromised.