Definizione del modello ThingWorx in Composer > Protezione > Strumento di gestione della protezione
Strumento di gestione della protezione
Lo strumento di gestione della protezione è un modo per gestire le informazioni protette utilizzate dal software ThingWorx. Lo strumento può crittografare qualsiasi valore di chiave dai file di configurazione per questi prodotti, ad esempio password di database e licenze. Può essere utilizzato con qualsiasi applicazione ThingWorx ed è supportato con prodotti quali ThingWorx Platform, Connection Server, ThingWorx Azure IoT Hub Connector 3.0.0, ThingWorx Edge MicroServer (EMS), Integration Runtime e così via.
Lo strumento di gestione della protezione funziona con i file keystore PFX e utilizza la crittografia AES per i segreti. L'utilizzo della crittografia AES richiede una versione Java superiore a 8U141.
Se si dispone di un keystore .JKS esistente, è necessario eseguire l'aggiornamento a un keystore .PFX. Ciò si verifica quando l'interfaccia della riga di comando viene eseguita su qualsiasi keystore JKS. Una volta creata, la versione JKS del keystore può essere rimossa, sebbene sia consigliabile eseguirne il backup in caso di problemi.
Il file keystore conf funzionerà così com'è, ma deve essere aggiornato per impostare il nome del keystore sul solo nome del file senza l'estensione al fine di ridurre un'elaborazione aggiuntiva.
Ubicazione
Questo strumento è disponibile nella pagina PTC Software Download, con i download del software ThingWorx.
Versioni supportate
Questo strumento può essere utilizzato con ThingWorx 8.4.0 e versioni successive.
Permessi
Questo strumento è inteso solo per l'uso da parte dell'amministratore. Installarlo secondo necessità e rimuoverlo dopo l'uso.
Configurazione
* 
Il parametro default-encryption-key-length deve corrispondere alla configurazione dell'applicazione. In ThingWorx è il parametro InternalAesCryptographicKeyLength situato in platform-settings.json. Il valore di default è 128 ma, se si utilizza Java 1.8.0_162 o versioni successive, è possibile utilizzare la crittografia a 256 bit. Se necessario, è inoltre possibile usare le versioni precedenti di Java aggiornando i criteri di Java per il limite di dimensione della chiave.
Impostazioni di 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"
}
}
}
Impostazioni di 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"
}
}
}
Utilizzo dello strumento della riga di comando
Lo strumento della riga di comando consente di eseguire operazioni specifiche al di fuori dell'applicazione per preimpostare i segreti richiesti da un'applicazione. Lo script dell'applicazione (security-common-cli) viene fornito nella distribuzione per Linux e Windows. Esistono diversi modi per eseguire lo strumento della riga di comando.
• Senza un file di configurazione: lo strumento viene avviato senza la gestione della protezione configurata e i comandi che possono essere eseguiti sono limitati. È necessario eseguire il comando init per configurare la gestione della protezione:
# run without providing a config, will have to run init, prompt for input
./security-common-cli
• Con un file di configurazione come primo parametro dello script: lo strumento viene avviato e la gestione della protezione viene inizializzata con la configurazione specificata.
# initialize security manager with specified config, prompt for input
./security-common-cli <path to keystore>\keystore.conf
• Con un file di configurazione e molti altri parametri: lo strumento viene eseguito in modalità di utilizzo singolo. Esegue l'azione fornita e quindi interrompe immediatamente l'esecuzione. Questo è un modo per chiamare da un programma di installazione di base. Quando sulla riga di comando si trasmettono parametri che contengono uno spazio bianco, è necessario racchiuderli tra virgolette singole affinché vengano elaborati come argomento singolo. Quando viene eseguito nella modalità della riga di comando, viene eseguito solo nelle impostazioni locali degli Stati Uniti per garantire che i nomi delle azioni siano prevedibili.
# 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'
* 
È possibile utilizzare il percorso completo del file di configurazione o solo il nome del file di configurazione, se il file di configurazione si trova nel classpath.
Comandi comuni
Comando
Descrizione
help o ?
Visualizza le informazioni sull'utilizzo.
exit
Chiude lo strumento.
config
Visualizza la configurazione corrente.
init <file-config>
Carica la configurazione.
createTokenFile<percorso><token>
Crea un file di token.
* 
Questa opzione è disponibile nella versione 1.3.1+ dello strumento di gestione della protezione.
Comandi di gestione dei segreti
Comando
Descrizione
keys
Elenco delle chiavi nel provider di segreti.
get <nome>
Recupera un valore dal provider di segreti.
set <nome> <Valore>
Imposta un valore nel provider di segreti.
remove <nome>
Rimuove un valore dal provider di segreti.
Comandi di crittografia e keystore
Comando
Descrizione
generate-key <nome-segreto>
Genera una nuova chiave di crittografia e la memorizza in un segreto.
encrypt <nome-chiave-crittografia> <nome segreto> <stringa>
Crittografa una stringa utilizzando la chiave facoltativa e la memorizza in un segreto.
* 
<nome-chiave-crittografia> è facoltativo. Se <nome-chiave-crittografia> non è specificato, viene utilizzata la chiave interna di default. I file hanno un limite di dimensione pari a 10 MB.
decrypt<nome-chiave-crittografia> <nome segreto>
Decodifica una stringa memorizzata in un segreto utilizzando la chiave facoltativa.
* 
<nome-chiave-crittografia> è facoltativo. Se <nome-chiave-crittografia> non è specificato, viene utilizzata la chiave interna di default. I file hanno un limite di dimensione pari a 10 MB.
encryptFile <nome-chiave-crittografia> <origine> <destinazione>
Crittografa il file di origine e lo scrive nella destinazione con la chiave facoltativa memorizzata come segreto.
* 
<nome-chiave-crittografia> è facoltativo. Se <nome-chiave-crittografia> non è specificato, viene utilizzata la chiave interna di default. I file hanno un limite di dimensione pari a 10 MB.
decryptFile <nome-chiave-crittografia> <origine> <destinazione>
Decrittografa il file di origine e lo scrive nella destinazione con la chiave facoltativa memorizzata come segreto.
* 
<nome-chiave-crittografia> è facoltativo. Se <nome-chiave-crittografia> non è specificato, viene utilizzata la chiave interna di default. I file hanno un limite di dimensione pari a 10 MB.
viewFile <nome-chiave-crittografia> <origine>
Decrittografa il file di origine e visualizza i contenuti con la chiave facoltativa memorizzata come segreto.
* 
<nome-chiave-crittografia> è facoltativo. Se <nome-chiave-crittografia> non è specificato, viene utilizzata la chiave interna di default. I file hanno un limite di dimensione pari a 10 MB.
migrate <password>
Esegue la migrazione del keystore in una nuova password generata o viene specificata una password.
addcert <nome><percorso>
Carica un certificato X.509 nel keystore.
import <config-keystore-orchestrazione>
Importa i segreti dal file al provider di segreti.
* 
Questa opzione è disponibile nella versione 1.3.1+ dello strumento di gestione della protezione.
Esempi di utilizzo
Nell'esempio seguente non è presente alcuna configurazione sulla riga di comando:

./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
Nell'esempio seguente è presente un file di configurazione sulla riga di comando:
./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
L'esempio seguente contiene modifiche dirette della riga di comando:
./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
Utilizzo
Il provider del keystore impiega un token sicuro memorizzato crittografato in un file per utilizzare il keystore. Tutti i dati scritti nel keystore vengono memorizzati in modo sicuro tramite la password. La prima volta che il provider viene avviato, genera un valore di password a caso e un file keystore, se non esistono già.
* 
La password e il file del keystore devono essere limitati solo all'utente dell'applicazione. L'utente dell'applicazione deve disporre dei permessi di lettura e scrittura per i file.
Per creare un file keystore per la memorizzazione dei dati iniziali, è necessario utilizzare lo strumento di gestione della protezione.
1. Ottenere il file ZIP dello strumento di gestione della protezione dal sito del supporto tecnico PTC (nella sezione della release 8.4 o successiva).
2. Estrarre il contenuto del file ZIP in una directory.
3. Creare un file di configurazione con i parametri riportati nell'esempio seguente e inserirlo nella cartella bin.
In questo esempio il file è denominato keystore.conf, la versione dello strumento è 1.0.0.36 e si trova in 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. Avviare un prompt dei comandi e andare al percorso security-common-cli-1.0.0.36\bin.
5. Eseguire
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"
Vengono creati un file di password e il keystore nel percorso configurato.
6. Aprire ThingworxPlatform\platform-settings.json in LicensingConnectionSettings e impostare il valore password su encrypt.licensing.password. Ad esempio "password": "encrypt.licensing.password". Questa password segnala a ThingWorx Platform di cercare la password di licenza crittografata nel keystore quando viene rilevato.
Modifica della password del keystore
È inoltre possibile eseguire la migrazione della password del keystore in una nuova password utilizzando lo strumento di gestione della protezione. Dopo che la password è stata modificata, l'applicazione non può più utilizzare le chiavi, poiché queste vengono migrate fino a quando la password del keystore delle applicazioni non viene reimpostata. Attualmente ciò richiede il riavvio dell'applicazione.
1. Arrestare l'applicazione utilizzando il keystore.
2. Eseguire lo script dello strumento di gestione della protezione con la configurazione del keystore.
3. Eseguire il comando migrate. Viene generata una nuova password, tutti i dati vengono spostati nella nuova password e il file sicuro viene protetto con la nuova password.
4. Riavviare l'applicazione per caricare la nuova password del keystore.
È stato utile?