wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

refactor encrypted file schema as "Extension to m.message"

Browse source
This commit is contained in:
Hubert Chathi 2018-08-31 12:11:27 -04:00
parent 28ced3b0a4
commit e3daf10bb9
9 changed files with 161 additions and 170 deletions
Download patch file Download diff file Expand all files Collapse all files

55
event-schemas/examples/m.room.message.encrypted_file
View file

@ -1,55 +0,0 @@
{
"age": 146,
"content": {
"body": "something-important.doc",
"filename": "something-important.doc",
"file": {
"url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe",
"mimetype": "application/msword",
"v": "v2",
"key": {
"alg": "A256CTR",
"ext": true,
"k": "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0",
"key_ops": ["encrypt","decrypt"],
"kty": "oct"
},
"iv": "w+sE15fzSc0AAAAAAAAAAA",
"hashes": {
"sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA"
}
},
"info": {
"mimetype": "application/msword",
"size": 46144,
"thumbnail_file": {
"hashes": {
"sha256": "/NogKqW5bz/m8xHgFiH5haFGjCNVmUIPLzfvOhHdrxY"
},
"iv": "U+k7PfwLr6UAAAAAAAAAAA",
"key": {
"alg": "A256CTR",
"ext": true,
"k": "RMyd6zhlbifsACM1DXkCbioZ2u0SywGljTH8JmGcylg",
"key_ops": ["encrypt", "decrypt"],
"kty": "oct"
},
"mimetype": "image/jpeg",
"url": "mxc://localhost/pmVJxyxGlmxHposwVSlOaEOv",
"v": "v2"
},
"thumbnail_info": {
"h": 768,
"mimetype": "image/jpeg",
"size": 211009,
"w": 432
}
},
"msgtype": "m.file"
},
"event_id": "$143273582443PhrSn:localhost",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:localhost",
"type": "m.room.message",
"sender": "@example:localhost"
}

6
event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml
View file

@ -20,6 +20,12 @@ properties:
thumbnail_url:
description: The URL to a thumbnail of the image.
type: string
thumbnail_file:
description: |-
Information on the encrypted thumbnail file, as specified in
|encrypted_files|_.
title: EncryptedFile
type: object
thumbnail_info:
allOf:
- $ref: thumbnail_info.yaml

9
event-schemas/schema/m.room.message#m.audio
View file

@ -27,12 +27,17 @@ properties:
- m.audio
type: string
url:
description: The URL to the audio clip.
description: Required if the file is not encrypted. The URL to the audio clip.
type: string
file:
description: |-
Required if the file is encrypted. Information on the encrypted
file, as specified in |encrypted_files|_.
title: EncryptedFile
type: object
required:
- msgtype
- body
- url
type: object
type:
enum:

15
event-schemas/schema/m.room.message#m.file
View file

@ -23,6 +23,12 @@ properties:
thumbnail_url:
description: The URL to the thumbnail of the file.
type: string
thumbnail_file:
description: |-
Information on the encrypted thumbnail file, as specified in
|encrypted_files|_.
title: EncryptedFile
type: object
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
@ -34,12 +40,17 @@ properties:
- m.file
type: string
url:
description: The URL to the file.
description: Required if the file is unencrypted. The URL to the file.
type: string
file:
description: |-
Required if the file is encrypted. Information on the encrypted
file, as specified in |encrypted_files|_.
title: EncryptedFile
type: object
required:
- msgtype
- body
- url
- filename
type: object
type:

9
event-schemas/schema/m.room.message#m.image
View file

@ -17,12 +17,17 @@ properties:
- m.image
type: string
url:
description: The URL to the image.
description: Required if the file is unencrypted. The URL to the image.
type: string
file:
description: |-
Required if the file is encrypted. Information on the encrypted
file, as specified in |encrypted_files|_.
title: EncryptedFile
type: object
required:
- msgtype
- body
- url
type: object
type:
enum:

6
event-schemas/schema/m.room.message#m.location
View file

@ -21,6 +21,12 @@ properties:
thumbnail_url:
description: The URL to a thumbnail of the location being represented.
type: string
thumbnail_file:
description: |-
Information on the encrypted thumbnail file, as specified in
|encrypted_files|_.
title: EncryptedFile
type: object
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml

15
event-schemas/schema/m.room.message#m.video
View file

@ -29,6 +29,12 @@ properties:
thumbnail_url:
description: The URL to an image thumbnail of the video clip.
type: string
thumbnail_file:
description: |-
Information on the encrypted thumbnail file, as specified in
|encrypted_files|_.
title: EncryptedFile
type: object
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
@ -40,12 +46,17 @@ properties:
- m.video
type: string
url:
description: The URL to the video clip.
description: Required if the file is unencrypted. The URL to the video clip.
type: string
file:
description: |-
Required if the file is encrypted. Information on the encrypted
file, as specified in |encrypted_files|_.
title: EncryptedFile
type: object
required:
- msgtype
- body
- url
type: object
type:
enum:

100
event-schemas/schema/m.room.message.encrypted_file
View file

@ -1,100 +0,0 @@
---
allOf:
- $ref: core-event-schema/room_event.yaml
description: |-
This message represents an encrypted generic file, corresponding to a
plaintext ``m.file`` message. ``m.image``, ``m.video`` and ``m.audio`` can be
sent encrypted using the same structure.
properties:
content:
properties:
body:
description: |-
A human-readable description of the file. This is recommended to be
the filename of the original upload.
type: string
filename:
description: The original filename of the uploaded file.
type: string
info:
description: Information about the file referred to in ``file``.
properties:
mimetype:
description: The mimetype of the file e.g. ``application/msword``.
type: string
size:
description: The size of the file in bytes.
type: integer
thumbnail_file:
description: The URL to the thumbnail of the file.
title: EncryptedFile
type: object
thumbnail_info:
allOf:
- $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
description: Metadata about the image referred to in ``thumbnail_url``.
title: FileInfo
type: object
msgtype:
enum:
- m.file
type: string
file:
description: Information needed to decrypt the file.
properties:
url:
description: The URL to the file.
type: string
key:
description: A `JSON web key`_ object.
type: object
title: JWK
properties:
kty:
description: Key type. Must be ``oct``.
type: string
key_ops:
description: |-
Key operations. Must at least contain ``encrypt`` and ``decrypt``.
type: array
items:
type: string
alg:
description: Algorithm. Must be ``A256CTR``.
type: string
k:
description: The key, encoded as urlsafe unpadded base64.
type: string
ext:
description: Extractable. Must be ``true``. This is a `W3C extension`_.
type: boolean
iv:
description: |-
The Initialisation Vector used by AES-CTR, encoded as unpadded
base64.
type: string
hashes:
description: |-
A map from an algorithm name to a hash of the ciphertext, encoded
as unpadded base64. Clients should support the SHA-256 hash.
type: object
additionalProperties:
type: string
v:
description: Version of the encrypted attachments protocol.
type: string
enum: ["v2"]
title: EncryptedFile
type: object
required:
- msgtype
- body
- file
- filename
type: object
type:
enum:
- m.room.message
type: string
title: EncryptedFileMessage
type: object

116
specification/modules/end_to_end_encryption.rst
View file

@ -250,14 +250,116 @@ the decrypted file.
A hash of the ciphertext must also be included, in order to prevent the homeserver from
changing the file content.
A client should send the data as a ``m.room.message`` event, using either
``m.file`` as the msgtype, or the appropriate msgtype for the file type. The
structure is similar to an unencrypted file message, except for two differing
keys: ``url`` and ``thumbnail_url`` are replaced respectively by ``file`` and
``thumbnail_file``, containing an ``EncryptedFile`` object as specified below.
The key is sent using the `JSON Web Key`_ format, with a `W3C extension`_.
A client should send the data as an encrypted ``m.room.message`` event, using
either ``m.file`` as the msgtype, or the appropriate msgtype for the file
type. The key is sent using the `JSON Web Key`_ format, with a `W3C
extension`_.
{{m_room_message_encrypted_file_event}}
.. anchor for link from m.message api spec
.. |encrypted_files| replace:: End-to-end encryption
.. _encrypted_files:
Extensions to ``m.message`` msgtypes
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This module adds ``file`` and ``thumbnail_file`` properties to ``m.message``
msgtypes that reference files, such as ``m.file`` and ``m.image``, replacing
the ``url`` and ``thumbnail_url`` properties.
.. todo: generate this from a swagger definition?
``EncryptedFile``
========= ================ =====================================================
Parameter Type Description
========= ================ =====================================================
url string The URL to the file.
key JWK A `JSON Web Key`_ object.
iv string The Initialisation Vector used by AES-CTR, encoded as
unpadded base64.
hashes {string: string} A map from an algorithm name to a hash of the
ciphertext, encoded as unpadded base64. Clients
should support the SHA-256 hash, which uses the key
``sha256``.
v string Version of the encrypted attachments protocol. Must
be ``v2``.
========= ================ =====================================================
``JWK``
========= ========= ============================================================
Parameter Type Description
========= ========= ============================================================
key string Key type. Must be ``oct``.
key_opts [string] Key operations. Must at least contain ``encrypt`` and
``decrypt``.
alg string Algorithm. Must be ``A256CTR``.
k string The key, encoded as urlsafe unpadded base64.
ext boolean Extractable. Must be ``true``. This is a `W3C extension`_.
========= ========= ============================================================
Example:
.. code :: json
{
"content": {
"body": "something-important.jpg",
"file": {
"url": "mxc://domain.com/FHyPlCeYUSFFxlgbQYZmoEoe",
"mimetype": "image/jpeg",
"v": "v2",
"key": {
"alg": "A256CTR",
"ext": true,
"k": "aWF6-32KGYaC3A_FEUCk1Bt0JA37zP0wrStgmdCaW-0",
"key_ops": ["encrypt","decrypt"],
"kty": "oct"
},
"iv": "w+sE15fzSc0AAAAAAAAAAA",
"hashes": {
"sha256": "fdSLu/YkRx3Wyh3KQabP3rd6+SFiKg5lsJZQHtkSAYA"
}
},
"info": {
"mimetype": "image/jpeg",
"h": 1536,
"size": 422018,
"thumbnail_file": {
"hashes": {
"sha256": "/NogKqW5bz/m8xHgFiH5haFGjCNVmUIPLzfvOhHdrxY"
},
"iv": "U+k7PfwLr6UAAAAAAAAAAA",
"key": {
"alg": "A256CTR",
"ext": true,
"k": "RMyd6zhlbifsACM1DXkCbioZ2u0SywGljTH8JmGcylg",
"key_ops": ["encrypt", "decrypt"],
"kty": "oct"
},
"mimetype": "image/jpeg",
"url": "mxc://domain.com/pmVJxyxGlmxHposwVSlOaEOv",
"v": "v2"
},
"thumbnail_info": {
"h": 768,
"mimetype": "image/jpeg",
"size": 211009,
"w": 432
},
"w": 864
},
"msgtype": "m.image"
},
"event_id": "$143273582443PhrSn:domain.com",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:domain.com",
"sender": "@example:domain.com",
"type": "m.room.message",
"unsigned": {
"age": 1234
}
}
Claiming one-time keys
~~~~~~~~~~~~~~~~~~~~~~