Uninstalling and upgrading

If you delete a provider login credential you will no longer be able to use it for the nShield Web Services SQLEKM provider.
If you delete an associated SQL Server login you will no longer be able to use it to access the SQL Server or the nShield Web Services SQLEKM provider and will be locked out.

Turning off TDE and removing TDE setup

You must turn off TDE on all your databases and remove TDE setup before uninstalling nShield Web Services SQLEKM. Otherwise, you will not be able to decrypt any databases encrypted with TDE.

Before disabling and removing TDE encryption you are advised to back up the encrypted database (see Backing up a database with SQL Server Management studio) and associated Security World.

  1. In SQL Server Management Studio, navigate to Databases > TestDatabase.

  2. Right-click TestDatabase, then select Tasks > Manage Database Encryption…​

  3. Ensure Set Database Encryption On is deselected, then click OK.

  4. Wait for the decryption process to finish. Check this by referring to the section How to check the TDE encryption/decryption state of a database.

  5. When the database has completed decryption, drop the encryption key using the following T‑SQL query:

    USE TestDatabase
DROP DATABASE ENCRYPTION KEY;
GO

  6. Restart the database instance. If you are using a database failover cluster, you may have to do this directly on the active server. In SQL Server Management Studio right-click on the instance and select Restart.

  7. In SQL Server Management Studio, navigate to Security > Logins, and select the TDE login you wish to remove (for example, tdeLogin). Right-click on the selected login and select Properties.

  8. Ensure the associated credential (for example, tdeCredential) is highlighted then choose Remove. Untick the box Map to credential. Click OK.

  9. In SQL Server Management Studio, navigate to Security > Credentials, and select the same credential you previously removed from the login (for example, tdeCredential). Right-click on the credential and select Delete. In the following screen, select OK.

  10. In SQL Server Management Studio, navigate to Security > Logins, and select the TDE login you wish to remove (for example, tdeLogin). Right-click on the selected login and select Delete. In the following screen, select OK.

  11. In SQL Server Management Studio, navigate to Databases > System Databases > master >Security > Asymmetric keys.

    • Select the key you wish to remove (for example, dbAsymWrappingKey). Right-click on the key and select Delete.

    • Alternatively, you can use the following query:

      USE master
DROP ASYMMETRIC KEY dbAsymWrappingKey REMOVE PROVIDER KEY;
GO

Uninstalling nShield Web Services SQLEKM

Do not uninstall nShield Web Services SQLEKM until you have:

  • Decrypted any data encrypted using the nShield Web Services SQLEKM provider in all your databases.

  • Turned off TDE.

To uninstall nShield Web Services SQLEKM:

  1. Remove the loginCredential from the logged-in user:

    1. In SQL Server Management Studio, select Security > Logins and open up the properties of the logged-in user.

    2. Select loginCredential, then click Remove, then OK.

  2. Select Security > Credentials, and delete the loginCredential.

  3. Disable and remove the nShield Web Services SQLEKM provider:

    1. Select Security > Cryptographic Providers.

    2. Right-click to select the nShield Web Services SQLEKM provider and click Disable Provider.

    3. A dialog is displayed which shows that this action was successful. Click Close.

    4. Right-click to select the disabled nShield Web Services SQLEKM provider, then click Delete, then OK.

  4. Select Start > Control Panel > Administrative Tools > Services (or Start > Administrative Tools > Services, depending on your version of Windows). Select SQL Server (MSQLSERVER) and click Action > Stop.

  5. Select Start > Control Panel > Add/Remove programs (or Uninstall program, depending on your version of Windows). Select nShield Web Services SQLEKM then click Uninstall.

  6. A dialog is displayed asking if you want to continue with uninstalling nShield Web Services SQLEKM. Click Yes.

  7. A setup status screen is displayed while nShield Web Services SQLEKM is uninstalled. Click Finish to complete the removal of the program from your system.

  8. Select Start > Control Panel > Administrative Tools > Services (or Start > Administrative Tools > Services, depending on your version of Windows). Select SQL Server (MSQLSERVER) then click Action > Start.

Upgrading

Follow the instructions for your system:

Upgrading a standalone system

Enhancements will be made to nShield Web Services SQLEKM over time, and product upgrades made available to customers.

Upgrading is a service affecting operation.

Before upgrading, please confirm the following:

  • The system and the database are in a working state.

  • The version of the nShield Web Services SQLEKM provider:

    SELECT * FROM sys.dm_cryptographic_provider_properties;

To upgrade the product:

  1. Disable the nShield Web Services SQL provider using the following query:

    ALTER CRYPTOGRAPHIC PROVIDER SQLEKM
DISABLE;
GO

  2. Restart SQL Server.

  3. Uninstall nShield Web Services SQLEKM:

    1. Ensure that you are signed in as Administrator or as a user with local administrator rights.

    2. Select Start > Control Panel.

    3. Depending on your version of Windows, select Add/Remove programs or Uninstall program.

    4. Select nShield Web Services SQLEKM, then click Uninstall.

    5. A dialog is displayed, asking if you want to continue with uninstalling nShield Web Services SQLEKM. Click Yes.

    6. A setup status screen is displayed while nShield Web Services SQLEKM is uninstalled. Click Finish to complete the removal of the program from your system.

  4. Install the upgraded version of nShield Web Services SQLEKM, see Installation.

  5. Specify the new nShield Web Services SQLEKM provider with the following query (specifying the path as appropriate):

    ALTER CRYPTOGRAPHIC PROVIDER SQLEKM
FROM FILE = 'C:\Program Files\nCipher\WebServices\SQLEKM\provider\nShield.WebServices.SQLEKM.dll';
GO

  6. Enable the new nShield Web Services SQLEKM provider using the following query:

    ALTER CRYPTOGRAPHIC PROVIDER SQLEKM
ENABLE;
GO

  7. Restart SQL Server and check that the system and database are in a working state. Confirm that the version of the nShield Web Services SQLEKM provider is as expected with the following query:

    SELECT * FROM sys.dm_cryptographic_provider_properties;

Upgrading a clustered system

Enhancements will be made to the nShield Web Services SQLEKM over time, and product upgrades made available to customers.

Upgrading is a service affecting operation.

Before upgrading, please confirm the following:

  • The system and the database are in a working state.

  • Each of the nodes can become the active node.

  • The version of the nShield Web Services SQLEKM provider:

    SELECT * FROM sys.dm_cryptographic_provider_properties;

The procedure is based on upgrading a passive node. This means that the particular node will have to be taken out of service. The following steps are dependent on being able to pause a passive node in the cluster, using the Failover Cluster Manager via the Windows Server Manager (Server Manager Dashboard > Tools > Failover Cluster Manager). The paused node is the one to be upgraded. Windows Server 2016 and later versions are automatically cluster-aware. Therefore the Failover Cluster Manager should be available on all versions of Windows that can run SQL Server Enterprise.

To upgrade the product:

  1. Select a passive node (Node U) that will be temporarily out of service while it is upgraded. At least one other node (Node A) must remain active to continue service.

  2. Using the Failover Cluster Manager (Server Manager Dashboard > Tools > Failover Cluster Manager), open the Nodes tree, and select Node U. Pause Node U by selecting Pause > Drain roles.

  3. On node U, disable the nShield Web Services SQL provider using the following query:

    ALTER CRYPTOGRAPHIC PROVIDER SQLEKM
DISABLE;
GO

  4. On node U, uninstall nShield Web Services SQLEKM:

    1. Ensure that you are signed in as Administrator or as a user with local administrator rights.

    2. Select Start > Control Panel.

    3. Depending on your version of Windows, select Add/Remove programs or Uninstall program.

    4. Select nShield Web Services SQLEKM, then click Uninstall.

    5. A dialog is displayed, asking if you want to continue with uninstalling nShield Web Services SQLEKM. Click Yes.

    6. A setup status screen is displayed while nShield Web Services SQLEKM is uninstalled. Click Finish to complete the removal of the program from your system.

  5. On node U, install the upgraded version of nShield Web Services SQLEKM, see Installation.

  6. On Node U, specify the new nShield Web Services SQLEKM provider with the following query (specifying the path as appropriate):

    ALTER CRYPTOGRAPHIC PROVIDER SQLEKM
FROM FILE = 'C:\Program Files\nCipher\WebServices\SQLEKM\provider\nShield.WebServices.SQLEKM.dll';
GO

  7. On Node U, enable the new nShield Web Services SQLEKM provider using the following query:

    ALTER CRYPTOGRAPHIC PROVIDER SQLEKM
ENABLE;
GO

  8. Using the Failover Cluster Manager (Server Manager Dashboard > Tools > Failover Cluster Manager), open the Nodes tree, and select Node U. Resume Node U by selecting Resume > Do not fail roles.

  9. On Node U, check that the system and database are in a working state. Confirm that the version of the nShield Web Services SQLEKM provider is as expected with the following query:

    SELECT * FROM sys.dm_cryptographic_provider_properties;

  10. Check that all databases held in common by both Node A and Node U are synchronized. If so, Node U can now be used for active service in the cluster if required.

  11. Repeat all steps above, except step 6, for all remaining nodes that you wish to upgrade.

Migrating nDSOP keys

If migrating keys from the nDSOP SQLEKM provider for use with the nShield Web Services SQLEKM provider, it will be necessary for:

  • The Web Services Option Pack Server to be indoctrinated into the same Security World as the existing nDSOP installation.

  • The existing sqlekm keys to be migrated and then renamed.

Before migrating keys to the nShield Web Services SQLEKM provider, the following should be considered:

  • The algorithms that are supported by the nShield Web Services SQLEKM provider, see Supported cryptographic algorithms.

  • That whilst symmetric keys without an IDENTITY_VALUE can be migrated, they will not be able to be used to decrypt data encrypted by the nDSOP SQLEKM provider. See Symmetric keys for more information on the importance of specifying an IDENTITY_VALUE.

  • If the Security World is either an unrestricted or FIPS 140-2 Level 2 Security World, it will be necessary to set the following registry entry: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\nCipher\SQLEKM\WebServices\ForceLegacyRSAPKCS15Padding (type REG_DWORD) to 1. Setting this registry entry will require SQL Server to be restarted.

  • As the Web Services Option Pack currently only supports softcards for protection domains, any nDSOP keys protected by an operator cardset (OCS) will first need to be transferred to a softcard, see the documentation for your HSM for further information.

To indoctrinate the Web Services Option Pack Server into the existing Security World, it will be necessary to make the %NFAST_KMDATA%\local folder available. The Security World can then be loaded using new-world. See the documentation for your HSM for further information about loading an existing Security World.

Once the Security World has been loaded and confirmed as usable, dbmt should be used to migrate the existing sqlekm keys, and protecting softcards, to the Web Services Option Pack database. See nShield Web Services v3.3.1 for further information about using the database management tool dbmt.

After the keys which are supported have been successfully migrated, it is necessary to run the ws-sqlekm-key-rename tool to ensure the migrated keys are named appropriately. This tool is available on the nShield Web Services SQLEKM ISO under linux. The ws-sqlekm-key-rename.tar.gz file should be copied to the machine where dbmt was run.

To install ws-sqlekm-key-rename:

tar -xf ws-sqlekm-key-rename.tar.gz
cd opt/nfast/wsop/ws-sqlekm-key-rename
./install.sh

ws-sqlekm-key-rename is installed to the PYTHONPATH directory. (e.g. /opt/nfast/python3/bin/ws-sqlekm-key-rename)

The install script must be called with the correct user permissions.

Using the same config.yaml as used when running dbmt, the migrated keys can be renamed as follows:

ws-sqlekm-key-rename --config config.yaml