|
Oracle® Application Server Certificate Authority Administrator's Guide
10g Release 2 (10.1.2) Part No. B14080-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Certificate Authority Administrator's Guide
10g Release 2 (10.1.2) Part No. B14080-01 |
|
|
Previous |
Next |
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 administrative command line tool ocactl, operating through the computer hosting the Oracle Application Server Certificate Authority.
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 Server 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
ocactl <operation> -type <related-parameters, if any>
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
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 |
|---|---|---|
| changesecurity | -server_auth_port port
|
Changes the Identity Management services (Oracle Internet Directory/OracleAS Single Sign-On Server) used by OCA to the new Oracle Internet Directory and OracleAS Single Sign-On Server.
Updates oca.conf with the new IM machine and port number, and uses the specified port while registering OCA with the new OracleAS Single Sign-On Server. |
| clear | LOG, TRACE
OCA or ADMIN |
Clears the storage location specified in a prior set command, either a file or a database table, for the type of log or trace data chosen, either OCA or ADMIN. (If OCA is not running, all such data is cleared.)
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: Converting a CA SSL Server Wallet into SSO Form ("Convertwallet"). |
| generatewallet
|
CA, CASSL, or CASMIME | 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 type named below are store 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. |
| 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 OracleAS Single Sign-On Server to display OCA certificate enrollment form to OracleAS Single Sign-On Server 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 OracleAS Single Sign-On Server is restarted.) |
| renewcert
|
CA, CASSL, CASMIME | 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:
|
| revokecert
(Revoking CA makes your OCA installation inoperable.) |
CA WEBADMIN (Be very careful and certain before taking this action.) | 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-5 for details on revocation reasons. |
| set | LOG or TRACE,
ON or OFF OCA or ADMIN
|
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". The discussion in this Appendix is at "Setting Log/Trace Options". |
| setpasswd | CA,
DB,
CASSL,
or
CASMIME
|
Requests and resets the password for the specified role: administrator, database administrator, certificate authority SSL server, or email encryption. OCA 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 "setpasswd" command will thus look like this:
|
| start
|
<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 opmn.)
A sample "start" command will thus look like the following:
|
| status
|
<no parameters> | Displays the status of the Oracle Application Server Certificate Authority services.
A sample "status" command will thus look like this:
|
| stop
|
<no parameters> | Stops the Oracle Application Server Certificate Authority service.
(Does not stop database, web server, or OracleAS. Relinquishes database connection pool; closes logger, tracer, and configuration data files.) A sample "stop" command will thus look like the following:
|
| unlinksso
|
<none> | De-registers OCA from OracleAS Single Sign-On Server, 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 OracleAS Single Sign-On Server is restarted.) |
| updateconnection | <no parameters> | Writes the connection information stored in Oracle Internet Directory into the OCA 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 Oracle Application Server Certificate Authority web interface for the administrator.) OCA connection information is originally written to Oracle Internet Directory when OracleAS is installed; this data is then also fetched from Oracle Internet Directory and written into oca.conf. This information changes if OCA 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 ocactl updateconnection after any such change to configuration settings, and after using this command, you must restart OCA by issuing the following commands: $ORACLE_HOME/oca/bin/ocactl stop $ORACLE_HOME/oca/bin/ocactl start |
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 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 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 OracleAS Single Sign-On Server 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 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 OHS and OCA's OC4J, use opmnctl commands in the following order:
$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 initializing configuration.
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 commands to stop OCA's OC4J process and OCA itself:
$ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=oca 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 Oracle Application Server 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 Oracle Application Server 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 OCA operations:
Table A-3 Password Types and Uses
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:
Table A-4 Privileged Roles and the setpasswd Command
OCA must be stopped before any password can be changed.
The changes resulting from executing these commands take effect after the next start of Oracle Application Server Certificate Authority. 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 administrative 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 the CA signing wallet, a CRL issued by the 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.For general information on SMIME, see Appendix G, "SMIME with OracleAS Certificate Authority" |
Regenerating the CA signing wallet and other critical wallets can only be done after OCA is successfully installed and OCA service is not running.
The root CA signing 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 signing wallet:
ocactl generatewallet -type CA
This certificate is stored in the OCA repository.
The signing key is also stored in the OCA repository, encrypted by the OCA 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 Oracle Application Server 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 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:
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 Server 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 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 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:
Table A-5 Revocation Reasons for Use with revokecert Command
| Revocation Reason | Explanation |
|---|---|
AFFILIATION_CHANGE
|
The organization has decided to use a different root CA. |
CA_COMPROMISE
|
There may be reason to distrust the root CA, so a new CA is required. |
CERTIFICATE_HOLD
|
The certificate is being held due to some suspicions. |
CESSATION_OF_OPERATION
|
The present root CA has ceased operations, so a new CA is required. |
KEY_COMPROMISE
|
The root CA's key has been compromised, so certificates based on it may not in fact be trustworthy. |
REMOVE_FROM_CRL
|
Certificate status will be REVOKED, but this revoked certificate will not be added to the CRL. |
SUPERSEDED
|
The root CA's certificate has been replaced. The old one must be removed and the new one installed. |
UNSPECIFIED
|
No reason is available or has been given. This is the default reason. |
You can generate a Sub CA signing wallet from Oracle Application Server 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 Oracle Application Server Certificate Authority Administrative form, issue a Sub CA certificate. Please specify the path-length, i.e., 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 one generated from Oracle Application Server Certificate Authority, as in Generating a Sub CA Signing Wallet from OCA, or come from any X.509v3-compliant CA, such as CMS.
Before importing a Sub CA signing wallet, you must install Oracle Application Server Certificate Authority successfully, which will create its repository, the password store, the Root CA signing wallet, and the CA SSL wallet. Then do the following steps:
Stop OC4J and OHS if they are running, using these commands:
$ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=oca $ORACLE_HOME/opmn/bin/opmnctl stopproc type=ohs
Use the ocactl importwallet command to install the Sub CA signing wallet, which is
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 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 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:
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 Server 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 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 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 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 includes the connection strings that OCA uses to connect to its repository and to Oracle Internet Directory.
The ocactl command updateconnection writes the connection information into the OCA configuration file $ORACLE_HOME/oca/conf/oca.conf.
|
Note: See changesecurity, clear, generatewallet, help, importwallet, linksso, renewcert, revokecert, set, setpasswd, start, stop, unlinksso, and updateconnection in Table A-2. |
OCA connection information is originally written to Oracle Internet Directory when OracleAS is installed, when it is also fetched from Oracle Internet Directory 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 OracleAS Single Sign-On Server-authenticated users to request and receive such certificates.
When the OCA administrator executes the ocactl linksso command, it registers OCA with OracleAS Single Sign-On Server to display OCA's certificate enrollment form to OracleAS Single Sign-On Server 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 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 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:
OCA LOG data goes into the OCA 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:
OCA trace goes to oca.trc, i.e., $ORACLE_HOME/oca/logs/oca.trc.
ADMIN trace goes to admin.trc, i.e., $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.
