25
OracleAS Certificate Authority

This chapter describes issues with OracleAS Certificate Authority (OCA). It includes the following topics:

• Section 25.1, "General Issues and Workarounds"

• Section 25.2, "Configuration Issues and Workarounds"

• Section 25.3, "Administration Issues and Workarounds"

• Section 25.4, "Documentation Errata"

25.1 General Issues and Workarounds

This section describes general issues and their workarounds for OCA. It includes the following topics:

• Installing Another OracleAS Certificate Authority

• Choosing a Chinese Locale for OCA Installation

25.1.1 Installing Another OracleAS Certificate Authority

The OracleAS Certificate Authority schema in one repository can only be used with one OCA.

When installing another OracleAS Certificate Authority, you must not choose a repository that has been used to install an earlier OCA: the OCA configuration tool will fail.

This failure will force you to exit the whole installation and restart it.

25.1.2 Choosing a Chinese Locale for OCA Installation

When installing another OracleAS Certificate Authority, you must not install and start OCA in zh or zh_TW locale. Instead, use one of the following locales:

• For Simplified Chinese, use zh_CN.GBK

• For Traditional Chinese, use zh_TW.BIG5.

25.2 Configuration Issues and Workarounds

This section describes configuration issues and their workarounds for OracleAS Certificate Authority. It includes the following topics:

• Section 25.2.1, "Administrator's Password"

• Section 25.2.2, "OCA's SSL Connection to Oracle Internet Directory"

• Section 25.2.3, "Enabling PKI Authentication with SSO and OCA"

25.2.1 Administrator's Password

During installation, you establish the password for the administrator of the Oracle Application Server Certificate Authority. The following information supersedes the administrator password information given in Section 6.24 of the Oracle Application Server 10g Installation Guide in Table 6.14. Passwords must

• Use only characters in the ASCII character set

• Begin with an alphabetic character from your database character set;

• Be at least eight characters long;

• Contain at least one alphabetic character and at least one non-alphabetic character, that is, a numeric or special character;

• Be different from all Oracle reserved words; and

• Contain only alphanumeric characters from your database character set. If needed, the underscore (_), dollar sign ($), or pound sign (#) can also be used, although Oracle strongly discourages you from using $ and #.

Thus during installation, the password you choose for the OCA administrator must accommodate these restrictions.

Note: If your database will be using Oracle's password complexity verification routine (specified using the PL/SQL script UTLPWDMG.SQL), then the password must also meet the following requirements (or additional requirements that you add to that script): Be at least four characters long Differ from the username Have at least one alpha, one numeric, and one punctuation mark character Be different from simple or obvious words, such as welcome, account, database, or user Subsequent changes to this password must also differ from the previous password by at least 3 characters.

25.2.2 OCA's SSL Connection to Oracle Internet Directory

In Oracle Application Server 10g, by default, the Oracle Internet Directory server has two ports available: SSL and NON SSL.

To secure the connection between OCA and Oracle Internet Directory, OCA always connects to the directory server using the SSL port. This DH (Diffie Hellman SSL) connection does not require authentication. OCA then authenticates itself to the directory server by sending its username/password over the now-secured SSL connection.

Therefore, on the administrative pages, on the General page within Configuration Management, the section for Certificate Publishing has a check box for "Protect publication using SSL mode". This check box is not relevant anymore, because OCA always uses SSL.

25.2.3 Enabling PKI Authentication with SSO and OCA

This section extends the discussion of the same name ("Enabling PKI Authentication with SSO and OCA") that appears in Chapter 3 of the Oracle Application Server Certificate Authority Administrator's Guide, on page 3-22.

After installation, the OracleAS Single Sign-On server can be PKI-enabled. If a site chooses to PKI-enable its OracleAS Single Sign-On, then users of the applications partnering with OracleAS Single Sign-On, which use its authentication service, must have certificates to log in to those applications.

See Also: Oracle Application Server Single Sign-On Administrator's Guide, Chapter 7: Signing on with Digital Certificates.:

This requirement presents the following issue:

• Users need to log on to OCA to get their certificates.

• Since OCA also uses the OracleAS Single Sign-On authentication service, users without certificates cannot log on to OCA.

This issue is resolved by using multiple authentication levels in the OracleAS Single Sign-On server. Once PKI is enabled, all partner applications will have "medium high" security level (using certificates for authentication), even though OCA can have "medium" security level by using username/password or Windows Native Authentication. This allows OCA to use passwords to authenticate a user before issuing a certificate, but forces other SSO-enabled applications to use certificates for authentication.

To configure OCA to have "medium" security level using username/password:

1. In $ORACLE_HOME/sso/conf/policy.properties, make sure that the following lines exist:

   MediumSecurity = 40 
   MediumSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOServerAuth 
   
   

2. After finding or inserting the two lines from step 1, you need to add an additional line. To do so, you need to know the OCA server authentication SSL port. You can find it by signing on to the Oracle Enterprise Manager Control and clicking the instance on which OCA was installed. Then click the Ports link, find the entry in the Type column that says "OCA Server Authentication (SSL)", and use the number in the adjacent column, headed "Port In Use".

   Once you know this port number, add the following line:

   ocaHostName\:ocaPort = MediumSecurity 
   
   

   where ocaPort is OCA's server authentication (SSL) port on the host machine ocaHostName. For example, if OCA is allocated port 4400 during installation on the host machine myoca1234.us.company.com, this line would read

   myoca1234.us.company.com\:4400 = MediumSecurity 
   
   

3. Restart the OracleAS Single Sign-On server with the following command:

   $ORACLE_HOME/opmn/bin/opmnctl restartproc type=oc4j instancename=OC4J_
   SECURITY 
   

See Also: For more detail, see Chapter 6, Multiple Authentication, in the Oracle Application Server Single Sign-On Administrator's Guide.

Similarly, OCA can be configured to use other authentication mechanisms like Windows Native Authentication. Assign a security level to the plugin implementing the authentication mechanism as in Step 1 and then assign the OCA URL to use that security level as in Step 2.

See Also: Chapter 8: Windows Native Authentication in the Oracle Application Server Single Sign-On Administrator's Guide.

25.2.3.1 Re-registering OCA's Virtual Host to SSO Server

This section corrects one parameter in the discussion of the same name ("Re-registering OCA's Virtual Host to SSO Server") that appears in Chapter 3 of the Oracle Application Server Certificate Authority Administrator's Guide, also on page 3-22.

The syntax for the command to re-register with the SSL server, to be run on a single line from the $ORACLE_HOME where OCA is installed, is given there as follows:

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar
-oracle_home_path orcl_home_path
-site_name site_name
-config_mod_osso TRUE
-mod_osso_url mod_osso_url
-u userid
[-virtualhost virtual_host_name]
[-update_mode CREATE | DELETE | MODIFY]
[-config_file config_file_path]
[-admin_info admin_info]
[-admin_id adminid]

The correction is to remove the square brackets, which indicated an optional parameter, from the line reading

[-virtualhost virtual_host_name]

so that it reads instead as follows:

-virtualhost virtual_host_name

indicating, by the absence of the square brackets, that this parameter is required.

Thus in the example that directly follows, on page 3-23, the command in step 2 should read as follows:

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar
-oracle_home_path $ORACLE_HOME -site_name "my_oca_site_name" 
-config_mod_osso TRUE  -mod_osso_url https://myoca.mysite.com:4400
-u root -config_file $ORACLE_HOME/Apache/Apache/conf/osso/oca/osso.conf
-virtualhost

For OCA, the -virtualhost command does not require that a virtual_host_name be specified.

25.3 Administration Issues and Workarounds

This section describes administration issues and their workarounds for OracleAS Certificate Authority. It includes the following topics:

• Section 25.3.1, "National Language Support (NLS)"

• Section 25.3.2, "E-mail Templates"

• Section 25.3.3, "Using Netscape 7.x to Export or Import a Certificate"

25.3.1 National Language Support (NLS)

OracleAS Certificate Authority alerts and notifications are created and sent in the language of the Server Locale. They will not use the language of the client locale, if that is different from the Server locale. If OCA were to be installed on an server that is in English, and a Japanese client submits a request, the notification will be in English.

If you use templates for customizing alerts or notifications, as described in the next section, the language in which you edit the templates is used. It is advisable to edit the templates in the language of the server, because the message body is encoded in the language of the server locale.

If you do not use templates, then all alerts and notifications will appear in the language of the server locale.

25.3.2 E-mail Templates

As the administrator, you can specify the body of e-mail alerts and notifications as templates, which are stored in the following directory:

$ORACLE_HOME/oca/templates/email 

You can use the tokens described below to format the e-mail to provide specific information. These tokens are replaced before the e-mail is sent. Table 25-1 lists the notifications, filenames for e-mail format and the supported tokens.

Table 25-1 Notifications, Templates, and Tokens Supported for E-mail Customization  

Notifications	Template File Name	Supported Tokens
CertificateRequestNotify	reqacc.txt	#NAME#, #REQUESTID#, #SUBJECTDN#, #PHONE#, #EMAIL#
RequestApprovalNotify	reqapp.txt	#NAME#, #REQUESTID#, #SUBJECTDN#, #SERIALNUM#, #OCAURL#, #PHONE#, #EMAIL#, #VALIDITY#
RequestRejectionNotify	reqrej.txt	#NAME#, #REQUESTID#, #SUBJECTDN#, #PHONE#, #EMAIL#
PendingRequestsAlert	pendreq.txt	#NAME#, #NUMBERREQUESTS#
CRLAutoGenFailureAlert	crlfail.txt	#NAME#

Note: If you do not check the box for Use Template in Configuration Management in the Notification screen, then templates are not used. All alerts and notifications would be predefined text that cannot be changed.

25.3.2.1 Values for the tokens

Table 25-2 describes the values that will replace each of the listed tokens before the alert or notification is sent:

Table 25-2 Values Taken by Tokens Supported for Customization in Notifications and Templates 

Notifications and Template File Names	Supported Tokens	To Be Replaced by This Data:
CertificateRequestNotify Template = reqacc.txt	#NAME# #REQUESTID# #SUBJECTDN# #PHONE# #EMAIL#	the contact data Name specified in the certificate request the request ID issued by OCA to this request the DN in the certificate request the contact data phone number in the certificate request the contact data email address in the certificate request
RequestApprovalNotify Template = reqapp.txt	#NAME# #REQUESTID# #SUBJECTDN# #SERIALNUM# #OCAURL# #PHONE# #EMAIL# #VALIDITY#	the contact data Name specified in the certificate request the request ID issued by OCA to this request the DN in the certificate request the serial number of the certificate the URL of the user home page the contact data phone number specified in the certificate request the contact data email ID specified in the certificate request the validity period for which the certificate request is approved by the administrator.
RequestRejectionNotify Template = reqrej.txt	#NAME# #REQUESTID# #SUBJECTDN# #PHONE# #EMAIL#	the contact data Name in the certificate request the request ID issued by OCA to this request the DN in the certificate request the contact data phone number in the certificate request the contact data email address in the certificate request
PendingRequestsAlert Template = pendreq.txt	#NAME#	the value specified in the OracleAS Certificate Authority Administrator field under Configuration Management in the Notification screen
	#NUMBERREQUESTS#	the number of pending requests in the OCA repository
CRLAutoGenFailureAlert Template = crlfail.txt	#NAME#	the value specified in the OracleAS Certificate Authority Administrator field under Configuration Management in the Notification screen

25.3.3 Using Netscape 7.x to Export or Import a Certificate

25.3.3.1 Netscape 7.x Export of Certificate to a PKCS#12 Wallet

After importing the certificate into your browser from the OCA screen, you can export it as a PKCS#12 wallet using the following steps:

1. In Netscape's Edit menu, click Preferences. The Preferences window appears.

2. In the Preferences Window, expand the option, 'Private & Security' and click Certificates.

3. Click Manage Certificates (on the right) to display the Certificate Manager window.

4. Select the certificate that needs to be exported and click Backup.

5. Enter the file name for the PKCS#12 wallet and click on Save.

6. Enter the Netscape Repository password, and click OK.

   A window appears, labeled 'Choose a Certificate Backup password', with the prompt 'Please enter the master password for the Software Security Device'.

7. In this window, enter the password with which the PKCS#12 wallet will be encrypted. You will need to enter the same password again to confirm the password. There is a password quality meter in this window that gives information on how good this password provided is.

8. Click OK. An alert appears saying that backup is successful.

25.3.3.2 Netscape 7.x Import of Certificate from a PKCS#12 Wallet

1. In Netscape's Edit menu, click Preferences. The Preferences window appears.

2. In the Preferences Window, expand the option, 'Private & Security' and click Certificates.

3. Click Manage Certificates (on the right) to display the Certificate Manager window.

4. Click Import

5. Choose the PKCS#12 wallet containing the certificate and key to be imported and click Open.

6. Enter the Netscape Repository password in the popup that appears, and click OK.

7. The prompt says 'Please enter the master password for the Software Security Device'. A window appears, labeled Password Entry Dialog.

8. In this window, enter the password that will be used to decrypt the PKCS#12 wallet, and click OK.

9. An alert appears, saying that restoration of the certificate and private key is successful.

25.4 Documentation Errata

This section describes known errors in the documentation for OracleAS Certificate Authority. It includes the following topics:

• Section 25.4.1, "References to "portlist.ini""

• Section 25.4.2, "Identity Management Services Errata"

25.4.1 References to "portlist.ini"

Pages 3-4, 3-7, 3-20, and 6-15 refer to the SSL port. Chapter 3 refers to the file "portlist.ini" as the place to find what port number to use. However, if port changes have occurred since installation, the most current information will be found by signing on to the Oracle Enterprise Manager Control and clicking the instance on which OCA was installed. Then click the Ports link, find the entry in the Type column that says "OCA Server Authentication (SSL)", and use the number in the adjacent column, headed "Port In Use".

25.4.2 Identity Management Services Errata

25.4.2.1 Chapter 6, Advanced Topics

Replace an explanatory sentence and add a Note in Chapter 6 of the OracleAS Certificate Authority Administrator's Guide, in the section entitled "Changing Identity Management (IM) Services (SSO/OID) Used by OCA", pages 6:15,16.

The sentence immediately after Step 6 should read as follows:

This command performs the following two actions:

• Updates the file oca.conf at $ORACLE_HOME/oca/conf to point to the new IM Services machine (Machine 2)

• Registers OCA with the new SSO server (Machine 2)

Then the following note should appear after that second bullet just added:

Note: Identity Management (IM) reassociation can be used to accommodate changes to the configuration of SSO or OID services for scalability or failover purposes, or to accommodate the transition from a pilot IM to production IM. For more information on such reassociation, see Oracle Application Server 10g Administrator's Guide.