Sun Java System Portal Server Secure Remote Access 7.2 Administration Guide

Chapter 10 Working with Certificates

This chapter describes certificate management and explains how to install self-signed certificates and certificates from a Certificate Authority.

This chapter explains the following topics:

Introduction to SSL Certificates

The Sun Java System Portal Server Secure Remote Access software provides certificate-based authentication for remote users. SRA uses Secure Sockets Layer (SSL) to enable secure communication. The SSL protocol enables secure communication between two machines.

A SSL certificate provides encryption and decryption capabilities using a public and private key pair.

The two types of certificates are:

Self-signed certificates (also called root CA certificate)
Certificates issued by Certificate Authority (CA)

By default, a self-signed certificate is generated and installed when you install the Gateway.

You can generate, obtain, or replace a certificate anytime after installation.

SRA also supports client authentication with Personal Digital Certificates (PDCs). PD Cs are a mechanism to authenticate a user through SSL client authentication. With SSL client authentication, the SSL handshake ends at the Gateway. The Gateway extracts the user’s PDC and passes it to the authenticated server. This server uses the PDC to authenticate the user. To configure PDCs along with Authentication Chaining, see Using Authentication Chaining.

SRA provides a tool named certadmin that you can use to manage the SSL certificates. See The certadmin Script.

Note –

Certificate pop up windows are common in SSL applications. Advise users to accept the warning and proceed.

Certificate Files

Certificate related files are located in /etc/opt/SUNWportal/cert/gateway-profile-name. This directory contains 5 files by default.

Certificate Files lists these files and their descriptions.

Table 10–1 Certificate Files


File Name	Type	Description
`cert8.db`, `key3.db`, `secmod.db`	Binary	Contains the data for certificates, keys, and cryptographic modules. Can be manipulated using the `certadmin` script. If necessary, these files can be shared between the Portal Server host and gateway components or the Gateway.
`.jsspass`	hidden text file	Contains the encrypted password for the SRA key database.
`.nickname`	hidden text file	Stores the names of the token and certificate that the Gateway needs to use in the format `token-name:certificate-name`. If you are using the default token (the token on the default internal software encryption module), omit the token name. In most cases, the `.nickname` file stores only the certificate name. As an administrator, you can modify the certificate name in this file. The certificate that you specify is now used by the Gateway.

Certificate Trust Attributes

The trust attributes of a certificate indicate the following information:

Whether the certificate (in the case of client or server certificate) was issued by a Trusted CA.
Whether the certificate (in the case of a root certificate) can be trusted as the issuer of a server or client certificate.

The three available trust categories for each certificate are expressed in this order: “SSL, email, object signing”. Only the first category is useful for the Gateway. In each category position, zero or more trust attribute codes are used.

The attribute codes for the categories are separated by commas, and the entire set of attributes is enclosed by quotation marks. For example, the self-signed certificate generated and installed during the Gateway installation is marked "u,u,u" which means the certificate is a server certificate (user certificate) and not a root CA certificate.

Certificate Trust Attributes lists the possible attribute values and the meaning of each value.

Table 10–2 Certificate Trust Attributes


Attribute	Description
p	Valid peer
P	Trusted peer (implies p)
c	Valid CA
T	Trusted CA to issue client certificates (implies c)
C	Trusted CA to issue server certificates (SSL only) (implies c)
u	Certificate can be used for authentication or signing
w	Send warning (use with other attributes to include a warning when the certificate is used in that context)

CA Trust Attributes

Most well-known public CAs are included in the certificate database. See Modifying the Trust Attributes of a Certificate for information on modifying the trust attributes of a public CA.

CA Trust Attributes lists the most common Certificate Authorities with the trust attributes.

Table 10–3 Public Certificate Authorities


Certificate Authority Name	Trust Attribute
Verisign/RSA Secure Server CA	CPp,CPp,CPp
VeriSign Class 4 Primary CA	CPp,CPp,CPp
GTE CyberTrust Root CA	CPp,CPp,CPp
GTE CyberTrust Global Root	CPp,CPp,CPp
GTE CyberTrust Root 5	CPp,CPp,CPp
GTE CyberTrust Japan Root CA	CPp,CPp,CPp
GTE CyberTrust Japan Secure Server CA	CPp,CPp,CPp
Thawte Personal Basic CA	CPp,CPp,CPp
Thawte Personal Premium CA	CPp,CPp,CPp
Thawte Personal Freemail CA	CPp,CPp,CPp
Thawte Server CA	CPp,CPp,CPp
Thawte Premium Server CA	CPp,CPp,CPp
American Express CA	CPp,CPp,CPp
American Express Global CA	CPp,CPp,CPp
Equifax Premium CA	CPp,CPp,CPp
Equifax Secure CA	CPp,CPp,CPp
BelSign Object Publishing CA	CPp,CPp,CPp
BelSign Secure Server CA	CPp,CPp,CPp
TC TrustCenter, Germany, Class 0 CA	CPp,CPp,CPp
TC TrustCenter, Germany, Class 1 CA	CPp,CPp,CPp
TC TrustCenter, Germany, Class 2 CA	CPp,CPp,CPp
TC TrustCenter, Germany, Class 3 CA	CPp,CPp,CPp
TC TrustCenter, Germany, Class 4 CA	CPp,CPp,CPp
ABAecom (sub., Am. Bankers Assn.) Root CA	CPp,CPp,CPp
Digital Signature Trust Co. Global CA 1	CPp,CPp,CPp
Digital Signature Trust Co. Global CA 3	CPp,CPp,CPp
Digital Signature Trust Co. Global CA 2	CPp,CPp,CPp
Digital Signature Trust Co. Global CA 4	CPp,CPp,CPp
Deutsche Telekom AG Root CA	CPp,CPp,CPp
Verisign Class 1 Public Primary Certification Authority	CPp,CPp,CPp
Verisign Class 2 Public Primary Certification Authority	CPp,CPp,CPp
Verisign Class 3 Public Primary Certification Authority	CPp,CPp,CPp
Verisign Class 1 Public Primary Certification Authority - G2	CPp,CPp,CPp
Verisign Class 2 Public Primary Certification Authority - G2	CPp,CPp,CPp
Verisign Class 3 Public Primary Certification Authority - G2	CPp,CPp,CPp
Verisign Class 4 Public Primary Certification Authority - G2	CPp,CPp,CPp
GlobalSign Root CA	CPp,CPp,CPp
GlobalSign Partners CA	CPp,CPp,CPp
GlobalSign Primary Class 1 CA	CPp,CPp,CPp
GlobalSign Primary Class 2 CA	CPp,CPp,CPp
GlobalSign Primary Class 3 CA	CPp,CPp,CPp
ValiCert Class 1 VA	CPp,CPp,CPp
ValiCert Class 2 VA	CPp,CPp,CPp
ValiCert Class 3 VA	CPp,CPp,CPp
Thawte Universal CA Root	CPp,CPp,CPp
Verisign Class 1 Public Primary Certification Authority - G3	CPp,CPp,CPp
Verisign Class 2 Public Primary Certification Authority - G3	CPp,CPp,CPp
Verisign Class 3 Public Primary Certification Authority - G3	CPp,CPp,CPp
Verisign Class 4 Public Primary Certification Authority - G3	CPp,CPp,CPp
Entrust.net Secure Server CA	CPp,CPp,CPp
Entrust.net Secure Personal CA	CPp,CPp,CPp
Entrust.net Premium 2048 Secure Server CA	CPp,CPp,CPp
ValiCert OCSP Responder	CPp,CPp,CPp
Baltimore CyberTrust Code Signing Root	CPp,CPp,CPp
Baltimore CyberTrust Root	CPp,CPp,CPp
Baltimore CyberTrust Mobile Commerce Root	CPp,CPp,CPp
Equifax Secure Global eBusiness CA	CPp,CPp,CPp
Equifax Secure eBusiness CA 1	CPp,CPp,CPp
Equifax Secure eBusiness CA 2	CPp,CPp,CPp
Visa International Global Root 1	CPp,CPp,CPp
Visa International Global Root 2	CPp,CPp,CPp
Visa International Global Root 3	CPp,CPp,CPp
Visa International Global Root 4	CPp,CPp,CPp
Visa International Global Root 5	CPp,CPp,CPp
beTRUSTed Root CA	CPp,CPp,CPp
Xcert Root CA	CPp,CPp,CPp
Xcert Root CA 1024	CPp,CPp,CPp
Xcert Root CA v1	CPp,CPp,CPp
Xcert Root CA v1 1024	CPp,CPp,CPp
Xcert EZ	CPp,CPp,CPp
CertEngine CA	CPp,CPp,CPp
BankEngine CA	CPp,CPp,CPp
FortEngine CA	CPp,CPp,CPp
MailEngine CA	CPp,CPp,CPp
TraderEngine CA	CPp,CPp,CPp
USPS Root	CPp,CPp,CPp
USPS Production 1	CPp,CPp,CPp
AddTrust Non-Validated Services Root	CPp,CPp,CPp
AddTrust External Root	CPp,CPp,CPp
AddTrust Public Services Root	CPp,CPp,CPp
AddTrust Qualified Certificates Root	CPp,CPp,CPp
Verisign Class 1 Public Primary OCSP Responder	CPp,CPp,CPp
Verisign Class 2 Public Primary OCSP Responder	CPp,CPp,CPp
Verisign Class 3 Public Primary OCSP Responder	CPp,CPp,CPp
Verisign Secure Server OCSP Responder	CPp,CPp,CPp
Verisign Time Stamping Authority CA	CPp,CPp,CPp
Thawte Time Stamping CA	CPp,CPp,CPp
E-Certify CA	CPp,CPp,CPp
E-Certify RA	CPp,CPp,CPp
Entrust.net Global Secure Server CA	CPp,CPp,CPp
Entrust.net Global Secure Personal CA	CPp,CPp,CPp

The certadmin Script

You can use the certadmin script to do the following certificate administration tasks:

Generating Self-Signed Certificates

You need to generate certificates for SSL communication between each server and Gateway.

To Generate a Self-Signed Certificate After Installation

As root, run the certadmin script on the Gateway machine for which you want to generate a certificate:

portal-server-install-root/SUNWportal/bin/certadmin -n gateway-profile-name

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10) Quit
choice: [10]
1

Choose option 1 on the certificate administration menu.

The certificate administration script asks you if you want to keep the existing database files.

Enter organization-specific information, token name, and the certificate name.

Note –

For a wild card certificate, specify a * in the fully-qualified DNS name of the host. For example, if the fully-qualified DNS name of the host is abc.sesta.com, specify it as *.sesta.com. The certificate that is generated is now valid for all host names in the sesta.com domain.

What is the fully-qualified DNS name of this host? [host_name.domain_name]
What is the name of your organization (ex: Company)? []
What is the name of your organizational unit (ex: division)? []
What is the name of your City or Locality? []
What is the name (no abbreviation please) of your State or Province? []
What is the two-letter country code for this unit? []
Token name is needed only if you are not using the default internal 
(software) cryptographic module, for example, if you want to use a crypto card 
(Token names could be listed using:
modutil -dbdir /etc/opt/SUNWportal/cert/gateway-profile-name -list);
Otherwise, just hit Return below.
Please enter the token name. []
Enter the name you like for this certificate?
Enter the validity period for the certificate (months) [6]
A self-signed certificate is generated and the prompt returns.

The token name (default being empty) and certificate name are stored in the .nickname file under /etc/opt/SUNWportal/cert/gateway-profile-name.

Restart the Gateway for the certificate to take effect:

./psadmin start-sra-instance -u amadmin -f passwordfile -N profilename -t gateway

Generating a Certificate Signing Request (CSR)

Before you can order a certificate from a CA, you need to generate a certificate signing request which contains the information that is required by the CA.

To Generate a CSR

As root, run the certadmin script:

portal-server-install-root/SUNWportal/bin/certadmin -n gateway-profile-name

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10) Quit
choice: [10]
2

Choose option 2 on the certificate administration menu.

The script prompts you for organization-specific information, token name, and web master’s email and phone number.

Ensure that you specify the fully-qualified DNS name of the host.

What is the fully-qualified DNS name of this host? [snape.sesta.com]
What is the name of your organization (ex: Company)? []
What is the name of your organizational unit (ex: division)? []
What is the name of your City or Locality? []
What is the name (no abbreviation please) of your State or Province? []
What is the two-letter country code for this unit? []
Token name is needed only if you are not using the default internal 
(software) cryptographic module, 
for example, if you want to use a crypto card 
(Token names could be listed using: 
modutil -dbdir /etc/opt/SUNWportal/cert -list);
Otherwise, just hit Return below.
Please enter the token name []
Now input some contact information for
the webmaster of the machine that the certificate 
is to be generated for.
What is the email address of the admin/webmaster for this server [] ?
What is the phone number of the admin/webmaster for this server [] ?

Type all the required information.

Note –
Do not leave the web master’s email and phone number blank. The information is necessary for obtaining a valid CSR.

A CSR is generated and stored in the file portal-server-install-root/SUNWportal/bin/csr.hostname.datetimestamp. The CSR is also printed on the screen. You can directly copy and paste the CSR when you order a certificate from a CA.

Adding a Root CA Certificate

If a client site presents a certificate signed by a CA that is unknown to the Gateway certificate database, the SSL handshake fails.

To prevent this, you need to add a root CA certificate to the certificate database. This ensures that the CA becomes known to the Gateway.

Browse to the CA’s website and obtain the root certificate for that CA. When you use the certadmin script, specify the file name and path of the root CA certificate.

To Add a Root CA Certificate

As root, run the certadmin script.

portal-server-install-root/SUNWportal/bin/certadmin -n gateway-profile-name

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10) Quit
choice: [10]
3

Choose option 3 on the certificate administration menu.

Enter the name of the file that contains the root certificate and enter the name of the certificate.

The root CA certificate is added to the certificate database.

Installing SSL Certificates From the Certificate Authority

During the installation of the Gateway, a self-signed certificate is created and installed by default. At any point after installation, you can install SSL certificates signed by vendors who provide official certificate authority (CA) services, or by your corporate CA.

The three steps involved in this task are:

Ordering a Certificate from a CA

After generating a certificate signing request (CSR), you need to order the certificate from the CA using a CSR.

To Order a Certificate From a CA

Go to the Certificate Authority’s web site and order your certificate.

Provide the CSR as requested by the CA. Provide other information if requested by the CA.

You will receive your certificate from the CA. Save it in a file. Include the "BEGIN CERTIFICATE" and "END CERTIFICATE" lines with the certificate in the file.

The following example omits the actual certificate data.
-----BEGIN CERTIFICATE----- The certificate contents... ----END CERTIFICATE-----

Installing a Certificate from a CA

Using the certadmin script, install the certificate obtained from the CA in your local database files in /etc/opt/SUNWportal/cert/gateway-profile-name.

To Install a Certificate From a CA

As root, run the certadmin script.

portal-server-install-root/SUNWportal/bin/certadmin -n gateway-profile-name

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10)Quit
choice: [10]
4

Choose option 4 on the certificate administration menu.

The script asks you to enter the certificate file name, certificate name, and the token name.

What is the name (including path) of file that contains the certificate?
Please enter the token name you used when creating CSR for this certificate. []

Supply all the required information.

The certificate is installed in /etc/opt/SUNWportal/cert/gateway-profile-name, and the screen prompt returns.

Restart the Gateway for the certificate to take effect:

./psadmin start-sra-instance -u amadmin -f passwordfile -N profilename -t gateway

Deleting a Certificate

You can delete a certificate by using the certificate administration script.

To Delete a Certificate

As root, run the certadmin script.

portal-server-install-root/SUNWportal/bin/certadmin -n

where gateway-profile-name is the name of the Gateway instance.

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10)Quit
choice: [10]
5

Choose option 5 on the certificate administration menu.

Enter the name of the certificate to be deleted.

Modifying the Trust Attributes of a Certificate

One case in which the trust attributes of a certificate needs to be modified is if client authentication is used with the Gateway. An example of client authentication is PDC (Personal Digital Certificate). The CA that issues the PDCs must be trusted by the Gateway, and the CA certificate must be marked "T" for SSL.

If the Gateway is set up to communicate with an HTTPS site, the CA of the HTTPS site server certificate must be trusted by the Gateway, and the CA certificate must be marked "C" for SSL.

To Modify the Trust Attributes for a Certificate

As root, run the certadmin script.

gateway-install-root/SUNWportal/bin/certadmin -n
gateway-profile-name

where gateway-profile-name is the name of the Gateway instance.

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10)Quit
choice: [10]
6

Choose option 6 on the certificate administration menu.

Enter the name of the certificate. For example, Thawte Personal Freemail CA.
Please enter the name of the certificate? Thawte Personal Freemail CA

Enter the trust attribute for the certificate.
Please enter the trust attribute you want the certificate to have [CT,CT,CT]
The certificate trust attribute will be changed.

Listing Root CA Certificates

You can view all root CA certificates by using the certificate administration script.

To View the List of Root CAs

As root, run the certadmin script.

portal-server-install-root/SUNWportal/bin/certadmin -n
gateway-profile-name

where gateway-profile-name is the name of the Gateway instance.

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10)Quit
choice: [10]
7

Choose option 7 on the certificate administration menu.

All root CA certificates are displayed.

Listing All Certificates

You can view all certificates and their corresponding trust attributes by using the certificate administration script.

To List All the Certificates

As root, run the certadmin script.

portal-server-install-root
/SUNWportal/bin/certadmin -n
gateway-profile-name

where gateway-profile-name is the name of the Gateway instance.

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10)Quit
choice: [10]
8

Choose option 8 on the certificate administration menu.

All CA certificates are displayed.

Printing a Certificate

You can print a certificate by using the certificate administration script.

To Print a Certificates

As root, run the certadmin script.

portal-server-install-root/SUNWportal/bin/certadmin -n
 gateway-profile-name

where gateway-profile-name is the name of the Gateway instance.

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) Delete Certificate
6) Modify Trust Attributes of Certificate (e.g., for PDC)
7) List Root CA Certificates
8) List All Certificates
9) Print Certificate Content
10)Quit
choice: [10]
9

Choose option 9 on the certificate administration menu.

Enter the name of the certificate.