Creating a new key pair and certificate request

You find key pairs and certificate requests stored in a key database. This topic provides information on how to create a key pair and certificate request.

1. Use the gskcapicmd command-line interface. Enter the following command (as one line):

   install_root/bin/gskcapicmd -certreq -create -db name 
   [-crypto module_name [-tokenlabel token_label]] 
   [-pw password | -stashed] -label label -dn dist_name 
   [-size 2048 | 1024 | 512] -file name 
   [-secondaryDB filename -secondaryDBpw password] [-fips] 
   [-sigalg md5|sha1|sha224|sha256|sha384|sha512]

   where:

   • -certreq specifies a certificate request.
   • -create specifies a create action.
   • -db filename specifies the name of the database.
   • -pw password is the password to access the key database.
   • -stashed indicates that the password for the key database should be recovered from the stash file.
   • -label label indicates the label attached to the certificate or certificate request.
   • -dn distinguished_name indicates an X.500 distinguished name. Input as a quoted string of the following format (only CN, O, and C are required): CN=common_name, O=organization, OU=organization_unit, L=location, ST=state, province, C=country.

     For example, "CN=weblinux.raleigh.ibm.com,O=IBM,OU=IBM HTTP Server,L=RTP,ST=NC,C=US"

   • -size 2048 | 1024 | 512 indicates a key size of 2048, 1024, or 512. The default key size is 1024. The 2048 key size is available if you are using IBM® Global Security Kit (GSKit) Version 7.0.4.14 and later.
   • -file filename is the name of the file where the certificate request will be stored.
   • -san * <subject alternate name attribute value> | <subject alternate name attribute value> specifies the subject alternate name extensions in the certificate request that inform SSL clients of alternate hostnames that correspond to the signed certificate.

     These options are only valid if the following line is entered in the ikminit.properties file. DEFAULT_SUBJECT_ALTERNATE_NAME_SUPPORT=true. The * (asterisk) can have the following values:

     dnsname

     The value must be formatted using the preferred name syntax according to RFC 1034, such as the example, zebra,tek.ibm.com.

     emailaddr

     The value must be formatted as an addr-spec according to RFC 822, such as the example, myname@zebra.tek.ibm.com

     ipaddr

     The value is a string representing an IP address formatted according to RFC 1338 and RFC 1519, such as the example, 193.168.100.115

     The values of these options are accumulated into the subject alternate name extended attribute of the generated certificate. If the options are not used then this extended attribute is not added to the certificate.
   • -ca true | false specifies the basic constraint extension to the self-signed certificate. The extension is added with a CA:true and PathLen:<max int> if the value passed is true or not added if the value passed is false.

   Avoid trouble: Two types of escaping might be necessary when you create certificate requests on the command line:

   • Shell escaping
     Shell meta-characters must be escaped if they are meant to be interpreted by the underlying command.

     • Encapsulate string values that are associated with all tags in double quotation marks "....".
     • If the following characters are in the string values. Escape them with a backslash \ character: exclamation mark !, backslash \, double quotation mark ".

     When the gskcapicmd command prompts you for a value such as a password, you do not need to put quotation marks around the string or add the escape characters. The shell is no longer influencing the input that you provide to the command.
   • Escaping commas within the -dn option

     The -dn option takes a comma-separated list of distinguished name components. Because the comma is used as a delimiter, it must be escaped with a backslash when it is used as a literal.

     For example, if the -dn option has the following elements: CN=www.example.com O=Example, Inc. OU=example unit, specify the -dn option as follows:

     -dn "CN=www.example.com,O=Example\, Inc.,OU=example unit" 

   Use the GSKCapiCmd tool. GSKCapiCmd is a tool that manages keys, certificates, and certificate requests within a CMS key database. The tool has all of the functionality that the existing IBM Global Security Kit (GSKit) Java™ command line tool has, except GSKCapiCmd supports CMS and PKCS11 key databases. If you plan to manage key databases other than CMS or PKCS11, use the existing Java tool. You can use GSKCapiCmd to manage all aspects of a CMS key database. GSKCapiCmd does not require Java to be installed on the system.

2. Verify that the certificate was successfully created:
   1. View the contents of the certificate request file you created.
   2. Ensure that the key database recorded the certificate request:

      install_root/bin/gskcapicmd -certreq -list -db filename [-pw password | -stashed]

      You should see the label listed that you just created.

3. Send the newly-created file to a certificate authority.