Chapter 1: About This Manual

Who is this for?

This guide is designed to help IBM i application developers and project managers implement key retrieval or remote encryption in their business applications. It covers installing the AKM key retrieval client for the IBM i (AS/400, iSeries) platform, defining a key manager, using sample code to implement key retrieval or encryption, and developer guidelines.

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:

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
1.00 11/22/2008 Initial release.
2.1.13.001 2/21/2014 New manual format.
3.0.3.001 1/5/2015 Update for AKM 3.0.3 and the ready to use version of AKM for VMware.
3.0.3.002 6/18/2015 Name change from “AKM Quick Start Guide for IBM i” to “AKM Guide for IBM i Developers”.
4.0.0.001 5/24/2016 Update preparation chapter for AKM 4.0.
4.5.0.001 10/20/2016 Update asymmetric RSA key support.
4.6.1.001 11/8/2019 Updated links and references to technical information.

Chapter 2: Preparation

You will need to complete the following steps before continuing with client setup and configuration:

  • 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)

  • Start Digital Certificate Manager (see the document “AKM DCM Configuration for IBM i”)

  • Create and sign a certificate signing request (CSR) in Digital Certificate Manager

  • 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, 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. The following certificates should be installed on the client in order to authenticate your client application with the AKM server:

  • AKM’s certificate authority (CA) certificate in .pemformat

  • A client certificate/private key in .pem format

AKM’s certificate authority (CA) certificate is generated on initialization and stored on the AKM server. See your platform specific deployment guide for instructions on downloading certificates, and download AKM’s CA certificate in .pem format.

Then, follow the steps in the document AKM DCM Configuration for IBM i to create a certificate signing request (CSR), and then use AKM’s Administrative Menu to sign the certificate signing request. See your platform specific deployment guide for information on signing the CSR.

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.

Digital Certificate Manager

On the IBM i platform the IBM Digital Certificate Manager (DCM) is used to import the CA certificate for use in the client application as well as to create and manage client certificates. See the document AKM DCM Configuration for IBM i for information on installing DCM, creating the application ID that will be used in your client software, creating a Certificate Signing Request for the client certificate, and importing the signed client certificate and CA certificate for use in your client application

Server information

The following server information is required for client setup and 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) or encryption (the default is 6003)

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 any secondary AKM servers) and the port number it will use for key retrieval (the default is 6000) or remote encryption (the default is 6003)

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

Chapter 3: Install the Software

Client software for key retrieval and AKM encryption services is available on the AKM Evaluation page under the “Development Kits” section.

[AKM IBM i Dev Kit](http://townsendsecurity.com/downloads/products/sdk/IBM_System_i.zip)```

Select `ALLKEYRTV_SAVF.zip` for key retrieval or `ALLENCDEC_SAVF.zip` for encryption. 


Select `ALLRSARTV.zip` for asymmetric RSA key retrieval or `ALLRSAENC.zip` for asymmetric RSA encryption.

> **_NOTE:_**  If you have licensed the Alliance AES/400 product from Townsend Security, you already have the AKM key retrieval software in the ALLAES100 library and you do not need to load this client software. To validate the connection to AKM, navigate to the Main Menu and enter option 2 to configure the product. From the Configuration menu enter option 40 to Validate AKM key retrieval.


## Install from the Save file

Use the following steps to install from the Save file (this example uses the key retrieval save file):

Create a save file on the IBM i:

Crtsavf qgpl/allkeyrtv


Use FTP from your PC to transfer the save file to your IBM i in binary mode:


Start, Run, FTP Open 1.1.1.1 // use your IBM i IP address User username // use your IBM i profile Pass password // use your IBM i password Binary Put c:\allkeyrtv.savf qgpl/allkeyrtv Quit


You can now install the library `ALLKEYRTV` using the following command:


Rstlib savlib(allkeyrtv) dev(*savf) savf(qgpl/allkeyrtv)


Observe that all objects are restored properly.

You can now delete the save file using the following command:


Dltf file(qgpl/allkeyrtv)



# Chapter 4: Define a Key Manager

On the IBM i platform you must now define the location of the Alliance Key Manager. For symmetric key retrieval and encryption, you can do this through the configuration option on the `ALLKEYRTV` menu:


Addlible allkeyrtv Go allkeyrtv



For RSA key retrieval and encryption, use the library and menu `ALLRSARTV`.

Select option 1 to **_Work With Key Managers_**.

You will notice a default key management definition named `ALLAKM`. Enter a 2 next to this option to change it. On the second panel you can provide the IP address and port number of the AKM server. Your system administrator can give you this information. Press **_Enter_** through all of the panels to update the definition. 


> **_IMPORTANT:_**  The name of the key manager definition must be `ALLAKM`.


# Chapter 5: Sample Code

Sample ILE RPG code is provided to help you get started with key retrieval or encryption, and can be used to validate the application. Use the option on the menu to view sample code to start PDM. You can view the application source code in the normal way.

Sample ILE COBOL source code is also provided for key retrieval if you prefer to develop in the COBOL language. Select the option to view the COBOL sample code. To create the application please see the create statements in the sample code. You must bind the service program `ALLKEYRTV` to any application that retrieves encryption keys from the AKM server. You may freely use the sample code to create your own applications that retrieve keys. However, you should place your application source and objects in a different library.

Sample code is located in the [AKM IBM i Dev Kit]([AKM IBM i Dev Kit](http://townsendsecurity.com/downloads/products/sdk/IBM_System_i.zip)

The following files are available:

* `sampkeyrtv.rpgle` - ILE RPG code for symmetric key retrieval

* `encakm01.rpgle` - ILE RPG code for symmetric key encryption

* `decakm01.rpgle` - ILE RPG code for symmetric key decryption

* `sampcblle2.cblle` - ILE COBOL code for symmetric key retrieval


* `samprsartv.rpgle` - ILE RPG code for asymmetric key retrieval


* `sampkeyenc.rpgle` - ILE RPG code for asymmetric key encryption




# Chapter 6: Developer Guidelines

Good development practice when using encryption keys is to minimize the chance of accidental disclosure of key material. Consider the following 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 `CLEAR` or other appropriate command.

## Build applications with visibility removed

After you create your application you can remove program visibility with the following command:


CHGPGM PGM(MYLIB/MYPGM) RMVOBS(*ALL)


Note that removing visibility will limit your ability to debug the application. 

## Use common modules

Rather than calling the Alliance Key Retrieval or Encryption API in every RPG or COBOL program, consider creating a common module 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 IBM i object security and object auditing on a single module.

## Use native IBM i security

Consider implementing native IBM i object security on the `ALLKEYRTV` or `ALLRSARTV` service program. You can attach an authorization list to the service program, and add authorized users to the list. Remove `*PUBLIC` authority to the service program, and do not add `*PUBLIC` to the authorization list.

## Implement object auditing

If you have implemented security audit journaling (`QAUDJRN`) on your IBM i, consider implementing object auditing for the `ALLKEYRTV` or `ALLRSARTV` service program. This will generate a security audit journal entry for each user access to the key retrieval API. You can turn on object auditing using the following commands:


CHGOBJAUD OBJ(ALLKEYRTV/ALLKEYRTV OBJTYPE(SRVPGM) OBJAUD(ALL) ```