41 Configuring an Identity Keystore Specific to a Network Channel

This chapter explains how to configure a network channel to have its own custom identity keystore, and other SSL attributes, that are separate from and that override the default keystore and SSL configuration settings for the Managed Server instance or the domain in WebLogic Server 12.1.3. This enables you to configure a WebLogic Server instance to use one identity and SSL configuration on one network channel, and another identity and SSL configuration on other channels.

This chapter includes the following sections:

• About Network Channels

• Channel-Specific SSL Configuration Attributes

• Steps to Configure a Channel-Specific Identity Keystore

• Using WLST to Configure a Channel-Specific Identity Keystore

About Network Channels

As explained in "Understanding Network Channels" in Administering Server Environments for Oracle WebLogic Server, a network channel in a WebLogic Server instance is a combination of the following four attributes:

• Communication protocol, which can be t3, t3s, http, or https

• Listen address

• Listen port

• Channel name

By default, when you configure a network channel, the channel uses the SSL configuration that is set for the server instance. This means that the channel uses the same identity and trust that is established for the server. The server might use a custom identity that is specific to that server, or it might be a single domain-wide identity, depending on how the server instance and domain are configured.

However, rather than using one identity for all network communication in which a Managed Server instance participates, you might have a need for the server to switch to a different identity when communicating with a particular client. For example, you might need to use one identity for the server when communicating with one particular business group, and a different identity for the server when communicating with other Managed Server instances in the domain. By customizing a network channel to use a custom identity keystore that is separate from either the identity keystore configured for the server instance or the one configured for the domain, you can assert one identity on one network channel, and another identity on a different channel.

Channel-Specific SSL Configuration Attributes

The NetworkAccessPointMBean contains the attributes that you can set to create a channel-specific SSL configuration. In addition to enabling a network channel to use a custom identity keystore, these attributes also allow you to customize other SSL settings, such as the use of a custom host name verifier, the cipher suites to be used in SSL communications, and certificate validation rules.

Table 41-1 lists and describes the SSL attributes that can be configured on the NetworkAccessPointMBean for a specific network channel.

Note:

For ease of reference in Table 41-1, the following attributes on the NetworkAccessPointMBean are referred to collectively as the CustomIdentityKeyStore* attributes:

• CustomIdentityKeyStoreFileName

• CustomIdentityKeyStorePassPhrase

• CustomIdentityKeyStorePassPhraseEncrypted

• CustomIdentityKeyStoreType

Table 41-1 NetworkAccessPointMBean Attributes for Customizing a Channel's SSL Configuration

Attribute	Description
ChannelIdentityCustomized	Specifies whether the channel's custom identity should be used. This setting has an effect only if the network channel uses a custom keystore. By default the channel's identity is inherited from the server's identity. The CustomIdentityKeyStore* attributes have the following validation rules related to the ChannelIdentityCustomized attribute to ensure that the network channel alias relates to the channel keystore and does not default to an alias in the server keystore: If any CustomIdentityKeyStore* attributes are set, then all CustomIdentityKeyStore* attributes must be set. The ChannelIdentityCustomized attribute must be set to true. The CustomPrivateKeyAlias attribute must be set. Note that if the CustomIdentityKeyStore* attributes are not set, the CustomPrivateKeyAlias attribute may be set to refer to the server keystore.
CustomIdentityKeyStoreFileName	Specifies the custom identity keystore to assign to the channel. If a value for this attribute is not set, the value of the ServerMBean.CustomIdentityKeyStoreFileName attribute is used by default. This attribute is used only if the ServerMBean.KeyStores attribute is set to one of the following values: CUSTOM_IDENTITY_AND_JAVA_STANDARD_TRUST CUSTOM_IDENTITY_AND_CUSTOM_TRUST CUSTOM_IDENTITY_AND_COMMAND_LINE_TRUST If you are using a JKS keystore, specify this value as an absolute path, or as a relative path to the directory from which the server is booted. For more information, see Chapter 30, "Configuring Keystores". If you are using an Oracle OPSS Key Store Service (KSS) keystore, specify this value as the KSS URI. For more information, see Configuring the OPSS Keystore Service for Custom Identity and Trust: Main Steps.
CustomIdentityKeyStorePassPhrase	Encrypts and decrypts the plain text form of the passphrase for the channel's custom identity keystore. When you set the keystore password using this attribute, WebLogic Server automatically encrypts the value and stores it in the CustomIdentityKeyStorePassPhraseEncrypted attribute. If the value is empty or null, keystores not requiring a passphrase may be opened. If a value for this attribute is not set, the value of the ServerMBean.CustomIdentityKeyStorePassPhrase attribute is used by default. This attribute is used only if the ServerMBean.KeyStores attribute is set to one of the following values: CUSTOM_IDENTITY_AND_JAVA_STANDARD_TRUST CUSTOM_IDENTITY_AND_CUSTOM_TRUST CUSTOM_IDENTITY_AND_COMMAND_LINE_TRUST Note: Using the CustomIdentityKeyStorePassPhrase attribute is a potential security risk because the String object that contains the unencrypted password remains in the JVM memory until garbage collection removes it and the memory is reallocated, which potentially can be an indefinite duration. Therefore, Oracle recommends using the CustomIdentityKeyStorePassPhraseEncrypted attribute instead.
CustomIdentityKeyStorePassPhraseEncrypted	Specifies the encrypted passphrase that is set when the custom identity keystore is created. If a value for this attribute is not set, the value of the ServerMBean.CustomIdentityKeyStorePassPhraseEncrypted attribute is used by default. This attribute is only used if the ServerMBean.KeyStores attribute is set to one of the following values: CUSTOM_IDENTITY_AND_JAVA_STANDARD_TRUST CUSTOM_IDENTITY_AND_CUSTOM_TRUST CUSTOM_IDENTITY_AND_COMMAND_LINE_TRUST
CustomIdentityKeyStoreType	Specifies the keystore type of the custom identity keystore. If you are using a JKS keystore, specify the value as JKS. If you are using the Oracle OPSS Key Store Service, specify this value as KSS. If a value for this attribute is not set, the value of the ServerMBean.CustomIdentityKeyStoreType attribute is used by default. The value of this attribute is used only if the ServerMBean.KeyStores attribute is set to one of the following values: CUSTOM_IDENTITY_AND_JAVA_STANDARD_TRUST CUSTOM_IDENTITY_AND_CUSTOM_TRUST CUSTOM_IDENTITY_AND_COMMAND_LINE_TRUST
ClientCertificateEnforced	Specifies whether clients must present digital certificates from a trusted certificate authority to WebLogic Server on this channel.
CustomPrivateKeyAlias	Specifies the string alias used to store and retrieve the channel's private key in the custom identity keystore. This private key is associated with the server's digital certificate. A value of null indicates that the network channel uses the alias specified in the server's SSL configuration. Note that if the CustomIdentityKeyStore* attributes are not set, the CustomPrivateKeyAlias attribute may be set to refer to the server keystore.
CustomPrivateKeyPassPhrase	Encrypts and decrypts the plain text form of the passphrase used to retrieve the channel's private key from the custom identity keystore. When you set the private key passphrase using this attribute, WebLogic Server automatically encrypts the value and stores it in the CustomPrivateKeyPassPhraseEncrypted attribute. This passphrase is assigned to the private key when it is generated. A value of null indicates that the network channel uses the passphrase specified in the server's SSL configuration.
CustomPrivateKeyPassPhraseEncrypted	Specifies the encrypted passphrase used to retrieve the channel's private key from the custom identity keystore.
OutboundPrivateKeyEnabled	Specifies whether the identity specified by the NetworkAccessPointMBean.CustomPrivateKeyAlias attribute should be used for outbound SSL connections on this channel. Typically the outbound identity is determined by the caller's environment.
TwoWaySSLEnabled	Specifies whether this network channel uses two way SSL.
HostnameVerificationIgnored	Specifies whether to ignore the configured implementation of the host name verifier (weblogic.security.SSL.HostnameVerifier). This attribute is used only when the server is acting as a client to another application server on a remote host. If a value for this attribute is not set, the value of the SSLMBean.HostnameVerificationIgnored attribute is used by default.
HostnameVerifier	Specifies the name of the class that implements the weblogic.security.SSL.HostnameVerifier interface. A host name verifier is useful when an SSL client (for example, WebLogic Server acting as an SSL client) connects to an application server on a remote host. The host name verifier helps to prevent man-in-the-middle attacks: It ensures that the host name in the URL to which the client connects matches the host name in the digital certificate that the server sends back as part of the SSL connection. If a value for this attribute is not set, the value of the SSLMBean.HostnameVerifier attribute is used by default.
Ciphersuites	Specifies the cipher suites that are to be used with the SSL listener for the network channel. During the SSL handshake, the strongest negotiated cipher suite is chosen. The set of cipher suites that are enabled by default depends on the specific JDK version with which WebLogic Server is configured. For more information, see Cipher Suites. If a value for this attribute is not set, the value of the SSLMBean.Ciphersuites attribute is used by default. Note: You cannot set the SSLMBean.Ciphersuites attribute from the WebLogic Server Administration Console, but you can set the NetworkAccessPointMBean.Ciphersuites attribute from the console.
AllowUnencryptedNullCipher	Specifies whether unencrypted null ciphers are allowed on the network channel. If a value for this attribute is not set, the value of the SSLMBean.AllowUnencryptedNullCipher attribute is used by default. During the SSL handshake, when the server and client negotiate the set of cipher suites that are to be used, the client might specify a set of cipher suites that contain only null ciphers. A null cipher passes data on the wire in clear-text, making it possible for a network packet sniffer to see the SSL messages. When null ciphers are used, SSL may be used for authentication, but messages may not be encrypted. By default, WebLogic Server does not allow null ciphers. For more information, see "An Important Note Regarding Null Cipher Use in SSL" in Securing a Production Environment for Oracle WebLogic Server.
InboundCertificateValidation	Specifies the client certificate validation rules for inbound SSL. This attribute applies only to a network channel that is configured to use two-way SSL. Either of the following values may be set: BuiltinSSLValidationOnly—Uses the built-in trusted Certificate Authority-based validation. This is the default. BuiltinSSLValidationAndCertPathValidators—Uses the built-in trusted CA-based validation and also the configured CertPathValidator providers to perform extra validation. For more information about these rules, see How SSL Certificate Validation Works in WebLogic Server. If a value for this attribute is not set, the value of the SSLMBean.InboundCertificateValidation attribute is used by default.
OutboundCertificateValidation	Specifies the server certificate validation rules for outbound SSL. Either of the following values may be set: BuiltinSSLValidationOnly—Uses the built-in trusted Certificate Authority-based validation. This is the default. BuiltinSSLValidationAndCertPathValidators—Uses the built-in trusted CA-based validation and also the configured CertPathValidator providers to perform extra validation. For more information about these rules, see How SSL Certificate Validation Works in WebLogic Server. If a value for this attribute is not set, the value of the SSLMBean.OutboundCertificateValidation attribute is used by default.

Steps to Configure a Channel-Specific Identity Keystore

To configure a network channel to use a custom identity keystore separate from the one used by the Managed Server, complete the following steps:

1. Configure a custom identity keystore, add the private key and the public identity certificate to be used by the network channel, and assign a private key alias.

   • For information about configuring a JKS keystore, see Chapter 30, "Configuring Keystores".

   • For information about configuring an Oracle OPSS Key Store Service (KSS) keystore, see Configuring the OPSS Keystore Service for Custom Identity and Trust: Main Steps.

2. Create a custom network channel and assign the following attributes, ensuring that the combination of them is unique in the domain:

   • Channel name

   • Listen address

   • Listen port

   • Secure communication protocol (that is, either HTTPS or t3s)

   For information, see "Configure custom network channels" in Oracle WebLogic Server Administration Console Online Help.

3. Configure the channel to use the custom identity keystore created in Step 1 by setting the following attributes on the NetworkAccessPointMBean:

   • CustomIdentityKeyStoreFileName — If you are using a JKS keystore, specify the path to the keystore. If you are using a KSS keystore, specify this value as the KSS URI.

   • CustomIdentityKeyStoreType — Specify the key store type. For example, JKS or KSS.

   • Either the CustomIdentityKeyStorePassPhraseEncrypted attribute, or the CustomIdentityKeyStorePassPhrase attribute using the custom identity keystore passphrase.

   • ChannelIdentityCustomized — Set to true.

   • CustomPrivateKeyAlias — Specifies the string alias used to store and retrieve the channel's private key in the custom identity keystore. This private key is associated with the channel's identity certificate. Setting this attribute ensures that the channel alias corresponds to the channel's custom identity keystore and not to an alias in the server's identity keystore.

   • CustomPrivateKeyPassPhrase — Specify the value of the passphrase of the private key referenced by the CustomPrivateKeyAlias attribute.

   For information, see "Configure keystores and SSL attributes specific to a network channel" in Oracle WebLogic Server Administration Console Online Help.

   Note:

   If any of the CustomIdentityKeyStoreFileName, CustomIdentityKeyStoreType, CustomIdentityKeyStorePassPhraseEncrypted, or CustomIdentityKeyStorePassPhrase attributes are set, then all the following conditions must be met to ensure that the channel alias relates to the channel's custom identity keystore and does not default to an alias in the server keystore:

   1. All the preceding attributes must be set (that is, CustomIdentityKeyStoreFileName, CustomIdentityKeyStoreType, CustomIdentityKeyStorePassPhraseEncrypted, and CustomIdentityKeyStorePassPhrase must all be set).

   2. The NetworkAccessPointMBean.ChannelIdentityCustomized attribute must be set to true.

   3. The NetworkAccessPointMBean.CustomPrivateKeyAlias attribute must be set.

   Note that if none of the CustomIdentityKeyStoreFileName, CustomIdentityKeyStoreType, CustomIdentityKeyStorePassPhraseEncrypted, and CustomIdentityKeyStorePassPhrase attributes are set, the network channel's private key alias may be set to refer to the server keystore.

4. Configure any additional attributes for the network channel, as appropriate. For more information, see "Configuring a Channel" in Administering Server Environments for Oracle WebLogic Server and "Configure custom network channels" in Oracle WebLogic Server Administration Console Online Help.

   For information about specifying a host name verifier class, see Chapter 32, "Using Host Name Verification".

   For information about inbound and outbound certificate validation, see Chapter 35, "SSL Certificate Validation".

Using WLST to Configure a Channel-Specific Identity Keystore

This section provides an example of using WLST to configure a channel-specific identity keystore. Example 41-1 shows the following:

1. Connecting to a Managed Server instance.

2. Navigating to the MBean that corresponds to the specific network channel for which a custom identity keystore is to be configured, https-override.

3. Setting the name and location of the custom identity keystore file, channelIdentity.jks.

4. Setting the passphrase for the custom identity keystore.

5. Setting the custom identity keystore type to JKS.

6. Establishing that the channel's custom identity should be used.

7. Setting the custom private key alias to myID.

8. Setting the custom private key passphrase.

9. Saving and activating the new channel configuration, then disconnecting from the Managed Server instance.

Example 41-1 Configuring a Custom Identity Keystore

connect('admin-user','password') 
edit()
startEdit()
cd ('Servers/myserver/NetworkAccessPoints/https-override')
 
cmo.setCustomIdentityKeyStoreFileName('/path/keystores/channelIdentity.jks')  
cmo.setCustomIdentityKeyStorePassPhrase('passphrase') 
cmo.setCustomIdentityKeyStoreType('JKS')
cmo.setChannelIdentityCustomized(true)
cmo.setCustomPrivateKeyAlias('myID')
cmo.setCustomPrivateKeyPassPhrase('keypassphrase')
 
save()
activate()
disconnect()