Certificate Management

This section describes in general terms the process after obtaining TLS certificates from a Certified Authority (CA) and management with the Recovery Appliance.

A certificate authority (CA) is a company or organization that acts to validate the identities of entities (such as websites, email addresses, companies, or individual persons) and bind them to cryptographic keys through the issuance of electronic documents known as digital certificates. A CA acts as a trusted third party for both the subject (owner) of the certificate and the party relying upon the certificate.

A digital certificate provides:

Authentication; the certificate serves as a credential to validate the identity of its owner. In this case, it authenticates communication from the Recovery Appliance to its protected databases, to other replication Recovery Appliances, and to cloud archival storage.
Encryption for secure communication over insecure networks such as the Internet.
Integrity of documents signed with the certificate so that they cannot be altered by a third party in transit.

The format of these certificates is specified by the X.509 standard.

The techniques vary between CAs for validating the domain to prove that certificate applicant controls the given domain name.

Likewise each CA has its own application steps that are beyond the scope of this chapter to detail.

In general, upon completion of the certificate application process with your chosen CA, you (the applicant) downloads a bundle file containing all of your certificates.

The following assumes that you have that bundle file (*.pfx), named in this example YourCompany.pfx, generated by your chosen CA.

CA Bundle File (*.pfx) of Certificates

The Recovery Appliance TLS encryption requires both a trusted certificate (*.pem) and signed certificate (*.p12). Each certificate needs to be extracted from the bundle file (*.pfx) and then imported into the TLS wallet.

Certificate Creation Using Third Party Software

On the Recovery Appliance, obtain a list of all subject alternative names (SAN) by issuing the following command.
```
racli list san
```
Note:
If this returns nothing, patch to a newer version.
With the SAN information available particularly for common name (CN) and DNS entries, go to your security website and enter this information to obtain the certificate package.

Use the PKCS#8 format and make sure to specify separate files.
Download the certificate ZIP package.
Unzip the certificate ZIP package.

The certificate ZIP package contains several files including trusted certificate and user certificate.
- The trusted certificate may have chain or root in its name, and it is *.pem format.
- User certificate is in *.crt format.
- The *.key file should also in this directory from downloaded package.
With openssl pkcs12, sign the user certificate with the trusted certificate to create a *.p12 file.
```
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:
Do not use ewallet or cwallet for <NAME4>. <NAME4> should refer to local host information or organization name used for <NAME>, <NAME2>, and <NAME3>.
Import both the trusted certificate and the signed user certificate into the Recovery Appliance wallet.
```
racli add certificate --signed_cert=/<DIR>/<NAME4>.p12 
--trusted_cert=/<DIR>/<NAME3>.pem
```
Verify the certificates are in the Recovery Appliance wallet.
```
racli list certificate 
```
Continue with Configuring TLS Data Security on the Recovery Appliance followed by Configuring TLS Data Security on the Client.

Using Your Organization's CA process for TLS Certificates

This section details how to create TLS certificates using openssl.

Large organizations or government bodies, as examples, may have their own PKIs (public key infrastructure), each containing their own CAs.

For the case that your organization has its own certificate process, this section explains how to integrate Recovery Appliance certificates.

Prepare Information for the Certificates

On a Recovery Appliance as an admin_user or root, run this command.

racli list san


    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

The CN (Common Name) item from your host is <yourScanName> which later corresponds to certificate files.

In this example, <yourScanName> is "zdlra09ingest-scan1", the signed certificate file is <yourScanName>.p12, and the trusted certificate is <yourScanName>.pem.

Use an editor to create a CRT configuration file for your organization's certification/security process..

In this example, it is named <YOUR_CONFIG2>. In your environment, all of the constructs with YOUR_... or yourDir are replaced with specific information from the local instance. And the <YOUR_DNS> items are replace with information obtained in previous step using racli list san.

[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = v3_req
distinguished_name = dn
 
[ dn ]
C=$args{YOUR_COUNTRY}
ST=$args{YOUR_STATE}
L=$args{YOUR_LOCATION}
O=$args{YOUR_ORGANIZATION}
OU=$args{YOUR_ORGANIZATION_UNIT}
emailAddress=$args{YOUR_EMAIL_ADDRESS}
CN = $list_san->{CN}
[ v3_req ]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = \@alt_names
[alt_names]
DNS.1 = <YOUR_DNS.1>
DNS.2 = <YOUR_DNS.2>

Upload the <YOUR_CONFIG2>.CRT file to your organization's certification/security process.
Note:
When your CA organization generates the bundle:
- Choose the format PEM (OpenSSL).
- Check the option for including CRT file, because <YOUR_CONFIG2> is needed.
From your organization's certification/security process, download the whole package to a location designated as <yourDir>. This example assumes it is named <yourDownload>.crt.

The trusted certificate, <yourDownload>.pem, is within that package and is used from this package in later steps to generate a signed certificate.
On a Recovery Appliance as an admin_user or root, run this command to generate the key file. In this example, it is yourScanName.key.
```
openssl genrsa --passout pass:<yourPassword> --out <yourDir>/<yourScanName>.key 2048
```

Get the certificate signed by the trusted certificate using the pkcs12 format.

openssl pkcs12 --export --in <yourDir>/<yourDownload>.crt 
    --inkey <yourDir>/<yourScanName>.key
    --certfile <yourDir>/<yourDownload>.pem 
    --passin pass:<yourPassword> 
    --passout pass:<yourPassword> 
    --out <yourDir>/<yourScanName>.p12

Import the signed certificate into the TLS wallet.

racli add certificate --signed_cert=<yourDir>/<yourScanName>.p12

Import the trusted certificate into the TLS wallet.

racli add certificate --trust_cert=<yourDir>/<yourScanName>.pem

After importing the certificates, verify with "racli list certificate" that the certificates are in the raa_certs database table.

# racli list certificate

Created log /opt/oracle.RecoveryAppliance/log/racli_list_certificate.20230329.1146.log
Wed Mar 29 11:46:49 2023: Start: List Certificate
Serial: 9A15CB4B76BBC52D
    Expire Time:      2024-03-28
    Certificate Type: trusted_cert
 
Serial: 95B9181340F644F0
    Expire Time:      2024-03-28
    Certificate Type: signed_cert
 
Wed Mar 29 11:46:49 2023: End: List Certificate

Continue with Configuring TLS Data Security on the Recovery Appliance followed by Configuring TLS Data Security on the Client.

Manually Creating TLS Certificates with RACLI

This section details how to create TLS certificates with RACLI.

If your organization does not have or is not using a Certificate Authority (CA), these instructions allow you to create the needed trusted and signed certificates for TLS operations.

The following information is required for both the trusted and signed certificates:

Country Name
State Name
Organization Name
Organization Unit Name
Email Address

Generate Trusted and Signed Certificates using RACLI.

With the organization information on-hand, issue an RACLI command similar to:

# racli create certificate --country=US --state=CA --location=SF --organization=oracle 
--organization_unit=zdlra --email_address=<YOUR_EMAIL>

Created log /opt/oracle.RecoveryAppliance/log/racli_create_certificate.20230329.1110.log
Enter New Password for Certificate:
Confirm New Password for Certificate:
Wed Mar 29 11:11:22 2023: Start: Create TLS Trusted Certificate
Wed Mar 29 11:11:26 2023: End: Create TLS Trusted Certificate
Wed Mar 29 11:11:26 2023: Start: Create TLS Signed Certificate
Wed Mar 29 11:11:31 2023: End: Create TLS Signed Certificate
Certificate(s) created under /raacfs/raadmin/config/cert

The name of the certificate created is <yourScanName>.p12, where <yourScanName> is the CN for your environment.

To obtain <yourScanName> local host information and Common Name (CN) item.

racli list san

    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

In this example, <yourScanName> is "zdlra09ingest-scan1" and the certificate file is <yourScanName>.p12.

You assign the certificate type (trusted or signed) later when added to the wallet.

Import Certificates into Wallet

Upon completion of creating the trusted and signed certificates, <yourScanName>.pem and <yourScanName>.p12 respectively, import them into the Recovery Appliance wallet for TLS.

Import the certificates (trusted or signed) from the previous steps into the wallet. Here is the generic command, while specific examples are in the next steps.
```
racli add certificate { [--trusted_cert=<VALUE>] |
      [--signed_cert=<VALUE>] | [--self_signed] }
```
Arguments:
- --trusted_cert=<VALUE>: Specify the full path and name of the trusted certificate to be added.
- --signed_cert=<VALUE>: Specify the full path and name of the signed certificate in the trusted store to be added.
- --self_signed: Specifies that Recovery Appliance will look for both certificates from designated locations. This should only be used when the certificates were created by "racli create certificate". This is not the Oracle recommended configuration, and is used only in a test environment.
  
  Note:
  Self-signed certificates should not be used long-term or for production. The recommendation is to use a (trusted) certificate signed by your Certification Authority.
Import the signed certificate into the TLS wallet. If the certificate was created by RACLI, include the --self_signed argument.
```
racli add certificate --signed_cert=<yourDir>/<yourScanName>.p12 [--self_signed]
```
Import the trusted certificate into the TLS wallet. If the certificate was created by RACLI, include the --self_signed argument.
```
racli add certificate --trust_cert=<yourDir>/<yourScanName>.pem [--self_signed]
```

After importing the certificates, verify with "racli list certificate" that the certificates are in the raa_certs database table.

# racli list certificate

Created log /opt/oracle.RecoveryAppliance/log/racli_list_certificate.20230329.1146.log
Wed Mar 29 11:46:49 2023: Start: List Certificate
Serial: 9A15CB4B76BBC52D
    Expire Time:      2024-03-28
    Certificate Type: trusted_cert
 
Serial: 95B9181340F644F0
    Expire Time:      2024-03-28
    Certificate Type: signed_cert
 
Wed Mar 29 11:46:49 2023: End: List Certificate

Continue with Configuring TLS Data Security on the Recovery Appliance followed by Configuring TLS Data Security on the Client.

After a certificate is in the raa_certs database table and when it has less than 90 validation days remaining, an incident is raised. If a certificate expires, the user is required to import a new valid certificate using RACLI to replace the old one.