> ## 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`          |

<Info>
  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.
</Info>

## Prerequisites

Before using the encryption/decryption features, ensure:

<Check>The Documents plugin is deployed and configured in your environment</Check>
<Check>Files are already uploaded to the Documents plugin (you'll need file IDs)</Check>
<Check>Kafka topics are properly configured</Check>

## 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**
</Tip>

***

## 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={"system"}
{
  "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={"system"}
{
  "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

<Steps>
  <Step title="Add a Send Message Task node">
    Configure a Kafka Send action with the encryption topic and the following message body:

    ```json theme={"system"}
    {
      "fileIds": ["${uploadedDocument.fileId}"],
      "password": "${encryptionPassword}"
    }
    ```
  </Step>

  <Step title="Add a Receive Message Task node">
    Configure the node to listen on the encryption results topic to capture the encrypted file ID.
  </Step>

  <Step title="Store the encrypted file ID">
    Use the response `fileId` for subsequent operations (e.g., sending via email, downloading).
  </Step>
</Steps>

***

## 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={"system"}
{
  "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={"system"}
{
  "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.
</Note>

### Example: Decrypt a password-protected file

<Steps>
  <Step title="Add a Send Message Task node">
    Configure a Kafka Send action with the decryption topic and the following message body:

    ```json theme={"system"}
    {
      "fileId": "${encryptedDocument.fileId}",
      "password": "${userProvidedPassword}"
    }
    ```
  </Step>

  <Step title="Add a Receive Message Task node">
    Configure the node to listen on the decryption results topic.
  </Step>

  <Step title="Process the decrypted files">
    The response `fileIds` array contains all successfully decrypted files. Use these IDs for further document processing.
  </Step>
</Steps>

***

## 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={"system"}
{
  "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.
</Warning>

***

## Security considerations

<CardGroup cols={2}>
  <Card title="Password handling" icon="key">
    In the current version, passwords are transmitted in clear text. Ensure your Kafka communication is secured with TLS encryption.
  </Card>

  <Card title="File storage" icon="database">
    Encrypted files are stored as new documents with unique file IDs. Original files remain unchanged.
  </Card>
</CardGroup>

***

## Related documentation

<CardGroup cols={2}>
  <Card title="Documents plugin overview" icon="file" href="../documents-plugin-overview">
    Learn about all Documents plugin capabilities
  </Card>

  <Card title="Documents plugin setup" icon="gear" href="/setup-guides/documents-plugin-setup">
    Configure the Documents plugin in your environment
  </Card>

  <Card title="Uploading files" icon="upload" href="./uploading-a-new-document">
    Upload files to the Documents plugin before encryption
  </Card>

  <Card title="Kafka Send action" icon="paper-plane" href="/docs/building-blocks/actions/kafka-send-action">
    Configure Kafka Send actions in your process
  </Card>
</CardGroup>