SSL Certificate Management

Learn to use single socket layer (SSL) certificates with your Load Balancer resource.

To use SSL with your load balancer, you must add one or more certificate bundles to your system. The certificate bundle you upload includes the public certificate, the corresponding private key, and any associated Certificate Authority (CA) certificates. For the easiest workflow, upload the certificate bundles you want to use before you create the listeners or backend sets you want to associate them with.

Load balancers commonly use single domain certificates. However, load balancers with listeners that include request routing configuration (see Request Routing Management) might require a subject alternative name (SAN) certificate (also called multi-domain certificate) or a wildcard certificate. The Load Balancing service supports each of these certificate types.

Note

  • The Load Balancing service does not generate SSL certificates. It can only import an existing certificate that you already own. The certificate can be one issued by a vendor, such as Verisign or GoDaddy. You can also use a self-signed certificate that you generate with an open source tool, such as OpenSSL or Let's Encrypt. Refer to the corresponding tool's documentation for instructions on how to generate a self-signed certificate.

  • If you submit a self-signed certificate for backend SSL, you must submit the same certificate in the corresponding CA Certificate field.

Oracle Cloud Infrastructure accepts x.509 type certificates in PEM format only. The following is an example PEM encoded certificate:


-----BEGIN CERTIFICATE-----
<Base64_encoded_certificate>
-----END CERTIFICATE-----

Converting to PEM Format

If you receive your certificates and keys in formats other than PEM, you must convert them before you can upload them to the system. You can use OpenSSL to convert certificates and keys to PEM format. The following example commands provide guidance.

Certificate or Certificate Chain from DER to PEM

openssl x509 -inform DER -in <certificate_name>.der -outform PEM -out <certificate_name>.pem

Private Key from DER to PEM

openssl rsa -inform DER -in <private_key_name>.der -outform PEM -out <private_key_name>.pem

Certificate Bundle from PKCS#12 (PFX) to PEM

openssl pkcs12 -in <certificate_bundle_name>.p12 -out <certificate_bundle_name>.pem -nodes

Certificate bundle from PKCS#7 to PEM

openssl pkcs7 -in <certificate_bundle_name>.p7b -print_certs -out <certificate_bundle_name>.pem

Configuring Peer Certificate Verification

Peer certificate verification is used for client authentication. Peer certificate verification depth is the number of certificates in the chain that need to be verified for client authentication.

The following are expected values to be set:

  • One intermediate certificate, client certificate, root certificate - 2

  • Client certificate, root certificate - 1s

To determine if your peer certificate verification is configured incorrectly, note the following:

  • The client indicates that it is unable to verify the certificate and results in a client SSL handshake failure. This error message varies based on the client type.

  • In the load balancer logs, the following error appears: Client %s has SSL certificate verify error

  • Use the OpenSSL utility to run the following command: openssl verify -verbose -CAfile RootCert.pem Intermediate.pem

    An error occurs that shows at what depth the validation failure is occurring: error 20 at 0 depth lookup:unable to get local issuer certificate

To resolve this situation, provide the correct certificate depth and confirm that the client certificate and certificate authority certificate match and are in the correct order.

Uploading Certificate Chains

If you have multiple certificates that form a single certification chain (for example, any intermediate certificate authority certificates), then include all relevant certificates in one file in the correct order before you upload them to the system. The correct order begins with the certificate directly signed by the trusted root certificate authority at the bottom of the list. Any additional certificates are pasted above the signed certificate.

Combine the server certificate (SSL_Certificate.crt) and the intermediate certificate authority certificate (intermediateCA.crt) files into a single, concatenated file.

To get a single, concatenated file from the SSL certificate and the intermediate certificate authority certificate, open a command prompt and run the following command:

cat ssl_certificate.crt IntermediateCA.crt >> certbundle.pem

The following example of a concatenated certificate chain file includes four certificates:

-----BEGIN CERTIFICATE-----
Base64-encoded_certificate
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Base64-encoded_certificate
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Base64-encoded_certificate
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Base64-encoded_certificate
-----END CERTIFICATE-----

Submitting Private Keys

Note

Oracle recommends a minimum length of 2048 bits for your RSA private key.

If your private key submission returns an error, the three most common reasons are:

  • You provided an incorrect passphrase.

  • Your private key is malformed.

  • The system does not recognize the encryption method used for your key.

Key Pair Mismatch

If you receive an error related to the private key and public key being mismatched, then before uploading, use the following OpenSSL commands to confirm that they are part of the same pair:

openssl x509 -in certificate_name.crt -noout -modulus | openssl sha1
openssl rsa -in private_key.key -noout -modulus | openssl sha1

Confirm that the returned sha1 hash values match exactly. If they are different, then the private key provided is not used to sign the public certificate and cannot be used.

Private Key Consistency

If you receive an error related to the private key, then you can use OpenSSL to check its consistency:

openssl rsa -check -in <private_key>.pem

This command verifies that the key is intact, the passphrase is correct, and the file contains a valid RSA private key.

Decrypting a Private Key

If the system does not recognize the encryption technology used for your private key, decrypt the key. Upload the unencrypted version of the key with your certificate bundle. You can use OpenSSL to decrypt a private key:

openssl rsa -in <private_key>.pem -out <decrypted_private_key>.pem

Updating an Expiring Certificate

To ensure consistent service, you must update (rotate) expiring certificates:

  1. Update your client or backend server to work with a new certificate bundle.

    Note

    The steps to update your client or backend server are unique to your system.

  2. Upload the new SSL certificate bundle to the load balancer:
    1. Open the navigation menu, click Networking, and then click Load Balancers.

    2. Click the name of the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.

    3. Click the load balancer you want to configure.

    4. In the Resources menu, click Certificates, and then click Add Certificate.

    5. In the Add Certificate dialog box, enter the following:

      • Certificate Name: Required. Specify a friendly name for the certificate bundle. It must be unique within the load balancer, and it cannot be changed in the Console. (It can be changed using the API.) Avoid entering confidential information.

      • Choose SSL Certificate File: Required. Drag and drop the certificate file, in PEM format, into the SSL Certificate field.

        Alternatively, you can choose the Paste SSL Certificate option to paste a certificate directly into this field.

        Important

        If you submit a self-signed certificate for backend SSL, you must submit the same certificate in the corresponding CA Certificate field.

      • Specify CA Certificate: Optional. (Recommended for backend SSL termination configurations.) Select (check) this box if you want to provide a CA certificate.

        • Choose CA Certificate File: Drag and drop the CA certificate file, in PEM format, into the CA Certificate field.

          Alternatively, you can choose the Paste CA Certificate option to paste a certificate directly into this field.

      • Specify Private Key: Optional. (Required for SSL termination.) Select (check) this box if you want to provide a private key for the certificate.

        • Choose Private Key File: Drag and drop the private key, in PEM format, into the Private Key field.

          Alternatively, you can choose the Paste Private Key option to paste a private key directly into this field.

        • Enter Private Key Passphrase: Optional. Specify the private key passphrase.

    6. Click Add Certificate.

  3. Edit listeners or backend sets (as needed) so they use the new certificate bundle

    Editing a listener:

    1. Open the navigation menu, click Networking, and then click Load Balancers.
    2. Choose the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.

    3. In the Resources menu, click Listeners.

    4. For the listener you want to edit, click the Actions icon (three dots), and then click Edit Listener.

    5. In the Certificate Name list, choose the new certificate bundle.

    6. Click Submit.

    Editing a backend set:

    Important

    Updating the backend set temporarily interrupts traffic and can drop active connections.

    1. Open the navigation menu, click Networking, and then click Load Balancers.

    2. Click the name of the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.

    3. In the Resources menu, click Backend Sets, and then click the name of the backend set you want to edit.

    4. Click Edit Backend Set.

    5. In the Edit Backend Set dialog box, select (check) Use SSL.

    6. In the Certificate Name list, choose the new certificate bundle.

    7. Click Save Changes.

  4. (Optional) Remove the expiring SSL certificate bundle
    Important

    You cannot delete an SSL certificate bundle that is associated with a listener or backend set. Remove the bundle from any additional listeners or backend sets before deleting.

    1. Open the navigation menu, click Networking, and then click Load Balancers.

    2. Click the name of the Compartment that contains the load balancer you want to modify, and then click the load balancer's name.

    3. Click the load balancer you want to configure.

    4. In the Resources menu, click Certificates.

    5. For the certificate you want to delete, click the Actions icon (three dots), and then click Delete.

    6. Confirm when prompted.

Configuring SSL Handling

Learn about configuring SSL handling for a Load Balancer resource.

You can perform the following SSL handling tasks for a load balancer:

  • Terminate SSL at the load balancer. This configuration is frontend SSL. Your load balancer can accept encrypted traffic from a client. No encryption of traffic exists between the load balancer and the backend servers.

  • Implement SSL between the load balancer and your backend servers. This configuration is backend SSL. Your load balancer does not accept encrypted traffic from client servers. Traffic between the load balancer and the backend servers is encrypted.

  • Implement point-to-point SSL. Your load balancer can accept SSL encrypted traffic from clients and encrypts traffic to the backend servers.

Terminating SSL at the Load Balancer

To terminate SSL at the load balancer, you must create a listener at a port such as 443, and then associate an uploaded certificate bundle with the listener. See Creating Listeners for more information.

Implementing Backend SSL

To implement SSL between the load balancer and your backend servers, you must associate an uploaded certificate bundle with the backend set. See Creating Backend Sets for more information.

Note

  • If you want to have more than one backend server in the backend set, sign your backend servers with an intermediate CA certificate. The intermediate CA certificate must be included as part of the certificate bundle.

  • Your backend services must be able to accept and terminate SSL.

Implementing Point-to-Point SSL

To implement point-to-point SSL, you must associate uploaded certificate bundles with both the listener and the backend set. See Creating Listeners and Creating Backend Sets for more information.

Adding Certificates

Add a certificate to a Load Balancer resource.

Use one of the following methods to add a certificate to a selected load balancer.

To add a certificate using the Console

Use the OCI Console to add a certificate to a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer whose rule set you want to delete.

    The Load Balancer Details dialog box appears.

  6. Click Certificates under Resources.

    The Certificates list appears. All certificates are listed in tabular form.

  7. Click Add Certificate.

    The Add Certificate dialog box appears.

  8. Enter the following:

    • Certificate Name: Required. Specify a friendly name for the certificate bundle. It must be unique within the load balancer, and it cannot be changed in the Console. (It can be changed using the API.)

    • Choose SSL Certificate File: Required. Drag and drop the certificate file, in PEM format, into the SSL Certificate field.

      Alternatively, you can choose the Paste SSL Certificate option to paste a certificate directly into this field.

      Important

      If you submit a self-signed certificate for backend SSL, you must submit the same certificate in the corresponding CA Certificate field.

    • Specify CA Certificate: Optional. (Recommended for backend SSL termination configurations.) Select (check) this box if you want to provide a CA certificate.

      • Choose CA Certificate File: Drag and drop the CA certificate file, in PEM format, into the CA Certificate field.

        Alternatively, you can choose the Paste CA Certificate option to paste a certificate directly into this field.

    • Specify Private Key: Optional. (Required for SSL termination.) Select (check) this box if you want to provide a private key for the certificate.

      • Choose Private Key File: Drag and drop the private key, in PEM format, into the Private Key field.

        Alternatively, you can choose the Paste Private Key option to paste a private key directly into this field.

      • Enter Private Key Passphrase: Optional. Specify the private key passphrase.

  9. Click Add Certificate.

To add a certificate using the CLI

Use the command line interface (CLI) to list the certificates to a Load Balancer resource.

Enter the following command:

oci lb certificate create --certificate-name certificate_name --load-balancer-id load_balancer_id --items items [OPTIONS]

See the CLI online help for a list of options:

oci lb certificate create --help

See oci lb certificate create for a complete description of the command.

To add a certificate using the API

Use the API to add a certificate to a Load Balancer resource.

Run the CreateCertificate method to create a certificate for a load balancer. See CreateCertificate for a complete description.

Listing Certificates

List the certificates for a Load Balancer resource.

Use one of the following methods to display a list of certificates for a selected load balancer.

To list the certificates using the Console

Use the OCI Console to list the certificates for a Load Balancer resource.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer whose rule set you want to delete.

    The Load Balancer Details dialog box appears.

  6. Click Certificates under Resources.

    The Certificates list appears. All certificates are listed in tabular form.

To list the certificates using the CLI

Use the command line interface (CLI) to list the certificates for a Load Balancer resource.

Enter the following command:

oci lb certificate list --certificate-name certificate_name --load-balancer-id load_balancer_id --items items [OPTIONS]

See the CLI online help for a list of options:

oci lb certificate list --help

See oci lb certificate list for a complete description of the command.

To list the certificates using the API

Use the API to list the certificates for a Load Balancer resource.

Run the ListCertificates method to list the certificates for a load balancer. See ListCertificates for a complete description.

Deleting Certificates

Delete a certificate from a Load Balancer resource.

Important

You cannot delete an SSL certificate that is associated with a listener or backend set. Remove the bundle from any listeners or backend sets before deleting.

Use one of the following methods to delete a certificate from a selected load balancer.

To delete a certificate using the Console

Use the OCI Console to delete a certificate from a Load Balancer resource.

Important

You cannot delete an SSL certificate that is associated with a listener or backend set. Remove the bundle from any listeners or backend sets before deleting.

  1. Open the navigation menu, click Networking, and then click Load Balancers.

  2. Select the Compartment from the list.

    All load balancers and network load balancers in that compartment are listed in tabular form.

  3. (optional) Select a State from the list to limit the load balancers displayed to that state.

  4. (optional) Uncheck Load Balancer under Type to only display load balancers.

  5. Select the load balancer whose rule set you want to delete.

    The Load Balancer Details dialog box appears.

  6. Click Certificates under Resources.

    The Certificates list appears. All certificates are listed in tabular form.

  7. Click the Actions icon (Actions icon) associated with the certificate you want to delete and click Delete.

  8. Confirm the deletion when prompted.

To delete a certificate using the CLI

Use the command line interface (CLI) to delete a certificate from a Load Balancer resource.

Enter the following command:

oci lb certificate delete --certificate-name certificate_name --load-balancer-id load_balancer_id --items items [OPTIONS]

See the CLI online help for a list of options:

oci lb certificate delete --help

See oci lb certificate delete for a complete description of the command.

To delete a certificate using the API

Use the API to delete a certificate from a Load Balancer resource.

Run the DeleteCertificate method to create a certificate for a load balancer. See DeleteCertificate for a complete description.