4 Introduction to Administration and Certificate Management

4.1 Starting and Stopping Oracle Application Server Certificate Authority

For security reasons, OracleAS Certificate Authority's start and stop operations can only be done using the command-line tool ocactl, which requires the administrator's password. An example of using these operations appears in Replacing the Administrator Certificate. This tool is fully described in Appendix A, "Command-Line Administration".

Before OracleAS Certificate Authority can be started, the following five components must be operating or available:

• Infrastructure metadata repository

• Oracle Internet Directory

• and optionally OracleAS Single Sign-On

• Oracle HTTP Server (OHS)

• OC4J for OracleAS Certificate Authority

If OracleAS Certificate Authority is installed in a different $ORACLE_HOME from the other infrastructure components, then OHS and OracleAS Certificate Authority's OC4J must be started separately, after the repository. Use this command in OracleAS Certificate Authority's $ORACLE_HOME:

$ORACLE_HOME/opmn/bin/opmnctl startall

If a single $ORACLE_HOME contains all the infrastructure components, including OracleAS Certificate Authority, then OHS and OC4J will already have been started, as in Section 4.3 earlier.

To start, stop, or restart OracleAS Certificate Authority, enter the corresponding command on the command line:

1. To stop OracleAS Certificate Authority, use this command:

   $ORACLE_HOME/oca/bin/ocactl stop
   
   

2. To start OracleAS Certificate Authority, use this command:

   $ORACLE_HOME/oca/bin/ocactl start
   
   

3. To restart OracleAS Certificate Authority, use the stop command listed in Step 1, followed by the start command listed in Step 2.

4. To get the status of Oracle Application Server Certificate Authority, use this command:

   $ORACLE_HOME/oca/bin/ocactl status
   

4.2 Requesting the Administrator Certificate

You must have the administrator certificate before you can use any of the Oracle Application Server Certificate Authority administrative options and controls in the web interface. If you have the administrator password created during installation, this certificate is easy to get, and is the first step you must do before any other task.

In other systems, requesting, acquiring, and installing your administrator PKI certificate required a whole set of command-line, floppy disk, and cut-and-paste operations.

With OracleAS Certificate Authority, however, the process is simple and easy:

To request the administrator certificate for your authentication, you simply fill in and submit a brief form that appears after OracleAS Certificate Authority is started for the first time. You must be accessing OracleAS Certificate Authority from the computer you intend to use as the administrator. Clicking the Certificate Management tab displays a Welcome page, followed by a form requesting your identifying data.

The form requires your common name, organization, and the OracleAS Certificate Authority administrator password created during installation. You can also supply other DN information: your email address, organizational unit, locality, state, and country.

You can select the certificate key size (default: 2048) and the validity period (default: 1 year).

When the administrator certificate is issued, you install it into your browser. With this certificate in your browser, you can access the OracleAS Certificate Authority facilities in the administration and configuration interfaces to manage certificate requests, certificate revocation or renewal, and policies.

This simple process — easy installation after filling in a simple request-form — replaces all the operations formerly required (before OracleAS Certificate Authority) for PKI certificate acquisition and use.

To request your certificate, perform the following steps:

1. Access the OracleAS Certificate Authority administration interface.

   Launch your web browser and enter the URL and port number of the administration server as they were displayed at the end of installation. For example:

   https://Oracle_HTTP_host:ssl_port/oca/admin
   
   

   where Oracle_HTTP_host is the host on which OracleAS Certificate Authority is installed, and ssl_port is listed in $ORACLE_HOME/install/portlist.ini under "Oracle Certificate Authority SSL Server Authentication port". For Windows, the path is %ORACLE_HOME\install\portlist.ini.

   
   

   Note: If port changes have occurred since installation, then the most current information is not in portlist.ini. Instead, sign on to the Oracle Enterprise Manager Control and click the instance on which OracleAS Certificate Authority was installed. Then click the Ports link, find the entry in the Type column that says "OracleAS Certificate Authority Server Authentication (SSL)", and use the number in the adjacent column, headed "Port In Use".

   
   

   The screen displays a welcome page. Clicking the link provided there displays the form to request the administrator certificate.

2. Enter into that form the DN, password, and certificate information to request your certificate:

   • DN Information: Enter the data for the distinguished name (DN) that will identify the administrator as the certified owner of the certificate.

     Table 4-1 DN Information for the Administrator's Certificate

     Field Name	Information to Enter
     Common name	The name that you want on the certificate
     Email address	Email address of the administrator
     Organization unit	Name of the organization unit or division to which the administrator belongs
     Organization	Name of the company or organization to which the administrator belongs
     Location	The city location of the administrator
     State	The state or province of the administrator
     Country	Two-letter code for the administrator's country

     
     
     
     

     Note: For a DN, the DC and EMAIL components must use only printable (ASCII) characters. This restriction means that even in a locale that uses a multibyte character set, the DC and EMAIL components for Distinguished Names must still use ASCII characters.

     
     

   • Certificate Authority Administrator Password: Only the OracleAS Certificate Authority administrator can do certificate and configuration management. This person is initially authenticated by entering here the password as entered during OracleAS Certificate Authority installation, in the screen named "Specify OCA Administrator Password".

     Passwords must

     • 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

     • Use only characters in the ASCII character set

     • 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 Corporation strongly discourages you from using the characters $ and #.

     Thus during installation, the password you choose for the OracleAS Certificate Authority administrator must accommodate these restrictions.

     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.

   • Certificate Information: The two vital data for creating a new certificate are the size of its keys and the period of its validity (or its expiration date). In this section of the form, you choose these parameters.

     • In Netscape, the phrase Certificate Key Size appears, referring to the size in bits of the key-pair to be generated: 512-bit, 1024-bit, or 2048-bit. Choose the size appropriate to your site: 2048-bit is OracleAS Certificate Authority's default, providing excellent security. Higher numbers improve the security at some price in performance.

     • In Internet Explorer, the phrase Cryptographic Service Provider appears, referring to a choice of providers for cryptography service. Standard choices include key sizes of 512-bit (Microsoft Basic Crypto Provider), 1024-bit (Microsoft Enhanced Crypto Provider), and 2048-bit (Microsoft Strong Cryptographic Provider). OracleAS Certificate Authority's default is the "Strong" choice, if available, followed by Enhanced, if available, and then by Basic. Other choices may also be present, such as Gemplus for smartcard usage. Select the size according to your requirements.

       This section of the form will look like this:

       
       Description of the illustration iekeystorchoicswcts.gif
       
       

     OracleAS Certificate Authority recommends using Microsoft Strong Cryptographic Provider for the Administrator Certificate. However, if readers for smartcards like Gemplus or Schlumberger are available, they should be used; if no reader is installed, selecting smartcard suppliers causes an error.

   • Validity Period: The duration of the certificate's validity. The standard default of 1 year is shown, but you can choose your desired period.

3. If you need to start over, click the Reset button.

4. To send your request for the Administrator certificate, click Submit. (You may have to supply your browser security password.)

5. Follow the instructions that your browser presents as it generates a key-pair. This process can take a few minutes, depending on keysize chosen and processor/memory limitations.

6. Click Install in Browser. (You may have to supply your browser security password.)

   Now you have a client authentication certificate in the common name you specified.

   At this point, you can perform any of the tasks available through the web interface of OracleAS Certificate Authority, as described in Chapter 5, "Configuring Oracle Application Server Certificate Authority".

7. Click Administration Home to access the welcome page for OracleAS Certificate Authority.

4.3 Replacing the Administrator Certificate

You may in future need to replace the administrator's certificate. Reasons could include the password to your private key being lost, the private key somehow being compromised or stolen, or the administrator role being given to someone new.

To replace the administrator certificate, you must stop the server, revoke the current administrator's certificate, and restart the server. These tasks are performed by using the command-line tool ocactl, which requires the OracleAS Certificate Authority Administrator password. For security reasons, these commands are only enabled on the command line and not through the graphical user interface (GUI).

The administrator then navigates to the Oracle Application Server Certificate Authority web page and fills in the form presented for Web Administrator Enrollment, as described earlier in "Requesting the Administrator Certificate".

Here are the three relevant command-line tasks:

1. To stop the OracleAS Certificate Authority server, enter the following command on the command line:

   $ORACLE_HOME/oca/bin/ocactl stop
   
   

2. To revoke the administrator's certificate, enter the following command:

   $ORACLE_HOME/oca/bin/ocactl revokecert -type WEBADMIN -reason REASON_CODE
   
   

   Note: You may choose any one of the following reason codes (separated by | ):

   {KEY_COMPROMISE | CA_COMPROMISE | AFFILIATION_CHANGE | SUPERSEDED | CESSATION_OF_OPERATION | CERTIFICATE_HOLD | REMOVE_FROM_CRL | UNSPECIFIED}
   
   

3. You may want to change the administrative password as well. See "Changing Privileged Passwords" in Appendix A, "Command-Line Administration".

4. On the command line, start OracleAS Certificate Authority services by entering one of the following commands:

   For UNIX, enter $ORACLE_HOME/oca/bin/ocactl start

   For Windows, enter %ORACLE_HOME%\oca\bin\ocactl start.

At this point, follow the instructions at "Requesting the Administrator Certificate" to obtain that certificate, enabling all administrative capabilities.

4.4 Overview of the OracleAS Certificate Authority Administration Interface

To perform administrative tasks you must have a valid administrator certificate. If your initial sign-in is as a regular user, rather than as administrator, you may get the error message described in Appendix C, "Troubleshooting OracleAS Certificate Authority", in section "Prerequisite Issues and Warnings", item "Key Pair Generation Fails during Certificate Requests on Windows"

To access the OracleAS Certificate Authority administration interface, launch your web browser. Enter the URL and port number of the administration server as they were displayed at the end of installation:

https://Oracle_HTTP_host:ssl_port/oca/admin

For information about the host and port number in the URL, see "Requesting the Administrator Certificate", Step 1.

After issuing the command to start OracleAS Certificate Authority, the OracleAS Certificate Authority home page appears, presenting three additional subtabs, as the following figure shows:

These three subtabs enable you to address specific tasks in managing certificates or the Certificate Authority configuration:

• "Certificate Management Tab", described in this chapter

• "Configuration Management Tab", described in Chapter 5, "Configuring Oracle Application Server Certificate Authority"

• "View Logs Tab", described in Chapter 5

4.4.1 Certificate Management Tab

The Certificate Management tab shows all the pending certificate requests, displaying a page that looks like the following:

Description of the illustration certrqstlistxpnddrva.gif

This page enables the administrator to choose among the following tasks:

4.5 Managing Certificates

Oracle Application Server Certificate Authority maintains a master list of all certificate requests and their current status: pending, rejected, or certified. Upon entering the Certificate Management tab, all certificate requests needing action (pending) are displayed. The administrator is responsible for approving or rejecting such requests, for revoking or renewing certificates as needed, and for managing the Certificate Revocation List (CRL) generation.

In performing these tasks as the administrator, you can search the master lists of certificates or certificate requests by name or number, and then examine specific certificates or requests of interest.

You can then

• approve or reject any individual certificate request,

• revoke specific issued certificates, if they have been compromised or are no longer appropriate, such as being owned by someone who has left the company, or renew any existing certificate during a brief period just before or after it expires.

  
  

  See Also: You can specify this renewal-period window: see Chapter 6, "Managing Policies in Oracle Application Server Certificate Authority", in the following sections: the "Certificate Renewal Policy as Shipped" section under "Policy Sub-tab of Oracle Application Server Certificate Authority" and the "Edit" section under "Policy Actions".

  
  

All of these certificate management tasks are described in the sections that follow:

• Approving or Rejecting Certificate Requests

• Viewing Details of Certificates

• Revoking Certificates

• Renewing Certificates

• Listing a Single Certificate Request or Issued Certificate

• Using Advanced Search

4.6 Updating the Certificate Revocation List (CRL)

Revoking a certificate should make it unusable in your environment. Making the fact of revocation publicly available ensures that revoked certificates are not misused. Publishing the list of revoked certificates, called the certificate revocation list (CRL), accomplishes this goal because entities granting authentication can first check this list. For example, all the applications in your trust environment can use the CRL to prevent authentication of a revoked certificate.

Automatic CRL generation is enabled by default when OracleAS Certificate Authority is installed. Once you have provided the necessary email information, any failure of CRL generation causes an email to be sent to you automatically.

The first CRL is generated at midnight with a validity period (and regeneration interval) of one day. These values (and auto-generation) are configurable in the Scheduled Jobs section of the Notification subtab within the Configuration Management tab of the Administrator's web interface.

You can generate an updated CRL manually by performing the following steps:

1. From the main Certificate Management page, click the Update Certificate Revocation List (CRL) button. The Update Certificate Revocation List form appears.

2. For the CRL Validity, specify a number, representing how many days until the next update.

3. For the Signature Algorithm, choose from the drop-down menu, such as MD5 with RSA or SHA1 with RSA. (Oracle recommends using SHA-1 because it generates a larger digest, which is inherently more secure against known attacks, such as inversion and brute-force collision attacks.)

After filling in the form, click the Submit button. This action generates the CRL.

You can retrieve it for review or saving by choosing Save CRL then Install in Browser or Save to Disk.

The Oracle HTTP Server uses this list to check the validity of the SSL certificates it receives, rejecting an SSL connection with any end-entity whose certificate is on the CRL. If your system uses multiple such servers, you will need to copy the CRL to the appropriate path and filename used by those servers as their CRL. Follow the steps established for each server in setting up its CRL.

Similarly, browser and email clients can verify servers they are connecting to, verifying incoming S/MIME email using these CRLs.

4.7 Oracle Internet Directory Integration

OracleAS Certificate Authority publishes the following to Oracle Internet Directory:

• Certificates are published to the user's directory entry in the attributes userCertificate and userSMIMECertificate

• Certificate Revocation Lists (CRL) are published to the location cn=oca1,cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext

This section addresses the following topic related to directory integration:

• Retrieving the Certificate Revocation List

dn: cn=oca1,cn=CRLValidation,cn=Validation,cn=PKI,cn=Products,cn=OracleContext
certificaterevocationlist:: MIICADCB6QIBATANBgkqhkiG9w0BAQUFADA8MQswCQYDVQQGE
 wJVUzEPMA0GA1UEChMGb3JhY2xlMRwwGgYDVQQDExNDQS1sa2V0aGFuYS1zdW4tOTA0Fw0wNTAxM
 DQyMjA2MjZaFw0wNTAxMDkyMjA2MjZaMCIwIAIBBRcNMDUwMTA0MjIwNTQzWjAMMAoGA1UdFQQDC
 gEBoFUwUzBRBgNVHSMBAf8ERzBFoUCkPjA8MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGb3JhY2xlM
 RwwGgYDVQQDExNDQS1sa2V0aGFuYS1zdW4tOTA0ggEBMA0GCSqGSIb3DQEBBQUAA4IBAQAwBRgih
 GOB08sWRg2sIaelqLFlUYNvnbtOe4QjdyTPaAy6k31+15jGi1vA7UBw7c0HqLv9r9iHLn7x9MtBj
 Ei8GKj+OJ5GGvrVVnj7ngoSAfpMMhg805m+sgZu0UoBbBkuh9tyAGFzUbxqMCadwakUgEwi7OVsn
 2jaDJilPD/1Lcp975hhlO0JH5hAwpERttSzaZcLqNEPGc9GMiAEUkTVCEa9rPwaw+C42msTZg38N
 7hChaqVf6gj/NpwTOZw98tVyOfU/Iy5tndh5ghbx4PMQ8HoxjXuw0xh6VHTvjmV6q51eTfiAFD3e
 M+IWjxO7fdgL8zUTZ/6HA8fNxZgaJen

4.8 Single Sign-on and OracleAS Certificate Authority

OracleAS Certificate Authority and OracleAS Single Sign-On complement each other in simplifying the provisioning of user certificates and using them to enable PKI authentication to all applications that use OracleAS Single Sign-On. The two configuration choices described in this section can make this collaboration even easier:

• Broadcasting the OracleAS Certificate Authority Certificate Request URL to SSO-Authenticated Users

• Bringing SSO-Authenticated Users to the OracleAS Certificate Authority Certificate Request URL

The first configuration choice, broadcasting, makes it even easier for an OracleAS Single Sign-On user to file a certificate request than it is using the default OracleAS Certificate Authority configuration. OracleAS Certificate Authority's default is to provide certificates when an OracleAS Single Sign-On-authenticated user files a certificate request, a process that takes several steps. That process is described in the "Single Sign-on Authentication (SSO)" section of Chapter 8, "End-User Interfaceof the Oracle Application Server Certificate Authority".

Broadcasting makes it even easier by providing a link that can be sent to all users, enabling them to request an OracleAS Single Sign-On/OracleAS Certificate Authority certificate directly.

The second configuration choice is described in the section following that, Bringing SSO-Authenticated Users to the OracleAS Certificate Authority Certificate Request URL. It explains an OracleAS Certificate Authority configuration command that shortens that process considerably, by simplifying OracleAS Single Sign-On configuration. OracleAS Single Sign-On's default deployment does not automatically use SSL, which PKI authentication requires. So for OracleAS Single Sign-On to leverage OracleAS Certificate Authority-provided user certificates at run-time, OracleAS Single Sign-On server needs to be configured to use SSL and certificates. This second configuration choice, described in "User Certificatesand SSO Usage", details how this process can be further simplified, leveraging the usual configuration defaults.

The last two subsections are

• Enabling PKI Authentication with SSO and OracleAS Certificate Authority

• User Certificatesand SSO Usage

They describe all the steps required for PKI authentication with OracleAS Certificate Authority and OracleAS Single Sign-On server, and the process Single Sign-On uses for authentication.

https://<Oracle_HTTP_host>:<oca_ssl_port>/oca/sso_oca_link

4.8.2 Bringing SSO-Authenticated Users to the OracleAS Certificate Authority Certificate Request URL

Although Oracle Application Server Certificate Authority is configured by default to act on OracleAS Single Sign-On authentication, there are several steps. Users would still need to go to the OracleAS Certificate Authority user interface, select SSO authentication, and then request the certificate. (See Chapter 8, "End-User Interfaceof the Oracle Application Server Certificate Authority", in the Single Sign-on Authentication (SSO) subsection.) Some users might find this process a bit difficult.

Therefore, OracleAS Certificate Authority has a mechanism to simplify the user experience, by sending users directly to the OracleAS Certificate Authority Certificate Request URL after authentication by the OracleAS Single Sign-On server.

Oracle Application Server Certificate Authority can be configured to provide this URL to OracleAS Single Sign-On, for display whenever OracleAS Single Sign-On is not using a certificate to authenticate a user. After OracleAS Single Sign-On authenticates such a user, it then displays the OracleAS Certificate Authority screen enabling that user to request a certificate. After that certificate is created and installed into the user's browser, future authentication can simply use that certificate automatically. (It should be noted, however, that this pop-up screen is shown to all users whether they are interested or not, and to some it could seem an inconvenience.)

Note: To see the pop-up, users must have pop-up-blocking turned off in their browsers.

To configure OracleAS Certificate Authority in this way, the administrator uses the ocactl command-line tool (with the administrator password) to issue the following command:

ocactl linksso

The administrator can also use the ocactl command-line tool (with the administrator password) to cancel the use of this URL through OracleAS Single Sign-On, by issuing the following command:

ocactl unlinksso

Please note that these commands do not require OracleAS Certificate Authority service to be shut down. However, the SSO server needs to be restarted for them to take effect, by using the following commands in the OracleAS Single Sign-On server ORACLE_HOME:

$ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=oca
$ORACLE_HOME/opmn/bin/opmnctl startproc type=oc4j instancename=oca

After the ocactl linksso command is executed and the OracleAS Single Sign-On server is restarted, the OracleAS Certificate Authority welcome page will be displayed whenever OracleAS Single Sign-On is not using a certificate to authenticate a user. That page looks like the following illustration:

Description of the illustration welcomenetscape.gif

When the OracleAS Single Sign-On user clicks that here link, the OracleAS Certificate Authority certificate request page appears:

Description of the illustration scndssontscpaftrwlcom.gif

This composite illustration shows that SSO users must choose a key size and then click Submit once their choice is set as desired. (Clicking Revert changes the choice back to the default.) After the request is submitted, the key for this certificate is automatically generated (which can take a few minutes). Then the certificate is imported into Oracle Internet Directory and displayed to the user. After the user views the certificate information and clicks Install in Browser, the certificate is installed into the user's browser for automatic use.

4.9 Default Install Values for OracleAS Certificate Authority

Table 4-4 lists the installation default values and other information, including default locations and validity periods for several important wallets.

If you want to change the depth of Sub CA's, that is, the path length, then the CA signing wallet should be regenerated using the command line. Use ocactl as described in Appendix A, "Command-Line Administration", in the section entitled "Generating a Sub CA Signing Wallet from OracleAS Certificate Authority".

However, once the CA is regenerated, all previously issued certificates would be invalid. So if you want to change the path length value, the CA signing wallet should be regenerated immediately after the install, as should all dependent wallets such as the SSL wallet.

Notes to Table 4-4:

1. To set different properties, use ocactl.

2. For the CA signing wallet, used to sign the certificates, only the DN and Key Size can be changed during installation.

   
   

   Note: For a DN, the DC and EMAIL components must use only printable (ASCII) characters. This restriction means that even in a locale that uses a multibyte character set, the DC and EMAIL components for Distinguished Names must still use ASCII characters.

   
   

3. For the CA signing wallet, after installation all elements can be changed by running ocactl generatewallet -type CA to regenerate the CA signing wallet. You can also change the validity period by renewing this certificate with the desired validity period.

4. Used for the HTTP Server hosting the Certificate Authority. All CA SSL wallet values can be changed by running ocactl generatewallet -type CASSL. It can be regenerated at any time, such as expiration, with a commandline option, or replaced with an SSL wallet from a different CA, such as Verisign. This replacement can be done to avoid the warning "CA certificate not trusted" when first connecting to OracleAS Certificate Authority. Possible key sizes are 512, 768, 1024, and 2048, with 1024 the default.

5. $OH stands for $ORACLE_HOME, so the full location is $ORACLE_HOME/oca/wallet/ssl.

6. Other ports available for use with multiple installs, such as another OracleAS Certificate Authority, include 6602 through 6619.

7. $OH stands for $ORACLE_HOME, so the full location is $ORACLE_HOME/Apache/conf/ocm_apache.conf.

   
   

   Note: Two listener ports are defined for OracleAS Certificate Authority in the ocm_apache.conf file. The reason two are needed is that there is a part of the functionality that does not need certificates and a part of the functionality that does need certificates. Using two listener ports is preferable to using the ClientCertificate optional directive in Apache, which would display a certificate-related dialog for all cases.