Chapter 1: About This Manual

AKM Key Connection for Drupal

The AKM Key Connection for Drupal module is a plugin for the Encrypt project that allows you to use encryption key management to protect sensitive data in Drupal. You can set up key retrieval or remote encryption on the AKM server via the easy-to-use interface.

Who is this for?

This guide is designed to help Drupal developers install and use the AKM Key Connection for Drupal module for encryption key management within Drupal. For information on server management, see the AKM Server Management Guide. For more information on key management, see the AKM Administrative Console Guide.

Other resources

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

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.

Change log

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

Version Date Description
3.0.0.001 4/2/2014 Initial release.
3.0.0.002 4/23/2014 Minor updates.
3.0.0.003 5/30/2014 Update “Before You Begin” chapter. Add chapters on creating and managing encryption keys, creating additional client and admin certificates, and managing the AKM server.
3.0.3.001 12/30/2014 Update for AKM 3.0.3 and the ready to use version of AKM for VMware.
4.0.0.001 5/24/2016 Update Preparation chapter for AKM 4.0 release.

Chapter 2: Preparation

You will need to complete the following steps before continuing:

  • Install and set up 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 setup, or, through the AKM Administrative Console application)

  • Download certificates from the AKM server

  • Know the IP address(es) of the AKM server(s) and port numbers for the desired services (key retrieval or remote encryption)

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

Certificates and private keys are the mechanism by which the client and the AKM server establish a secure TLS connection and perform authentication. You will need the following certificates to authenticate your Drupal clients with the AKM server:

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

  • Client certificate in .pem format (AKMClientCertificate.pem)

  • Client private key in .pem format (AKMClientPrivateKey.pem)

These certificates and private keys are generated during AKM server initialization and stored on the server. See your platform specific deployment guide for instructions on downloading certificates.

You will need to concatenate the client certificate and private key .pem files (see below).

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.

Concatenate certificate files

You will need to concatenate the client certificate and client private key files into a single .pem file to use them with Key Connection for Drupal. To concatenate two files in a shell on Linux use the following example:

cat AKMClientCertificate.pem AKMClientPrivateKey.pem > AKMClientCertAndKey.pem

Server information

You will need the following server information before continuing:

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

  • The port number that AKM has been configured to use for key retrieval (the default is 6000) or encryption (the default is 6003)

Encryption keys

Key Connection for Drupal supports the use of 256-bit encryption keys.

To set up client key retrieval or remote encryption, you must have the name(s) of the encryption key(s) on AKM you would like to use.

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

Before continuing, you will need the following items:

  • AKM’s CA certificate in .pem format

  • A client certificate/private key in .pem format

  • The IP address or DNS name of the AKM server and the port number it will use for key retrieval or remote encryption (for both the primary and secondary AKM servers if using a failover server)

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

Chapter 3: Set up AKM Key Connection for Drupal

Download modules

Download the Key Connection for Drupal module from www.drupal.org/project/townsec_key.

Download the Encrypt module from www.drupal.org/project/encrypt. This module provides the framework to enable encryption in Drupal.

Download the Field_Encrypt module from www.drupal.org/project/field_encrypt. This module allows you to tag certain fields within Drupal for encryption.

Extract modules

Extract the modules into your sites/all/modules directory (or other site subdirectory if running a multi-site).

Enable modules

Enable the modules via the Module page at Administer > Modules (example.com/admin/modules). Click the Enabled check box next to each module and then click the Save Configuration button.

Upload certificates to Drupal

Upload the client certificate/private key and CA certificate .pem files to the Drupal server.

SECURITY ALERT: Keep your certificate and private key files outside of the Drupal root directory and accessible only to the server via your Linux permissions. This is necessary to prevent unauthorized access to the AKM server.

Configure AKM

Navigate to the Encrypt module administration page (example.com/admin/config/system/encrypt). You will first select the encrypt method and key provider:

image alt text

To use key retrieval with AKM, select the desired encrypt method. To configure AKM for remote encryption, select Townsend Security AES under “Default Encrypt Method”.

Under “Key Provider”, select Townsend Security AKM.

Configure the AKM server

You will now need to provide settings for the AKM server:

image alt text

Location of Client X509 Certificate and Private Key File: Enter the directory location (relative to the Drupal root) of your client certificate/private key file.

Location of Certificate Authority Certificate File: Enter the directory location (relative to the Drupal root) of your CA certificate.

AKM Host Server: Enter the IP address or DNS name of your AKM server.

Key Retrieval Port: Enter the port for key retrieval (the default is 6000).

Remote Encryption Port: Enter the port for remote encryption (the default is 6003).

Configure the secondary AKM server

If you are using a secondary AKM server, click Backup Server Settings to expand the “Backup Server Settings” pane and complete the following fields:

AKM Backup Server: Enter the IP address or DNS name of your secondary AKM server.

Key Retrieval Port: Enter the secondary AKM server’s port for key retrieval (the default is 6000).

Remote Encryption Port: Enter the secondary AKM server’s port for remote encryption (the default is 6003).

Enter encryption key information

image alt text

Key Name: Enter the name of the encryption key you would like to use for key retrieval or remote encryption.

Key Type: Select the key type (AES-256).

Key Size: Enter the size of the key (256).

NOTE: AES-256 is the only type of key currently supported by AKM Key Connection for Drupal.

Encoding Method: Select the encoding method (Base16 Encoded).

NOTE: It is highly recommended to use Base16 Encoded as the encoding method. Other encoding methods will need additional customizations.

NOTE: At this time remote encryption only supports up to 16Kb of data to encrypt in a single stream. For encryption of larger files, please contact Townsend Security to help with customization.

Encrypt fields in Drupal

Navigate to the page for the field you want to encrypt (Example: Body). Scroll down to the Field Settings. Check the box for Encrypt this field. Click Save settings. This tells the Encrypt module to encrypt this field’s content.

Go to the “Generate Content” page. Enter the number of nodes you would like to generate with encrypted content. Click Generate.

Navigate to the home page. You can see in a snapshot of the database that all of the data is stored securely and fully encrypted.

Next steps

You are now finished setting up Key Connection for Drupal. See the AKM User Guide for more information on using AKM, including server management and encryption key administration.

Chapter 4: Support

There are two levels of technical support available for AKM customers. The basic level of support comes with your 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.

For technical support, start a support ticket on the Townsend Security website at: