utilitaire MigrateEncryptedInfo

MigrateEncryptedInfo est un utilitaire qui permet de modifier la clé de commerçant et de rechiffrer toutes les données chiffrées dans la base de données.

Par défaut, il gère les tables suivantes, comme indiqué dans DBUpdate.txt : USERREG, USERPWDHST, PATTRVALUE, ORDPAYINFO, ORDPAYMTHD, PPCEXTDATA, PPCPAYINST, MERCHCONFINFO, GRUSERAUTH, CSEDITATT, ISEDITATT. Pour exécuter l'utilitaire MigrateEncryptedInfo de manière plus efficace, commencez par exécuter l'utilitaire de nettoyage de base de données sur l'une quelconque des tables dont les données périmées peuvent être supprimées, telles que la table PPCEXTDATA. Pour plus d'informations sur l'optimisation de MigrateEncryptedInfo, voir : Optimisation de l'utilitaire MigrateEncryptedInfo. Vous disposez de deux méthodes pour définir les valeurs de la clé de commerçant dans cet outil. La première méthode consiste à indiquer l'ancienne et la nouvelle clés de commerçant au moyen d'arguments de ligne de commande. La seconde méthode consiste à extraire les clés en appelant Key Locator Framework à l'aide du paramètre "-k".

Important : Vous devez spécifier vos propres valeurs de clé de commerçant et de clé de chiffrement de clé pour la sécurité de votre installation HCL Commerce. N'utilisez pas les valeurs par défaut contenues dans les exemples de fichier de configuration et les exemples de documentation fournis.

Gestion des tables personnalisées à l'aide de l'utilitaire MigrateEncryptedInfo

Les tables personnalisées à utiliser pour le chiffrement doivent être chiffrées à l'aide de la classe DataReEncrypter. L'ID ReEncryptUserPasswordHistory du fichier DBUpdate.txt doit être utilisé pour répertorier les tables personnalisées qui seront chiffrées. Au moins une zone de table doit contenir des données chiffrées et doit être incluse dans le fichier DBUpdate.txt.

Voici l'exemple de la procédure d'ajout d'une table personnalisée dans DBUpdate.txt :

[DBTable]
TableName=<Custom_Table_Name>
TableColumns=<Encrypted_Values_Column_Names>
UniqueColumns=<Unique_Values_Column_Names>
[Parameter]
ID=OldEncryptionKey
DisplayID=OldEncryptionKey
Value=

TableName: Nom de la table personnalisée à utiliser pour le chiffrement.
TableColumns: Contient le nom de colonne de la table qui stocke les valeurs chiffrées. Plusieurs colonnes peuvent avoir des données chiffrées.
UniqueColumns: Contient le nom de colonne de la table qui stocke les valeurs uniques. Plusieurs colonnes peuvent avoir des données uniques. La colonne UniqueColumns doit être de type de données numériques (par exemple, Entier) et doit être la clé primaire de la table personnalisée.

Si l'un des détails ci-dessus est manquant dans DBUpdate.txt, l'utilitaire MigrateEncryptedInfo ne pourra alors pas déchiffrer ou chiffrer correctement les données.

Remarque :

Si les données USERREG.CHALLENGEANSWER sont définies en texte brut, vous pouvez les chiffrer en réglant l'indicateur MemberSubSystem/challengeAnswerEncrypted dans le fichier de configuration wc-server.xml sur true. Ensuite, l'exécution de MigrateEncryptedInfo chiffrera USERREG.CHALLENGEANSWER.

Introduction

L'utilitaire MigrateEncryptedInfo se trouve dans le répertoire suivant :

utilities_root/bin/MigrateEncryptedInfo.sh
WCDE_installdir/bin/MigrateEncryptedInfo.bat

A l'issue de l'exécution de l'utilitaire MigrateEncryptedInfo, les fichiers journaux suivants sont générés :

CCInfoMigration.log
MKChangeUserAndCCInfoMigration.log
MigrateEncryptedInfoError.log
migrateFailedRecords_TABLENAME.log

dans le répertoire suivant :

utilities_root/logs/
WCDE_installdir/logs/

Vérifiez que les informations consignées dans ces fichiers journaux ne contiennent pas de message d'erreur.

Si l'erreur s'est produite lors du chiffrement ou du déchiffrement de données, les enregistrements de données en échec correspondants sont enregistrés dans le fichier journal utilities_root/logs/migrateFailedRecords_TABLENAME.log. TABLENAME est le nom de la table des données en échec. Cette table doit être l'une des suivantes : USERREG, USERPWDHST, PATTRVALUE, ORDPAYINFO, ORDPAYMTHD, PPCEXTDATA, PPCPAYINST, MERCHCONFINFO, GRUSERAUTH, CSEDITATT et ISEDITATT.

Par exemple, si un enregistrement dans ORDPAYINFO est déchiffré avec une exception, il est enregistré dans le fichier utilities_root/logs/migrateFailedRecords_ORDPAYINFO.log. Si l'erreur s'est produite pendant la transaction, par exemple lors de la validation de transaction, tous les enregistrements de données contenus dans le lot sont enregistrés et un lot en échec n'affecte pas les autres lots. Le nombre d'enregistrements de données dans un lot est configuré par le paramètre commit_count dans la ligne de commande. La valeur conseillée est 5000. Une fois que l'erreur s'est produite, identifiez et résolvez l'origine de l'erreur en vous aidant des messages d'erreur et des enregistrements de données qui ont échoué. Alors :

Restaurez d'abord la base de données et ré-exécutez l'utilitaire.

Avant de commencer

Vérifiez que les paramètres HostName et HostJDBCPort ont été définis dans le fichier de configuration utilities_root/schema/DBTYPE/migration/DBUpdate.txt.

Syntaxe

Diagramme illustrant l'utilitaire MigrateEncryptedInfo. Les paramètres sont décrits dans la liste ci-dessous.

Valeurs des paramètres

type_base_de_données: Votre type de base de données, DB2 ou oracle.
instance_name: Paramètre obligatoire permettant d'indiquer le nom de l'instance mise à jour. Par exemple, demo.
nombre_unités_d'exécution: Nombre d'unités d'exécution créées pour rechiffrer les données. Il est recommandé de faire correspondre ce nombre avec le nombre de processeurs présents sur le serveur qui exécute l'utilitaire.
nombre_validations: Le nombre d'enregistrements traités avant la validation de la transaction. La valeur définie pour ce paramètre doit correspondre au nombre maximal de transactions autorisées par le journal de transaction de base de données. La valeur recommandée pour ce paramètre est 5000.

Si les clés de commerçant ne sont pas extraites de Key Locator Framework, les paramètres suivants sont acceptés :

clé_commerçant_en_cours

Paramètre facultatif représentant la clé de commerçant en cours, en texte clair (ASCII). Vous devez indiquer ce paramètre uniquement si la clé de commerçant que vous utilisez n'est pas la clé par défaut et qu'elle doit être remplacée par une nouvelle clé. Dans ce cas, vous devez également spécifier le paramètre new_merchant_key. L'utilitaire détecte par lui-même que vous utilisez la clé par défaut.

nouvelle_clé_commerçant

Paramètre obligatoire en texte clair (ASCII). Si vous utilisez une clé de commerçant non définie par défaut, ce paramètre est facultatif. Il doit respecter les règles suivantes :

Un caractère hexadécimal de 32 doit être utilisé. Les caractères peuvent être 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b, c, d, e ou f.
Il doit inclure au moins un caractère alphabétique.
Il doit inclure au moins un caractère numérique.
Il doit être en minuscules.
Il ne doit pas contenir plus de quatre caractères consécutifs.
Par exemple, 1a1a1a1a1a1a1a1a2b2b2b2b2b2b2b2b.

Si les clés de commerçant ne sont pas extraites de Key Locator Framework, les paramètres suivants sont acceptés :

-k emplacement_fichier_configuration_clés: La clé en cours et la nouvelle clé de commerçant doivent être extraites de Key Locator Framework à l'aide du fichier de configuration de clés indiqué. Vous devez indiquer le chemin d'accès absolu au fichier.
-interactive: Facultatif : L'administrateur est invité à entrer la nouvelle clé de commerçant lorsque cet indicateur est spécifié. Cet indicateur peut être utilisé en mode hors ligne uniquement.
Si vous voulez exécuter l'utilitaire MigrateEncryptedInfo sans arrêter le serveur, le paramètre -interactive ne peut pas être utilisé.

Modification de la valeur de clé de commerçant dans un fichier externe

Si votre clé de commerçant est stockée dans un fichier externe et que vous souhaitez modifier la valeur, procédez comme suit :

Arrêtez l'instance du HCL Commerce.

Si vous exécutez la commande MigrateEncryptedInfo pour modifier les clés alors que le Transaction server est hors ligne, définissez un nouveau fichier de configuration de clés personnalisées, CustomKeys.xml, similaire à ce qui suit. Placez-le dans un répertoire relatif à une entrée du chemin d'accès aux classes de l'application HCL Commerce, comme application_dir/WC/xml/config.

<?xml version="1.0" encoding="UTF-8"?>

<keys xmlns="http://www.ibm.com/xmlns/prod/WebSphereCommerce"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/WebSphereCommerce
xsd/WCKeys.xsd">

<key 
	name="MerchantKey"
	providerName="WC"
	status="current"
	className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">

	<config name="keyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml"/>
	<config name="keyEncryptionKeyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml"/>
</key>

<key 
	name="MerchantKey" 
	providerName="WC" 
	status="new"
	className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl">
	
	<config name="keyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml"/>
	
	<config name="keyEncryptionKeyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml"/>
	
	<config name="newKeyFile1"
	value="c:/temp/newMerchantKey1.xml"/>
	
	<config name="newKeyFile2" 
	value="c:/temp/newMerchantKey2.xml"/>

</key>
</keys>

Pour obtenir une description détaillée de chaque paramètre et du format des fichiers de clés, voir Implémentations d'un fournisseur de clés pour une clé de commerçant.

Si vous exécutez la commande MigrateEncryptedInfo pour migrer le chiffrement de 3DES vers AES et que le Transaction server est en ligne, HCL Commerce doit avoir un moyen de différencier les données chiffrées avec la clé d'origine des données chiffrées avec la nouvelle clé. Pour cette raison, vous devez spécifier un numéro de version unique pour chaque clé à l'aide du paramètre version.

Dans ce cas, l'utilitaire MigrateEncryptedInfo déchiffre les données chiffrées avec la clé existante (statut "current") et les chiffre à nouveau avec la nouvelle clé (statut "new").

Les valeurs valides pour l'algorithme sont 3DES et AES.

<?xml version="1.0" encoding="UTF-8"?>

<keys xmlns="http://www.ibm.com/xmlns/prod/WebSphereCommerce"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/WebSphereCommerce
xsd/WCKeys.xsd">

<key 
	name="MerchantKey"
	providerName="WC"
	status="current"
	className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl"
	version="2"
	algorithm="AES">
	
	<config name="keyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml"/>
	<config name="keyEncryptionKeyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml"/>
</key>

<key 
	name="MerchantKey"
	providerName="WC"
	status="new"
	className="com.ibm.commerce.security.keys.WCExternalFileMerchantKeyImpl"
	version="3"
	algorithm="AES">

	<config name="keyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/merchantKey.xml"/>

	<config name="keyEncryptionKeyFile"
	value="/opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/KeyEncryptionKey.xml"/>

	<config name="newKeyFile1" 
	value="c:/temp/newMerchantKey1.xml"/>

	<config name="newKeyFile2" 
	value="c:/temp/newMerchantKey2.xml"/>
</key>
</keys>

Ouvrez une invite de commande et accédez au répertoire utilities_root/bin.
Exécutez l'utilitaire. La commande serait la suivante, en supposant que les données chiffrées sont stockées dans une base de données DB2 et que "demo" est le nom de l'instance :
- ```
MigrateEncryptedInfo db2 demo 4 5000 -k workspace_dir/WC/xml/config/CustomKeys.xml
```
Maintenant que toutes les données sont chiffrées avec la valeur extraite du fournisseur de la nouvelle clé ("new"), WCExternalFileMerchantKeyImpl, éditez le fichier de configuration de clés de la manière suivante :
- Supprimez le fournisseur de la clé en cours ("current")
- Associez le statut du fournisseur de la nouvelle clé à la valeur "current".
Démarrez l'instance de HCL Commerce.
Déployez les modifications dans les fichiers XML personnalisés sur Transaction server Docker container. Par exemple, merchantKey.xml, CustomKeys.xml et KeyEncryptionKey.xml.