Composer 中的 ThingWorx 模型定義 > 安全性 > 安全性管理工具
安全性管理工具
「安全性管理工具」是管理 ThingWorx 軟體使用之安全資訊的一種方法。此工具可對來自這些產品組態檔案的任何金鑰值進行加密，例如資料庫與授權密碼。您可將此工具與任何 ThingWorx 應用程式搭配使用，此工具受 ThingWorx Platform、連線伺服器、ThingWorx Azure IoT Hub Connector v.3.0.0、ThingWorx Edge MicroServer (EMS)、Integration Runtime 等產品支援。
「安全性管理工具」可與 PFX 金鑰庫檔案搭配使用，且會針對密碼使用 AES 加密。使用 AES 加密需要 8U141 以上的 Java 版本。
如果您擁有現有 .JKS keystore，應採取動作來升級至 .PFX keystore。只要 CLI 針對任何 JKS keystore 執行，就會發生這種情況。建立之後，您可移除 keystore 的 JKS 版本；但我們建議進行備份，以免發生問題。
Keystore conf 檔案將依現狀運作，但應予以更新，以將 keystore 名稱設定為不含副檔名的檔案名稱，以減少額外處理。
位置
此工具可在 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>
載入組態。
createTokenFile<路徑><權杖>
建立權杖檔案。
* 
此選項可在安全性管理工具的 1.3.1+ 版中找到。
密碼管理指令
指令
描述
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 憑證載入至金鑰庫。
import <協調-金鑰庫-組態>
將密碼從檔案匯入至密碼提供者。
* 
此選項可在安全性管理工具的 1.3.1+ 版中找到。
範例使用關係
在下列範例中，指令行沒有組態：

./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. 重新啟動應用程式以載入新金鑰庫密碼。
這是否有幫助?