Chapter 1: About This Manual

Hardware Security Module

The Alliance Key Manager Hardware Security Module (HSM) is a tamper evident 1u server for customers with traditional IT infrastructure who would like the AKM server to run on their network, or for customers who would like to take advantage of additional physical access controls to protect encryption keys.

Who is this for?

This guide is intended to help project managers, crypto officers, system administrators, and application developers set up the AKM Hardware Security Module. It covers setting up a primary server (and secondary mirror server if needed), creating and downloading certificates for client connections, creating an initial set of encryption keys, creating additional key client and key admin/crypto officer certificates if needed, obtaining a permanent license, and getting support. It also gives an overview of AKM server management and encryption key management.

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 AKM End User License Agreement for more information.

Software updates

Townsend Security will provide you with any needed updates to the web interface, operating system, and key management application through the Townsend Security customer support group.

IMPORTANT: You must not attempt to apply any software updates through automated patch facilities, the web interface, or any updates not directly provided by Townsend Security. Applying these updates will void your warranty, and you may be required to restore your system from backup in order to continue operation.

For current Townsend Security customers migrating to a new AKM server from an older version of AKM, see the section on migration in this guide for instructions. Open a support ticket with Townsend Security for assistance.

Change log

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

Chapter 2: Introduction

This chapter briefly describes the deployment process for the AKM Hardware Security Module. Subsequent chapters describe these steps in more detail.

Set up the AKM HSM

Once the HSM is installed (see Chapter 3: Preparation), setting up the AKM HSM begins with connecting via SSH as the admin user to the primary AKM server. This will launch an Administrative Menu from which you can complete the following tasks:

• Initialize the primary AKM server (either initialize a new server or migrate from a previous version of AKM)

  • Automatically activate the license and create all certificates and private keys needed to set up client/server connections

  • Create an initial set of encryption keys (optional)

• Set the admin password

• Create additional certificates and private keys for client/server connections if needed (optional)

• Collect logs for troubleshooting and print system info if needed

NOTE: Since the certificates and encryption keys are dynamically generated upon initialization, no one except you has access to these components.

After initializing the primary AKM server, you may also initialize a secondary mirror AKM server for real-time key mirroring, high availability, or failover support if needed.

Once you have initialized the primary AKM server and set the password, you can log in to the web interface and download the certificates and private keys needed for client/server connections.

If you set up a secondary mirror server, you should download certificates and private keys after setting up mirroring.

Licensing

The AKM license generated on initialization provides a fully functional AKM server that you can run for 30 days. See Chapter 9: Obtain a Permanent License for information on migrating from a temporary to a permanent license.

IMPORTANT: For AKM to activate the license, your HSM must have a route to the internet. If licensing fails, contact Townsend Security or your software vendor to manually license AKM. Then, see the section Install a new license in Chapter 9 for instructions on manually installing the license.

Certificates

The following certificates are created automatically on initialization and stored on the AKM server:

• Authentication Key (Auth Key) and Key Encryption Key (KEK) certificates and private keys: The KEK and Auth certificate and private key pairs are used by AKM to create the Key Encryption Key (KEK) and Authentication Key (Auth Key), two symmetric keys that are stored on the AKM server. These “secret keys” are used by AKM to protect your data encryption keys. You will not need to use or distribute the KEK and Auth certificates and private keys.

• Server certificate and private key: These are used by AKM servers to authenticate with each other for mirroring, and to authenticate with client applications.

• Certificate authority (CA) certificate: This is a unique CA certificate that is used to sign admin and key client certificates. Admin and key clients must install the CA certificate to authenticate with the AKM server. The CA certificate will also be used to sign additional admin (Crypto Officer) and client certificates if needed. See Chapter 7: Create Additional Admin and Client Certificates for more information.

• Admin certificates and private keys: Admin certificates and private keys allow for authentication between admin clients and the AKM server, and are used by crypto officers for key creation and management in the AKM Administrative Console. Two admin certificates are created by default to support dual control. See the AKM Administrative Console Guide for information on key creation, key management, and enabling dual control.

• Client certificate and private key: Client certificates and private keys allow for authentication between key clients and the AKM server when retrieving keys or sending sensitive data to the AKM server for remote encryption. One client certificate/private key is created by default and additional client certificates and private keys can be created at any time.

After setting up the AKM HSM, you can immediately download and distribute certificates and private keys to client application developers and crypto officers for client configuration. After you initialize the primary AKM server, you will be presented with the option to create additional admin and client certificates and private keys if needed. See Chapter 7: Create Additional Admin and Client Certificates for more information.

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.

Encryption keys

On initialization, you will be given the option to generate an initial set of encryption keys. You can use these encryption keys in client applications for proof of concept, development, or production. If you need to create additional encryption keys or manage existing keys, you can do so at any time using the AKM Administrative Console.

Chapter 3: Preparation

Install the HSM

First you must install the HSM 1u server. See the AKM Hardware Installation Guide and the Hardware Rails Specification for installation instructions.

Download Client Applications or SDKs

Visit this page https://info.townsendsecurity.com/alliance-key-manager-evaluation for a current list of client applications, software libraries, and code samples.

Chapter 4: Set up AKM

Setting up the AKM HSM includes the following steps:

• Initializing the primary AKM server
• Creating an initial set of encryption keys (optional)
• Setting the admin password for the primary AKM server
• Initializing the secondary AKM server (optional)
• Creating additional admin and client certificates (optional)
• Exiting to a shell (optional)
• Disconnecting from AKM

These steps are completed through a text interface Administrative Menu.

Overview

The initialization process sets up the AKM server, creates a unique CA certificate for use with AKM, creates all certificate and private key pairs needed for server/client communication, and activates the license. You will also have the option to create an initial set of encryption keys to use during testing or production.

After initializing the primary AKM server and setting the admin password, you can set up a secondary AKM server if needed. A secondary AKM server can be used for real-time key mirroring, high availability, or failover support. To set up a secondary AKM server, you will have to disconnect from the primary AKM server and reconnect using the IP address or hostname of the secondary AKM server.

After you initialize the primary AKM server, you will have the option to create additional admin and key client certificate and private key pairs via the Certificate Manager option on the text interface Administrative Menu if needed.

Other administrative options include exiting to a shell, collecting logs for support, and disconnecting from AKM. You can exit to a shell if you need direct access to the OS for control over Linux options and facilities (enter akm-menu to return to the Administrative Menu). You should disconnect from AKM when you are finished with the session.

Initialize the primary AKM server

Open an SSH connection to the primary AKM server using the primary AKM server’s DNS name or IP address. For example:

ssh admin@IPaddress

The default password is OOHXPq6r530N6re.

NOTE: OS X users can use the Terminal application. Windows users can connect to the server using PuTTY. See Appendix A: Connect with PuTTY for more information.

IMPORTANT: For AKM to activate the license, your HSM must have a route to the internet. If licensing fails, contact Townsend Security or your software vendor to manually license AKM. Then, see the section Install a new license in Chapter 9 for instructions on manually installing the license.

Indicate that you have read and accept the AKM End User License Agreement (available here) to continue with initialization:

The Administrative Menu is displayed:

Initialize the primary AKM server

Enter option 1 to Initialize AKM. The Initialization Menu is displayed:

Enter option 1 to Initialize as PRIMARY. This will designate this server as a primary AKM server and start the initialization process.

NOTE: In the context of mirroring, a primary AKM server either operates alone or sends mirrored keys and metadata to any number of mirror servers. You must initialize a primary server first and can then initialize any additional mirror servers. A server initialized as a primary can also receive mirrored keys in a bidirectional mirroring configuration.

You will be prompted to enter the two-character country code, the name of your state or province, your city/locale, and your organization name (for example, your company name), and a unique name for this AKM server:

Create an initial set of encryption keys

You will be prompted to create an initial set of encryption keys:

Enter y if you would like to create an initial set of encryption keys. You can use these encryption keys for proof of concept, development, or production. Enter N if you do not want to create encryption keys at this time. You can also create encryption keys at any time using the AKM Administrative Console. See Chapter 6: Create and Manage Encryption Keys for more information.

NOTE: Creating encryption keys at this point is optional and does not affect the operation of AKM. However, it may be convenient to have keys available for development or proof of concept without having to use the AKM Administrative Console to manually create encryption keys. See this section for a list of keys that are created with this option.

AKM will now initialize. Make sure you do not interrupt this process:

The primary AKM server has now initialized and AKM is running. The server time has been synchronized with a time server (time.nist.gov).

The initialization process has created a unique certificate authority (CA) certificate and server certificate for AKM, activated the license, and generated client certificate and private key pairs needed for key clients and admin clients to connect to the AKM server.

By default, one client certificate and two admin certificates are created by the initialization process. Two admin certificates are created in order to support dual control of encryption key administration. You can create additional client or admin certificates at a later time.

IMPORTANT: The CA certificate created during this process is unique and should only be used with AKM, and you do not need to create an additional CA certificate for use with AKM.

Press any key to return to the main menu. After initialization, the following menu is displayed:

Set the admin password

After initialization you should change the password for the server. This password will be used to access the Administrative Menu on all future sessions and to log in to the AKM server via the web interface.

From the Administrative Menu, enter the option to Set admin password. You will be prompted to change the admin password:

When prompted to enter a “New Password”, enter your new admin password. This is the password you will use when logging in to the AKM web interface as the “admin” user for server management.

Set a strong password and protect it carefully, as the compromise of this password breaches the security of AKM. If you set a weak password you will receive a warning, but the password will still be accepted. It is recommended to set a password of at least 15 characters that includes upper and lower case letters, numbers, and symbols.

IMPORTANT: Do not lose this password, as there are no backdoors to recover it. If you lose the password please do not contact your software vendor to recover it for you, as this is not possible.

When prompted, reenter the password. The password has now been changed and will be used to access the primary AKM server’s Administrative Menu for all future sessions. You will also use this password and username “admin” to log in to the primary AKM server web interface to download client certificates and perform other server management tasks.

Initialize a secondary mirror server

After initializing the primary AKM server, you can set up additional mirror AKM servers for real-time key mirroring and high availability failover support.

Setting up mirror servers at this point is optional and can be completed at a later time.

NOTE: If there is a firewall in place between the primary AKM server and any mirror servers, be sure that ports 22 and 6002 are open before setting up mirroring.

SSH Key Pairing Options

During mirroring setup, you will be prompted to establish authentication between the two servers using an SSH key. You can accomplish this in one of three ways: by copying the primary AKM server’s public SSH key and pasting it into the menu of the secondary AKM server, by downloading the public SSH key from the primary and uploading it to the secondary, or by using an already established SSH key.

Option 1: Paste the SSH public key

This is the most common option to exchange an SSH key between a secondary and primary AKM server.

Open the Administration Menu on the primary AKM server and select option 2) Mirroring after initializing the server. The Mirror Configuration Menu is displayed:

Select 1) Add mirror. Copy and save the SSH public key displayed on the screen.

Connect via SSH to the secondary AKM server and log in using the command prompt with user “admin” and the default password OOHXPq6r530N6re to launch the Administrative Menu.

SECURITY ALERT: It is recommended to change the admin password for the mirror server at this time if you have not done so already.

Select option 1) Initialize AKM, then select option 2) Initialize as MIRROR.

Enter the locality information and unique name for this server, then wait for the server to initialize.

Return to the main menu. Selection the option for Mirroring and then select the option to Accept mirrored keys. You will see three options for establishing authentication using an SSH key:

Select option 1 and press Enter. Paste the SSH public key of the primary AKM server into the console.

NOTE: If you are using PuTTY on Windows, right-click in the console to paste the SSH public key.

After pasting in the SSH public key, press Enter, then press Ctrl-D to continue mirroring setup:

Copy the fingerprint of this AKM for later verification. Press any key to return to the main menu.

Return to the primary AKM server’s Mirror Configuration Menu and press Enter:

Enter the IP address of the secondary mirror server to complete mirroring setup. Verify the fingerprint of the mirror server and enter yes to continue. Wait for mirroring setup to complete. Do not interrupt this process.

Option 2: Upload the public SSH key to the server

Instead of copying and pasting the SSH public key, you may download the SSH public key from the primary AKM server, then upload it to the secondary mirror AKM server.

Open the Administration Menu on the primary AKM server and select option 2) Mirroring after initializing the server. The Mirror Configuration Menu is displayed:

Select 1) Add mirror.

Connect via SSH to the secondary AKM server and log in using the command prompt with user “admin” and the default password OOHXPq6r530N6re to launch the Administrative Menu.

SECURITY ALERT: It is recommended to change the admin password for the mirror server at this time if you have not done so already.

Select option 1) Initialize AKM, then select option 2) Initialize as MIRROR.

Enter the locality information and unique name for this server, then wait for the server to initialize.

Return to the main menu. Selection the option for Mirroring and then select the option to Accept mirrored keys. You will see three options for establishing authentication using an SSH key:

On the secondary AKM server select option 2 from the SSH menu:

Log in to the primary AKM server web interface and navigate to File Manager.

The SSH public key is located in /home/admin/.ssh/ and is called id_rsa.pub.

Select this file and double click to save. Log in to the secondary AKM server web interface and upload this file to /home/admin/uploads/ via File Manager.

Return to the SSH menu on the secondary AKM server and press any key to continue:

Enter y to confirm that you would like this secondary AKM server to accept mirrored AKM keys from the primary.

Note the fingerprint of the secondary AKM for later confirmation.

Return to the primary AKM server Administrative Menu, then use the mirroring menu to select the secondary AKM as its mirror. Confirm the fingerprint of the secondary AKM server.

Mirroring setup is complete.

Option 3: Use an established SSH key

Use this option if the public SSH key has already been authenticated but mirroring setup was not completed.

Connect via SSH to the secondary AKM server and log in using the command prompt with user “admin” and the default password OOHXPq6r530N6re to launch the Administrative Menu.

SECURITY ALERT: It is recommended to change the admin password for the mirror server at this time if you have not done so already.

Select option 1) Initialize AKM, then select option 2) Initialize as MIRROR.

Enter the locality information and unique name for this server, then wait for the server to initialize.

Return to the main menu. Selection the option for Mirroring and then select the option to Accept mirrored keys. You will see three options for establishing authentication using an SSH key:

Select option 3 from the SSH menu of the secondary AKM server:

You should see the name of the primary AKM server under the list of public keys that are already trusted. If not, establish trust using one of the previous authentication options.

Enter y to confirm that you want the secondary AKM server to receive keys from this server. Wait for mirroring setup to complete.

Once mirroring setup is complete, press any key to return to the main menu.

Disable automatic rollover on the secondary AKM (IMPORTANT)

The automatic rollover attribute must be disabled on any secondary mirror servers. That way, keys with the automatic rollover attribute are only rolled on the primary server, and the new keys then mirrored to the secondary server. You would not want the mirrored keys on the secondary server (which are mirrored with the same automatic rollover attribute) to roll once again on the secondary, independent of and without the knowledge of the primary server.

Log in to the secondary mirror server via the web interface and select File Manager from the left navigation menu. Navigate to the /etc/akm directory and select akm.conf, then click the Edit in the Actions column.

Locate the [AutomaticRollover] section and set Enabled to N. Click the Save and Close button. Stop and restart AKM via the Custom Commands link.

Next steps

After setting up mirroring, bundled CA certificate files are created which contain the CA certificates of both AKM servers. These must be installed on any client connecting to AKM along with the client certificate and private key.

If you have previously set up clients before setting up mirroring, the CA certificates installed on the client must be replaced with the CA certificate bundle. See the section Set up key and admin clients for more information. The client certificate and private key files do not need to be replaced.

NOTE: If a bidirectional mirroring configuration is desired, continue with the steps in Appendix B: Set up Bidirectional Mirroring.

Certificate Manager

After initialization, you will be presented with the option to Start Certificate Manager when you return to the Administrative Menu.

On initialization, AKM generated one client certificate and private key pair for a client application to authenticate with the AKM server to perform key retrieval or remote encryption. Two admin certificate and key pairs were created for Crypto Officers to manage encryption keys on the AKM server.

You only need to run the Certificate Manager if you need to create additional admin or client certificates or sign a CSR. See Chapter 7: Create Additional Admin and Client Certificates for more information.

IMPORTANT: Initialization of the primary AKM server creates a unique CA certificate which is used to sign all client certificates. This CA certificate should only be used with AKM, and you do not need to create an additional CA certificate for use with AKM.

By default, one client certificate and two admin certificates are created by the initialization process. Two admin certificates are created in order to support dual control of encryption key administration.

Other administrative options

This section describes other Administrative Menu options.

Migrate (Initialize from backup)

Current Townsend Security customers can migrate the key database and authentication certificates from an earlier version of AKM to a new AKM.

Start a support ticket on the Townsend Security website for assistance with the migration, including information about transferring your permanent license to your new AKM. Follow the steps below to migrate the key database and authentication certificates.

Log in to the web interface of the server you wish to migrate from and run both an application and a secret key backup, selecting a local folder on AKM as the destination. For more information on running a backup, see the AKM Server Management Guide.

Navigate to the directory in File Manager where you saved the backups, and double click to save.

Log in to the new AKM server via the web interface. Use File Manager to upload both files to the /home/admin/uploads directory.

Connect via SSH to the new AKM server and launch the Administrative Menu. Select the option to Initialize AKM, then select the option to Migrate (Initialize from BACKUP). Press Enter.

Wait until the migration is successful and AKM has started. Do not interrupt this process.

This initialization option does not include the creation of new client and admin certificates. Use the Start Certificate Manager option in the main menu if new certificates are needed. See the next chapter for information on downloading these certificates.

Client certificates already in use in client applications will still be valid to connect to AKM. However, if the new AKM has a different IP address than the previous AKM, this will need to be updated in the client application configuration.

Start/Stop AKM

After initializing the server, the main Administrative Menu will include the option to Stop AKM. This stops key services and prevents all clients from connecting to AKM. When AKM is stopped, you can select the option to Start AKM to restart key services.

Disable Webmin

You will use the web interface to download key and admin client certificates and private keys in the next chapter. However, it is recommended to disable the web interface to the AKM server when not in use. From the Administrative Menu, select the option to Disable Webmin. Follow the prompts to disable the web interface.

Support

Collect logs for troubleshooting

For problem determination, you can view logs. From the Administrative Menu, select the Support option to Collect logs for troubleshooting. See Chapter 10: Support for more information.

Print System Info

Selecting this option will display system version information.

Fix akm.conf

This option will appear if there is a conflict between the IP address assigned to the AKM server and what is listed in the AKM configuration file (akm.conf). Selecting this option will resolve the conflict by resetting all IP addresses to default (0.0.0.0). This will remove any manual changes you have made to the AKM configuration file IP addresses.

Exit to shell

You can exit to a shell if you need direct access to the OS for control over Linux options and facilities.

Disconnect from AKM

You should disconnect from AKM when you are finished with the session.

Next steps

You can now log in to the AKM server web interface and download admin and client certificate and key pairs for distribution to admin and key clients. See Chapter 5: Start Using the AKM HSM for more information.

Chapter 5: Set up Key and Admin Clients

Overview

To get started using AKM, you will need to set up your key clients for key retrieval and/or remote encryption. You will first log in to the AKM server web interface and download the client certificates and private keys needed for client/server connections. You will then give a key client certificate and private key plus the name of one or more AKM encryption keys to your client application developer. You can also download admin client certificates needed for encryption key management functions in the AKM Administrative Console.

Log in to the web interface

Open a web browser and connect to the primary AKM virtual machine via a secure HTTPS connection. You will use the DNS name or IP address and the web interface port number (default 3886) for the primary AKM server:

• https://PrimaryAkmIPAddress:3886

NOTE: AKM generates a private SSL certificate during initialization, so you will likely be presented with a browser security warning. Choose the option to proceed.

The login page is displayed:

NOTE: A different IP address may be displayed.

Enter the default username “admin” and the password you set during initialization. Click Login.

The following page is displayed:

Click the green arrow next to “AKM” to expand the navigation pane:

The navigation pane contains different options for managing the AKM server, including backup/restore, mirroring and logging. See the AKM Server Management Guide for information on these tasks.

To verify that AKM is running, click on the link for Running Processes in the navigation pane. Click Search in the Display menu at the top of the page. Select Matching, enter “akmd”, and click Search. If AKM is running, you will see it listed as a running process:

If AKM is not running, click on the link for Custom Commands in the navigation pane. Click on the Start AKM button to start the AKM process and click Return to commands. Check the Running Processes tab again for the “akmd” process.

If the “akmd” process is still not running, navigate back to Custom Commands and click on the Display AKM Error Log Snippet button. This will display a list of recent errors to help with problem determination. Contact Townsend Security or your software vendor if you need assistance.

IMPORTANT: If you are deploying the AKM HSM in a production environment, you may need to install software patches. If there are any necessary software patches available from Townsend Security or your software vendor, you should install them now.

Set up key and admin clients

Setting up key clients for key retrieval or remote encryption includes downloading and distributing client certificates and giving the name of an encryption key to your client application developer.

To set up admin clients for key management in the AKM Administrative Console, you will download admin certificates and private keys.

SECURITY ALERT: The private key files associated with admin and key client certificates must be protected during creation, distribution, and storage. The loss of these files will compromise the security of any encryption keys this client has access to. Depending on the file format, the private key files may be bundled with a certificate or they may be separate files. Transfer these 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 certificates 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 HSM Quick Start Guide for more information.

In the web interface for the primary AKM server, click on the link for File Manager in the navigation pane. File Manager is used for managing the files on the AKM server.

Download key client certificates

Key client certificates are used in client applications for key retrieval or remote encryption and decryption on the AKM server.

Your client application developer will need AKM’s CA certificate or a CA certificate bundle (when implementing mirroring), a client certificate/private key pair, and any associated passwords to set up client applications for key retrieval or remote encryption on the AKM server.

The format of the certificate files your client application developer will need depends on the platform and language of the client application environment.

If using a secondary mirror server, follow the steps in the section Certificates to use after setting up mirroring.

NOTE: If you do not need to control access to keys, you can use the same client certificate/private key in each client application. If you need to control access to keys, each client application will need a unique client certificate/private key. See Chapter 7: Create Additional Admin and Client Certificates for information on creating additional client certificates.

Certificates to use prior to setting up mirroring

In File Manager, navigate to the /home/admin/downloads/ directory. Client certificates are located in <AKMServerName>_user.zip. Select <AKMServerName>_user.zip and double click to save. Unzip this archive.

The following certificates and private keys can be used to set up key clients before mirroring setup:

• /JKS

  • AKMClientKeystore.jks (client certificate/private key)

  • AKMClientPassword.txt (client certificate/private key password)

  • AKMRootCATruststore.jks (AKM’s CA certificate)

  • AKMRootCATruststorePassword.txt (the CA certificate password)

• /KeyConnection

  • AKMClientCertificateAndPrivateKey.p12 (client certificate/private key)

  • AKMClientPassword.txt (client certificate/private key password)

  • AKMRootCACertificate.pem (AKM’s CA certificate)

• /P12

  • AKMClientCertificateAndPrivateKey.p12 (client certificate/private key)

  • AKMClientPassword.txt (the client certificate/private key password)

• /PEM

  • AKMClientCertificate.pem (client certificate)

  • AKMClientPrivateKey.pem (client private key)

  • AKMRootCACertificate.pem (AKM’s CA certificate)

  • <PrimaryAKMServerName>.AKMServerCertificate.pem (the primary AKM’s server certificate, used for “certificate pinning”)

Certificates to use after setting up mirroring

After mirroring setup, you will need to use a bundle containing the CA certificates of both AKM servers along with the client certificate and private key. Log in to the web interface and redownload <AKMServerName>_user.zip to gain access to the new mirroring configuration certificates used in client applications after a mirroring pair has been established.

If you have previously set up clients before setting up mirroring, the CA certificates installed on the client must be replaced with this new CA certificate bundle (.pem or .jks) for seamless client failover when AKM is unreachable. The client certificate and private key files do not need to be replaced.

NOTE: When setting up clients in a Windows environment, Windows Certificate Store will not import all of the CA certificates in the bundle. In this case, the primary and secondary mirror CA certificates must be imported individually.

In File Manager, navigate to the /home/admin/downloads/ directory. Client certificates are located in <AKMServerName>_user.zip. Select <AKMServerName>_user.zip and double click to save. Unzip this archive.

The following certificates and private keys can be used to set up key clients after mirroring:

• /JKS

  • AKMClientKeystore.jks (keystore containing the client certificate/private key)

  • AKMClientPassword.txt (keystore password)

  • /Mirror_Config_Certificates

    • AKMTruststoreBundle.jks (truststore bundle containing both AKM’s CA certificates)

    • AKMTruststoreBundlePassword.txt (truststore password)

• /KeyConnection:

  • AKMClientCertificateAndPrivateKey.p12 (client certificate/private key)

  • AKMClientPassword.txt (client certificate/private key password)

  • /Mirror_Config_Certificates

    • <PrimaryAKMServerName>.AKMRootCACertificate.pem (the primary AKM’s CA certificate)

    • <MirrorAKMServerName>.AKMRootCACertificate.pem (the mirror AKM’s CA certificate)

• /P12

  • AKMClientCertificateAndPrivateKey.p12 (client certificate/private key)

  • AKMClientPassword.txt (the client certificate/private key password)

• /PEM

  • AKMClientCertificate.pem (client certificate)

  • AKMClientPrivateKey.pem (client private key)

  • <PrimaryAKMServerName>.AKMServerCertificate.pem (the primary AKM’s server certificate, used for “certificate pinning”)

  • /Mirror_Config_Certificates

    • <PrimaryAKMServerName>.AKMRootCACertificate.pem (the primary AKM’s CA certificate)

    • <MirrorAKMServerName>.AKMRootCACertificate.pem (the mirror AKM’s CA certificate)

    • AKMRootCertificatesBundle.pem (bundle with both AKM’s CA certificates)

Download Crypto Officer certificates

Crypto Officer certificates are used to connect to AKM for key management operations.

Your Crypto Officer will need the AKM CA certificate truststore or truststore bundle (when implementing mirroring), and an admin client certificate/private key keystore in .jks format, as well as any associated passwords, to use the AKM Administrative Console to create and manage encryption keys.

.pem files can be used for admin clients under program control if needed. See the AKM Admin API Reference for more information on using admin commands under program control.

If using a secondary mirror server, follow the steps in the section Certificates to use after setting up mirroring.

Certificates to use prior to setting up mirroring

In File Manager, navigate to the /home/admin/downloads/ directory. Crypto Officer certificates are located in <AKMServerName>_admin1.zip and <AKMServerName>_admin2.zip in the /home/admin/downloads/ directory on the primary AKM server.

Two unique sets of admin certificates are provided if you want to implement PCI requirements around dual control of key management operations.

Select <AKMServerName>_admin1.zip and/or <AKMServerName>_admin2.zip and double click to save. Unzip the archives.

The following files can be used to set up admin clients before mirroring setup:

• /PEM

  • AKMAdminCertificate.pem (admin certificate)

  • AKMAdminPrivateKey.pem (admin private key)

  • AKMRootCACertificate.pem (AKM’s CA certificate)

• /Admin_Console

  • AKMAdminKeystore.jks (admin keystore)

  • AKMAdminKeystorePassword.txt (admin keystore password)

  • AKMRootCATruststore.jks (admin truststore with AKM’s CA certificate)

  • AKMRootCATruststorePassword.txt (admin truststore password)

Certificates to use after setting up mirroring

After mirroring setup, you will need to use a truststore bundle containing the CA certificates of both AKM servers, along with the keystore file.

Log in to the web interface and redownload <AKMServerName>_admin1.zip and <AKMServerName>_admin2.zip (if implementing dual control) to gain access to the new mirroring configuration certificates used in the admin application after a mirroring pair has been established.

If you have previously set up the admin client before setting up mirroring, the CA certificates installed on the client must be replaced with the new CA certificate bundle (.pem or .jks) for seamless client failover when AKM is unreachable. The client certificate and private key (.pem or .jks) do not need to be replaced.

NOTE: If setting up an admin client under program control in a Windows environment with .pem files, Windows Certificate Store will not import all of the CA certificates in the bundle. In this case, the primary and secondary mirror CA certificates must be imported individually.

The following files can be used to set up admin clients after mirroring:

• /PEM

  • AKMAdminCertificate.pem (admin certificate)

  • AKMAdminPrivateKey.pem (admin private key)

  • /Mirror_Config_Certificates

    • <PrimaryAKMServerName>.AKMRootCACertificate.pem (the primary AKM’s CA certificate)

    • <MirrorAKMServerName>.AKMRootCACertificate.pem (the mirror AKM’s CA certificate)

    • AKMRootCertificatesBundle.pem (bundle with both AKM’s CA certificates)

• /Admin_Console

  • AKMAdminKeystore.jks (admin keystore)

  • AKMAdminKeystorePassword.txt (admin keystore password)

  • /Mirror_Config_Certificates

    • AKMTruststoreBundle.jks (truststore bundle with both AKM’s CA certificates)

    • AKMTruststoreBundlePassword.txt (truststore bundle password)

Give the name of an encryption key to your client application developer

If you created a set of initial encryption keys on initialization of the primary AKM server, the following keys are immediately available for use:

• AES128 - 128-bit symmetric key, general access

• AES192 - 192-bit symmetric key, general access

• AES256 - 256-bit symmetric key, general access

• EKM128 - 128-bit symmetric key for use with SQL Server EKM, enabled for EKM

• EKM256 - 256-bit symmetric key for use with SQL Server EKM, enabled for EKM

• EKMSS - 2048-bit RSA key for use by SQL Server EKM, enabled for EKM

• RSA1024 - 1024-bit RSA key

• RSA2048 - 2048-bit RSA key

• RSA3072 - 3072-bit RSA key

• RSA4096 - 4096-bit RSA key

Give the name of the appropriate encryption key to your client application developer.

SECURITY ALERT: These encryption keys are set for general access. That means anyone with a valid key client certificate for AKM can retrieve these keys or use them for remote encryption. If you have multiple clients and you would like to implement key access control, you can change the access level for these keys or create new encryption keys with a restricted access level in the AKM Administrative Console. Key Access is based on the Common Name (CN) and Organization Unit (OU) of the client certificate which you entered earlier. See Chapter 6: Create and Manage Encryption Keys for more information.

Chapter 6: Create and Manage Encryption Keys

If you created a set of encryption keys during initialization of the primary AKM server, you can use one of these encryption keys. If you would like to manage these encryption keys (for example, to change the access policy) or create new encryption keys, you can do so using the AKM Administrative Console.

AKM Administrative Console

The AKM Administrative Console is a Windows application with a GUI interface for one or more Crypto Officers to create and manage encryption keys. See the AKM Administrative Console Guide for detailed instructions on installing and using the AKM Administrative Console.

To set up the Admin Console, you will need the AKM CA certificate truststore or truststore bundle and an admin client certificate/private key in .jks format and passwords for these files.

If you are using the Admin Console after setting up mirroring, you will need to use the CA certificate truststore bundle which contains the CA certificates of both AKM servers (AKMTruststoreBundle.jks) and the associated password.

See the section Download Crypto Officer certificates for information on downloading the truststore and keystore.

IMPORTANT: By default, two sets of admin certificates and private keys are generated for two Crypto Officers in order to support dual control (<AKMServerName>_admin1.zip and <AKMServerName>_admin2.zip). To authorize a second Crypto Officer to use the Admin Console, you will need to follow the same steps using the <AKMServerName>_admin2.zip file. See the AKM Administrative Console Guide for information on implementing dual control.

When opening the AKM Administrative Console for the first time, the following dialog is displayed:

This dialog allows you to define the AKM server to which you want to connect using the AKM Administrative Console.

Server Name: Enter a name of your choosing for this key server.

Server Address: Enter the IP address or hostname of this key server (example: cloud-service-name.cloudapp.net).

Server Port: Enter the admin port number (the default is 6001).

Key Store File: Click Browse and select AKMAdminKeystore.jks.

Passphrase: Enter the password contained in the AKMAdminKeystorePassword.txt file.

Trust Store File: Click Browse and select AKMRootCATruststore.jks (or AKMTruststoreBundle.jks if you have already set up mirroring).

Passphrase: Enter the password contained in the AKMRootCATruststorePassword.txt file (or AKMTruststoreBundlePassword.txt if you have already set up mirroring).

Click Add. You are now authorized to create and manage encryption keys on the AKM server. See the AKM Administrative Console Guide for more information.

Verify the connection to AKM server

In the AKM Administrative Console you will see a list of options in the left pane. Expand the option for Status and select the link for Administrative NoOp. Click Submit. You should see the following output in the right pane:

AKM_222 (10.0.1.230 port 6001)
------------------------------------------
Command: Administrative NoOp
------------------------------------------
Server: AKM_222 (10.0.1.230 port 6001)
  Transaction Length: <00008>
  Transaction Id: <1044>
  Return Code: <0>
  Command completed successfully.
Command Output: 
  No additional command output
---------------------------------------
End Command Administrative NoOp
---------------------------------------

You are now ready to use the AKM Administrative Console to create and manage encryption keys.

Create a new encryption key

To create a new encryption key, expand the option for Manage Keys in the left pane and select the Create Symmetric Key command. Next you will define attributes for the encryption key in the middle pane. First give your key a user-friendly name and a key size. For evaluation purposes check the box next to Activate key immediately and Key never expires, and select the option for Anyone to access the key. For production encryption keys, the expiration date of the key should be determined by your organization’s policy on cryptoperiods, and you should use a restricted key access policy. Define additional options for the key and scroll down to click the Submit button to create the key. You should receive the following output:

Command: Create Symmetric Key
------------------------------------------
Server: 10.0.1.230 (10.0.1.230 port 6001)
  Transaction Length: <00072>
  Transaction Id: <1002>
  Return Code: <0>
  Command completed successfully.
Command Output: 
  Key Name: <TEST KEY               >                 
  Key Instance: <SAZ4he9kkZYjmF5+n2A6Mg==>
---------------------------------------
End Create Symmetric Key Command
---------------------------------------

You will now be able to use this encryption key in your client application.

Set key access policy on an encryption key

To modify the key access policy on an existing encryption key, expand the option for Manage Key Attributes in the left pane and select the Set Key Access Flag command. Enter the key name and select the desired key access policy. See the AKM User Guide for more information on key access control.

Chapter 7: Create Additional Admin and Client Certificates

During initialization, AKM automatically generates a certificate authority (CA) certificate, two admin (Crypto Officer) certificates and one client (key retrieval or remote encryption) certificate. For information on using these certificates, see Chapter 5: Start Using the AKM HSM and Chapter 6: Create and Manage Encryption Keys.

If you need to create additional key client certificates, admin certificates, or import certificate signing requests, you can do so using the Certificate Manager option. Connect via SSH to the primary AKM server and log in with user admin and the password you set during initialization. After initialization, the Administrative Menu has an the option to Start Certificate Manager. Select this option to display the Certificate Menu:

Create an admin certificate

Enter option 1 to Create an admin client certificate and key pair. This will create an additional admin certificate and private key for a Crypto Officer to manage encryption keys. You will be prompted to enter a unique Common Name (CN) for this admin certificate:

The admin certificate files have been created and are available in the /home/admin/downloads/ directory on the AKM server.

Create a key client certificate

From the Certificate Menu, enter option 2 to Create a key client certificate and key pair. This will create an additional client certificate and private key for key clients to perform key retrieval or encryption and decryption on the AKM server. You will be prompted to enter a unique Common Name (CN) and Organizational Unit (OU) for this key client certificate:

The key client certificate files have been created and are available in the /home/admin/downloads/ directory on the AKM server.

SECURITY ALERT: If you are using an encryption key created on initialization of the primary AKM server and you want to use key access control, you will need to modify the key access policy of the encryption key and enter User and Group information that matches the Common Name (CN) and Organizational Unit (OU) of the key client certificate. See Chapter 6: Create and Manage Encryption Keys for more information.

Import and sign certificate signing requests

If you are on the IBM i platform, you will need to import a certificate signing request (CSR) to be signed by AKM’s CA certificate to create a signed key client certificate. For information on creating a certificate signing request, see the document AKM DCM Configuration for IBM i.

From the Certificate Menu, enter option 3 to Import and sign certificate signing requests. The following screen is displayed:

Log in to the AKM web interface as the “admin” user with the password you created above. Click on the link for File Manager in the left navigation pane. Upload the CSRs to the /home/admin/uploads/ directory. You can upload multiple CSRs. After uploading the CSRs, return to the Certificate Menu and press Enter. The following screen is displayed:

AKM will detect the Common Name (CN) of each CSR and use it to name the client certificate files. The signed client certificate files are available in the /home/admin/downloads/ directory on the AKM server.

Chapter 8: Manage the AKM Server

Server management

Backup and restore, system logging, and firewalls can be configured via the web interface. See the AKM Server Management Guide for information on these tasks. See the AKM User Guide for more detail on these concepts.

IMPORTANT: You should perform a backup of the AKM server as soon as you have finished setting up the AKM HSM, and periodically after any significant changes to keys, user access policies, and certificates.

Software updates

Each time you log into the Webmin UI, you will see new package updates available on the dashboard.

When you click on the package updates section you will be taken to a list of the available updates. You should see something similar to the image below.

You can apply all available updates by selecting the select all option. Once you have made your selection you can click the button to Update Selected Packages. You can specify to be alerted of new updates via email if you need. This feature can be found by scrolling to the bottom of the list. You will be able to set an interval to check for updates, as well as provide an email and specify any action to be taken.

After clicking Update Selected Packages you will be taken to the screen below to confirm and install the updates. Click on Install Now when you are ready to begin the update.

You will see the output similar to what is shown below. The update process is done when you see install complete at the bottom of the output window.

Your updates will be complete at this point and any future updates can be applied in this manner as well.

NOTE: An alternative method to update your AKM can be completed via the AKM shell. This method requires accss to the AKM shell using SSH, Putty, your VM console, or a dummy console. Once connected, you can issue the command sudo apt-get update to list the available packages for update. When you are ready to apply the update, you will issue the command sudo apt-get upgrade. The process may take a few moments to finish.

Certificate backup

You should back up all certificate and private keys used by AKM. See the AKM Server Management Guide for more information.

SECURITY ALERT: Private key files must be protected during creation, distribution, and storage. The loss of these files will compromise the security of the AKM server. Transfer the certificate 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 from loss, including encryption. In the event the client certificates 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 HSM Quick Start Guide for more information.

Chapter 9: Obtain a Permanent License

Install a new license

Log in to the AKM web interface and click on the link for Custom Commands in the left navigation pane. Click on the link to Display eth0 MAC address. Copy the MAC address into an email message and send it to your presales engineer or account manager. Be sure to include your name, company name, and contact information. The license file you will receive will be named License.txt.

Once you receive the license, you are ready to upload it to the AKM server.

IMPORTANT: Do not change the name of the license file. It must have the name License.txt when it is installed on the server.

Log in to the web interface and expand the navigation pane. Click on the link for File Manager. Navigate to the /var/lib/townsend/akm directory. Select License.txt and click the Delete button.

Click the Upload button. Click Choose File, select the permanent license, and click okay.

Now you will need to restart AKM. Click on the link for Custom Commands in the navigation pane, click the Stop AKM button, then click the Start AKM button.

Chapter 10: Support

There are two levels of technical support available for AKM customers. The basic level of support comes with your permanent AKM license and includes technical documentation as well as email support, during business hours, Monday through Friday. Contact Townsend Security to purchase premium level support.

Townsend Security customers with a permanent license can collect logs and send them to Townsend Security support for assistance. From the Administrative Menu, select the Support option to _Collect logs for troubleshooting. Then start a support ticket on the Townsend Security website at https://townsendsecurity.com/support/ticket.

Appendix A: Connect with PuTTY

If you are a Windows user, you can use PuTTY to connect to the AKM server via SSH for initialization.

First, download PuTTY at https://www.chiark.greenend.org.uk/~sgtatham/putty/download.html and run the executable. When you open PuTTY for the first time, you will be prompted to enter configuration information for the AKM server:

Enter the AKM server IP address. Leave the default port 22. You can save this configuration by entering a name (example: AKM1) in the Saved Sessions field and clicking Save. Click Open.

You will be prompted to log in:

Enter “admin” as the username, and when prompted, the default password “OOHXPq6r530N6re”. If the login is successful, the Administrative Menu will be displayed. Return to Chapter 4: Set up AKM to continue with initialization.

Appendix B: Set up Bidirectional Mirroring

To set up bidirectional mirroring, first initialize the primary AKM server, then initialize a secondary mirror server as described in the section Initialize a secondary mirror server.

In the secondary server menu, select the option for Mirroring and select 1) Add a mirror. Copy the SSH public key of the secondary server.

In the primary server menu, select Mirroring and select 2) Receive mirrored keys. Paste the SSH public key of the secondary into the menu.

Return to the secondary server’s Mirror Configuration Menu and press Enter to continue.

Enter the IP address of the primary server. Verify the fingerprint of the primary server and enter yes to continue.