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:
:Oracle Advanced Security Administrator's Guide for details of orapki usage:
http://docs.oracle.com/cd/E11882_01/network.112/e10746/toc.htm
Chapter 6 for details about keystore and wallet management in Oracle Fusion Middleware.
Note:
Theorapki utility is located in the binary directory of Oracle Common home, that is, $ORACLE_HOME/oracle_common/bin.This section contains these topics:
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.
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
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.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.
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.
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.
Adding Certificates and Certificate Requests to Oracle Wallets with orapki
Exporting Certificates and Certificate Requests from Oracle Wallets with orapki
Note:
The-wallet parameter is mandatory for all wallet module commands.See Also:
For examples of how to create either a password-protected wallet or an auto-login wallet, see Doc ID 1226654.1, "How To Create a Wallet via ORAPKI in FMW 11g" on the OTN Knowledge Base.
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 asadd.
orapki wallet display -wallet wallet_location
This command displays the certificate requests, user certificates, and trusted certificates contained in the wallet.
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.
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.
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 withorapki:
http://docs.oracle.com/cd/E11882_01/network.112/e10746/asossl.htm
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.
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.
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.
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."
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.
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 usingorapki 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.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.
This section lists and describes the following orapki commands:
The following sections describe this command.
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.
The following sections describe this command.
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
The following sections describe this command.
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
The following sections describe this command.
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.
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.
The following sections describe this command.
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.
The following sections describe this command.
The following sections describe this command.
The following sections describe this command.
Use this command to add certificate requests and certificates to an Oracle wallet.
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
The following sections describe this command.
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.
The following sections describe this command.
Use this command to create an Oracle wallet or to set auto-login on for an Oracle wallet.
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.
The following sections describe this command.
The following sections describe this command.
Use this command to export certificate requests and certificates from an Oracle wallet.
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.
The following sections describe this command.
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.
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" |
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. |