orapki cheatsheet - plembo/onemoretech GitHub Wiki

created: 2011/09/08 12:40:43

This is a short piece describing common operations that can be performed by the Oracle's orapki utility, the command line tool used to manage their SSL "wallet". The Oracle SSL "wallet" is a database for storing SSL certificates used by various Oracle applications. It's basically a proprietary implementation of the old Netscape nss (Network Security Services) certificate system (nss is now maintained at mozilla.org as an open source project). For those who already know nss, the orapki tool corresponds most closely to certutil.

Basic documentation from Oracle on how to manage the SSL wallet and the use of orapki can be found in the Fusion Middleware Administrator's Guide (check relevant doc for versions of orapki shipped with different products). For those with access to Oracle Support, document 1218695.1 ("Master Note for SSL Configuration in Fusion Middleware 11g) is also a good resource. Following are some basic tasks along with examples of how to use orapki to perform them from that doc. Perform them as the product system user (e.g. "oracle"). Note, if your wallet does not have auto login enabled you'll need to add the "-pwd" parameter with the wallet password when invoking these commands.

Some words of warning before you begin:

1. Note that any given option or syntax shown here may or may not exist or work depending upon the specific version of the Oracle software you're using. Oracle has very definitely not been consistent about this. You have been warned.

2. Create new wallets using the "-auto_login", or where available, the "-auto_login_only" switch. You'll thank me later on.

3. After creating a new wallet be sure to first add the root CA certificate for your chosen Certificate Authority, then any Intermediate CA certificates (these are required by Verisign for all standard SSL installations since October, 2010) IN THAT ORDER.

4. DO NOT create your first certificate request until you have completed step 3 above.

5. Be careful about using orapki and owm interchangeably, in particular always make sure you Save any changes you make in owm -- unless you want to do it all over again.

6. Some (earlier?) versions of orapki like you to end command strings with "-pwd" and the wallet password. I can't even begin to express how incredibly dumb this is. Any security product that requires that you enter a password at the console in the clear (not to mention facilitating its recording in shell history) is an absolute disgrace. But then this is Oracle, and Oracle has no shame.

7. Although orapki does not provide a method to remove certificates from the wallet (owm does do this), if you find the need to I'd recommend exporting all your certificates (and cert requests), deleting the wallet files, and reloading everything in proper order. It should work. But just in case be sure to keep a backup copy of the original wallet.

8. Using a path like "./fileordirname" works with many versions of orapki, but I can't guarantee it will with all.

Display wallet contents

orapki wallet display -wallet [wallet path]

The wallet path is a path to the directory that the wallet files are stored in. This is typically something like "/app/oracle/product/ohs/conf/ssl_wallet" depending on how you've organized things. Wallets are usually password protected for security, and orapki will prompt for this password when it is invoked.

Exporting certificates from a wallet

orapki wallet export -wallet [wallet path] \
-dn [dn of cert] -cert [filename for cert]

This is to export a particular certificate from the database, usually used for migrating things to another place. The cert dn can be found by running the display command given above, the filename is really up to the user. The dn for the cert will be something like:

CN=dev.example.com,O=Snakeoil Sales, Inc,L=Melville,ST=New York,C=US

Make sure to surround it in single quotes and to escape any commas in the data.

orapki wallet export -wallet $OH/conf/ssl_wallet \
-dn 'CN=dev.example.com,O=Snakeoil Sales, Inc,L=Melville,ST=New York,C=US' \
-cert $OH/conf/dev.example.com.crt

Creating a cert request

(Be sure you import the root CA and any intermediate CA certs for the Certificate Authority that will be signing your cert request before creating a request.) This is really a two-step process. First you "add" the certificate request to the wallet:

orapki wallet add -wallet [wallet path] \
-dn [dn for cert] -keySize [either 512, 1024 or 2048]

The dn and key size will depend on your CA (Certificate Authority) requirements. Once you've done this, you export the request so it can be signed:

orapki wallet export -wallet [wallet path] \
-dn [dn for cert] -request [filename for req]

Importing a CA cert

orapki wallet add -wallet [wallet path] \
-trusted_cert -cert [full path for cert file]

These are called "trusted certs" in Oracle-speak. In other words, genuine, CA root and intermediate certificates. Be sure to include all certs required for the certificate chain to be complete (e.g. both root and intermediate certs for CAs like Verisign that require both) _in order of precedence. That means: import the root cert first, and then any intermediates.

Importing a server cert

orapki wallet add -wallet [wallet path] \
-user_cert -cert [full path for cert file]

Server certs (the ones named for the web site or server you are trying to serve up SSL for) are considered "user certs" by Oracle. These need to be signed by a trusted CA. Be sure to import the associated trusted certs for the certificate chain (see above) before importing your server cert to avoid certificate chain errors.

Create a new wallet with auto login

orapki wallet create -wallet [wallet path] \
-auto_login

This creates a wallet with auto login enabled, or auto login enables an existing wallet. Leaving off the "-auto_login" will create a wallet that requires a password each time it is opened. Newer versions of orapki offer an "auto_login_only" switch. If yours has this, use it. Happiness is only being prompted for passwords when absolutely necessary.

Change wallet password

orapki wallet change_pwd -wallet [wallet path] \
-oldpwd [old pass] -newpwd [new pass]

Note that this requires you to know the old password for the wallet. If you've lost it, you're screwed just like if you were using nss.