28 Configuring Keystores
-
Using Keystores and Certificates in a Development Environment
-
Obtaining and Storing Certificates for Production Environments
For background information about identity and trust keystores, see Identity and Trust in Understanding Security for Oracle WebLogic Server.
About Configuring Keystores in WebLogic Server
Learn about the concepts related to the configuration and use of keystores with WebLogic Server.
About Private Keys, Digital Certificates, and Trusted Certificate Authorities
Private keys, digital certificates, and trusted certificate authorities establish and verify server identity and trust.
SSL uses public key encryption technology for authentication. With public key encryption, a public key and a private key are generated for a server. Data encrypted with the public key can only be decrypted using the corresponding private key and data encrypted with the private key can only be decrypted using the corresponding public key. The private key is carefully protected so that only the owner can decrypt messages that were encrypted using the public key. Furthermore, anyone with the public key can verify that a message was encrypted by the owner of the private key.
The public key is embedded in a digital certificate and is cryptographically bound to the accompanying information about the owner of the public key, such as name, street address, and e-mail address. The CA signs the entire certificate, including the key, thereby vouching that the key belongs to the named entity. A private key and digital certificate provide identity for the server.
The data embedded in a digital certificate is verified by a certificate authority (CA) and digitally signed with the CA's digital certificate. The trusted CA certificate establishes trust for a certificate.
An application participating in an SSL connection is authenticated when the other party evaluates and accepts the application's digital certificate. Web browsers, servers, and other SSL-enabled applications generally accept as genuine any digital certificate that is signed by a trusted CA and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the digital certificate of the CA used to sign it expired. A client will not trust a server certificate if the host name in the digital certificate of the server does not match the URL specified by the client.
Servers need a private key, a digital certificate containing the matching public key, and a certificate of at least one trusted certificate authority (CA). WebLogic Server supports the following options for configuring private keys, digital certificates, and trusted CA certificates:
-
Custom Keystores: You can provide your own keystores containing your own private keys and digital certificates.
-
Demo Keystores: You can use the demonstration digital certificates, private keys, and trusted CA certificates that are automatically generated by WebLogic Server for development and testing. They are located in the
DOMAIN_HOME
\security
, andJAVA_HOME
\lib\security
directories.Note:
The demonstration digital certificates, private keys, and trusted CA certificates should be used in development environments only.
-
Domain Keystores: Use certificates generated, obtained and managed by the Certificate Management Service.
Note:
The Certificate Management Service is available as a Technical Preview in this release of WebLogic Server for testing purposes only. Do not use it in production environments. For more information, see Using the Certificate Management Service in Administering Security for Oracle WebLogic Server.
Using Separate Keystores for Identity and Trust in Custom Keystore Configurations
When using custom keystore configurations, you must configure an identity keystore and a trust keystore.
In general, systems within a domain have the same trust rules — they use the same set of trusted CAs — but they tend to have per-server identity. Identity requires a private key, and private keys should not be copied from one system to another. Therefore, you should maintain separate identity keystores for each system, each keystore containing only the server identity needed for that system. However, trust keystores can be copied from system to system, thus making it easier to standardize trust conventions.
Trust can be stored in a file-based JDK keystore without having security issues because a trust store contains only certificates, not private keys.
Using PKCS12 Keystores in WebLogic Server
PKCS12 is an extensible, standard, and widely-supported format for storing cryptographic keys. In JDK 9, the JDK default keystore type changed from JKS to PKCS12.
The JDK default keystore type is determined by the default defined in the keystore.type
property in the java.security
file of your JDK installation. In JDK 8, the default was JKS. As of JDK 9, the default is PKCS12. However, you can explicitly specify the type of keystore you require. Existing keystores will not change.
Note the following as of JDK 9:
-
PKCS12 keystores require a passphrase to access public certificates.
-
The JDK installation provides the
cacerts
truststore. By default, WebLogic Server will use the JKS format for SSL/TLS Java Standard Trust but it also supports PKCS12. -
If you did not explicitly set the keystore type in your WebLogic Server configuration and you rely on the JDK default, when you upgrade to JDK 9 or later, the JDK default keystore type may need to be updated. In this case, if you want to continue to use JKS as the keystore type, you can set the
storetype
property in thejava.security
file to JKS. If you prefer to use PKCS12, you can convert your JKS keystores using the-importkeystore
option of thekeytool
utility. See Converting the Default JKS Keystore for FIPS Compliance or thekeytool
utility documentation in the JDK Tool Specifications . -
For PKCS12 keystores, keytool does not support different keystore and key passwords. It uses the keystore password to persist the key. If you specify a password using the
-keypass
option and it differs from the password specified for the-storepass
option, keytool displays a warning and ignores the keypass value.
The following table summarizes the supported keystores and defaults for WebLogic Server features and components.
Table 28-1 Keystore Type Defaults in WebLogic Server
Feature/Component | Keystore Type | Comments |
---|---|---|
SSL/TLS configuration settings for custom trust and custom identity keystores | PKCS12 or JKS | You can specify the keystore type using the configuration setting. If not specified, the JDK default keystore type in the java.security file is used. See Configuring Keystores.
|
Network Channel Identity Keystore | PKCS12 or JKS | You can specify the keystore type using the configuration setting. If not specified, the JDK default keystore type in the java.security file is used. See Configuring an Identity Keystore Specific to a Network Channel.
|
PKI Credential Mapping Provider Keystore | JKS (the default), or PKCS12 | You can specify PKCS12 as the Keystore Type to change from the JKS default. See Configuring a PKI Credential Mapping Provider. |
LDAP Authentication Provider SSL configuration | JKS or PKCS12 | You can specify the keystore type to use for custom trust using the configuration setting. See Enabling an LDAP Authentication Provider for SSL. |
Node Manager SSL Configuration | JKS or PKCS12 | You can specify the keystore type using the configuration setting. If not specified, the JDK default keystore type in the java.security file is used. See Using SSL With Java-based Node Manager in Administering Node Manager for Oracle WebLogic Server.
|
Demonstration Identity and Trust Keystores | PKCS12 only | These demonstration keystores are for development use only. See Using the Demonstration Keystores |
Java Standard Trust | JKS or PKCS12 |
|
JDK Keytool Utility | JKS or PKCS12 | You can specify the keystore type using the command line property. If not specified, the JDK default keystore type in the java.security file is used. See Creating a Keystore Using Keytool |
DemoCertGen Utility | PKCS12 only | The DemoCertGen utility only supports creating keystores in PKCS12 format. See Creating a Keystore Using DemoCertGen. |
ImportPrivateKey Utility | JKS or PKCS12 | You can specify the keystore type using the command line property. If not specified, the JDK default keystore type in the java.security file is used. See Creating a Keystore Using ImportPrivateKey |
Domain Keystores (with Certificate Management Service) | PKCS12 only | The Domain Keystores are only available when the Certificate Management Service is enabled. See Domain Keystores. |
Using the Certificate Management Service
Use the Certificate Management Service to simplify and streamline the management of SSL/TLS certificates in a WebLogic Server domain.
Note:
The Certificate Management Service is available as a Technical Preview in this release of WebLogic Server for testing purposes only. Do not use it in production environments.
The following components work together to ensure that certificates are made available and distributed to servers as necessary:
-
The Certificate Management Service makes requests of supported Certificate Issuers to obtain certificates. It stores these certificates in the Domain Keystores and distributes them to servers as necessary.
-
Certificate Issuers obtain and refresh the certificates for servers in the domain. WebLogic Server supports several Certificate Issuers. See Certificate Issuers.
-
Domain Keystores stores all of the keystores managed by the Certificate Management Service. See Domain Keystores.
This arrangement allows WebLogic Server to seamlessly distribute certificates to the correct servers and to regularly check with Certificate Issuers to obtain new certificates so certificates remain valid with minimal intervention.
The Certificate Management Service runs on the Administration Server and on individual Managed Servers. Communication between these instances is facilitated by the Remote Certificate Service, a REST application also running on the Administration Server. The Remote Certificate Service REST application also responds to certificate requests from Managed Servers. The Remote Certificate Service application is deployed as an internal application, with the context root wls-certificate-service
.
Note:
REST API calls to the Remote Certificate Service require SSL/TLS so you must either expose an SSL/TLS port for the Administration Server or you must configure an Administration Channel. If a Managed Server has not yet initialized its own trust store, it can temporarily rely on the local machine-trust
keystore until it initializes its own trust store.
When a domain is created, the Certificate Management Service initializes the WebLogic Domain CA (the Domain Certificates Issuer), and its related keystores, as well as the machine-trust
keystore for the machine where the Administration Server is running. When new Managed Servers are configured to use Domain Keystores, they will temporarily use these keystores until their own server and machine keystores finish initializing. See Domain Certificates Issuer (WebLogic Domain CA).
For instructions on enabling and configuring the Certificate Management Service, see Configuring the Certificate Management Service.
Certificate Issuers
The Certificate Management Services uses Certificate Issuers to obtain and maintain certificates required for secure communication between servers.
The Certificate Management Service supports the following Certificate Issuers:
- Domain Certificates Issuer (WebLogic Domain CA)
- Provisioned Certificates Issuer
- OCI Certificates Plug-in Certificate Issuer
Domain Certificates Issuer (WebLogic Domain CA)
The Domain Certificates Issuer issues certificates on behalf of the WebLogic domain CA, a self-signed root CA for the domain. It is automatically enabled as soon as the Certificate Management Service is enabled. All servers in a domain will request a certificate from the domain CA.
The current and historical Domain CA certificates are automatically trusted by servers using Domain Keystores.
Typically, the Domain Certificates Issuer issues certificates that combine server authentication, client authentication, and signing and encryption into a single certificate. You can choose to configure the issuer to issue certificates that are intended for a single purpose instead. In secured production mode, single purpose certificates are enabled by default.
Single purpose certificates are not currently supported for machine certificates.
Table 28-2 WebLogic CA Certificate Attributes
Attribute | Value |
---|---|
Subject DN | CN=Domain Root Certificate Authority R1,OU=domain:<domain-name>,O=WebLogic Domain PKI |
Issuer DN | Subject DN (for self-signed) |
Validity Period | The default validity period is 365 days but you can specify any value, in days, between 45 to 1825 days. |
Public Key Info | 2048-bit RSA key |
Serial Number | A 16-byte random BigInteger() |
Signature Algorithm | SHA-256 with RSA Encryption |
Fingerprints | SHA-256, SHA-1 |
Basic Constraints |
Critical, CA == yes PathLen = 1 |
Key Usages | Critical, Digital Signature, Certificate Signing, CRL Signing |
Subject Key ID | RFC 3280 type 1 subject key identifier |
Table 28-3 Server Certificate Attributes
Attribute | Value |
---|---|
Subject DN | CN=<hostname>, OU=server:<server-name>, OU=domain:<domain-name>, O=WebLogic Domain PKI |
Issuer DN | Issuing CA's Subject DN |
Validity Period | The default validity period is 90 days but you can specify any value, in days, between 15 to 365 days. |
Subject Alternate Names (SANs) | Additional DNS or IP address added to the certificate per configuration |
Public Key Info | 2048-bit RSA key |
Serial Number | A 16-byte random BigInteger() |
Signature Algorithm | SHA-256 with RSA Encryption |
Fingerprints | SHA-256, SHA-1 |
Basic Constraints | Critical, CA == no |
Key Usages | Critical, Digital Signature, Key Encipherment, Data Encipherment
Note: Single purpose certificates may not support all of these usages. |
Extended Key Usages | Server Authentication, Client Authentication, Code Signing
Note: Single purpose certificates will each support only one of these usages. |
Subject Key ID | RFC 3280 type 1 subject key identifier |
Authority Key ID | The Issuing CA's RFC 3280 type 1 subject key identifier |
Provisioned Certificates Issuer
The Provisioned Certificates Issuer distributes private keys and certificates that were manually added to the domain by an administrator. They are stored in the identity keystore on the Administration Server and available to any Managed Server that is configured to use them.
You must enable the Provisioned Certificates Issuer. See Configure the Certificate Management Service.
If you plan to use provisioned certificates, it is your responsibility to ensure that these certificates meet the security standards required for your environment.
OCI Certificates Plug-in Certificate Issuer
The OCI Certificates Plug-in Certificate Issuer is a plug-in issuer that obtains certificates directly from the OCI Certificates service. The OCI Certificates service uses one or more self-signed CAs configured for the OCI tenancy to issue certificates.
For general information on the OCI Certificates service, see OCI Certificates in OCI Documentation.
Domain Keystores
Domain Keystores are a set of identity and trust keystores managed by the Certificate Management Service. These Java keystores can contain identity certificates, trust certificates, certificate authority certificates, and associated private keys.
These keystores are PKCS12 keystores that use the .p12
extension. Private key entries are password protected.
Each keystore has an associated properties file that contains the name, type, and purpose of the keystore, along with the passphrases needed to access the keystore and its entries. Sensitive values are encrypted. The properties file is co-located with the keystore file and shares its name barring the file extension. For example:
-
DOMAIN_HOME/security/pki/domain/domain-trust.p12
-
DOMAIN_HOME/security/pki/domain/domain-trust.props
For more information on working with the Certificate Management Service and Domain Keystores, see Configuring the Certificate Management Service.
Table 28-4 describes the keystores within Domain Keystores.
Table 28-4 Domain Keystore
Keystore Name | Location | Description |
---|---|---|
server-servername-trust |
DOMAIN_HOME/security/pki |
Stores the local server's copy of the domain-trust certificates. This trust store also includes any certificates stored in the |
server-servername-identity |
DOMAIN_HOME/security/pki |
Stores the identity certificates for a server. |
machine-trust |
DOMAIN_HOME/security/pki/machine |
Stores a copy of the domain's trust certificates, |
machine-identity |
DOMAIN_HOME/security/pki/machine |
Stores the identity certificates for a machine. |
domain-trust |
DOMAIN_HOME/security/pki/domain |
Stores the trust anchors for the domain. By default, this is the self-signed CA certificate for the domain. Note: This keystore is only available on the Administration Server. |
domain-ca |
DOMAIN_HOME/security/pki/domain |
The signing key and certificate(s) for the Domain Certificate Authority. Note: This keystore is only available on the Administration Server. |
provisioned-trust |
DOMAIN_HOME/security/pki/provisiond |
Stores trust anchors that the domain should trust in addition to the domain CA. Note that this is only to provision specific CAs that may be needed for a particular environment. This file is only updated by admins, and read by the Certificate Service. Note
|
provisioned-identity |
DOMAIN_HOME/security/pki/provisioned |
Stores keys and certificates that an administrator can make available to other servers. The Certificate Management Service fetches certificates from the Provisioned Certificates Issuer on request and distributes them to servers. Note: This keystore is only available on the Administration Server. |
Using Certificate Management Service with Node Manager
If you plan to use the Certificate Management Service and Node Manager in the same domain, you must perform some additional configuration.
The Certificate Management Service provisions machine certificates to every machine in the domain. Node Manager uses the domainpki-machine-identity
certificate from the machine-identity
keystore as its identity certificate, and obtains trust anchors from the machine-trust
keystore.
The machine-trust
keystore is created when the domain is created, and then copied to new machines when they are configured. If the domain trust certificates change, the machine-trust
keystore is updated by the servers running on the host.
You can use Certificate Management Service with either per domain and per host Node Manager configurations. See Using SSL With Java-Based Node Manager in Administering Node Manager for Oracle WebLogic Server.
Configuring the Certificate Management Service
You can configure the Certificate Management Service as needed for your environment.
Table 28-5 Configuring the Certificate Management Service
If you want to do this... | Follow this... |
---|---|
Enable the Certificate Management Service |
Configure the Certificate Management Service in Oracle WebLogic Remote Console Online Help. |
Enable Domain Keystores |
Configure Keystores in Oracle WebLogic Remote Console Online Help. |
Import Certificates into the Provisioned Keystores |
Import Certificates into the Provisioned Trust or Identity Keystores in Oracle WebLogic Remote Console Online Help. |
Configure Single Purpose Certificates |
Configure Single Purpose Certificates in Oracle WebLogic Remote Console Online Help. |
Configure the OCI Certificates Plug-in Certificate Issuer |
Configure the OCI Certificates Plug-in Certificate Issuer in Oracle WebLogic Remote Console Online Help |
Review Certificates in Domain Keystores |
Review Certificates Managed by Certificate Management Service in Oracle WebLogic Remote Console Online Help. |
Refresh Certificates and Trust |
Refresh Certificates and Trust in Oracle WebLogic Remote Console Online Help. |
Export Trusted Certificates |
Export Trusted Certificates in Oracle WebLogic Remote Console Online Help. |
Roll the Domain CA Certificate |
Roll Domain CA Certificate in Oracle WebLogic Remote Console Online Help. |
Configuring Custom Keystores: Main Steps
To configure custom identity and trust keystores for a WebLogic Server instance being used in a production environment, complete the following steps:
- Create the keystore to hold the server identity certificate. See Creating a Keystore.
- Create a Certificate Signing Request (CSR), and submit it to a reputable Certificate Authority. See Generating a Certificate Signing Request. Oracle strongly recommends this step for production environments.
- Import the identity and trust certificates returned by the CA. See Importing Certificates into the Trust and Identity Keystores.
- Configure the trust and identity keystores with WebLogic Server. See Configuring Keystores with WebLogic Server
If you are working in a development environment where security requirements typically are less stringent, you can use the demonstration certificates included with WebLogic Server and create self-signed certificates. However, do not use these certificates in a production environment. See Using Keystores and Certificates in a Development Environment.
How WebLogic Server Locates Trust
WebLogic Server uses the following algorithm when it loads its trusted CA certificates:
-
If the trust keystore is specified by the
-Dweblogic.security.SSL.trustedCAkeystore
command-line argument in either of the following use cases, then WebLogic Server loads the trusted CA certificates from that keystore:- Starting a Managed Server that downloads the initial configuration from the Administration Server over SSL
- Running a WebLogic client, such as WLST, that connects to a WebLogic Server server instance over SSL
Note:
If, however, the Managed Server instance is started usingDOMAIN_DIR/bin/startManagedWebLogic.sh managed_instance_name admin_SSL_url
, then step 2 is not applicable to the outbound SSL connection established with the Administration Server for downloading the configuration. -
Else if the keystore is specified in the configuration file (
config.xml
), WebLogic Server loads trusted CA certificates from the specified keystore. If the server is configured with DemoTrust, trusted CA certificates will be loaded from DOMAIN_HOME\security\DemoTrust.p12
,ORACLE_HOME\wlserver\server\lib\DemoTrust.jks
, and the JDKcacerts
keystores.
Creating a Keystore
You can create a PKCS12 keystore using the DemoCertGen
utility, or a JKS or PKCS12 keystore using the keytool
, or the ImportPrivateKey
utilities. Oracle recommends that you keep server certificates and trusted CA certificates in separate keystores.
The following sections explain how to create a keystore. However, in practice, creating a keystore is typically done in conjunction with obtaining a server certificate for the identity keystore or importing a trusted CA certificate into the trust keystore, as explained in Obtaining and Storing Certificates for Production Environments.
Note:
The preferred keystore format is JKS or PKCS12. WebLogic Server supports private keys and trusted CA certificates stored in files or in the WebLogic Keystore provider for the purpose of backward compatibility only.
Keystore File Name Requirements
When choosing a name for the keystore file:
-
Do not choose a file name longer than 256 characters.
-
Do not use special characters, except for an underscore (_) or hyphen (-).
-
Do not use non-ASCII characters.
-
Follow the operating system-specific rules for directory and file names.
Creating a Keystore Using DemoCertGen
DemoCertGen is a key and certificate management utility included in WebLogic Server. It combines functionality from the CertGen, keytool, and ImportPrivateKey utilities to configure demonstration keystores for a domain.
DemoCertGen
creates PKCS12 keystores that are suitable for development and testing purposes only. Do not use them in production environments.
DemoCertGen
will generate a self-signed demo CA and then import the demonstration certificates, signed with the demo CA, into the identity and trust keystores, in the DOMAIN_HOME/security
directory.
Note:
DemoCertGen
also creates a DemoCerts.props
file to store the passphrases for the identity and trust keystores, among other properties. This file also located in the DOMAIN_HOME/security
directory. Do not manually edit DemoCerts.props
.
For more information on DemoCertGen
, see DemoCertGen in Command Reference for Oracle WebLogic Server.
Regenerating Demo CA and Demo Certificates using DemoCertGen
To ensure there is no lapse in service, you should regenerate your demo CA certificate and demo certificates before they expire. The demo CA certificate expires after 5 years. The demo certificates expire after 6 months.
Note:
You can use the pack
and unpack
commands to create a Managed Server template that includes the newly generated demo CA and certificates.
Perform steps 1 through 4 to generate the new demo CA and certificates, then run the pack
command with your preferred parameters. Make sure you include -managed=true
. Then, on the remote machine, run the unpack
command with your preferred parameters. Do not perform step 5.
See Pack and Unpack Command Reference in Creating Templates and Domains Using the Pack and Unpack Commands.
Creating a Keystore Using Keytool
Keytool is a key and certificate management utility that is included in the JDK. It allows you to administer your own public/private key pairs and associated certificates for use in self-authentication (in which you authenticate yourself to other users or services) or data integrity and authentication services, using digital signatures. Keytool also allows you to cache the public keys, in the form of certificates, of your communicating peers.
When you use keytool to create a public and private key pair, keytool also creates a keystore if one does not already exist in the current directory.
Note:
-
The default keystore type is determined by the JDK default as defined by the
keystore.type
property in thejava.security
file. As of JDK 9, the default ispkcs12
. You can change the default by specifying thestoretype
property. - For PKCS12 keystores, keytool does not support different keystore and key passwords and uses the keystore password to persist the key. If you specify a password using the
-keypass
option and it differs from the password specified for the-storepass
option, keytool displays a warning and ignores the keypass value.
To use keytool to create a JKS or PKCS12 keystore, complete the following steps:
-
Create a directory to hold the keystore. For example:
ORACLE_HOME
/keystores
. -
Change to the
bin
subdirectory of your WebLogic domain root directory. For example:prompt> cd DOMAIN_HOME/bin
-
Run the
setDomainEnv
script, which sets the domain-wide environment for starting and running WebLogic Server instances. -
Change to the directory you created for the keystore and enter the following command:
prompt> keytool -genkeypair -alias alias -keyalg RSA -keysize 2048 -dname dn -keystore keystore -storetype keystoretype
In the command, enter the following values:
-
A private key alias, represented by
alias
. -
The X.500 Distinguished Name associated with the private key alias, represented by
dn
. -
The name of the keystore being created, represented by
keystore
. -
The key pair generation algorithm
RSA
. -
The type of keystore being created, either
jks
orpkcs12
, represented bystoretype
.
-
When you enter the keytool command as described in the preceding steps, keytool automatically prompts you for the following:
- The keystore password
- The password for the private key, which is represented by its alias. Note that for PKCS12 keystores, you are not prompted for the key password.
For example:
prompt> keytool -genkeypair -alias server_cert -keyalg RSA -keysize 2048 -dname "CN=server.avitek.com,OU=Support,O=Avitek,L=Reading,ST=Berkshire,C=GB" -keystore keystore.jks -storetype jks Enter keystore password: Re-enter new password: Enter key password for <server_cert> (RETURN if same as keystore password): Re-enter new password:
Note the following from the preceding example:
-
The keystore file is named
keystore.jks
. -
The private key alias is
server_cert
. -
The X.500 Distinguished Name, which consists of the WebLogic Server host and DNS domain name, is
server.avitek.com
. -
The keystore type is
jks
.
Note:
Make note of the private key alias and passwords you specify, and be sure to record passwords only in a safe location.
For a summary of keytool commands commonly used with WebLogic Server, see Keytool Command Summary. For details, see help for the keytool
utility in
JDK Tool Specifications
.
Creating a Keystore Using ImportPrivateKey
If you have a certificate and private key, you use the ImportPrivateKey utility to create a keystore in which you can store that certificate and key.
If you used CertGen to create a private key file that is protected by a password, that password is the one required by ImportPrivateKey to extract the key from the key file and insert the key in the keystore being created.
To create a keystore using ImportPrivateKey, complete the following steps:
-
Change to the
bin
subdirectory of your WebLogic domain root directory. -
Run the
setDomainEnv
script, which sets the domain-wide environment for starting and running WebLogic Server instances. -
Change to the directory in which you want to create the keystore.
-
Generate the certificate and private key.
For example, using CertGen:
-
Enter the following command to generate the certificate file named
testcert
and the private key file namedtestkey
:prompt> java utils.CertGen -keyfilepass mykeyfilepass -certfile testcert -keyfile testkey Generating a certificate with common name machine-name and key strength 2048 issued by CA with certificate from CertGenCA.der file and key from CertGenCAKey.der file
-
Convert the certificate from DER format to PEM format. For example:
prompt> java utils.der2pem CertGenCA.der
Note:
By default, the CertGen utility looks for the
CertGenCA.der
andCertGenCAKey.der
files in the current directory, or in theWL_HOME
/server/lib
directory, as specified in theweblogic.home
system property or the CLASSPATH.Alternatively, you can specify CA files on the command line. If you want to use the default settings, there is no need to specify CA files on the command line.
-
-
Concatenate the certificate and the Certificate Authority (CA) certificate. For example:
prompt> cat testcert.pem CertGenCA.pem >> newcerts.pem
-
Create a new keystore and load the private key.
For example, to create a keystore named
mykeystore
and load the private key located in the filetestkey.pem
, enter the following command:prompt> java utils.ImportPrivateKey -keystore mykeystore -storepass mystorepasswd -keyfile mykey -keyfilepass mykeyfilepass -certfile newcerts.pem -keyfiletestkey.pem -alias passalias -storetype jks No password was specified for the key entry Key file password will be used Imported private key testkey.pem and certificate newcerts.pem into a new keystore mykeystore of type jks under alias passalias
Note:
The defaultstoretype
is determined by the default for the JDK as defined by the keystore.type
property in the java.security
file. As of JDK 9, the default is PKCS12. You can change the default by specifying the storetype
property.
For more information about using the ImportPrivateKey utility, see ImportPrivateKey in Command Reference for Oracle WebLogic Server.
Using Keystores and Certificates in a Development Environment
Learn about the tools and procedures to generate digital certificates and private keys for demonstration or testing purposes in a development environment. This information does not apply to a WebLogic Server production environment.
Using the Demonstration Keystores
By default, WebLogic Server is configured with two keystores, which are located in the DOMAIN_HOME
\security
directory:
-
DemoIdentity.p12
—Contains an identity certificate and demonstration private key (paired to the public key within the certificate) for WebLogic Server. This keystore contains the identity for WebLogic Server. -
DemoTrust.p12
—Contains the CA certificate for the domain. This keystore establishes trust for WebLogic Server.
Note:
As of WebLogic Server 14.1.2.0.0, the demonstration keystores that are generated at domain creation, are created in PKCS12 format.For testing and development purposes, the keystore configuration is complete. The digital certificates and trusted CA certificates in the demonstration keystores are signed by a WebLogic Server demonstration certificate authority. A unique demo CA certificate is created for each new domain. Do not use these demonstration keystores in a production environment. For information about how to configure keystores for use in a production environment, see Obtaining and Storing Certificates for Production Environments.
Creating Demonstration Certificates Using CertGen
The following sections explain the use of CertGen for creating demonstration certificates and private keys for use in a development environment:
About CertGen
The CertGen utility provides command line options to specify a CA certificate and key to be used for issuing generated certificates. The digital certificates generated by the CertGen utility by default have the host name of the machine on which they were generated, as the value for its common name field (cn
). Beginning with WebLogic Server 14.1.1.0.0, the digital certificates by default also contain the Subject Alternative Name (SAN) extension that lists the fully-qualified DNS name as the value for the SAN extension.
Command line options let you specify values for the cn
and other Subject domain name (DN
) fields, such as orgunit
, organization
, locality
, state
, and countrycode
.
Use the CertGen utility if you want to set an expiration date in the digital certificate or specify a correct host name in the digital certificate so that you can use host name verification. You can specify additional host names, or IP addresses, or both, in the SAN extension of your digital certificates by using the -a DNS:<hostname>,IP:<ip address>
option. Optionally, you can create your certificates without the SAN extension, by using the -nosandnshost
option at the command line. This option disables the fully-qualified DNS name and creates your certificates without the SAN extension.
The CertGen utility generates public certificate and private key files in PEM and DER formats. To view the details of the generated digital certificate on Windows platforms, double-click .der
files in Windows Explorer
By default, the CertGen utility uses the following demonstration digital certificate and private-key files: CertGenCA.der
and CertGenCAKey.der
. CertGen looks for these files in the current directory, or in the WL_HOME
/server/lib directory
, as specified in the weblogic.home
system property or the CLASSPATH
. If you want to use these files, you do not need to specify CA files in the CertGen command; however, you can specify those CA files in the command if desired.
For complete details about the CertGen utility's syntax and arguments, see CertGen in the Command Reference for Oracle WebLogic Server.
Using CertGen to Create a Certificate and Private Key
To create a certificate and private key using CertGen, complete the following steps:
CertGen Usage Notes
Note the following about using CertGen:
-
By default, the CertGen utility looks for the
CertGenCA.der
andCertGenCAKey.der
files in the current directory, or in theWL_HOME
/server/lib
directory, as specified in theweblogic.home
system property or the CLASSPATH.Alternatively, you can specify CA files on the command line. If you want to use the default settings, there is no need to specify CA files on the command line.
- By default, the CertGen utility generates demo certificates with the SAN extension containing the fully-qualified DNS name.
Optionally, you can create demo certificates without the SAN extension and disable the fully-qualified DNS name, by using the
-nosandnshost
command-line option. -
If you do not explicitly specify a host name with the
-cn
option, CertGen uses the JDKInetAddress.getHostname()
method to get the host name, which CertGen inserts in the Subject common name.However, note that the results of the
getHostName()
method depends on the platform on which it is used. For example:-
On some platforms, such as Solaris, this method returns a fully qualified domain name (FQDN).
-
On other platforms, such as Windows NT, this method returns a short host name.
-
On Solaris platforms, the result of
InetAddress.getHostname()
depends on how the hosts entry is configured in the/etc/nsswitch.conf
file.
If WebLogic Server is acting as a client and host name verification is enabled (which it is by default), you need to ensure that the host name specified in the URL matches the Subject common name in the server certificate. Otherwise, connections fail because the host names do not match.
-
Limitation on CertGen Usage
By default, a WebLogic Server domain is configured with the DemoIdentity.jks
keystore, which contains a demonstration public certificate and private key for WebLogic Server. This certificate and key are created by CertGen with the default options of containing the host name in the common name field (cn
), and the fully-qualified DNS name in the SAN (Subject Alternative Name) extension value. As a result, attempts to establish SSL connections may fail in some situations due to a host name verification exception. This section describes this limitation and provides some workarounds.
If you are using the demo certificates in a multi-server domain, Managed Server instances fail to boot if they cannot establish an SSL connection with the Administration Server. An error message similar to the following may be generated:
BAD_CERTIFICATE alert was received from node-name.avitek.com - xxx.yy.zzz.yyy. Check the peer to determine why it rejected the certificate chain (trusted CA configuration, hostname verification). SSL debug tracing may be required to determine the exact reason the certificate was rejected.
This error occurs because the host name verifier, which is enabled by default in all WebLogic domains and which is used during the SSL handshake, compares the value of the SAN extension in the certificate or the value of the cn
field (if the certificate is created without the SAN extension) with the host name of the SSL server that accepts the SSL connection. If these names do not match, the SSL connection is dropped.
If you use the demo identity certificates in a WebLogic domain, you can use the following workarounds:
-
Specify the SSL listen address of each WebLogic Server instance in a domain as the host name that appears in the certificate's
cn
field. Avoid using the fully-qualified DNS name or IP address. This workaround consists of two steps:-
When using the Configuration Wizard to create the WebLogic domain, specify the listen address of each WebLogic Server instance as a simple host name as it appears in the certificate's
cn
field, not as a fully-qualified DNS name or IP address. For example, if the host name in the certificate isavitek01
, the listen address for the server instance should be specified simply asavitek01
. -
At run time, when specifying the SSL listen address of a server instance, make sure the URL also matches the host name for that server as specified as the certificate's
cn
field. For example:https://avitek01:7002
-
-
When starting a Managed Server instance, pass the URL of the Administration Server's SSL listening address as a parameter to the
startManagedWebLogic
script. The URL should be specified in a form that excludes the domain suffix. For example:C:\mydomain\bin> startManagedWebLogic.cmd https://admin01:7002
-
Disable host name verification. This causes WebLogic Server to skip the verification check of ensuring that the host name in the URL to which a connection is made matches the host name in the digital certificate that the server sends back as part of the SSL connection.
You can disable host name verification by including a command similar to the following in the
setDomainEnv
script:set JAVA_OPTIONS=%JAVA_OPTIONS% -Dweblogic.security.SSL.ignoreHostnameVerification=true
For information about configuring host name verification, see Using Host Name Verification.
Note:
Oracle does not recommend using the demo certificates, or turning off host name verification, in production environments.
Using Your Own Certificate Authority
Many companies act as their own certificate authority. To use those trusted CA certificates with WebLogic Server:
Converting a Microsoft p7b Format to PEM Format
Digital certificates issued by Microsoft are in a format (p7b) that cannot be used by WebLogic Server. The following example converts a digital certificate in p7b (PKCS#7) format to PEM format on Windows XP:
Configuring Demo Certificates for Clients
To use SSL/TLS in development mode between a client and WebLogic Server, configure the demo certificates in the JVM for both the client and the server as follows:
Note:
The passphrase for the Demo Trust keystore is DemoTrustKeyStorePassPhrase
. The passphrase for the Demo Identity keystore is stored in the DOMAIN_HOME/security/DemoCerts.props
file.
Obtaining and Storing Certificates for Production Environments
To obtain a digital certificate for use in a production environment, you must generate a Certificate Signing Request (CSR) and issue it to a reputable CA. The CA returns a digital certificate that is signed with the CA's private key and that is used for establishing identity. The CA also returns the CA's signed public certificate, which is used for trust. You then import the digital certificate for identity into your identity keystore, and the CA's public certificate into the trust keystore.
The following sections explain these steps in detail:
Generating a Certificate Signing Request
Oracle strongly recommends that all certificates used in a production environment are signed by a reputable Certificate Authority (CA). To obtain a CA-signed certificate, you must issue an individual Certificate Signing Request (CSR) for each certificate that you plan to use in that production environment.
To generate a CSR, complete the following steps:
The CSR file is encoded in PKCS#10 format and may look similar to the following:
-----BEGIN NEW CERTIFICATE REQUEST----- MIIBtzCCASACAQAwdzELMAkGA1UEBhMCR0IxEjAQBgNVBAgTCUJlcmtzaGlyZTEQMA 4GA1UEBxMHUmVhZGluZzEPMA0GA1UEChMGT3JhY2xlMRAwDgYDVQQLEwdTdXBwb3J0 MR8wHQYDVQQDExZtYXJzaGFsbC51ay5vcmFjbGUuY29tMIGfMA0GCSqGSIb3DQEBA QUAA4GNADCBiQKBgQCEopgMZp1lI6jWXxb1rM1kWIc1l8bhiV/0UTcsdKzeaSHxbO SLO3Ed9kxNWAZgXaR9f5FBlwkaRJ+IR163e64v3SplHenxHfVRaHYWPZx4KlJz/6p Yd1fAlF0PdQm1DNoFtKmCHVk/cRuvGRpsp38l7K2mYlyQ+GxH38llS7g3owIDAQAB oAAwDQYJKoZIhvcNAQEFBQADgYEAD/sG1+rSI76OjihHg3WezT+VIbSRJxyly9nbx 4uwXbDHh8DGgQLAXV51C9ioaMrm+dM0eygVDDMESXFxvJiYipS/pphgYt1xDBgnEH GcNiX3BnTaLNtzYlc5eAMsmbDlpk/qOxvQiH3bKN+UKYQlBXJZWPL6FusXu2LMTrk zsY= -----END NEW CERTIFICATE REQUEST-----
Note:
The Certificate Request Generator servlet is deprecated. Use the keytool utility instead.
Importing Certificates into the Trust and Identity Keystores
After you submit a CSR to a CA, the CA returns the following:
-
The CA's signed public certificate. (This certificate may be an intermediate certificate that is signed by a high-level CA, or it may be a self-signed (root) certificate.)
You place this certificate into the keystore designated as the trust keystore.
-
A CA-signed digital certificate for WebLogic Server. This is often referred to simply as the server certificate.
You place the server certificate into the keystore designated as the identity keystore.
-
Optionally, one or more intermediate certificates that establish the chain of trust to the root CA certificate.
To import the CA-signed certificates into the trust and identity keystores, complete the following steps:
Configuring Keystores with WebLogic Server
All private key entries in a keystore are accessed by WebLogic Server through the use of aliases, which you specify when loading private keys into the keystore. Although WebLogic Server does not use the alias to access trusted CA certificates, the keystore does require an alias when loading a trusted CA certificate into the keystore. After you have created the identity and trust keystores, you need to configure WebLogic Server to use them.
Aliases are case-insensitive: the aliases Hugo and hugo would refer to the same keystore entry. When you configure SSL, aliases for private keys are specified in the Server Private Key Alias field on the Environment: Servers: server page, under the Security: SSL tab in the WebLogic Remote Console.
See:
-
Configure Keystores Using the WebLogic Remote Console in Oracle WebLogic Remote Console Online Help
Configuring a Keystore Using WLST
This section provides an example of using WLST to configure the identity and trust keystores for WebLogic Server. Example 28-1 does the following:
-
Connects to the Managed Server instance for which the identity and trust keystores are being configured.
-
Navigates to the MBean that corresponds to the specific server instance for which the identity and trust keystores are to be configured,
myserver
. -
Sets the configuration rule that WebLogic Server uses to locate the identity and trust keystores,
CustomIdentityAndCustomTrust
. -
Sets the name and location of the identity keystore file,
Identity.jks
. -
Sets the passphrase for the identity keystore.
-
Sets the identity keystore type to
JKS
. -
Sets the name and location of the trust keystore file,
Trust.jks
. -
Sets the passphrase for the trust keystore.
-
Sets the trust keystore type to
JKS
. -
Saves and activates the new keystore configuration, then disconnects from the Managed Server instance.
Note:
This example sets the keystore and truststore type to JKS. You can also configure PKCS12 keystores. To do so, be sure to set thesetCustomIdentityKeyStoreType()
and setCustomTrustKeyStoreType()
properties to PKCS12.
Example 28-1 Configuring Custom Identity and Trust Keystores
connect('','','t3://host:port') Please enter your username : Please enter your password : ... edit() startEdit() cd ('Servers/myserver') cmo.setKeyStores('CustomIdentityAndCustomTrust') cmo.setCustomIdentityKeyStoreFileName('/path/keystores/Identity.jks') cmo.setCustomIdentityKeyStorePassPhrase('passphrase') cmo.setCustomIdentityKeyStoreType('JKS') cmo.setCustomTrustKeyStoreFileName('/path/keystores/Trust.jks') cmo.setCustomTrustKeyStorePassPhrase('passphrase') cmo.setCustomTrustKeyStoreType('JKS') save() activate() disconnect()
Viewing Keystore Contents
Use the keytool
command to view the contents of a keystore.
Use the following keytool
command syntax, where keystore
represents the name of the keystore you created:
keytool -list -v -keystore keystore
When you enter the preceding command, you are prompted for the keystore password. For example, the following command lists the contents of keystore.jks
:
prompt> keytool -list -v -keystore keystore.jks Enter keystore password: Alias name: rootcacert Creation date: Sep 13, 2010 Entry type: trustedCertEntry Owner: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB Issuer: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB Serial number: c47f4774c2ef014c Valid from: Fri Jan 09 10:27:18 GMT 2009 until: Mon May 26 11:27:18 BST 2036 Certificate fingerprints: MD5: E9:24:39:56:DE:34:44:DB:46:93:45:93:8E:82:66:AC SHA1: 17:39:92:C0:43:9B:28:F3:C2:54:55:9B:5E:97:CA:EE:71:5D:9C:26 Signature algorithm name: SHA1withRSA Version: 3 Extensions: #1: ObjectId: 2.5.29.14 Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: 67 57 BA 54 BB 9B C0 38 9A 71 AA 28 82 23 4B 08 gW.T...8.q.(.#K. 0010: 72 B9 FC C1 r... ] ] #2: ObjectId: 2.5.29.19 Criticality=false BasicConstraints:[ CA:true PathLen:2147483647 ] #3: ObjectId: 2.5.29.35 Criticality=false [CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB] SerialNumber: [ c47f4774 c2ef014c] ] ******************************************* ******************************************* Alias name: server_cert Creation date: Sep 13, 2010 Entry type: PrivateKeyEntry Certificate chain length: 2 Certificate[1]: Owner: CN=server.avitek.com, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB Issuer: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB Serial number: e Valid from: Mon Sep 13 14:02:00 BST 2010 until: Sat Sep 22 14:02:00 BST 2012 Certificate fingerprints: MD5: CB:B8:07:32:22:B5:76:78:44:BB:94:D2:CE:EF:A3:CA SHA1: 1E:3E:C6:BC:17:EB:43:50:19:01:0B:11:50:D8:23:60:21:B2:57:3E Signature algorithm name: MD5withRSA Version: 1 Certificate[2]: Owner: CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB Issuer: CN=SSL Training CA, OU=Support, O=Avitek, L=Readin g, ST=Berkshire, C=GB Serial number: c47f4774c2ef014c Valid from: Fri Jan 09 10:27:18 GMT 2009 until: Mon May 26 11:27:18 BST 2036 Certificate fingerprints: MD5: E9:24:39:56:DE:34:44:DB:46:93:45:93:8E:82:66:AC SHA1: 17:39:92:C0:43:9B:28:F3:C2:54:55:9B:5E:97:CA:EE:71:5D:9C:26 Signature algorithm name: SHA1withRSA Version: 3 Extensions: #1: ObjectId: 2.5.29.14 Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: 67 57 BA 54 BB 9B C0 38 9A 71 AA 28 82 23 4B 08 gW.T...8.q.(.#K. 0010: 72 B9 FC C1 r... ] ] #2: ObjectId: 2.5.29.19 Criticality=false BasicConstraints:[ CA:true PathLen:2147483647 ] #3: ObjectId: 2.5.29.35 Criticality=false AuthorityKeyIdentifier [ KeyIdentifier [ 0000: 67 57 BA 54 BB 9B C0 38 9A 71 AA 28 82 23 4B 08 gW.T...8.q.(.#K. 0010: 72 B9 FC C1 r... ] [CN=SSL Training CA, OU=Support, O=Avitek, L=Reading, ST=Berkshire, C=GB] SerialNumber: [ c47f4774 c2ef014c] ] ******************************************* *******************************************
Setting Certificate Expiry Notifications
You can set reminders to notify you when your SSL certificates are about to expire. Reminders appear in the Security Warnings Report in WebLogic Remote Console.
Replacing Expiring Certificates
You must replace an expiring certificate before it actually expires to avoid or reduce application downtime.
You can set a notification to remind you prior to its expiration. See Setting Certificate Expiry Notifications.
To replace a certificate, complete the following steps:
Creating a Keystore: An Example
Learn how to use the keytool utility for creating a keystore and storing keys and certificates in it.
Note that this section shows only how to create one keystore. In a production environment, Oracle recommends that you have two keystores: one for trust, and another for identity, as explained in Using Separate Keystores for Identity and Trust in Custom Keystore Configurations. For complete details about each of the keytool command options shown in this section, see the help for the keytool utility at the following locations:
-
Java SE 17 - keytool in Java Development Kit Version 17 Tool Specifications
-
Java SE 21 - keytool in Java Development Kit Version 21 Tool Specifications
To create a keystore and populate it with private keys and certificates, complete the following steps:
Supported Formats for Identity and Trust Certificates
The PEM (Privacy Enhanced Mail) format is the preferred format for private keys, digital certificates, and trusted certificate authority (CA) certificates.
A .pem
format file begins with this line:
----BEGIN CERTIFICATE----
and ends with this line:
----END CERTIFICATE----
A .pem
format file supports multiple digital certificates (for example, a certificate chain can be included). The order of certificates within the file is important. The server's digital certificate should be the first digital certificate in the file, followed by the issuer certificate, and so on. Each certificate in the chain is followed by its issuer certificate. If the last certificate in the chain is the self-signed (self-issued) root certificate of the chain, the chain is considered complete. Note that the chain does not have to be complete.
When using the deprecated file-based private keys, digital certificates, and trusted CA certificates, WebLogic Server can use digital certificates in either PEM or distinguished encoding rules (DER) format.
A .der
format file contains binary data for a single certificate. Thus, a .der
file can be used only for a single certificate, while a .pem
file can be used for multiple certificates.
Microsoft is often used as a CA. Microsoft issues trusted CA certificates in p7b format, which must be converted to PEM before they can be used with WebLogic Server. See Converting a Microsoft p7b Format to PEM Format.
Private key files (meaning private keys not stored in a keystore) must be in PKCS#5/PKCS#8 PEM format.
You can still use private keys and digital certificates used with other versions of WebLogic Server with this version of WebLogic Server. Convert the private key and digital certificate from distinguished encoding rules (DER) format to privacy-enhanced mail (PEM) format. See the description of the der2pem utility in "Using the WebLogic Server Java Utilities" in Command Reference for Oracle WebLogic Server.
After converting the files, ensure the digital certificate file has the -----BEGIN CERTIFICATE-----
header and the -----END CERTIFICATE-----
footer. Otherwise, the digital certificate will not work.
Note:
OpenSSL can add a header to the PEM certificate it generates. In order to use such certificates with WebLogic Server, everything in front of "-----BEGIN CERTIFICATE-----
" should be removed from the certificate, which you can do with a text editor.
Obtaining a Digital Certificate for a Web Browser
The digital certification you receive for a web browser contains public information, including your name and public key, and additional information you would like authenticated by a third party, such as your E-mail address. You are required to present the digital certificate when authentication is requested.
Low-security browser certificates are easy to acquire and can be done from within the Web browser, usually by selecting the Security menu item in Options or Preferences. Go to the Personal Certificates item and ask to obtain a new digital certificate. You will be asked for some information about yourself.
As part of the process of acquiring a digital certificate, the Web browser generates a public-private key pair. The private key should remain secret. It is stored on the local file system and should never leave the Web browser's machine, to ensure that the process of acquiring a digital certificate is itself safe. With some browsers, the private key can be encrypted using a password, which is not stored. When you encrypt your private key, you will be asked by the Web browser for your password at least once per session.
Note:
Digital certificates obtained from Web browsers do not work with other types of Web browsers or on different versions of the same Web browser.