Download received files

Download and decrypt the attachments of a received message.

Prerequisites

A message read successfully (status 200): see Read a message. The files are in the response's FilesMetaData.

Important

Use an up-to-date SDK. Each file name is chosen by the sender: the SDK reduces it to a plain file name inside your reception folder, then checks the SHA-512 hash of the rebuilt file. Versions released before this fix did not.

Example

SecureFiles files = response.FilesMetaData;   // GetMessage response, status 200
if (files?.Files != null && files.Files.Count > 0)
{
    var fileHelper = new FileHelper();
    List<DownloadedFileWithMetaData> received = fileHelper.PrepareFileToDownload(files, receptionFolder);
    fileHelper.DownloadSecureFiles(files, received);

    if (received.Count != files.Files.Count)
        logger.LogWarning("Some files could not be prepared");

    foreach (DownloadedFileWithMetaData f in received)
    {
        if (!f.Success)
            logger.LogWarning("File rejected: incomplete or altered download");
    }
}

from secure_exchanges_sdk.helpers.file_helper import FileHelper

files = response.secure_files  # get_message response, status 200
if files is not None and files.files:
    for f in FileHelper().download_secure_files(files, reception_folder):
        if not f.success:
            logger.warning("File rejected: incomplete or altered download")

use SecureExchanges\SDK\Helpers\FileHelper;

$files = $response->secureFiles;   // getMessage response, status 200
if ($files !== null && $files->files !== []) {
    foreach ((new FileHelper())->downloadSecureFiles($files, $receptionFolder) as $f) {
        if (!$f->success) {
            $logger->warning('File rejected: incomplete or altered download');
        }
    }
}

The result

One item per file:

Field	Content
`Success`	The file is downloaded and decrypted. Test it for each file: the call itself does not raise errors.
`FilePath`	Path of the decrypted file.
`MimeType`	File type, as declared by the sender.

The SDK checks the SHA-512 hash of the rebuilt file: an altered file is deleted and Success is false. A file sent without a hash is downloaded without this check.

The reception folder

Dedicated folder. Outside your website's root, accessible only to the service account. Create it yourself with those rights before the first download: the SDK creates it if missing, but with default rights (0755 in PHP).
Plain-text files. Decrypted files are written in plain text: process them, then delete them, or keep them encrypted. See Encryption.
Temporary files. The SDK writes encrypted chunks in the same folder. They are deleted after the file is rebuilt, but kept on failure: clean the folder regularly.
Same name. If an identical file already exists, it is kept without a new download. If it differs, the new file gets a name prefixed with an identifier.
Logs. Do not write file names to them: they may contain personal information.

The SDK offers no in-memory download: files always go through the disk.

In preview, the .NET SDK downloads from the SettingsHelper.CustomFileHandler address: set it as described in Credentials and environments.

Common errors

Symptom	Likely cause	Solution
.NET: `NullReferenceException` in `DownloadSecureFiles`	The message has no files (`FilesMetaData` is null)	Test it before the call, as in the example.
Python: `AttributeError` / PHP: `TypeError`	`secure_files` or `secureFiles` is None (null)	Same solution.
`Success` is false	Network failure, folder not writable, or altered file	Check the folder's rights, then download again.
.NET: file not found in preview	Production download address used	Set `SettingsHelper.CustomFileHandler`.
The file has a name prefixed with an identifier	Another file with the same name already existed	Normal: the existing file is not replaced.

Read a message

Table of Contents