This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

# Internal Platform Encryption

Platform Operators have the option of enabling encryption for internal traffic on the Platform during installation. Enabling this feature will enforce encryption for guest application and Apprenda components as described in the Configuration section below.

It should be noted that encryption of external traffic depends on settings configured in the Security section of the SOC and will use a separate certificate (the SSL Certificate) from those discussed below. It should also noted that certain data (such as passwords) will always be encrypted regardless of transport method.

## Certificates for Internal Platform Encryption

Two certificates are required for internal Platform encryption:

• the host certificate, which is used to encrypt traffic
• the issuer certificate, which is used to create the host certificate

Should you choose to enable internal Platform encryption, you have three options in regards to the certificates that will be used:

1. Apprenda will generate and install the issuer certificates that will be used; Apprenda will then create and install host certificates (named after each individual host) as needed.
2. You may specify an issuer certificate (as a PFX file) and password; Apprenda will install the issuer certificate and will then create and install host certificates (named after each individual host) as needed.
3. You may specify a public key for the issuer certificate as either a PEM or CER file. Apprenda will install the issuer certificate. You must create and install the host certificates as indicated in the Pre-Installation Checklist.

Note: All user generated certificates must be Cryptographic Service Provider (CSP) compliant.

Issuer certificates created by the Apprenda will expire 20 years from their creation date. Host certificates created by Apprenda will have the same expiration date as the issuer certificate used to create them. Issuer certificates installed by Apprenda will be installed to the local certificate store under "Personal" and "Trusted Root Certification Authorities." Host certificates installed by Apprenda will be installed to the local certificate store under "Personal."

It should be noted that any guest application workload running on the Apprenda Platform can access the certificate and private key used as the host certificate. Because of this, the certificate used for the host certificate should be trusted within Apprenda only and should be used only to encrypt internal Platform traffic. The issuer certificate cannot be accessed in this way.

## Enabling Encryption at Platform installation

When using the Apprenda GUI Installer, you will be able to indicate your certificate configuration preferences (and specify the path to any certificates that you must supply) through the installer's user interface.

Should you choose to install using the Apprenda CLI Installer, you can configure each of the three certificate configuration options in the ApprendaGridDefinitions.xml file that you configure for the install. Each configuration requires a different combination of the following attributes under the ApprendaGrid element:

Setting Description Values
encryptInternalCommunication Enables / disables internal encryption true,false
generateInternalCommunicationIssuerCertificate Makes the installer generate the issuer certificate (true) or use a customer supplied certificate (false) true,false
generateInternalCommunicationCertificates Allows Apprenda to generate host certificates at runtime (true) or expect certificates to already be in the store (false) true,false
internalCommunicationIssuerCertificate Path to the certificate to be used as the issuer; (required only if generateInternalCommunicationIssuerCertificate is false) [file-path]
internalCommunicationIssuerCertificatePassword Password for the issuer certificate; (required only if generateInternalCommunicationCertificates is false and generateInternalCommunicationCertificates is true) [password]

Examples of the relevant part of the ApprendaGridDefinitions.xml file for the each of the three certificate configuration options are as follows:

Example 1: Installer-generated issuer and host certificates

  <ApprendaGrid encryptInternalCommunication="true"
generateInternalCommunicationIssuerCertificate="true"
generateInternalCommunicationCertificates="true" />


Example 2: Issuer certificate and password are supplied by Platform Operator; host certificate generated by the Installer

  <ApprendaGrid encryptInternalCommunication="true"
generateInternalCommunicationIssuerCertificate="false"
internalCommunicationIssuerCertificate="C:\Path\to\issuer\internal_encryption_issuer_cert.pfx"
generateInternalCommunicationCertificates="true" />


Example 3: Issuer certificate public key supplied by Platform Operator

  <ApprendaGrid encryptInternalCommunication="true"
generateInternalCommunicationIssuerCertificate="false"
internalCommunicationIssuerCertificate="C:\Path\to\issuer\internal_encryption_issuer_cert.pem"
generateInternalCommunicationCertificates="false" />


Configuration

The following settings in the Platform Registry pertain to internal Platform encryption:

 Name Explanation Values Apprenda.Security.EncryptInternalTraffic The Platform checks this setting when deciding whether internal web traffic must be encrypted or not. Currently can only be set at install or for some  upgrade scenarios. It is set by the Apprenda Installer and should not be modified by the Platform Operator. True, False Apprenda.Security.CertificateCreationEnabled When True, Apprenda will generate host certificates for Windows and Linux nodes within the Platform as necessary. Currently can only be set at install or upgrade time. It is set by the Apprenda Installer and should not be modified by the Platform Operator True, False Apprenda.Security.PlatformCACertificateThumbprint This setting only exists when Apprenda.Security.EncryptInternalTraffic has a value of True. When deploying new workloads, Apprenda checks the node the workload is being deployed to for a host certificate which has been signed by the Platform's issuer certificate. It does this by verifying the signer thumbprint of the host cert matches the GUID of this registry setting. GUID Hosting.Services.EnforceSSL When True, Windows Services and Linux Services must serve over https unless they are on an exception list. When false, Windows Services and Linux Services will serve over http. True,False Hosting.Services.EnforceSSLExceptionList When Hosting.Services.EnforceSSL is set to True, the platform will check the application aliases on this list during deployment. If there is a match, and the app is either a Windows Service or a Linux Service, it will be allowed to serve http traffic. This list is ignored if Hosting.Services.EnforceSSL is set to False. List of application aliases separated by commas

When internal Platform encryption is enabled, the Platform will automatically encrypt communications from the Load Manager to the following guest application workloads (including those owned by the "Apprenda" Tenant):

• WCF services
• .NET UIs
• Java Webs Applications (WARs)

Traffic amongst  the guest application workloads listed above (e.g., between WCF services or between a .NET UI and WCF service) will also be encrypted.

Encryption for the following can be enforced by the Hosting.Services.EnforceSSL setting described in the table above (and modified as needed with the Hosting.Services.EnforceSSLExceptionList setting):

• Windows Services
• Linux Services

Encryption for traffic from any Apprenda node to the following must be configured separately by your IT department as per your organization's security protocols:

• Platform Repository
• SQL Server or Oracle Database Servers (including the SQL instance used for the Auditing Database if you have enabled Platform Auditing)

It should be noted that this version of the Apprenda Platform cannot natively encrypt traffic that involves the Apprenda Caching or ZooKeeper (Platform Coordination) services.

## Considerations for Guest Applications

### Environment Variables

Encryption support for traffic from other guest application components to storage partitions relies on the level of encryption support built into the database drivers used when developing the components. Any Platform-wide encryption requirements should therefore be communicated clearly to Developers so that they use appropriate drivers when developing applications.

Internal encryption for some guest application workload types, such as Linux Services, relies on certain configuration options made by Developers. In order to assist Developers with this, the following environment variables, which relate to the host certificate, have been made available for Linux Services:

• SSL_PRIVATE_KEY_PATH -> The file path to the private key in PEM format
• SSL_CERTIFICATE_PATH -> The file path to the certificate in PEM format

Apprenda Tokens for the host certificate and private key path have also been made available for Linux Services.

### Windows Services

When internal Platform encryption is enabled on the Platform, guest applications with Windows Services will be handled in specific ways by the Platform when deployed. The following chart documents how Developers should expect guest applications with Windows Services to behave based on how Platform Operators have configured internal Platform encryption and if the application alias is listed in the Hosting.Services.EnforceSSLExceptionList Platform Registry setting. (For application aliases listed in the Hosting.Services.EnforceSSLExceptionList setting, Windows Services will be accessed via http regardless of global internal Platform configuration settings and regardless of the value configured for the Hosting.Services.EnforceSSL Registry setting).

Platform Encryption Application on Exempt List Access Control Host Certificate bound to Port Thumbprint Token Switching

Enabled

Yes

http

No

Yes

Enabled

No

https

Yes

Yes

Disabled

No

http

No

No

Developers should be aware of how the Platform will handle their application so that they can make the necessary design decisions when developing applications with Windows Services. If a certain configuration is needed for an application, contact your Platform Operator for more information on how your Apprenda environment is configured and if your application should be added to the Hosting.Services.EnforceSSLExceptionList Platform Registry setting.

## Transport Layer Security

The Platform supports TLS 1.0, 1.1, and Platform version 8.1.0 adds support for 1.2 for internal and external web applications communications depending on corresponding environmental configurations.  It is recommended that you disallow vulnerable cryptographic protocol suites (e.g. SSL v2) in your environments to force communications over more secure standards like TLS 1.2.

### TLS and Windows Nodes

Set TLS protocols for Windows nodes in the Windows Registry settings.

### TLS and Linux Nodes

As of Platform version 8.1.0, Platform Operators have the ability to control TLS configurations to and from Linux nodes when internal TLS encryption is enabled using the following  Platform Registry Setting.

• Hosting.Linux.EnabledTLSProtocols.

Hosting.Linux.EnabledTLSProtocols defaults to TLSv1,TLSv1.1,TLSv1.2, but you can update it with the protocols you want enabled on your Platform. The values of Hosting.Linux.EnabledTLSProtocols are a comma delimited string of an explicit protocol set, like the default value, or TLS versions (1.0,1.1).

Protocols are enforced at application bootstrap time on the workload JVM and hosting container configurations. Platform Operators should make sure to communicate the list of supported protocols, as the Platform will not deploy guest application workloads that use unsupported TLS versions.

Using the Hosting.Linux.EnabledTLSProtocols setting will set the sslEnabledProtocols field in server.xml on the Tomcat Hosting Container.

Operators can also specify a comma-delimited list of ciphers to exclude for TLS handshake by using the Apprenda.Security.SSLCipherBlacklist registry setting. The following are excluded by default:

• TLS_DHE_RSA_WITH_AES_128_CBC_SHA
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA
• TLS_DHE_DSS_WITH_AES_256_CBC_SHA