10g (9.0.4)
Part Number B10663-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle® Application Server Certificate Authority Administrator's Guide 10g (9.0.4) Part Number B10663-01 |
|
This Appendix is a "quick help" reference to commands and options available through using the Oracle Application Server Certificate Authority command-line tool ocactl. The detailed usage of these commands, with use cases, will be explained in Advanced Topics.
This Appendix describes how to do Oracle Application Server Certificate Authority administration tasks using the command line tool ocactl, operating through the computer hosting the Oracle Application Server Certificate Authority.
This chapter contains the following topics:
|
Link to General Topic |
Links to Specific Subtopics |
|---|---|
|
Commands and Operations |
|
|
Root Certificate Operations |
|
|
SSL/SSO Operations |
|
|
Sub-CA Operations |
|
|
Log/Trace Operations |
As the OCA administrator, you use the command line tool named ocactl to specify the parameters needed to perform the various Oracle Application Server Certificate Authority operations. (You may need to add oca/bin to your path.) Each time this tool is invoked it requests your OCA 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
For example, to start Oracle Application Server Certificate Authority, you would enter
As another example, to generate a certificate and wallet for CASSL operations in publishing certificates with mutual authentication between Oracle Application Server Certificate Authority and Oracle Internet Directory, you would enter
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-1.
Table A-1 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:
changeschema, changesecurity, clear, generatewallet, help, importwallet, linksso, renewcert, revokecert, set, setpasswd, start, stop, unlinksso, updateconnection
|
Operation |
Parameters |
Meaning |
|---|---|---|
|
|
|
Used when the entire database is changed to a different one and the data is migrated to the new database.
|
|
changesecurity |
|
Changes the Identity Management services (OID/SSO) used by OCA to the new OID and SSO server.
|
|
clear |
OCA or ADMIN |
Clears the storage location specified in a prior Examples of each command appear in Chapter 6, "OracleAS Certificate Authority Administration: Advanced Topics" at Log or Trace OCA Actions for Oracle Application Server Certificate Authority. |
|
convertwallet |
See later discussion |
after this table: "Convertwallet" Explained with Examples. |
|
|
CA, |
Generates a certificate and wallet for the type specified: certificate authority signing certificate, or certificate authority SSL certificate certificate.
A sample "generatewallet" command will thus look like this: Wallets of the type named below are store in the indicated place:
CA
CASSL
CASMIME |
|
help |
<command name> |
Shows the syntax for the command specified by name.
A sample "help" command will thus look like the following: |
|
importwallet |
SUBCA |
After prompting for the directory where the wallet should be stored, and the administrator's password, this command installs a wallet named ewallet.p12: a subordinate CA server wallet.
A sample "importwallet" command will thus look like this: |
|
linksso |
<none> |
Registers OCA with SSO to display OCA certificate enrollment form to SSO users who lack a certificate, so they can request one. (This command does not require OCA service to be shut down, but it won't take effect until the SSO server is restarted.) |
|
|
CA, |
When OCA is not running, the administrator can use this command to renew the specified certificate, with a prompt for a new validity period, in days.
A sample "renewcert" command will thus look like this: |
|
(Revoking CA makes your OCA installation inoperable.) |
CA |
Usable only when OCA is not operating. Revokes the root CA certificate. See "Revoking a Root CA Certificate" for additional reasons specifiable with the CA parameter.
A sample "revokecert" command will thus look like this: Please refer to Table A-2 for details on revocation reasons. |
|
set |
|
Sets the OCA configuration to use the additional parameters for state (ON or OFF) or mode (OCA or ADMIN) specified after LOG or TRACE, as follows: Examples of each command appear in Chapter 6, "OracleAS Certificate Authority Administration: Advanced Topics" at Log or Trace OCA Actions for Oracle Application Server Certificate Authority. |
|
setpasswd |
CA, |
Requests and resets the password for the specified role: administrator, database administrator, directory, OCA user, or certificate authority SSL server. See text for detailed description of the use, setting, and storage of passwords relating to certificate generation and usage.
A sample "setpasswd" command will thus look like this: |
|
|
<no parameters> |
Starts the Oracle Application Server Certificate Authority service. (OC4J, OHS, and the database must already be in operation for OCA to start. You control OC4J and OHS by the command-line tool
A sample "start" command will thus look like the following: |
|
|
<no parameters> |
Displays the status of the Oracle Application Server Certificate Authority services.
A sample "status" command will thus look like this: |
|
|
<no parameters> |
Stops the Oracle Application Server Certificate Authority service.
(Does not stop database, web server, or OracleAS.
A sample "stop" command will thus look like the following: |
|
unlinksso |
<none> |
De-registers OCA from SSO, so the screens for welcome and enrollment form will not be shown. (This command does not require OCA service to be shut down, but it won't take effect until the SSO server is restarted.) |
|
updateconnection |
<no parameters> |
Writes the connection information stored in Oracle Internet Directory (OID) for connecting to the OCA repository and directory (used for publishing certificates) into the OCA configuration file OCA connection information is originally written to OID when OracleAS is installed, when it is also fetched from OID and written into oca.conf. This information changes if OCA is moved to another database. Also used in RAC-enabled database when the connect string is changed because more RAC nodes are added or removed. No data needs to be migrated. |
Table A-1 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.
The convertwallet command is used to convert an SSL Server wallet (ewallet.p12, in PKCS#12 format) into a wallet in the SSO format, with file name cwallet.sso.
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. This password is usually requested when HTTP Server starts up in SSL mode, using a PKCS#12 wallet.
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 SSO (single sign-on) to bring up the web server in SSL mode automatically, without asking a human for the wallet password.
The convertwallet syntax is:
For example,
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 OCA during OCA's installation. This command therefore uses the OCA 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).
Oracle Application Server Certificate Authority will use the new SSO wallet stored at $ORACLE_HOME/oca/wallet/ssl/ only after OHS, OCA's OC4J, and Oracle Application Server Certificate Authority are restarted (in that order). (To start the required infrastructure, see section 4.1 in Oracle Application Server 10g Administrator's Guide. To start middle tier components like OHS and OC4J, see section 4.2.)
After OC4J, OHS, and the database are operating, you can start the Oracle Application Server Certificate Authority services that support the forms for administrator and user access. To start OC4J and OHS, use the command-line tool opmnctl as follows:
$ORACLE_HOME/opmn/bin/opmnctl startproc type=oc4j instancename=oca $ORACLE_HOME/opmn/bin/opmnctl startproc type=ohs
To start Oracle Application Server Certificate Authority, issue the following command:
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 an XML configuration file.
The stop command stops the Oracle Application Server Certificate Authority services. No other services are affected: database, OracleAS, and web server remain unchanged.
To stop the Oracle Application Server Certificate Authority services, issue the following command:
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 Oracle Application Server Certificate Authority engine. The response shows whether the following facilities are open or closed: the database connection pool; logger, tracer, and XML files; and the password store.
To get the Oracle Application Server Certificate Authority services status, issue this command:
Installation creates the Oracle Application Server Certificate Authority password store, which contains the initial passwords required for OCA operations:
The contents of this password store are encrypted using the OCA 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:
With the exception of the database password (DB), all other passwords can be changed even when Oracle Application Server Certificate Authority is in operation. The possibility of active connections to the CA, using the existing DB password, precludes allowing the DB password to be changed until Oracle Application Server Certificate Authority has been stopped. After the DB password is changed while Oracle Application Server Certificate Authority is stopped, the new password will be required to start it and will be used while it is in operation.
The changes resulting from executing these commands take effect after the next start of Oracle Application Server Certificate Authority. Until the Certificate Authority is restarted, the new passwords will not be used: the referenced wallets will remain usable as encrypted with the old passwords, because that information is already stored in memory. After Oracle Application Server Certificate Authority is restarted, the new passwords will be in effect.
Each use of ocactl requires the OCA 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 OCA administrator password.
When installing Oracle Application Server 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 command line tool. The new CA certificate and private key will be stored in the OCA 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 CA wallet, a CRL issued by old CA will not be useful.
|
See:
Chapter 6, "OracleAS Certificate Authority Administration: Advanced Topics", specifically the sections entitled Regenerating the CA Signing Wallet and Regenerating the CA SSL and CA SMIME Wallets. |
This can only be done after OCA is successfully installed and OCA service is not running.
The root CA wallet can be generated only when OCA is not running. If OCA is running, stop OCA and use this command to regenerate the Root CA wallet:
This certificate is stored as a binary file in the directory
$ORACLE_HOME/oca/wallet/ca.
The signing key is stored in the directory $ORACLE_HOME/oca/wallet/ca, encrypted by the OCA administrator password.
The password store is kept in the directory $ORACLE_HOME/oca/pwdstore.
The CA SSL certificate and wallet are generated during installation and are used to enable the Oracle Application Server Certificate Authority engine to listen in HTTPS mode. If these are compromised or corrupted, or the CA wallet is regenerated, you must regenerate them in order to re-establish secure communications.
The CA SSL wallet can be generated only when OCA is not running. If OCA is running, stop OCA and use this command to regenerate the CA SSL certificate and wallet:
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 SSO format and stores it as cwallet.sso at $ORACLE_HOME/oca/wallet/ssl.
Revoking a root CA certificate is a very drastic operation, which will make OCA 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 OCA Administrator's certificate. It can only be used when OCA is not operating.
Revoking a root certificate authority certificate is required before installing a new root CA for ongoing OCA operations.
When you intend to install a new CA, use revokecert first to revoke the old CA 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 OCA repository.
Once the OCA 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 OCA. 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:
revokecert Command
You can use the command line tool's convertwallet command to convert a CA SSL server wallet into Oracle Single Sign-on (SSO) format. The command uses the current CA SSL wallet location, unless you specify a different location.
To convert the CA SSL Server wallet to SSO format, issue the following command as root user, with <wlt-location> replaced by the desired destination:
The optional parameter -walletwrl identifies the next parameter as specifying the source location where the CA SSL PKCS#12 wallet is presently located. It should be stored in the filename ewallet.p12 in that directory. 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 <wlt-location>.
If this source location is not specified, then ocactl assumes the wallet is the CA SSL wallet generated by OCA during OCA's installation. This command therefore uses the OCA 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).
You can generate a Sub CA wallet from Oracle Application Server Certificate Authority as follows:
The steps in this section enable you to install and use a Sub CA wallet, creating a hierarchy of CAs. This wallet can be one generated from Oracle Application Server Certificate Authority, as in Generating a Sub CA Wallet from Oracle Application Server Certificate Authority, or come from any X.509v3-compliant CA, such as CMS.
Before importing a Sub CA wallet, you must install Oracle Application Server Certificate Authority successfully, which will create its repository, the password store, the Root CA wallet, and the CA SSL wallet. Then do the following steps:
$ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=oca $ORACLE_HOME/opmn/bin/opmnctl stopproc type=ohs
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 OCA 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 OCA 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 Oracle Application Server 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 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 wallet.
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 Oracle Application Server Certificate Authority to listen in HTTPS mode, and they can be regenerated if they become compromised or corrupted, in order to re-establish secure communications.
Generating the Sub CA SSL wallet is also done when OCA is not running, using this command:
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 SSO format using the command
Once you install a Sub CA, the earlier CA that issued the SSL certificate no longer exists. Clients connecting to OCA 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:
Oracle Application Server Certificate Authority will now use the Sub CA certificate for signing certificate requests.
The command line tool enables removal of existing log or trace files at the administrator's choice. The clear command has the following format:
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 OCA repository; clearing trace data removes the file oca.trc from $ORACLE_HOME/oca/logs.
The connection information used for publishing certificates is displayed under Settings in the General subtab of the Oracle Application Server Certificate Authority web interface for the administrator. This information is stored in Oracle Internet Directory (OID) for connecting to the OCA repository and directory.
The ocactl command updateconnection writes the connection information into the OCA configuration file $ORACLE_HOME/oca/conf/oca.conf.
OCA connection information is originally written to OID when OracleAS is installed, when it is also fetched from OID and written into oca.conf. This information changes if OCA is moved to another database.
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.
Oracle Application Server Certificate Authority has an expedited process to enable SSO-authenticated users to request and receive such certificates.
When the OCA administrator executes the ocactl linksso command, it registers OCA with SSO to display OCA's certificate enrollment form to SSO users who lack a certificate. Using the short process thus presented, such users can request a certificate, which OCA then issues, and the user can import it into the browser for future authentication.
All aspects of this process are discussed in Chapter 3, "Introduction to OCA Administration and Certificate Management", in the section titled Single Sign-on (SSO) and OracleAS Certificate Authority (OCA). An overview appears in Chapter 6, "OracleAS Certificate Authority Administration: Advanced Topics", in the section OracleAS Certificate Authority and High-Availability Features.
The ocactl linksso command does not require OCA service to be shut down, but it takes effect only after the SSO server is restarted.
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 -state ON ocactl set -type TRACE -state ON ocactl set -type LOG -state OFF ocactl set -type TRACE -state OFF
Data generated by the first two commands above is stored in the following locations:
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 or Oracle Application Server Certificate Authority stops operating.
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|