#密钥管理

YahsanDB通过三级密钥体系与钱包机制为数据透明加密提供的密钥管理与安全保障，既能保证密钥的安全，又能兼顾数据加解密的效率。

密钥管理功能不适用于存算一体分布式集群部署。

# 三级密钥体系

三级密钥体系是指采用分层的密钥管理机制来确保数据的保密性、完整性和可用性。这个体系通过三种不同级别的密钥来管理和保护数据，不同级别的密钥各自扮演着不同的角色，层层保护数据的隐私与完整：

主密钥（MEK，Master Encryption Key）：又称一级密钥，是最高级别的密钥，用于加/解密其下一级的全局密钥。由用户手动创建，并通过钱包机制加密持久化在数据库外部的钱包中。
全局密钥（GEK，Global Encryption Key）：又称二级密钥，用于加/解密数据密钥。由数据库按需自动创建，并通过主密钥进行加密后持久化在数据库控制文件中。
数据密钥（DEK，Data Encryption Key）：又称三级密钥，用于加/解密数据库中存储的具体数据（例如表空间、表或列数据）。由数据库按需自动创建，并通过全局密钥进行加密后持久化在数据库中。

# 钱包

钱包（wallet）是一个虚拟容器，用于对数据库安全凭证进行独立的外部存储与管理，并实现数据库集群中各服务器之间密钥共享。钱包中的所有数据都会加密，且需要使用钱包密码对其进行解锁，避免钱包内容被恶意访问。

Caution:

请务必牢记钱包的密码并及时对钱包进行备份，钱包相关数据丢失会导致数据库不可用。

# 配置钱包与主密钥

在单机部署或共享集群部署环境中：

存量加密对象：例如从YashanDB 23.2升级至YashanDB 23.4后，数据库中原有的加密对象无需配置钱包和密钥可继续正常使用。如需为原有加密对象启用密钥管理功能，则需配置并使用钱包。
新增加密对象：需要先配置钱包，并在日常启停数据库时按要求开启钱包。

在存算一体分布式集群部署中，无钱包和密钥管理功能，直接创建并使用加密对象即可。

Note

配置钱包需要重启数据库。

# 本地密钥管理

# 准备工作

在每台数据库服务器上规划并创建钱包文件的存放路径，YashanDB的安装用户（即yashan）需具备对应路径的全部权限，本文以规划在/data/yashan/wallet路径为例。
```
$ cd /data/yashan
$ mkdir wallet
```
Warn:

钱包文件涉及数据安全，请合理规划其存放路径并妥善保管。同时，建议在安全的位置存放多个本地或异地备份。

按需准备钱包主密钥ID所需的值（MKID）和钱包主密钥所需的值（MK），本文以使用openssl工具生成相应值为例：

# 使用openssl工具生成MKID
$ openssl rand -hex 16
1e3eeec2f7cc8af9a919517216e8057d

# 使用openssl工具生成MK
$ openssl rand -hex 32
d8ab781a44b864099a5e607a2063b265d7703f802fcfe7e8334cd8776da44444

确保执行钱包配置的数据库用户具备ADMINISTER KEY MANAGEMENT权限或SYSKM角色，授权操作请查阅管控用户权限。

-- 查看当前用户的权限信息
SELECT PRIVILEGE FROM USER_SYS_PRIVS;
-- 查看当前用户的角色信息
SELECT GRANTED_ROLE FROM USER_ROLE_PRIVS;

# 操作步骤

为数据库的某个节点（例如单机高可用部署的主库、共享集群部署的任一实例）配置钱包的根目录WALLET_ROOT参数。

# 基于节点ID指定目标节点，可执行如下命令获取节点ID值
$ yasboot cluster status -c yashandb -d -p sys_password

# 本文以1-1节点为例
$ yasboot node config set -c yashandb --node-id 1-1 -k WALLET_ROOT -v '/data/yashan/wallet'

重启数据库使配置生效。

$ yasboot cluster restart -c yashandb -d -p sys_password

连接上述节点（1-1节点），查看WALLET_ROOT配置是否生效。

$ yasql sales/********@192.168.1.2:1688

SQL> SHOW PARAMETER WALLET_ROOT

NAME                                                             VALUE                                                  
---------------------------------------------------------------- ----------------------------------------------------------------
WALLET_ROOT                                                      /data/yashan/wallet

执行如下语句创建钱包，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的create_keystore子句。

-- 场景1：若不指定keystore_location，系统会自动在WALLET_ROOT路径下创建子目录/tde和钱包文件
ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY Your_password;

-- 场景2：若指定keystore_location，必须指定为WALLET_ROOT路径的/tde子目录
 ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/data/yashan/wallet/tde' IDENTIFIED BY Your_password;

Caution:

请务必牢记钱包的密码并及时对钱包进行备份，钱包相关数据丢失会导致数据库不可用。

执行如下语句开启钱包，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的open_keystore子句。
```
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY Your_keystore_password;
```

执行如下语句创建并激活主密钥，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的set_key子句。

-- 该语句必须在数据库实例处于OPEN阶段时执行
ADMINISTER KEY MANAGEMENT SET KEY '1e3eeec2f7cc8af9a919517216e8057d:d8ab781a44b864099a5e607a2063b265d7703f802fcfe7e8334cd8776da44444' USING TAG 'myTag' IDENTIFIED BY Your_keystore_password WITH BACKUP;

为主备部署的所有备库、共享集群部署的其他实例配置并开启钱包：
1. ）依次为数据库的其他节点，配置钱包的根目录WALLET_ROOT参数。
```
# 依次指定不同的节点ID执行该命令，直至完成所有节点的对应配置
$ yasboot node config set -c yashandb --node-id 1-2 -k WALLET_ROOT -v '/data/yashan/wallet'   
```
1. ）使用Linux命令复制1-1节点所在服务器WALLET_ROOT路径下的TDE文件夹及其文件至其他节点所在服务器的WALLET_ROOT路径下。
2. ）重启数据库并开启钱包。
```
# 必须指定--wallet-password参数
$ yasboot cluster restart -c yashandb -d -p sys_password --wallet-password Your_keystore_password
```
配置完成，可以使用数据透明加密相关功能。

# 第三方密钥管理

# 准备工作

在每台数据库服务器上规划并创建钱包文件的存放路径，YashanDB的安装用户（即yashan）需具备对应路径的全部权限，本文以规划在/data/yashan/wallet路径为例。
```
$ cd /data/yashan
$ mkdir wallet
```
Warn:

钱包文件涉及数据安全，请合理规划其存放路径并妥善保管。同时，建议在安全的位置存放多个本地或异地备份。

按需准备钱包主密钥ID所需的值（MKID）和钱包主密钥所需的值（MK），本文以使用openssl工具生成相应值为例：

# 使用openssl工具生成MKID
$ openssl rand -hex 16
1e3eeec2f7cc8af9a919517216e8057d

# 使用openssl工具生成MK
$ openssl rand -hex 32
d8ab781a44b864099a5e607a2063b265d7703f802fcfe7e8334cd8776da44444

确保执行钱包配置的数据库用户具备ADMINISTER KEY MANAGEMENT权限或SYSKM角色，授权操作请查阅管控用户权限。

-- 查看当前用户的权限信息
SELECT PRIVILEGE FROM USER_SYS_PRIVS;
-- 查看当前用户的角色信息
SELECT GRANTED_ROLE FROM USER_ROLE_PRIVS;

已在腾讯云密钥管理服务中创建根密钥（操作指引可参考腾讯云KMS官方文档 (opens new window)），并获取如下信息：

Note:

支持对接的腾讯云KMS的API版本号为2019-01-18（或其他兼容版本），具体版本信息请咨询腾讯云官方技术支持。
- KMS服务的API地址，例如https://kms.tencentcloudapi.com/。
- keyId：在KMS中所创建的根密钥ID。
- secretId：创建根密钥的腾讯云账号的云API密钥ID。
- secretKey：创建根密钥的腾讯云账号的云API密钥值。

# 操作步骤

为数据库的某个节点（例如单机高可用部署的主库、共享集群部署的任一实例）配置密钥管理方式TDE_CONFIGURATION参数和钱包的根目录WALLET_ROOT参数。

# 基于节点ID指定目标节点，可执行如下命令获取节点ID值
$ yasboot cluster status -c yashandb -d -p sys_password

# 本文以1-1节点为例
$ yasboot node config set -c yashandb --node-id 1-1 -k TDE_CONFIGURATION -v 'KEYSTORE_CONFIGURATION=FILE;KMS=TRUE' -k WALLET_ROOT -v '/data/yashan/wallet'

重启数据库使配置生效。

$ yasboot cluster restart -c yashandb -d -p sys_password

连接上述节点（1-1节点），查看WALLET_ROOT配置是否生效。

$ yasql sales/********@192.168.1.2:1688

SQL> SHOW PARAMETER WALLET_ROOT

NAME                                                             VALUE                                                  
---------------------------------------------------------------- ----------------------------------------------------------------
WALLET_ROOT                                                      /data/yashan/wallet

执行如下语句创建钱包，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的create_keystore子句。

-- 场景1：若不指定keystore_location，系统会自动在WALLET_ROOT路径下创建子目录/tde和钱包文件
ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY Your_password;

-- 场景2：若指定keystore_location，必须指定为WALLET_ROOT路径的/tde子目录
 ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/data/yashan/wallet/tde' IDENTIFIED BY Your_password;

Caution:

请务必牢记钱包的密码并及时对钱包进行备份，钱包相关数据丢失会导致数据库不可用。

执行如下语句开启钱包，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的open_keystore子句。
```
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY Your_keystore_password;
```

执行如下语句创建并激活主密钥，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的set_key子句。

-- 该语句必须在数据库实例处于OPEN阶段时执行
ADMINISTER KEY MANAGEMENT SET KEY '1e3eeec2f7cc8af9a919517216e8057d:d8ab781a44b864099a5e607a2063b265d7703f802fcfe7e8334cd8776da44444' USING TAG 'myTag' IDENTIFIED BY Your_keystore_password WITH BACKUP;

为主备部署的所有备库、共享集群部署的其他实例配置并开启钱包：

）依次为数据库的其他节点，配置钱包的根目录WALLET_ROOT参数。

# 依次指定不同的节点ID执行该命令，直至完成所有节点的对应配置
$ yasboot node config set -c yashandb --node-id 1-2 -k WALLET_ROOT -v '/data/yashan/wallet'

）使用Linux命令复制1-1节点所在服务器WALLET_ROOT路径下的TDE文件夹及其文件至其他节点所在服务器的WALLET_ROOT路径下。

）重启数据库并开启钱包。

# 必须指定--wallet-password参数
$ yasboot cluster restart -c yashandb -d -p sys_password --wallet-password Your_keystore_password

配置完成，可以使用数据透明加密相关功能。

-- 场景1：若不指定keystore_location，系统会自动在WALLET_ROOT路径下创建子目录/tde和钱包文件
ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY "kms://tencent/?password=Your_password&keyId=6xxxxxxx-xxxx-xxxx-xxxx-5xxxxxxxxc09&secretId=AKID********************************&secretKey=********************************#https://kms.tencentcloudapi.com/";

-- 场景2：若指定keystore_location，必须指定为WALLET_ROOT路径的/tde子目录
 ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/data/yashan/wallet/tde' IDENTIFIED BY "kms://tencent/?password=Your_password&keyId=6xxxxxxx-xxxx-xxxx-xxxx-5xxxxxxxxc09&secretId=AKID********************************&secretKey=********************************#https://kms.tencentcloudapi.com/";

Caution:

请务必牢记钱包的密码并及时对钱包进行备份，钱包相关数据丢失会导致数据库不可用。

执行如下语句开启钱包，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的open_keystore子句。
```
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY Your_keystore_password;
```

执行如下语句创建并激活主密钥，语法详情可查阅ADMINISTER KEY MANAGEMENT语句的set_key子句。

-- 该语句必须在数据库实例处于OPEN阶段时执行
ADMINISTER KEY MANAGEMENT SET KEY '1e3eeec2f7cc8af9a919517216e8057d:d8ab781a44b864099a5e607a2063b265d7703f802fcfe7e8334cd8776da44444' USING TAG 'myTag' IDENTIFIED BY Your_keystore_password WITH BACKUP;

为主备部署的所有备库、共享集群部署的其他实例配置并开启钱包：
1. ）依次为数据库的其他节点，配置钱包的根目录WALLET_ROOT参数。
```
# 依次指定不同的节点ID执行该命令，直至完成所有节点的对应配置
$ yasboot node config set -c yashandb --node-id 1-2 -k WALLET_ROOT -v '/data/yashan/wallet'   
```
1. ）使用Linux命令复制1-1节点所在服务器WALLET_ROOT路径下的TDE文件夹及其文件至其他节点所在服务器的WALLET_ROOT路径下。
2. ）重启数据库并开启钱包。
```
# 必须指定--wallet-password参数
$ yasboot cluster restart -c yashandb -d -p sys_password --wallet-password Your_keystore_password
```
配置完成，可以使用数据透明加密相关功能。

# 日常开启钱包

创建加密对象后，在后续日常使用中必须在启动数据库时指定钱包密码开启钱包：

# 必须指定--wallet-password参数
$ yasboot cluster start -c yashandb -d -p sys_password --wallet-password Your_keystore_password

Caution:

单机（主备）部署/共享集群部署中，必须开启所有节点的钱包，否则可能造成新增加密对象后其他节点因未打开钱包而回放失败，单机（主备）部署中还可能会导致NEED REPAIR，此时需按上述操作步骤配置钱包并重启数据库。

即使后续删除了所有加密对象（表空间、表或列），在启动数据库时仍需指定钱包密码开启钱包。

# 备份钱包

请务必及时对钱包进行备份，钱包相关数据丢失会导致数据库不可用。

执行ADMINISTER KEY MANAGEMENT语句的backup_keystore子句单独备份钱包。

ADMINISTER KEY MANAGEMENT BACKUP KEYSTORE IDENTIFIED BY Your_keystore_password TO '/data/yashan';