Chapter 1: About This Manual

AKM key retrieval library

The AKM key retrieval library for Linux is a shared library for key retrieval in C. This library provides an interface to assist in client key retrieval implementations. Key retrieval is performed via a secure TLS connection to the AKM server and both the client and server end-points are authenticated via the TLS protocol. The library is packaged for several Linux distributions (see the chapter on installation for more information). The sample code in C can be invoked on several platforms. The library or sample code can also be invoked in C++ if needed.

Who is this for?

This guide is designed to help Linux C application developers and project managers implement key retrieval in their business applications using the AKM key retrieval library for Linux platforms.

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
• AKM Key Service API Reference
• AKM Encryption Service API Reference

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:

Chapter 2: Preparation

• 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 key retrieval

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, except for the Amazon Web Services fee-based deployment, which generates a permanent license.

A temporary license will enable a fully functional AKM server that may be run in your environment for evaluation or testing. 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

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

• Certificate Authority (CA) certificate in .pem format

• Client certificate/private key: This must be installed as a PKCS #12 file (.p12)

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

SECURITY ALERT: Certificate and private key files, regardless of origin, are crucial to securing the AKM key management system, and must be protected during creation, distribution, and storage.

These are sensitive files, and access to them should be controlled with the rights and permissions management capabilities of all platforms in use. All certificate and key files should be transferred with secure methods and tools. Files stored locally should be monitored for access and change using a tool such as the Linux facility auditd.

If any certificates or private keys are compromised or lost, they should immediately be replaced, including 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 that AKM has been configured to use for key retrieval (the default is 6000)

Encryption keys

To set up client key retrieval, 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 .p12 format

• 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 3: Install the AKM Key Retrieval Library

Install the key retrieval library

Download the AKM Linux Dev Kit. You will find install files for the following supported Linux platforms:

• RHEL/CentOS 4, 5, 6, 7
• SLE 11 SP2, SP3, SP4
• Ubuntu 12.04, 14.04, 16.04

Copy the appropriate install package to your system. Installation requires root privileges, either through sudo or su:

# rpm –ivh liballkeyrtv-version.arch.rpm 

# dpkg -i liballkeyrtv_version-arch.deb

If you need additional support, please contact Townsend Security for assistance.

Verify the installation (optional)

You can verify the application using GNU Privacy Guard (GPG) or PGP. You must import the Townsend Security public key to verify the signature. The Townsend Security public key is available at https://www.townsendsecurity.com/pgp_keys/product-security.asc.

Using GnuPG

 > gpg --import product-security.asc
 > gpg --edit-key product-security@townsendsecurity.com
	Command> trust
	Command> sign
	Command> save
	Command> quit
 > gpg --verify liballkeyrtv-version.arch.rpm.sig

Using PGP

 > pgp --import product-security
 > pgp --sign-key product-security@townsendsecurity.com --signer userid --sig-type exportable --passphrase passphrase  > pgp --verify liballkeyrtv-version.arch.rpm.sig

Uninstall the key retrieval library

Uninstalling requires root privileges, either through sudo or su:

# rpm -e liballkeyrtv 

Or:

# dpkg -r liballkeyrtv

Chapter 4: Configuration

A configuration file provides information to the AKM key retrieval library. When you call the key retrieval API you pass it the fully qualified path to the configuration file. This section provides information about the format of the configuration file. See keyclient.conf in the AKM Linux Dev Kit for a sample configuration file.

Configuration file format rules

The configuration file is an ASCII file describing parameters set in assignment lines and separated by sections.

Sections

The key retrieval configuration file is comprised of three sections that contain specific name and value assignment lines. Each section name appears on a line by itself, in square brackets ([]). All parameters after the section declaration are associated with that section. There is no explicit “end of section” delimiter; sections end at the next section declaration or the end of the file. Sections may not be nested. The sections of the key retrieval configuration file are [IP], [Cert] and [Log]. The [Log] section is optional.

Assignment line

The assignment line of the configuration file contains parameters. Every parameter has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign and the value appears to the right. There can be no whitespaces or comment characters leading or following an equal sign.

Example:

name=value

Comments

Semicolons (;) indicate the start of a comment. Comments continue to the end of the line. Everything between the semicolon and the End of Line is ignored, including any whitespace leading in front of the semi colon.

Example:

; this is a comment line

Colon character

The colon character is used to establish two values in one assignment line. The colon character cannot have anything leading or following it other than a printable character, no whitespace is allowed.

Example:

name=valueA:valueB

Whitespace & blank lines

Whitespace is ignored by the parser and is allowed between value assignments and comment markers (semicolon). Any characters following the comment marker are ignored; therefore any whitespace following the comment marker will also be ignored.

Whitespace characters are not allowed in section and assignment names. Whitespace characters cannot lead or follow an equal sign.

Any whitespace characters following a value parameter in an assignment line are treated as comment characters and are ignored, as well as any characters following the whitespace character.

Blank lines are ignored.

Quoted values

A value that contains whitespace characters must be wrapped in double quotes ("). A beginning quote must immediately follow an equal sign and an end quote finishes wrapping the value parameter of the assignment line.

Example:

name="a value with a spaces"

A single quote in a value parameter, or a quote not immediately following an equal sign, is illegal and treated as an error condition by the configuration file parser.

Sample configuration

The following example shows a primary AKM server and one failover server and the use of one CA certificate and one client certificate, with the timeout value set to 10 seconds:

; Configuration file for Universal Key Retrieval Api

[log]
Syslog=2 ; syslog output enabled
StdErr=2 ; stderr output enabled

[ip]
KeyStoreIpPort=localhost:6000

ConnectTimeoutSecs=5     ; timeout value in seconds
ConnectTimeoutMSecs=0    ; timeout value in milliseconds

[cert]
VerifyDepth=1    ; certificate verify depth

TrustedCACertDir=./CA  ; CA Signed Cert directory
TrustedCACert=./CA/AKMRootCACertificate.pem  ; CA Signed Cert (root cert)

ClientPrivKey=./CA/AKMClientPrivateKey.pem ; Client Private key 
ClientSignedCert=./CA/AKMClientCertificate.pem ; Client Signed certificate

See the following sections for more information on the configuration file.

IP section

The IP section contains at least three name and value assignment lines. They are KeyStoreIpPort(one or more), ConnectTimeoutSecs, and ConnectTimeOutMsecs.

Key server IP and port

The KeyStoreIpPort names contain information about your AKM servers. Each name requires an IP address (or hostname) and a port value, separated by a colon. The key retrieval library parses and stores KeyStoreIpPort values in the order that they appear in the configuration file. There is no limit to the number of KeyStoreIpPort name and values that you can specify.

Connect timeout seconds

The ConnectTimeoutSecs name requires a value specified in whole seconds. This is the seconds timeout value for establishing a TCP connection to the key server before an TLS transaction occurs.

This is a value which may be specified as zero if necessary.

Connect timeout milliseconds

The ConnectTimeOutMsecs name requires a value specified in milliseconds. This is the millisecond timeout value which adds granularity to the timeout feature. This is a value which may be specified as zero if necessary.

Cert section

The Cert section has four name and value assignment lines. They are: VerifyDepth, ClientSignedCert, TrustedCACert, and TrustedCACertDir.

Certificate verification depth

VerifyDepth must be added to the Cert Section, and set with a number of 1 or greater depending on the level of certificate verification.

Client signed certificate

The ClientSignedCert name requires the client signed certificate full path value. Full path value should include both the complete path and the name of the certificate file.

Trusted CA certificate

The TrustedCACert name requires the trusted certificate authority certificate file full path value. Full path value should include both the complete path and the name of the certificate file. In the case of specifying multiple TrustedCACert assignment lines, there is no amount limit.

Trusted CA certificate directory

The TrustedCACertDir name requires the trusted CA certificate file path value.

Client private key

The ClientPrivateKey name requires the client private key full path value. Full path value should include both the complete path and the name of the private key file.

Log section

The optional Log section has two name and value assignment lines. They are, Syslog and StdErr.

Syslog option

The Syslog name requires a specified value of 1 for OFF, or 2 for ON. Default behavior for Syslog is OFF. To enable logging, the optional Log section needs to be added to the configuration file.

Syslog settings report at facility level LOG_LOCAL0, message option LOG_ODELAY and priority LOG_ERR. These settings are static and are not changed throughout the API.

Standard error output option

The StdErr name requires a specified value of 1 for OFF, or 2 for ON. Default behavior for Standard Error Stream (stderr) is OFF.

Chapter 5: Key Retrieval API

The following interface is provided for the AKM key retrieval library. Please see the individual language examples for more information on how to call this API from a specific programming language.

Function prototype

The function prototypes are in the include file client.h. The function prototype for the AKM key retrieval library API is:

void ALLKeyRtv(unsigned char* pcaKeyName,        /* Specify key name */
               unsigned char* pcaKeyInstance,    /* Request key Instance */
               unsigned long* pulFormat,         /* Specify format for returned key value */
               unsigned char* pcaIniPath,        /* Path to configuration settings file */
               unsigned long* pulKeySize,        /* Key size in bits (128, 192, 256) */
               unsigned char* pcaKey,            /* Key value in specified format */
               unsigned char* pcaInstanceUsed,   /* Instance of key returned */
               unsigned char* pcaExpiration,     /* Expiration date */
               unsigned char* pcaLastRolledDate, /* Date of last rollover */
               unsigned long* pulReturn);        /* Return code if error */

Parameter definitions

Key name (Character, 40)

The name of the encryption key you want to retrieve. This must be a character value that is left justified and blank padded, with no null termination character. The key name is case sensitive and must match the value in the AKM server. (Note that on the IBM i and System z platforms, this value is converted to the ASCII character set before transmission to the AKM server. You should provide this as an EBCDIC value).

Key instance (Character, 24)

The name of the key instance you want to retrieve. An encryption key may have many instances of the key each of which have a different encryption key value. This must be a character value that is left justified and blank padded, with no null termination character. If this field contains blanks, the current instance of the key will be retrieved. (Note that on the IBM i and System z platforms, this value is converted to the ASCII character set before transmission to the AKM server. You should provide this as an EBCDIC value).

Key Size (Unsigned long)

The size of the key you want to retrieve from AKM. This must be an unsigned long numeric value in Network Byte Order. The value must be 128, 192, or 256 to indicate a 128-bit key, 192-bit key, or 256-bit key. An error will be returned if the key exists on the AKM server, but is a different key size.

Format (Unsigned long)

This field indicates the format you want for the returned encryption key. This must be an unsigned long numeric value in Network Byte Order. The value must be 1 for raw binary format, 2 for Base64 encoded format, or 3 for Base16 hex format.

Key

This is the value of the encryption key returned to your program. It will be left justified and blank padded in the format you requested. If an error occurs this field will not contain the encryption key and should not be used.

Key instanced used (Character, 24)

This field contains the name of the key instance used for key retrieval. If you specified a blank value for the key instance this field contains the name of the current instance of the key. If you specified an actual key instance name, that name is echoed in this field.

Expiration date (Character, 8)

This field is returned to your program and contains the expiration date of the encryption key in CCYYMMDD format (Year, Month, Day).

Last change date (Character, 8)

This field is returned to your program and contains the last change date of the key in CCYYMMDD format.

Return code (Unsigned long)

This field contains the success or failure code of the operation in numeric Network Byte Order. If the operation was successful this field contains the value 0 (zero). If an error occurred for the request, this field contains a positive numeric value. See the AKM Error Codes Reference for a listing of the error codes.

Sample C program code

The sample program client.c is available in the AKM Linux Dev Kit to demonstrate key retrieval. See Chapter 7: Sample Code for more information.

Chapter 6: Get Next Key API Specification

The following interface is provided for the Get Next Key API (ALLGetNextKey). The Get Next Key API retrieves the next available encryption key that was created by the Automatically Generate Key API. Please see the individual language examples for more information on how to call this API from a specific programming language.

IMPORTANT: The Get Next Key API is used in conjunction with the Automatically Generate Keys API. This API is used to create large numbers of keys in advance of their use. Unless you have special requirements for pre-generating large numbers of keys, you should not use this API in your application programs.

Function prototype for ALLGetNextKey

The function prototype for the Get Next Key API is:

void ALLGetNextKey(unsigned char* pcaIniPath,
  unsigned char* pcaConstant,
  unsigned char* pcaIncrementLen,
  unsigned char* pcaIncrementCode,
  unsigned char* pcaConstantLen,
  unsigned char* pcaKeyFormat,
  unsigned char* pcaKeyName,
  unsigned char* pcaInstance,
  unsigned char* pcaLastRolloverDate,
  unsigned char* pcaExpirationDate,
  unsigned char* pcaKeySizeBits,
  unsigned char* pcaKeyValue,
  unsigned char* pcaLastIncrement,
  unsigned long* pulReturn)

Parameter definitions for ALLGetNextKey

Configuration file path (Character, null terminated string) The path to the configuration file. This is a null terminated value.

Constant (Character, 40) Pointer to a buffer containing the constant value. 39-bytes, ASCII, left-justified.

Increment length (Character, 2) Pointer to a buffer containing the increment length. 2-bytes, ASCII, right-justified, with leading zeros. The size of the incrementing field in bytes

Increment code (Character, 1) Pointer to a buffer containing the increment code. The type of incrementing to be performed. 1-byte, ASCII. The values must be one of the following:

• A - Alpha Numeric . 0-9, A-Z, a-z. Initial value is 0s. Incrementing from numbers to upper case letters then lower case letters. (The same as the appearance of the character in the ASCII table).
• H - Hex digits. 0-9, A-F (upper case only). Initial value is all 0s.
• N – Numeric. 0-9. Initial value is all 0s

Constant length (Character, 2) Pointer to a buffer containing the constant length. 2-bytes, ASCII, right-justified, with leading zeros. The number of significant digits in the Constant field. The value must be in the range 00 – 39.

Key format (Character, 3) Pointer to a buffer containing the code for how the key value should be formatted. 3-byte, ASCII. The value must be one of the following:

• BIN – binary.
• B16 - Base16 encoded (hex). Based on the definition in RFC 4648.
• B64 - Base64 encoded

Key name (Character, 40) The name of the encryption key you want to retrieve. This must be a character value that is left justified and blank padded, with no null termination character. The key name is case sensitive and must match the value in the AKM server. (Note that on the IBM i and System z platforms, this value is converted to the ASCII character set before transmission to the AKM server. You should provide this as an EBCDIC value).

Key instance (Character, 24) The name of the key instance you want to retrieve. An encryption key may have many instances of the key each of which have a different encryption key value. This must be a character value that is left justified and blank padded, with no null termination character. If this field contains blanks, the current instance of the key will be retrieved. (Note that on the IBM i and System z platforms, this value is converted to the ASCII character set before transmission to the AKM server. You should provide this as an EBCDIC value).

Last rollover date (Character, 8) This field is returned to your program and contains the last change date of the key in CCYYMMDD format.

Expiration date (Character, 8) This field is returned to your program and contains the expiration date of the encryption key in CCYYMMDD format (Century, Year, Month, Day).

Key Size (Unsigned long) The size of the key you want to retrieve from AKM. This must be an unsigned long numeric value in Network Byte Order. The value must be 128, 192, or 256 to indicate a 128-bit key, 192-bit key, or 256-bit key. An error will be returned if the key exists on the AKM server, but is a different key size.

Key (Binary character, 256) This is the value of the encryption key returned to your program. It will be left justified and blank padded in the format you requested. If an error occurs this field will not contain the encryption key and should not be used.

Last increment (Character, 40) The instance name of the last increment.

Return code (Unsigned long) This field contains the success or failure code of the operation in numeric Network Byte Order. If the operation was successful this field contains the value 0 (zero). If an error occurred for the request, this field contains a positive numeric value. See the AKM Error Codes Reference for a listing of the error codes.

Chapter 7: Sample Code

Source code for a sample application in C (client.c) is provided to help you get started with key retrieval, and can be used to validate the application (see Chapter 8). To create the application, please see the Readme file and comments in the sample code.

You may freely use the sample code to create your own applications that retrieve keys. However, you should place your application source and executables in your own directory.

Chapter 8: Validating the Application

The sample application can be used to validate the proper operation of key retrieval. Before you start you will need to obtain the name of an encryption key on the AKM server. Ask your Crypto Officer for the name of a key. If you are deploying AKM for VMware, Microsoft Azure, or AWS, you had the option to create the following encryption keys during the initialization process. If you created encryption keys, the following keys are available for use:

• AES128 - 128-bit symmetric key, general access
• AES192 - 192-bit symmetric key, general access
• AES256 - 256-bit symmetric key, general access

Modify the sample application source code to specify the sample encryption key, re-compile the program, and run it. If it is successful you will see a display on your session console with a message to this effect. If unsuccessful, you will see an error code. You can use the AKM Error Codes Reference to determine the cause of the error.

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

Chapter 9: Developer Guidelines

Good development practice when using encryption keys is to minimize the chance of accidental disclosure of key material. Consider these programming techniques to minimize the loss of keys:

Clear encryption key variables after use

After performing encryption or decryption tasks, clear the encryption key from memory using the memset, bzero, or other appropriate command.

Use common modules

Rather than calling the Alliance Key Retrieval API in every application program, consider creating a common module or class that performs key retrieval, and call this program from your applications. This provides a layer of separation between your applications and the key retrieval API, and allows you to implement native security and auditing on a single module.

Use native file security

Consider implementing native file security on the shared library. Remove public access to the object and assign individual or group authority to the shared library.

Chapter 10: Error Handling

Reply codes and error handling

The AKM key retrieval library API provides a reply code that indicates the success or failure of the key retrieval operation. Your application should always inspect the value of this reply code and take appropriate action in the event of an error. The value of 0 (zero) indicates the success of the operation. Any other non-zero value indicates a failure. The failure may be on the local system (for example, you passed an invalid value to the API), or may be an error that occurred on the key server. Your application must handle the error condition and take appropriate action.