1. Administering Oracle Fusion Middleware
  2. Appendixes
  3. orapki

G orapki

Use this appendix to learn how to transition from pre-12c tools like orapki to the certificate, wallet management, and SSL configuration tools provided in 12c (12.2.1.1).

The orapki utility is 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.2.1.1) provides both command-line (the orapki utility) 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.

Topic:

See Also:

  • Doc ID 1629906.1 "How To Create a Wallet via ORAPKI in Fusion Middleware 12c" in the Oracle Technology Network Knowledge Base for additional information and examples of the orapki commands shown in this appendix.

  • WLST Command Reference for Infrastructure Security for examples of the WLST commands shown in this appendix.

  • Configuring SSL in Oracle Fusion Middleware for details about keystore and wallet management in Oracle Fusion Middleware.

Note:

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

Parent topic: Appendixes

Using the orapki Utility for Certificate and CRL Management

You can use the orapki utility to perform some of the basic operations like creating a wallet or creating a certificate.

This section contains these topics:

  • 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.
  • Displaying orapki Help
    You can display all the orapki commands that are available for a specific mode.
  • Creating Signed Certificates for Testing Purposes
    The orapki command-line utility provides a convenient, lightweight way to create signed certificates for testing purposes.
  • Managing Oracle Wallets with the orapki Utility
    You can use these orapki utility wallet module commands in scripts to automate the wallet creation process.
  • Managing Certificate Revocation Lists with orapki Utility
    Certificate Revocation Lists (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.
  • orapki Utility Commands Summary
    Review the purpose and syntax of these orapki commands for managing wallets, certificates and certificate revocation lists.

Parent topic: orapki

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.

Parent topic: Using the orapki Utility for Certificate and CRL Management

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

DN Syntax is Platform-specific

Many orapki commands require the specification of the DN. On UNIX, the user_dn is surrounded by single quotes, for example: 

$ORACLE_HOME/oracle_common/bin/orapki wallet add 
-wallet $ORACLE_HOME/wallet 
-dn 'CN=server.in.oracle.com, OU=Support, O=Oracle, L=Jaipur, ST=Rajasthan, C=IN' 
-keysize 1024

Windows requires double quotes:

$ORACLE_HOME/oracle_common/bin/orapki wallet add 
-wallet $ORACLE_HOME/wallet 
-dn "CN=server.in.oracle.com, OU=Support, O=Oracle, L=Jaipur, ST=Rajasthan, C=IN"
-keysize 1024

Parent topic: orapki Overview

Environment Setup for orapki

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

Parent topic: orapki Overview

Displaying orapki Help

You can display all the orapki commands that are available for a specific mode. 

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.

Parent topic: Using the orapki Utility for Certificate and CRL Management

Creating Signed Certificates for Testing Purposes

The orapki 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.

Parent topic: Using the orapki Utility for Certificate and CRL Management

Managing Oracle Wallets with the orapki Utility

You can use these orapki utility wallet module commands in scripts to automate the wallet creation process.

The following topics describe the syntax used to create and manage Oracle wallets with the orapki command-line utility:

Parent topic: Using the orapki Utility for Certificate and CRL Management

Creating and Viewing Oracle Wallets with orapki

This section contains these topics:

Creating an Oracle Wallet
orapki wallet create -wallet wallet_location

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

Creating an Oracle Wallet with Auto-login Enabled
orapki wallet create -wallet wallet_location -auto_login

This command creates a wallet with auto-login enabled. 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.

Creating an Oracle Wallet with AES Encryption

orapki wallet create -wallet wallet -pwd pwd -compat_v12

This command creates an Oracle wallet with AES encryption.

Converting an Existing Wallet to Use AES Encryption

orapki wallet convert -wallet wallet -compat_v12 -pwd pwd

This command converts an Oracle wallet from 3DES to AES encryption.

Viewing an Oracle Wallet

orapki wallet display -wallet wallet_location

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

Adding Certificates and Certificate Requests to Oracle Wallets with orapki

This section contains these topics:

Adding a Certificate Request to an Oracle Wallet
orapki wallet add -wallet wallet_location -dn user_dn -keysize certificate_key_size -addext_ski -addext_ku extension_key_usage -addext_basic_cons CA -pathLen number -addext_san DNS

This command adds a certificate request to a wallet for the user with the specified distinguished name (user_dn). The request also specifies the following parameters and extensions:

  • The –keysize parameter specifies the requested certificate's key size. The key size identifiers are 512, 1024, 2048, 4096, 8192, 16384.

  • The -addext_ski parameter is an extension for adding a subject key identifier extension to a certificate request.

  • The -addext_ku parameter is an extension for adding key usages. The keys are digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, and decipherOnly.

  • The -addext_basic_cons parameter is an extension for adding basic constraints. This extension mentions that the certificate request is CA. It also mentions the -pathLen, which signifies the number of non-self-issued intermediate CA certificates that may follow in a valid certification path under CA.

  • The -addext_san parameter is an extension to X509 certificates used to add subject alternative names, which is used in addition to identity a subject. This option only allows adding domain names separated by a comma. It can be added as shown below in example. 

    -addext_san DNS:<value1>,DNS:<value2>,DNS:<value3>
or
-addext_san DNS:ns1.example.com,DNS:ns2.example.com

    Note:

    The -addext_san support is applicable in Oracle Fusion Middleware since 12c (12.2.1.1).

To sign the request, export it with the export option. See Exporting Certificates and Certificate Requests from Oracle Wallets with orapki.

For example:

Linux/Unix:
$ORACLE_HOME/oracle_common/bin/orapki wallet add 
-wallet $ORACLE_HOME/wallet 
-dn 'CN=server.in.test.com, OU=Support, O=Oracle, L=Jaipur, ST=Rajasthan, C=IN' 
-keysize 1024 

Windows:
$ORACLE_HOME/oracle_common/bin/orapki wallet add 
-wallet $ORACLE_HOME/wallet 
-dn "CN=server.in.test.com, OU=Support, O=Oracle, L=Jaipur, ST=Rajasthan, C=IN"
-keysize 1024
Adding 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.

Adding a Root Certificate to an Oracle Wallet
orapki wallet add -wallet wallet_location -dn
certificate_dn -keysize 512|1024|2048|4096|8192|16384 -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, 4096, 8192 or 16384 bits.

See Adding a Certificate Request to an Oracle Wallet for an example showing the DN syntax.

Adding 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.

Adding an ECC Certificate to an Oracle Wallet with orapki

This section contains these topics:

Adding an ECC Certificate Request to an Oracle Wallet
orapki wallet add -wallet wallet_location -dn user_dn -sign_alg signing_alg -asym_alg ECC -eccurve curve_type -addext_ski -addext_ku extension_key_usage -addext_basic_cons CA -pathLen number -addext_san DNS

This command adds a certificate request to a wallet for the user with the specified distinguished name (user_dn). The request specifies the following ECC specific parameters:

  • The -sign_alg parameter specifies the signature algorithm that can be used by CA to sign the certificate. ecdsasha1, ecdsasha256, ecdsasha384 and ecdsasha512 are the supported signing algorithms for CAs having ECC key and md5, sha1, sha256, sha384 and sha512 are the signing algorithms supported for CAs with RSA keys.

  • The -asym_alg parameter specifies the type of key: ECC or RSA. If the key type is ECC, then option -eccurve has to be specified to set the ECC curve on which key is generated. If the key type is RSA, then option -keysize has to be specified to set the key size of RSA key to be generated.

  • The -eccurve parameter specifies the curve on which ECC key is generated. The curve identifiers are p192, p224, p256, p384, p521, k163, k233, k283, k409, k571, b163, b233, b283, b409, b571.

Viewing an Oracle Wallet with ECC Certificate
orapki wallet display -wallet wallet_location

This command displays the ECC certificates contained in the wallet.

Exporting Certificates and Certificate Requests from Oracle Wallets with orapki

This section contains these topics:

Exporting a Certificate from an Oracle Wallet
orapki wallet export -wallet wallet_location -dn
certificate_dn -cert certificate_filename -issuer_dn dn_of_issuer –serial_num serial_number_of_certificate

This command exports a certificate with the subject's distinguished name (-dn) from a wallet to a file that is specified by -cert. The command uses the following options to uniquely identify a certificate in a wallet:

  • The -issuer_dn option specifies the DN of the certificate issuer.

  • The -serial_num option is used as an identification number for a certificate. The serial number option supports both decimal and hexadecimal format.

See Adding a Certificate Request to an Oracle Wallet for an example showing the DN syntax.

Exporting 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.

See Adding a Certificate Request to an Oracle Wallet for an example showing the DN syntax.

Creating and Managing Trust Flags

Trust flags allow adequate roles to be assigned to certificates to facilitate operations like certificate chain validation and path building. By default, wallets do not support trust flags.

You can use the orapki utility to maintain trust flags in the certificates installed in an Oracle Wallet. You can create and convert wallets to support trust flags, create and maintain appropriate flags in each certificate, and so on.

Table G-1 shows the supported trust flags:

Table G-1 Trust Flags in Oracle Wallet Certificates

NZ Trust Flag Value Description and Best Practices NSS Flag

SERVER_AUTH (Trusted server CA certificate)

Assigned to trusted CA's root and intermediate certificates. Useful for fine-grain control to allow CA certificates to act in client CA or server CA roles.

Can co-exist with "CLIENT_AUTH" flag.

During server authentication, if the server's certificate chain has a CA certificate with a SERVER_AUTH flag in the client's certificate store, authentication succeeds. If a CA certificate with a SERVER_AUTH flag is not present, authentication fails.

In client wallet, assigning the "SERVER_AUTH" flag to server's Root CA certificate is recommended. Server certificate chain verification stops at the certificate with this "SERVER_AUTH" flag. If you do not want to add server's ROOT CA certificate to the client wallet, set it to the server's intermediate CA certificate.

"C"

CLIENT_AUTH (Trusted client CA certificate)

Assigned to trusted CA's root and intermediate certificates.

Can co-exist with the "SERVER_AUTH" flag.Useful for fine-grain control to allow CA certificates to act in client CA or server CA roles.

When the SSL server requests client authentication, the server sends a list of subject names of trusted CA certificates it is willing to accept certificates from. Trusted certificates in wallets with the CLIENT_AUTH flag would be used to make this list.

During SSL client authentication, if the client's certificate chain has a CA certificate having the CLIENT_AUTH flag in server's wallet, then authentication succeeds. If a CA certificate with the CLIENT_AUTH flag is not present, then authentication fails.

"T"

VALID_PEER

Assigned to peer's user certificate to authenticate peer. Usually it would be without a private key.

Cannot co-exist with "CLIENT_AUTH", "SERVER_AUTH", or "USER_CERT" flags.

Adding this flag to self-signed server or client certificates is recommended. Certificate chain building and verification stops at the certificate with the "VALID_PEER" flag.

During authentication, if the user's certificate sent by an SSL peer for authentication exists in relying party's certificate store with VALID_PEER flag, then this certificate is allowed to establish the SSL connection without any certificate chain validation provided that it is a valid peer's user certificate.

"P"

NULL.

Assigned implicitly to certificates that do not have any flag.

Recommended for use with intermediate CA certificates.

""

In addition to the flag assignments you can explicitly perform, here are certain assignments automatically made in certificates when the wallet allows trust flags:

  • In a root wallet (with copies of the same certificate in 'user certificates' and 'trusted certificates' section), USER_CERT flag is added to certificate(s) in 'user certificates' section only.

  • When a wallet is converted so that it supports trust flags, specific rules govern the assignment of trust flags to the trusted certificates added to the wallet (see Assigning Trust Flags to Trusted Certificates below).

  • When a certificate is deleted from the wallet, all flags associated with the certificate are deleted. If the same certificate is re-installed flags must be added again.

  • When a wallet is created with trust flags (using the -with_trust_flags option) the wallet is populated with certain default certificates. All these certificates are assigned the SERVER_AUTH/CLIENT_AUTH flags.

Assigning Trust Flags to Trusted Certificates

When you add trusted certificates to wallets which are trust flag-enabled, trust flags are computed as follows:

  • Root CA is assigned the SERVER_AUTH flag.

  • Intermediate CA (ICA) is assigned the NULL flag.

  • End-entity certificate without private key is assigned the VALID_PEER flag.

  • Self-signed certificates without private key are assigned the VALID_PEER flag.

The following topics explain the trust flag operations you can perform with orapki:

Creating a Wallet to Support Trust Flags

Use the orapki option with_trust_flags when creating the wallet. 

orapki wallet create –wallet wallet_location 
–pwd password –with_trust_flags

This command creates an Oracle wallet that supports trust flags; wallets created without the with_trust_flags parameter do not support trust flags, but can be converted to do so.

Other options like creating an auto-login wallet can also be specified when creating a wallet to support trust flags.

Rules governing the assignment of trust flags to trusted certificates added to a trust-flag-enabled wallet are explained in Creating and Managing Trust Flags (see Assigning Trust Flags to Trusted Certificates), and you can clear these flags explicitly.

Converting a Wallet to Support Trust Flags

You can update an existing wallet to support trust flags.

This command syntax converts a wallet to support trust flags.

orapki wallet enable_trust_flags –wallet wallet_location –pwd password

or, for auto-login wallet:

orapki wallet enable_trust_flags –wallet wallet_location –auto_login_only

Usage rules are as follows:

  • Password is not required if it is an auto-login wallet.

  • After using this command, you cannot convert the wallet back to its original state, that is, to not support trust flags.

  • All user certificates present in the wallet are assigned the USER_CERT flag.

Trust flags for trusted certificates are computed as follows:

  • Root CA is assigned SERVER_AUTH flag.

  • ICA or intermediate CA is assigned NULL flag.

  • End-entity certificate without private key is assigned VALID_PEER flag.

You can change the flags associated with trusted certificates to assign the desired trust flags to these certificates.

Adding Certificates to Empty Wallet

As mentioned earlier, after using this command you cannot convert the wallet back to its original state to not support trust flags.

If you remove all the certificates from the wallet, including the default certificates installed by orapki, the tool can no longer determine whether the wallet supports trust flags. Therefore it is advisable not to remove the default installed certificates from the wallet; if you must remove them, make sure to install a certificate before removing them so at least one certificate remains in the wallet.

If you delete all the certificates from a wallet and later install new certificates, the wallet behaves as follows: If the new certificate is installed with the trust flags option, the wallet will automatically support trust flags. If the new certificate is installed without the trust flags option, the wallet will not support trust flags.

Adding and Updating a Certificate's Trust Flags

The orapki option trust_flags assigns the requisite flags to selected certificates. 

orapki wallet assign_trust_flags –wallet wallet_location
–pwd password –trust_flags ""|"flags" 
–dn "value" [–serial_num "value"  –issuer "value"]

This command adds, updates, or deletes trust flags for the certificate specified by the dn. Syntax rules are as follows:

  • The wallet must support trust flags.

  • Password is not required if wallet is an auto-login wallet.

  • Specify the flags as defined in Table G-1.

  • The Subject DN is the only mandatory certificate attribute parameter, the remaining two parameters being optional. However, you must provide sufficient detail using these parameters to uniquely identify the certificate.

  • The matching attribute names are case insensitive, and attribute values are case-sensitive.

  • The -serial_num option is used as an identification number for a certificate. The serial number option supports both decimal and hexadecimal format.

  • Existing flags, if any, assigned to the certificate are over-written.

  • Multiple flags can be assigned using ", "(comma); like –add "SERVER_AUTH,CLIENT_AUTH"

  • The USER_CERT flag is not permitted in this command, as this flag is assigned implicitly to the user certificates. for the user certificate the USER_CERT flag shall always be there.

  • To remove trust flags, use –add "". The NULL flag is assigned to the certificate.

  • if the modify/clear action would result in an invalid certificate chain for any user certificate, the action is not carried out.

For example:

orapki wallet assign_trust_flags –wallet /usr/test
–trust_flags "SERVER_AUTH,CLIENT_AUTH" 
–dn "cn=jack, ou=people, dc=example, dc=com" 
–serial_num "1122" –issuer "sample"
Adding a Certificate with Trust Flags to Wallet

Use the orapki option trust_flags when adding certificates to a wallet. 

orapki wallet add –wallet wallet_location 
–[trusted_cert|user_cert|self_signed] 
–cert cert_location –pwd password –trust_flags "flag(s)"

This command adds a certificate with specified trust flag(s) to an Oracle wallet. Syntax rules are as follows:

  • The wallet must support trust flags.

  • Passwords are not required if the wallet is an auto-login wallet.

  • cert_location is not required if you generate a self signed certificate.

  • USER_CERT flag is added implicitly if the certificate is of type user_cert. (In a root wallet a self-signed certificate is also present in the 'trusted certificates' section; the USER_CERT flag is not assigned to this certificate).

  • The flags are specified as defined in Table G-1.

  • If trust flags are enabled there is no need for the complete hierarchy of trusted certificates to be present (unlike the case for wallets without trust flags, where the entire chain must be present when adding a user certificate). The certificate chain building stops if a SERVER_AUTH/CLIENT_AUTH flag is assigned to any trusted certificate in the hierarchy.

Importing PKCS#12 Files to an Oracle Wallet

The orapki option pkcs12file enables you to import PKCS#12 files into a wall.et 

orapki wallet import_pkcs12 
–wallet wallet_location [-pwd wallet_password] 
-pkcs12file pkcs12_file_location [-pkcs12pwd pkcs12_file_password]

This command imports a PKCS#12 file into an Oracle wallet. The utility prompts you if you do not specify passwords with the command.

Converting Between Oracle Wallet and JKS Keystore

You can convert a JKS keystore to an Oracle wallet, and convert an Oracle wallet to JKS.

Converting JKS to Oracle Wallet

Use this command to migrate entries from JKS store to p12 wallet:

jks_to_pkcs12 -wallet wallet -pwd pwd -keystore keystore 
-jkspwd jkspwd [-aliases [alias:alias..]]

where the parameters are as follows:

  • wallet is the wallet location; entries from the JKS keystore will be migrated to this wallet.

  • pwd is the wallet password.

  • keystore is the keystore location; this JKS will be migrated to the p12 wallet.

  • jkspwd is the JKS password.

  • aliases are optional. If specified, only entries corresponding to the specified alias are migrated. If not specified, all the entries are migrated.

To illustrate this command, start by creating a self-signed JKS keystore:

keytool -genkey -alias myalias -keyalg RSA -keysize 1024 -dname CN=root,C=US -validity 3650 -keystore ./ewallet.jks -storetype jks -storepass password 
-keypass password

Next, create an Oracle wallet:

orapki wallet create -wallet ./ -pwd password

Migrate the JKS keystore entries to the wallet:

orapki wallet jks_to_pkcs12 -wallet ./ -pwd password -keystore ./ewallet.jks -jkspwd password

Note:

In this example the wallet was newly created and is empty. However, in practice the wallet need not be empty when you use this command; pre-existing entries are preserved.

Converting Oracle Wallet to JKS

Use this command to migrate entries from a p12 wallet to a JKS keystore:

pkcs12_to_jks -wallet p12wrl -pwd p12pwd 
[-jksKeyStoreLoc jksKSloc -jksKeyStorepwd jksKS_pwd][-jksTrustStoreLoc loc -jksTrustStorepwd pwd]

where the parameters are as follows:

  • wallet is the p12 wallet location.

  • pwd is the wallet password.

  • jksKeyStoreLoc is the JKS keystore location.

  • jksKeyStorepwd is the JKS keystore password.

  • jksTrustStoreLoc is the JKS truststore location.

  • jksTrustStorepwd is the JKS truststore password.

Note:

Passwords must have a minimum length of eight characters and contain alphabetic characters combined with numbers or special characters.

This example migrates all wallet entries to the same JKS keystore:

orapki wallet pkcs12_to_jks -wallet ./ -pwd password -jksKeyStoreLoc ./ewallet.jks -jksKeyStorepwd password2

This example migrates keys and trusted certificate entries into separate JKS keystores:

orapki wallet pkcs12_to_jks -wallet ./ -pwd password1
-jksKeyStoreLoc ./ewalletK.jks -jksKeyStorepwd password2 
-jksTrustStoreLoc ./ewalletT.jks -jksTrustStorepwd password2

Managing Certificate Revocation Lists with orapki Utility

Certificate Revocation Lists (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.

See Also:

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

The following sections describe CRLs, how you use them, and how to use orapki to manage them:

Parent topic: Using the orapki Utility for Certificate and CRL Management

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.

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.

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 locations and management of CRL files is component-dependent. For Oracle WebLogic Server, see "Configuring the CRL Local Cache" in Administering Security for Oracle WebLogic Server. For Oracle HTTP Server, see Doc ID 1665286.1, "How to Configure CRL Checking in Oracle HTTP Server in FMW 12c" in the Oracle Technology Network Knowledge Base.

  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.

    Note:

    • For performance reasons, only user certificates are checked.

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

Certificate Revocation List Management

Procedures for CRL management depend on the component in question. For Oracle WebLogic Server, see Configuring the CRL Local Cache in Administering Security for Oracle WebLogic Server. For Oracle HTTP Server, see Doc ID 1665286.1, "How to Configure CRL Checking in Oracle HTTP Server in FMW 12c" in the Oracle Technology Network Knowledge Base.

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.

Parent topic: Managing Certificate Revocation Lists with orapki Utility

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.
                              

                           

                           
                        

                        
                        
                     

                  

               
orapki Utility Commands Summary

                  
Review the purpose and syntax of these orapki commands for managing wallets, certificates and certificate revocation lists.
                  

                  

                     
                     

                        

                           
Parent topic: Using the orapki Utility for Certificate and CRL Management

                        

                     

                  

                  
orapki cert create

                     

                        

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

                           
The syntax for FMW is:
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.
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki cert display

                     

                        

                           
Use this command to display details of a specific certificate.

                        

                        
                     

                     
                     
                  
orapki crl create

                     

                        

                           
The syntax for FMW to create a CRL is:
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 syntax for ENT to create a CRL is:

                           
crl:
create [-crl [url|filename]] [-wallet [cawallet]] <-issuer [issuer_dn]>
<-issuersissuer [issuersissuer_dn]>
<-serial_num [serial_num]> [-nextupdate [days]] [-pwd <pwd>] [-sign_alg
<md5|sha1|sha256|sha384|sha512|ecdsasha1|ecdsasha256|ecdsasha384|ecdsasha512>]

                           
    
                              
  • 
                                 
                                 
    -crl is the location where the CRL will be created (for example
                            ./nzcrl.txt)
    
                                 
                              
    • 
                              
  • 
                                 
                                 
    -issuer is the DN of the issuer
    
                                 
                              
    • 
                              
  • 
                                 
                                 
    -issuersissuer is the issuer DN of the issuer certificate
    
                                 
                              
    • 
                              
  • 
                                 
                                 
    -serial_num is the serial number for the CRL
    
                                 
                              
    • 
                              
  • 
                                 
                                 
    -sign_alg is the sign algorithm to be used
    
                                 
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki crl hash

                     

                        

                           
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.

                           
The syntax is:
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.
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki crl revoke

                     

                        

                           
Use these commands to revoke a certificate.

                           
The syntax for FMW is:
orapki crl revoke [-crl [url|filename]] 
[-wallet [cawallet]] 
[-cert [revokecert]] 
[-pwd pwd]

The syntax for ENT is:

                           
revoke [-crl [url|filename]] [-wallet [cawallet]] [-cert [revokecert]] [-pwd
<pwd>] [-sign_alg
<md5|sha1|sha256|sha384|sha512|ecdsasha1|ecdsasha256|ecdsasha384|ecdsasha512>]

    
                              
  • 
                                 
    -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.
                                 
    
                              
    • 
                              
  • 
                                 
                                 
    -sign_alg is the sign
                                                  algorithm to be used. 
                                 
    
                                 
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki crl status

                     

                        

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

                           
The syntax is:
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
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki crl verify

                     

                        

                           
Use this command to verify a CRL signature.

                           
The syntax is:
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
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki wallet add

                     

                        

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

                           

                              
See Also:

                              
See Adding a Certificate Request to an Oracle Wallet for an example showing the DN syntax.
                              

                           

                           
To add certificate requests:
orapki wallet add -wallet wallet_location -dn user_dn -keysize 512|1024|2048|4096|8192|16384

    
                              
  • 
                                 
    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 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|4096|8192|16384
 -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

To add trust flags while adding a certificate to a wallet:
orapki wallet add –wallet wallet_location 
–[trusted_cert|user_cert|self_signed] 
–cert cert_location –pwd password –trust_flags "flag(s)"


                           
See Adding a Certificate Request to an Oracle Wallet for an example showing the DN syntax.
                           

                        

                        
                     

                     
                     
                  
orapki wallet change_pwd

                     

                        

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

                           
The syntax is:
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. 
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki wallet create

                     

                        

                           
Use this command to create an Oracle wallet, to set auto-login on for an Oracle wallet, and to enable trust flags for certificates.

                           
The syntax is:
orapki wallet create -wallet wallet_location 
[–with_trust_flags] [-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 –with_trust_flags parameter enables the wallet to support trust flags.
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki wallet enable_trust_flags

                     

                        

                           
Use this command to convert a wallet to support trust flags.

                           
The syntax is:
orapki wallet enable_trust_flags –wallet wallet_location –pwd password


                        
                     

                     
                     
                  
orapki wallet assign_trust_flags

                     

                        

                           
Use this command to assign trust flags to a certificate in a wallet.

                           
The syntax is:
orapki wallet assign_trust_flags [–wallet [wallet_location]] [–pwd password] [–trust_flags ""|"flags"] 
[–dn ["value"]] [–issuer [issuer_dn]] [–serial_num [serial_num]]
    
                              
  • 
                                 
    The -wallet parameter specifies the location of the wallet from which you want to assign trust flags to a certificate.
                                 
    
                              
    • 
                              
  • 
                                 
    The -pwd specifies the wallet password.
                                 
    
                              
    • 
                              
  • 
                                 
    The –trust_flags parameter specifies which trust flags to enable. The trust flags are SERVER_AUTH,CLIENT_AUTH, VALID_PEER, and NULL.
                                 
    
                              
    • 
                              
  • 
                                 
    The -dn parameter specifies the distinguished name of the certificate.
                                 
    
                              
    • 
                              
  • 
                                 
    The -issuer option specifies the DN of the certificate issuer.
                                 
    
                              
    • 
                              
  • 
                                 
    The -serial_num option is used as an identification number for a certificate. The serial number option supports both decimal and hexadecimal format.
                                 
    
                              
    • 
                           

                           
The -serial_num and -issuer options may be required to uniquely match a single certificate in the wallet.
                           

                           
For additional usage details, see Adding and Updating a Certificate's Trust Flags.
                           

                           
See Adding a Certificate Request to an Oracle Wallet for an example showing the DN syntax.
                           

                        

                        
                     

                     
                     
                  
orapki wallet display

                     

                        

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

                           
The syntax is:
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.
                           

                        

                        
                     

                     
                     
                  
orapki wallet export

                     

                        

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

                           

                              
See Also:

                              
Adding a Certificate Request to an Oracle Wallet for examples of specifying the dn parameter.
                              

                           

                           
The syntax is:
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.
                                 
    
                              
    • 
                           

                        

                        
                     

                     
                     
                  
orapki wallet export_trust_chain 

                     

                        

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

                           
The syntax is:
orapki wallet export_trust_chain [-wallet [wallet]] 
[-certchain [filename]]
[-dn [user_cert_dn] ] 
[-pwd pwd]
[-issuer_dn [issuer_dn]]
[-serial_num [serial_num]]
    
                              
  • 
                                 
    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.
                                 
    
                              
    • 
                              
  • 
                                 
    The -issuer_dn option specifies the DN of the certificate issuer.
                                 
    
                              
    • 
                              
  • 
                                 
    The -serial_num option is used as an identification number for a certificate. The serial number option supports both decimal and hexadecimal format.
                                 
    
                              
    • 
                           

                           
See Adding a Certificate Request to an Oracle Wallet for an example of how to specify the —dn parameter.
                           

                        

                        
                     

                     
                     
                  
orapki wallet import_pkcs12

                     

                        

                           
Use this command to import a PKCS#12 file into an Oracle wallet.
orapki wallet import_pkcs12 
–wallet wallet_location [-pwd wallet_password] 
-pkcs12file pkcs12_file_location [-pkcs12pwd pkcs12_file_password]

    
                              
  • 
                                 
    The wallet parameter specifies the relative or absolute path of Oracle Wallet into which PKCS#12 file is to be imported. Required.
                                 
    
                              
    • 
                              
  • 
                                 
    The pwd parameter specifies the password of Oracle Wallet into which PKCS#12 file is to be imported. Optional, prompts as needed.
                                 
    
                              
    • 
                              
  • 
                                 
    The pkcs12file parameter specifies the relative or absolute path of PKCS#12 file to be imported into Oracle Wallet. Required.
                                 
    
                              
    • 
                              
  • 
                                 
    The pkcs12pwd parameter specifies the password of PKCS#12 file that is to be imported into Oracle Wallet. Optional, prompts as needed.
                                 
    
                              
    • 
                           

                           
For example:
orapki wallet import_pkcs12 –wallet /scratch/user/oracleWalletFolder/ewallet.p12 -pwd walletPassword -pkcs12file /scratch/userId/pkcs12fileFolder/certandkey.p12 -pkcs12pwd pkcs12filePassword