Oracle® Traffic Director Administrator's Guide 11g Release 1 (11.1.1.7.0) Part Number E21036-04 |
|
|
PDF · Mobi · ePub |
This section contains the following topics:
Note:
The information in this section is aimed at readers who are familiar with the concepts of SSL, certificates, ciphers, and keys. For basic information about those concepts, see Section 11.2.7, "SSL/TLS Concepts."
The CLI examples in this section are shown in shell mode (tadm>
). For information about invoking the CLI shell, see Section 2.3.1, "Accessing the Command-Line Interface."
You can create a self-signed certificate if you do not need your certificate to be signed by a CA, or if you want to test the SSL/TLS implementation while the CA is in the process of signing your certificate.
Note that if you use a self-signed certificate to enable SSL/TLS for an Oracle Traffic Director virtual server, when a client accesses the https://
URL of the virtual server, an error message is displayed indicating that the signing CA is unknown and not trusted. To proceed with the connection, the client can choose to trust the self-signed certificate.
You can create a self-signed certificate by using either the administration console or the CLI.
Before you begin creating a self-signed certificate or a certificate-signing request, decide the following:
The fully qualified host name used in DNS lookups (for example, www.example.com
).
If the host name in the client request does not match the name on the certificate, the client is notified that the certificate server name does not match the host name.
Note:
In a high availability scenario, ensure that the server name (CN) in the server's certificate matches the host name of the VIP that the OTD instance is configured to listen on.
The nickname of the certificate (required only for creating a self-signed certificate).
The certificate's validity period, in months (required only for creating a self-signed certificate).
The key type—RSA or ECC.
Oracle Traffic Director supports generation of the traditional RSA-type keys and the more advanced Elliptic Curve Cryptography (ECC) keys. ECC offers equivalent security with smaller key sizes, which results in faster computations, lower power consumption, and memory and bandwidth savings.
The key size (for RSA) or curve (for ECC).
For RSA keys, you can specify 1024, 2048, 3072, or 4096 bits. Long keys provide better encryption, but Oracle Traffic Director would need more time to generate them.
For ECC keys, you should specify the curve for generating the key pair. Oracle Traffic Director supports the following curves: prime256v1, secp256r1, nistp256, secp256k1, secp384r1, nistp384, secp521r1, nistp521, sect163k1, nistk163, sect163r1, sect163r2, nistb163, sect193r1, sect193r2, sect233k1, nistk233, sect233r1, nistb233, sect239k1, sect283k1, nistk283, sect283r1, nistb283, sect409k1, nistb409, sect571k1, nistk571, sect571r1, nistb571, secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224, prime192v1.
Creating a Self-Signed Certificate Using the Administration Console
To create a self-signed certificate by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to create an self-signed certificate.
In the navigation pane, expand SSL and select Server Certificates.
The Server Certificates page is displayed.
Click the New Self-Signed Certificate button.
The New Self-Signed Certificate wizard starts.
Figure 11-1 New Self-Signed Certificate Wizard
Note:
If the PKCS#11 token, in which the certificates and keys for the configuration are stored, is protected by a pin, the first screen of the wizard displays a prompt to select the token and enter the pin.
Select the appropriate token.
If the keys are stored in the local key database maintained by Oracle Traffic Director, select the internal token.
If the keys are stored in a Smart Card, or in an external device or engine, select the name of that external token.
Enter the pin for the selected token.
To avoid having to enter token pins repeatedly during an administration-console session, you can cache the pins as described in "Caching the Token Pins for an Administration Console Session".
Follow the on-screen prompts to complete creation of the certificate by using the details—server name, certificate nickname, validity, key type, and so on—that you decided earlier.
After the certificate is created, the Results screen of the New Self-Signed Certificate wizard displays a message confirming successful creation of the certificate.
Click Close.
A message is displayed in the Console Message pane confirming that the certificate was created.
The certificate that you created is displayed on the Server Certificates page.
In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes, as described in Section 4.3, "Deploying a Configuration."
Creating a Self-Signed Certificate Using the CLI
To create a self-signed certificate, run the create-selfsigned-cert
command, as shown in the following example:
tadm> create-selfsigned-cert --config=soa --server-name=soa.example.com
--nickname=cert-soa
OTD-70201 Command 'create-selfsigned-cert' ran successfully.
This command creates a self-signed certificate that is valid for a default period of 12 months with the nickname cert-soa
for the server soa.example.com
in the configuration soa
. The key type and other parameters were not specified; so the command creates the certificate with RSA-type (default) keys that are 2048 bits (default) long.
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config
command.
For more information, about create-selfsigned-cert
, see the Oracle Traffic Director Command-Line Reference or run the command with the --help
option.
To obtain a certificate signed by a Certificate Authority (CA), you should submit a Certificate Signing Request (CSR) to the CA, pay the prescribed fee if required, and wait for the CA to approve the request and grant the certificate.
The CSR is a digital file—a block of encrypted text in Base-64 encoded PEM format—containing information such as your server name, organization name, and country. It also contains the public key that will be included in the certificate.
You can create a CSR by using either the administration console or the CLI of Oracle Traffic Director.
Before you begin creating a CSR, decide the server name; key type; and key size (for RSA) or curve (for ECC), as described in Section 11.4.1, "Creating a Self-Signed Certificate.".
Note:
In a high availability scenario, ensure that the server name (CN) in the server's certificate matches the host name of the VIP that the OTD instance is configured to listen on.
Creating a CSR Using the Administration Console
To create a CSR by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to create a CSR.
In the navigation pane, expand SSL and select Server Certificates.
The Server Certificates page is displayed.
Click the Create Certificate Request button.
The Create Certificate Signing Request wizard starts.
Figure 11-2 Create Certificate Signing Request Wizard
Note:
If the PKCS#11 token in which the certificates and keys for the configuration are stored is protected by a pin, the first screen of the wizard displays a prompt to select the token and enter the pin.
Select the appropriate token.
If the keys are stored in the local key database maintained by Oracle Traffic Director, select the internal token.
If the keys are stored in a Smart Card, or in an external device or engine, select the name of that external token.
Enter the pin for the selected token.
To avoid having to enter token pins repeatedly during an administration console session, you can cache the pins as described in "Caching the Token Pins for an Administration Console Session".
Follow the on-screen prompts to complete creation of the CSR by using the details—server name, key type, and so on—that you decided earlier.
After the CSR is created, the Results screen of the Create Certificate Signing Request wizard displays the encrypted text of the CSR as shown in the following example:
-----BEGIN NEW CERTIFICATE REQUEST----- MIICmDCCAYACAQAwDDEKMAgGA1UEAxMBeTCCASIwDQYJKoZIhvcNAQEBBQADggEP ADCCAQoCggEBAMBzgU1mQJrQYQOiedKVpQVedJplQT1gh943RfNfCsl6VbD1Kid8 ... lines deleted ... v6PWA9azqAfnJ8IriK6xTMQ54oQNzSALEKvIGb+jBUUzo2S+UiEr+VXvfPAdHnPX 2ZBCA4qvPr477lETgPphfxDjjvvH+EKrZMClM4JkJ4g3p+X0X+5vz53w964= -----END NEW CERTIFICATE REQUEST-----
Copy and store the CSR text, including the header line BEGIN NEW CERTIFICATE REQUEST
and the footer line END NEW CERTIFICATE REQUEST
, and click Close.
The CSR includes the public key and other information that the CA needs to verify the identity of the Oracle Traffic Director server for which you want to enable SSL. The private key is stored in encrypted form in the INSTANCE_HOME/net-
config_name
/config/key4.db
file.
You can now send the CSR with the required certificate-signing fee to a CA of your choice.
To create a CSR, run the create-cert-request
command, as shown in the following example:
tadm> create-cert-request--config=soa --server-name=soa.example.com
--token=internal
OTD-70201 Command 'create-selfsigned-cert' ran successfully.
This command creates a CSR and displays the encrypted text of the CSR as shown in "Creating a Self-Signed Certificate Using the Administration Console".
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config
command.
For more information, about create-cert-request
, see the Oracle Traffic Director Command-Line Reference or run the command with the --help
option.
After obtaining the CA-signed certificate in response to your CSR, you should install the certificate in the appropriate configuration, as described in Section 11.4.3, "Installing a Certificate."
You can install a self-signed or CA-signed certificate by using the administration console or the CLI. In addition, you can install an existing certificate by using the pk12util utility.
This section contains the following topics:
Section 11.4.3, "Installing a Self-signed or CA-signed Certificate Using the Administration Console"
Section 11.4.3, "Installing a Self-signed or CA-signed Certificate Using the CLI"
Section 11.4.3, "Installing an Existing Certificate Using pk12util"
Installing a Self-signed or CA-signed Certificate Using the Administration Console
To install a self-signed or CA-signed certificate by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to install a certificate.
In the navigation pane, expand SSL, and select Server Certificates or Certificate Authorities.
To install self-signed or CA-signed certificates, select Server Certificates.
To install root certificates or certificate chains, select Certificate Authorities.
Click the Install Certificate button.
The Install Certificate wizard or the Install Server Certificate wizard (Figure 11-3) starts, depending on whether you were on Server Certificates page or the Certificate Authorities page when you clicked the Install Certificate button.
Figure 11-3 Install Server Certificate Wizard
Note:
If the PKCS#11 token in which the certificates and keys for the configuration are stored is protected by a pin, the first screen of the wizard displays a prompt to select the token and enter the pin.
Select the appropriate token.
If the keys are stored in the local key database maintained by Oracle Traffic Director, select the internal token.
If the keys are stored in a Smart Card, or in an external device or engine, select the name of that external token.
Enter the pin for the selected token.
To avoid having to enter token pins repeatedly during an administration console session, you can cache the pins as described in "Caching the Token Pins for an Administration Console Session".
Paste the certificate text from a .pem
file or specify the path name of the certificate file.
If you opt to paste the certificate text, be sure to include the headers BEGIN CERTIFICATE
and END CERTIFICATE
, including the beginning and ending hyphens, as shown in the following example:
-----BEGIN CERTIFICATE----- MIIEuTCCA6GgAwIBAgIQQBrEZCGzEyEDDrvkEhrFHTANBgkqhkiG9w0BAQsFADCB vTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL ... lines deleted ... lRQOfc2VNNnSj3BzgXucfr2YYdhFh5iQxeuGMMY1v/D/w1WIg0vvBZIGcfK4mJO3 7M2CYfE45k+XmCpajQ== -----END CERTIFICATE-----
Follow the on-screen prompts to complete installation of the certificate.
Installing a Self-signed or CA-signed Certificate Using the CLI
To install a self-signed or CA-signed certificate, run the install-cert
command, as shown in the following example:
tadm> install-cert --config=soa --token=internal --cert-type=server --nickname=soa-cert /home/admin/certs/verisign-cert.cer
The --cert-type
option specifies the certificate type—server or CA. This command install the server certificate with the nickname soa-cert
in the configuration soa
. To install a CA certificate, specify ca
for the --cert-type
option. Note that the --nickname
option is not mandatory for installing ca
and chain
certificate types.
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config
command.
For more information about install-cert
, see the Oracle Traffic Director Command-Line Reference or run the command with the --help
option.
Installing an Existing Certificate Using pk12util
The command-line utility pk12util
can be used to import an existing certificate and private key into an internal or external PKCS#11 module. By default, pk12util
uses certificate and private key databases named cert7.db
and key3.db
.
Perform the following steps to install an existing certificate:
Add ORACLE_HOME/lib
to your path.
Run the pk12util
command as shown below:
pk12util -i importfile [-d certdir] [-P dbprefix] [-h tokenname] [-k slotpwfile | -K slotpw] [-w p12filepwfile | -W p12filepw] [-v]
Note:
Option -P
must follow the -h
option, and it must be the last argument.
Enter the exact token name including capital letters and spaces between quote marks.
For example, the following command imports a PKCS12-formatted certificate into an NSS certificate database:
pk12util -i certandkey.p12 [-d certdir][-h "nCipher"][-P https-jones.redplanet.com-jones- ]
Enter the database and/or token password. For more information about PKCS#11 tokens, see Section 11.5, "Managing PKCS#11 Tokens."
Associate the certificate that you installed with one more listeners. For more information, see Section 11.2.2, "Configuring SSL/TLS for a Listener."
You can view a list of the certificates installed in a configuration by using either the administration console or the CLI.
Viewing a List of Certificates Using the Administration Console
To view a list of the certificates installed in a configuration by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to view certificates.
In the navigation pane, expand SSL, and select Server Certificates or Certificate Authorities.
To view self-signed or CA-signed certificates installed in the configuration, select Server Certificates.
To view root certificates or certificate chains, select Certificate Authorities.
The resulting page displays the installed certificates.
Note:
If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
Viewing a List of Certificates Using the CLI
To view a list of the certificates installed in a configuration, run the list-certs
command, as shown in the following examples.
The following command displays a list of the server certificates in the configuration soa
.
tadm> list-certs --config=soa --verbose --all
nickname issuer-name expiry-date
-------------------------------------------
cert-adf adf "Aug 17, 2012 5:32:40 AM"
cert-soa soa "Aug 17, 2012 5:32:26 AM"
The following command displays a partial list of the CA certificates that are installed in the configuration soa
.
tadm> list-certs --config=soa --server-type=ca --verbose --all
nickname issuer-name expiry-date
-------------------------------------------
"Builtin Object Token:GlobalSignRootCA" "GlobalSign" "Jan 28, 2028 4:00:00 AM"
"Builtin Object Token:GlobalSignRootCA-R2" "GlobalSign" "Dec 15, 2021 12:00:00 AM"
To view the properties of a certificate, run the get-cert-prop
command, as shown in the following example.
tadm> get-cert-prop --config=soa --nickname=cert-soa
nickname=cert-soa
subject="CN=soa.example.com"
server-name=soa.example.com
issuer="CN=soa.example.com"
serial-number=00:95:9C:34:04
fingerprint=34:E7:52:5E:3F:0A:EE:30:ED:BF:96:81:DD:1E:A3:02
key-type=rsa
key-size=2048
issue-date=Sep 14, 2011 12:22:41 AM
expiry-date=Sep 14, 2012 12:22:41 AM
is-expired=false
is-read-only=false
is-self-signed=true
is-user-cert=true
is-ca-cert=false
has-crl=false
Note:
If the pin is enabled for a token in the specified configuration, a prompt to enter the token pin is displayed when you run the list-certs
and get-cert-prop
commands.
For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the command with the --help
option.
To renew a certificate, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to renew certificates.
In the navigation pane, expand SSL and select Server Certificates.
The resulting page displays the installed server certificates.
Note:
If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
Click the Renew button for the certificate that you want to renew.
The Renew Server Certificate dialog box is displayed.
Specify the new validity period and click Next.
Click Renew Certificate.
Click Close.
A message is displayed in the Console Messages pane, confirming that the certificate has been renewed for the specified period.
The new expiry date for the certificate is displayed on the Server Certificates page.
In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."
You can delete certificates in a configuration by using either the administration console or the CLI.
Deleting a Certificate Using the Administration Console
To delete a certificate in a configuration by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to delete certificates.
In the navigation pane, expand SSL and select Server Certificates or Certificate Authorities.
To delete self-signed or CA-signed certificates, select Server Certificates.
To delete root certificates or certificate chains, select Certificate Authorities.
The resulting page displays the installed certificates.
Note:
If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
Click the Delete button for the certificate that you want to delete.
If one or more listeners are associated with the certificate that you are deleting, a message is displayed indicating that the certificate cannot be deleted.
If the certificate that you are deleting is not associated with any listener, a prompt to confirm deletion of the certificate is displayed.
Click OK to proceed.
A message is displayed in the Console Messages pane, confirming that the certificate has been deleted.
In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."
Deleting a Certificate Using the CLI
To delete a certificate, run the delete-cert
command.
For example, the following command deletes the certificate with the nickname rsa-cert-1
from the configuration soa
.
tadm> delete-cert --token=internal --config=soa rsa-1
If the certificate that you are deleting is associated with one or more listeners, the following message is displayed.
OTD-64309 Certificate 'rsa-1' is being referred by listeners: listener1,listenerN
You can delete the certificate forcibly by including the --force
option.
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config
command.
For more information about delete-cert
, see the Oracle Traffic Director Command-Line Reference or run the command with the --help
option.
The built-in certificates database in Oracle Traffic Director includes several pre-installed root certificates, including those from popular commercial CAs like VeriSign. You can also use the administration console and the CLI to configure Oracle Traffic Director to trust certificates signed by specific CAs.
Configuring Certificate Trust Flags Using the Administration Console
To specify whether Oracle Traffic Director should trust certificates signed by a specific CA by using the administration console, do the following:
Log in to the administration console, as described in Section 2.3.2, "Accessing the Administration Console."
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to change certificate trust flags.
In the navigation pane, expand SSL and select Certificate Authorities.
The resulting page displays the installed certificates.
Note:
If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
Click the nickname of the certificate for which you want to change the trust flags.
The Edit Certificate Authority dialog box is displayed.
Select the Trusted to Sign Client Certificates or Trusted to Sign Server Certificates check box, as required.
Click Save.
A message is displayed in the Console Messages pane, confirming that the trust flags for the selected certificate have been updated.
In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Section 4.3, "Deploying a Configuration."
Configuring Certificate Trust Flags Using the CLI
To specify whether Oracle Traffic Director should trust certificates signed by a specific CA, run the set-cert-trust-prop
command.
For example, the following command configures the certificate with the nickname Visa eCommerce Root
in the configuration soa
to be trusted to sign client and server certificates.
tadm> set-cert-trust-prop --config=soa --nickname="Visa eCommerce Root"
is-client-ca=true is-server-ca=true
OTD-70201 Command 'set-cert-trust-prop' ran successfully.
For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config
command.
For more information about set-cert-trust-prop
, see the Oracle Traffic Director Command-Line Reference or run the command with the --help
option.