Chapter 1: About This Manual

Who is this for?

This guide is designed to help IBM i system administrators use IBM Digital Certificate Manager (DCM) to manage certificates needed for the Alliance Key Manager client for IBM i. It covers installing DCM, creating the application ID that will be used in your client software, creating a certificate signing request (.csr file) for your client applications, and importing AKM’s CA certificate and the signed client certificate and private key.

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:

Change log

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

Version Date Description
2.1.13.001 7/20/2012 Reformat and revise for AKM version 2.1.13.
3.0.0.001 8/13/2014 Update for AKM 3.0.0.
3.0.3.001 12/17/2014 Update for AKM 3.0.3 and the ready to use version of AKM for VMware.
4.5.0.001 10/25/2016 Update AKM authentication certificates information. Misc updates.
4.6.0.001 9/12/2018 Update images for AKM 4.6
4.6.0.002 11/8/2019 Updated links and references to technical information.

Chapter 2: Install Digital Certificate Manager

Before you can create certificates you must install the no-charge licensed program IBM Digital Certificate Manager (DCM) available on your IBM i product CDs. From the LICPGM menu select option 10 to display licensed programs, then page down and look for the 5722-DC1 licensed program. If you do not have this program you must install it before proceeding.

From the LICPGM menu select the option to Install Licensed Programs. Insert your IBM product disks in the IBM i CD-ROM reader and select the option to install Digital Certificate Manager (Option 34). Follow the prompts to install the licensed program.

Apply necessary PTFs

You should acquire and apply the following Program Temporary Fix (PTFs) for the appropriate version of your operating system from IBM or your software supplier. The PTFs are available from the IBM i PTF website and can be downloaded directly to your IBM i from Fix Central. After downloading the PTFs you will need to load the PTFs with the LODPTF command, and apply the PTFs with the APYPTF command. Be sure to stop and restart the HTTP *ADMIN server after loading the PTFs. More information is available in the PTF cover letter in the QAPZCOVER file in library QGPL.

Before loading any of the following PTFs you should use the DSPPTF command to determine if it has been previously loaded. The LODPTF command will not load a PTF if it has been previously loaded or has been superseded.

IMPORTANT: The following PTFs may have been superseded and may have dependencies. Please refer to the IBM documentation to determine if there are more current versions of these PTFs.

V5R2 PTF  
SI10530 5722SS1
SI04888 5722SS1

Start Digital Certificate Manager

In order to use Digital Certificate Manager (DCM) you must start the *ADMIN instance of the IBM HTTP server. You can use the STRTCP command like this:

strtcpsvr server(*http) httpsvr(*admin)

Allow a few minutes for the server to start.

Chapter 3: Configure DCM

From your PC start a web browser session with the Admin instance of your IBM i server. The Admin instance of the IBM i web server is available on port 2001. In your browser use the IP address or domain name of your IBM i like this:

http://10.0.1.205:2001

Or,

http://AS400DomainName:2001

You will be prompted for a user ID and password. Enter the QSECOFR password or an equivalent user profile and password. The user profile you use must have *SECADM and *ALLOBJ authority.

On V7R1 of the IBM i operating system you will see the following page after you log in:

image alt text

Click on the link for Internet Configurations in the left frame.

The main page will expand with new options:

image alt text

After selecting Digital Certificate Manager the following page is displayed:

Selecting the *SYSTEM store

image alt text

Click the Select a Certificate Store button in the left frame to continue.

The following page is displayed:

image alt text

Select the option for *SYSTEM and click Continue.

The following page is displayed:

image alt text

Enter your password and click Continue.

The following page is displayed:

image alt text

Click the Expand All button to view the options. The left frame will expand to show all of the options.

Chapter 4: Create a Client Application ID

Now you will create an Application ID. The Application ID will be used to link your client application to the correct certificates in DCM.

Under Manage Applications in the left frame, click Add Application. Select the option for Client - Add a client application and click Continue:

image alt text

The following page is displayed:

image alt text

Create an Application ID. Be sure to create an Application ID name with the following characteristics:

  • All upper case

  • No embedded blanks

  • No special characters

  • No more than ten characters long

ALCLISEC and AKMCLIENT are examples of names you can use as your application ID.

IMPORTANT: This application ID name will be used in your Key Manager configuration on the IBM i. Its importand you remember this name

Enter a description of this client application ID in the application description field. this is how you will identify your application within DCM.

image alt text

For the other options, leave the default selections. Scroll down and click the Add button.

If you receive an error message, review your information, correct the problem, and try again.

If the action is successful, the following page is displayed:

image alt text

You have now added a client application for use with Alliance key retrieval for IBM i.

Click OK to continue.

Chapter 5: Create a Certificate Signing Request

You can now create a certificate signing request (.csr file) to be signed by AKM’s certificate authority (CA) certificate. Click the Create Certificate link from the list on the left frame. The following page is displayed:

image alt text

Select the option for Server or client certificate. Then click Continue.

The following page is displayed:

image alt text

Select the option VeriSign or other Internet Certificate Authority (CA) to create a certificate signing request that will be signed by a non-IBM i certificate authority.

Click Continue.

The following page is displayed:

image alt text

Complete this page with the certificate information. The key size must be 2048 bits.

IMPORTANT: The default key size for the local certificate authority in DCM may be 1024. You MUST change this to 2048 in order to create certificate signing requests for AKM.

Provide a label, common name (user name), organizational unit (department), organization name (company name), locality, state, and country. ALL fields are REQUIRED by the Alliance Key Manager.

IMPORTANT: Check with your Crypto Officer to determine if they are enforcing access controls and restricting key retrieval to known users or groups. If so, set the common name and organization unit fields to match the User and Group fields on AKM, respectively.

image alt text

Click Continue.

The following page is displayed:

image alt text

This page displays the certificate signing request in the section that begins “—–BEGIN NEW CERTIFICATE REQUEST —“. Use your cursor to select all of the text starting with this line, and ending with the line “—–END NEW CERTIFICATE REQUEST—–“. Copy this to your clipboard and paste it into a Notepad document. Save this document with the extension “.csr”, and provide it to the person in your organization responsible for managing AKM certificates.

Click OK. You are finished with this step. The csr must be uploaded to your PRIMARY AKMs filesystem under /home/admin/uploads. This can be done via webmin, under File Manager, or you can use Filezilla, or SCP. Once the file is in place access the AKM shell via Putty or SSH and bring up the Administrative Menu (akm-menu)

image alt text

Option 3 “Manage Certificates” contains the option to “Import and Sign Certificate Signing Requests”. you will see a mesage about the placement of the file, simply hit enter to sign the uploaded .csr file. If this process was successful you will see a second message.

image alt text

You will be able to download the .zip thatwas created from /home/admin/downloads. This will contain two certificates, the new client certificate and your AKMs root CA.

Chapter 6: Import the CA Certificate

Use FTP in binary mode to transfer the AKM root CA and signed client certificate to an IFS directory on your IBM i or upload them via System i Navigator. Both the AKM root CA certificate and signed client certificate should now be in a directory on the IFS.

IMPORTANT: At this stage, check to be sure you are still working within the *SYSTEM certificate store in DCM

Before you import the signed client certificate, you must first import the certificate authority (CA) belonging to AKM. It is critical that the CA certificate be imported prior to importing the signed client certificate.

Use the following steps to import the CA certificate to DCM.

Click on the Import Certificate link under “Manage Certificates” from the list in the left frame. The following page will be displayed:

image alt text

Select the option for a Certificate Authority (CA) certificate. Click Continue.

The following page is displayed:

image alt text

Enter the full path and name of the certificate authority certificate. This field is case sensitive. Click Continue.

The following page is displayed:

image alt text

Enter a label for the AKM CA certificate. Click Continue. You should receive a successful completion message and can continue with the following steps.

Chapter 7: Import the Signed Client Certificate

By this point Your Crypto Officer will have signed the certificate signing request that you created in Chapter 5 and return the .zip file containing the two needed certificates. Those two certificates should still be on the IFS.

Click on the Import Certificate under “Manage Certificates” from the list in the left frame. The following page will be displayed:

image alt text

Select the option for Server or client and click Continue.

The following page is displayed:

image alt text

Enter the full path and name of the signed certificate. This field is case sensitive. Click Continue.

If you encounter any errors on the import of the certificate, you should discuss these with your Crypto Officer.

The following page is displayed:

image alt text

Select the option to Assign certificate to assign this newly imported client certificate to the application you created in Chapter 4. Click Continue.

The following page is displayed:

image alt text

Select Client and click Continue.

The following page is displayed:

image alt text

Select your AKM client certificate, and click the Assign To Applications button.

The following page is displayed. Scroll down and select the application you created in Chapter 4. You will find it in the list based on the application description you assigned to it.

image alt text

Select the application and click Continue.

The following page is displayed:

image alt text

Click OK to continue. You are now finished with Digital Certificate Manager and can now use the application ID in your IBM i client application definitions to authenticate to the AKM server to retrieve data encryption keys.

Chapter 8: User Authority to DCM

Grant user authority to DCM

Any user who will retrieve encryption keys with the Alliance Key Manager client must have authority to access the DCM files. Use the WRKLNK command and grant *RW authority to all certificate files. You should not grant authority to *PUBLIC for these files. The DCM files are located in /QIBM/USERDATA/ICSS.

Many of the Alliance applications for the AS/400 have a menu option to make it easier to grant access to DCM. Navigate to the main menu and take the option for Installation. You will find a menu option like this:

20. Grant user authority for DCM

When you select this option you can enter a user profile name:

image alt text

The application will then grant authority to use DCM for this user profile.

View user authority to DCM

To view a list of users who are authorized to DCM, take the following steps:

  • From a command line run WRKLNK.

  • Enter /QIBM/USERDATA/ICSS/CERT/SERVER/ into the object field. Press Enter.

  • Enter option 5 next to Server. Press Enter.

  • Enter option 9 next to Default.KDB. Press Enter.

  • This will list all the users authorized to DCM.

You can also remove access to DCM for a user profile here.