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.
The following documents provide additional information on the installation and use of Alliance Key Manager:
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.
The following table provides information on the changes to this documentation:
|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.|
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.
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.
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
A client certificate/private key in
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
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
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)
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.
Before continuing, you will need the following items:
AKM’s CA certificate in
A client certificate/private key in
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 Supplemental at the following location:
ALLKEYRTV_SAVF.zip for key retrieval or
ALLENCDEC_SAVF.zip for encryption.
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:
Use FTP from your PC to transfer the save file to your IBM i in binary mode:
Start, Run, FTP `Open 188.8.131.52 // 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:
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
Addlible allkeyrtv Go allkeyrtv
For RSA key retrieval and encryption, use the library and menu
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
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 following directory on the AKM Supplemental:
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
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
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)