How to Generate a CSR on IBM HTTP Server

This guide shows you how to generate a CSR (Certificate Signing Request) on IBM HTTP Server (IHS), and how to do the same job on HCL Domino (formerly IBM Domino).

IBM HTTP Server stores keys and certificates in a CMS key database (a .kdb file plus a .sth stash), which you manage with the IKEYMAN graphical tool or the gskcapicmd command line utility from the IBM Global Security Kit (GSKit) that ships with IHS.

The steps below cover both paths on IHS 9.0.5.x (the current supported release), then the two CSR flows for HCL Domino: the classic Server Certificate Administration database (kept for legacy installs) and the modern Certificate Manager task with certstore.nsf, which HCL recommends on Domino 12 and later.

Generate a CSR on IBM HTTP Server

If you have already generated your CSR, skip ahead to how to install an SSL certificate on IBM HTTP Server.

You can build the request two ways on IHS: through the IKEYMAN GUI (the classic point-and-click utility), or with gskcapicmd on the command line. Both write the private key into the same CMS key database and produce a PKCS #10 request as a .arm file that you submit to your Certificate Authority. Pick the GUI on a desktop or a server with a display; pick the CLI on a headless box or when you want a repeatable script.

Prerequisites: IBM HTTP Server is installed, GSKit is on the system (it ships inside the IHS package), and the IHS bin directory is on your PATH or you know its full path (typically /opt/IBM/HTTPServer/bin/ on Linux/AIX, or C:\Program Files\IBM\HTTPServer\bin\ on Windows). You also need a working directory where you can write the new key database and the CSR file, and somewhere to record the key database password.

Method 1. Generate a CSR with IKEYMAN (GUI)

Step 1. Create a new CMS key database (.kdb)

• Start IKEYMAN. On Windows, open Start > IBM HTTP Server > Start Key Management Utility. On Linux, AIX, or other UNIX, run ikeyman from the IHS bin directory (for example /opt/IBM/HTTPServer/bin/ikeyman); you need a working X11 display.
• From the menu, choose Key Database File > New.
• In the Key database type drop-down, select CMS. This is the format IBM HTTP Server reads.
• In File Name, enter a name for the new database (for example key.kdb).
• In Location, point to a folder you can find again (for example /opt/IBM/HTTPServer/ssl/ on Linux, or C:\IBM\HTTPServer\ssl\ on Windows). Click OK.
• Set a strong password, then tick Stash password to a file so IKEYMAN writes a matching .sth stash file next to the .kdb. IHS reads the stash at start-up so you do not have to type the password each time the server starts. Click OK.

IKEYMAN creates two files in that folder: the database itself (key.kdb) and the stash (key.sth). Treat both as secret. Keep their file permissions tight (readable only by the IHS user) and back them up to a safe location, because you cannot recover the private key without them.

Step 2. Create the certificate request

• With the new database open, find the Key database content drop-down and change it to Personal Certificate Requests.
• Click New. The Create New Key and Certificate Request dialog opens.

Fill in the fields with standard ASCII characters only; non-Latin letters break the request:

• Key Label: a short identifier for this certificate inside the key database, for example www.example.com. You reference this label later in httpd.conf with the SSLServerCert directive.
• Key Size: select 2048. This is the current minimum every public CA accepts. Choose 3072 or 4096 only if your policy requires a larger key; the trade-off is slightly slower TLS handshakes.
• Signature Algorithm: pick SHA256WithRSA (or stronger, such as SHA384WithRSA). Avoid anything with SHA-1; public CAs will not issue against it.
• Common Name: the fully qualified domain name you want to secure, for example www.example.com. For a wildcard certificate, put an asterisk in front of the apex, for example *.example.com.
• Organization: the full legal name of your company, exactly as registered. Required for OV and EV certificates; ignored for DV.
• Organizational Unit: this attribute is deprecated for public certificates (the CA/Browser Forum has phased it out). Leave it blank or enter a short label such as IT.
• Locality: the full city name (for example Seattle, not SEA).
• State/Province: the full state or province name (for example Washington, not WA).
• Country: the two-letter ISO country code, for example US, GB, or DE.
• Subject Alternative Names (SAN): add every hostname that should appear on the certificate, including the value you put in Common Name. Modern browsers ignore Common Name and validate only against the SAN list, so a multi-name certificate needs entries here.
• Enter the name of a file in which to store the certificate request: a path and name ending in .arm, for example /opt/IBM/HTTPServer/ssl/www_example_com.arm. Save it in the same folder as the key database so the two stay together.

Click OK. IKEYMAN generates the key pair inside the key database, stores the request as a pending entry, and writes the PKCS #10 CSR to the .arm file you named.

Step 3. Copy the CSR and submit it to the CA

Open the .arm file in any text editor (Notepad, vi, nano). You will see a block like this:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIDXjCCAkYCAQAwgZQxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApXYXNoaW5ndG9u
... (many lines of base64) ...
-----END NEW CERTIFICATE REQUEST-----

Select the entire block, including the BEGIN and END lines, copy it, and paste it into the CSR field on your order form. The private key stays in the key database on the server; only the CSR text leaves the machine.

Method 2. Generate a CSR with gskcapicmd (CLI)

The gskcapicmd utility (sometimes listed as gskcmd for the Java wrapper, or as gsk8capicmd_64 on 64-bit GSKit installations) does the same work as IKEYMAN without a graphical session. Run it from the IHS bin directory.

Step 1. Create the CMS key database and stash file

Pick a folder for the key database, then run:

gskcapicmd -keydb -create \
  -db /opt/IBM/HTTPServer/ssl/key.kdb \
  -pw your_strong_password \
  -type cms \
  -stash

Argument breakdown:

• -db: the full path to the new .kdb file.
• -pw: the password that protects the key database.
• -type cms: the format IHS reads.
• -stash: writes a matching .sth stash file next to the database so IHS can read it without prompting at start-up.

On the command line, the password is visible in process listings and shell history. After the database exists, change the password to one that is not recorded in history with gskcapicmd -keydb -changepw, or pass the password through an environment variable and unset it.

Step 2. Create the certificate request

Generate the key pair and the PKCS #10 CSR in one step, with SAN entries for every hostname you want on the certificate:

gskcapicmd -certreq -create \
  -db /opt/IBM/HTTPServer/ssl/key.kdb \
  -pw your_strong_password \
  -label www.example.com \
  -dn "CN=www.example.com,O=Example Inc,L=Seattle,ST=Washington,C=US" \
  -size 2048 \
  -sigalg SHA256WithRSA \
  -san_dnsname "www.example.com,example.com" \
  -file /opt/IBM/HTTPServer/ssl/www_example_com.arm

Argument breakdown:

• -label: the identifier for this certificate inside the key database. Reference it later from httpd.conf with the SSLServerCert directive.
• -dn: the Distinguished Name, written as one string with comma-separated attributes. Use CN= for the FQDN and the two-letter ISO code in C=.
• -size: 2048 is the minimum. Use 3072 or 4096 only if your policy mandates it.
• -sigalg: SHA256WithRSA (or SHA384WithRSA). Do not use SHA-1.
• -san_dnsname: a comma-separated list of every hostname that must appear on the certificate. Include the Common Name value in this list. Browsers and most TLS libraries validate only the SAN, not the CN.
• -file: the path where gskcapicmd writes the .arm CSR file.

If you need an ECDSA key instead of RSA, replace -sigalg SHA256WithRSA with -sigalg SHA256WithECDSA and change -size to match your target curve (-size 256 for P-256, -size 384 for P-384). The supported curves are secp256r1 (P-256), secp384r1 (P-384), and secp521r1 (P-521). ECDSA support in IHS is fully exposed only through gskcapicmd; IKEYMAN does not let you choose ECDSA on older IHS releases. For ECDSA on a specific IHS release, follow IBM’s certificate management guidance.

Step 3. List and verify the request

Confirm the request was added to the key database:

gskcapicmd -certreq -list \
  -db /opt/IBM/HTTPServer/ssl/key.kdb \
  -pw your_strong_password

To read the CSR back and check the Common Name, SAN entries, key size, and signature algorithm:

gskcapicmd -certreq -details \
  -db /opt/IBM/HTTPServer/ssl/key.kdb \
  -pw your_strong_password \
  -label www.example.com

Then open the .arm file in a text editor, copy the full BEGIN NEW CERTIFICATE REQUEST to END NEW CERTIFICATE REQUEST block, and submit it on your CA order form.

Check the CSR before you submit it (optional)

If you have OpenSSL installed, run this on the same machine to confirm the subject, the SAN list, and the key size:

openssl req -noout -text -in www_example_com.arm

Prefer an online tool? Paste the contents of the request into SSL Dragon’s CSR Decoder to read back the same details. Confirm that the Common Name matches the hostname clients will use and that every required hostname appears under Subject Alternative Name.

After the CA issues your certificate

The signed certificate must come back into the same key database that produced the CSR, against the same label. Receive it with the CLI:

gskcapicmd -cert -receive \
  -db /opt/IBM/HTTPServer/ssl/key.kdb \
  -pw your_strong_password \
  -file www_example_com.crt

Or do the same in IKEYMAN under Personal Certificates > Receive. Add the root and intermediate certificates first as signer certificates, then update httpd.conf with the KeyFile and SSLServerCert directives and restart IHS. The full procedure is covered in how to install an SSL certificate on IBM HTTP Server.

Generate a CSR on HCL Domino

Note: IBM Domino is now HCL Domino. HCL closed the acquisition of IBM’s collaboration portfolio (including Notes/Domino) on July 1, 2019. On Domino 12 and later, HCL recommends the Certificate Manager task (with certstore.nsf and TLS Credentials documents) for all new TLS work. The classic Server Certificate Administration database (CERTSRV.NSF) still works for legacy installs and is documented below, but new deployments should use Certificate Manager.

Method A. Create a CSR with Certificate Manager (Domino 12+ / 14.x)

• Add the CertMgr task on your designated Certificate Manager server so it creates certstore.nsf. On each Domino server that needs to read TLS keys, run CertMgr too so the database replicates.
• Open certstore.nsf, go to TLS Credentials, and click Add TLS Credentials.
• Host names: enter the exact FQDN clients will use, and add every additional hostname as a Subject Alternative Name.
• Servers with access: select the Domino servers that must be able to read the private key.
• Certificate Provider: choose Manual for any third-party CA. (Pick Let’s Encrypt only if you want CertMgr to obtain a free ACME-issued certificate automatically.)
• Key type: choose RSA or ECDSA.
• RSA: select 2048 bits (or larger if your policy requires it).
• ECDSA: pick a curve (P-256 or P-384; P-384 is the listed default).
• Click Submit Request. CertMgr generates the key pair, signs the CSR, and the document moves to Status = Waiting.
• Open the document, copy the value of Certificate signing request (CSR) (or use the Copy CSR action that appears after processing), and paste the PEM block into your CA order form.

The private key stays inside certstore.nsf, encrypted to the servers you authorized. You never export it. When the CA issues your certificate, paste the signed certificate (plus the issuing chain) back into the same TLS Credentials document and CertMgr installs it for you. The full reference is in HCL’s Certificate Manager documentation.

Method B. Classic Server Certificate Administration (legacy Domino)

Use this method only on Domino releases that still rely on key ring files (.kyr + .sth). HCL marks it as legacy on Domino 12 and later.

• In the Domino Administrator client, open Server Certificate Administration.
• Choose Create Key Ring. Enter a key ring name and a strong password.
• Key Size: select 2048 bits.
• Fill in the Distinguished Name:
• Common Name: the FQDN you want to secure, for example www.example.com.
• Organization: the full legal name of your company.
• Organizational Unit: leave blank or enter a short label such as IT (the attribute is deprecated for public certificates).
• City or Locality: the full city name, for example Seattle.
• State or Province: the full state name, for example Washington.
• Country: the two-letter ISO code, for example US.
• Review the details and click Continue. Domino creates the key ring file.
• Choose Create Certificate Request. Under Method, pick Paste into form on CA’s site. Domino displays the CSR text.
• Copy the entire CSR block (including the BEGIN and END lines) and paste it into your CA order form.

Classic key ring files do not support SAN entries through this dialog. If you need a multi-name certificate, move to Certificate Manager (Method A) or generate the CSR off-server.

Frequently Asked Questions