Composer 中的 ThingWorx 模型定義 > 安全性 > 安全性管理工具
安全性管理工具
「安全性管理工具」是管理 ThingWorx 軟體使用之安全資訊的一種方法。此工具可對來自這些產品組態檔案的任何金鑰值進行加密，例如資料庫與授權密碼。您可將此工具與任何 ThingWorx 應用程式搭配使用，此工具受 ThingWorx Platform、 連線伺服器、 ThingWorx Azure IoT Hub Connector v.3.0.0、 ThingWorx WebSocket 式 Edge MicroServer (WS EMS)、 Integration Runtime 等產品支援。
ThingWorx 8.5 中的變更
在 8.5 中，安全性管理工具已升級，可使用 PFX keystore 檔案，而且現在會針對密碼使用 AES 加密。使用 AES 加密需要 8U141 以上的 Java 版本。
如果您擁有現有 .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
• 使用組態檔案與多個其他參數 - 工具會在單一使用模式下執行。它會執行提供的動作，然後立即停止執行。這是從基本安裝程式呼叫的方法。當在指令行傳送的參數包含空格時，您必須用單引號將其括住才能作為單一引數處理。在指令行模式下執行時，只能在美國地區設定之下執行，以確保能夠預測動作名稱。
# 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'
* 
如果組態檔案在類別路徑中，您可以使用組態檔案的完整路徑，也可以只使用組態檔案的名稱。
常用指令
指令
描述
helpor ?
顯示使用關係資訊。
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>，則會使用預設內部金鑰。檔案有 10 MB 的大小限制。
decrypt<encryption-key-name> <secret name>
使用選用金鑰解密儲存在密碼中的字串。
* 
<encryption-key-name> 為選填。若未指定 <encryption-key-name>，則會使用預設內部金鑰。檔案有 10 MB 的大小限制。
encryptFile <encryption-key-name> <source> <destination>
使用儲存為密碼的選用金鑰加密來源檔案，並將其寫入目的地。
* 
<encryption-key-name> 為選填。若未指定 <encryption-key-name>，則會使用預設內部金鑰。檔案有 10 MB 的大小限制。
decryptFile <encryption-key-name> <source> <destination>
使用儲存為密碼的選用金鑰解密來源檔案，並將其寫入目的地。
* 
<encryption-key-name> 為選填。若未指定 <encryption-key-name>，則會使用預設內部金鑰。檔案有 10 MB 的大小限制。
viewFile <encryption-key-name> <source>
使用儲存為密碼的選用金鑰解密來源檔案，並檢視內容。
* 
<encryption-key-name> 為選填。若未指定 <encryption-key-name>，則會使用預設內部金鑰。檔案有 10 MB 的大小限制。
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 檔案，您必須使用「安全性管理工具」。
1. 從 PTC 支援網站 (發行版本 8.4 或更新版本部份中) 取得「安全性管理工具」ZIP 檔。
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. 重新啟動應用程式以載入新金鑰庫密碼。