Composer 中的 ThingWorx 模型定义 > 安全 > 安全管理工具
安全管理工具
安全管理工具是一种管理 ThingWorx 软件所使用安全信息的方法。该工具可以对这些产品 (如数据库) 的配置文件中以及许可密码中的任何键值进行加密。您可以将此工具与任何 ThingWorx 应用程序一起使用，而且它支持诸如 ThingWorx Platform、 Connection Server、 ThingWorx Azure IoT Hub Connector v.3.0.0、 ThingWorx WebSocket-based Edge MicroServer (WS EMS)、 Integration Runtime 等产品。
ThingWorx 8.5 中的更改
安全管理工具已在 8.5 中升级，以使用 PFX keystore 文件，并且现在对密码使用 AES 加密。使用 AES 加密需要的 Java 版本高于 8U141。
如果您当前使用 .JKS keystore，应采取操作升级到 .PFX keystore。一旦 CLI 针对任何 JKS keystore 运行，即会发生这种情况。keystore 的 JKS 版本在创建完成后可以移除；但是，我们建议对其进行备份，以防出现问题。
Keystore conf 文件将照常工作，但应进行更新，以将 keystore 名称设置为仅文件名，而不使用扩展名，从而减少额外处理。
* 
ThingWorx 8.5 中的更改也意味着对集成连接器的 Integration Runtime 服务的初始设置进行了更改。请参阅 迁移密钥库和密钥库密码。
位置
此工具可在 PTC 软件下载页面同 ThingWorx 软件一起下载。
支持的版本
此工具可与 ThingWorx 8.4.0 及更高版本搭配使用。
权限
此工具仅供管理员使用。需要时可进行安装，用完后可将其移除。
配置
* 
default-encryption-key-length 必须同应用程序配置相匹配。在 ThingWorx 中，它是位于 platform-settings.json 中的 InternalAesCryptographicKeyLength 参数。默认值为 128，但如果您使用的是 Java 1.8.0_162 或更高版本，则可使用 256 位加密。如有必要，您还可以通过更新密钥大小限制的 Java 策略来使用较旧的 Java 版本。
Linux 设置：
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/<path to ThingworxPlatform folder>/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/<path to ThingworxStorage folder>/ThingworxStorage"
name = "keystore"
}
}
}
Windows 设置：
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "C:\\<path to ThingworxPlatform folder>\\ThingworxPlatform"
password-file-name = "keystore-password"
path = "C:\\<path to ThingworxStorage folder>\\ThingworxStorage"
name = "keystore"
}
}
}
使用命令行界面工具
使用命令行界面工具在应用程序之外执行特定操作，以预设置应用程序所需的机密。应用程序脚本 (security-common-cli) 将在 Linux 和 Windows 的分布中提供。命令行界面工具有下面几种运行方法：
• 不使用配置文件 - 无需配置安全管理器即可启动工具，且可运行的命令有限。您必须运行该 init 命令才能配置安全管理器：
# run without providing a config, will have to run init, prompt for input
./security-common-cli
• 将配置文件作为第一个脚本参数 - 工具将启动，并使用指定的配置初始化安全管理器。
# initialize security manager with specified config, prompt for input
./security-common-cli <path to keystore>\keystore.conf
• 使用配置文件和多个其他参数 - 工具在单一使用模式下运行。将运行所提供的操作，然后立即停止运行。这是一种从基本安装程序调用的方法。在命令行上传递包含空格的参数时，必须用单引号括起来，才能将其作为单个参数处理。当该工具在命令行模式下运行时，它仅会在 US 区域设置中运行，以确保操作名称是可预测的。
# run one command and tool exits
./security-common-cli <config file path> <action> <parameters>
./security-common-cli keystore.conf set 'mykeyname' 'some value for my key'
* 
可以对配置文件使用完整路径，或者，当配置文件位于类路径中时，可仅使用配置文件的名称。
常用命令
命令
说明
help 或 ?
显示使用信息。
exit
退出该工具。
config
显示当前配置。
init <config-file>
加载配置。
机密管理命令
命令
说明
keys
机密提供程序中的密钥列表。
get <name>
从密钥提供程序中检索值。
set <name> <Value>
在密钥提供程序中设置值。
remove <name>
从密钥提供程序中删除值。
加密和密钥库命令
命令
说明
generate-key <secret-name>
生成新的加密密钥并将其存储在机密中。
encrypt <encryption-key-name> <secret name> <string>
使用可选密钥加密字符串，并将其存储在机密中。
* 
<encryption-key-name> 是可选的。如果未指定 <encryption-key-name>，则使用默认的内部密钥。文件的大小限制为 10MB。
decrypt<encryption-key-name> <secret name>
使用可选密钥解密存储在机密中的字符串。
* 
<encryption-key-name> 是可选的。如果未指定 <encryption-key-name>，则使用默认的内部密钥。文件的大小限制为 10MB。
encryptFile <encryption-key-name> <source> <destination>
加密源文件并将其写入目标文件，同时将可选密钥存储为机密。
* 
<encryption-key-name> 是可选的。如果未指定 <encryption-key-name>，则使用默认的内部密钥。文件的大小限制为 10MB。
decryptFile <encryption-key-name> <source> <destination>
解密源文件并将其写入目标文件，同时将可选密钥存储为机密。
* 
<encryption-key-name> 是可选的。如果未指定 <encryption-key-name>，则使用默认的内部密钥。文件的大小限制为 10MB。
viewFile <encryption-key-name> <source>
解密源文件并查看内容，同时将可选密钥存储为机密。
* 
<encryption-key-name> 是可选的。如果未指定 <encryption-key-name>，则使用默认的内部密钥。文件的大小限制为 10MB。
migrate <password>
将 KeyStore 迁移到新生成的密码或指定的密码。
addcert <name><path>
将 X.509 许可证加载到密钥库。
示例用法
在以下示例中，命令行上没有任何配置：

./security-common-cli
Not initialized, use 'init <config-file>' to initialize
> init sample-keystore.conf
Loading config from file sample-keystore.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /tmp/keystore
Password File: /tmp/keystore-password
Keystore Password: 47886866662481XXXXX
> get mykey
No value found for mykey
> set mykey "this is the value"
mykey stored
> get mykey
this is the value
> remove mykey
mykey removed
> get mykey
No value found for mykey
> encrypt mykey "this is my value to encrypt"
mykey stored
> get mykey
YVljoGhjNVQjnlo/m8c+FRtZhkOb/rcfioakxxxxxx=
> decrypt mykey
this is my value to encrypt
> remove mykey
mykey removed
> exit
Complete
在下面的示例中，命令行上注释有以下配置文件：
./security-common-cli sample-keystore.conf
Loading config from file sample-keystore.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /tmp/keystore
Password File: /tmp/keystore-password
Keystore Password: 47886866662481XXXXX
> get mykey
No value found for mykey
> set mykey "some test"
mykey stored
> get mykey
some test
> remove mykey
mykey removed
> exit
Complete
在下面的示例中，存在直接命令行更改：
./security-common-cli sample-keystore.conf get mykey
Loading config from file sample-keystore.conf
No value found for mykey
./security-common-cli sample-keystore.conf set mykey "this is the value to set"
Loading config from file sample-keystore.conf
mykey stored
./security-common-cli sample-keystore.conf get mykey
Loading config from file sample-keystore.conf
this is the value to set
用法
KeyStore 提供程序使用加密存储在文件中的安全令牌来使用 KeyStore。写入 KeyStore 的所有数据都将通过密码进行安全存储。第一次启动此提供工具时，将生成随机密码值和 KeyStore 文件 (若尚未存在)。
* 
KeyStore 密码和 KeyStore 文件应仅限于应用程序用户使用。应用程序用户必须具有该文件的读取和写入权限。
要创建用于存储初始数据的 KeyStore 文件，必须使用安全管理工具。
1. 从 PTC 支持站点 (在版本 8.4 或更高版本部分中) 获取 Security Management Tool 压缩文件。
2. 将 ZIP 文件中的内容解压缩至某一目录。
3. 使用您在以下示例中看到的参数创建一个配置文件，并将其放置在 bin 文件夹中。
在本示例中，该文件的文件名为 keystore.conf，该工具的版本为 1.0.0.36，其位于 C:\security-common-cli-1.0.0.36\bin。
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = ":\\<path to ThingworxPlatform folder>\\ThingworxPlatform"
password-file-name = "keystore-password"
path = ":\\<path to ThingworxStorage folder>\\ThingworxStorage"
name = "keystore"
}
}
}
4. 启动命令提示符并转至 security-common-cli-1.0.0.36\bin 位置。
5. 运行
C:\security-common-cli-1.0.0.36\bin> security-common-cli.bat <path to keystore>\keystore.conf
set encrypt.licensing.password "add-password-here"
，将在配置位置处创建密码文件和密钥库。
6. 在 LicensingConnectionSettings 下打开 ThingworxPlatform\platform-settings.json，并将 password 值更改为 encrypt.licensing.password。例如，"password": "encrypt.licensing.password"。此密码指示 ThingWorx 平台在需要时查找密钥库中加密的许可密码。
更改密钥库密码
也可以使用安全管理工具将密钥库密码迁移到新密码。更改密码后，除非重置应用程序 KeyStore 密码，否则应用程序在迁移密钥时将无法再使用密钥。目前，这需要重新启动应用程序。
1. 使用密钥库停止应用程序。
2. 使用 KeyStore 配置运行安全管理工具脚本。
3. 运行 migrate 命令。这将生成新密码，将所有数据移动到新密码，并使用新密码更新安全文件。
4. 重新启动应用程序以加载新的密钥库密码。