IBM Support

Using iKeyman to create and manage digital certificates

Technical Blog Post


Abstract

Using iKeyman to create and manage digital certificates

Body

In today's blog post we will be using the iKeyman SSL tool on Windows to create and manage keystores, keys and certificates as well as provide some examples of how we can use this tool.  We will describe the differences between self-signed and CA signed certificates, and will be creating a self-signed certificate for signing our own certificate request.  Once signed, we will receive our certificates into the keystore our application will use.

iKeyman is shipped with WebSphere application server as well as many other IBM applications to manage keystores and certificates.  Since WebSphere Application Server uses JKS keystores by default, we will use the iKeyman command line tool to create and work with our certificates and keystores.

There are command line and GUI versions of the iKeyman tool available but the GUI is limited in its functionality.  For example, it does not provide a mechanism for adding a basic constraint to a certificate. Without the basic constraint, we cannot create a Certificate Authority type of signer certificate which is needed when using self-signed certificates for use with the Maximo application server.  For this presentation, we will use the ikeycmd command line tool to accomplish all tasks related to the creation, signing, and receiving of signed certificates.

Self-signed vs CA signed certificates:

So, what are self-signed certificates?  These are certificates that have been signed by themselves - The Subject and Issuer Distinguished Names are identical

- The Subject key identifier and authority key identifier are identical and the public key from the public/private key pair is used by client applications to validate the server's personal certificate

- A self-signed certificate can be created using most SSL tools quickly and is supported by most SSL enabled software or middleware.  WebSphere application server provides facilities to create self-signed certificates within the administration console but does not provide a mechanism to set the basic constraints needed when creating a trusted CA certificate.  The administration console is best used for creating a certificate request, to be signed by a third party.
 
- A self-signed certificate does not require a certificate request to be signed by a Certificate Authority since it is signed solely by itself.

- When a self-signed certificate is used as a personal certificate, it's typically only used for testing purposes because it is not trusted or known by external client applications without first being explicitly added and trust being enabled within the client application.

- The public portion of this type of certificate must be installed, and trust must be enabled in every client application that needs to be able to validate the personal certificate it receives from the server during the ssl handshake.  


There are many benefits to using a Certificate Authority (or CA) signed certificates including insurance protection, guarantees made by the certificate authority against data loss or unauthorized access as well as revocation checking.

- In a CA signed certificate, the Subject and Issuer Distinguished Names are distinct from one another, whereby the issuer Distinguished name belongs to an established certificate authority such as Verisign, Comodo, Entrust, and others you probably have heard of before.  These signer certificate are found in most software already, such as IE, Firefox, and many other types of software that employ digital cryptography.  The top level certificate in the certificate chain is always a self-signed certificate, but is issued by a trusted certificate authority.

- The Subject key identifier of the CA certificate matches the authority key identifier specified on the personal certificate.  Applications use these values to determine the path to the root level signer certificate.

- To obtain a CA signed certificate, a certificate request must be generated and sent to a Certificate Authority to be signed.  Once signed and returned, the certificate is added to the key store.  This process usually involves a fee for the certificate ranging in price.

- When used as a personal certificate for an application server such as Maximo, it is typically installed in a production environment where security and strict validation must be enforced.

- Certificates issued by Certificate Authorities are trusted and provide security assurances over self-signed certificates such as external CRL and OSCP revocation checking, enforcing stronger cipherspec and key size requirements during SSL handshaking, and preventing man-in-the-middle attacks.

- The top most signer certificate, known as the root certificate, must be installed on every client that needs to be able to validate the personal certificate it receives from the server during the SSL handshake.


Using the ikeycmd tool

Now we will perform the necessary commands using the iKeyman command line tool.  


In the examples that follow, we will create two key stores.  keyselfsigned.jks which will be used to create a self-signed certificate, and keypersonalcert.jks, which will be used to create a certificate request and to receive the final signed certificate.  The keypersonalcert.jsk is the keystore that you would use with your application server since it will contain the final signed certificate along with the self-signed CA certificate.

A self-signed certificate will be used in this example as a Certificate Authority signer to sign the certificate request.  This is the same type of process a certificate authority uses to sign certificate requests receive by customers.

Let's start by creating our keystores.


        ikeycmd -keydb -create -db keyselfsigned.jks -pw 1234 -type jks

        ikeycmd -keydb -create -db keypersonalcert.jks -pw 1234 -type jks



In these examples, we set the password for each key store to "1234", and specified the type jks which is used by java applications.  The next command creates a self-signed certificate in keyselfsigned.jks key store and enables this certificate to be used as a signer certificate, in order to allow us to sign our personal certificate request.  The resulting certificate is our CA signer.


        ikeycmd -cert -create -db keyselfsigned.jks -pw 1234 -label mysigner -dn "cn=My self-signed Signer Certificate ou=Software Group o=IBM c=CA" -size 2048 -expire 365 -ca true


In this example, we created a self-signed certificate using the -cert -create parameters, specified the distinguished name between double quotes, set a label for identification purposes, and specified the size of the key to be 2048 bits in length. We also set the certificate expiry to 365 days, and added the critical basic constraint "ca" which we set to true.  

Some implementations of SSL will not allow a signer certificate to act as a signer unless this critical basic constraint exists, and is set to true.  This is the case for Firefox, and will prevent you from adding it to the certificate authority key repository if missing.



The next command will allow us to view the details of the certificate we just created:


        ikeycmd -cert -details -label mysigner -db keyselfsigned.jks -pw 1234
        

        
        Label: mysigner
        Key Size: 2048
        Version: X509 V3
        Serial Number: 54 AF ED 9A
        Issued by: CN="My self-signed Signer Certificate ou=Software Group o=IBM c=CA"
        Subject: CN="My self-signed Signer Certificate ou=Software Group o=IBM c=CA"
        Valid: From: Friday, January 9, 2015 10:02:50 AM EST To: Saturday, January 9, 2016 10:02:50 AM EST
        Fingerprint: 46:22:00:DC:F9:B8:2B:35:52:D7:C0:59:4D:3D:97:5B:AA:47:46:52
        Extensions:
          - AuthorityKeyIdentifier: ObjectId: 2.5.29.35 Criticality=false
        AuthorityKeyIdentifier [
        KeyIdentifier [
        0000: 0e db 91 b7 a3 79 9d 4b                           .....y.K
        ]
        
        ]
        
          - BasicConstraints: ObjectId: 2.5.29.19 Criticality=true
        BasicConstraints:[
        CA:true
        PathLen:2147483647
        ]
        
          - SubjectKeyIdentifier: ObjectId: 2.5.29.14 Criticality=false
        SubjectKeyIdentifier [
        KeyIdentifier [
        0000: 0e db 91 b7 a3 79 9d 4b                           .....y.K
        ]
        ]
        
        Signature Algorithm: SHA1withRSA (1.2.840.113549.1.1.5)
        Trust Status: enabled
        
        

The -details parameters requires the -label parameter and a valid label name to be passed so we can see the full details of the certificate.  In the output we can see that the Issuer and Subject names are identical which is:  "My self-signed Signer Certificate".  This is our new CA signer certificate.


Previously, we created the keypersonalcert.jks key store, which we will use to create the certificate request, to be signed and used for our application server.


        ikeycmd -certreq -create -db keypersonalcert.jks -pw 1234 -label ibmwebsphereformaximo -dn "cn=My Personal Certificate ou=MQ o=IBM c=CA" -size 2048 -file personalcertreq.arm



The result is a certificate request created in the keystore, as well as a file called personalcertreq.arm whose contents will look similar to the output shown.


        more personalcertreq.arm
 
       
        
        -----BEGIN NEW CERTIFICATE REQUEST-----
        MIICeDCCAWACAQAwMzExMC8GA1UEAxMoTXkgUGVyc29uYWwgQ2VydGlmaWNhdGUgb3U9TVEgbz1J
        Qk0gYz1DQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIwMdto45TyvAg2QnW55UU2k
        AAqCrLLSHbsqMHkqNKTcH+5JR5xpm2kbKfV6ztQ2Y24f7hxL4mZTnPJ2rON9nOmvpYfBDyOubn6E
        LIe7A3H66y87yI0qVstgR62OW5nV72Eg24gMx4In65dzzm25h92wT57UZ8EF/oze75QcXown8blP
        u1dI4luc9JbWX/R3DK9aesQ2Po/dRP5daHvOjCt2JySWUe0fvgsWzBYerOnSlR6sd0361ynt0nyx
        tpMwfGytkXVqzFbz8Blpi3bB16aBEhzNjo2xjhFigITsGOzwZ6ubpPTyJ7ZJtjY93Ax/KEiNqRjX
        1aSsRNj3NAITtPMCAwEAAaAAMA0GCSqGSIb3DQEBBQUAA4IBAQB7zqbwJBnmx8nE4r7dZO+6sEak
        4S0Lz5Pxer0KRW7ZEcgikFEw3R1oaoggch+yh3sDWxBPyalrSZJq+JaXQgSpdrpRciA8cMYn5KC+
        VpTdsecQCdvY9xZdGYX9xnBYRrINPdOdk/W4nsMB6HLoHtZNob4Y09z0Z04W0CCs5j2gyMigBB+e
        F+l3hmPwIoTZF3fPgYUZqQYWzAxzu+kcvqMrR4IzHPDr9zEWZqjpZPgfS1fvJ46sTaJMqXbjaP2F
        BHkhSiSHF72iRhr5d2clqudLPiUOenefrsJ+60/fa1eP4QZnVrP2xNwk9eF0cPgTuuW/hEYcQteb
        oMaHBHxmHz5B
        -----END NEW CERTIFICATE REQUEST-----


This is how a PEM formatted file looks with base64 encoded data between the tags, and the type of certificate is noted within the begin and end tags.


The next command shows the same certificate request as it exists in the keystore before it is signed and received back into the keystore.


        ikeycmd -certreq -details -label ibmwebsphereformaximo -db keypersonalcert.jks -pw 1234
    
    
        
        Label: ibmwebsphereformaximo
        Key Size: 2048
        Subject: CN="My Personal Certificate ou=MQ o=IBM c=CA"
        Fingerprint: AF:29:6B:68:25:AD:A1:2B:6D:C5:F9:F5:69:20:90:C7
        Signature Algorithm: SHA1withRSA (1.2.840.113549.1.1.5)

        
        
        
        
In this output we created a certificate request which is not signed, and since this will be a personal certificate representing a Maximo application server, the label was set to ibmwebsphereformaximo simply for identification purposes.


Now we have to have this certificate request signed by our previously created signer certificate.  Earlier, we created a self-signed certificate for the purpose of using it as a Certificate Authority signer.  The next command is used to sign the certificate request using that signer.


        ikeycmd -cert -sign -db keyselfsigned.jks -pw 1234 -label mysigner -target signedpersonalcert.cer -format ascii -file personalcertreq.arm


In this example, we used the parameters -cert -sign.  We specified the database name and label name of the certificate to be used as the signer, and we specified the target file name to write the signed certificate to, called signedpersonalcert.cer.  We passed the -file parameter to tell the command the location of the existing certificate request.


When we look at the resulting signed certificate file, it looks like the output seen here.

The begin and end tags indicate this is a certificate.


        more signedpersonalcert.cer
        
        
        -----BEGIN CERTIFICATE-----
        MIIDJDCCAgygAwIBAgIEVK/ueTANBgkqhkiG9w0BAQUFADBJMUcwRQYDVQQDEz5NeSBzZWxmLXNp
        Z25lZCBTaWduZXIgQ2VydGlmaWNhdGUgb3U9U29mdHdhcmUgR3JvdXAgbz1JQk0gYz1DQTAeFw0x
        NTAxMDkxNTA2MzNaFw0xNjAxMDkxNTA2MzNaMDMxMTAvBgNVBAMTKE15IFBlcnNvbmFsIENlcnRp
        ZmljYXRlIG91PU1RIG89SUJNIGM9Q0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCM
        DHbaOOU8rwINkJ1ueVFNpAAKgqyy0h27KjB5KjSk3B/uSUecaZtpGyn1es7UNmNuH+4cS+JmU5zy
        dqzjfZzpr6WHwQ8jrm5+hCyHuwNx+usvO8iNKlbLYEetjluZ1e9hINuIDMeCJ+uXc85tuYfdsE+e
        1GfBBf6M3u+UHF6MJ/G5T7tXSOJbnPSW1l/0dwyvWnrENj6P3UT+XWh7zowrdickllHtH74LFswW
        Hqzp0pUerHdN+tcp7dJ8sbaTMHxsrZF1asxW8/AZaYt2wdemgRIczY6NsY4RYoCE7Bjs8Germ6T0
        8ie2SbY2PdwMfyhIjakY19WkrETY9zQCE7TzAgMBAAGjKjAoMBMGA1UdIwQMMAqACA7bkbejeZ1L
        MBEGA1UdDgQKBAgG3wy5mMUC7TANBgkqhkiG9w0BAQUFAAOCAQEAewRPAQiX84fWubyC71PVabc0
        74UozbPLbX3kTaiNi7/8iStu8ZTz3kEIPz2kPOtoqgVVigX4JmkrTO63MtO96H7QODBwRzO0ZET+
        B4M6ACZT+Cxo/8ZwBA8UvNLXW2Vd39Xz2OCivSbdf8H0p89WMGeTe6FMlw1xKSXEJfCg/SzlRQmk
        wM+vGKtkOWK3Bd0zgJlfgAtRyeLrX8eF5UlBKWekAheaqKvVgPK8UEpP+SHSGm7i63lV0cztSI5Y
        lXBI+H5b5FSFYlfB7nZvXf/JKZK6abaZvVe3MiKSsv3wa0LqGVyBLsHm2IhS2Tk+Gut62BWP1IRp
        ZcPZQE8NRzf2ww==
        -----END CERTIFICATE-----


We will need to receive the signed certificate into the keystore our application server will use, but first we must make sure that the CA signer certificate is added into the application server's key store.  We need to extract the signer certificates from the original keystore to add it to the one we will use with the application server using this command:


        ikeycmd -cert -extract -db keyselfsigned.jks -pw 1234 -label mysigner -target signer.cer -format ascii


This command results in a file called signer.cer, indicated by the -target parameter in the extract command which is in PEM format.  This command extracts only the public key, leaving the private key in the signer keystore.  The private key should never be exported or given to anyone at any time.

Using the -add parameter we can add this certificate to the keypersonalcert.jks key store using this command:


        ikeycmd -cert -add -db keypersonalcert.jks -pw 1234 -label mysigner -file signer.cer -format ascii -trust enable


This command results in the signer being added to the keystore, specifies that the label will be "mysigner", and sets the trust flag on.  Now that the prerequisite signer certificate has been added as a trusted CA, we can receive the signed certificate into the keypersonalcert.jks key store.

We use the -cert -receive parameters to receive the signed personal certificate shown in this next command:


        ikeycmd -cert -receive -file signedpersonalcert.cer -db keypersonalcert.jks -pw 1234 -format ascii
        
        Validation failed: Unsupported certificate format or algorithm.

In this example, the certificate was received successfully, but an error was displayed.  This error is related to bug caused by the version of iKeyman we used for this presentation.  iKeyman version 3.0.399 corrects this problem but is not problematic.  Since the receive function was successful, the outstanding certificate request no longer exists in the keystore.  We will see the following message when we try to view the associated certificate request:


        ikeycmd -certreq -list -db keypersonalcert.jks -pw 1234
 
       
        No request key was found in the key database.


Since there are no outstanding requests remaining after the successful receive command, the message shown here is expected.


Now we can look at the key store for our certificate to ensure it was added as we expected.  We can use the next command to view a list of all certificates in the key store.


        ikeycmd -cert -list all -db keypersonalcert.jks -pw 1234
 
       
        Certificates in database C:\notes\jvm\bin\keypersonalcert.jks:
           ibmwebsphereformaximo
           mysigner


The result of this command is a list of two certificate labels showing each certificate that currently exists in the keystore.  We can also look at details for the certificate based on the labels shown in the output.


        ikeycmd -cert -details -label ibmwebsphereformaximo -db keypersonalcert.jks -pw 1234
        
        Label: ibmwebsphereformaximo
        Key Size: 2048
        Version: X509 V3
        Serial Number: 54 AF EE 79
        Issued by: CN="My self-signed Signer Certificate ou=Software Group o=IBM c=CA"
        Subject: CN="My Personal Certificate ou=MQ o=IBM c=CA"
        Valid: From: Friday, January 9, 2015 10:06:33 AM EST To: Saturday, January 9, 2016 10:06:33 AM EST
        Fingerprint: 70:30:7F:75:25:F6:E0:2B:63:F1:9B:23:65:30:B0:D3:23:7B:35:01
        Extensions:
          - AuthorityKeyIdentifier: ObjectId: 2.5.29.35 Criticality=false
        AuthorityKeyIdentifier [
        KeyIdentifier [
        0000: 0e db 91 b7 a3 79 9d 4b                           .....y.K
        ]
        
        ]
        
          - SubjectKeyIdentifier: ObjectId: 2.5.29.14 Criticality=false
        SubjectKeyIdentifier [
        KeyIdentifier [
        0000: 06 df 0c b9 98 c5 02 ed                           ........
        ]
        ]
        
        Signature Algorithm: SHA1withRSA (1.2.840.113549.1.1.5)
        Trust Status: enabled


Notice in the output for our personal certificate that the issuer is "My self-signed Signer Certificate" and the Subject is "My Personal Certificate".  Performing the same command on the other certificate, we see it is the self-signed CA.


        ikeycmd -cert -details -label mysigner -db keypersonalcert.jks -pw 1234
        
        Label: mysigner
        Key Size: 2048
        Version: X509 V3
        Serial Number: 54 AF ED 9A
        Issued by: CN="My self-signed Signer Certificate ou=Software Group o=IBM c=CA"
        Subject: CN="My self-signed Signer Certificate ou=Software Group o=IBM c=CA"
        Valid: From: Friday, January 9, 2015 10:02:50 AM EST To: Saturday, January 9, 2016 10:02:50 AM EST
        Fingerprint: 46:22:00:DC:F9:B8:2B:35:52:D7:C0:59:4D:3D:97:5B:AA:47:46:52
        Extensions:
          - AuthorityKeyIdentifier: ObjectId: 2.5.29.35 Criticality=false
        AuthorityKeyIdentifier [
        KeyIdentifier [
        0000: 0e db 91 b7 a3 79 9d 4b                           .....y.K
        ]
        
        ]
        
          - BasicConstraints: ObjectId: 2.5.29.19 Criticality=true
        BasicConstraints:[
        CA:true
        PathLen:2147483647
        ]
        
          - SubjectKeyIdentifier: ObjectId: 2.5.29.14 Criticality=false
        SubjectKeyIdentifier [
        KeyIdentifier [
        0000: 0e db 91 b7 a3 79 9d 4b                           .....y.K
        ]
        ]
        
        Signature Algorithm: SHA1withRSA (1.2.840.113549.1.1.5)
        Trust Status: enabled


We have completed all functions pertaining to the creation of a personal certificate.  The extracted CA signer certificate now needs to be added to every client application that needs to be able to securely access the Maximo application server.  Each application will have tools to allow you to perform this process and may use different tools and processes to accomplish.

[{"Business Unit":{"code":"BU005","label":"IoT"}, "Product":{"code":"SSLKT6","label":"Maximo Asset Management"},"Component":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"","Edition":""}]

UID

ibm11132575