i-Planet Administration Guide

SSL Service

SSL service is used for encrypted communication between the end user and the i-Planet gateway. You can use the self-signed certificate that you created during installation or you can create a certificate signing request, obtain a signed certificate from a Certificate Authority, and add it to the rp.keystore file (the certificate database) on the i-Planet gateway.

Using SSL service between the i-Planet server and the i-Planet gateway provides greater security for the information that must flow between them. SSL service requires an SSL certificate.

SSL Certificates for the i-Planet Gateway

The SSL certificates, either self-signed or from a certificate vendor, who provides authority (CA) services, are used for secure communication over the Internet with the end user. SSL certificates provide a way to authenticate users. When you installed the i-Planet software, you automatically created a self-signed SSL certificate. In creating this certificate, you entered specific information about your organization, such as company name and address, and a passphrase. This information is used in creating a certificate.

If you want to use an SSL certificate that is signed by a certificate vendor after you have installed the i-Planet software, you must run the certadmin script to generate an SSL certificate signing request CSR). The CSR is used to get an SSL certificate from a vendor.

Self-Signed SSL Certificate on the i-Planet Gateway

When you installed the i-Planet software, you created and installed a self-signed SSL certificate. At some point after installation, you might want to generate a new self-signed certificate; you might want to change the information for the certificate you entered during the original installation, for example.

To Generate a Self-Signed SSL Certificate for the i-Planet Gateway

As root, run the certadmin script on the i-Planet gateway:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 1 on the Certificate Administration menu to generate a self-signed certificate.

The Certificate Administration script prompts you to enter specific information about your organization and a passphrase for the self-signed certificate:

What is the fully qualified DNS name of this host? [hostname.domainname]
What is the name of your organization? []
What is the name of your organizational unit? []
What is the name of your City or Locality? []
What is the name of your State or Province? []
What is the two-letter country code for this unit? []
...
Enter passphrase []

Enter the information for your organization and a passphrase for the self-signed certificate.

A self-signed certificate is generated and added to the file /etc/opt/SUNWstnr/rp.keystore on the i-Planet gateway. Your prompt returns.

Stop and restart the reverse proxy server on the i-Planet gateway for the certificate to take effect.

See the procedure "To Stop and Restart the Reverse Proxy Server on the i-Planet Gateway" in Chapter 3, Other Administrative Tasks.

Make a backup copy of the rp.keystore file.

SSL Certificates From Vendors

During i-Planet software installation, you created and installed a self-signed SSL certificate. At some point after installation, you have the option to install SSL certificates signed by vendors who provide official certificate authority (CA) services.

i-Planet software contains root certificates that can be used with SSL certificates from Verisign, Inc. If you decide to install an SSL certificate from a vendor other than Verisign, you must install a root certificate from that vendor first, and then install the web server certificate.

Certificates are stored in the rp.keystore file. Once you generate a certificate signing request (used to request a certificate from a third-party vendor), make sure you keep a backup copy of the rp.keystore file. This file contains your private key, which is associated with the certificate that you purchase; if you lose the file, you will not be able to use the certificate that you bought.

To Install SSL Certificates From Verisign

As root, run the certadmin script on the i-Planet gateway.

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 2 on the Certificate Administration menu to generate a certificate signing request (CSR).

The information from your current self-signed certificate is displayed. You are asked if this information is correct.

If no self-signed certificate exists on this machine, the Certificate Administration script notifies you that you must create one. Refer to the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Gateway" earlier in this chapter.
If a self-signed certificate exists on this machine, the information from the certificate is displayed. The Certificate Administration script asks the question:
Is this information correct (y/n)? [n]

Enter y if the information is correct, or enter n if it is not correct.

If you enter n, you are asked to enter information for a new self-signed certificate. See the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Gateway" in this chapter.

If you enter y, you are asked to enter some contact information for the webmaster of the machine for which the certificate is being generated:

What is the name of the admin/webmaster for this server? []
What is the email address of the admin/webmaster for this server? []
What is the phone number of the admin/webmaster for this server? []

Enter the name, the email address, and the telephone number of the administrator or webmaster for this server.

The Certificate Administration script displays the values you enter and asks the question:
Are these values correct (y/n)? [n]

Enter y if the information is correct, or enter n if it is not correct.
- If you enter y, the CSR is generated and stored in the file /tmp/csr.hostname.
- If you enter n, the Certificate Administration script asks you to enter the values again.

Go to the certificate authority's website and order your web server certificate.
1. Provide information from your CSR, as requested by the CA.
2. Provide any other information as requested by the CA, such as a passphrase.
3. Specify your web server type as: Java Webserver.
  
  Specifying Java Webserver means that you want your certificate in privacy enhanced mail (PEM) format.

After you receive your certificate from the CA, save it in a file.

The certificate begins with a line that reads:
```
-----BEGIN CERTIFICATE----
```
continues with the certificate itself, and ends with a line that reads:
```
-----END CERTIFICATE-----
```
Make sure you include both of these lines with the certificate in the file.

As root, run the certadmin script on the i-Planet gateway:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 4 on the Certificate Administration menu to install your certificate from the CA.

The Certificate Administration script asks the question:
What is the name (including path) of the file that contains the certificate? []

Enter the full path to the file containing the certificate from the CA.

Your certificate is stored in the file /etc/opt/SUNWstnr/rp.keystore and your prompt returns.

Stop and restart the reverse proxy server on the i-Planet gateway for the certificate to take effect.

See the procedure "To Stop and Restart the Reverse Proxy Server on the i-Planet Gateway" in Chapter 3, Other Administrative Tasks.

Make a backup copy of the rp.keystore file for the i-Planet gateway.

To Install SSL Root Certificates and SSL Certificates From Other Vendors

You must have already generated a self-signed certificate to install a root certificate. See the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Gateway" in this chapter.

Go to the Certificate Authority's website and download its root certificate.

The website should contain instructions for downloading the certificate, usually as a file.

As root, run the certadmin script on the i-Planet gateway:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 3 on the Certificate Administration menu to add a root certificate from the CA.

The Certificate Administration script asks the question:
What is the name (including path) of the file that contains the root certificate that you would like to add to your database? []
1. Enter the full path to the file containing the root certificate.
  
  The file is displayed and the Certificate Administration script asks the question:
  Is this information correct (y/n)? [n]
2. Enter y if the file is correct, or n if it is not.
  - If you enter y, the root certificate is stored the /etc/opt/SUNWstnr/rp.CAstore file and your prompt returns.
  - If you enter n, the root certificate is not added and your prompt returns.

As root, run the certadmin script on the i-Planet gateway.
# /opt/SUNWsnrp/bin/certadmin

Enter 2 on the Certificate Administration menu to generate a certificate signing request (CSR).

If no self-signed certificate exists on this machine, the Certificate Administration script notifies you that you must create one. Refer to the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Gateway" earlier in this chapter.
If a self-signed certificate exists on this machine, the information from the certificate is displayed. The Certificate Administration script asks the question:
Is this information correct (y/n)? [n]

Enter y if the information is correct, or enter n if it is not correct.

If you enter n, you are asked to enter information for a new self-signed certificate. See the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Gateway" in this chapter.

If you enter y, you are asked to enter some contact information for the webmaster of the machine for which the certificate is being generated:

What is the name of the admin/webmaster for this server? []
What is the email address of the admin/webmaster for this server? []
What is the phone number of the admin/webmaster for this server? []

Enter the name, the email address, and the telephone number of the administrator or webmaster for this server.

The Certificate Administration script displays the values you enter and asks the question:
Are these values correct (y/n)? [n]

Enter y if the information is correct, or enter n if it is not correct.
- If you enter y, the CSR is generated and stored in the file /tmp/csr.hostname.
- If you enter n, the Certificate Administration script asks you to enter the information again.

Return to the Certificate Authority's website and order your web server certificate.
1. Provide information from your CSR, as requested by the CA.
2. Provide other information as requested by the CA, such as a passphrase.
3. Specify your web server type as: Java Webserver.
  
  Specifying Java Webserver means that you want your certificate in privacy enhanced mail (PEM) format.

After you receive your certificate from the CA, save it in a file.

The certificate begins with a line that reads:
```
-----BEGIN CERTIFICATE----
```
continues with the certificate itself, and ends with a line that reads:
```
-----END CERTIFICATE-----
```
Make sure you include both of these lines with the certificate in the file.

As root, run the certadmin script on the i-Planet gateway:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 4 on the Certificate Administration menu to install the certificate from the CA.

The Certificate Administration script asks the question:
What is the name (including path) of the file that contains the certificate? []

Enter the full path to the file containing the certificate.

Your certificate is added to the /etc/opt/SUNWstnr/rp.keystore file and your prompt returns.

Stop and restart the i-Planet gateway for the certificate to take effect.

See the procedure "To Stop and Restart the Reverse Proxy Server on the i-Planet Gateway" in Chapter 3, Other Administrative Tasks.

Make a backup copy of the rp.keystore file for the i-Planet gateway.

Using SSL Service for Encrypted Communication Between the i-Planet Server and the i-Planet Gateway

To use SSL service for encrypted communication between the i-Planet server and the i-Planet gateway, you must:

Create a self-signed certificate
Create a certificate signing request on the i-Planet server
Obtain a signed certificate from the Certificate Authority
Add the signed certificate to the rp.keystore file for the i-Planet server (the certificate database)
Configure SSL service on the i-Planet gateway
Configure SSL service on the i-Planet server

Self-Signed SSL Certificate on the i-Planet Server

You cannot use self-signed certificates for SSL service between the i-Planet server and the i-Planet gateway. You must use an SSL certificate from a certificate vendor.

You must generate a self-signed certificate in order to obtain an SSL certificate from certificate vendor who provides authority (CA) services.

To Generate a Self-Signed SSL Certificate for the i-Planet Server

As root, run the certadmin script on the i-Planet server:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 1 on the Certificate Administration menu to generate a self-signed certificate.

The Certificate Administration script prompts you to enter specific information about your organization and a passphrase for the self-signed certificate:

What is the fully qualified DNS name of this host? [hostname.domainname]
What is the name of your organization? []
What is the name of your organizational unit? []
What is the name of your City or Locality? []
What is the name of your State or Province? []
What is the two-letter country code for this unit? []
...
Enter passphrase []

Enter the information for your organization and a passphrase for the self-signed certificate.

A self-signed certificate is generated and added the file /etc/opt/SUNWstnr/rp.keystore on the i-Planet server. Your prompt returns.

Make a backup copy of the rp.keystore file on the i-Planet server.

SSL Certificates for the i-Planet Server

Using SSL service between the i-Planet server and the i-Planet gateway provides greater security for the information that must flow between them. SSL service requires a SSL certificate. In creating a self-signed certificate as part of this process for an SSL certificate for the i-Planet server, you enter specific information about your organization, such as company name and address, and a passphrase.

If you decide to enable SSL service so that you have secure communication between the i-Planet server and the i-Planet gateway after you have installed the i-Planet software, you must to run the certadmin script to install an SSL certificate that is signed by a certificate vendor who provides authority (CA) services.

SSL Certificates from Vendors

If you decide to enable SSL services between the i-Planet server and the i-Planet gateway after you have installed the i-Planet software, you must generate a self-signed certificate.

To Install SSL Certificates From Verisign

As root, run the certadmin script on the i-Planet server:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 2 on the Certificate Administration menu to generate a certificate signing request (CSR).

If no self-signed certificate exists on this machine, the Certificate Administration script notifies you that you must create one. Refer to the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Server" earlier in this chapter.
If a self-signed certificate exists on this machine, the information from the certificate is displayed. The Certificate Administration script asks the question:
Is this information correct (y/n)? [n]

Enter y if the information is correct, or enter n if it is not correct.

If you enter n, you are asked to enter information for a new self-signed certificate. See the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Server" in this chapter.

If you enter y, you are asked to enter some contact information for the webmaster of the machine for which the certificate is being generated:

What is the name of the admin/webmaster for this server? []
What is the email address of the admin/webmaster for this server? []
What is the phone number of the admin/webmaster for this server? []

Enter the name, the email address, and the telephone number of the administrator or webmaster for this server.

The Certificate Administration script displays the values you enter and asks the question:
Are these values correct (y/n)? [n]

When prompted, enter y if the information is correct, or enter n if it is not correct.
- If you enter y, the CSR is generated and added to the file /tmp/csr.hostname on the i-Planet server.
- If you enter n, the Certificate Administration script asks you to enter the values again.

Go to the Certificate Authority's website and order your web server certificate.
1. Provide information from your CSR, as requested by the CA.
2. Provide other information as requested by the CA, such as a passphrase.
3. Specify your web server type as: Java Webserver.
  
  Specifying Java Webserver means that you want your certificate in privacy enhance mail (PEM) format.

After you receive your certificate from the CA, save it in a file.

The certificate begins with a line that reads:

 -----BEGIN
CERTIFICATE----

continues with the certificate itself, and ends with a line that reads:

-----END CERTIFICATE-----

Make sure you include both of these lines with the certificate in the file.

As root, run the certadmin script on the i-Planet server.
# /opt/SUNWsnrp/bin/certadmin

Enter 4 on the Certificate Administration menu to install your certificate from the CA.

The Certificate Administration script asks the question:
What is the name (including path) of the file that contains the certificate? []

Enter the full path to the file containing the certificate from the CA.

Your certificate is stored in the file /etc/opt/SUNWstnr/rp.keystore on the i-Planet server.

Enable SSL service on the i-Planet server.

See the procedure "To Enable SSL Service on the i-Planet Server" in this chapter.

Make a backup copy of the rp.keystore file on the i-Planet server.

Enable SSL service on the i-Planet gateway.

See the procedure "To Enable SSL Service on the i-Planet Gateway" in this chapter.

To Install SSL Root Certificates and SSL Certificates From Other Vendors

You must have already generated a self-signed certificate to install a root certificate. See the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Server" in this chapter.

Go to the Certificate Authority's website and download its root certificate.

The website should contain instructions for downloading the certificate.

As root, run the certadmin script on the i-Planet server:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 3 on the Certificate Administration menu to add a root certificate.

The Certificate Administration script asks the question:
What is the name (including path) of the file that contains the root certificate that you would like to add to your database? []
1. Enter the full path to the file containing the root certificate from the CA.
  
  The file is displayed and the Certificate Administration script asks the question:
  Is this information correct (y/n)? [n]
2. Enter y if the file is correct, or n if it is not.
  - If you enter y, the root certificate is stored in the etc/opt/SUNWstnr/rp.CAstore file and your prompt returns.
  - If you enter n, the root certificate is not added and your prompt returns.

As root, run the certadmin script on the i-Planet server.
# /opt/SUNWsnrp/bin/certadmin

Enter 2 on the Certificate Administration menu to generate a certificate signing request (CSR).

If no self-signed certificate exists on this machine, the Certificate Administration script notifies you that you must create one. Refer to the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Server" earlier in this chapter.
If a self-signed certificate exists on this machine, the information from the certificate is displayed. The Certificate Administration script asks the question:
Is this information correct (y/n)? [n]

Enter y if the information is correct or enter n if it is not correct.

If you enter n, you are asked to enter information for a new self-signed certificate. Refer to the procedure "To Generate a Self-Signed SSL Certificate for the i-Planet Server" earlier in this chapter.

If you enter y, the Certificate Administration script asks you to enter specific information about your organization:

What is the name of the admin/webmaster for this server? []
What is the email address of the admin/webmaster for this server? []
What is the phone number of the admin/webmaster for this server? []

Enter your specific information about your organization.

The Certificate Administration script displays the values you enter and asks the question:
Are these values correct (y/n)? [n]

Enter y if the information is correct or enter n if it is not correct.
- If you enter y, a CSR is generated and stored in the file /tmp/csr.hostname.
- If you enter n, the Certificate Administration script asks you to enter the values again.

Go to the Certificate Authority's website and order your web server certificate.
1. Provide information from your CSR, as requested by the CA.
2. Provide other information as requested by the CA, such as a passphrase.
3. Specify your web server type as: Java Webserver.
  
  Specifying Java Webserver means that you want your certificate in PEM format.

After you receive your certificate from the CA, save it in a file.

The certificate begins with a line that reads:
```
-----BEGIN CERTIFICATE----
```
continues with the certificate itself, and ends with a line that reads:
```
-----END CERTIFICATE-----
```
Make sure you include both of these lines with the certificate in the file.

As root, run the certadmin script on the i-Planet server:

# /opt/SUNWsnrp/bin/certadmin

The Certificate Administration menu is displayed:

1) Generate Self-Signed Certificate
2) Generate Certificate Signing Request (CSR)
3) Add Root CA Certificate
4) Install Certificate from Certificate Authority (CA)
5) Quit
choice: [5]

Enter 4 on the Certificate Administration menu to install your certificate from the CA.

The Certificate Administration script asks the question:
What is the name (including path) of the file that contains the certificate? []

Enter the full path to the file containing the certificate from the CA.

Your certificate is added to the /etc/opt/SUNWstnr/rp.keystore file on the i-Planet server.

Enable SSL service on the i-Planet server.

See the procedure "To Enable SSL Service on the i-Planet Server" in this chapter.

Stop and restart the web server on the i-Planet server for the certificate to take effect.

See the procedure "To Stop and Restart the Web Server on the i-Planet Server" in Chapter 3, Other Administrative Tasks.

Make a backup copy of the rp.keystore file on the i-Planet server.

Enable SSL service on the i-Planet gateway.

See the procedure "To Enable SSL Service on the i-Planet Gateway" in this chapter.

Configuring SSL Service on the i-Planet Gateway

Use the following procedures to configure SSL service if you want to use it in communicating with the i-Planet server or if you want to disable SSL service and communicate with i-Planet server in the clear.

If you enable or disable SSL service on the i-Planet gateway, you must also enable and disable it on the i-Planet server.

If you are enabling SSL service after you have installed i-Planet, the default port 443 will be used if you used the default installation. If you used the custom installation, the port that you specified during the installation will be used.

To Enable SSL Service on the i-Planet Gateway

As root on the i-Planet gateway, type the following to enable SSL service if you want encrypted communication with the i-Planet server:
# /opt/SUNWsnrp/bin/iplanet_gw ssl on r
If you installed the i-Planet software using the default installation, the default SSL port 443 will be used. If you used the customized installation and specified another port for SSL, that port will be used.

Stop and restart the reverse proxy on the i-Planet gateway for the change to take effect.

See the procedure "To Stop and Restart the Reverse Proxy Server on the i-Planet Gateway" in Chapter 3, Other Administrative Tasks."

To Disable SSL Service on the i-Planet Gateway

As root on the i-Planet gateway, type the following to disable SSL service, if you want to communicate with i-Planet server in the clear:
# /opt/SUNWsnrp/bin/iplanet_gw ssl off

Stop and restart the reverse proxy on the i-Planet gateway for the change to take effect.

See the procedure "To Stop and Restart the Reverse Proxy Server on the i-Planet Gateway" in Chapter 3, Other Administrative Tasks.

Configuring SSL Service on the i-Planet Server

The default installation configures the i-Planet server for communication with the gateway so that it can use both SSL service and clear (plaintext) communication. By default SSL from the i-Planet server to the i-Planet gateway is disabled.

If you enable or disable SSL service on the i-Planet server, you must also enable or disable it on the i-Planet gateway.

If you are enabling SSL service after you have installed the i-Planet software, you must use the default port 443. Both the i-Planet server and the i-Planet gateway must use the same port number for SSL service.

When you are using SSL service for communication between the i-Planet server and the i-Planet gateway, use the URL below to connect to the Administration Console, if you are using the default port 443:

https://i-Planet_server.domain/console

Use the URL below to connect to the Administration Console, if you are using a port other than port 443:

https://i-Planet_server.domain:port/console
The port number that you use here must be the one that you specified in
the custom installation. Both the i-Planet server and the i-Planet gateway
must use the same port number for SSL service.

You can switch between communicating with the i-Planet server and the i-Planet gateway using SSL service and communicating in the clear. If you switch the i-Planet server so that it is communicating using SSL (or in the clear), you must also switch the i-Planet gateway so that it is using the same mode of communication as the i-Planet server. The default installation configures the Java web server for both http and https services, but the https service is disabled.

Note -

If you used the default installation settings and then decide to turn on SSL service for communication between the i-Planet gateway and the i-Planet server using the command below, the default port 443 is used. If you want to use a different port, you must have specified that port when you installed the i-Planet software using the custom installation.

To Enable SSL Service on the i-Planet Server

As root, type the following command to enable encrypted communication using SSL service from the i-Planet server with the i-Planet gateway.
# /opt/SUNWjeev/bin/iplanet_serv ssl on
If you installed the i-Planet software using the default installation, the default SSL port 443 will be used. If you used the customized installation and specified another port for SSL, that port will be used.

Stop and restart the web server before the SSL service will be started.

See the procedure "To Stop and Restart the Web Server on the i-Planet Server" in Chapter 3, Other Administrative Tasks.

To Disable SSL Service on the i-Planet Server

As root, type the following command to disable SSL service if you want to communicate with the i-Planet gateway in the clear.
# /opt/SUNWjeev/bin/iplanet_serv ssl off

Stop and restart the web server before the SSL service will be stopped.

See the procedure "To Stop and Restart the Web Server on the i-Planet Server" in Chapter 3, Other Administrative Tasks.