Creating a Signing Key Pair

There are a number of ways to get a key pair into an eDirectory system:

• Use Novell^® Certificate Server^TM to generate the key pair and certificate, signed by your Tree CA
• Use Novell Certificate Server to generate the key pair and certificate signing request to be signed by an external CA
• Use Novell Certificate Server to import an external key pair stored in PKCS#12 format

The following instructions show how to generate a key pair using Novell Certificate Server and the Novell Certificate Server snap-ins. For more detailed information on key and certificate management, Novell Certificate Server 2.7.x Administration Guide.

1. Create a NDSPKI:Key Material object.

   This is the what the Novell Certificate Server calls a public / private Key Pair object. Novell Certificate Server stores and associates Key Pair objects with servers, so you must create the Key Material object in the same container as the server you want to use to host the key. For these purposes, the server you choose to use is immaterial. Figure 60 shows how a Key Material object is created:

   Figure 60
   Creating the Key Material Object
   

2. Select the Key Material object, then click OK.

   A wizard is launched to guide you through thee certificate generation process, as shown in Figure 61.

   Figure 61
   Certificate Generation Wizard
   

3. Select the server where you want to create the private key.

   The Creation Method selection determines what type of operation you are going to perform.

4. If you already have a certificate you want to use, select Import. Otherwise, select Custom.

   If you choose the Import option, you are prompted to enter the file name and password associated with the PKCS#12 file you want to import. (This is a relatively straightforward operation; see the Novell Certificate Server documentation for details on importing external certificates.)

5. Click Next.

6. You are prompted about whether you want to create a public key certificate signed by your Tree's Certificate Authority (CA) or an external CA, as shown in Figure 62:

   Figure 62
   Specify the CA
   

   Typically, if you are creating a certificate for testing, you can use your built-in Organizational Certificate Authority. For production, you will probably want a certificate signed by a well-known CA, such as Verisign* or Entrust*. If you want to select an external CA, select External Certificate Authority.

7. Click Next.

8. Define the key pair properties. Bacause this certificate is to be used to sign SAML data, make sure Signature is selected, as shown in Figure 63:

   Figure 63
   Define Key Pair Properties
   

   Typically, a key size of 2048 bits is sufficient.

9. Click Next.

10. Define additional key and certificate properties.

    Make sure you create a subject name that allows your partner sites to identify the certificate as yours. A general rule is to make the subject name the same as your Site ID. In this example, a certificate is being generated for the iChainSite sample site, so the Subject name is .CN=www.ichainsite.com. Subject names in the Novell Certificate Server must begin with a period (.) character, as shown in Figure 64:

    Figure 64
    Define Additional Key and Certificate Properties
    

11. Click Next.

12. Finish this operation: If you are signing the certificate with your Tree CA (Organizational), you are prompted to select either Your Organization's Certificate or the Novell Root Certificate's certificate that will sign your certificate.

    Figure 65
    Specify the Trusted Root Certificate
    

    Either certificate works for testing purposes. For information about the differences between the two, refer to the Novell Certificate Server 2.7.x Administration Guide.

13. Click Next.

    You are presented with a summary page that outlines all of the selections you made using the wizard. Verify that your selections are correct, then click Finish.

    Figure 66
    Summary of Your Selections
    

    The key pair is generated.

    You should see a new NDSPKI: Key Material object in the directory. The name of this new object is the name you specified in the wizard, followed by the hosting server name. Figure 67 shows the key pair generated in this example. The certificate name is mysig_keypair - Dutton.

    Figure 67
    Key Pair
    

    You can associate your SAML configuration object with the key pair you just created. Although this is not required, we recommend it because it keeps the association between the key pair you generated and the SAML configuration.

14. To create this association, right-click the SAML configuration object, then click Properties, as shown in Figure 68:

    Figure 68
    SAML Configuration Object: Properties
    

    If you create this association, when you are working with the configuration of the SAML system, you now have a link back to the key pair you're using to sign SAML data, as shown in Figure 69:

    Figure 69
    Key Pair Link
    

15. Continue with Exporting a Signing Key Pair.

Exporting a Signing Key Pair

You must now export the key pair you just created to a disk to store on the SAML extension server:

1. In ConsoleOne, double-click or right-click the Key Pair object, then select Properties.

   The key pair's Properties page is displayed, as shown in Figure 70:

   Figure 70
   Key Pair Properties
   

2. Click the Certificates page.

3. Select Public Key on the drop-down menu.

   A Properties page is displayed, as shown in Figure 71:

   Figure 71
   Public Key Properties
   

4. Verify that the subject name, effective date, and expiration date match the values you entered during the certificate creation process.

5. Click Export.

   This exports the key pair. A wizard page is displayed, as shown in Figure 72:

   Figure 72
   Key Pair Export Wizard
   

   If you want to export only the public key certificate, select No. In this example, because you are exporting the public - private key pair, Yes is selected.

   Selecting Yes exports the public and private keys in password-protected PKCS#12 format. This is what you must move to the SAML extension server.

   Selecting No exports the public key only. This is what you must provide to your partner sites later.

6. Select Next. The Export Certificate Wizard is displayed, as shown in Figure 73:

   Figure 73
   Export Certificate Wizard
   

7. Specify a filename and password.

   The filename can be whatever you desire. Take note of the password you enter. It is required later as part of the SAML extension server setup.

8. Click Next.

   Continue with Setting the PKCS#12 Signature Key on the SAML Extension Server for information on importing the file into the SAML extension server.

Setting the PKCS#12 Signature Key on the SAML Extension Server

To import the Signature Key file into the SAML extension server:

1. Copy the PKCS#12 file exported in the previous process to the local drive of the SAML extension server.

2. Modify the SAML extension server configuration file to point to the PKCS#12 file.

3. Restart Tomcat.

When you installed SAML extension, a configuration file was automatically generated. This file is located at samlext_home/conf/samlextConfig.xml. (For example, this path could be C:\Program Files\Apache Group\Tomcat 4.1\webapps\samlext\conf\samlextConfig.xml.) If you did not specify any key pairs during the installation, the configuration file should look like the one shown in Figure 74:

Modify the signature keypair element with usage signing to include the file name and password of the PKCS#12. In the example, the file would be modified to read as shown in Figure 75:

This example assumes that the exported PKCS#12 file was copied to the SAML extension server as c:\mysig_keypair.pfx, using novell as the password.

Modifying the SAML Settings in the Directory

Although you have created and imported the key pair, it is only used if it is required by the SAML configuration stored in the directory. The signing of SAML data is a setting made on a per-affiliate basis. This means that the SAML administrator can decide which SAML partner sites receive signed data and which do not. The following steps show how signing is turned on for the eMartian affiliate:

1. In ConsoleOne, select the Trusted Affiliate object you want to sign data for.

   In this example, data that is intended for the eMartian affiliate is signed.

2. Open the Trusted Affiliate object's property page by right-clicking the object and selecting Properties, as shown in Figure 76:

   Figure 76
   Trusted Affiliate Properties
   

3. Click the Assertions page.

   Figure 77
   eMartian Properties: Assertions Page
   

4. Select Digitally Sign Assertions for the Browser/POST Profile.

   This causes the system to use your key pair to sign SAML data sent to the eMartian Trusted Affiliate using the browser/POST file.

5. Click OK.

   Continue with Exporting the Public Key Certificate.

Exporting the Public Key Certificate

Now that you are signing the SAML data, you need to provide your SAML partner site with a way of validating the signatures you generate. You do this by providing the partner with your public key certificate which the partner can import into its system and use to validate the signatures you generate.

To export the public key certificate:

1. In ConsoleOne, open the Properties page associated with the key pair you are using to generate your digital signatures (the same as you did when you exported the key pair in PKCS#12 format).

2. Click the Certificates page, then select public key certificate. (This is also the same as you did when you exported the key pair in PKCS#12 format.).

3. Click Export.

   The Export Certificates Wizard is displayed:

   Figure 78
   Export Certificate Wizard
   

4. Select No. You should only export the public key portion of the pair.

5. Click Next.

6. Select the file name and format to save the file as.

   The most common file format is binary DER encoding.

   Figure 79
   Output Format: Binary DER Format
   

7. Click Next.

8. Click Finish.

Next, you should send the public key certificate to your partner sites that want signed data. The partner sites would then import the certificate so that they could validate your signatures.

Continue with Importing Public Key Certificates.

Importing Public Key Certificates

This section is presented from the point of view of the SAML administrator of eMartian. At this point you have received a public key certificate from www.ichainsite.com that you can use to validate signatures generated by that site. You must now import this public key certificate into your system and associate it with the Trusted Affiliate object representing www.ichainsite.com. The following steps show how to import a public key certificate into eDirectory and then associate the certificate with the Trusted Affiliate object representing www.ichainsite.com.

In Novell eDirectory, trusted public key certificates must be placed in a Trusted Roots container. If you do not already have one you will need to create this container. Typically, the Trusted Roots container is created under the [ROOT].security container.

1. In ConsoleOne, right-click the security container, then click New > Object.

2. Select NDSPKI:Trusted Root as shown in Figure 80:

   Figure 80
   NDSPKI Trusted Root
   

   When the Trusted Roots container has been created, you can add a new Trusted Root public key certificate to it.

3. Right-click the Trusted Roots container, then click New > Trusted Root.

   Figure 81
   New Trusted Root
   

4. Click OK.

   The Create Trusted Root Wizard launches.

5. Specify the NDS Object name for the trusted root. In Figure 82, ichainsite_signature has been entered as the name.

   Figure 82
   Trusted Root Name
   

6. Click Finish.

   This completes the trusted root import. You should now have a new object in the Trusted Roots container.

   Next, you need to associate this object with your Trusted Affiliate entry for www.ichainsite.com.

7. Right-click the iChainSite Trusted Affiliate object, then select Properties.

   Figure 83
   iChainSite Trusted Affiliate Object Properties
   

8. Click the General page, then select the plus sign (+) under the SAML Signature section.

9. Browse to the Trusted Roots container and select the desired trusted root object.

   Figure 84 shows the www.ichainsite.com Properties page with the trusted root reference set:

   Figure 84
   iChainSite Properties: Trusted Root Reference Set
   

   Creating this setting allows the SAML system to validate data signed by www.ichainsite.com.

10. Click OK.

11. Verify that signature validation occurs by clicking the Assertions page and selecting the Require Digitally Signed Messages for Browser/POST Profile option, as shown in Figure 85:

    Figure 85
    iChainSite Properties: Assertions Page
    

    Choosing this setting ensures that all SAML messages sent from www.ichainsite.com to eMartian using the browser/POST profile must be signed and validated or they are not be accepted.

Configuring SAML to Support SSL Mutual Authentication

Use the following procedure to configure the SAML system to support SSL Mutual authentication over the SAML back-channel:

1. Generate an SSL key pair (SKP) or import it into the system and store it in eDirectory. See Generating the SSL Key Pair.
2. Export the SKP from eDirectory in PKCS#12 format and store it on the SAML extension server. See Exporting the SSL Key.
3. Use the SKP as the SSL key pair on the appropriate iChain accelerator. See Importing the SSL Key Into iChain.
4. Import the SKP into the SAML extension server. See Importing and Configuring the SAML Extension Server to Use the SSL Certificate.
5. Export the public key certificate associated with the SKP and send it to the Trusted Affiliate. See Exporting the iChain Server SSL Public Key Certificate.
6. Import the partner's SSL public key certificate (the one it sends to you) into your trust store. See Importing the Partner's SSL Public Key Certificate.
7. Configure the appropriate settings on the Trusted Affiliate that will be communicating with your site over SSL-M. See Importing the Partner's SSL Public Key Certificate.

Generating the SSL Key Pair

You can use the Novell Certificate Server snap-ins to generate your SSL key pair. If you choose to do this, the steps required are nearly identical to those followed to generate the data signing key. The only difference is on the Create Server Certificate page, rather than selecting the Signature option as you did when you were generating the signature key pair, you should select the SSL or TLS option as shown in Figure 86:

Figure 86
Create Server Certificate (Key Material)

Importing the Partner's SSL Public Key Certificate

In order to create mutually authenticated SSL connections, the following two conditions must be in place:

• Your partners must validate and trust your server certificate.
• You must trust your partners' server certificates.

Thus, just as you sent your SAML partner site your SSL public key certificate, you must receive from your SAML partner sites their SSL public key certificates and import them into your system's trust store.

It is assumed that your partner site, eMartian, has generated an SSL key pair and sent you (iChainSite) its SSL public key certificate.

1. Connect to the eMartian site accelerator using Internet Explorer.

2. Double-click the lock in the lower right-hand corner, then click the Certification Path page.

3. Select the CA (the top item).

4. Click View Certificate, then click the Details page.

5. Select Copy to File.

6. Select Base-64, then click Next.

7. Name the file eMartian.b64, then save it.

You import eMartian's SSL certificate into your Trusted Root container and associate it with the eMartian Trusted Affiliate object.

NOTE:  Each iChainServiceObject can associate with a Trusted Root container. You must verify that the SSL trusted roots that you use are imported into this container. Otherwise, SSL connections do not work through iChain. The Trusted Root container associated with the iChainServiceObject can be determined by opening the iChainServiceObject's Properties page and selecting the General page, as shown in Figure 91:

Figure 91
iChainServiceObject Properties Page

If you haven't set the the value, you can set it by selecting the Browse button on the right. If no Trusted Root container has been created, follow the steps outlined in Importing Public Key Certificates to create one.

After setting this Trusted Root container name attribute in the iChainServiceObject, browse to the container and import the eMartian.b64 certificate. The certificate can be imported by following the steps outlined in Importing Public Key Certificates.

After importing the certificate into the appropriate Trusted Root container, you must configure the SAML extension server to use it. In this example, you are administering iChainSite and are receiving a certificate from eMartian, so you would select the Trusted Affiliate object associated with eMartian as shown in Figure 92:

Figure 92
eMartian Trusted Affiliate Object

To configure the SAML extension server to use the certificate:

1. Right-click the object, then select Properties.

2. Select the General page, then click the plus sign (+) associated with the Secure SAML Communication group.

3. Select the SSL certificate associated with this Trusted Affiliate. In this example, the certificate is the eMartian SSL public key certificate, as shown in Figure 93:

   Figure 93
   eMartian SSL Public Key Certificate
   

4. Click OK.

5. Go to the eMartian site and import the ichainsite.b64 you saved earlier.

Modifying the SAML SOAP Endpoint URL

After you are set up for SSL, you can modify the SOAP endpoint associated with the eMartian affiliate to make use of this new security. There are two separate ways of accessing the SAML back-channel:

• Through the /cmd/ext URL switch. This extension can handle clear text and server side SSL. :
• Through the /cmd/mutExt URL switch. This runs only SSL-M. If you modify the SOAP endpoint of the eMartian site to include the /cmd/mutExt switch rather than the /cmd/ext switch, SSL-M is used. This setting is made at the URLs page. Figure 94 shows this setting.

Figure 94
Modifying the SOAP Endpoint for eMartian

The SOAP Responder URL now contains /cmd/mutExt rather than /cmd/ext. You can require that affiliates communicating with you over the SAML back-channel use SSL-M. This setting is made on the Assertions page. Figure 95 shows this setting:

Figure 95
eMartian Properties: Require Client Authentication

With the Require Client Authentication for Secure SAML Communication setting enabled, only connections with SSL-M with a certificate matching that are in the Secure SAML Communication field are accepted.