Add doc processor_encrypt (#539)

* Add doc processor_encrypt
alibaba · Dec 2, 2022 · ad909ce · ad909ce
1 parent db933ea
commit ad909ce
Show file tree

Hide file tree

Showing 3 changed files with 161 additions and 0 deletions.
diff --git a/docs/cn/SUMMARY.md b/docs/cn/SUMMARY.md
@@ -60,6 +60,7 @@
   * [原始数据](data-pipeline/processor/default.md)
   * [数据脱敏](data-pipeline/processor/processor-desensitize.md)
   * [丢弃字段](data-pipeline/processor/processor-drop.md)
+  * [字段加密](data-pipeline/processor/processor-encrypy.md)
   * [条件字段处理](data-pipeline/processor/fields-with-condition.md)
   * [日志过滤](data-pipeline/processor/processor-filter-regex.md)
   * [Grok](data-pipeline/processor/processor-grok.md)

diff --git a/docs/cn/data-pipeline/overview.md b/docs/cn/data-pipeline/overview.md
@@ -30,6 +30,7 @@
 | `processor_default`<br>原始数据                    | SLS官方                                             | 不对数据任何操作，只是简单的数据透传。           |
 | `processor_desensitize`<br>数据脱敏                    | SLS官方<br>[`Takuka0311`](https://github.com/Takuka0311) | 对敏感数据进行脱敏处理。           |
 | `processor_drop`<br>丢弃字段                       | SLS官方                                             | 丢弃字段。                                       |
+| `processor_encrypt`<br>字段加密                   | SLS官方                                               | 加密字段                                  |
 | `processor_fields_with_conditions`<br>条件字段处理 | 社区<br>[`pj1987111`](https://github.com/pj1987111) | 根据日志部分字段的取值，动态进行字段扩展或删除。 |
 | `processor_filter_regex`<br>日志过滤               | SLS官方                                             | 通过正则匹配过滤日志。                           |
 | `processor_grok`<br>Grok                          ｜ SLS官方<br>[`Takuka0311`](https://github.com/Takuka0311) | 通过 Grok 语法对数据进行处理              |

diff --git a/docs/cn/data-pipeline/processor/processor-encrypy.md b/docs/cn/data-pipeline/processor/processor-encrypy.md
@@ -0,0 +1,159 @@
+# 字段加密
+
+## 简介
+
+`processor_encrypt`插件可以使用 AES-128、AES-192、AES-256 算法对指定的字段加密，采用 PKCS7 填充算法。**由于密文可能包含不可见字符，插件会对其进行十六进制编码。**
+
+### 参数说明
+
+| 参数 | 类型，默认值 | 说明 |
+| - | - | - |
+| Type                      | String，无默认值(必填)                | 插件类型，固定为`processor_encrypt` |
+| SourceKeys                | String[]，无默认值(必填)              | 指定需要加密的字段名，支持指定多个。 |
+| EncryptionParameters      | EncryptionParameter，无默认值(必填)   | 指定加密参数。 |
+| KeepSourceValueIfError    | Boolean，`false`                    | 如果发生加密失败，是否保留原始值，如果不保留的话，字段值会被替换为 `ENCRYPT_ERROR`。为了保护您的数据安全，默认值为 `false`，即失败时进行替换。|
+
+* EncryptionParameter 类型说明
+
+| 参数 | 类型，默认值 | 说明 |
+| - | - | - |
+| Key           | String，无默认值         | 指定密钥（十六进制），未配置 KeyFilePath 时必选。AES-128、AES-192、AES-256 分别要求密钥为 16、24、32 字节，所以直接以此参数指定密钥时，需要填入 32、48、64 个十六进制字符。 |
+| IV            | String，默认全`0`        | 指定加密的初始向量（十六进制），若配置了KeyFilePath可不填写。此参数值大小等于内部 block 大小，AES-128、AES-192、AES-256 下分别为 8、12、16 字节，所以需要填入 16、24、32 个十六进制字符。 |
+| KeyFilePath   | String，无默认值         | 指定保存加密参数的文件路径，未配置 Key 时必选。支持将前述参数（Key、IV）保存至文件（JSON 格式），文件中指定的值会覆盖通过前述参数指定的值。 |
+
+## 样例
+
+### 示例 1：直接指定 Key 且使用默认 IV
+
+对字段 `important` 进行加密，假设密钥（Key）为二进制全 0 组成（256 bits）、不设置初始向量（IV），使用插件默认值，则配置详情及处理结果如下：
+
+* 采集配置
+
+```Yaml
+processors:
+  - Type: processor_encrypt
+    SourceKeys:
+      - "important"
+    EncryptionParameters: 
+      Key: "0000000000000000000000000000000000000000000000000000000000000000"
+```
+
+* 输入
+
+```Json
+"normal_key": "1",
+"another_normal_key": "2",
+"important": "0123456"
+```
+
+* 输出（由于加密后内容包含不可见字符，加密后会将其转换为十六进制）
+
+```Json
+"normal_key": "1",
+"another_normal_key": "2",
+"important": "bc3acdbd40c283d91f7dc7010fd7d2b1"
+```
+
+* 利用 openssl 进行解密
+
+```shell
+$ printf "%b" '\xbc\x3a\xcd\xbd\x40\xc2\x83\xd9\x1f\x7d\xc7\x01\x0f\xd7\xd2\xb1' > ciphertext
+$ openssl enc -d -aes-256-cbc -iv 00000000000000000000000000000000 \
+    -K 0000000000000000000000000000000000000000000000000000000000000000 \
+    -in ciphertext -out plaintext
+$ cat plaintext
+0123456
+```
+
+### 示例 2：直接指定 Key 和 IV
+
+对字段 `important` 进行加密，假设密钥（Key）为二进制全 0 组成（256 bits）、初始向量（IV）为二进制全 1 组成（128 bits），则配置详情及处理结果如下：
+
+* 输入
+
+```Json
+"normal_key": "1",
+"another_normal_key": "2",
+"important": "0123456"
+```
+
+* 配置详情（注意 Key/IV 都是十六进制表示）
+
+```Yaml
+processors:
+  - Type: processor_encrypt
+    SourceKeys:
+      - "important"
+    EncryptionParameters: 
+      Key: "0000000000000000000000000000000000000000000000000000000000000000"
+      IV: "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"
+```
+
+* 输出（由于加密后内容包含不可见字符，加密后会将其转换为十六进制）
+
+```Json
+"normal_key": "1",
+"another_normal_key": "2",
+"important": "af6428af62d698be617b82cffd9e109b"
+```
+
+* 利用 openssl 进行解密
+
+```shell
+$ printf "%b" '\xaf\x64\x28\xaf\x62\xd6\x98\xbe\x61\x7b\x82\xcf\xfd\x9e\x10\x9b' > ciphertext
+$ openssl enc -d -aes-256-cbc -iv FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF \
+    -K 0000000000000000000000000000000000000000000000000000000000000000 \
+    -in ciphertext -out plaintext
+$ cat plaintext
+0123456
+```
+
+### 示例 3：通过文件指定 Key
+
+对字段 `important` 进行加密，假设密钥（Key）为二进制全 1 组成（256 bits），密钥保存在机器的本地文件 `/home/admin/aes_key` 中，文件内容中未指定 IV 参数，使用插件默认值，配置详情及处理结果如下：
+
+* 前置条件
+
+运行 logtail 的机器上需要创建文件 `/home/admin/aes_key.json`（JSON 格式），并将密钥以十六进制存放在其中，命令如下：
+
+```shell
+printf "{\"Key\": \"FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF\"}" > /home/admin/aes_key.json
+```
+
+* 输入
+
+```Json
+"normal_key": "1",
+"another_normal_key": "2",
+"important": "0123456"
+```
+
+* 配置详情
+
+```Yaml
+processors:
+  - Type: processor_encrypt
+    SourceKeys:
+      - "important"
+    EncryptionParameters: 
+      KeyFilePath: "/home/admin/aes_key.json"
+```
+
+* 输出
+
+```Json
+"normal_key": "1",
+"another_normal_key": "2",
+"important": "bc3acdbd40c283d91f7dc7010fd7d2b1"
+```
+
+* 利用 openssl 进行解密
+
+```shell
+$ printf "%b" '\xbc\x3a\xcd\xbd\x40\xc2\x83\xd9\x1f\x7d\xc7\x01\x0f\xd7\xd2\xb1' > ciphertext
+$ openssl enc -d -aes-256-cbc -iv 00000000000000000000000000000000 \
+    -K 0000000000000000000000000000000000000000000000000000000000000000 \
+    -in ciphertext -out plaintext
+$ cat plaintext
+0123456
+```