Set up a public key infrastructure with WebSphere Application Server Community Edition V2.0

Learn the basics of setting up a public key infrastructure in general, and specifically how it can be achieved using IBM® WebSphere® Application Server Community Edition V2.0, a free to use Java™ EE 5 certified application server.

Share:

Vamsavardhana Reddy Chillakuru (vamsic007@in.ibm.com), Advisory Software Engineer, EMC

Vamsavardhana Reddy Chillakuru , a.k.a Vamsi, is an Advisory Software Engineer at IBM India Software Labs in Bangalore, India. He is a committer, a member of the Apache Geronimo Project Management Committee, and is part of the IBM WebSphere Application Server Community Edition Level 3 Support Team. He received his Bachelor of Statistics (Hons.) and Master of Statistics degrees from Indian Statistical Institute, Kolkata, India in the years 1994 and 1996 respectively.


developerWorks Contributing author
        level

Manu T. George (mageorge@in.ibm.com), Staff Software Engineer, IBM

Manu T. George is a Staff Software Engineer at IBM India Software Labs in Bangalore, India. He is a committer on Apache OpenEJB project, and is a part of the IBM WebSphere Application Server Community Edition Level 3 Support Team. He received his Bachelor of Technology in Applied Electronics from the College of Engineering Trivandrum in the year 2001.


developerWorks Contributing author
        level

24 October 2007

Introduction

Client authentication using digital certificates helps overcome the problem of using compromised credentials and provides a better sense of security about your applications. Typically, since application servers generally do not provide the issuing of digital certificates, you would be required to obtain digital certificates from external certification authorities. In this respect, IBM WebSphere Application Server Community Edition V2.0 stands out from other application servers, as it does provide certification authority (CA) functionality.

Download Community Edition V2.0 now!
IBM WebSphere Application Server Community Edition V2.0 is free to use and deploy. Download it now to get started.

IBM WebSphere Application Server Community Edition V2.0 (hereafter referred to as Community Edition), a free-to-use Java Platform, Enterprise Edition 5.0 (Java EE 5) certified application server based on Apache Geronimo 2.0.1, provides a Certification Authority portlet and a CA Helper application that performs an array of tasks that a typical CA would perform. This article shows you how easily a public key infrastructure (PKI) can be setup using Community Edition, and how you can request and download digital certificates from your Web browser.

To follow along, you will need WebSphere Application Server Community Edition V2.0 (or later), and a browser that supports the KEYGEN form tag for requesting and downloading digital certificates using the CA Helper application.

Digital certificates

The most common use of a digital public-key certificate -- commonly referred to as a digital certificate or just "certificate" for simplicity -- is to verify that a user sending a message is who they claim to be, and to provide the receiver with the means to encode a reply. This feature is used for Web server and client authentication over HTTPS protocol, which is based on SSL. At a high level, this is how digital certificates usually work:

  1. An entity wishing to send an encrypted message creates a public-private keypair and applies for a digital certificate from a certification authority.
  2. The CA issues a digital certificate containing the public key of the applicant (commonly referred to as the subject), the subject's identity, the CA's identity, a serial number, a validity period, and a variety of other identification information.
  3. The CA makes its own public key readily available through print publicity.

Two public-key cryptography algorithms that are widely used are RSA (named after its inventors Rivest, Shamir and Adleman) and DSA (Digital Signature Algorithm). The most widely used standard for digital certificates is X.509. Community Edition currently supports only RSA algorithm for generating keypairs (see Resources).

The administrative console

The administrative console provides a convenient, user-friendly way to administer many aspects of Community Edition. It uses several portlets, such as the Applications portlet, the Keystores portlet, and the Certification Authority portlet, to perform key administration tasks. The admin console provides additional portlets, such as the Information portlet, the JVM portlet, and the DB Info portlet, that let an administrator monitor and view the status of the server.

Once Community Edition is started, you can access the administrative console (Figure 1) at: http://localhost:8080/console, with the default login of system with a password of manager.

Figure 1. Administrative console - Welcome
Figure 1. Administrative console - Welcome
  • Keystores portlet

    The Keystores portlet enables the management of certificates and private keys in Community Edition using Java™ keystore files. Launch the Keystores portlet (Figure 2) by clicking on the Keystores link in the Console Navigation pane of the admin console.

    Figure 2. Keystores portlet
    Figure 2. Keystores portlet

    All the keystores in Community Edition are listed in the portlet. The Keystore File column shows the name of the keystore file; in Figure 2, there is one keystore, called "geronimo-default," which is the default keystore shipped with Community Edition. The Editable and Available columns show whether the keystore is locked or unlocked for editing and availability, respectively. Click a "locked" icon (shown in the Editable column) and provide the password used at keystore creation time to unlock a keystore. Similarly, you can lock a keystore for editing and availability by clicking an "unlocked" icon (shown in Available column) in the corresponding column. When a keystore is unlocked for editing, the Keystore File column will provide a clickable link through which you can view or alter the contents of the keystore. You can also click New Keystore to create a new keystore.

    Keystore files are stored under the <WASCE_HOME>/var/security/keystores directory (where <WASCE_HOME> refers to the directory in which Community Edition is installed). JKS and PKCS12 are common types of keystores; Community Edition currently supports JKS type keystores only. (See Resources for more on using the Keystores portlet.)

  • Applications portlets

    There are several Applications portlets available in the admin console, listed under the Applications heading in the Console Navigation pane (Figure 1). With these portlets you can deploy new Web, EJB, and Java EE applications, as well as application clients, Java EE connectors, and more. You can also start, stop, and uninstall existing applications, connectors, and so on.

    The Web App WARs portlet (Figure 3) lists all the WARs deployed in Community Edition; these applications can be started, stopped, restarted, and uninstalled from this portlet. The portlet also provides a URL that contains the context root to access a running Web application. In this article, you will use the Web App WARs portlet to start the CA Helper application.

    To launch the Web App WARs portlet, click Web App WARs under Console Navigation (Figure 1).

    Figure 3. Web App WARs portlet
    Figure 3. Web App WARs portlet
  • Certification Authority portlet

    The Certification Authority (CA) portlet (Figure 4) enables an administrator to setup a keypair and a self-signed certificate for the CA, lock/unlock, and access CA functions. The available links in the CA portlet will differ, depending on whether a CA has been initialized, and if it has been initialized, whether the CA is locked or unlocked.

    To launch the CA portlet, select the Certificate Authority link in the Console Navigation pane (Figure 1). Figure 4 shows the CA portlet before a CA is initialized.

    Figure 4. Certification Authority portlet - Welcome
    Figure 4. Certification Authority portlet - Welcome

    When you select Setup Certification Authority from this portlet, the CA's keypair and self-signed certificate are created. As you will see, the CA's keypair and self-signed certificate are created using the Setup Certification Authority function from this portlet. With the CA initialized, any subsequent access to the CA portlet will display further options (Figure 5):

    Figure 5. Certification Authority portlet - Functions
    Figure 5. Certification Authority portlet - Functions

    Functions available from the CA portlet after the CA is initialized include:

    • Lock CA: Locks the CA so that the CA functions are not accessible. When you select this option, the CA will be locked and the panel shown in Figure 6 will display.
    • View CA Details: Displays the details of the CA
    • Publish CA Certificate: Stores the CA's certificate in the CA's certificate store.
    • Requests to be verified: Displays a list of Certificate Signing Requests (CSR), submitted from Web browsers, that are due for verification.
    • Requests to be fulfilled: Displays a list of CSRs that have been verified and are pending issue of a certificate.
    • Issue New Certificate: Issues a new certificate directly from the portlet using the CSR text.
    • View Issued Certificate: Search previously issued certificates.
    Figure 6. Certification Authority portlet - Locked
    Figure 6. Certification Authority portlet - Locked

    CA functions are not available when the CA is locked. You can unlock the CA by clicking the Unlock CA link and providing the password that was used when setting up the CA.

More on these functions will be discussed later.

Public key infrastructure

A public key infrastructure (PKI) is a means for associating public keys with the respective user identities using a Certification Authority (CA). A PKI enables users with no prior contact to authenticate each other by accepting the CA as a trusted third party. The CA itself can be certified by another CA, or it can use a self-signed certificate. When the CA uses a self-signed certificate, called a Root CA, the CA usually publishes its self-signed certificate details publicly so that users can establish the authenticity of the CA. Users who want to be certified by the CA will typically send their Certificate Signing Request (CSR) to a Registration Authority (RA) that then validates the authenticity of the request, after which the CA issues a digital certificate.

Each issued certificate possesses a serial number, and no two certificates issued by a CA will have the same serial number. The CA makes any certificates it has issued available, should there be any requests for them. The CA can also revoke certificates it has issued (usually upon the request of the recipient of the certificate), periodically publish a Certificate Revocation List (CRL), and also provide an interface (typically a Web site) through which users can submit CSRs and download issued certificates.

By default, Community Edition Certification Authority uses a self-signed certificate. Should you need to have the Community Edition CA certified by another CA, a CSR can be generated from Community Edition CA's keypair (using the Keystores portlet) that can be sent to the external CA for processing. Once processed, you can use the certificate issued by the external CA instead of the Community Edition CA's self-signed certificate. The Community Edition CA uses a certificate store and certificate request store on disk-based files.

The next sections examine how to setup a PKI using the CA portlet and the CA Helper application.

CA Helper application

The CA Helper application (Figure 7) in Community Edition provides an interface for you to request a digital certificate using your Web browser, download and install the certificate issued by the CA, and install the CA certificate into your browser.

After completing the CA setup, you can start CA Helper by clicking on the Start link that corresponds to org.apache.geronimo.configs/ca-helper-tomcat/2.0.1/car, under Commands in the Web App WARs portlet (Figure 3). You can access the application at: http://localhost:8080/CAHelper.

Figure 7. CA Helper application - Welcome
xxx

The CA Helper welcome panel displays three options:

  • Request Certificate: Lets you submit a CSR using your Web browser, which generates a keypair for you. CSRs submitted in this manner are stored in the CA's CertificateRequestStore and readily displays in the CA portlet for easy processing of the request.
  • Download your Certificate: Lets you download and install a certificate issued by the CA in response to a CSR submitted earlier.
  • Download CA Certificate: Lets you view the CA's details and install CA's certificate into the Web browser.

More on the options later.

Certification Authority

Let's look at the details of the initial setup required by a CA and how it issues digital certificates by going through each of the major activities associated:

  1. Setup CA keypair and self-signed certificate

    To generate a keypair:

    1. Start Community Edition and access the administrative console.
    2. Navigate to the CA by selecting the Certificate Authority link under Console Navigation (Figure 1).
    3. Select Setup Certification Authority (Figure 4).
      Figure 8. CA setup - Step 1
      Figure 8. CA setup - Step 1

      The significant fields on the CA Setup panel (Figure 8) include:

      • Common Name (CN): CA's common name.
      • Division/Business/Unit(OU), Company/Organization(O), City/Locality(L), State/Province(ST): Fields to reflect the identity of the CA.
      • Country Code(2 char) (C): Two-character ISO 3166 country code that reflects the CA's country.
      • Alias: Name used to identify this keypair in the keystore.
      • Key Algorithm: The private key algorithm to be used to generate the keypair. (Community Edition currently supports only RSA.)
      • Key Size: Length in bits of the modulus of RSA keypair. The higher the key size, more secure is the keypair. The administrative console supports 512, 1024, and 2048 key sizes.
      • Password/Confirm Password: Password used to protect the CA's private key and keystore. (This password will be required to unlock the CA.)
      • Certificate Serial Number: Serial number for CA's self-signed certificate. Any certificates issued by this CA later will have serial numbers starting from the next number.
      • Valid From Date: Start date of the CA certificate's validity.
      • Valid To Date: End date of the CA certificate's validity.
      • Signature Algorithm: Algorithm to be used to sign the self-signed certificate. (Community Edition supports MD2withRSA, MD5withRSA, and SHA1withRSA.)

      Enter or select the following values for these fields:

      • Common Name (CN):CE Dev CA
      • Division/Business Unit (OU): Your division
      • Company/Organization (O): Your company
      • City/Locality (L): Your city
      • State/Province (ST): Your state
      • Country Code (2 char) (C): your country code
      • Alias:cedevca
      • Key Algorithm: RSA
      • Key Size: 1024
      • Password: cedevca
      • Confirm Password:cedevca
      • Certificate Serial Number:0
      • Valid From Date(mm/dd/yyyy): 10/01/2007
      • Valid To Date(mm/dd/yyyy): 10/01/2017
      • Signature Algorithm:MD5withRSA

      Click Review CA Details.

      Figure 9. CA Setup - Step 2
      Figure 9. CA Setup - Step 2
    4. On the Review and Confirm CA Details dialog (Figure 9), confirm the values you entered, then select Setup Certification Authority to complete the CA setup. Community Edition creates a new keystore with name "ca-keystore," and generates a new keypair and a self-signed certificate. The keystore and the keypair are protected with the password "cedevca." The Keystores portlet will now include ca-keystore in the list of keystores. If setup is successful, a CA details screen with the message "CA Setup is successful!" will display (Figure 10).

      Figure 10. CA setup successful
      Figure 10. CA setup successful

      Figure 10 also shows the details of the CA's self-signed certificate:

      • Highest Serial Number: Reflects the highest actual serial number of any certificate issued by this CA. Since this example uses a serial number '0' for the CA's self-signed certificate, this field shows a value of 0.
      • Finger prints: Shows the SHA1 and MD5 fingerprints of the CA certificate.
      • Certificate Text: Shows the certificate in Base64 encoded format. This data is shown in Listing 1 and is also provided in the download materials in the ca-cert.txt file.
      Listing 1. Community Edition's CA certificate
      -----BEGIN CERTIFICATE-----
      MIICQjCCAa2gAwIBAgIBADALBgkqhkiG9w0BAQQwaTESMBAGA1UEAxMJQ0UgRGV2IENBMRcwFQYD
      VQQLEw5Tb2Z0d2FyZSBHcm91cDEMMAoGA1UEChMDSUJNMRIwEAYDVQQHEwlCYW5nYWxvcmUxCzAJ
      BgNVBAgTAktBMQswCQYDVQQGEwJJTjAeFw0wNzA5MzAxODMwMDBaFw0xNzA5MzAxODMwMDBaMGkx
      EjAQBgNVBAMTCUNFIERldiBDQTEXMBUGA1UECxMOU29mdHdhcmUgR3JvdXAxDDAKBgNVBAoTA0lC
      TTESMBAGA1UEBxMJQmFuZ2Fsb3JlMQswCQYDVQQIEwJLQTELMAkGA1UEBhMCSU4wgZ8wDQYJKoZI
      hvcNAQEBBQADgY0AMIGJAoGBAINePu4Rep4LBSlfdIQWBWtTY3N29N9H5rHDp9uurHjJI/k2EWvQ
      FDJRaWnH4zyJvULouWti24wCfrApQK8WUbhUut4u1OQL07bnEZiMHDmNs3hVqHWXSzVpNxlHx1rX
      VEyEaw/k4gnj0ku4Oam+GfsjuO75GzArfkN4vQ3HD55XAgMBAAEwCwYJKoZIhvcNAQEEA4GBAB2/
      B5L922wdKsawXpc8QBey9HIysc84p6FhPAbH1+729KwJMfAOnOGYz68XVsSfNV9aAps1VwCvaFOh
      6ERI7OVok79obzyDBeBYZ5h/cZzu5v4PWPHdnXiUGw4XCmvk29+rYSKHEW2cFlA99KKdK1eXhb5K
      zWBTzDA4ZGTmbSFZ
      -----END CERTIFICATE-----
  2. Setup CA certificate

    If you decide to get the Community Edition CA certified by another external CA, rather than use the self-signed certificate, you need to perform these steps:

    1. Generate a CSR for the Community Edition CA

      Recall that Community Edition's CA keypair is stored in a keystore called "ca-keystore." Using the Keystores portlet, unlock the keystore for editing/availability and generate a CSR for the key entry "cedevca," which is the alias you used at CA setup (see Figure 8). Copy the CSR text and send it to the external CA from which you intend to get a certificate for the Community Edition CA.

    2. Import the external CA's certificate as a trusted certificate

      Before importing the certificate issued by the external CA, you need to import the external CA's own certificate into ca-keystore as a trusted certificate. To do so, access the ca-keystore from the Keystores portlet and import the certificate using the Import Trusted Certificate function. This will enable signature verification when the CA's reply is imported later.

    3. Import the external CA's reply

      After the external CA issues a certificate, it sends a reply that will typically be a PKCS7 encoded certificate. To use the certificate with the Community Edition CA, import it into the ca-keystore by accessing ca-keystore from the Keystores portlet, and importing it using the Import CA Reply function while viewing the details for the cedevca key entry.

    4. Publish Community Edition's CA certificate

      Once the new certificate is imported into ca-keystore, you need to publish it to the certificate store used by the CA so that the CA Helper application can use the new certificate. To publish the CA's certificate, access the CA portlet and select Publish CA Certificate (Figure 5).

  3. Process CSRs submitted using the CA Helper application

    As mentioned earlier, once a CSR is received in a PKI, an RA validates the CSR to determine if the request satisfies the necessary criteria and, in turn, whether or not to issue a certificate in response. The criteria can be different for each PKI, but once the CSR is approved, the CA fulfils the request by issuing a certificate.

    The page in the CA portlet that lists all requests to be verified shows the CSRs that were submitted using the CA Helper application. Through this page, the RA can view the details of each CSR. Once approved, a CSR is automatically listed as a request to be fulfilled in the CA portlet. The CA can then access the CSRs to issue a certificate. (In this example, CA and RA are essentially the same entity.) The use of the pages to accomplish this will be discussed later.

  4. Issue certificate using CSR text

    You can use the Issue New Certificate function in the CA portlet to issue a certificate for a CSR sent to the CA from outside of the CA Helper application. For example, Listing 2 shows a CSR that was generated for the default key entry with an alias of "geronimo" in the default keystore "geronimo-default." (This data is also provided in the download materials in the geronimo-csr.txt file.)

    Listing 2. Default "geronimo" keypair CSR text
    -----BEGIN CERTIFICATE REQUEST-----
    MIIBvDCCASUCAQAwfjEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA
    4GA1UEBxMHVW5rbm93bjEaMBgGA1UEChMRQXBhY2hlIEZvdW5kYXRpb24xEDAOBgNVBAsT
    B1Vua25vd24xGDAWBgNVBAMTD0FwYWNoZSBHZXJvbmltbzCBnzANBgkqhkiG9w0BAQEFAA
    OBjQAwgYkCgYEA2CeZHvvrqO2sGqj6ULttIRnrT1ggYNMDl4qRYtRsdxXvNpBlbDBtHH7B
    97g9QZ1rJJcloSgQo3kOc+ErBsUP16fydvBpUegMtjc3aW60uSfL/r6tnBGoCsuVY/lf/x
    mfGL9ze0d/YzQ8x1eyfh/MbMIZCQpVyy11A7miaIsCKwMCAwEAATANBgkqhkiG9w0BAQQF
    AAOBgQAiO5SFK/sMlflSUq92610G2NGqG/YngCJ+LCwzbWRvniMRDCtVqC5fw25Ar1ufmr
    NpZNhhS0MlcHg8fjgtQFj4kR+QwM6mm57u/VHmDtvXd1M36jno5DQO811b9PmwTisCmgA2
    ZVKP/NIIN7d/mA2r1mQcE07nqFRxQhxrOMHojQ==
    -----END CERTIFICATE REQUEST-----

    To issue a new certificate for this CSR:

    1. Navigate to the CA portlet by selecting the Certificate Authority link under Console Navigation (Figure 1).
    2. If the Unlock CA link is visible (see Figure 6), click the link to unlock the CA using password cedevca, which was used earlier to set up the CA.
    3. Click Issue New Certificate. The panel shown in Figure 11 will display.
      Figure 11. Issue New Certificate - Step 1
      Figure 11. Issue New Certificate - Step 1
    4. Enter the CSR text into the text area and select Process CSR.

      Figure 12. Issue New Certificate - Step 2
      Figure 12. Issue New Certificate - Step 2
    5. Enter or select values for the fields shown in Figure 12:
      • Certificate Serial No: Automatically generated value, based on the current running serial number. (Recall the Highest Serial Number shown on the CA Details panel in Figure 10).
      • Valid From Date: Start date of certificate's validity.
      • Valid To Date: End date of certificate's validity.
      • Signature Algorithm: The signature algorithm to be used for signing the certificate; in this case, MD5withRSA.
    6. Select Review Client Cert Details to display data for the certificate about to be issued. Click your the browser's Back button to edit any fields, if necessary.
    7. Select Issue Certificate. A panel similar to Figure 13 will display.
      Figure 13. Certificate issued successfully
      Figure 13. Certificate issued successfully

    You have now issued a certificate in response to a CSR. The text area shows the Base64 encoded text of the certificate you issued. This data is shown in Listing 3, and also provided in the download materials in the geronimo-cert.txt file. This text is sent to the requestor as the CA's reply to the CSR (for this example, this text will be used later with the Keystores portlet).

    Listing 3. Community Edition CA's reply to CSR for default "geronimo" keypair
    -----BEGIN CERTIFICATE-----
    MIICQjCCAa2gAwIBAgIBADALBgkqhkiG9w0BAQQwaTESMBAGA1UEAxMJQ0UgRGV2IENBMRcwFQYD
    VQQLEw5Tb2Z0d2FyZSBHcm91cDEMMAoGA1UEChMDSUJNMRIwEAYDVQQHEwlCYW5nYWxvcmUxCzAJ
    BgNVBAgTAktBMQswCQYDVQQGEwJJTjAeFw0wNzA5MzAxODMwMDBaFw0xNzA5MzAxODMwMDBaMGkx
    EjAQBgNVBAMTCUNFIERldiBDQTEXMBUGA1UECxMOU29mdHdhcmUgR3JvdXAxDDAKBgNVBAoTA0lC
    TTESMBAGA1UEBxMJQmFuZ2Fsb3JlMQswCQYDVQQIEwJLQTELMAkGA1UEBhMCSU4wgZ8wDQYJKoZI
    hvcNAQEBBQADgY0AMIGJAoGBAINePu4Rep4LBSlfdIQWBWtTY3N29N9H5rHDp9uurHjJI/k2EWvQ
    FDJRaWnH4zyJvULouWti24wCfrApQK8WUbhUut4u1OQL07bnEZiMHDmNs3hVqHWXSzVpNxlHx1rX
    VEyEaw/k4gnj0ku4Oam+GfsjuO75GzArfkN4vQ3HD55XAgMBAAEwCwYJKoZIhvcNAQEEA4GBAB2/
    B5L922wdKsawXpc8QBey9HIysc84p6FhPAbH1+729KwJMfAOnOGYz68XVsSfNV9aAps1VwCvaFOh
    6ERI7OVok79obzyDBeBYZ5h/cZzu5v4PWPHdnXiUGw4XCmvk29+rYSKHEW2cFlA99KKdK1eXhb5K
    zWBTzDA4ZGTmbSFZ
    -----END CERTIFICATE-----
  5. View certificate issued

    The View Issued Certificate function enables the certificates issued by the CA to be searched by certificate serial number. To use this function, simply select View Issued Certificate in the CA portlet, then enter the certificate serial number and click View Certificate. If the serial number is valid, certificate details will display.

  6. Lock and unlock CA

    The Lock CA function locks the ca-keystore, thus preventing access to the CA functions discussed so far. Click Lock CA or Unlock CA in the CA portlet (Figure 6) to perform either action. To complete the unlock function, you will need to provide the password used at CA setup time and click Unlock Certification Authority. Once the ca-keystore is unlocked, you will be able to access the CA functions.

Client digital certificates

The method used for submitting CSRs will depend on the user; a Community Edition administrator with access to CA functionality will use the CA portlet described above, whereas a typical user who wants to request a certificate from the Community Edition CA will use the CA Helper application through a Web browser. In this section, you will see how to submit CSRs using the CA Helper application from a Web browser that supports the KEYGEN tag. Mozilla Firefox is used in this example.

Browsers and KEYGEN
The KEYGEN tag is not supported by Internet Explorer. Support for submitting CSRs through Internet Explorer will be available in a forthcoming version of the CA Helper application.

To submit a CSR using the CA Helper application:

  1. Install CA certificate into Web browser

    The first step toward using a certificate issued by any CA is to designate that CA as a trusted third party. You do this by installing the CA's certificate into your Web browser -- or any other software that deals with certificates. To install the CA's certificate in your browser:

    1. Open a browser window and access the CA Helper application.
    2. Select Download CA's Certificate (see Figure 7) to display a page with the CA certificate details.
    3. Select Download CA's Certificate. The browser will open a dialog that enables you to add the CA's certificate as a trusted Certification Authority (Figure 14). Most browsers will provide an option to view the certificate details.
      Figure 14. Firefox - Downloading certificate
      Figure 14. Firefox - Downloading certificate
    4. Click View to examine the certificate. The CA common name should appear as "CE Dev CA."
    5. Enable the option to Trust the CA to identify web sites and click OK. The CA's certificate has now been imported into the Web browser as a trusted certificate.
    6. To check if the CA has been added, select (in Firefox) Tools => Options. Select the Advanced tab and click on View Certificates. This will display the Certificate Manager dialog (Figure 15).
    7. Select the Authorities tab and scroll down to IBM to see the Community Edition CA listed. Select View to see the certificate details.
      Figure 15. Firefox - Certificate Manager
      Figure 15. Firefox - Certificate Manager
  2. Request a certificate using a Web browser

    To request a certificate, you need to generate a keypair using cryptography software. Web browsers that support the KEYGEN form tag eliminate the need for external software to generate a keypair. When a form containing the KEYGEN tag is submitted by the Web browser, the browser generates a keypair, stores the private key locally, creates a SignedPublicKeyAndChallenge (SPKAC) containing the public key, and submits it along with the other form data. The CA can extract the public key from this SPKAC and issue a certificate containing the identity information that was received separately.

    To submit a certificate request from the web browser:

    1. Access the CA Helper application at http://localhost:8080/CAHelper.
    2. Select Request Certificate. A panel similar to Figure 16 will display.
      Figure 16. Request Certificate - Step 1
      Figure 16. Request Certificate - Step 1
    3. Enter values for these fields representative of the requestor's identity:
      • Common Name (CN): Web Client
      • Division/Business Unit (OU):Software Group
      • Company/Organization (O): IBM
      • City/Locality (L):Bangalore
      • State/Province (ST): KA
      • Country Code (2 char) (C):IN
      • Challenge Phrase: secret
      • Confirm Challenge: secret
    4. Click Review Name Details. A panel similar to Figure 17 displays so you can review the name details you entered before submitting the request.
      Figure 17. Request Certificate - Step 2
      Figure 17. Request Certificate - Step 2
    5. For Key Size, select 1024 (Medium Grade) (or any other value if one is more applicable to you) and click Submit Certificate Request.

    The certificate request submission process is complete. The CSR Confirmation page displas with a CSR Id, as shown in Figure 18.

    Figure 18. CSR Confirmation
    Figure 18. CSR Confirmation

    Once the CSR is fulfilled by the CA, you will need to download the certificate using the same CSR Id. The challenge phrase should be kept private, in case it needs to be used for revoking a certificate. As mentioned earlier, CAs periodically publish CRLs with the serial numbers of revoked certificates.

  3. Approve the CSRs

    The "Certificate Requests awaiting verification" panel in the CA portlet lists the CSRs submitted through the CA Helper application. To approve or reject any CSRs:

    1. Access the CA portlet and unlock the CA, if necessary.
    2. Select Requests to be verified. A panel listing all CSRs awaiting verification will display (Figure 19).
      Figure 19. CSRs to be verified
      Figure 19. CSRs to be verified
    3. Click on the CSR Id of the CSR to approve or reject. A panel with details of the CSR will display (Figure 20).
      Figure 20. Confirm Certificate Request
      Figure 20. Confirm Certificate Request
    4. Click on either Approve CSR or Reject CSR. If a CSR is approved, the CSR Id will display in "Certificate Requests awaiting fulfillment." A rejected CSR is deleted from the Certificate Request Store used by the CA.
  4. Fulfill approved CSRs

    The Certificate Requests awaiting fulfillment panel in the CA portlet enables you to fulfill a CSR by issuing a certificate. The approved CSRs are listed on this panel by CSRs Id. To fulfill a CSR:

    1. Access the CA portlet and unlock the CA, if necessary.
    2. Click Requests to be fulfilled. The Certificate Requests awaiting fulfillment panel displays (Figure 21), showing the CSR Ids that have been approved and are awaiting fulfillment.
      Figure 21. CSRs to be fulfilled
      Figure 21. CSRs to be fulfilled
    3. Click on the CSR Id to be fulfilled.
      Figure 22. Certificate details
      Figure 22. Certificate details
    4. On the Certificate Requestor Details panel (Figure 22), enter or select the following values:
      • Valid From Date:10/01/2007
      • Valid To Date:10/01/2008
      • Signature Algorithm:MD5withRSA

      The Certificate Serial No. field is automatically populated. Client certificates are typically issued with a validity period of one year, however, the CA may have its own constraints on the validity period.

    5. Click Review Client Cert Details to display the certificate details before issuing a certificate.
    6. Click Issue Certificate to complete the process. Figure 23 shows a panel with the details of the certificate that is issued.
      Figure 23. Certificate issued successfully
      Figure 23. Certificate issued successfully

    You have now fulfilled a CSR by issuing a certificate. The requestor can now download and install the certificate into the Web browser using the CSR Id provided on the CSR confirmation page.

  5. Install certificate into Web browser

    Once a CSR has been fulfilled, the CA typically either sends the issued certificate to the requestor or informs the requestor to download the certificate from CA's Web site. In this case, the CA Helper application serves as the CA's Web site from which users can download their personal certificates. Be aware that you will only be able to install the issued certificate into the Web browser that you used for submitting the CSR.

    To download and install your personal certificate:

    1. Open the CA Helper application at http://localhost:8080/CAHelper from the same Web browser you used to request the certificate.
    2. Select Download your Certificate (Figure 7) to display the panel shown in Figure 24.
      Figure 24. Download Certificate
      Figure 24. Download Certificate
    3. Enter the CSR id you received and click Download Certificate. The certificate has been installed into the Web browser. The browser will typically display a message indicating that the certificate has been installed. Firefox displays a message similar to "Your personal certificate has been installed."
    4. The next page should display a message that says "Certificate is downloaded successfully," along with a link to verify the certificate details, if an HTTPS connector is enabled for client authentication and configured in Community Edition.
  6. Verify the client certificate is installed in the browser

    You can examine the downloaded certificate details with the Certificate Management functions provided by the Web browser. (For example, Firefox provides Certificate Management functions under Options => Advanced.) To verify the certificate is installed in the browser, follow the steps described in step 1. The certificate entry will be listed in the Your Certificates tab.

Using a client certificate with Community Edition

To use certificates for client authentication, you need to create an HTTPS Connector configured with clientAuth. The general steps to do this are:

  1. Prepare the keystore

    The keystore is the file in which the server's certificate and keypair are stored. Community Edition is shipped with a keystore named "geronimo-default" that contains a default keypair and self-signed certificate with alias "geronimo." The same keypair is shared by all Community Edition installations and so the private key in the default keypair is, in fact, not private at all. The default keypair is provided only to enable the startup of the default HTTPS connector. After installing Community Edition, you should delete the default keypair and generate a new keypair. You can then generate a CSR for the newly created keypair and use it with the Issue New Certificate function of the Community Edition CA to issue a certificate. Since you used the CSR (Listing 2) from the default keypair that is shipped with Community Edition to issue a certificate (Listing 3), you can use the same keypair for this exercise. To import the certificate into the geronimo-default keystore:

    1. Access the Keystores portlet from the administrative console.
    2. Unlock the geronimo-default keystore for editing, using the password "secret," if necessary.
    3. Open the geronimo-default keystore for editing by clicking on the link in the Keystores portlet.
    4. Using the Add Trust Certificate link, import Community Edition's CA certificate (Listing 1) as a trusted certificate.
    5. View the contents of the geronimo private key entry by clicking on the corresponding View link.
    6. Click Import CA Reply.
    7. Paste the contents of Listing 3 into PKCS7 Certificate Reply field and click the Save button.

    The certificate has now been imported into the geronimo-default keystore. Notice that "CE Dev CA" is shown as the issuer. This certificate will be used by Community Edition to authenticate itself to any users accessing the server using HTTPS, typically referred to as HTTPS server authentication.

  2. Prepare the truststore

    A truststore is the file in which a CA's certificates are stored. You can use the same file as both keystore and truststore, although it is preferred that you use a different file for truststore containing only trusted certificate entries. To prepare a truststore:

    1. Create a new keystore.
    2. Import the CA's certificate as a trusted certificate.

    If there is more than one CA that you want to designate as trusted, repeat the import step with each CA's certificate. When the truststore is used with an HTTPS connector that is configured for clientAuth, the connector will recognize the certificates issued by any of the CAs in the truststore. In this example, the geronimo-default keystore is also used for truststore. Recall that you have already imported Community Edition's CA certificate as a trusted certificate.

  3. Create an HTTPS connector with clientAuth

    Once you have prepared the keystore and truststore, you can use the Web Server portlet to create an HTTPS connector configured for clientAuth when the server is running; if the server is stopped, you can add an HTTPS connector gbean to the config.xml file, located under <WASCE_HOME>/var/config. Make sure to stop the server before changing config.xml. (Any changes made to config.xml while the server is running will not take effect until the server is restarted and will be lost when the server is stopped.) In this example, you will add a new HTTPS connector by adding a gbean to config.xml:

    1. Add the XML code fragment shown in Listing 4 inside the module tag with name "org.apache.geronimo.configs/tomcat6/2.0.1/car" in config.xml. (The value for the gbean name attribute in the listing is split across multiple lines for the purpose of display only and should be in a single line without spaces when added to config.xml.) The same XML code is available in the https-connector-gbean.xml file provided in the download material.
      Listing 4. HTTPS connector gbean
      <gbean name="org.apache.geronimo.configs/tomcat6/2.0.1/car?
      ServiceModule=org.apache.geronimo.configs/tomcat6/2.0.1/car,
      j2eeType=GBean,name=TomcatWebSSLClientAuthConnector"
      gbeanInfo="org.apache.geronimo.tomcat.connector.Https11ConnectorGBean">
        <attribute name="name">HTTPS</attribute>
        <attribute name="host">0.0.0.0</attribute>
        <attribute name="port">443</attribute>
        <attribute name="maxHttpHeaderSize">8192</attribute>
        <attribute name="maxThreads">150</attribute>
        <attribute name="minSpareThreads">25</attribute>
        <attribute name="maxSpareThreads">75</attribute>
        <attribute name="enableLookups">false</attribute>
        <attribute name="acceptCount">100</attribute>
        <attribute name="disableUploadTimeout">false</attribute>
        <attribute name="clientAuth">true</attribute>
        <attribute name="algorithm">Default</attribute>
        <attribute name="sslProtocol">TLS</attribute>
        <attribute name="keystoreFile">var/security/keystores/geronimo-default</attribute>
        <attribute name="keystorePass">secret</attribute>
        <attribute name="truststoreFile">var/security/keystores/geronimo-default</attribute>
        <attribute name="truststorePass">secret</attribute>
        <reference name="TomcatContainer">
          <pattern>
            <name>TomcatWebContainer</name>
          </pattern>
        </reference>
        <reference name="ServerInfo">
          <pattern>
            <name>ServerInfo</name>
          </pattern>
        </reference>
      </gbean>

      When the server is started, a new HTTPS connector named TomcatWebSSLClientAuthConnector will be added on port 443 to the Web container named TomcatWebContainer. Important attributes to observe here are:

      • clientAuth is set to true.
      • keystoreFile and keystorePass correspond to the keystore.
      • truststoreFile and truststorePass correspond to the truststore.
      • keystoreFile and truststoreFile values are the file location relative to <WASCE_HOME>.

      Notice that the same file is used for both keystore and truststore. The truststore related attributes are necessary only when clientAuth is set to true.

  4. Once the server is started, access the page in the CA Helper application to verify a certificate page: https://localhost:443/CAHelper/verifyCertificate.jsp.
  5. Select the desired certificate when prompted to select a certificate for authenticating. The application loads and displays the details of the certificate you have selected for authentication.

See Resources for more information.

Conclusion

In this article, you set up a public key infrastructure using WebSphere Application Server Community Edition V2.0. You learned how to issue a certificate to be used for server authentication and configured Community Edition for client authentication using certificates. You also saw how the process was completed end to end, from a user submitting a CSR to receiving a certificate and using that certificate to authenticate to the Community Edition server.


Download

DescriptionNameSize
Code samplepublickey_samples.zip7 KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=264170
ArticleTitle=Set up a public key infrastructure with WebSphere Application Server Community Edition V2.0
publish-date=10242007