> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Encrypting and decrypting files

> Learn how to encrypt and decrypt files using the Documents plugin via Kafka messaging.

## Overview

The Documents plugin provides file encryption and decryption capabilities through Kafka messaging. This feature allows you to:

* **Encrypt files** - Password-protect one or multiple files stored in the Documents plugin
* **Decrypt files** - Unlock password-protected files and extract contents from encrypted ZIP archives

Both operations are triggered via Kafka messages. Internal HTTP endpoints are also available for testing purposes.

### Supported file types

| Format | Extensions |
| - | - |
| PDF | `.pdf` |
| Microsoft Word | `.doc`, `.docx` |
| Microsoft Excel | `.xls`, `.xlsx` |
| ZIP | `.zip` |

> [!NOTE]
>
> When encrypting multiple files, they are automatically bundled into a password-protected ZIP archive. During decryption, ZIP archives are extracted and only files matching supported types are returned.

## Prerequisites

Before using the encryption/decryption features, ensure:

> [!TIP]
>
> The Documents plugin is deployed and configured in your environment

> [!TIP]
>
> Files are already uploaded to the Documents plugin (you'll need file IDs)

> [!TIP]
>
> Kafka topics are properly configured

## Kafka topics

The encryption and decryption operations use dedicated Kafka topics for communication between the FlowX Engine and the Documents plugin.

### Topic configuration

| Environment Variable | Default Topic Name | Direction | Description |
| - | - | - | - |
| `KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_IN` | `ai.flowx.plugin.document.trigger.encrypt.file.v1` | Inbound | Topic for encryption requests |
| `KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_IN` | `ai.flowx.plugin.document.trigger.decrypt.file.v1` | Inbound | Topic for decryption requests |
| `KAFKA_TOPIC_DOCUMENT_ENCRYPT_FILE_OUT` | `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1` | Outbound | Topic for encryption results |
| `KAFKA_TOPIC_DOCUMENT_DECRYPT_FILE_OUT` | `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1` | Outbound | Topic for decryption results |

> [!TIP]
>
> To find the configured topic names in your environment:
>
> 1. Navigate to **FlowX Designer → Platform Status**
> 2. Locate **document-plugin-mngt** in the components list
> 3. Click the eye icon and expand **KafkaTopicsHealthCheckIndicator → details → configuration → topic → document**

***

## Encrypting files

Use file encryption to password-protect documents stored in the Documents plugin.

### How encryption works

1. The plugin validates that all specified file(s) exist
2. Validates that files are of supported types
3. Downloads the file(s) from storage
4. Creates a password-protected copy:
   * **Single file**: Creates an encrypted copy with a new file ID
   * **Multiple files**: Creates a ZIP archive containing all files, then password-protects the ZIP
5. Returns the file ID of the encrypted document

### Request message structure

Configure a **Send Message Task** node with a Kafka Send action to trigger file encryption.

**Topic**: Use the encryption inbound topic (e.g., `ai.flowx.plugin.document.trigger.encrypt.file.v1`)

**Request body**:

```json theme={"dark"}
{
  "fileIds": ["file-id-1", "file-id-2"],
  "password": "your-secure-password"
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileIds` | Array of strings | Yes | List of file IDs to encrypt (files must exist in Documents plugin) |
| `password` | String | No | Password for encryption. If null, creates an unprotected archive for multiple files |

### Response message structure

Configure a **Receive Message Task** node to receive the encryption result.

**Topic**: Use the encryption outbound topic (e.g., `ai.flowx.engine.receive.plugin.document.encrypt.file.results.v1`)

**Response body**:

```json theme={"dark"}
{
  "status": "success",
  "message": null,
  "fileId": "encrypted-file-id-123"
}
```

| Parameter | Type | Description |
| - | - | - |
| `status` | String | Operation result: `success`, `partial_success`, `error`, or `no-op` |
| `message` | String | Additional information (populated in case of errors or partial success) |
| `fileId` | String | The file ID of the newly created encrypted file |

### Example: Encrypt a single file

**1. Add a Send Message Task node**

Configure a Kafka Send action with the encryption topic and the following message body:

```json theme={"dark"}
{
  "fileIds": ["${uploadedDocument.fileId}"],
  "password": "${encryptionPassword}"
}
```

**2. Add a Receive Message Task node**

Configure the node to listen on the encryption results topic to capture the encrypted file ID.

**3. Store the encrypted file ID**

Use the response `fileId` for subsequent operations (e.g., sending via email, downloading).

***

## Decrypting files

Use file decryption to unlock password-protected documents and extract contents from encrypted archives.

### How decryption works

1. The plugin validates that the specified file exists
2. Validates that the file is of a supported type
3. Downloads the file from storage
4. Attempts to open the file:
   * First tries without a password
   * If that fails, uses the provided password
5. If the file is a ZIP archive, extracts its contents
6. Filters extracted files by supported types
7. Uploads the resulting file(s) to storage
8. Returns the file ID(s) of the decrypted/extracted files

### Request message structure

Configure a **Send Message Task** node with a Kafka Send action to trigger file decryption.

**Topic**: Use the decryption inbound topic (e.g., `ai.flowx.plugin.document.trigger.decrypt.file.v1`)

**Request body**:

```json theme={"dark"}
{
  "fileId": "encrypted-file-id-123",
  "password": "your-secure-password"
}
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | String | Yes | The file ID of the encrypted file to decrypt |
| `password` | String | No | Password for decryption. If the file is not password-protected, this can be null |

### Response message structure

Configure a **Receive Message Task** node to receive the decryption result.

**Topic**: Use the decryption outbound topic (e.g., `ai.flowx.engine.receive.plugin.document.decrypt.file.results.v1`)

**Response body**:

```json theme={"dark"}
{
  "status": "success",
  "message": null,
  "fileIds": ["decrypted-file-id-1", "decrypted-file-id-2"]
}
```

| Parameter | Type | Description |
| - | - | - |
| `status` | String | Operation result: `success`, `partial_success`, `error`, or `no-op` |
| `message` | String | Additional information (populated in case of errors or partial success) |
| `fileIds` | Array of strings | List of file IDs for the decrypted/extracted files |

> [!NOTE]
>
> When decrypting a ZIP archive, the response contains multiple file IDs—one for each extracted file that matches supported file types.

### Example: Decrypt a password-protected file

**1. Add a Send Message Task node**

Configure a Kafka Send action with the decryption topic and the following message body:

```json theme={"dark"}
{
  "fileId": "${encryptedDocument.fileId}",
  "password": "${userProvidedPassword}"
}
```

**2. Add a Receive Message Task node**

Configure the node to listen on the decryption results topic.

**3. Process the decrypted files**

The response `fileIds` array contains all successfully decrypted files. Use these IDs for further document processing.

***

## Error handling

Both encryption and decryption operations return descriptive error messages when issues occur.

### Common error scenarios

| Scenario | Status | Description |
| - | - | - |
| All files processed | `success` | All files were encrypted/decrypted successfully |
| Some files failed | `partial_success` | Some files were processed but others failed (e.g., unsupported type in a batch) |
| File not found | `error` | The specified file ID does not exist in the Documents plugin |
| Unsupported file type | `error` | The file format is not supported for encryption/decryption |
| Invalid password | `error` | The provided password is incorrect (decryption only) |
| No files to process | `no-op` | Empty file list provided or all files filtered out |

### Example error response

```json theme={"dark"}
{
  "status": "error",
  "message": "File with ID 'invalid-id-123' not found",
  "fileId": null
}
```

> [!WARNING]
>
> Always implement error handling in your process flow to gracefully manage encryption/decryption failures. Check the `status` field before proceeding with subsequent operations.

***

## Security considerations

> [card] Password handling
>
> In the current version, passwords are transmitted in clear text. Ensure your Kafka communication is secured with TLS encryption.

> [card] File storage
>
> Encrypted files are stored as new documents with unique file IDs. Original files remain unchanged.

***

## Related documentation

> [card] [Documents plugin overview](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/documents-plugin-overview.md)
>
> Learn about all Documents plugin capabilities

> [card] [Documents plugin setup](https://docs.flowx.ai/6.x/setup-guides/documents-plugin-setup.md)
>
> Configure the Documents plugin in your environment

> [card] [Uploading files](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/uploading-a-new-document.md)
>
> Upload files to the Documents plugin before encryption

> [card] [Kafka Send action](https://docs.flowx.ai/6.x/docs/building-blocks/actions/kafka-send-action.md)
>
> Configure Kafka Send actions in your process


## Related topics

- [File Storage](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/file-storage.md)
- [File download](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-download.md)
- [Deleting files](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/deleting-a-file.md)
- [File preview](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/file-preview.md)
- [Combining files](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/content-management/documents-plugin/combining-files.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.