Définition du modèle ThingWorx dans Composer > Sécurité > Outil de gestion de la sécurité
Outil de gestion de la sécurité
L'outil de gestion de la sécurité permet de gérer les informations de sécurité utilisées par le logiciel ThingWorx. L'outil peut chiffrer n'importe quelle valeur de clé à partir des fichiers de configuration de ces produits, tels que les mots de passe de base de données et de gestion des licences. Il peut être utilisé avec n'importe quelle application ThingWorx et est notamment pris en charge par ThingWorx Platform, Connection Server, ThingWorx Azure IoT Hub Connector v.3.0.0, ThingWorx Edge MicroServer (EMS), Integration Runtime, etc.
L'outil de gestion de la sécurité fonctionne avec des fichiers KeyStore PFX et utilise un chiffrement AES pour les clés secrètes. L'utilisation du chiffrement AES nécessite une version de Java ultérieure à la 8U141.
Tout KeyStore JKS existant nécessite d'être mis à niveau vers un KeyStore PFX. Cette mise à niveau se produit dès que la CLI est exécutée sur le KeyStore JKS. Une fois créée, la version JKS du KeyStore peut être supprimée, bien qu'il soit recommandé d'en conserver une copie de sauvegarde en cas de problème.
Le fichier conf du KeyStore fonctionnera en l'état, même s'il convient de le mettre à jour pour définir le nom du KeyStore sur le nom du fichier sans l'extension, afin d'éliminer des traitements superflus.
emplacement
Cet outil est disponible sur le site Web de téléchargement de logiciels PTC, avec les téléchargements de logiciels ThingWorx.
Versions prises en charge
Cet outil est compatible avec ThingWorx 8.4.0 et versions ultérieures.
Permissions
Cet outil est destiné aux administrateurs uniquement. Installez-le au besoin, puis supprimez-le après utilisation.
Configuration
* 
Le paramètre default-encryption-key-length doit correspondre à la configuration de l'application. Dans ThingWorx, cela correspond au paramètre InternalAesCryptographicKeyLength qui se trouve dans le fichier platform-settings.json. La valeur par défaut est 128, mais vous pouvez définir le chiffrement 256 bits si vous utilisez Java 1.8.0_162 ou une version ultérieure. Si nécessaire, vous pouvez également utiliser les versions antérieures de Java en mettant à jour la politique Java en matière de limite de taille de clé.
Paramètres de 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"
}
}
}
Paramètres de 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"
}
}
}
Utilisation de l'interface de ligne de commande
Utilisez l'interface de ligne de commande pour effectuer des opérations spécifiques en dehors de l'application afin de préconfigurer les secrets dont une application a besoin. Le script de l'application (sécurité-common-cli) est fourni dans la distribution pour Linux et Windows. Vous pouvez exécuter l'interface de ligne de commande de plusieurs façons :
• Sans fichier de configuration : l'interface est lancée sans gestionnaire de sécurité configuré et les commandes disponibles pour exécution sont limitées. Vous devez exécuter la commande init pour configurer le gestionnaire de sécurité :
# run without providing a config, will have to run init, prompt for input
./security-common-cli
• Avec un fichier de configuration en tant que premier paramètre du script : l'interface est lancée et le gestionnaire de sécurité initialisé avec la configuration spécifiée.
# initialize security manager with specified config, prompt for input
./security-common-cli <path to keystore>\keystore.conf
• Avec un fichier de configuration et plusieurs autres paramètres : l'interface est exécutée en mode d'utilisation unique. Elle exécute l'action voulue, puis se ferme immédiatement. Il s'agit d'un mode d'appel depuis un programme d'installation de base. Lors de la transmission dans la ligne de commande de paramètres contenant des espaces, vous devez les mettre entre guillemets uniques afin qu'ils soient traités comme un seul argument. Lors d'une exécution en mode ligne de commande, l'interface s'exécute avec les paramètres régionaux des Etats-Unis pour s'assurer que les noms des actions sont prévisibles.
# 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'
* 
Vous pouvez utiliser le chemin complet du fichier de configuration, ou uniquement le nom du fichier si le fichier de configuration se trouve dans le chemin de classe (classpath).
Commandes courantes
Commande
Description
help ou ?
Affiche les informations d'utilisation.
exit
Ferme l'interface.
config
Affiche la configuration actuelle.
init <fichier-configuration>
Charge la configuration.
createTokenFile<chemin><jeton>
Crée un fichier de jeton.
* 
Cette option est disponible dans les versions 1.3.1 et ultérieures de l'outil de gestion de la sécurité.
Commandes de gestion des secrets
Commande
Description
keys
Liste des clés dans le fournisseur de secrets.
get <nom>
Récupère une valeur auprès du fournisseur de secrets.
set <nom> <valeur>
Définit une valeur dans le fournisseur de secrets.
remove <nom>
Supprime une valeur du fournisseur de secrets.
Commandes de chiffrement et de KeyStore
Commande
Description
generate-key <nom-secret>
Génère une nouvelle clé de chiffrement et la stocke dans un secret.
encrypt <nom-clé-chiffrement> <nom secret> <chaîne>
Chiffre une chaîne à l'aide de la clé facultative et la stocke dans un secret.
* 
L'élément <nom-clé-chiffrement> est facultatif. Si aucun élément <nom-clé-chiffrement> n'est spécifié, la clé interne par défaut est utilisée. La taille des fichiers est limitée à 10 Mo.
decrypt<nom-clé-chiffrement> <nom secret>
Déchiffre une chaîne stockée dans un secret à l'aide de la clé facultative.
* 
L'élément <nom-clé-chiffrement> est facultatif. Si aucun élément <nom-clé-chiffrement> n'est spécifié, la clé interne par défaut est utilisée. La taille des fichiers est limitée à 10 Mo.
encryptFile <nom-clé-chiffrement> <source> <destination>
Chiffre le fichier source et l'écrit dans la destination avec la clé facultative stockée en tant que secret.
* 
L'élément <nom-clé-chiffrement> est facultatif. Si aucun élément <nom-clé-chiffrement> n'est spécifié, la clé interne par défaut est utilisée. La taille des fichiers est limitée à 10 Mo.
decryptFile <nom-clé-chiffrement> <source> <destination>
Déchiffre le fichier source et l'écrit dans la destination avec la clé facultative stockée en tant que secret.
* 
L'élément <nom-clé-chiffrement> est facultatif. Si aucun élément <nom-clé-chiffrement> n'est spécifié, la clé interne par défaut est utilisée. La taille des fichiers est limitée à 10 Mo.
viewFile <nom-clé-chiffrement> <source>
Déchiffre le fichier source et affiche son contenu avec la clé facultative stockée en tant que secret.
* 
L'élément <nom-clé-chiffrement> est facultatif. Si aucun élément <nom-clé-chiffrement> n'est spécifié, la clé interne par défaut est utilisée. La taille des fichiers est limitée à 10 Mo.
migrate <mot de passe>
Remplace le mot de passe du KeyStore par un nouveau mot de passe généré ou le mot de passe spécifié.
addcert <nom><chemin>
Charge un certificat X.509 dans le KeyStore.
import <config-keystore-orchestration>
Importe les clés secrètes du fichier vers le fournisseur de clés secrètes.
* 
Cette option est disponible dans les versions 1.3.1 et ultérieures de l'outil de gestion de la sécurité.
Exemples d'utilisation
Dans l'exemple suivant, il n'y a pas de fichier de configuration sur la ligne de commande :

./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
Dans l'exemple suivant, un fichier de configuration est spécifié sur la ligne de commande :
./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
Dans l'exemple suivant, il y a des modifications directes en ligne de commande :
./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
Utilisation
Le fournisseur du KeyStore utilise un jeton sécurisé chiffré dans un fichier afin d'utiliser le KeyStore. Toutes les données écrites dans le KeyStore sont stockées en toute sécurité à l'aide du mot de passe. Au premier démarrage du fournisseur, celui-ci génère une valeur de mot de passe aléatoire et un fichier KeyStore s'ils n'existent pas déjà.
* 
L'accès au mot de passe du KeyStore et au fichier KeyStore doit être limité à l'utilisateur de l'application. Ce dernier doit disposer des droits d'accès en lecture et écriture aux fichiers.
Pour créer un fichier KeyStore pour le stockage des données initiales, vous devez utiliser l'outil de gestion de la sécurité.
1. Téléchargez le fichier ZIP de l'outil de gestion de la sécurité depuis le site de support PTC (section relative à la version 8.4 ou ultérieure).
2. Extrayez le contenu du fichier Zip dans un répertoire.
3. Créez un fichier de configuration avec les paramètres que vous voyez dans l'exemple ci-après et placez-le dans le dossier bin.
Dans cet exemple, le fichier est nommé keystore.conf, la version de l'outil est 1.0.0.36, et il se trouve dans 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. Lancez une invite de commande et accédez à l'emplacement security-common-cli-1.0.0.36\bin.
5. Exécutez
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"
. Un fichier de mot de passe et le KeyStore sont créés à l'emplacement configuré.
6. Ouvrez le fichier ThingworxPlatform\platform-settings.json dans LicensingConnectionSettings et remplacez la valeur password par encrypt.licensing.password. Par exemple, "password": "encrypt.licensing.password". Ce mot de passe indique à ThingWorx Platform de rechercher le mot de passe chiffré du serveur de licences dans le KeyStore lorsqu'elle le rencontre.
Modification du mot de passe du KeyStore
Il est également possible de remplacer le mot de passe du KeyStore par un nouveau mot de passe à l'aide de l'outil de gestion de la sécurité. Une fois le mot de passe modifié, l'application n'a plus accès aux clés lors de leur migration tant que le mot de passe du KeyStore de l'application n'est pas réinitialisé. Actuellement, cela nécessite un redémarrage de l'application.
1. Arrêtez l'application à l'aide du KeyStore.
2. Exécutez le script de l'outil de gestion de la sécurité avec la configuration du KeyStore.
3. Exécutez la commande migrate. Cette opération génère un nouveau mot de passe, lui associe toutes les données voulues et met à jour le fichier de sécurité avec le nouveau mot de passe.
4. Redémarrez l'application pour charger le nouveau mot de passe du KeyStore.
Est-ce que cela a été utile ?