28 Configuring Keystores

Learn how to configure Oracle WebLogic Server to use Java keystores for identity and trust.

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, and JAVA_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 the java.security file to JKS. If you prefer to use PKCS12, you can convert your JKS keystores using the -importkeystore option of the keytool utility. See Converting the Default JKS Keystore for FIPS Compliance or the keytool 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 17 supplies the JDK cacerts in JKS format.
  • JDK 21 supplies the JDK cacerts in PKCS12 format.
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)

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 provisioned-trust keystore.

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, domain-trust and provisioned-trust. These certificates are used to boostrap Managed Servers, and by the Node Manager.

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

  • Trust in the global trust anchors provided by the JRE's cacerts file is configured differently and they should not be added to this keystore.

  • This keystore is only available on the Administration Server.
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:

  1. Create the keystore to hold the server identity certificate. See Creating a Keystore.
  2. 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.
  3. Import the identity and trust certificates returned by the CA. See Importing Certificates into the Trust and Identity Keystores.
  4. 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:

  1. 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 using DOMAIN_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.

  2. 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 JDK cacerts 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.

  1. Change to the DOMAIN_HOME/bin directory of your WebLogic domain root directory.
  2. Run the setDomainEnv script, which sets the domain-wide environment for starting and running WebLogic Server instances.
  3. Run the DemoCertGen utility. Include the -domain argument and set its value to the domain home directory.
    java utils.DemoCertGen -domain <DOMAIN_HOME>

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.

  1. On every machine with a WebLogic Server instance, make sure you back up the following files, located under DOMAIN_HOME/security:
    • democacert.der
    • democakey.der
    • democert.der
    • demokey.der
    • DemoCerts.props
    • DemoIdentity.p12
    • DemoTrust.p12
  2. On the machine where the Administration Server is located, go to the DOMAIN_HOME/bin directory of your WebLogic domain root directory.
  3. Run the setDomainEnv script, which sets the domain-wide environment for starting and running WebLogic Server instances.
  4. Run the DemoCertGen utility. Include the -domain argument and set its value to the domain home directory. Typically, you will also want to include -genIDOnly so that only the demo certificates are regenerated and not the demo CA certificate.

    For example:

    java utils.DemoCertGen -domain DOMAIN_HOME -genIDOnly
    1. Optional: If you want to regenerate both the demo certificates and the demo CA certificate, omit the -genIDOnly argument.

      For example:

      java utils.DemoCertGen -domain DOMAIN_HOME
  5. Optional: If you have Managed Servers on other machines, then perform the following steps on each of the machines:
    1. On the Administration Server machine, copy the demo certificate files, democacert.der and democakey.der, over to DOMAIN_HOME/security on the Managed Server machine, replacing the existing files.
    2. Run the DemoCertGen utility with the -genIDOnly option.

      For example:

      java utils.DemoCertGen -domain DOMAIN_HOME -genIDOnly

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 the java.security file. As of JDK 9, the default is pkcs12. You can change the default by specifying the storetype 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:

  1. Create a directory to hold the keystore. For example: ORACLE_HOME/keystores.

  2. Change to the bin subdirectory of your WebLogic domain root directory. For example: 

    prompt> cd DOMAIN_HOME/bin

  3. Run the setDomainEnv script, which sets the domain-wide environment for starting and running WebLogic Server instances.

  4. 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 or pkcs12, represented by storetype.

When you enter the keytool command as described in the preceding steps, keytool automatically prompts you for the following:

  1. The keystore password
  2. 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:

  1. Change to the bin subdirectory of your WebLogic domain root directory.

  2. Run the setDomainEnv script, which sets the domain-wide environment for starting and running WebLogic Server instances.

  3. Change to the directory in which you want to create the keystore.

  4. Generate the certificate and private key.

    For example, using CertGen:

    1. Enter the following command to generate the certificate file named testcert and the private key file named testkey: 

      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

    2. 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 and CertGenCAKey.der files in the current directory, or in the WL_HOME/server/lib directory, as specified in the weblogic.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.

  5. Concatenate the certificate and the Certificate Authority (CA) certificate. For example:

    prompt> cat testcert.pem CertGenCA.pem >> newcerts.pem

  6. 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 file testkey.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 default storetype 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.

This section includes the following topics:

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:

  1. Open a command window and change to the bin subdirectory of your WebLogic domain root directory.
  2. Run the setDomainEnv script. This script sets the domain-wide environment for starting and running WebLogic Server instances.
  3. Optionally, change to the directory in which you want to create the certificate and private key.
  4. Generate the certificate and private key using the following command:
    java utils.CertGen -keyfilepass keyfilepass -certfile cert-name -keyfile keyfile-name

    In the preceding command:

    • keyfilepass represents the password for the private key file.

    • cert-name represents the name of the certificate.

    • keyfile-name represents the name of the private key file.

    For example, the following command generates the certificate file named testcert and the private key file named testkey: 

    prompt> java utils.CertGen -keyfilepass mykeyfilepass -certfile testcert -keyfile testkey
Generating a certificate with common name return and key strength 2048
issued by CA with certificate from CertGenCA.der file and key from CertGenCAKey.der file
CertGen Usage Notes

Note the following about using CertGen:

  • By default, the CertGen utility looks for the CertGenCA.der and CertGenCAKey.der files in the current directory, or in the WL_HOME/server/lib directory, as specified in the weblogic.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 JDK InetAddress.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:

    1. 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 is avitek01, the listen address for the server instance should be specified simply as avitek01.

    2. 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:

                     

                     
    
                        
  1. Ensure the trusted CA certificates are in PEM format. 
    
                              
                           
    
                        
    2. 
                        
  2. Create the trust keystore to hold the trusted CA certificate, as explained in Creating a Keystore.
    3. 
                        
  3. Store the trusted CA certificate in the trust keystore. See Importing Certificates into the Trust and Identity Keystores.
    4. 
                        
  4. Configure WebLogic Server to use the trust keystore. See Configuring Keystores with WebLogic Server.
    5. 
                     

                  

               
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:

                     

                     
    
                        
  1. In Windows Explorer, select the file (filename.p7b) you want to convert. Double-click on the file to display a Certificates window.
    2. 
                        
  2. In the left pane of the Certificates window, expand the file.
    3. 
                        
  3. Expand the Certificates folder to display a list of certificates.
    4. 
                        
  4. Select a certificate to convert to PEM format. Right-click on the certificate, then choose All Tasks > Export to display the Certificate Export Wizard.
    5. 
                        
  5. In the wizard, click Next.
    6. 
                        
  6. Select the Base-64 encoded X.509 (.CER) option. Then click Next. (Base-64 encoded is the PEM format.)
    7. 
                        
  7. In the File name field, enter a name for the converted digital certificate; then click Next.
    
                              
    
                                 
    Note:
    
                                 
    The wizard appends a .cer extension to the output file. The .cer extension is a generic extension which is appended to both base-64 encoded certificates and DER certificates. You can change the extension to .pem after you exit the wizard.
                                 
    
                              
    
                           
    
                        
    8. 
                        
  8. Verify that the settings are correct. If the settings are correct, click Finish; if they are not correct, click Back and make any necessary modifications.
    
                              
    
                                 
    Note:
    
                                 
    For p7b certificate files that contain certificate chains, you need to concatenate the issuer PEM digital certificates to the certificate file. The resulting certificate file can be used by WebLogic Server.
    
                              
    
                           
    
                        
    9. 
                     

                  

               
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:

                     

                     
    
                        
  1. Import DOMAIN_HOME/security/democacert.der into the cacerts keystore in the jre/lib/security directory of the client's JVM.
    For instructions on using the importcert command in keytool, see the keytool utility section in 
                                 JDK Tool Specifications
                                 .
                           
    
                        
    2. 
                        
  2. Import DOMAIN_HOME/security/democacert.der into the cacerts keystore in the jre/lib/security directory of the WebLogic Server's JVM.
    3. 
                        
  3. Restart both the client and WebLogic Server.
    4. 
                     

                     

                        

                           
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:

                     

                     
    
                        
  1. Create a keystore to hold the identity of the WebLogic Server instance, if you have not already done so, as explained in Creating a Keystore.
    2. 
                        
  2. Open a command window, change to the bin subdirectory of your WebLogic domain, and run the setDomainEnv script. For example, on Windows systems:
    prompt> cd DOMAIN_HOME/bin
prompt> setDomainEnv

    In the preceding path, DOMAIN_HOME represents the WebLogic domain root directory.
                              
    
                           
    
                        
    3. 
                        
  3. Change to the directory that contains your keystore and create a CSR using the keytool command with the following syntax:
    keytool -certreq -v -alias alias -file certreq_file -keystore keystore

    In the preceding command syntax:
    
                              
      
                                 
    • 
                                    
      alias represents the private key alias specified when you created the keystore
                                    
      
                                 
      • 
                                 
    • 
                                    
      certreq_file represents the name of the file that contains the CSR.
                                    
      
                                 
      • 
                                 
    • 
                                    
      keystore represents the keystore.
                                    
      
                                 
      • 
                              
    
                              
    Note that when you enter the preceding command, you are prompted for the passwords for the keystore and the private key, which you specified when you created the keystore.
    
                           
    
                        
    4. 
                        
  4. Submit the CSR file to a certificate authority (CA) of your choice.
    5. 
                     

                     

                        
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:

                     

                     
    
                        
  1. Open a command window, change to the bin subdirectory of your WebLogic domain, and run the setDomainEnv script. For example, on Windows systems:
    prompt> cd DOMAIN_HOME/bin
prompt> setDomainEnv

    In the preceding path, DOMAIN_HOME represents the WebLogic domain root directory.
                              
    
                           
    
                        
    2. 
                        
  2. Change to the directory to hold the trust keystore and enter the following keytool command. This command creates the trust keystore, if it does not already exist, and imports the CA-signed certificate:
    keytool -importcert -file CAcert -alias CAcert-alias -keystore keystore

    In the preceding command:
    
                              
      
                                 
    • 
                                    
      CAcert represents the name of the CA's signed public certificate.
                                    
      
                                 
      • 
                                 
    • 
                                    
      CAcert-alias represents the alias of the CA's signed public certificate.
                                    
      
                                 
      • 
                                 
    • 
                                    
      keystore represents the keystore file name.
                                    
      
                                 
      • 
                              
    
                              
    If you currently have additional trusted CA-signed public certificates or intermediate certificates, or receive them in the future, you can add them to the preceding trust keystore using the same keytool command. For example:
    keytool -importcert -file CAcert2 -alias CAcert2-alias -keystore keystore

    If you are importing certificates that are part of a sequentially-ordered certificate path, you must import those certificates into the trust keystore in the order in which they exist in that path. If you import them in the wrong sequence, the SSL handshake when making a connection may fail. For example, consider the following certificate path:
    
                              
      
                                 
    • 
                                    
      Root CA certificate, rootCA
      
                                 
      • 
                                 
    • 
                                    
      Intermediate certificate ICA1, which is signed by rootCA
      
                                 
      • 
                                 
    • 
                                    
      Intermediate certificate ICA2, which is signed by ICA1
      
                                 
      • 
                              
    
                              
    In the preceding certificate path, you would import rootCA into the trust keystore first, followed by ICA1, then finally by ICA2. If these certificates are imported into the keystore in the wrong sequence, 
                              
    
                              
    
                                 
    Note:
    
                                 
    Note the following:
    
                                 
      
                                    
    • 
                                       
      A root CA may impose a limit on the number of intermediate certificates that may exist in a certificate path based on a root certificate issued by that CA. See Certificate Authorities in Understanding Security for Oracle WebLogic Server.
                                       
      
                                    
      • 
                                    
    • 
                                       
      If your trust keystore does not contain the certificate of the intermediate CA that signed your server certificate, but that intermediate CA is trusted by the target of an SSL connection that you are making, the SSL connection may succeed by means of transitive trust. 
      
                                    
      • 
                                 
    
                              
    
                           
    
                        
    3. 
                        
  3. Make a backup copy of the trust keystore.
    4. 
                        
  4. Change to the directory that contains the identity keystore for WebLogic Server.
    5. 
                        
  5. Import the CA-signed server certificate into your keystore using the following keytool command:
    keytool -importcert -v -alias alias -file servercert_file -keystore keystore

    In the preceding syntax:
    
                              
      
                                 
    • 
                                    
      alias represents the alias of the server certificate, which must be the same as the private key alias assigned in Step 4.) 
                                    
      
                                 
      • 
                                 
    • 
                                    
      servercert_file represents the name of the file that contains the CA-signed server certificate.
                                    
      
                                 
      • 
                                 
    • 
                                    
      keystore represents the name of your keystore.
                                    
      
                                 
      • 
                                 
    • 
                                    
      Using the -v option increases the amount of information displayed in the command output.
                                    
      
                                 
      • 
                              
    
                              
    For example, the following command imports the server certificate server.pem into the keystore, using the alias (server_cert) assigned in Step 4:
                              
    prompt> keytool -importcert -v -alias server_cert -file server.pem -keystore keystore.jks
Enter keystore password:
Certificate reply was installed in keystore[Storing keystore.jks
]
    
                        
    6. 
                        
  6. Make a backup copy of the identity keystore.
    7. 
                     

                  

               

            
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:

                  
               
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:
                     

                     
    
                        
  1. 
                           
    Connects to the Managed Server instance for which the identity and trust keystores are being configured.
    
                        
    2. 
                        
  2. 
                           
    Navigates to the MBean that corresponds to the specific server instance for which the identity and trust keystores are to be configured, myserver.
                           
    
                        
    3. 
                        
  3. 
                           
    Sets the configuration rule that WebLogic Server uses to locate the identity and trust keystores, CustomIdentityAndCustomTrust. 
                           
    
                        
    4. 
                        
  4. 
                           
    Sets the name and location of the identity keystore file, Identity.jks.
                           
    
                        
    5. 
                        
  5. 
                           
    Sets the passphrase for the identity keystore.
    
                        
    6. 
                        
  6. 
                           
    Sets the identity keystore type to JKS.
                           
    
                        
    7. 
                        
  7. 
                           
    Sets the name and location of the trust keystore file, Trust.jks.
                           
    
                        
    8. 
                        
  8. 
                           
    Sets the passphrase for the trust keystore.
    
                        
    9. 
                        
  9. 
                           
    Sets the trust keystore type to JKS.
                           
    
                        
    10. 
                        
  10. 
                           
    Saves and activates the new keystore configuration, then disconnects from the Managed Server instance.
    
                        
    11. 
                     

                     

                        
Note:
This example sets the keystore and truststore type to JKS. You can also configure PKCS12 keystores. To do so, be sure to set the setCustomIdentityKeyStoreType() 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.
                  

                  
To set a certificate expiry notification:

                  
    
                     
  1. In the WebLogic Remote Console Edit Tree, go to Environment, then Domain.
    2. 
                     
  2. On the Security tab, select the Warnings subtab.
    3. 
                     
  3. Turn on at least one of the following options: Check Identity Certificates or Check Trust Certificates.
    4. 
                     
  4. In the Check Certificates Expiration Days field, enter a number (in days) to specify how far in advance of the certificate's expiration should the warnings begin to appear. 
    By default, WebLogic Server checks that no certificates are expiring within the next 30 days.
    
                     
    5. 
                     
  5. In the Check Certificates Interval Days field, enter a number (in days) to specify how often WebLogic Server should check if the certificates are set to expire. 
    By default, WebLogic Server checks daily if certificates are about to expire.
    
                     
    6. 
                     
  6. Click Save.
    7. 
                  

               

            
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:

                  

                  
    
                     
  1. Open a command window, change to the DOMAIN_HOME/bin directory, and run the setDomainEnv script.
    2. 
                     
  2. Change to the directory that contains the identity keystore that stores the certificate needing to be replaced.
    3. 
                     
  3. Generate a CSR, as explained in Generating a Certificate Signing Request, using the same private key alias specified when you created the keystore for which the current expiring certificate was issued.
    4. 
                     
  4. Submit the CSR to the CA that issued the original certificate. The validity date of the new certificate should be earlier than the expiration date of the current certificate. This overlap is recommended to reduce downtime.
    
                           
    
                              
    Note:
    
                              
    Steps 3 and 4 are not required if the CA already maintains the certificate request in a repository. In that case, simply ask the CA to issue a new certificate.
    
                           
    
                        
    
                     
    5. 
                     
  5. Import the newly issued certificate into the identity keystore using the alias of the private key.
    6. 
                     
  6. If the new certificate is issued by a CA other than the one that issued the original certificate, you may also need to import the new CA's trusted certificate before importing the newly issued identity certificate.
    7. 
                  

               

            
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:

                  

                  
    
                     
  1. Create a directory to hold the keystore; for example: ORACLE_HOME/keystores.
    2. 
                     
  2. Run the following script, which sets the domain-wide environment for starting and running WebLogic Server instances:
    DOMAIN_HOME/bin/setDomainEnv

    In the preceding path, DOMAIN_HOME represents the WebLogic domain root directory.
                           
    
                        
    
                     
    3. 
                     
  3. Change to the directory to hold the keystore, which you created in Step 1.
    4. 
                     
  4. Create the keystore using the following keytool command syntax. This command also creates a key pair (a public key and associated private key) and an alias for the private key.
    keytool -genkeypair -alias alias -keyalg RSA -keysize 2048 -dname dn -keystore keystore
-storetype storetype
    In the preceding command syntax:
    
                           
      
                              
    • 
                                 
      alias represents the private key alias.
                                 
      
                              
      • 
                              
    • 
                                 
      dn represents the X.500 Distinguished Name associated with the private key alias.
                                 
      
                              
      • 
                              
    • 
                                 
      keystore represents the name of the keystore being created.
                                 
      
                              
      • 
                              
    • 
                                 
      storetype represents the keystore type, jks or pkcs12.
                                 
      
                              
      • 
                           
    
                           
    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
    Note the following in the preceding example:
    
                           
      
                              
    • 
                                 
      server.avitek.com represents the WebLogic Server host and DNS domain name.
                                 
      
                              
      • 
                              
    • 
                                 
      Although the keytool command includes the -storepass and -keypass options for specifying the keystore and private key passwords, respectively, Oracle recommends that you avoid using these command-line options. When you enter a keytool command that requires one or more passwords, but you omit the command-line options for passing them, you are subsequently prompted to enter them. However, unlike passwords passed in command-line options, passwords entered in response to a prompt are not displayed in the command window and are not captured in any log.
                                 
      
                              
      • 
                              
    • 
                                 
      Make note of the private key alias and passwords you specify, and be sure to record passwords only in a safe location.
      
                              
      • 
                           
    
                        
    
                     
    5. 
                     
  5. Make a backup copy of the keystore created in Step 4.
    6. 
                     
  6. Create a Certificate Signing Request (CSR) using the following keytool command syntax:
    keytool -certreq -v -alias alias -file certreq_file -keystore keystore

    In the preceding command syntax:
    
                           
      
                              
    • 
                                 
      alias represents the private key alias specified in Step 4.
                                 
      
                              
      • 
                              
    • 
                                 
      certreq_file represents the name of the file that contains the CSR.
                                 
      
                              
      • 
                              
    • 
                                 
      keystore represents the keystore created in Step 4.
                                 
      
                              
      • 
                           
    
                           
    Note that when you create a CSR using the preceding command, you are prompted to enter the passwords for the keystore and the private key.
    
                           
    For example, the following command creates a CSR in the file server.csr:
                           
    prompt> keytool -certreq -v -alias server_cert -file server.csr -keystore keystore.jks

    
                     
    7. 
                     
  7. Submit the CSR file to a certificate authority (CA) of your choice. The CA returns:
    
                           
      
                              
    • 
                                 
      A digital certificate for WebLogic Server. This certificate is signed by the CA and is often referred to simply as the server certificate.
      
                              
      • 
                              
    • 
                                 
      The public certificate of the CA that signed your server certificate.
      
                              
      • 
                              
    • 
                                 
      Optionally, one or more intermediate CA certificates. For example, if the CA that signed your certificate is an intermediate CA, you might also receive the public certificate of the intermediate CA that signed your CA's certificate. (If your CA's certificate was signed by a root CA, you might also receive the root certificate.)
      
                              
      • 
                           
    
                        
    
                     
    8. 
                     
  8. In the directory you created for your keystore, save the server certificate, and also the CA certificates, in individual files. For example, the server certificate can be saved as server.pem, and the CA certificate as rootCA.pem.
    
                           
    If you have an intermediate CA who also returns other intermediate certificates, save them also in your keystore directory using names such as intermediateCA2.pem, intermediateCA3.pem, and so on, to properly establish the certificate path in a way that indicates the correct sequence of that path.
                           
    
                        
    
                     
    9. 
                     
  9. Import the CA certificate, including any additional intermediate certificates and the root certificate if available, into your keystore using the following keytool command syntax:
    keytool -importcert -v -noprompt -trustcacerts -alias alias -file rootca_file -keystore keystore

    In the preceding syntax:
    
                           
      
                              
    • 
                                 
      alias represents the alias of the root CA certificate.
                                 
      
                              
      • 
                              
    • 
                                 
      rootca_file represents the name of the file that contains the root CA certificate.
                                 
      
                              
      • 
                              
    • 
                                 
      keystore represents the name of your keystore.
                                 
      
                              
      • 
                           
    
                           
    For example, the following command imports the root CA certificate in file rootCA.pem into the keystore, assigning it the alias rootcacert:
                           
    prompt> keytool -importcert -v -noprompt -trustcacerts -alias rootcacert -file rootCA.pem -keystore keystore.jks
Enter keystore password:
Certificate was added to keystore
Storing keystore.jks

    
                              
    Note:
    
                              
    If your CA returns a certificate chain, make sure you import the certificates in the proper sequence, as explained in Importing Certificates into the Trust and Identity Keystores.
                              
    
                           
    
                        
    
                     
    10. 
                     
  10. Import the server certificate into your keystore using the following keytool command syntax:
    keytool -importcert -v -alias alias -file servercert_file -keystore keystore

    In the preceding syntax:
    
                           
      
                              
    • 
                                 
      alias represents the alias of the server certificate, which must be the same as the private key alias assigned in Step 4.) 
                                 
      
                              
      • 
                              
    • 
                                 
      servercert_file represents the name of the file that contains the server certificate.
                                 
      
                              
      • 
                              
    • 
                                 
      keystore represents the name of your keystore.
                                 
      
                              
      • 
                           
    
                           
    For example, the following command imports the server certificate server.pem into the keystore, using the alias (server_cert) assigned in Step 4:
                           
    prompt> keytool -importcert -v -alias server_cert -file server.pem -keystore keystore.jks
Enter keystore password:
Certificate reply was installed in keystore[Storing keystore.jks
]
    
                     
    11. 
                     
  11. To view the contents of the keystore, use the following keytool command syntax, where keystore represents the name of your keystore:
    keytool -list -v -keystore keystore

    
                     
    12. 
                  

               

            
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.