Definición del modelo de ThingWorx en Composer > Seguridad > Herramienta de gestión de seguridad
Herramienta de gestión de seguridad
La herramienta de gestión de seguridad es una manera de gestionar la información segura utilizada por el software de ThingWorx. La herramienta puede cifrar cualquier valor de clave de los ficheros de configuración de estos productos, como contraseñas de base de datos y de licencias. Esta herramienta se puede utilizar con cualquier aplicación de ThingWorx y se soporta en productos como, por ejemplo, ThingWorx Platform, Connection Server, ThingWorx Azure IoT Hub Connector v.3.0.0, ThingWorx Edge MicroServer (EMS), Integration Runtime, etc.
La herramienta de gestión de la seguridad funciona con ficheros de keystore PFX y utiliza la codificación AES para los secretos. El uso de la codificación de AES requiere una versión de Java superior a 8U141.
Si ya existe un keystore .JKS, se debe actualizar a un keystore .PFX. Esto ocurre en cuanto se ejecuta CLI en cualquier keystore JKS. Una vez creado, se puede quitar la versión JKS del keystore, aunque se recomienda realizar una copia de seguridad en caso de problemas.
El fichero de keystore conf funcionará tal cual, pero se debe actualizar para definir el nombre de keystore a tan solo el nombre de fichero sin la extensión, para reducir el procesamiento adicional.
Ubicación
Esta herramienta está disponible en la página de descargas de software de PTC, con las descargas de software de ThingWorx.
Versiones soportadas
Esta herramienta se puede utilizar con ThingWorx 8.4.0 y versiones posteriores.
Permisos
Esta herramienta está diseñada para que solo la utilice el administrador. Instálela cuando sea necesaria y quítela después de usarla.
Configuración
* 
El parámetro default-encryption-key-length debe coincidir con la configuración de la aplicación. En ThingWorx, el parámetro InternalAesCryptographicKeyLength se encuentra en platform-settings.json. El valor por defecto es 128, pero se puede utilizar la codificación de 256 bits si se utiliza Java 1.8.0_162 o superior. Si fuese necesario, también se puede utilizar con versiones anteriores de Java mediante la actualización de la directiva de Java para el límite de tamaño de la clave.
Configuración 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"
}
}
}
Configuración 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"
}
}
}
Utilización de la herramienta de línea de comandos
Utilice la herramienta de línea de comandos para realizar operaciones específicas fuera de la aplicación y predefinir los secretos que una aplicación requiere. El script de la aplicación (security-common-cli) se proporciona en la distribución de Windows y Linux. Hay varias maneras de ejecutar la herramienta de línea de comandos:
• Sin un fichero de configuración: la herramienta se inicia sin un gestor de seguridad configurado y los comandos que se pueden ejecutar son limitados. Se debe ejecutar el comando init para configurar el gestor de seguridad:
# run without providing a config, will have to run init, prompt for input
./security-common-cli
• Con un fichero de configuración como primer parámetro del script: la herramienta se inicia e inicializa el gestor de seguridad con la configuración especificada.
# initialize security manager with specified config, prompt for input
./security-common-cli <path to keystore>\keystore.conf
• Con un fichero de configuración y varios parámetros más: la herramienta se ejecuta en modo de único uso. Ejecuta la acción proporcionada y, a continuación, deja inmediatamente de ejecutarse. Es una manera de llamar desde un instalador básico. Cuando se pasan parámetros que contienen espacios en blanco en la línea de comandos, se deben especificar entre comillas simples para que se procesen como argumento único. Cuando se ejecuta en el modo de línea de comandos, solo se ejecuta en la configuración regional de Estados Unidos para asegurarse de que los nombres de las acciones sean predecibles.
# 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'
* 
Se puede utilizar la ruta completa para el fichero de configuración o simplemente el nombre del fichero de configuración si se encuentra en la classpath.
Comandos comunes
Comando
Descripción
help o bien ?
Permite mostrar la información de uso.
exit
Permite cerrar la herramienta.
config
Permite mostrar la configuración actual.
init <fichero config>
Permite cargar la configuración.
createTokenFile<ruta><token>
Permite crear un fichero de token.
* 
Esta opción está disponible en la versión 1.3.1 y posteriores de la herramienta de gestión de la seguridad.
Comandos de gestión de secretos
Comando
Descripción
keys
Lista de claves en el proveedor de secreto.
get <nombre>
Permite recuperar un valor del proveedor de secreto.
set <nombre> <valor>
Permite definir un valor en el proveedor de secreto.
remove <nombre>
Permite quitar un valor del proveedor de secreto.
Codificación y los comandos de KeyStore
Comando
Descripción
generate-key <nombre-secreto>
Permite generar una nueva clave de codificación y almacenarla en un secreto.
encrypt <nombre-clave-codificación> <nombre-secreto> <cadena>
Permite cifrar una cadena utilizando la clave opcional y almacenarla en un secreto.
* 
<nombre-clave-codificación> es opcional. Si no se especifica un valor de <nombre-clave-codificación>, se utiliza la clave interna por defecto. Los ficheros tienen un límite de tamaño de 10 MB.
decrypt<nombre-clave-codificación> <nombre-secreto>
Permite descifrar una cadena almacenada en el secreto utilizando la clave opcional.
* 
<nombre-clave-codificación> es opcional. Si no se especifica un valor de <nombre-clave-codificación>, se utiliza la clave interna por defecto. Los ficheros tienen un límite de tamaño de 10 MB.
encryptFile <nombre-clave-codificación> <origen> <destino>
Permite cifrar el fichero de origen y escribirlo en el destino con la clave opcional almacenada como secreto.
* 
<nombre-clave-codificación> es opcional. Si no se especifica un valor de <nombre-clave-codificación>, se utiliza la clave interna por defecto. Los ficheros tienen un límite de tamaño de 10 MB.
decryptFile <nombre-clave-codificación> <origen> <destino>
Permite descifrar el fichero de origen y escribirlo en el destino con la clave opcional almacenada como secreto.
* 
<nombre-clave-codificación> es opcional. Si no se especifica un valor de <nombre-clave-codificación>, se utiliza la clave interna por defecto. Los ficheros tienen un límite de tamaño de 10 MB.
viewFile <nombre-clave-codificación> <origen>
Permite descifrar el fichero de origen y ver el contenido con la clave opcional almacenada como secreto.
* 
<nombre-clave-codificación> es opcional. Si no se especifica un valor de <nombre-clave-codificación>, se utiliza la clave interna por defecto. Los ficheros tienen un límite de tamaño de 10 MB.
migrate <contraseña>
Permite migrar el KeyStore a una nueva contraseña generada o contraseña especificada.
addcert <nombre><ruta>
Permite cargar un certificado X.509 en el KeyStore.
import <orchestration-keystore-config>
Permite importar secretos de un fichero a un proveedor de secreto.
* 
Esta opción está disponible en la versión 1.3.1 y posteriores de la herramienta de gestión de la seguridad.
Ejemplos de uso
En el ejemplo siguiente, no hay ninguna configuración en la línea de comandos:

./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
En el siguiente ejemplo, hay un fichero de configuración anotado en la línea de comandos:
./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
En el ejemplo siguiente, hay cambios directos en la línea de comandos:
./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
Uso
El proveedor de KeyStore utiliza un token seguro almacenado cifrado en un fichero para trabajar con el KeyStore. Todos los datos que se escriben en el KeyStore se almacenan de forma segura mediante la contraseña. La primera vez que se inicia el proveedor, genera un valor de contraseña aleatorio y un fichero de KeyStore, si aún no existen.
* 
La contraseña de KeyStore y el fichero de KeyStore deben estar restringidos solo al usuario de la aplicación. El usuario de la aplicación debe tener permisos de lectura y escritura para los ficheros.
Para crear un fichero de KeyStore para almacenar los datos iniciales, se debe utilizar la herramienta de gestión de seguridad.
1. Obtenga el fichero comprimido de la herramienta de gestión de seguridad del sitio de soporte técnico de PTC (en la sección Versión 8.4 o posterior).
2. Extraiga el contenido del fichero comprimido en un directorio.
3. Cree un fichero de configuración con los parámetros que se ven en el siguiente ejemplo y colóquelo en la carpeta bin.
En este ejemplo, el fichero se denomina keystore.conf, la versión de la herramienta es 1.0.0.36 y se encuentra en 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. Inicie un símbolo del sistema y vaya a la ubicación de security-common-cli-1.0.0.36\bin.
5. Ejecute
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"
Se creará un fichero de contraseña y KeyStore en la ubicación configurada.
6. Abra ThingworxPlatform\platform-settings.json en LicensingConnectionSettings y cambie el valor de password a encrypt.licensing.password. Por ejemplo, "password": "encrypt.licensing.password". Esta contraseña indica a ThingWorx Platform que busque la contraseña codificada de licencias en el keystore cuando se encuentre.
Cambio de la contraseña de KeyStore
También es posible migrar la contraseña de KeyStore a una nueva contraseña mediante la herramienta de gestión de seguridad. Cuando se cambia la contraseña, la aplicación ya no puede utilizar las claves ya que se migran hasta que se redefina la contraseña de KeyStore de aplicaciones. Actualmente, esto requiere un reinicio de la aplicación.
1. Detenga la aplicación mediante el KeyStore.
2. Ejecute el script de la Herramienta de gestión de seguridad con la configuración de KeyStore.
3. Ejecute el comando migrate. De este modo, se genera una nueva contraseña, se mueven todos los datos a la nueva contraseña y se actualiza el fichero seguro con la nueva contraseña.
4. Reinicie la aplicación para cargar la nueva contraseña de KeyStore.
¿Fue esto útil?