Monday, May 12, 2025

Configuring TLS security on ZDLRA

 TLS security is becoming more and more necessary to protect data, and the ZDLRA supports configuring TLS security for both communicating with the RMAN catalog, and for send/receiving backup pieces. In this blog post I will go through the steps to configure TLS security.


These steps are well documented and you can find the documentation below

Configuring Certificate Management 


As a DBA, some of the concepts were new to me, and I wanted to go through the steps in detail so even a DBA (like me) could understand the process.

  1. Determine the DNS entries 

In order to create the certificate request I first need to gather DNS network information about the ZDLRA.

This can be done by utilizing the "racli list san" command.

racli list san

Below is the example output from the documentation showing the DNS entries.


    Created log /opt/oracle.RecoveryAppliance/log/racli_list_san.log
    Thu May  6 16:18:33 2021: Start: List SAN
    CN = zdlra09ingest-scan1.yourdomain.com
    DNS.1 = zdlra09adm01.yourdomain.com
    DNS.2 = zdlra09adm02.yourdomain.com
    DNS.3 = zdlra09ingest-scan1.yourdomain.com
    DNS.4 = zdlra09ingest01-vip.yourdomain.com
    DNS.5 = zdlra09ingest01.yourdomain.com
    DNS.6 = zdlra09ingest02-vip.yourdomain.com
    DNS.7 = zdlra09ingest02.yourdomain.com
    Thu May  6 16:18:39 2021: End: List SAN

This returns the two pieces of information necessary to create the request.

CN (Common Name)

The common name is the name associated with the certificate.  For the ZDLRA this will be the scan listener's fully qualified DNS name.  You will request a certificate registered to this name.



Alternate Names

As you probably know the Protected Database client connects to the ZDLRA using DNS entries other than the Scan Listener.  The scan listener is used to balance traffic and the connection itself is handed to a DNS/IP address assigned to one of the hosts.
Because of this you can see in the example that there are 7 additional DNS entries that are associated with this certificate as alternate names.

 zdlra09adm01.yourdomain.com,zdlra09adm02.yourdomain.com,zdlra09ingest-scan1.yourdomain.com,zdlra09ingest01-vip.yourdomain.com,zdlra09ingest01.yourdomain.com,zdlra09ingest02-vip.yourdomain.com,zdlra09ingest02.yourdomain.com




2. Prepare Certificate Details

The next step is to create the signed certificate and add it to the ZDLRA
There are 2 methods you can use to create the signed certificate, and they are outlined in the documentation

NOTE: You need a signed certificate in order to implement TLS on the ZDLRA. If you are not familiar with the process of requesting a signed certificate you should contact someone from your security team, or talk to someone in your organization who has gone through the process of requesting a server certificate.

A) Certificate Creation Using Third Party Software.

Request Certificate


With this method you request a signed certificate from your company's certificate authority.
Along with the signed certificate the private key is generated by the certificate authority and provided to you.
I used this method because my companies certificate authority process pre-filled in most of the fields required for the request.


In order acquire the certificate I created a request (following my companies process) and entered the two items determined above in the request details along with the company specific information provided to me by the security team.
  • CN name
  • Alternate DNS names
From this, my company's certificate request process (once approved) returned to me a .ZIP file containing two files
  • {CN name}.crt
  • {CN name}.key
I was also given a link to download the Trusted Certificate associated with the certificate authority used by my company.
I stored the Trusted Certificate in a .pem file.
  • {CN name}.pem

NOTE: The PKCS12 command (used in the next step) requires a "Trusted Certificate" as input. When signing my certificate, I was also given a link to the CA Chain certificates, including ROOT and intermediate CA.  As a DBA, I did not immediately understand this concept.  The "Trusted Certificate" contains the ROOT certificate and any intermediate certificates for the 3rd part Certificate Authority that will validate the signed certificate and ensure the certificate is valid and belongs to DNS names provided with the certificate request.
Examples of Trusted Certificate Authorities are DigiCert, Entrust, GlobalSign, Symantec, etc.
You can find more detail on this concept here.

Once completed you can continue to Step #3 with the 3 files

  • {CN Name}.crt - Signed certificate request
  • {CN Name}.key - Private key
  • {CN name}.pem - Trusted Certificate (may be named differently)

B) Create the request and send the request to be signed

With this method, you create the request and generate the key on the ZDLRA.  The request is sent to the Certificate Authority, and signed. You are responsible for creating and storing the private key.

Manually create the certificate request


You begin by creating a ".crt" file with your company's certificate information.
You can see an example in the documentation. 

You need to replace the information in the request file with your companies detail that was provided to you. 

With your company specific detail, you also need to ensure that the request contains the proper
  • CN name from the first step
  • Alternate names from the first step

Upload your certificate request using your company's process

Upload your certificate request to get it signed.
Once signed you will be returned your certificate and you will be given a copy of (or a link to) your company's Trusted Certificate. (see explanation from the first method if this is a new concept).

You should have 2 files
  • {CN name}.crt
  • {CN name}.pem
NOTE: The .pem file for the trusted certificate might be named differently as it is associated with Certificate Authority rather than the Common Name.

Generate a private key

You need to generate a private key to be associated with your signed certificate.  Using the first method, the key was provided to me. With this method you will generate the key yourself. 

The command to generate this key is below, and you may assign a password to the private key.

openssl genrsa -passout pass:<your password> --out /dir/{CN name>.key 2048

Once completed you will have 3 files
  • {CN Name}.crt - Signed certificate request
  • {CN Name}.key - Private key
  • {CN name}.pem - Trusted Certificate

3. Add Certificate to ZDLRA

Sign the user Certificate with the Trusted Certificate

The next step is create a signed user certificate. This step will create a {CN name}.p12 file that can be added to the wallet on the ZDLRA.

NOTE: A PKCS12 file, often also called a PFDX file, is a standard format for storing digital certificates and private keys within a single, encrypted file. It's commonly used to bundle all the necessary cryptographic components for secure communicate, especially for SSL/TLS certificates and code signing. This file combines the signed certificate, the private encryption key, and the Certificate Authority (Trusted Certificate) information into a single file. 

The PKCS12 file is created by executing "openssl pkcs12 -export" and passing in all three files  from above.

openssl pkcs12 -export --in /<DIR>/<NAME>.crt 
--inkey /<DIR>/<NAME2>.key --certfile  /<DIR>/<NAME3>.pem 
--passin pass:<YOURPASSWORD> --passout pass:<YOURPASSWORD>  
--out /<DIR>/<NAME4>.p12

NOTE: The command includes a password. The --passin password is the password for the .key file and the --passout password will be used adding to the .p12 file when created.

Import the user Certificate with the Trusted Certificate

The next step is to take the .PKCS12 file (contained the signed certificate, the private key, and the Certificate Authority) along with the trusted certificate and add them to the wallet on the ZDLRA.

In this step you execute the command below to add both files to the wallet.
 Ensure you give a fully qualified location for the files.

racli add certificate --signed_cert /dir/{CN name}.p12 --trusted_cert=/dir/{CN name}.pem

NOTE: If this is the first time executing this command you will be asked to provide a password for the wallet. The password will be stored on the ZDLRA and you will not be asked for it again. You will also be asked for the password used to create the PKCS12 files in the previous step

Validate both the user Certificate and Trusted Certificate were added

Execute the "racli list certificate command".

This command should return BOTH the "trusted_cert" and "signed_cert" similar to the example in the documentation.

4. Enable the certificate

Once both the trusted_cert and signed_cert have been added to the wallet on the ZDLRA we can configure the ZDLRA to utilize TLS encryption for BOTH TNS (TCPS SQL*net) and backup (HTTPS) traffic.


NOTE: 
  • The ZDLRA will bounce when implementing this step

  • TLS will be the default for sending and receiving backups. ALL channel configurations should contain "_RA_NO_SSL=TRUEin order to ensure they continue sending backups until they are configured with a client wallet.

  • Configuring TLS with "ONLY" will disable non-TLS connections and traffic. Ensure all of your clients are configured for TLS prior to enabling ONLY.

The command to enable TLS is specified in the documentation with the default settings.
When enabling TLS you need to decide if you want TLS to be mandatory, or optional.

You can use the simple command (without any defaults), or you can change the default ports.
If you want to use all of the defaults you can execute the command below

racli alter network --service=ra_server --encrypt=enable | only




4. Validate the TLS configuration

You can validate the configuration in a couple of different ways.

  • Check the health of TLS with "racli run check --check_name=tls_health". This should give you a PASS status
  • As Oracle execute a listener status "lsnrctl status". Below is the output and I can see that TPCS traffic is configured to go over port 2484 and HTTP will go over port 8005 has a certificate configured to ensure it is encrypted.


5. Configuring the Protected DB Client wallet

When using TLS there are 2 wallet entries that need to be referenced when communicating with the ZDLRA
  • Trusted Certificate - This is a new wallet entry and needs to be present so that the client can validate the certificate.
  • VPC credentials (SEPS) - These are the login credentials for the VPC user. If you are using an EZ connect entry, then you would need to change the entry format to use EZConnect Plus (see below) or a TNS alias. If you are currently using a TNS alias you would need to update the tnsnames.ora entry.
These two entries are independent and do not have to be in the same wallet file.

Update current wallet file to include the Trusted Certificate

In order to add certificates to the wallet file, the wallet file must have been created using the orapki command (rather than mkstore).
If the your wallet file was created with mkstore, you will need to recreate it with the orapki command

You will be loading the Trusted Cert into the wallet file used by the ZDLRA to authenticate the VPC user.
More discussion on where the wallet should be located, and how to set the wallet location is covered in my last blog post you can find here.

Assuming the Trusted Certificate is stored in a file names {CN name).pem you would execute the command below also providing the location of the wallet you want to add the certificate to.
Remember it needs to be added to all nodes in a RAC cluster.

orapki wallet add --wallet <WRL> --trusted_cert --cert <dir>/{CN name}.pem

 

Update the SEPS wallet

If you have been using the EZConnect string in your SEPS wallet vs a tnsnames alias you are at a decision point. 

EZConnect - {host}:{port}/{service}

When using TCPS to encrypt communication, you need to indicate that you are using TCPS, and you need to tell EZConnect where to find the wallet file containing the Trusted Certificate for the communication.
Because EZConnect does not support TCPS you need to use EZConnect Plus. EZConnect Plus was introduced with 18g, and is supported with release 19g and above.

EZConnect Plus [Protocol]://{host}:{port}/{service}?wallet_location={wallet location on disk}

When adding the SEPS credential for the VPC user  you need to use the EZConnect Plus format in your wallet for the connection to succeed.

TNSNAMES Alias - As an alternate to using EZConnect, you can use a tnsnames.ora alias. If using an alias, you would add the entry to the tnsnames.ora file that points to the correct port and uses TPCS, and you would ensure the WALLET_LOCATION set in the associated sqlnet.ora file contains the Trusted Certificate.


EZConnect Plus example :

TCPS://ra1-scan1.mycorp.com:2484/radb1?/u1/app/oracle/mydb/wallet/server_seps


6. Configuring the Client to utilize TLS

There are three places where you would change the settings to use TLS

  • RMAN catalog connections (/@)
  • RMAN channel configuration
  • Protected DB real-time redo destination

RMAN catalog connections

In order to connect to the RMAN securely with TLS you need to ensure that your connection is using the correct encrypted port using the TPCS protocol, and you need to ensure that the WALLET_LOCATION in the sqlnet.ora file points to a wallet containing the Trusted Certificate.  You can connect to the catalog using a few different methods
  • Connect directly using the password and using a tnsnames.ora alias.
  • Connect directly using the password and using the EZConnect Plus format specifying TCPS and the location of the Trusted Certificate wallet.
  • Connect using a SEPS entry pointing to a tnsnames alias or the EZConnect Plus formatted string.

RMAN channel configuration

There are a couple of changes to the channel configuration.  The channel configuration will use the two different wallet entries.
  • ra_wallet - This points to the SEPS wallet location and you specify the credential you want to utilize which is in this SEPS wallet.
  • Trusted Certificate location - If you are using the EZConnect Plus format, you would specify the wallet_location which points to a wallet containing the Trusted Certificate. If you are using a tnsnames alias, the WALLET_LOCATION in the sqlnet.ora points to a wallet containing the Trusted Certificate.
NOTE: If your entry is in the EZConnect Plus format, you might have to enclose the credential on double quotes.

Real-time redo configuration


The real-time redo connection will use the two different wallet entries.
  • SEPS wallet - Real-time redo will determine if the parameter WALLET_ROOT is set and if there is a server_seps directory within the WALLET_ROOT. If so, that wallet is used to look up the SEPS connection. If WALLET_ROOT is not set, the connection will use the WALLET_LOCATION set in the sqlnet.ora file pointed to during DB startup.
  • Trusted Certificate location - Real-time redo will always use the WALLET_LOCATION from the sqlnet.ora file to locate the Trusted Certificate.
NOTE: If your entry is in the EZConnect Plus format, you might have to enclose the credential on double quotes.


Thursday, March 13, 2025

Oracle database wallets for TDE, ZDLRA and External Authentication

 One topic that I spend a lot of time on is "wallets" and the Oracle database. When working with multiple features in the database, there are multiple wallets that are used for different purposes. Along with multiple wallets, there are 2 ways to manage wallets (mkstore and orapki), and there a multiple types of wallets, passworded, auto-login and local.


Wallet Use Cases

Below is a subset of all the places where wallets are used.  

Encryption Wallet : This wallet contains the encryption keys used by DBMS_CRYPTO, TDE and/or RMAN encrypted backups

Strong authentication: Often when external authentication is configured in the database, each database has unique certificates that are stored in a wallet.  In this blog I will refer to this as Strong Authentication. This covers all of DB authentication terms. EUS, OUD, Kerberos, RADIUS, etc.

Certificate authorities and Self-signed certificates : These are used by the database to establish external calls to websites using SSL (HTTPS).  The database can validate the certificate with an external certificate authority, or the self-signed certificate can be stored directly in the wallet.

SEPS authentication : SEPS authentication is used by Oracle clients (including the ZDLRA) to allow scripts to authenticate with a username and password that is stored in an auto-login wallet.  The connection string to the DB is used as the key to retrieve the encrypted connection information.

Real-time redo and TLS certificates for ZDLRA : When the ZDLRA is configured to utilize HTTPS for send/receiving backups, a self-signed certificate is stored in a wallet. This is the same wallet that is used for SEPS authentication of the VPC user.

You can imagine the confusion when you try to combine multiple products that use a wallet, and you want to manage those wallets separately.


Encryption Wallet 

The encryption wallet is the easiest wallet to manage because it is typically isolated from the other wallets that are in use.

The hierarchy Oracle uses to find the location of an encryption wallet is below.  It follows this hierarchy and it will use the first wallet it finds.

WALLET_ROOT : This the recommended location for the encryption wallet as of 19c. The WALLET_ROOT is a spfile/pfile setting that allows you to specify a different location for each database.  It is recommended that the wallet is stored under $ORACLE_BASE/admin/{DB name}/wallet on each node to allow for out of place upgrades.

ENCRYPTION_WALLET_LOCATION in the sqlnet.ora : This was the recommended location prior to 19c.  When multiple databases were sharing the same $ORACLE_HOME (and thus the same sqlnet.ora file), this became confusing. The workaround was to set the location using a variable representation of the DB_NAME.  

$ORACLE_BASE/admin/{DB name}/wallet : This location is the recommended location, But you should set the WALLET_ROOT, or in on an old release (less than 19c)  set the ENCRYPTION_WALLET_LOCATION.  Depending on this location to be the "default" location can cause issues when you start using a wallet for other purposes.  This same location is the default location for any Strong authentication implementations.

Since you should be on 19c, you should be using WALLET_ROOT for encryption wallet location.

NOTE: If you running databases in OCI, it is mandatory to be using WALLET_ROOT in order to utilize the recovery service.

Recommendation :

My recommendation is to always use OKV to manage TDE encryption keys, but I understand that it is a licensable product and it isn't feasible to expect that all customers are using it.

When working in a RAC environment (non-OKV) it becomes critical to have a shared TDE wallet. You may be tempted to store the wallet on ASM, or Exascale. I recommend that you DO NOT.  This makes it much more difficult to backup the wallet, and it makes it more difficult to have a shared SEPS wallet if backing up to a ZDLRA.

Store the TDE encryption wallet on ACFS, and point the WALLET_ROOT to the ACFS location mounted on each node.  When backing up the encryption wallet, copy ONLY the passworded wallet ewallet.p12 to another location to be backed up outside of the DB backups.

Strong authentication wallets

This wallet typically causes the most headaches for users.  The hierarchy Oracle uses to find the location of a Strong authentication wallet is below.  Like the encryption wallet, it follows this hierarchy and it will use the first wallet it finds.

WALLET_LOCATION in the sqlnet.ora : When multiple databases are sharing the same $ORACLE_HOME (and thus the same sqlnet.ora file), this becomes confusing. The workaround was to set the location using a variable representation of the DB_NAME as part of location string.  

$ORACLE_BASE/admin/{DB name}/wallet : This is the location that most customers place their Strong authentication wallets in since it is isolated to the Database associated with the wallet

NOTE: The issue arises when customers use a product/feature that updates the WALLET_LOCATION in the sqlnet.ora, which breaks authentication since the WALLET_LOCATION is checked first.

Use separate wallets, and leverage the TNS_ADMIN variable to point to different sqlnet.ora files and sharing the same $ORACLE_HOME.


Certificate authorities and Self-signed certificates 

The most common use case for certificate authorities is when  utilizing the DBMS_CLOUD family of products.  Products such as DBMS_CLOUD call out object storage and require a secure (HTTPS) connection. In order to open a secure connection the client needs to authenticate the certificate as  valid certificate, or use a self-signed certificate that is stored in the wallet.
This same issue is true when using DBMS_CLOUD_AI and DBMS_VECTOR_CHAIN which makes calls to external LLMs that often require a secure connection.

This wallet is controlled by setting the database property "SSL_WALLET". 
For simplicity I would recommend creating a central wallet that can be used by ALL databases on the host and is stored within $ORACLE_BASE. My favorite location is $ORACLE_BASE/cert_wallet which identifies it as containing certificate authorities.

I do not recommend adding certificates to the Strong authentication wallet, or the SEPS wallet (discussed next) as it becomes more difficult to mange multiple wallets to make updates.

SEPS authentication 

The next wallet I want to discuss is the SEPS authentication wallet. This wallet is used by Oracle clients (sqlplus, RMAN, and ZDLRA) to store the credentials for a database.

The connection string (either an ezconnect string or a tnsnames.ora entry) is added to the wallet, along with the username and password that will be used when connecting using this entry.  

The location of the wallet is stored in the sqlnet.ora file, and there are 2 parameters associated with this setting.

SQLNET.WALLET_OVERRIDE=true

WALLET_LOCATION={location on disk}

NOTE: Setting the WALLET_OVERRIDE to true disables any OPS$ usage and allows the usage of SEPS wallets for authentication. 

Setting the WALLET_LOCATION on a host that supports databases utilizing Strong authentication often causes issues if it does not specify a separate location each database using variable.  The sqlnet.ora file is only read at startup, so changes to the WALLET_LOCATION might not become apparent to after a database bounce.

Recommendation :

If you are using multiple products that use a wallet AND share the same Oracle Home, I recommend using the TNS_ADMIN variable to mange which wallet to use in scripts. 

As wallets become more common for security, separating out the use cases, if possible, will make it easier to manage and rotate authentication information.  With TNS_ADMIN you can point to a directory containing a sqlnet.ora file specific to the database, and leave the original sqlnet.ora file without a WALLET_LOCATION entry. 

Real-time redo and TLS certificates for ZDLRA 

Prior to the 19.18 DB release, configuring real-time redo for databases sending backups to the ZDLRA required a bounce of the database (to refresh the DBs copy of the sqlnet.ora), and it required the WALLET_LOCATION to be set in the sqlnet.ora.

This changed with 19.18, and I recommend you use the new location.

   The hierarchy Oracle uses to find the location of the wallet real-time wallet is below.  Like the encryption wallet, it follows this hierarchy and it will use the first wallet it finds.

WALLET_ROOT/server_seps : If the variable WALLET_ROOT is set, and a wallet exists in the server_seps subdirectory, that wallet is used by the real-time redo.  This is a HUGE improvement as it doesn't require a bounce, and it makes it much easier to avoid issues with Strong authentication, and databases that share the same $ORACLE_HOME.

NOTE: WALLET_ROOT was added in 18c. If you are still using 12.x, you need to use the sqlnet.ora.

WALLET_LOCATION in the sqlnet.ora : When multiple databases are sharing the same $ORACLE_HOME (and thus the same sqlnet.ora file), this becomes confusing. The workaround was to set the location using a variable representation of the DB_NAME.  This is what I mentioned for Strong authentication.

Recommendation :

When backing up to a ZDLRA, especially with real-time redo you should be using a SEPS wallet that is stored under WALLET_ROOT.  
Since the ZDLRA supports encrypted backups, even if you don't own ASO, I recommend creating an encryption wallet with keys to encrypt your backups.  This is much more secure, and this ability is included in the ZDLRA license.
The steps I would recommend for any customer using the ZDLRA are
  • If you don't have an encryption wallet (because you don't own ASO), create one and set the  encryption keys for both the CDB and PDB (if it is multi-tenant). This does require a DB bounce to set the WALLET_ROOT, but this will allow you to have RMAN encrypted backups.
  • In a RAC environment store the encryption wallet on ACFS and point WALLET_ROOT to the ACFS location.
  • Store the SEPS wallet containing the VPC user credentials for the ZDLRA in the WALLET_ROOT/server_seps directory.  This will automatically be used by real-time redo starting with 19.18.
  • Ensure your channel configuration for RMAN points to the WALLET_ROOT/server_seps directory on ACFS for the wallet.
  • In your RMAN scripts ensure that you are pointing to a TNS_ADMIN location that has a sqlnet.ora file pointing to the WALLET_ROOT/server_seps location for WALLET_LOCATION or ensure that OEM has the correct SEPS wallet location set. 

MKSTORE vs ORAPKI

orapki 

The orapki utility manages public key infrastructure (PKI) elements, such as wallets and certificate revocation lists, from the command line.  This is the recommended method of managing wallet files.

You can use the orapki command-line utility to perform the following tasks:

  • Creating and viewing signed certificates for testing purposes

  • Manage Oracle wallets (except for Transparent Data Encryption keystores):

    • Create and display Oracle wallets

    • Add and remove certificate requests

    • Add and remove certificates

    • Add and remove trusted certificates

  • Manage certificate revocation lists (CRLs):

    • Renaming CRLs with a hash value for certificate validation

    • Uploading, listing, viewing, and deleting CRLs in Oracle Internet Directory

NOTE: The above is directly from the 19c documentation.  You can see that orapki is used to manage certificates with no mention of managing SEPS credentials.

mkstore

The first thing you will notice with mkstore, is that the mkstore command should be considered deprecated.  Upon digging into this some more, I found a comment from Russ Lowenthal (VP of Database Security products) who mentions that the SEPS credential wallet management will not be added to orapki until AFTER 23c.

NOTE: Even though it is considered deprecated, mkstore is the only way to manage SEPS credentials from the command line, and should only be used to manage SEPS credentials.

Administer key management

I added the "Administer Key Management" command to this section because it can also be used to manage both secrets and SEPS credentials.
The following options are available and can be found in the documentation.
  • add/update/delete Secret '{secret name}' for client '{client identifier}' --> secret
  • add/update/delete secret '{secret name}' for client '{client identifier}' to {local optionally} auto_login keystore {keystore location}  --> SEPS

How to manage wallets


Wallet Type How to manage contents
Encryption Keys Utilize the "ADMINISTER KEY MANAGEMENT" statement from the database
External user authentication Use orapki to manage certificates, or the OWM tool which uses orapki
Certificate authorities and Self-signed certificate Use orapki to manage certificates
SEPS authentication Use mkstore for now, as orapki does not support SEPS
Real-time redo for ZDLRA Use mkstore for now, as orapki does not support SEPS
TLS certificates for ZDLRA Use orapki to manage the certificates


Wallet names and type

When you look in the wallet directory you would see one, or both of these wallets.

cwallet.sso - This is an auto-login wallet.  With an auto-login wallet you can access the contents without having to provide a password. In almost all cases, you will have this type of wallet entry.

ewallet.p12 - This is the passworded wallet. In order add/change/delete entries you need to specify a password when making those changes.  

NOTE:

  • If only the cwallet.sso exist, you can assume it is an auto-login only wallet.
  • If both wallets exist, you can access the contents without a password, but any add/change/deletion commands will require a password and update both the passworded wallet and the auto-login wallet.
  • If only the ewallet.p12 exists, to access the contents of the wallet  you must provide a password.


Standard Password Protected wallet

This is the least common wallet type (at least alone without an auto-login wallet), since it requires a password to access the contents. This is most commonly used to protect encryption keys for databases since it will require entering password to open the wallet when the database is started.   In this configuration you create a new wallet using orapki or Administore key store and provide a password.  In this case there will only be a single wallet file, ewallet.p12.

NOTE: You cannot create a non auto-login wallet with mkstore 

  • orapki wallet create -wallet {wallet location}
  • administer key management create keystore {wallet location}

Auto-login only wallets

You can create an auto-login wallet using e mkstore,  orapki, or the administer key manage command.  The idea of an auto-login wallet, is that you can add entries to this wallet without needing a password. You can also list the entries in the wallet using either CLI tool. In this configuration there is only a cwallet.sso file in the wallet directory

Auto-login wallets

This is the most common configuration that you will see.  There is both a passworded wallet, and an auto-login wallet. With both wallets, it requires a password to make changes, but no password is required to open the wallet and use it.  The two wallets are synchronized when you make changes.

There are two ways to create auto-login wallets.

    1. Create a non auto-login wallet using orapki or within the database, then create an auto-login wallet from the non auto-login wallet.

  • orapki wallet create -wallet {wallet location}
    • orapki wallet create -wallet {wallet location} -auto_login  OR
    • mkstore -wrl {wallet location} -createSSO
  • administer keystore create keystore {wallet location}
    • administer keystore create auto_login keystore from keystore {wallet location}
     2. Create an auto-login wallet  and non auto-login wallet together
  •     orapki wallet create -wallet {wallet location} -auto_login

Local Auto-login wallets

Local auto-login wallets work the same way as the auto-login wallet, EXCEPT, the wallet is encrypted in a way that makes it only usable on the host it was created.  This limits any security risks if the wallet is copied (or restored) onto a different host.

When creating a local auto-login wallet you would use 
  • mkstore -wrl {wallet location} -createLSSO
  • orapki wallet create -wallet {wallet location} auto_login_local
  • administer keystore create local auto_login keystore from keystore {wallet location}

NOTE:

  • Local auto-login wallets are much more secure as they can only be used on the host  where the wallet was created. 
  • When backing up wallets, this includes Encryption wallets, only backup the ewallet.p12 file.  This ensures that a password is required to utilize the wallet.
NOTE: When only backing up the ewallet.p12, be sure you know the password so that you can recreate the auto-login wallet.
  • ALWAYS review the permissions on your wallet files, especially the auto-login wallet files containing credentials.  Any user that can access the auto-login wallet file can utilize the credentials contained within the wallet.

ASM/Exascale for Encryption wallets

You probably noticed that I am not a fan of ASM/Exascale as an encryption wallet location, even though ASM in mentioned in the documentation. 
I will add more to this section, but this is my reasoning for not preferring ASM.
  1. It's easy to forget backing up the wallet file.  Having it on ASM requires copying it back to the file system to get backed up.  It is very easy to forget about this, rotate the keys, and not have a wallet backup.
  2. WALLET_ROOT is becoming the starting point for different wallet files, not just encryption wallets.  ZDLRA is the first example. When WALLET_ROOT points to ASM or Exascale, then the same wallet cannot be used by many tools because they only expect wallets on the file system.
Shared wallets make sense, that's why I prefer ACFS, or a mounted filesystem for WALLET_ROOT.


Summary 

Starting with DB 19.18, you have the ability to store individual credential wallets for real-time redo transportation when leveraging ZDLRA for backups.  You can also use the TNS_ADMIN variable to set a different location when using SEPS authentication.  It is now possible to manage multiple wallets separately without having conflicts between products and features.


MY RECOMMENDATIONS (summary):

  • Use Oracle Key Vault (OKV) for encryption keys.  OKV is an Oracle product specifically designed to securely store and manage encryption keys, and much more.  OKV has tight integration with the Oracle Database.  If you are not using OKV, at least store Encryption Keys on ACFS as the shared location (not ASM or Exascale).
  • Use WALLET_ROOT if you are on 18c+.  This will continue to be used products to help separate wallet locations for different uses cases.  The ZDLRA is the first of many products to use the hierarchy for wallet files. 
  • Backup only the ewallet.p12.  This is the passworded wallet and with the password it can be used to recreate the auto-login wallet. This is especially critical for Encryption keys.

BUT - Make sure you know the password. Without the password, you can't recreate the auto-login wallet.

  • Lock down permissions on wallet files to only the account that needs access, especially the cwallet.sso file (auto-login).
  • Whenever possible create local auto-login wallets that can only be used on the source host where the wallet was created. This wallet, however,  cannot be shared across nodes.
  • Keep your SEPS wallets separate by utilizing the TNS_ADMIN variable and having a custom sqlnet.ora file.
  • If you are backing up to a ZDLRA create an encryption wallet with keys, and set the WALLET_ROOT location.  Put the SEPS wallet for ZDLRA under WALLET_ROOT/server_seps.  This wallet can also be used for the TPCS certificate if you configure HTTPS.   Keep this configuration separate to avoid conflicts with other products.


Wednesday, March 5, 2025

Oracle DB release 23.7 includes "Select AI" with the DBMS_CLOUD_AI package

 The latest release of Oracle DB23ai (23.7) now includes the promised packages for DBMS_CLOUD.  

I'm not talking about the ADB release, this is the general 23.7 DB release, and it even includes Select AI !!



You can find the documentation for how to install DBMS_CLOUD here.  This is updated documentation that supersedes the MOS note 2748362.1 - How To Setup And Use DBMS_CLOUD Package.


What's Included in 23.7

The Following packages are included in 23.7

DBMS_CLOUD - The SQL to install this package has been included with the DB release since 19.9.  More procedures have been added over time to provide more functionality with object storage.

DBMS_CLOUD_AI - This is the most interesting part of the release (at least to me).  This package is used as the basis for Select AI.

DBMS_CLOUD_NOTIFICATION -  This package allows you to send messages, or the output of a query to an e-mail or to Slack.

DBMS_CLOUD_PIPELINE -  This package allows you to create a data pipeline for loading and exporting data in the cloud.  This is mainly used to interact with data in object storage on a scheduled basis.

DBMS_CLOUD_REPO -  This package allows you to interact with hosted code repositories from the oracle Database. Repositories like Github are supported.


Where to start

The following are some great places to learn more about how to use the packages.

Videos:

Documentation:


Installing in your Database

I started by going through the install and prerequisites found here.
  1. Install the DBMS_CLOUD packages in a 23.7 CDB using the instructions in the 23.7 Documentation (20.2)
  2. Create the SSL wallet with certificates (20.3)
  3. Configure your environment with the new wallet (20.4).
NOTE: If you are using SEPS (ZDLRA uses SEPS), or other user authentication this is the same wallet that other authentication methods use).

    4. Configure the ACL list to allow DB calls to the LLM that you are going to be using (20.5)

    5. Verify the configuration for DBMS_CLOUD (20.6)

    6. Configure users or roles to use DBMS_CLOUD. (20.7).  In my case I granted the access to "SH".

    7. Create the credential for the LLM you are using in your PDB

    8. Create the Profile which identifies the tables that you want to use in your PDB

Example


I installed the Sample sales schema into my PDB (SH user) and followed the instructions in the documentation found here.


Below is the output of one of the queries that I ran using "Select AI" once I went through these steps to install it with the sample SH schema.

SQL> select ai tell me how many customers are in each country;

COUNTRY_NAME                             CUSTOMER_COUNT
---------------------------------------- --------------
Italy                                              7780
Singapore                                           597
Brazil                                              832
United Kingdom                                     7557
Australia                                           831
Japan                                               624
Canada                                             2010
Argentina                                           403
Poland                                              708
China                                               712
Germany                                            8173
United States of America                          18520
France                                             3833
Spain                                              2039
New Zealand                                         244
Denmark                                             383
South Africa                                         88
Saudi Arabia                                         75
Turkey                                               91


I am just getting starting determining how to best use this feature, and this should be enough to get your started.



Monday, January 20, 2025

Oracle DB 23ai in your datacenter

 Oracle DB 23ai is available for Exadata and I've been spending a lot of time working on building some demos in my lab environment. Below is the architecture.


To help you get started below are the pre-steps I did to create this demo.

  1. Download and install DB 23ai (latest version which was 23.6 when I created my demo).
  2. Install APEX within the database.  Most existing demos use APEX, and makes it easy to build a simple application.  Here is a link to a blog that I used to explain the install process, and ORDS setup for the webserver.
  3. Optional - Install the embedding model in your database to convert text it's vector representation. Here is a link to how to do this. You can also use an external model with Ollama.
  4. Optional - Install DBMS_CLOUD to access object storage.  Most demos access object storage to read in documents. Here is a link to my blog on how to install it.  I actually used ZFS for my object storage after installing DBMS_CLOUD. You can OCI, or even a PAR against any Object storage.
  5. Install ollama. Ollama is used to host the LLM, and you within Ollama you can download any open source model.. For my demo, I downloaded and installed llama3.2.
The demo I started with was the Texas Legislation demo which can be found here. This link points to a video showing the demo, and within the description is a link to the code and instruction on how to recreate the demo in your environment which are located in Github

The majority of the application is written in APEX, and can be downloaded using the instructions on github which can be found here.

The major changes I had to make to get this demo working on-premises had to do with using Ollama rather than access OCI for the LLM.

Documentation for using Ollama can be found here.

The biggest challenge was the LLM calls.  The embedding and document search was the same DBM_VECTOR calls regardless of the model.  The Demo, however uses DBMS_CLOUD.send_request which does not support OLLAMA.

I changed the functions to call DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT instead, and I built a "prompt" instead of a message.  This is outlined below.

Description Demo request Ollam request
Call LLM with chat history and results/td> dbms_cloud.send_request

Message:
Question:
DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT

Question:
Chat History:
Context:

SUMMARY : This RAG demo is a great place to start learning how to create a RAG architecture, and with just a few changes many of the Demo's created for Autonomous can be used on-premises also !