From 488e55ab2c5c1aa419ad4e79cfcb666c0000aa68 Mon Sep 17 00:00:00 2001 From: Documentation Updater Date: Tue, 28 Nov 2023 18:40:39 +0000 Subject: [PATCH] Updating documentation --- signal-server-openapi.yaml | 213 +++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) diff --git a/signal-server-openapi.yaml b/signal-server-openapi.yaml index 284d1aad6..87a09f9b9 100644 --- a/signal-server-openapi.yaml +++ b/signal-server-openapi.yaml @@ -680,6 +680,122 @@ paths: security: - authenticatedAccount: [] - {} + /v1/archives/media/batch: + put: + tags: + - Archive + summary: Batched backup media + description: | + Copy and re-encrypt media from the attachments cdn into the backup cdn. + + The original already encrypted attachment will be encrypted with the provided key material before being copied + + If the batch request is processed at all, a 207 will be returned and the outcome of each constituent copy will + be provided as a separate entry in the response. + operationId: copyMedia + parameters: + - name: X-Signal-ZK-Auth + in: header + description: Presentation of a ZK backup auth credential acquired from /v1/archives/auth + as a base64 encoded string + required: true + schema: + type: string + - name: X-Signal-ZK-Auth-Signature + in: header + description: Signature of the ZK auth credential's presentation as a base64 + encoded string + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CopyMediaBatchRequest' + required: true + responses: + "207": + description: | + The request was processed and each operation's outcome must be inspected individually. This does NOT necessarily + indicate the operation was a success. + content: + application/json: + schema: + $ref: '#/components/schemas/CopyMediaBatchResponse' + "413": + description: All media capacity has been consumed. Free some space to continue. + "429": + description: Rate limited. + "403": + description: Forbidden. The request had insufficient permissions to perform + the requested action + "401": + description: The provided backup auth credential presentation could not + be verified + "400": + description: Bad arguments. The request may have been made on an authenticated + channel + security: + - authenticatedAccount: [] + - {} + /v1/archives/media: + put: + tags: + - Archive + summary: Backup media + description: | + Copy and re-encrypt media from the attachments cdn into the backup cdn. + + The original, already encrypted, attachment will be encrypted with the provided key material before being copied + + If the destination media already exists, the copy will be skipped and a 200 will be returned. + operationId: copyMedia_1 + parameters: + - name: X-Signal-ZK-Auth + in: header + description: Presentation of a ZK backup auth credential acquired from /v1/archives/auth + as a base64 encoded string + required: true + schema: + type: string + - name: X-Signal-ZK-Auth-Signature + in: header + description: Signature of the ZK auth credential's presentation as a base64 + encoded string + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CopyMediaRequest' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/CopyMediaResponse' + "400": + description: Bad arguments. The request may have been made on an authenticated + channel + "413": + description: All media capacity has been consumed. Free some space to continue. + "410": + description: The source object was not found. + "429": + description: Rate limited. + "403": + description: Forbidden. The request had insufficient permissions to perform + the requested action + "401": + description: The provided backup auth credential presentation could not + be verified + security: + - authenticatedAccount: [] + - {} /v1/archives/auth: get: tags: @@ -3154,6 +3270,103 @@ components: type: integer description: The amount of space used to store media format: int64 + CopyMediaBatchResponse: + type: object + properties: + responses: + type: array + description: Detailed outcome information for each copy request in the batch + items: + $ref: '#/components/schemas/Entry' + Entry: + required: + - mediaId + type: object + properties: + status: + type: integer + description: | + The outcome of the copy attempt. + A 200 indicates the object was successfully copied. + A 400 indicates an invalid argument in the request + A 410 indicates that the source object was not found + format: int32 + failureReason: + type: string + description: "On a copy failure, a detailed failure reason" + cdn: + type: integer + description: The backup cdn where this media object is stored + format: int32 + mediaId: + type: string + description: The mediaId of the object in URL-safe base64 + description: Detailed outcome information for each copy request in the batch + CopyMediaBatchRequest: + required: + - items + type: object + properties: + items: + maxItems: 1000 + minItems: 1 + type: array + description: A list of media objects to copy from the attachments CDN to + the backup CDN + items: + $ref: '#/components/schemas/CopyMediaRequest' + CopyMediaRequest: + required: + - encryptionKey + - hmacKey + - iv + - mediaId + - objectLength + - sourceAttachment + type: object + properties: + sourceAttachment: + $ref: '#/components/schemas/RemoteAttachment' + objectLength: + type: integer + description: The length of the source attachment before the encryption applied + by the copy operation + format: int32 + mediaId: + type: string + description: mediaId to copy on to the backup CDN in URL-safe base64 + hmacKey: + type: string + description: "A 32-byte key for the MAC, base64 encoded" + encryptionKey: + type: string + description: "A 32-byte encryption key for AES, base64 encoded" + iv: + type: string + description: "A 16-byte IV for AES, base64 encoded" + RemoteAttachment: + required: + - cdn + - key + type: object + properties: + cdn: + type: integer + description: The attachment cdn + format: int32 + key: + type: string + description: The attachment key + description: The object on the attachment CDN to copy + CopyMediaResponse: + required: + - cdn + type: object + properties: + cdn: + type: integer + description: The backup cdn where this media object is stored + format: int32 BackupAuthCredential: type: object properties: