From f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 31 Aug 2018 12:59:57 -0400 Subject: [PATCH] add more clarifications --- .../msgtype_infos/image_info.yaml | 6 ++-- event-schemas/schema/m.room.message#m.file | 6 ++-- .../schema/m.room.message#m.location | 6 ++-- event-schemas/schema/m.room.message#m.video | 6 ++-- .../modules/end_to_end_encryption.rst | 36 ++++++++++--------- 5 files changed, 35 insertions(+), 25 deletions(-) diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml index 210c3837..8ff27b1e 100644 --- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml +++ b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml @@ -18,12 +18,14 @@ properties: description: Size of the image in bytes. type: integer thumbnail_url: - description: The URL to a thumbnail of the image. + description: |- + The URL to a thumbnail of the image. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message#m.file index 81f7ace6..2fb4fe50 100644 --- a/event-schemas/schema/m.room.message#m.file +++ b/event-schemas/schema/m.room.message#m.file @@ -21,12 +21,14 @@ properties: description: The size of the file in bytes. type: integer thumbnail_url: - description: The URL to the thumbnail of the file. + description: |- + The URL to the thumbnail of the file. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/event-schemas/schema/m.room.message#m.location b/event-schemas/schema/m.room.message#m.location index 2d01db63..ffc4edce 100644 --- a/event-schemas/schema/m.room.message#m.location +++ b/event-schemas/schema/m.room.message#m.location @@ -19,12 +19,14 @@ properties: type: object properties: thumbnail_url: - description: The URL to a thumbnail of the location being represented. + description: |- + The URL to the thumbnail of the file. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message#m.video index 553678c8..8a66fdeb 100644 --- a/event-schemas/schema/m.room.message#m.video +++ b/event-schemas/schema/m.room.message#m.video @@ -27,12 +27,14 @@ properties: description: The size of the video in bytes. type: integer thumbnail_url: - description: The URL to an image thumbnail of the video clip. + description: |- + The URL to an image thumbnail of the video clip. Only present if the + thumbnail is unencrypted. type: string thumbnail_file: description: |- Information on the encrypted thumbnail file, as specified in - |encrypted_files|_. + |encrypted_files|_. Only present if the thumbnail is encrypted. title: EncryptedFile type: object thumbnail_info: diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 950b3041..c5e40a88 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -262,9 +262,10 @@ extension`_. 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. +This module adds ``file`` and ``thumbnail_file`` properties, of type +``EncryptedFile``, 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? @@ -273,16 +274,16 @@ the ``url`` and ``thumbnail_url`` properties. ========= ================ ===================================================== 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 +url string **Required.** The URL to the file. +key JWK **Required.** A `JSON Web Key`_ object. +iv string **Required.** The Initialisation Vector used by + AES-CTR, encoded as unpadded base64. +hashes {string: string} **Required.** 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``. +v string **Required.** Version of the encrypted attachments + protocol. Must be ``v2``. ========= ================ ===================================================== ``JWK`` @@ -290,12 +291,13 @@ v string Version of the encrypted attachments protocol. Must ========= ========= ============================================================ 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`_. +key string **Required.** Key type. Must be ``oct``. +key_opts [string] **Required.** Key operations. Must at least contain + ``encrypt`` and ``decrypt``. +alg string **Required.** Algorithm. Must be ``A256CTR``. +k string **Required.** The key, encoded as urlsafe unpadded base64. +ext boolean **Required.** Extractable. Must be ``true``. This is a + `W3C extension`_. ========= ========= ============================================================ Example: