Encryption Key Maintenance Utility

This section describes how Advanced Store encrypts POSLog fields and how keys are generated and managed. The Encryption Key Maintenance Utility can be used to generate new encryption keys.

Encryption Standards

The Advanced Store solution uses AES-192 for field-level encryption in the POSLog. When a POSLog is stored on disk in the store, the entire file is encrypted using AES-192. Some EOM POS parameters permit storing credential information. This credential data can also be encrypted.

DSR Enterprise

The POS application requires an encryption key to run. When the Advanced Store databases are initially created, a default key is provided.

Important

NCR Voyix recommends that retailers delete the default key and issue a new one, at a minimum in their production environment.

Encryption key data is stored and managed at the enterprise in the CoreDb.dbo.EncryptionKey table. Database encryption key data is managed through the DSR Enterprise EncryptionKey Web API. Only users with a role code of 100 (Admin), are authorized to use the EncryptionKey API. For information about the DSR Web API, refer to Getting Started with the DSR Web API.

In-Store systems

When a new key is added using the POST EncryptionKey API, the key information is sent to store maintenance RabbitMQ queues for each store to retrieve and distribute to each POS terminal. The file that holds the key information has a 10-digit file name with an .lck extension, for example, 1646231312.lck. This file is located in the %ProgramData%\NCR\AdvancedStore\POS folder. A file named ENCFILE exists in the same folder, and this file indicates to the POS application which .lck file should be used to encrypt data.

Note

Multiple .lck files can exist, which gives the POS application the opportunity to decrypt data that comes back from central returns that may have originally been encrypted using a different key. However, retailers are unlikely to use a POS terminal for key decryption.

Creating an encryption key

Before creating an encryption key for the first time, you must create a Key Encryption Key (KEK) seed. After creating the initial encryption key, you can create encryption keys without generating a KEK seed, but it is unlikely that additional encryption keys will be needed.

To create an encryption key, follow these steps.

  1. On the Enterprise Messaging Server, go to the following folder: %ProgramFiles(x86)%\NCR\DSREnterprise\Utilities
  2. Run the ASKeyMaintenanceUtility.exe. The AS Encryption Key Maintenance Utility opens.

  3. Select Browse to choose the folder where the key files will be stored.

    Existing .lck files, if any, are displayed in the Key LCK Files list.

  4. If this is the first time running the utility, select New KEK Seed.

    A KEK Seed is created and displayed on the screen above the New KEK Seed button. This KEK seed will apply to all new encryption keys.

    Note

    The KEK seed resides in the utility's working folder in the KeyGenerationApp.dat file.

  5. To generate a new encryption key and .lck file, select Generate Encryption Key.

    The new .lck file is displayed in the Key LCK Files list, and the Total LCK File Count increases by one.

    Note

    The 10-digit Key ID corresponds to the Epoch time (number of seconds since January 1, 1970) when the key was generated.

Generating a JSON file

The Encryption Key Maintenance Utility does not call the POST EncryptionKey API directly to create a new key in the AS Database. However, it can generate the JSON payload used to call the POST EncryptionKey API.

To generate a JSON file that can be used with the EncryptionKey API, follow these steps.

  1. Open the AS Encryption Key Maintenance Utility.

  2. From the Key LCK Files list, select the desired Key ID, and then select Get JSON.

    The JSON Body for the POST EncryptionKey web API request is displayed.

    Note

    The KeyValue is base64-encrypted binary key data.

  3. To copy the JSON Body, select Copy to Clipboard.
  4. Select Close to close the Encryption API JSON dialog.
  5. Use the POST EncryptionKey API to update the AS Encryption Key table. For more information about using the DSR Web API, refer to Getting Started with the DSR Web API.
Important

Secure or delete the key files after confirming that the AS Encryption Key table has been updated with the new keys.