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:
- AKM User Guide
- AKM Server Management Guide
- AKM Administrative Console Guide
- AKM Guide for IBM i Developers
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:
https://10.0.1.205:2001
Or,
https://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:
Click on the link for Internet Configurations in the left frame.
The main page will expand with new options:
After selecting Digital Certificate Manager the following page is displayed:
Selecting the *SYSTEM store
Click the Select a Certificate Store button in the left frame to continue.
The following page is displayed:
Select the option for *SYSTEM and click Continue.
The following page is displayed:
Enter your password and click Continue.
The following page is displayed:
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:
The following page is displayed:
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.
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:
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:
Select the option for Server or client certificate. Then click Continue.
The following page is displayed:
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:
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.
Click Continue.
The following page is displayed:
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
)
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.
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:
Select the option for a Certificate Authority (CA) certificate. Click Continue.
The following page is displayed:
Enter the full path and name of the certificate authority certificate. This field is case sensitive. Click Continue.
The following page is displayed:
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:
Select the option for Server or client and click Continue.
The following page is displayed:
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:
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:
Select Client and click Continue.
The following page is displayed:
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.
Select the application and click Continue.
The following page is displayed:
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:
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.