|
Oracle® Application Server Certificate Authority Administrator's Guide
10g Release 2 (10.1.2) B14080-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Certificate Authority Administrator's Guide
10g Release 2 (10.1.2) B14080-02 |
|
|
Previous |
Next |
This Appendix is a "quick help" reference to commands and options available 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 OracleAS Certificate Authority administration tasks using the administrative command line tool ocactl, operating through the computer hosting the OracleAS Certificate Authority instance.
This chapter contains the following topics:
Table A-1 Links to Commands and Configuration Operations
| General Topic | Links to Specific Subtopics |
|---|---|
|
Basic Administration: Commands and Operations |
|
|
Root Certificate Operations |
|
|
SSL/OracleAS Single Sign-On Operations |
|
|
Sub-CA Operations |
|
|
Log/Trace Operations |
|
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
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
Table A-2 Operations and Parameters of the OracleAS Certificate Authority (OCA) ocactl Tool
| Operation | Parameters | Meaning |
|---|---|---|
|
-server_auth_port port
|
Changes the Identity Management services (Oracle Internet Directory/OracleAS Single Sign-On Server) used by OracleAS Certificate Authority to the new Oracle Internet Directory and OracleAS Single Sign-On. Updates oca.conf with the new IM machine and port number, and uses the specified port while registering OracleAS Certificate Authority with the new OracleAS Single Sign-On server. |
|
|
LOG, TRACE OracleAS Certificate Authority or ADMIN |
Clears the storage location specified in a prior Examples of each command appear in Chapter 7, "OracleAS Certificate Authority Administration: Advanced Topics" at Log or Trace OracleAS Certificate Authority Actions. |
|
|
convertwallet |
See next column |
See later discussion after this table: "Converting a CA SSL Server Wallet into SSO Form". |
|
|
Generates a certificate and wallet for the type specified: certificate authority signing certificate, or certificate authority SSL certificate. A sample "generatewallet" command will thus look like this: Wallets of the following type are stored in the indicated place:
For the CA, key size choices are 512, 1024, 2048, and 4096. Default is 2048. For CASSL and CASMIME, key size choices are 512, 768, 1024, and 2048, with 1024 the default. |
|
|
command name |
Shows the syntax for the command specified by name. A sample "help" command will thus look like the following: |
|
|
After prompting for the directory where the wallet should be stored, and the administrator's password, this command installs a wallet named ewallet.p12 as a subordinate CA server wallet. A sample Note: Before importing a wallet, ensure it is corruption-free and contains one or more self-signed certificates. You can verify a wallet with the |
||
|
none |
Registers OracleAS Certificate Authority with OracleAS Single Sign-On to display OracleAS Certificate Authority certificate enrollment form to OracleAS Single Sign-On users who lack a certificate, so they can request one. (This command does not require OracleAS Certificate Authority service to be shut down, but it won't take effect until the OracleAS Single Sign-On server is restarted.) |
|
|
|
CA, CASSL, CASMIME |
When OracleAS Certificate Authority 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 OracleAS Certificate Authority installation inoperable.) |
CA WEBADMIN (Be very careful and certain before taking this action.) |
Usable only when OracleAS Certificate Authority 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-5 for details on revocation reasons. |
|
ON or OFF OracleAS Certificate Authority or ADMIN
|
Sets the OracleAS Certificate Authority configuration to use the additional parameters for state (ON or OFF) or mode (OracleAS Certificate Authority or ADMIN) specified after LOG or TRACE, as follows: Examples of each command appear in Chapter 7, "OracleAS Certificate Authority Administration: Advanced Topics" at "Log or Trace OracleAS Certificate Authority Actions". The discussion in this Appendix is at "Setting Log/Trace Options". |
|
|
Requests and resets the password for the specified role: administrator, database administrator, certificate authority SSL server, or email encryption. OracleAS Certificate Authority must be stopped before changing passwords. See text for detailed description of the use, setting, and storage of passwords relating to certificate generation and usage. A sample |
||
|
|
no parameters |
Starts the OracleAS Certificate Authorityservice. (OC4J, OHS, and the database must already be in operation for OracleAS Certificate Authority to start. You control OC4J and OHS with the command-line tool A sample "start" command will thus look like the following: |
|
|
no parameters |
Displays the status of the OracleAS Certificate Authority services. A sample "status" command will thus look like this: |
|
|
no parameters |
Stops the OracleAS Certificate Authority service. (Does not stop database, web server, or Oracle Application Server. Relinquishes database connection pool; closes logger, tracer, and configuration data files.) A sample "stop" command will thus look like the following: |
|
|
none |
De-registers OracleAS Certificate Authority from the OracleAS Single Sign-On server, so the screens for welcome and enrollment form will not be shown. (This command does not require the OracleAS Certificate Authority service to be shut down, but it won't take effect until the OracleAS Single Sign-On server is restarted.) |
|
no parameters |
Writes the connection information stored in Oracle Internet Directory into the OracleAS Certificate Authority configuration file $ORACLE_HOME/oca/conf/oca.conf. These strings are used to
(This connection information is displayed under Settings in the General subtab of the OracleAS Certificate Authority web interface for the administrator.) OracleAS Certificate Authority connection information is originally written to Oracle Internet Directory when Oracle Application Server is installed; this data is then also fetched from Oracle Internet Directory and written into oca.conf. This information changes if OracleAS Certificate Authority is moved to another database or if any configuration information changes. Examples include altering nodes or ports in the connection strings, such as adding or removing RAC nodes in a RAC-enabled database. (No data needs to be migrated. If you are initiating a port change, use the proper steps as described in "Changing Infrastructure Ports" in Oracle Application Server Administrator's Guide.) Note: You must run
|
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]
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.)
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:
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.
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
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
Installation creates the Oracle Application Server Certificate Authority password store, which contains the initial passwords required for OracleAS Certificate Authority operations:
Table A-3 Password Types and Uses
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:
Table A-4 Privileged Roles and the setpasswd Command
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.
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.
|
See Also:
|
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.
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.
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:
Table A-5 Revocation Reasons for Use with revokecert Command
| Revocation Reason | Explanation |
|---|---|
|
|
The organization has decided to use a different root CA. |
|
|
There may be reason to distrust the root CA (for example, the CA may key may be compromised), so a new CA is required. |
|
|
The certificate is being held due to some suspicions. |
|
|
The present root CA has ceased operations, so a new CA is required. |
|
|
The user's private key has been compromised. |
|
|
Certificate status will be REVOKED, but this revoked certificate will not be added to the CRL. |
|
|
The root CA's certificate has been replaced. The old one must be removed and the new one installed. |
|
|
No reason is available or has been given. This is the default reason. |
You can generate a Sub CA signing wallet from OracleAS Certificate Authority as follows:
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 |
Using the Server/Sub CA enrollment form, submit the PKCS10 request and select certificate usage as CA signing.
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.
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.
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.
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.
Copy the BASE64 format of the Sub CA certificate and import it into Oracle Wallet Manager as a user certificate.
Save the Sub CA signing wallet using Oracle Wallet Manager. The wallet will be stored as ewallet.p12.
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:
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
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.
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:
OracleAS Certificate Authority will now use the Sub CA certificate for signing certificate requests.
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.
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.
|
See Also: See changesecurity, clear, generatewallet, help, importwallet, linksso, renewcert, revokecert, set, setpasswd, start, stop, unlinksso, and updateconnection in Table A-2. |
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.
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.
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.
