Chapter 1: About This Manual

Townsend Security Key Connection for Encryptionizer

NetLib’s Encryptionizer database security software provides automatic encryption on Windows for SQL Server, File/Folder encryption, MySQL, and Windows applications. Townsend Security’s Key Connection for Encryptionizer provides key management for Encryptionizer. You can securely retrieve encryption keys from the AKM server to encrypt data in your Encryptionizer application.

Who is this for?

This guide is designed to help application developers implement encryption key management via the Townsend Security Key Connection for Encryptionizer plugin. This guide assumes you are already familiar with Encryptionizer or you will reference NetLib documentation. It covers installation and configuration of the plugin.

Client applications and SDKs

Townsend Security provides the following applications and SDKs to assist with client-side key retrieval or remote encryption:

• Key Connection for SQL Server: Microsoft Extensible Key Management Provider for Transparent Data Encryption (TDE) and cell level encryption
• Windows SDK for .NET applications
• SQL Server UDF for all editions of SQL Server
• Key Connection for Drupal
• Key Connection for Encryptionizer

In addition to these offerings, Townsend Security provides software libraries and code samples to assist with custom implementations. Visit this page https://info.townsendsecurity.com/alliance-key-manager-evaluation for a current list of client applications, software libraries, and code samples.

Other resources

The following documents provide additional information on the installation and use of Alliance Key Manager:

• AKM User Guide
• AKM Server Management Guide
• AKM Administrative Console Guide

Notices

This product and documentation is covered by U.S. and International copyright law. This product may incorporate software licensed under one or more open source license agreements. Government users please note that this product is provided under restricted government use license controls. Please refer to the Alliance Key Manager End User License Agreement for more information.

Change log

The following table provides information on the changes to this documentation:

Version	Date	Description
3.0.0.001	10/16/2014	Initial release.
3.0.0.002	11/4/2014	Updates.
3.0.3.001	1/18/2015	Update for AKM 3.0.3 and the ready to use version of AKM for VMware.
4.0.0.001	2/17/2016	Add section on TLS support.
4.0.0.002	5/24/2016	Update preparation chapter for the AKM 4.0 HSM release. Update for new version of Encryptionizer.
4.0.0.003	7/18/2016	Update for the AKM 4.0 Azure release.
4.6.1.001	11/8/2019	Updated links and references to technical information.

Chapter 2: NetLib Encryptionizer

The Townsend Security Key Connection for Encryptionizer plugin provides key management for all Encryptionizer platforms. This chapter briefly summarizes the capabilities of NetLib Encryptionizer for those who want to use Alliance Key Manager to protect data encryption keys. For more information, see NetLib’s website at www.netlib.com.

SQL Server encryption

NetLib Encryptionizer provides Transparent Data Encryption and Column Encryption for all versions of SQL Server from 2000 through 2014, and for all editions of SQL Server from Express through Enterprise.

File/Folder encryption

NetLib Encryptionizer provides automatic encryption of folders and files on Windows.

MySQL encryption

NetLib Encryptionizer provides automatic whole database encryption with MySQL.

Application encryption

NetLib Encryptionizer provides client-side file encryption and field encryption for custom or off-the-shelf applications and databases for the desktop or server. You can seamlessly secure almost any database or application on the Windows platform without modification.

Chapter 3: Introduction

This chapter introduces concepts related to using the Key Connection for Encryptionizer plugin, including the use of certificates and private keys, configuration of the client application, and the AKM Key Service.

Certificates and private keys

The client and AKM server use certificates and private keys to authenticate and establish a secure TLS connection. Client certificates must be installed in the Windows certificate store. See subsequent chapters for more information on locating and installing the required certificates.

TLS version

Key Connection for Encryptionizer currently only supports TLS 1.0 for connections with AKM.

Client configuration

You will need to configure the Key Connection for Encryptionizer plugin to authenticate with the AKM server. Configuration includes certificate and private key information, server information, and other properties. You can set the configuration directly in the code of your application or in an application configuration file. See Chapter 7: Configure the Key Connection for Encryptionizer Plugin for more information.

AKM Key Service

The AKM Key Service allows clients to retrieve keys from the AKM server. The Key Connection for Encryptionizer plugin allows you to connect to the AKM Key Service and retrieve keys for use with the Encryptionizer application.

Chapter 4: Preparation

Before setting up key retrieval in your client application, you will need to complete the following steps:

• Install and initialize the primary AKM server and any secondary mirror servers (instructions are located in platform specific deployment guides)

• Create encryption keys (available as an option during AKM server initialization, or, through the AKM Administrative Console application)

• Download authentication certificates from the AKM server

• Know the DNS name or IP address of the AKM server and any secondary mirror servers, and key retrieval port number (the default is 6000)

See below for more information.

Licensing

A temporary or permanent license is required to use or evaluate AKM. All deployments of AKM create a 30-day license automatically during setup and initialization.

A temporary license will enable a fully functional AKM server that may be run in your environment for evaluation. If the temporary license expires, a permanent license may be purchased from Townsend Security or your software vendor. See your AKM platform specific deployment guide for information on installing a permanent license.

Certificates and private keys

The client and AKM server use certificates and private keys to authenticate and establish a secure TLS connection. You will need to install the following certificates and private keys on the client in the Windows certificate store in order to authenticate your client application with the AKM server:

• The primary AKM’s certificate authority (CA) certificate in .pem format

• [Optional] If doing mirroring, the secondary mirror AKM’s CA certificate in .pem format

• Client certificate/private key, installed as one file in PKCS #12 format (.p12 or .pfx), and associated password

SECURITY ALERT: Private key files must be protected during creation, distribution, and storage to prevent loss. The loss of these files will compromise the security of the AKM server. Depending on the file format, the private key files may be bundled with a certificate or they may be separate files. Transfer the private key files by sharing them over a secure network, placing them in a password-protected zip file, sending them using SFTP, or another secure method. Use the same level of care you would employ to protect encryption keys, including encryption. In the event the private keys are compromised or lost, you should immediately replace the certificate authority on the AKM server and all client certificates in that chain of trust. See the AKM Certificate Manager Guide for more information.

Server information

The following server information is required for client configuration:

• The IP address or DNS name of the primary AKM server and any secondary AKM servers

• The port number for key retrieval services on AKM (the default is 6000)

Encryption keys

The name of one or more encryption keys on the AKM server is required to set up client key retrieval.

AKM setup and initialization includes the option to generate an initial set of encryption keys. See your platform-specific AKM deployment guide for more information on encryption keys available for use, if that option was selected.

If needed, encryption keys can be created using the AKM Administrative Console application. See the AKM Administrative Console Guide for more information.

Checklist

To summarize, you will need the following items:

• The primary AKM’s server’s CA certificate in .pem format

• The secondary AKM’s server’s CA certificate in .pem format (if doing mirroring)

• A client certificate/private key in in PKCS #12 format (.p12 or .pfx)

• The IP address or DNS name of the primary AKM server (and any secondary AKM servers) and the key retrieval services port number (the default is 6000)

• The name of one or more encryption keys on the AKM server

Chapter 5: Install Certificates

This chapter describes installing certificates into the Windows certificate store.

Overview

Certificates must be installed in the Windows certificate store for Current User or Local Computer. Install the certificates to the store for Current User if Encryptionizer will be run under the Current User. If Encryptionizer will run as another user, install the certificates in the Local Computer certificate store where they will be available to all users. You will then grant the user running Encryptionizer read permissions to the client private key.

SECURITY ALERT: It is common for SQL Server or other applications to be run under a service account (eg. Network Service) that may not be exclusively used by SQL Server. Your private key must be accessible to the user account that SQL Server uses, but if the account is shared with other applications, this exposes your private key to those applications. Malicious or accidental exposure may result, yielding access to encryption keys on your AKM server.

Therefore, we strongly recommend your application run under a dedicated service account. This is generally a good security practice, and specifically protects access to your encryption keys. If you cannot change the user that your application runs under, then you must grant access to the private key to that user. Be aware, however, of the risk that this creates.

Install locations for certificates are listed below:

• Client certificate and private key - Personal store

• The primary AKM server’s root CA certificate - Trusted Root Certification Authorities store

• The secondary AKM server’s root CA certificate - Trusted Root Certification Authorities store

• Intermediate CA certificate (optional) - Intermediate Certification Authorities store

The configuration for the Key Connection for Encryptionizer plugin uses the thumbprint attributes of the certificates. See below for a detailed guide to installing certificates.

Start the Windows certificate store

Encryptionizer running under Current User

If installation, configuration of the plugin, and Encryptionizer will all be run under the Current User, you can start the Microsoft Management Console (MMC) with the Certificate Manager snap-in for the Current User:

Click Start, Run, and enter “certmgr.msc”. The following panel is displayed:

You can now install certificates to the “Current User” certificate stores. See the section Install the client certificate/private key below.

Encryptionizer running under another user

If Encryptionizer will run as another user, you will need to install the certificates in the “Local computer” store and grant the other user private key access.

Click Start, Run, and enter “mmc”. The following panel is displayed:

Select File, Add/Remove Snap-in. The following panel is displayed:

Select the Certificates snap-in and click Add.

The following panel is displayed:

NOTE: SQL Server or other applications might be installed to run under a Windows Service account. However, if you are using SQL Server it is not necessary to select the Service account option shown above, as you can follow the same steps to grant user permissions to the client private key as described elsewhere in this document.

Select Computer account and click Next. The following panel is displayed:

Select Local computer store and click Finish. In the Add or Remove Snap-ins dialog, click OK.

You can now import certificates to the “Local computer” certificate stores. Certificates installed in the “Local Computer” store will be available to all users. However, whoever installs the private keys will need to grant explicit user access to private keys. See below for more information.

You can add the Certificates snap-in twice (once for “Current User” and once for “Local computer”) if you so choose.

Install the client certificate/private key

Open the Windows certificate store. Right-click on the Personal store. Hover over All tasks. Select Import. The Certificate Import Wizard will open. Click Next. The following panel is displayed:

Click Browse to select the .p12 or .pfx client certificate/private key. You will need to select the “Personal Information Exchange” file format in the file chooser. Click Next. The following panel is displayed:

Enter the password associated with the client private key. The password used when creating the PKCS#12 file is used only in this step; Unless you choose otherwise, once imported, the certificate and private key are unlocked when you log into Windows. If you enter the wrong password, you will not be allowed to proceed.

NOTE: If you want to require the user to enter the password whenever accessing the client private key, check the box to Enable strong private key protection. You will be prompted to enter a password every time the key is used by an application. Do not select this option if you are using the Key Client assembly from a non-interactive program such as a server.

Click Next. The following panel is displayed:

Select Place all certificates in the following store and select “Personal”.

Click Next, then click Finish.

Grant user access to the client private key

If Encryptionizer is run under a different user and you have installed certificates and private keys to Local Computer, you will need to grant read access to the client private key to the user running the client application. To share the client private key with another user, right-click the certificate and hover over All Tasks. Select Manage Private Keys:

In the permissions dialog, select the users or groups to which you would like to grant read access to the client private key.

Install the CA certificates

If using a secondary mirror server, you will need to install both the primary AKM server’s root CA certificate and the secondary AKM server’s root CA certificate.

The process for installing the CA certificates is the same as installing the client certificate/private key with some differences:

• The CA certificates are installed in the Trusted Root Certification Authorities store.

• If using an intermediate CA certificate, this will be installed in the Intermediate Certification Authorities store.

• There will not be a password, as certificates are not password protected.

The first time you import the certificate, you will be warned about trusting the certificate. If the certificate is trusted, click Yes to advance through the warning.

Verify certificate installation

Go to the Action menu and click Refresh. That will refresh the certificate lists, and you should find the newly imported certificates. The client certificate should be in the Personal store, the root CA certificate should be in the Trusted Root Certification Authorities store, and any Intermediate CA certificates should be in the Intermediate Certification Authorities store.

Verify connection to the AKM server

You can use the Tester application to verify the connection to the AKM server and test key retrieval. This will ensure that the network and the certificates just installed are configured properly. See Appendix A: Verify the Connection with Tester for more information.

Find certificate thumbprints

Once the certificates are added to the Windows certificate store, the Key Connection for Encryptionizer plugin will automatically populate with the Certificate Authority and Client Certificate thumbprint information during configuration. If the thumbprint information does not automatically populate, proceed to obtain it manually.

The configuration options for the Key Connection for Encryptionizer plugin identify certificates by thumbprint. You will need to look up the thumbprints of your certificates in order to configure these certificates in your application. To find a certificate’s thumbprint, double-click on the certificate in the Windows certificate store. Click the Details tab and scroll to the bottom of the pane:

Select the Thumbprint field. The thumbprint will populate in the field below and you can copy it.

Chapter 6: Install Key Connection for Encryptionizer

Installation

Use the TownsendSecurity.EncryptionizerKeyProvider.4.6.exe installer located here.

Installed components

The following items are installed to C:\Program Files (x86)\Netlib\SECSQL\Plugins\Townsend: after the Key Connection for Encryptionizer plugin has been configured.

• TownsendSecurity.EncryptionizerKeyProvider.dll (Key Connection plugin assembly)

• TownsendSecurity.KeyClient.dll (Townsend Security Key Client assembly)

• default.config (configuration file for the Key Connection plugin assembly)

• Tester (Tester application to test connectivity to the AKM server and key retrieval)

• Tester.exe.config (configuration file for Tester)

The path to configure TownsendSecurity.EncryptionizerKeyProvider.dll is typically found at c:\Program Files (x86)\NetLib\SECSQL\Plugins\Townsend. The configuration file is automatically created with the Encryptionizer plugin. The file will have the name default.config and can be located in the same directory as the Encryptionizer DLL. In the event the default.config should require an edit, it is best to re-run the Townsend Encryptionizer plugin and save the new changes to the file rather than edit the configuration file directly.

 

Chapter 7: Configure the Key Connection for Encryptionizer Plugin

Overview

The client and AKM server use certificates and private keys to authenticate and establish a secure TLS connection. In addition, the Key Connection for Encryptionizer plugin requires a pinned certificate in the client configuration. Any one of the certificates in the server certificate chain must be identified as the “server certificate”. This could be the root CA certificate, an intermediate CA certificate, or the AKM server certificate(s). The pinned certificate must be installed in the appropriate Windows certificate store as described elsewhere in this document. A standard approach is to use the root CA certificate and this will be used in the examples below. See Appendix B: Certificate Pinning for a discussion of using AKM server certificates in your configuration as pinned certificates for additional security.

Client and Server certificates that contain an issuer OU of “AKM_Certificate_Authority” are selected from the Local Machine and Current User stores in the Windows certificate store. The Encryptionizer plugin should detect the certificates in the Windows certificate store and auto populate each thumbprints in its respective certificate field. If certificates for more than one AKM are present within the Windows certificate store, use the drop down arrows next to the field to select the correct certificate thumbprint. The IP address can be added manually. In the case that the certificate fields do not populate on their own, fill in all the fields manually.

You will need to provide the following information in the configuration:

• IP addresses of the primary AKM server and any additional secondary servers

• Ports on which those AKM servers are configured to perform key retrieval (default: 6000)

• Thumbprint of the primary or secondary AKM’s client certificate

• Thumbprint of primary AKM’s root CA certificate

• Thumbprint of secondary AKM’s root CA certificate (optional)

To begin setup for Key Connection for Encryptionizer, launch TownsendSecurity.EncryptionizerKeyProvider.4.6.exe:

Click Next.

Add the primary AKM server’s IP address, key retrieval port number (default 6000), and encryption port number (default 6003). The primary AKM server’s CA certificate thumbprint should populate automatically but can also be entered manually:

Click Next.

Enter the failover AKM server’s IP address. The failover AKM server’s CA certificate thumbprint should populate automatically but may be entered manually if needed: If not configuring a failover server at this time, click Next to proceed:

The client certificate thumbprint should populate automatically but can be entered manually if needed:

Click Next.

If your certificates are stored in the Personal Store, it is essential to follow the instructions on the “Modify Services Logon” panel. Failing to modify the logon information for the Netlib Encryptionizer Key Management Service could result in errors when attempting to encrypt or decrypt files in a SQL database.

Click Next.

Chapter 8: Configure Encryptionizer

Initial encryption of databases, files, and folders

Open the Encryptionizer Main Menu. It is located under the Start Menu or as a shortcut on the Desktop. Select the Encrypt/Decrypt Wizard box:

Select the Next button on the Welcome panel:

Select the Encrypt Database Files option and click Next:

Navigate to the files you want to encrypt. Before encrypting a SQL database file, navigate to the SQL Server instance (typically MSSQLSERVER) under Services on the Windows Server and select Stop. Database files cannot be encrypted while a SQL server instance is running. The SQL instance can be re-started once the encryption process is complete.

You can alternatively stop the SQL Server instance through the command line with the following command:

The status of the selected file should show “Not Encrypted”. If the status shows “Encrypted” you need to decrypt the file before encrypting it with a different key. The Destination determines the location of the encrypted file. To avoid fragmentation issues, it is best add the encrypted file to the same folder as the unencrypted folder.

When using the GUIs to initially encrypt database, files, and/or folders, specify the desired algorithm and key length. Stream files should always use the AES-CTR option. Then instead of specifying a key pass-phrase, provide the full path to the Key Connection DLL (C:\Program Files (x86)\Netlib\SECSQL\Plugins\Townsend\TownsendSecurity.EncryptionizerKeyProvider.dll by default). Provide the AKM key name in the “Additional Parameters” field:

Click the Next button.

Select Finish on the final panel to start encrypting your files:

A successful encryption is indicated in the final panel. Select the Finish button to exit the Encryptionizer application or Re-Launch to encrypt another file:

Chapter 9: Securing Keys on Database Files

In order to access an encrypted database file in SQL Server, the key used to encrypt the file will need to be secured. To secure the keys, open the Encryptionizer Main Menu and select “Administration Wizard”:

See Encryptionizer documentation for more information on the Administration Wizard.

Select Next on the first panel:

The SQL Server instance should show that it is not secured. Select Next to secure the instance:

Select the Add button to add a key to the SQL Server instance:

There might be a case where more than one key is used to encrypt multiple files. In this case, add each key the SQL server instance.

Click Next.

Enter the algorithm, key length, plugin location and key name in the additional parameters. Select the Save button:

Repeat the process of adding keys as needed. When finished adding keys, select the Next button:

Ensure Encrypt New Backups is selected and click the Next button:

Select Next on the Confirm Encryptionizer panel:

On the Instance Secured panel, select the Finish button to complete the process.

Chapter 10: Support

For customers with permanent licenses, technical support for Alliance Key Manager is available via the website at https://townsendsecurity.com/support/ticket. All others should contact your sales representative.

Please see the Townsend Security Maintenance Policy you received with your purchase for information on fees, online technical support, documentation, license transferability and upgrades, software maintenance, hardware maintenance, customer responsibilities, limitations, disclaimers, lapsed maintenance, enhanced maintenance services, and other topics.

 

Appendix A: Verify the Connection with Tester

The sample application Tester can be used to verify connection to the AKM server and the proper operation of key retrieval.

Obtain a test encryption key

Before continuing, you will need to obtain the name of an encryption key on the AKM server from your Crypto Officer.

SECURITY ALERT: It is strongly recommended that you use a test encryption key for this exercise to avoid accidental disclosure of a production key.

Import the Key Connection for Encryptionizer configuration file

You will need to import the Key Connection configuration file for use with Tester. First rename the existing Tester.exe.config file to Tester.exe.config_backup or similar. Then rename the TownsendSecurity.EncryptionizerKeyProvider.dll.config to Tester.exe.config and place it in the same folder as Tester.

Start Tester and select the option to use the section in the config file. Click Test to ensure that the config file can be parsed. Enter a key name that is valid and refers to an encryption key on the AKM server. AES128 is one of the default keys generated by cloud and virtual implementations of AKM. Click Retrieve to ensure that they key can be retrieved.

Certificates

If you have already installed certificates to the Windows certificate store, you do not need to install them with Tester and you can skip the “Install the certificate files” section below. Note that the method of installing certificates below installs certificates to the certificates stores for “Current User”.

Server information

You will need the IP address of the AKM server and the port number for key retrieval (the default is 6000).

Install the certificate files

Browse to the directory that contains the client certificate/private key .p12 file:

Double click the client certificate/private key file.

Windows will launch the Certificate Import Wizard:

Select Current User and click the Next button to start the import process.

 

The following dialog is displayed with the full path to the certificate file:

Click the Next button to continue.

The password dialog is displayed:

Enter the password for the client private key. Leave the Enable strong private key protection box unchecked. Leave the box for Include all extended properties unchecked.

Click the Next button to continue.

 

The following dialog is displayed:

Select the option to Automatically select the certificate store based on the type of certificate.

Click the Next button to continue.

The completion dialog is displayed:

Click the Finish button to continue.

 

The following warning dialog is displayed:

Click Yes to install the certificate. Click OK on the completion dialog to complete the certificate import.

Run the Tester application

When running the Tester application, you must know the IP address and port number for key retrieval of the AKM server, the name of the CA certificate and client certificates/private key, and the name of the test encryption key you want to retrieve.

IMPORTANT: If using AKM-generated certificates, be sure to select the option to Allow server certificate name mismatch. If this box is not checked, the connection to the server may fail.

Locate the Tester application and launch it by double-clicking the file:

The application will start and display the following dialog:

Server(s): Enter the server address and port number separated by a colon (:). For example, “10.0.1.29: 6000”. 6000 is the default key retrieval port.

Client certificate thumbprint: Click the Select button. This displays a list of certificate thumbprints:

Select the client certificate/private key. Click the OK button to populate the “Client certificate thumbprint” field:

Server certificate thumbprint: Click the Select button. A list of certificate authority certificates is displayed:

Select your CA certificate. Click the OK button to populate the “Server certificate thumbprint” field:

IMPORTANT: Check the box to Allow server certificate name mismatch.

NOTE: You can tell Tester to use the XML configuration file by checking the “Use named section in application configuration file” box.

Key name: Enter a name for the encryption key you want to retrieve. In this example, the encryption key is named “Key01-128”.

To test key caching, enter a timespan. You can also clear the cache, roll the key-caching key, and retrieve key-caching key filenames for the current Windows user.

NOTE: The Key Connection for Encryptionizer plugin provides key caching capabilities, which you can use when running Tester. However, NetLib’s Encryptionizer also provides functionality for key caching, so if you change settings in Tester to minimize key caching, you may see fewer key retrievals than you would expect due to Encryptionizer’s key caching.

Click the Retrieve button to retrieve the encryption key from the AKM server.

If the key retrieval is successful, the following dialog is displayed:

Click the OK button to continue. You may also test the retrieval of other keys.

 

Appendix B: Certificate Pinning

The client and AKM server use certificates and private keys to authenticate and establish a secure TLS connection. In addition, the Key Connection for Encryptionizer plugin requires a pinned certificate. Any one of the certificates in the server certificate chain must be identified as the “server certificate” in the client configuration. It can be the CA certificate, an intermediate CA certificate, or the AKM server certificate itself. The pinned certificate must be installed in the appropriate Windows certificate store as described elsewhere in this document.

Standard approach

The standard approach as described in this document is to install the root CA certificate onto the client in addition to the client certificate/private key. With the Key Connection for Encryptionizer plugin, you can use the alternate method of installing AKM’s server certificates on the client instead of the root CA certificate. This creates a situation where the server certificates are essentially “whitelisted” above and beyond simple trust of the root CA certificate, and you avoid having the root CA certificate installed on the client.

Using AKM server certificates as pinned certificates

If you have multiple AKM servers in your high availability configuration, you will need to install the server certificate of each server on the client and add the thumbprint for each AKM server certificate to the client application configuration.

If you only have one AKM server, you will only need to install one certificate and reference the thumbprint of that certificate in the client application configuration.

Install server certificates in .pem format in the “Trusted People” store of Current User or Local Computer.