A Command-Line Administration

A.1 Command-Line Tool

As the OracleAS Certificate Authority administrator, you use the command line tool named ocactl to specify the parameters needed to perform the various OracleAS Certificate Authority operations. (You may need to add oca/bin to your path.) Each time this tool is invoked it requests your OracleAS Certificate Authority Administrator password, which is always the same as the CA signing password. (If you use a slow telnet/rlogin session and backspace while entering the password, some portions of it are echoed.)+

The general form for using this command is:

ocactl operation -type related-parameters, if any

For example, to start OracleAS Certificate Authority, you would enter

ocactl start

As another example, to generate a certificate and wallet for CASSL operations in publishing certificates with mutual authentication between OracleAS Certificate Authority and Oracle Internet Directory, you would enter

ocactl generatewallet -type CASSL

Notice that not all commands have parameters. Those that do not use parameters also do not use the keyword "-type".

Those that do need parameters must use the keyword -type preceding the parameter.

The only exception is the "convertwallet" command, which has a special syntax explained after Table A-2.

Table A-2 shows the main operations (in alphabetical order) and their related parameters. After the table, additional parameters for the convertwallet command are explained.

The following operation-names are links directly into that table:

changesecurity, clear, generatewallet, help, importwallet, linksso, renewcert, revokecert, set, setpasswd, start, stop, unlinksso, updateconnection

A.2 Converting a CA SSL Server Wallet into SSO Form

Table A-2 shows samples for most of the commands you can issue using ocactl. However, the convertwallet command uses a different syntax, which this section explains with examples.

You use ocactl's convertwallet command to convert a CA SSL server wallet (ewallet.p12, in PKCS#12 format) into Oracle Single Sign-On format, with file name cwallet.sso. The command uses the current CA SSL wallet location, unless you specify a different location.

The advantage to using cwallet.sso is that HTTP Server can be brought up in SSL mode without requiring you to supply the wallet password. Otherwise, when HTTP Server starts up in SSL mode using a PKCS#12 wallet, the wallet password is requested.

The SSO-format wallet is encrypted to discourage users from visually opening the file and extracting the keys. However, the operating system file permissions are relied upon to protect it, since it is created with owner-only permissions.

Thus the convertwallet command enables the OracleAS Single Sign-On server to bring up the web server in SSL mode automatically, without asking a human for the wallet password.

The convertwallet command must be run as root user, with wlt-location replaced by the desired destination. The command syntax is:

convertwallet -format SSO [-walletwrl wallet-location]

For example,

convertwallet -format SSO -walletwrl $ORACLE_HOME/wallets

The optional parameter -walletwrl identifies the next parameter as specifying the directory where the CA SSL PKCS#12 wallet is presently located, under the filename ewallet.p12.

When -walletwrl is specified, ocactl assumes the administrator is trying to convert a CA SSL wallet that was not created by OCA, but rather obtained from elsewhere. The administrator must then supply the original CA SSL wallet's password to read the wallet at the specified location, since OCA's password store does not contain that password. Once the wallet is opened, the certificate is converted to .sso format and stored back in the same place specified by -walletwrl wallet-location.

When -walletwrl is not specified, then ocactl assumes the wallet is the CA SSL wallet generated by OracleAS Certificate Authority during OracleAS Certificate Authority installation. This command therefore uses the OracleAS Certificate Authority administrator's password, already supplied to validate using the ocactl command, to open the internal password store containing the CA SSL password. It then uses this password to open and convert the CA SSL wallet (present at $ORACLE_HOME/oca/wallet/ssl directory).

If the destination wlt-location is not specified, then by default this wallet is stored in $ORACLE_HOME/oca/wallet/ssl (or the location specified during installation).

OracleAS Certificate Authority will use the new OracleAS Single Sign-On wallet stored at $ORACLE_HOME/oca/wallet/ssl/ only after OHS, OracleAS Certificate Authority's OC4J, and OracleAS Certificate Authority are restarted (in that order). (To start the required infrastructure, see section 4.1 in Oracle Application Server Administrator's Guide. To start middle tier components like OHS and OC4J, see section 4.2.)

A.3 Starting the Oracle Certificate Authority Server

After OC4J, OHS, and the database are operating, you can start the OracleAS Certificate Authority services that support the forms for administrator and user access. To start OHS and OracleAS Certificate Authority's OC4J, use opmnctl commands in the following order:

$ORACLE_HOME/opmn/bin/opmnctl startproc type=oc4j instancename=OracleAS Certificate Authority 
$ORACLE_HOME/opmn/bin/opmnctl startproc type=ohs

To start Oracle Application Server Certificate Authority, issue the following command:

ocactl start

This command requests the administrator password and then starts the Oracle Application Server Certificate Authority engine, creating a database connection pool, logger and tracer files, and initializing configuration.

A.4 Stopping the Oracle Application Server Certificate Authority Server

The stop command stops the OracleAS Certificate Authority services. No other services are affected: database, OracleAS, and web server remain unchanged.

To stop the OracleAS Certificate Authority services, issue the following commands to stop OracleAS Certificate Authority's OC4J process and OracleAS Certificate Authority itself:

$ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j \
    instancename=OracleAS Certificate Authority 
ocactl stop

A.5 Finding the Status of the Oracle Certificate Authority Services

You can display the status of the Oracle Application Server Certificate Authority services by issuing the status command. It requests the administrator password and then queries the OracleAS Certificate Authority engine. The response shows whether the following facilities are open or closed: the database connection pool; logger, tracer, and the password store.

To get the OracleAS Certificate Authority services status, issue this command:

ocactl status

A.6 Changing Privileged Passwords

Installation creates the Oracle Application Server Certificate Authority password store, which contains the initial passwords required for OracleAS Certificate Authority operations:

The contents of this password store are encrypted using the OracleAS Certificate Authority administrator's password, which is also the CA signing password. This password is not stored in the password store.

At some point after installation, you can change the password for any of the following privileged operations for different types of administrators. Use the setpasswd command in the ocactl tool as follows:

OracleAS Certificate Authority must be stopped before any password can be changed.

The changes resulting from executing these commands take effect after the next start of OracleAS Certificate Authority. After OracleAS Certificate Authority is restarted, the new passwords will be in effect.

Each use of ocactl requires the OracleAS Certificate Authority administrator password. Once this is authenticated, the command requests the new password for the role type specified in the command, which then replaces the one in the password store. The results are again encrypted using the latest OracleAS Certificate Authority administrator password.

A.7 Regenerating the Root Certificate Authority's Certificate

When installing OracleAS Certificate Authority as a root certificate authority (CA), the Root CA certificate and wallet are created. If the CA key is somehow compromised, this certificate can be regenerated using the ocactl administrative command line tool. The new CA certificate and private key will be stored in the OracleAS Certificate Authority repository. The private key is encrypted by the password that was requested during its generation.

The former CA signing certificate entry and all other certificates issued by that former CA signing certificate will become invalid. Critical wallets like CA SSL, CA SMIME need to be regenerated again. After re-generation of the CA signing wallet, a CRL issued by the old CA will not be useful.

Regenerating the CA signing wallet and other critical wallets can only be done after OracleAS Certificate Authority is successfully installed and OracleAS Certificate Authority service is not running.

The root CA signing wallet can be generated only when OracleAS Certificate Authority is not running. If OracleAS Certificate Authority is running, stop OracleAS Certificate Authority and use this command to regenerate the Root CA signing wallet:

ocactl generatewallet -type CA

This certificate is stored in the OracleAS Certificate Authority repository.

The signing key is also stored in the OracleAS Certificate Authority repository, encrypted by the OracleAS Certificate Authority administrator password.

The password store is kept in the directory $ORACLE_HOME/oca/pwdstore, encrypted with the Administrator's password. The DB password is initially the same as the Administrator's password.

A.8 Regenerating the Certificate Authority's SSL Certificate and Wallet

The CA SSL certificate and wallet are generated during installation and are used to enable the OracleAS Certificate Authority engine to listen in HTTPS mode. If these are compromised or corrupted, or the CA signing wallet is regenerated, you must regenerate them in order to reestablish secure communications.

The CA SSL wallet can be generated only when OracleAS Certificate Authority is not running. If it is running, stop OracleAS Certificate Authority and use this command to regenerate the CA SSL certificate and wallet:

ocactl generatewallet -type CASSL

This wallet is stored in the directory $ORACLE_HOME/oca/wallet/ssl, encrypted by the password that was requested during its generation.

This command also generates CA SSL wallet in OracleAS Single Sign-On format and stores it as cwallet.sso at $ORACLE_HOME/oca/wallet/ssl.

A.9 Revoking a Root CA Certificate

Revoking a root CA certificate is a very drastic operation, which will make OracleAS Certificate Authority installation non-functional and invalidate the certificates already issued. This operation, revocation, should only be done when the CA key is compromised, so that you can install a new certificate authority.

The revokecert command enables you to revoke a root certificate authority certificate or an OracleAS Certificate Authority Administrator's certificate. It can only be used when OracleAS Certificate Authority is not operating.

Revoking a root certificate authority certificate is required before installing a new root CA for ongoing OracleAS Certificate Authority operations.

When you intend to install a new CA, use revokecert first to revoke the old CA signing wallet, giving the reason as a parameter. If the root CA certificate is revoked, all certificates issued by that CA will be in an inconsistent state. So before revoking the root CA certificate, first revoke all certificates issued by the existing CA and update the Certificate Revocation List. Otherwise, while the new CA signing certificate is being generated, all the old certificates signed by the old CA will be marked as Invalid in the OracleAS Certificate Authority repository.

Once the OracleAS Certificate Authority administrator certificate is revoked, the administrator cannot access any administrative functions on the web until he gets a new certificate. When he opens the Administration home page, it will require a new enrollment to get a new Administrator's certificate.

Revoking a root certificate authority certificate requires that you first stop OracleAS Certificate Authority. Then issue the following command:

ocactl revokecert -type CA -reason why

Since the primary reason for revoking a CA certificate is a compromised key, the actual command would be as follows:

ocactl revokecert -type CA -reason KEY_COMPROMISE

If other circumstances require a revocation, you can replace the why entry with whichever one of the following eight phrases is most appropriate:

A.10 Generating a Sub CA Signing Wallet from OracleAS Certificate Authority

You can generate a Sub CA signing wallet from OracleAS Certificate Authority as follows:

1. Create a new wallet and generate a certificate request using Oracle Wallet Manager or another similar tool.

   
   

   See also: Oracle Advanced Security Administrator's Guide

   
   

2. Using the Server/Sub CA enrollment form, submit the PKCS10 request and select certificate usage as CA signing.

3. Using the OracleAS Certificate Authority Administrative form, issue a Sub CA certificate. Please specify the path-length, that is, the number of levels of Sub CAs that it can have.

4. Go to the Server/Sub CA enrollment form and click Down CA Certificate, which will show the CA certificate along with the its ancestors, if there are any.

5. Copy the BASE64 certificate of the CA from the screen and import it as a Trusted certificate into Oracle Wallet Manager. If there are any trust points along with the CA, copy one by one into Oracle Wallet Manager using its Import Trusted Certificate option.

6. Using the Server/Sub CA enrollment form, get certificate details by giving the serial number or the common name of the Sub CA. Click View Details to view the Sub CA certificate in BASE64 format.

7. Copy the BASE64 format of the Sub CA certificate and import it into Oracle Wallet Manager as a user certificate.

8. Save the Sub CA signing wallet using Oracle Wallet Manager. The wallet will be stored as ewallet.p12.

A.11 Installing/Importing a Sub CA Signing Wallet

The steps in this section enable you to install and use a Sub CA signing wallet, creating a hierarchy of CAs. This wallet can be generated from OracleAS Certificate Authority, as in "Generating a Sub CA Signing Wallet from OracleAS Certificate Authority", a self-signed wallet created with the mkwallet or orapki utilities, or come from any X.509v3-compliant CA, such as CMS.

Before importing a Sub CA signing wallet, you must

• Install OracleAS Certificate Authority successfully, which will create its repository, the password store, the Root CA signing wallet, and the CA SSL wallet.

• Ensure that the wallet is free of corruption and contains one or more self-signed certificates. You can verify a wallet with the orapki wallet display command.

Then take the following steps:

1. Stop OC4J and OHS if they are running, using these commands:

   $ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=OracleAS Certificate Authority 
   $ORACLE_HOME/opmn/bin/opmnctl stopproc type=ohs
   
   

2. Use the ocactl importwallet command to install the Sub CA signing wallet:

   ocactl importwallet -type SUBCA
   
   

The command prompts for the administrator's password, for the directory where the wallet for the new Sub CA (ewallet.p12) is stored, and for that wallet's password. It then fetches the new CA's certificate and private key from that wallet, and stores them in the OracleAS Certificate Authority repository. The password used for the new CA's wallet, provided in response to the command prompts, is the new CA's signing password. This password now becomes the password of the OracleAS Certificate Authority Administrator.

See Appendix B, "Setting up a CA Hierarchy" for further detailed description in the present manual.

The former root CA certificate entry and all other certificates issued by that former root CA will become invalid. The old CA certificate and key in the OracleAS Certificate Authority repository will be overwritten by the new Sub CA certificate and key, respectively. The new Sub CA certificate's entry and Serial number will be added to the repository so that certificates issued by this Sub CA will have serial numbers greater than the serial number of the Sub CA certificate. Also, any administrator certificate issued by the old CA is removed from the password store. While importing Sub CA signing wallet, ocactl ensures that the correct bits are set for BasicConstraintsExtension and KeyUsageExtensions to be DIGITAL_SIGNATURE, KEY_CERT_SIGN, CRL_SIGN and NON_REPUDIATION. Otherwise, if these extensions are not set, the wallet will not be accepted as Sub CA signing wallet.

A.12 Generating a CA SSL Wallet for a Sub CA

As is described in "Regenerating the Certificate Authority's SSL Certificate and Wallet", the CA SSL certificate and wallet are generated during installation. They enable OracleAS Certificate Authority to listen in HTTPS mode, and they can be regenerated if they become compromised or corrupted, in order to reestablish secure communications.

Generating the Sub CA SSL wallet is also done when OracleAS Certificate Authority is not running, using this command:

ocactl generatewallet -type CASSL 

This wallet is signed by the Sub CA and stored in the directory $ORACLE_HOME/oca/wallet/ssl, encrypted by the password requested during its generation.

As root user, you can convert this wallet to OracleAS Single Sign-On format using the command

ocactl convertwallet -format SSO

Once you install a Sub CA, the earlier CA that issued the SSL certificate no longer exists. Clients connecting to OracleAS Certificate Authority will trust the current CA certificate. The CASSL issued by the previous CA is not trusted, so you should regenerate the CASSL certificate after importing Sub CA or after a CASSL wallet is corrupted or compromised.

After generating this CA SSL certificate and wallet, do the following steps:

1. Start HTTP Server.

2. Start OC4J.

3. Start OracleAS Certificate Authority.

OracleAS Certificate Authority will now use the Sub CA certificate for signing certificate requests.

A.13 Clearing Log or Trace Storage

The administrative command line tool enables removal of existing log or trace files at the administrator's choice. The clear command has the following format:

ocactl clear -type {LOG |TRACE} -mode {OCA|ADMIN}

The possible commands are

• ocactl clear -type LOG -mode ADMIN

• ocactl clear -type TRACE -mode ADMIN

• ocactl clear -type LOG -mode OCA

• ocactl clear -type TRACE -mode OCA

The result of each such command is to remove the corresponding log or trace data: clearing log data removes it from the OracleAS Certificate Authority repository; clearing trace data removes the file oca.trc from $ORACLE_HOME/oca/logs.

A.14 Updating OracleAS Certificate Authority Repository Connection Information

The connection information used for publishing certificates is displayed under Settings in the General subtab of the OracleAS Certificate Authority web interface for the administrator. This information includes the connection strings that OracleAS Certificate Authority uses to connect to its repository and to Oracle Internet Directory.

The ocactl command updateconnection writes the connection information into the OracleAS Certificate Authority configuration file $ORACLE_HOME/oca/conf/oca.conf.

OracleAS Certificate Authority connection information is originally written to Oracle Internet Directory when Oracle Application Server is installed, when it is also fetched from Oracle Internet Directory and written into oca.conf. This information changes if OracleAS Certificate Authority is moved to another database.

A.15 Setting SSO Authentication (linksso, unlinksso commands)

Single Sign-on authentication facilitates fast access to resources and applications, and is even more rapid and efficient when certificates are used in place of username and password.

OracleAS Certificate Authority has an expedited process to enable OracleAS Single Sign-On Server-authenticated users to request and receive such certificates.

When the OracleAS Certificate Authority administrator executes the ocactl linksso command, it registers OracleAS Certificate Authority with the OracleAS Single Sign-On server to display the certificate authority's certificate enrollment form to OracleAS Single Sign-On users who lack a certificate. Using the short process thus presented, such users can request a certificate, which OracleAS Certificate Authority then issues, and the user can import it into the browser for future authentication.

All aspects of this process are discussed in Chapter 4, "Introduction to Administration and Certificate Management", in the section titled "Single Sign-on and OracleAS Certificate Authority". An overview appears in Chapter 7, "OracleAS Certificate Authority Administration: Advanced Topics", in the section "OracleAS Certificate Authority and High-Availability Features".

The ocactl linksso command does not require OracleAS Certificate Authority service to be shut down, but it takes effect only after the OracleAS Single Sign-On Server is restarted.

A.16 Setting Log/Trace Options

The administrator can initiate logging and tracing operations with the ocactl set command, specifying which type of data is desired and turning its generation on or off. The forms of the command are as follows:

• ocactl set -type LOG -mode OCA -state ON

• ocactl set -type LOG -mode ADMIN -state ON

• ocactl set -type TRACE -mode OCA -state ON

• ocactl set -type TRACE -mode ADMIN -state ON

Data generated by these commands is stored in the following locations:

• OracleAS Certificate Authority LOG data goes into the OracleAS Certificate Authority repository.

• ADMIN LOG data goes into the admin.log file at $ORACLE_HOME/oca/logs.

• TRACE data goes into one of two files at $ORACLE_HOME/oca/logs:

  • OracleAS Certificate Authority trace goes to oca.trc, that is, $ORACLE_HOME/oca/logs/oca.trc.

  • ADMIN trace goes to admin.trc, that is, $ORACLE_HOME/oca/logs/admin.trc.

The OFF commands stop the process of generating LOG or TRACE data. Data already collected remains in the indicated locations until an ocactl clear command is issued. Files affected by such ocactl clear commands (oca.trc, admin.trc, or admin.log) are simply removed from the file system.