orapki

ORAPKI UTILITY

Shashi Kallae
Table of Contents

Deprecated features in Oracle Database 23c ...................................................... 2

Unsupported features in Oracle Database 23c .................................................... 4
What is orapki? .................................................................................................. 5
What is a Wallet? ............................................................................................. 10
About orapki utility .......................................................................................... 10
Create a wallet (using orapki tool). .................................................................. 11
ORACLE_HOME ............................................................................................................................. 12
JAVA_HOME ................................................................................................................................. 12
How to create a wallet for the Oracle database? ........................................................................... 13

Orapki and related Commands ......................................................................... 14

SQLNET.ORA Configuration .............................................................................. 18
LISTENER.ORA Configuration ............................................................................ 19
TNSNAMES.ORA Configuration ........................................................................ 20
Verify the Oracle Database access with the created Wallet .............................. 21
Important Points to Consider............................................................................ 22
Commands from Oracle Documentation ........................................................... 22
References ....................................................................................................... 25
Disclaimer ........................................................................................................ 26
Deprecated features in Oracle Database 23c

1. Oracle Virtual Directory with Real Application Security.

2. Enterprise User Security (EUS).
3. mkstore (Wallet Management Command Line Tool).
a. mkstore is a command-line utility allowing users to manage
Wallet secrets.
b. It is available in the Oracle Database Client.
c. The mkstore creates and modifies a wallet, adds credentials,
and manages Wallet Contents.

Note: As per Oracle Database 23c documentation, Oracle mentioned that

this feature will be deprecated.

From Oracle Database 23c documentation

The mkstore wallet management command line tool is deprecated
with Oracle Database 23c, and can be removed in a future release.
To manage wallets, Oracle recommends that you use
the orapki command line tool.
 A Question posed by a user on the deprecation of mkstore
User_3ABCEApr 28 2023

Security Guide 3.2.9 Managing the Secure External Password Store for

Password Credentials uses the mkstore utility to create database

credentials: mkstore -createCredential.

However, another section of the book says that the utility is
deprecated. B.1.3 Tools Used to Manage Oracle Database Wallets and

Certificates:

mkstore is a command-line Oracle utility that you can use to add secrets
to the wallet and then manage them. It is available in the Oracle Database
client. Starting in Oracle Database release 23c, mkstore is deprecated.
Oracle recommends that you use the orapki instead of mkstore.

How to manage the Secure External Password Store using the orapki
tool?

Rlowenth-Oracle May 1 2023

ANSWER

We will be enhancing orapki AFTER 23c to include the missing

functionality that is currently in mkstore. Essentially (right now) we find
ourselves maintaining two different command line utilities - and forcing
YOU to learn syntax for two different utilities - where we can easily
shrink things down to a single utility. We want to fix that in an upcoming
version of the database utilities.

Notice that for 23c we are only deprecating the utility - no changes at
this time. We just want to make sure the community is aware that we are
planning to fix this in an upcoming release.

Marked as Answer by Gerald Venzl-Oracle · May 1 2023

Note: Please contact Oracle Support for more information on the

deprecation and feature enhancements for mkstore wallet management.

Unsupported features in Oracle Database 23c

1. Oracle Wallet Manager (OWM)

2. Oracle Enterprise User Security – User Migration Utility.
3. Oracle Database 10G Password Verifier.
4. Unix Crypt or MD5Crypt Password Verifier.
5. Diffie-Hellman Anonymous Ciphers.
What is orapki?

Before delving into the definition of orapki, let’s explore some key
definitions.

1. ewallet.p12
1.1. This is a main keystore file in PKCS#12 format. It contains
private keys, certificates, and other password-protected information
used for database authentication. It is secured with a password and
associated with Oracle Wallet.

1.2. PKCS#12 files are commonly used to import and export

certificates and private keys and usually have the filename
extensions ".p12" or ".pfx." They are a binary format for storing a
certificate chain and private key in a single, encryptable file.
 For Example
Imagine a secure digital safe in the world of Oracle databases. This safe,
called a PKCS#12 file (often ending in .p12 or .pfx), acts like a vault that
holds two critical things:

Private Key: This is a secret code, like a master key, that grants access
to the database.

Certificate: This is like a digital ID card that verifies your identity to the
database and confirms you have the private key.

Just like a physical safe needs a key to open it, the PKCS#12 file has a
password for extra security. You can use this file to import or export
both the private key and certificate between your computer and Oracle
databases. This helps set up secure connections or use tools that
require both the key and certificate.
2. cwallet.sso
2.1. cwallet.sso is an auto-open wallet file that stores database
authentication and signing credentials. A configured wallet consists
of two files cwallet.sso and ewallet.p12 stored in a secured
directory.
2.1.1. Can you see what’s inside cwallet.sso?
Yes: $ORACLE_HOME/oracle_common/bin/orapki wallet display
-wallet /oracle_dir_name/wallet/cwallet.sso
 2.2. The Oracle wallet lock files: Lock files are not recreated
every time a new connection is created, but are only created at
startup to get the DB connection string. ewallet.p12.lck and
cwallet.sso.lck are created by the Oracle UCP driver at startup after
accessing the wallet files ewallet.p12 and cwallet.sso, which are
defined in the argument of the parameter,
-Doracle.net.wallet_location=<path>. Check the permissions on
these lock files. Are they (rw------- or -rwxrwxrwx).

Permissions on the lockfiles

/Users/shashikallae [Sun Mar 17 - 07:48:25 PM]

Shashis@shashikallae $ ls -lthr *.lck

-rw-r--r-- 1 shashikallae staff 0B Mar 17 19:48 ewallet.p12.lck
-rw-r--r-- 1 shashikallae staff 0B Mar 17 19:48 cwallet.sso.lck

/Users/shashikallae [Sun Mar 17 - 07:48:36 PM]

Shashis@shashikallae $ chmod 755 *.lck

/Users/shashikallae [Sun Mar 17 - 07:48:48 PM]

Shashis@shashikallae $ ls -lthr *.lck

-rwxr-xr-x 1 shashikallae staff 0B Mar 17 19:48 ewallet.p12.lck
-rwxr-xr-x 1 shashikallae staff 0B Mar 17 19:48 cwallet.sso.lck

/Users/shashikallae [Sun Mar 17 - 07:48:50 PM]

Shashis@shashikallae $ chmod 775 *.lck

/Users/shashikallae [Sun Mar 17 - 07:48:57 PM]

Shashis@shashikallae $ ls -lthr *.lck

-rwxrwxr-x 1 shashikallae staff 0B Mar 17 19:48 ewallet.p12.lck
-rwxrwxr-x 1 shashikallae staff 0B Mar 17 19:48 cwallet.sso.lck

/Users/shashikallae [Sun Mar 17 - 07:48:59 PM]

Shashis@shashikallae $ chmod 777 *.lck

/Users/shashikallae [Sun Mar 17 - 07:49:06 PM]

Shashis@shashikallae $ ls -lthr *.lck

-rwxrwxrwx 1 shashikallae staff 0B Mar 17 19:48 ewallet.p12.lck
-rwxrwxrwx 1 shashikallae staff 0B Mar 17 19:48 cwallet.sso.lck

Java Parameter Just For Your Understanding (References below)

java –classpath
./lib/ojdbc8.jar:./lib/ucp.jar:./lib/oraclepki.jar:./lib/osdt_core.jar:./lib/osdt_
cert.jar:.
-Doracle.net.tns_admin=/users/test/wallet_dbname
-Doracle.net.ssl_server_dn_match=true
-Doracle.net.ssl_version=1.2 (Not required for 12.2)
-Doracle.net.wallet_location=
“(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=/users/test/
wallet_dbname)))”
UCPSample
What is a Wallet?
A Wallet is a vault or a storage location. It allows users to securely access
the database without providing credentials to third-party software. Oracle
wallet can be stored on the Oracle database server or another secured
server such as an LDAP server.

About orapki utility

Orapki utility is an essential and critical command line utility used by
Database Administrators to,

1. Manage Oracle wallets.

2. Certificate revocation lists.
3. Public Key Infrastructure elements (PKIs).
4. Import and export certificates.

The table below is from Oracle Documentation.

Create a wallet (using orapki tool).

Before creating a wallet using orapki, you must set the below environment
variables,

1. $ORACLE_HOME.
2. $JAVA_HOME.
ORACLE_HOME

The above ORACLE_HOME is just an example. Adjust the settings

according to your environment and the Oracle Database version.

JAVA_HOME

export JAVA_HOME=/oracle/JDKX/jdk1.x.0_xx/
HOW TO CREATE A WALLET FOR THE ORACLE DATABASE?

1. Log in to the Oracle Database server using Putty or ssh.

2. sudo to Oracle User.
3. Check if a wallet exists by launching the sqlplus as sysdba.
4. Execute the SQL from “v$encryption_wallet” to determine if any
wallet exists.
5. Once you have determined no wallet exists, then proceed.
6. Create a directory for the Oracle wallet (mkdir).
7. List the file and set the permissions on the directory.
8. Check the permissions on the above created Oracle Wallet Directory.
9. Next, navigate to the sqlnet.ora file. By default, the sqlnet.ora file is
located in the $ORACLE_HOME/network/admin directory. The
sqlnet.ora file can also be stored in the directory specified by the
TNS_ADMIN environment variable.
10. Update the “WALLET_LOCATION” parameter with the full path
of the above-created wallet directory.
11. Echo the environment variables to see if they are correctly set.
12. Execute oraenv environment variables.
13. Locate orapki to see if it’s in the path.
14. Create the wallet using orapki command.
a. Password Protected wallet (ewallet.p12 and cwallet.sso).
b. Auto-Login only or Single-sign on (Only cwallet.sso).
15. After the above step, change to the Wallet directory from
step -6.
 16. List the directory's contents and see if the PKI files are created
with proper permissions.
17. Login to the SQLPLUS and execute the SQL from
“v$encryption_wallet” to determine if any wallet exists.
18. Once you have confirmed the “WRL_TYPE,
WRL_PARAMETER, STATUS,” exit from SQLPLUS.
19. Add database login credentials to the Wallet using mkstore (If
you are on lower versions of 23c, such as 21c/19c).
20. For Oracle 23c, reach out to Oracle Support to learn how to
add database credentials.
21. Use the orapki command to display the wallet, and change the
Oracle wallet password.

Orapki and related Commands

1. Important SQL Statements: execute them before and after.
a) select * from v$encryption_wallet;

b) select WRL_TYPE, WRL_PARAMETER, STATUS,

WALLET_TYPE, WALLET_OR KEYSTORE from

v$encryption_wallet;

c) Log in to the Linux server where the Oracle database is installed.

a) mkdir -p $ORACLE_HOME/wallet
 b) ls -lthr $ORACLE_HOME/wallet

c) chown -R oracle:oinstall $ORACLE_HOME/wallet (If not

created initially as Oracle user).

d) chmod -R 700 $ORACLE_HOME/wallet

e) ls -lthr $ORACLE_HOME/network/admin/sqlnet.ora

f) vi $ORACLE_HOME/network/admin/sqlnet.ora

g) WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_

DATA=(DIRECTORY=$ORACLE_HOME/wallet))) [Update the

“WALLET_LOCATION” parameter]

h) . oraenv (execute the oraenv to export the Oracle database

parameters)

d) Execute the following commands to create an Oracle wallet with

default trusted certificates.
a) $ORACLE_HOME/oracle_common/bin/orapki wallet

create -wallet $ORACLE_HOME/wallet -auto_login [To

create a Password Protected Wallet ewallet.p12 and

cwallet.sso].
 b) $ORACLE_HOME/oracle_common/bin/orapki wallet

create -wallet $ORACLE_HOME/wallet -pwd password

c) Execute the following commands to create an Oracle wallet with

default trusted certificates and autologin.

$ORACLE_HOME/oracle_common/bin/orapki wallet

create -wallet $ORACLE_HOME/wallet -auto_login_only

[To create an Auto-Login Wallet, only cwallet.sso].

d) Execute the following command to add a self-signed certificate in

the wallet with the dn.

$ORACLE_HOME/oracle_common/bin/orapki wallet add -

wallet $ORACLE_HOME/wallet -dn "CN=Common

Name,OU=Organizational Unit name,O=Organization

name,C=Country" -keysize 2048 -self_signed -validity

3650 -pwd pa$$word -sign_alg sha512

e) Execute the following command to view the Oracle wallet's

contents.
 $ORACLE_HOME/oracle_common/bin/orapki wallet

display -wallet $ORACLE_HOME/wallet -pwd pa$$word

f) Execute the below command to remove the default trusted

certificates in the Oracle wallet.

$ORACLE_HOME/oracle_common/bin/orapki wallet

remove -wallet $ORACLE_HOME/wallet -trusted_cert_all -

pwd pa$$word
Oracle Database Config Files Updates
After creating and configuring the Wallet using Orapki, update the
TNSNAMES.ora, LISTENER.ora, and SQLNET.ora files to ensure seamless
auto-login functionality.

SQLNET.ORA Configuration
A configured sqlnet.ora, as per Oracle’s recommendations, should look
like as follows,

SQLNET.AUTHENTICATION_SERVICES= (BEQ, TCPS)

SSL_VERSION = 0

NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)

 SSL_CLIENT_AUTHENTICATION = TRUE

WALLET_LOCATION =
(SOURCE =
(METHOD = FILE)
(METHOD_DATA =
(DIRECTORY = $ORACLE_HOME/wallet)
)
)

SSL_CIPHER_SUITES= (<custom values according to user>)

LISTENER.ORA Configuration
SSL_CLIENT_AUTHENTICATION = FALSE

WALLET_LOCATION =
(SOURCE =
(METHOD = FILE)
(METHOD_DATA =
(DIRECTORY = $ORACLE_HOME/wallet)
)
)

LISTENER =
(DESCRIPTION_LIST =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = IPC)(KEY = xxxxxxxx1521))
 (ADDRESS = (PROTOCOL = TCP)(HOST = hostname)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCPS)(HOST = hostname)(PORT =
1532))
)
)

TNSNAMES.ORA Configuration
1. A configured tnsnames.ora. Adjust the values as per your
requirements.
2. Ensure the TNS_ADMIN directory includes a properly configured
sqlnet.ora and tnsnames.ora files on the Oracle server and client.
3. After the Oracle server is configured to use Oracle wallets with SSL
certificates, restart the Oracle listener.

ORACLE_DATABASE_ALIAS =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCPS)(HOST = hostname)(PORT =
1521))
)
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = ORACLE_SID)
)
)
Verify the Oracle Database access with the created Wallet
1. Login into the Oracle database as sysdba, create a user associating
with the respective Oracle wallet and grant create session privileges.
SQL> CONNECT / AS SYSDBA
Connected.

SQL> create user username identified externally as

'CN=Common Name,OU=Organizational Unit
name,O=Organization name,C=Country';
User created.

SQL> GRANT CREATE SESSION TO username;

Grant succeeded.

2. Set the TNS_ADMIN variable to the absolute path of the directory

that contains the previously configured tnsnames.ora and sqlnet.ora
files.
TNS_ADMIN=$ORACLE_HOME/network/admin ; export
TNS_ADMIN

echo $TNS_ADMIN

3. Execute the following command to connect to the database using

the wallet configurations set in the tnsnames.ora and sqlnet.ora files.
sqlplus /@ORACLE_SID_ALIAS

Note: The user logs in to the database using Oracle wallet and the
ORACLE_DATABASE_ALIAS that is configured in the sqlnet.ora and
tnsnames.ora files in the TNS_ADMIN directory.
 4. Execute the following SQL to validate the user.
show user;

Note: The query returns the Oracle user associated with the Oracle
wallet configured in the tnsnames.ora and sqlnet.ora files in the
TNS_ADMIN directory.

Important Points to Consider

If the database login fails, it could be any of the following reasons:

1. The files in the TNS_ADMIN directory of the Oracle server and client
are not properly configured.
2. The Oracle wallet configured in the files in the TNS_ADMIN directory
might not be associated with any database users.
3. The user who logged in to the machine does not have appropriate
permissions to access the Oracle wallet configured in the files in the
TNS_ADMIN directory. Double-check the users and grants.

Commands from Oracle Documentation

Note: The -wallet parameter is mandatory for all wallet module
commands.

Creating and Viewing Oracle Wallets with orapki

To create an Oracle wallet:

orapki wallet create -wallet wallet_location

This command will prompt you to enter and re-enter a wallet password. It creates a wallet in the
location specified for -wallet.
To create an Oracle wallet with auto-login enabled:

orapki wallet create -wallet wallet_location -auto_login

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

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

To view an Oracle wallet:

orapki wallet display -wallet wallet_location

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

Adding Certificates and Certificate Requests to Oracle Wallets with orapki

To add a certificate request to an Oracle wallet:

orapki wallet add -wallet wallet_location -dn user_dn -keysize

512|1024|2048|4096

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

To add a trusted certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -trusted_cert -cert

certificate_location

This command adds a trusted certificate, at the specified location (-

cert certificate_location), to a wallet. You must add all trusted certificates in the certificate
chain of a user certificate before adding a user certificate, or the command to add the user
certificate will fail.
To add a root certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -dn

certificate_dn -keysize 512|1024|2048 -self_signed -validity number_of_days

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

To add a user certificate to an Oracle wallet:

orapki wallet add -wallet wallet_location -user_cert -cert

certificate_location

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

Exporting Certificates and Certificate Requests from Oracle Wallets with

orapki

To export a certificate from an Oracle wallet:

orapki wallet export -wallet wallet_location -dn

certificate_dn -cert certificate_filename

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

To export a certificate request from an Oracle wallet:

orapki wallet export -wallet wallet_location -dn

certificate_request_dn -request certificate_request_filename

This command exports a certificate request with the subject's distinguished name (-dn) from a
wallet to a file that is specified by -request.
References
1. https://docs.oracle.com/en/database/oracle/oracle-
database/23/dbimi/configuration-and-administration-tools-
overview.html#GUID-7868473D-432C-419A-94DD-39B25D21211B
2. https://docs.oracle.com/en/middleware/fusion-
middleware/12.2.1.3/asadm/orapki.html#GUID-BA36D997-1D53-
4997-B9A7-A881D51C4F16
3. https://docs.oracle.com/middleware/1212/core/ASADM/walletmgr.ht
m#CDEFHBGA
4. https://www.oracle.com/database/technologies/appdev/jdbc-
downloads.html (Oracle UCP and Java Drivers Download).
5. https://www.oracle.com/java/technologies/downloads/ (Latest JDK
downloads)
6. https://docs.oracle.com/en/cloud/paas/autonomous-
database/serverless/adbsb/connect-jdbc-thin-wallet.html#GUID-
BE543CFD-6FB4-4C5B-A2EA-9638EC30900D
7. Configuring the Secure Sockets Layer Authentication section from
the Database Advanced Security Administrator's Guide 23c.
8. Configuring and Administering the Oracle Net Listener section from
the Database Net Services Administrator's Guide 23c.
9. Configuring the Naming Methods section from the Database Net
Services Administrator's Guide 23c.
Disclaimer
This document is intended for educational purposes only. I am not
liable for any adverse effects resulting from using the information
provided herein. Please consult Oracle support for further assistance
if you have any questions or doubts regarding the tools mentioned in
this document.