Setting TLS protocol for Router and Message Processor

By default in Apigee Edge for Private Cloud 4.54.00, the Router (Nginx) and Message Processor (Java 21) enable TLSv1.2 and TLSv1.3. Depending on your business needs and security practices, you might want to restrict the allowed protocols or re-enable older protocols. This document describes how to configure the TLS protocols for northbound and southbound traffic on the Router and Message Processor.

For the Router, you can also set the protocol for individual virtual hosts. See Configuring TLS access to an API for the Private Cloud for more.

For the Message Processor, you can set the protocol for an individual TargetEndpoint. See Configuring TLS from Edge to the backend (Cloud and Private Cloud) for more.

Set the TLS protocol on the Router

The following properties help you set the desired TLS protocols on the Router for northbound communication.

To set the TLS protocol on the Router, set properties in the router.properties file:

Open the router.properties file in an editor. If the file does not exist, create it:
```
vi /opt/apigee/customer/application/router.properties
```

Set the properties as desired:

# Possible values are space-delimited list of: TLSv1 TLSv1.1 TLSv1.2 TLSv1.3
conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2

Save your changes.

Make sure the properties file is owned by the apigee user:

chown apigee:apigee /opt/apigee/customer/application/router.properties

Restart the Router:

/opt/apigee/apigee-service/bin/apigee-service edge-router restart

Verify that the protocol is updated correctly by examining the Nginx file /opt/nginx/conf.d/0-default.conf:
```
cat /opt/nginx/conf.d/0-default.conf
```
Ensure that the value for ssl_protocols is TLSv1.2.
If you are using two-way TLS with a virtual host, you must also set the TLS protocol in the virtual host as described in Configuring TLS access to an API for the Private Cloud.

Set the TLS protocol on the Message Processor

The following properties help you set the desired TLS protocols on the Message Processor for southbound communication. This section also describes how to work with disabled TLS protocols and ciphers.

To set the TLS protocol on the Message Processor, set properties in the message-processor.properties file:

Open the message-processor.properties file in an editor. If the file does not exist, create it:
```
vi /opt/apigee/customer/application/message-processor.properties
```

Configure the properties using the following syntax:

# Possible values are a comma-delimited list of TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3
conf/system.properties+https.protocols=[TLSv1][,TLSv1.1][,TLSv1.2][,TLSv1.3]
# Possible values are a comma-delimited list of SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
# SSLv3 is required
conf_jvmsecurity_jdk.tls.disabledAlgorithms=SSLv3[,TLSv1][,TLSv1.1][,TLSv1.2][,TLSv1.3]

# Specify the ciphers that the Message Processor supports. (You must separate ciphers with a comma.):
conf_message-processor-communication_local.http.ssl.ciphers=cipher[,...]

For example:

conf/system.properties+https.protocols=TLSv1.2
conf_jvmsecurity_jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1
conf_message-processor-communication_local.http.ssl.ciphers=TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

For a complete list of related properties, see Configuring TLS between a Router and a Message Processor.

Save your changes.

Make sure the properties file is owned by the apigee user:

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

Restart the Message Processor:

/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

If you are using two-way TLS with the backend, set the TLS protocol in the virtual host as described in Configuring TLS from Edge to the backend (Cloud and Private Cloud).

Working with older ciphers and TLS protocols: Refer to the following sections if you want to work with older ciphers or protocols.

Work with older TLS

In Java 21, legacy TLS protocols (TLSv1, TLSv1.1, and SSLv3) and weak Diffie-Hellman keys (DH keySize < 1024) are disabled by default in jdk.tls.disabledAlgorithms. To enable them, use one of the following options:

Option A: Modernize backend protocols: Update backend servers to support TLS 1.2 or TLS 1.3 and ensure Diffie-Hellman parameter sizes are 2048 bits or greater (>= 2048 bits).

Option B: Re-enable legacy protocols using CwC: Maintain compatibility with legacy TLS 1.0 or TLS 1.1 backends by removing TLSv1, TLSv1.1 from conf_jvmsecurity_jdk.tls.disabledAlgorithms in /opt/apigee/customer/application/message-processor.properties using code with config (CwC):

# Re-enable TLS 1.0 and TLS 1.1 for legacy backend connectivity
conf_jvmsecurity_jdk.tls.disabledAlgorithms=SSLv3, DTLSv1.0, RC4, DES, MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, ECDH, TLS_RSA_*, rsa_pkcs1_sha1 usage HandshakeSignature, ecdsa_sha1 usage HandshakeSignature, dsa_sha1 usage HandshakeSignature, include jdk.disabled.namedCurves

Work with static RSA ciphers

Apigee Edge for Private Cloud version 4.54.00 runs on Java 21, where static RSA cipher suites (TLS_RSA_*) that lack ephemeral Diffie-Hellman key exchange (ECDHE or DHE) are disabled by default in jdk.tls.disabledAlgorithms (for example, TLS_RSA_WITH_AES_128_CBC_SHA or TLS_RSA_WITH_AES_256_CBC_SHA). To support backends that require static RSA cipher suites, use the following option:

Re-enable static RSA ciphers using CwC: Maintain compatibility with legacy backends by removing TLS_RSA_* from conf_jvmsecurity_jdk.tls.disabledAlgorithms in /opt/apigee/customer/application/message-processor.properties using code with config (CwC):

# Re-enable Static RSA ciphers for backward compatibility with legacy Java 8 backends
conf_jvmsecurity_jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, DTLSv1.0, RC4, DES, MD5withRSA, DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, ECDH, rsa_pkcs1_sha1 usage HandshakeSignature, ecdsa_sha1 usage HandshakeSignature, dsa_sha1 usage HandshakeSignature, include jdk.disabled.namedCurves

After modifying properties, restart the Message Processor using apigee-service:

/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Enable TLS 1.3 for a hosts

This section explains how to enable TLS 1.3 for specific virtual hosts. To enable TLS 1.3, perform the following steps on the Management Server nodes:

On each Management Server node, edit the file /opt/apigee/customer/application/management-server.properties and add the following line (if the file doesn't exist, create it):
```
conf_virtualhost_virtual.host.allowed.protocol.list=TLSv1,TLSv1.1,TLSv1.2,TLSv1.3
```
For this file, the protocols are comma-separated and case sensitive.
Save the file.

Ensure the file is owned by the apigee user:

chown apigee:apigee /opt/apigee/customer/application/management-server.properties

Restart the Management Server:

/opt/apigee/apigee-service/bin/apigee-service edge-management-server restart

Repeat the preceding steps on all Management Server nodes one by one.

Create (or update an existing) virtual host with the following property. Note that the protocols are space-separated and case sensitive:

"properties": {
    "property": [
      {
        "name": "ssl_protocols",
        "value": "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"
      }
    ]
}

The following example shows a sample vhost with this property:

{
  "hostAliases": [
    "api.myCompany,com",
  ],
  "interfaces": [],
  "listenOptions": [],
  "name": "secure",
  "port": "443",
  "retryOptions": [],
  "properties": {
    "property": [
      {
        "name": "ssl_protocols",
        "value": "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"
      }
    ]
  },
  "sSLInfo": {
    "ciphers": [],
    "clientAuthEnabled": "false",
    "enabled": "true",
    "ignoreValidationErrors": false,
    "keyAlias": "myCompanyKeyAlias",
    "keyStore": "ref://myCompanyKeystoreref",
    "protocols": []
  },
  "useBuiltInFreeTrialCert": false
}

Testing TLS 1.3

To test TLS 1.3, enter the following command:

curl -v --tlsv1.3 "https://api.myCompany,com/testproxy"

Note that you can test TLS 1.3 only on clients that support this protocol. If TLS 1.3 isn't enabled, you see an error message similar to the following:

sslv3 alert handshake failure