Fusion Middleware Documentation
Advanced Search


Administering Oracle Fusion Middleware
Close Window

Table of Contents

Show All | Collapse

G orapki

Oracle Application Server 10g provided the orapki utility, a command-line tool to manage certificate revocation lists (CRLs), create and manage Oracle wallets, and create signed certificates for testing purposes. It also provided the SSL Configuration Tool.

Oracle Fusion Middleware 12c (12.1.2) provides both command-line and graphical user interfaces to configure SSL. The Oracle WebLogic Scripting Tool (WLST) and Oracle Enterprise Manager Fusion Middleware Control enable you to manage KSS- and JKS-based keystores, wallets, and certificates.

Use this appendix to learn about how to transition from pre-12c tools like orapki to the certificate, wallet management, and SSL configuration tools provided in 12c (12.1.2). The appendix contains these topics:

See Also:

:

Note:

The orapki utility is located in the binary directory of Oracle Common home, that is, $ORACLE_HOME/oracle_common/bin.

G.1 Using the orapki Utility for Certificate Validation and CRL Management

This section contains these topics:

G.1.1 orapki Overview

The orapki utility is provided to manage public key infrastructure (PKI) elements, such as wallets and certificate revocation lists, on the command line so the tasks it performs can be incorporated into scripts. This enables you to automate many of the routine tasks of maintaining a PKI.

This command-line utility can be used to perform the following tasks:

  • Creating signed certificates for testing purposes

  • Managing Oracle wallets:

    • Creating and displaying Oracle wallets

    • Adding and removing certificate requests

    • Adding and removing certificates

    • Adding and removing trusted certificates

  • Managing certificate revocation lists (CRLs):

    • Renaming CRLs with a hash value for certificate validation

orapki allows you to import certificates in both DER and PEM formats.

G.1.1.1 orapki Syntax

The basic syntax of the orapki command-line utility is as follows:

orapki module command -parameter value

In the preceding command, module can be wallet (Oracle wallet), crl (certificate revocation list), or cert (PKI digital certificate). The available commands depend on the module you are using. For example, if you are working with a wallet, then you can add a certificate or a key to the wallet with the add command. The following example adds the user certificate located at /private/lhale/cert.txt to the wallet located at ORACLE_HOME/wallet/ewallet.p12:

orapki wallet add -wallet ORACLE_HOME/wallet/ewallet.p12
-user_cert -cert /private/lhale/cert.txt

G.1.1.2 Environment Setup for orapki

When running orapki in the context of Web Tier or Classic installations, set ORACLE_HOME to point to the product installation location.

G.1.2 Displaying orapki Help

You can display all the orapki commands that are available for a specific mode by entering the following at the command line:

orapki mode help

For example, to display all available commands for managing certificate revocation lists (CRLs), enter the following at the command line:

orapki crl help

Note:

Using the -summary, -complete, or -wallet command options is always optional. A command will still run if these command options are not specified.

G.1.3 Creating Signed Certificates for Testing Purposes

This command-line utility provides a convenient, lightweight way to create signed certificates for testing purposes. The following syntax can be used to create signed certificates and to view certificates:

To create a signed certificate for testing purposes:

orapki cert create [-wallet wallet_location] -request
 certificate_request_location
-cert certificate_location -validity number_of_days [-summary]

This command creates a signed certificate from the certificate request. The -wallet parameter specifies the wallet containing the user certificate and private key that will be used to sign the certificate request. The -validity parameter specifies the number of days, starting from the current date, that this certificate will be valid. Specifying a certificate and certificate request is mandatory for this command.

To view a certificate:

orapki cert display -cert certificate_location [-summary | -complete]

This command enables you to view a test certificate that you have created with orapki. You can choose either -summary or -complete, which determines how much detail the command will display. If you choose -summary, the command will display the certificate and its expiration date. If you choose -complete, it will display additional certificate information, including the serial number and public key.

G.1.4 Managing Oracle Wallets with the orapki Utility

The following sections describe the syntax used to create and manage Oracle wallets with the orapki command-line utility. You can use these orapki utility wallet module commands in scripts to automate the wallet creation process.

G.1.4.1 Creating and Viewing Oracle Wallets with orapki

To create an Oracle wallet:

orapki wallet create -wallet wallet_location

This command will prompt you to enter and re-enter a wallet password. It creates a wallet in the location specified for -wallet.

To create an Oracle wallet with auto-login enabled:

orapki wallet create -wallet wallet_location -auto_login

This command creates a wallet with auto-login enabled, or it can also be used to enable auto-login on an existing wallet. If the wallet_location already contains a wallet, then auto-login will be enabled for it. To disable the auto-login feature, delete cwallet.sso.

Note:

For wallets with the auto-login feature enabled, you are prompted for a password only for operations that modify the wallet, such as add.

To view an Oracle wallet:

orapki wallet display -wallet wallet_location

This command displays the certificate requests, user certificates, and trusted certificates contained in the wallet.

G.1.4.2 Adding Certificates and Certificate Requests to Oracle Wallets with orapki

To add a certificate request to an Oracle wallet:

orapki wallet add -wallet wallet_location -dn user_dn -keysize 512|1024|2048|4096

This command adds a certificate request to a wallet for the user with the specified distinguished name (user_dn). The request also specifies the requested certificate's key size (512, 1024, or 2048 bits). To sign the request, export it with the export option. See Section G.1.4.3, "Exporting Certificates and Certificate Requests from Oracle Wallets with orapki."

To add a trusted certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -trusted_cert -cert
certificate_location

This command adds a trusted certificate, at the specified location (-cert certificate_location), to a wallet. You must add all trusted certificates in the certificate chain of a user certificate before adding a user certificate, or the command to add the user certificate will fail.

To add a root certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -dn
certificate_dn -keysize 512|1024|2048 -self_signed -validity number_of_days

This command creates a new self-signed (root) certificate and adds it to the wallet. The -validity parameter (mandatory) specifies the number of days, starting from the current date, that this certificate will be valid. You can specify a key size for this root certificate (-keysize) of 512, 1024, 2048, or 4096 bits.

To add a user certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -user_cert -cert certificate_location

This command adds the user certificate at the location specified with the -cert parameter to the Oracle wallet at the wallet_location. Before you add a user certificate to a wallet, you must add all the trusted certificates that make up the certificate chain. If all trusted certificates are not installed in the wallet before you add the user certificate, then adding the user certificate will fail.

G.1.4.3 Exporting Certificates and Certificate Requests from Oracle Wallets with orapki

To export a certificate from an Oracle wallet:

orapki wallet export -wallet wallet_location -dn
certificate_dn -cert certificate_filename

This command exports a certificate with the subject's distinguished name (-dn) from a wallet to a file that is specified by -cert.

To export a certificate request from an Oracle wallet:

orapki wallet export -wallet wallet_location -dn
certificate_request_dn -request certificate_request_filename

This command exports a certificate request with the subject's distinguished name (-dn) from a wallet to a file that is specified by -request.

G.1.5 Managing Certificate Revocation Lists (CRLs) with orapki Utility

CRLs must be managed with orapki. This utility creates a hashed value of the CRL issuer's name to identify the CRLs location in your system. If you do not use orapki, your Oracle server cannot locate CRLs to validate PKI digital certificates. The following sections describe CRLs, how you use them, and how to use orapki to manage them:

See Also:

"Certificate Revocation List Management" in the Oracle Advanced Security Administrator's Guide for details about managing CRLs with orapki:

http://docs.oracle.com/cd/E11882_01/network.112/e10746/asossl.htm

G.1.5.1 About Certificate Validation with Certificate Revocation Lists

The process of determining whether a given certificate can be used in a given context is referred to as certificate validation. Certificate validation includes determining that:

  • A trusted certificate authority (CA) has digitally signed the certificate.

  • The certificate's digital signature corresponds to the independently-calculated hash value of the certificate itself and the certificate signer's (CA's) public key.

  • The certificate has not expired.

  • The certificate has not been revoked.

The SSL network layer automatically performs the first three validation checks, but you must configure certificate revocation list (CRL) checking to ensure that certificates have not been revoked. CRLs are signed data structures that contain a list of revoked certificates. They are usually issued and signed by the same entity who issued the original certificate.

G.1.5.1.1 What CRLs Should You Use?

You should have CRLs for all of the trust points that you honor. The trust points are the trusted certificates from a third-party identity that is qualified with a level of trust. Typically, the certificate authorities you trust are called trust points.

G.1.5.1.2 How CRL Checking Works

Certificate revocation status is checked against CRLs which are located in file system directories, or downloaded from the location specified in the CRL Distribution Point (CRL DP) extension on the certificate. If you store your CRLs on the local file system or in the directory, then you must update them regularly. If you use CRL DPs then CRLs are downloaded when the corresponding certificates are first used.

The server searches for CRLs in the following locations in the order listed. When the system finds a CRL that matches the certificate CA's DN, it stops searching.

  1. Local file system

    The system checks the sqlnet.ora file for the SSL_CRL_FILE parameter first, followed by the SSL_CRL_PATH parameter. If these two parameters are not specified, then the system checks the wallet location for any CRLs.

    Note: if you store CRLs on your local file system, then you must use the orapki utility to periodically update them. See Section G.1.5.2.1, "Renaming CRLs with a Hash Value for Certificate Validation."

  2. CRL DP

    If the CA specifies a location in the CRL DP X.509, version 3, certificate extension when the certificate is issued, then the appropriate CRL that contains revocation information for that certificate is downloaded. Currently, Oracle Advanced Security supports downloading CRLs over HTTP and LDAP.

    Notes:

    • For performance reasons, only user certificates are checked.

    • Oracle recommends that you store CRLs in the directory rather than the local file system.

G.1.5.2 Certificate Revocation List Management

Before you can enable certificate revocation status checking, you must ensure that the CRLs you receive from the CAs you use are in a form (renamed with a hash value) or in a location (uploaded to the directory) in which your system can use them. Oracle Advanced Security provides a command-line utility, orapki, that you can use to perform the following task:

Note:

CRLs must be updated at regular intervals (before they expire) for successful validation. You can automate this task by using orapki commands in a script.

See Also:

Command-Line Tools Overview in the Oracle Fusion Middleware Reference for Oracle Identity Management for information about LDAP command-line tools and their syntax.

G.1.5.2.1 Renaming CRLs with a Hash Value for Certificate Validation

When the system validates a certificate, it must locate the CRL issued by the CA who created the certificate. The system locates the appropriate CRL by matching the issuer name in the certificate with the issuer name in the CRL.

When you specify a CRL storage location for the Certificate Revocation Lists Path field in Oracle Net Manager (sets the SSL_CRL_PATH parameter in the sqlnet.ora file), use the orapki utility to rename CRLs with a hash value that represents the issuer's name. Creating the hash value enables the server to load the CRLs.

On UNIX systems, orapki creates a symbolic link to the CRL. On Windows systems, it creates a copy of the CRL file. In either case, the symbolic link or the copy created by orapki are named with a hash value of the issuer's name. Then when the system validates a certificate, the same hash function is used to calculate the link (or copy) name so the appropriate CRL can be loaded.

Depending on your operating system, enter one of the following commands to rename CRLs stored in the file system.

To rename CRLs stored in UNIX file systems:

orapki crl hash -crl crl_filename [-wallet wallet_location]
-symlink crl_directory [-summary]

To rename CRLs stored in Windows file systems:

orapki crl hash -crl crl_filename
[-wallet wallet_location] -copy crl_directory [-summary]

In the preceding commands, crl_filename is the name of the CRL file, wallet_location is the location of a wallet that contains the certificate of the CA that issued the CRL, and crl_directory is the directory in which the CRL is located.

Using -wallet and -summary are optional. Specifying -wallet causes the tool to verify the validity of the CRL against the CA's certificate prior to renaming the CRL. Specifying the -summary option causes the tool to display the CRL issuer's name.

G.1.6 orapki Utility Commands Summary

This section lists and describes the following orapki commands:

G.1.6.1 orapki cert create

The following sections describe this command.

G.1.6.1.1 Purpose

Use this command to create a signed certificate for testing purposes.

G.1.6.1.2 Syntax
orapki cert create [-wallet wallet_location]
-request certificate_request_location
-cert certificate_location -validity number_of_days [-summary]
  • The -wallet parameter specifies the wallet containing the user certificate and private key that will be used to sign the certificate request.

  • The -request parameter (mandatory) specifies the location of the certificate request for the certificate you are creating.

  • The -cert parameter (mandatory) specifies the directory location in which the tool places the new signed certificate.

  • The -validity parameter (mandatory) specifies the number of days, starting from the current date, that this certificate will be valid.

G.1.6.2 orapki cert display

The following sections describe this command.

G.1.6.2.1 Purpose

Use this command to display details of a specific certificate.

G.1.6.2.2 Syntax
orapki cert display -cert certificate_location [-summary|-complete]
  • The -cert parameter specifies the location of the certificate you want to display.

  • You can use either the -summary or the -complete parameter to display the following information:

    • -summary displays the certificate and its expiration date

    • -complete displays additional certificate information, including the serial number and public key

G.1.6.3 orapki crl create

The following sections describe this command.

G.1.6.3.1 Purpose

Use this command to create a CRL.

G.1.6.3.2 Syntax
orapki crl create [-crl [url|filename]] 
[-wallet [cawallet]] 
[-nextupdate [days]] 
[-pwd pwd]
  • -crl is the location where the CRL will be created (for example ./nzcrl.txt)

  • -wallet is the cawallet, which contains self-signed certificate and corresponding private key

  • -nextupdate is the number of days until the next update

  • -pwd is the password of cawallet

G.1.6.4 orapki crl hash

The following sections describe this command.

G.1.6.4.1 Purpose

Use this command to generate a hash value of the certificate revocation list (CRL) issuer to identify the location of the CRL in your file system for certificate validation.

G.1.6.4.2 Syntax
orapki crl hash -crl crl_filename|URL 
 [-wallet wallet_location] [-symlink|-copy] crl_directory [-summary]
  • The -crl parameter specifies the filename that contains the CRL or the URL in which it can be found.

  • The -wallet parameter (optional) specifies the location of the wallet that contains the certificate of the certificate authority (CA) who issued the CRL. Using it causes the tool to verify the validity of the CRL against the CA's certificate prior to uploading it to the directory.

  • Depending on your operating system, use either the -symlink or the -copy parameter:

    • On UNIX: Use -symlink to create a symbolic link to the CRL at the crl_directory location

    • On Windows: Use -copy to create a copy of the CRL at the crl_directory location

  • The -summary parameter (optional) causes the tool to display the CRL issuer's name.

G.1.6.5 orapki crl revoke

The following sections describe this command.

G.1.6.5.1 Purpose

Use this command to revoke a certificate.

G.1.6.5.2 Syntax
orapki crl revoke [-crl [url|filename]] 
[-wallet [cawallet]] 
[-cert [revokecert]] 
[-pwd pwd]

where:

  • -crl specifies the CRL as either a URL or a filename

  • -wallet is the cawallet, which contains self-signed certificate and corresponding private key

  • -cert: certificate to be revoked

  • -pwd is the password of cawallet.

G.1.6.6 orapki crl status

The following sections describe this command.

G.1.6.6.1 Purpose

Use this command to check if a certificate is revoked in a CRL.

G.1.6.6.2 Syntax
orapki crl status [-crl [url|filename]] 
 [-cert [cert]]
  • -crl specifies the CRL as either a URL or a filename

  • -cert is the CA's certificate

G.1.6.7 orapki crl verify

The following sections describe this command.

G.1.6.7.1 Purpose

Use this command to verify a CRL signature.

G.1.6.7.2 Syntax
orapki crl verify [-crl [url|filename]] 
[-cert [cacert]]

where:

  • -crl specifies the CRL as either a URL or a filename

  • -cert specifies the certificate to be checked

G.1.6.8 orapki wallet add

The following sections describe this command.

G.1.6.8.1 Purpose

Use this command to add certificate requests and certificates to an Oracle wallet.

G.1.6.8.2 Syntax

To add certificate requests:

orapki wallet add -wallet wallet_location -dn user_dn -keysize 512|1024|2048
  • The -wallet parameter specifies the location of the wallet to which you want to add a certificate request.

  • The -dn parameter specifies the distinguished name of the certificate owner.

  • The -keysize parameter specifies the key size for the certificate.

  • To sign the request, export it with the export option. See Section G.1.6.12, "orapki wallet export".

To add trusted certificates:

orapki wallet add -wallet wallet_location -trusted_cert -cert certificate_location
  • The -trusted_cert parameter causes the tool to add the trusted certificate, at the location specified with -cert, to the wallet.

To add root certificates:

orapki wallet add -wallet wallet_location -dn 
certificate_dn -keysize 512|1024|2048 -self_signed 
-valid_from [mm/dd/yyyy] -valid_until [mm/dd/yyyy]
-validity number_of_days
  • The -self_signed parameter causes the tool to create a root certificate.

  • The -validity parameter can be used to specify the number of days, starting from the current date, that this root certificate will be valid.

  • The -valid_from and valid_until parameters can be used to specify an exact date range for which this root certificate will be valid. You may specify validity in this way instead of -validity number_of_days.

To add user certificates:

orapki wallet add -wallet wallet_location -user_cert -cert certificate_location
  • The -user_cert parameter causes the tool to add the user certificate at the location specified with the -cert parameter to the wallet. Before you add a user certificate to a wallet, you must add all the trusted certificates that make up the certificate chain. If all trusted certificates are not installed in the wallet before you add the user certificate, then adding the user certificate will fail.

To add a subject key identifier extension to a certificate request:

orapki wallet add -wallet wallet_location -dn user_dn -keysize 512|1024|2048 -addext_ski

To add a Version 3 self-signed certificate to a wallet:

orapki wallet add -wallet wallet_location -dn certificate_dn -keysize 512|1024|2048 -self_signed -validity number_of_days -addext_ski

G.1.6.9 orapki wallet change_pwd

The following sections describe this command.

G.1.6.9.1 Purpose

Use this command to change the password for an Oracle wallet.

G.1.6.9.2 Syntax
orapki wallet change_pwd [-wallet [wallet_location]] [-oldpwd oldpassword] [-newpwd newpassword]
  • The -wallet parameter specifies the location of the wallet whose password you want to change.

  • The -oldpwd parameter specifies the existing wallet password.

  • The -newpwd parameter specifies the new wallet password.

G.1.6.10 orapki wallet create

The following sections describe this command.

G.1.6.10.1 Purpose

Use this command to create an Oracle wallet or to set auto-login on for an Oracle wallet.

G.1.6.10.2 Syntax
orapki wallet create -wallet wallet_location [-auto_login]
  • The -wallet parameter specifies a location for the new wallet or the location of the wallet for which you want to turn on auto-login.

  • The -auto_login parameter creates an auto-login wallet, or it turns on automatic login for the wallet specified with the -wallet option.

G.1.6.11 orapki wallet display

The following sections describe this command.

G.1.6.11.1 Purpose

Use this command to view the certificate requests, user certificates, and trusted certificates in an Oracle wallet.

G.1.6.11.2 Syntax
orapki wallet display -wallet wallet_location
  • The -wallet parameter specifies a location for the wallet you want to open if it is not located in the current working directory.

G.1.6.12 orapki wallet export

The following sections describe this command.

G.1.6.12.1 Purpose

Use this command to export certificate requests and certificates from an Oracle wallet.

G.1.6.12.2 Syntax
orapki wallet export -wallet wallet_location -dn
certificate_dn -cert certificate_filename
  • The -wallet parameter specifies the directory where the wallet, from which you want to export the certificate, is located.

  • The -dn parameter specifies the distinguished name of the certificate.

  • The -cert parameter specifies the path and filename of the file that contains the exported certificate.

To export a certificate request from an Oracle wallet:

orapki wallet export -wallet wallet_location -dn
certificate_request_dn -request certificate_request_filename
  • The -request parameter specifies the path and filename of the file that contains the exported certificate request.

G.1.6.13 orapki wallet export_trust_chain

The following sections describe this command.

G.1.6.13.1 Purpose

Use this command to export a chain of trust (certificate chain) for a user.

G.1.6.13.2 Syntax
orapki wallet export_trust_chain [-wallet [wallet]] 
[-certchain [filename]] 
[-dn [user_cert_dn] ] 
[-pwd pwd]
  • The -wallet parameter specifies the location of the wallet from which you want to export the certificate chain.

  • The -certchain parameter specifies the name of the file to contain the exported certificate chain.

  • The -dn parameter specifies the distinguished name of the entry to be exported.

  • The -pwd specifies the wallet password.

G.2 Equivalent Features for orapki

Table G-1 shows the features provided by the orapki utility for Oracle wallets and CRLs, and the equivalent commands and options in 12c (12.1.2).

Table G-1 Mapping for orapki Features for Wallets and CRLs

orapki Feature How Implemented in 11gR1 Notes

Creating a standard PKCS#12 wallet

WLST createWallet()

To manage a password-protected and auto-login wallet, provide a non-empty password value. To manage just an auto-login wallet, provide an empty password value (that is, '')

Creating a PKCS#11 wallet

Not supported

Use orapki command-line tool

Uploading a wallet to an LDAP Directory

Not supported

Use orapki command-line tool

Downloading a wallet from an LDAP directory

Not supported

Use orapki command-line tool

Deleting a wallet

WLST deleteWallet()

 

Changing the wallet password

WLST changeWalletPassword()

For obvious reasons, password can only be changed for a password-protected wallet

Enabling auto-login

 

Auto-login wallet is automatically created with every password-protected wallet.

Enabling auto-login wallet that works only on local machine

Not supported

Use orapki command line tool

Create, revoke, hash, verify, upload, list, display, delete CRLs

Not supported

Use orapki command line tool


Table G-2 shows the features provided by the orapki utility for certificates, and the equivalent commands or options in 12c (12.1.2).

Table G-2 Mapping for orapki Features for Certificates

orapki Feature How Implemented in WLST in 11gR1 Notes

Adding a certificate request

addCertificateRequest()

 

Adding a self-signed certificate

addSelfSignedCertificate()

 

Listing all entries in a wallet

listWalletObjects()

Provide a valid value of type ("CertificateRequest", "Certificate" or "TrustedCertificate")

Importing a user certificate

importWalletObject()

Enter type as "Certificate"

Importing a trusted certificate

importWalletObject()

Enter type as "TrustedCertificate"

Removing a certificate request

removeWalletObject()

Enter type as "CertificateRequest"

Removing a user certificate

removeWalletObject()

Enter type as "Certificate"

Removing a trusted certificate

removeWalletObject()

Enter type as "TrustedCertificate"

Removing all trusted certificates

removeWalletObject()

Enter type as "TrustedAll"

Exporting a user certificate

exportKeyStoreObject()

Enter type as "Certificate"

Exporting a certificate request

exportWalletObject()

Enter type as "CertificateRequest"

Exporting a trusted certificate

exportWalletObject()

Enter type as "TrustedCertificate"

Exporting a certificate chain

exportWalletObject()

Enter type as "CertificateChain"

Importing a PKCS#7 certificate chain into the wallet

importWalletObject()

Enter type as "TrustedChain"


G.3 Features of the SSL Configuration Tool

Table G-3 shows the features provided by the SSL Configuration Tool.

Table G-3 Equivalent Features for the SSL Configuration Tool

Configuration Feature SSL Configuration in 12c (12.1.2)

Support for wallet management

Supports management of Oracle Wallets, JKS Keystores, and KSS Keystores, in addition to SSL configuration

Standalone type supported for SSL

Oracle HTTP Server supported for standalone SSL configuration

Types of interface

Provides both command line interface (WLST) and graphical interface (Fusion Middleware Control)

Configuration file required?

Configuration file is optional in the WLST command. If not provided, default values are used for SSL attributes.

Supported tiers

Supports SSL configuration for both Web tier and data tier.

Local or remote management

Allows remote management of components.