Chapter 4. Configuring TLS/SSL encryption
Chapter 4. Configuring TLS/SSL encryption You can secure Data Grid Server connections using SSL/TLS encryption by configuring a keystore that contains public and private keys for Data Grid. You can also configure client certificate authentication if you require mutual TLS. 4.1. Configuring Data Grid Server keystores Add keystores to Data Grid Server and configure it to present SSL/TLS certificates that verify its identity to clients. If a security realm contains TLS/SSL identities, it encrypts any connections to Data Grid Server endpoints that use that security realm. Prerequisites Create a keystore that contains certificates, or certificate chains, for Data Grid Server. Data Grid Server supports the following keystore formats: JKS, JCEKS, PKCS12/PFX and PEM. BKS, BCFKS, and UBER are also supported if the Bouncy Castle library is present. Certificates should include the subjectAltName extension of type dNSName and/or iPAddress so that clients can correctly perform hostname validation, according to the rules defined by the RFC 2818 specification. The server will issue a warning if it is started with a certificate which does not include such an extension. Important In production environments, server certificates should be signed by a trusted Certificate Authority, either Root or Intermediate CA. Tip You can use PEM files as keystores if they contain both of the following: A private key in PKCS#1 or PKCS#8 format. One or more certificates. You should also configure PEM file keystores with an empty password ( password="" ). Procedure Open your Data Grid Server configuration for editing. Add the keystore that contains SSL/TLS identities for Data Grid Server to the USDRHDG_HOME/server/conf directory. Add a server-identities definition to the Data Grid Server security realm. Specify the keystore file name with the path attribute. Provide the keystore password and certificate alias with the keystore-password and alias attributes. Save the changes to your configuration. steps Configure clients with a trust store so they can verify SSL/TLS identities for Data Grid Server. Keystore configuration XML <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <!-- Adds a keystore that contains server certificates that provide SSL/TLS identities to clients. --> <keystore path="server.p12" relative-to="infinispan.server.config.path" password="secret" alias="my-server"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> JSON { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "alias": "my-server", "path": "server.p12", "password": "secret" } } } }] } } } YAML server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: alias: "my-server" path: "server.p12" password: "secret" 4.1.1. SSL/TLS Certificate rotation SSL/TLS certificates have an expiration date, after which they are no longer valid. The process of renewing a certificate is also known as "rotation". Data Grid monitors the keystore files for changes and automatically reloads them without requiring a server or client restart. Note To ensure seamless operations during certificate rotation, use certificates signed by a Certificate Authority (CA) and configure both server and client trust stores with the CA certificate. Using self-signed certificates will cause temporary handshake failures until all clients and servers have been updated. Additional resources Configuring Hot Rod client encryption 4.1.2. Generating Data Grid Server keystores Configure Data Grid Server to automatically generate keystores at startup. Important Automatically generated keystores: Should not be used in production environments. Are generated whenever necessary; for example, while obtaining the first connection from a client. Contain certificates that you can use directly in Hot Rod clients. Procedure Open your Data Grid Server configuration for editing. Include the generate-self-signed-certificate-host attribute for the keystore element in the server configuration. Specify a hostname for the server certificate as the value. Save the changes to your configuration. Generated keystore configuration XML <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="generated-keystore"> <server-identities> <ssl> <!-- Generates a keystore that includes a self-signed certificate with the specified hostname. --> <keystore path="server.p12" relative-to="infinispan.server.config.path" password="secret" alias="server" generate-self-signed-certificate-host="localhost"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> JSON { "server": { "security": { "security-realms": [{ "name": "generated-keystore", "server-identities": { "ssl": { "keystore": { "alias": "server", "generate-self-signed-certificate-host": "localhost", "path": "server.p12", "password": "secret" } } } }] } } } YAML server: security: securityRealms: - name: "generated-keystore" serverIdentities: ssl: keystore: alias: "server" generateSelfSignedCertificateHost: "localhost" path: "server.p12" password: "secret" 4.1.3. Configuring TLS versions and cipher suites When using SSL/TLS encryption to secure your deployment, you can configure Data Grid Server to use specific versions of the TLS protocol as well as specific cipher suites within the protocol. Procedure Open your Data Grid Server configuration for editing. Add the engine element to the SSL configuration for Data Grid Server. Configure Data Grid to use one or more TLS versions with the enabled-protocols attribute. Data Grid Server supports TLS version 1.2 and 1.3 by default. If appropriate you can set TLSv1.3 only to restrict the security protocol for client connections. Data Grid does not recommend enabling TLSv1.1 because it is an older protocol with limited support and provides weak security. You should never enable any version of TLS older than 1.1. Warning If you modify the SSL engine configuration for Data Grid Server you must explicitly configure TLS versions with the enabled-protocols attribute. Omitting the enabled-protocols attribute allows any TLS version. <engine enabled-protocols="TLSv1.3 TLSv1.2" /> Configure Data Grid to use one or more cipher suites with the enabled-ciphersuites attribute (for TLSv1.2 and below) and the enabled-ciphersuites-tls13 attribute (for TLSv1.3). You must ensure that you set a cipher suite that supports any protocol features you plan to use; for example HTTP/2 ALPN . Save the changes to your configuration. SSL engine configuration XML <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <keystore path="server.p12" relative-to="infinispan.server.config.path" password="secret" alias="server"/> <!-- Configures Data Grid Server to use specific TLS versions and cipher suites. --> <engine enabled-protocols="TLSv1.3 TLSv1.2" enabled-ciphersuites="TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256" enabled-ciphersuites-tls13="TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> JSON { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "alias": "server", "path": "server.p12", "password": "secret" }, "engine": { "enabled-protocols": ["TLSv1.3"], "enabled-ciphersuites": "TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256", "enabled-ciphersuites-tls13": "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" } } } }] } } } YAML server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: alias: "server" path: "server.p12" password: "secret" engine: enabledProtocols: - "TLSv1.3" enabledCiphersuites: "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" enabledCiphersuitesTls13: "TLS_AES_256_GCM_SHA384" 4.2. Configuring Data Grid Server on a system with FIPS 140-2 compliant cryptography FIPS (Federal Information Processing Standards) are standards and guidelines for US federal computer systems. Although FIPS are developed for use by the US federal government, many in the private sector voluntarily use these standards. FIPS 140-2 defines security requirements for cryptographic modules. You can configure your Data Grid Server to use encryption ciphers that adhere to the FIPS 140-2 specification by using alternative JDK security providers. Additional resources Java PKCS#11 cryptographic provider The Legion of the Bouncy Castle cryptographic provider 4.2.1. Configuring the PKCS11 cryptographic provider You can configure the PKCS11 cryptographic provider by specifying the PKCS11 keystore with the SunPKCS11-NSS-FIPS provider. Prerequisites Configure your system for FIPS mode. You can check if your system has FIPS Mode enabled by issuing the fips-mode-setup --check command in your Data Grid command-line Interface (CLI) Initialize the system-wide NSS database by using the certutil tool. Install the JDK with the java.security file configured to enable the SunPKCS11 provider. This provider points to the NSS database and the SSL provider. Install a certificate in the NSS database. Procedure Open your Data Grid Server configuration for editing. Add a server-identities definition to the Data Grid Server security realm. Specify the PKCS11 keystore with the SunPKCS11-NSS-FIPS provider. Save the changes to your configuration. Keystore configuration XML <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <!-- Adds a keystore that reads certificates from the NSS database. --> <keystore provider="SunPKCS11-NSS-FIPS" type="PKCS11"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> JSON { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "provider": "SunPKCS11-NSS-FIPS", "type": "PKCS11" } } } }] } } } YAML server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: provider: "SunPKCS11-NSS-FIPS" type: "PKCS11" 4.2.2. Configuring the Bouncy Castle FIPS cryptographic provider You can configure the Bouncy Castle FIPS (Federal Information Processing Standards) cryptographic provider in your Data Grid server's configuration. Prerequisites Configure your system for FIPS mode. You can check if your system has FIPS Mode enabled by issuing the fips-mode-setup --check command in your Data Grid command-line Interface (CLI). Create a keystore in BCFKS format that contains a certificate. Procedure Download the Bouncy Castle FIPS JAR file, and add the file to the server/lib directory of your Data Grid Server installation. To install Bouncy Castle, issue the install command: Open your Data Grid Server configuration for editing. Add a server-identities definition to the Data Grid Server security realm. Specify the BCFKS keystore with the BCFIPS provider. Save the changes to your configuration. Keystore configuration XML <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <!-- Adds a keystore that reads certificates from the BCFKS keystore. --> <keystore path="server.bcfks" password="secret" alias="server" provider="BCFIPS" type="BCFKS"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> JSON { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "path": "server.bcfks", "password": "secret", "alias": "server", "provider": "BCFIPS", "type": "BCFKS" } } } }] } } } YAML server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: path: "server.bcfks" password: "secret" alias: "server" provider: "BCFIPS" type: "BCFKS" 4.3. Configuring client certificate authentication Configure Data Grid Server to use mutual TLS to secure client connections. You can configure Data Grid to verify client identities from certificates in a trust store in two ways: Require a trust store that contains only the signing certificate, which is typically a Certificate Authority (CA). Any client that presents a certificate signed by the CA can connect to Data Grid. Require a trust store that contains all client certificates in addition to the signing certificate. Only clients that present a signed certificate that is present in the trust store can connect to Data Grid. Tip Alternatively to providing trust stores you can use shared system certificates. Prerequisites Create a client trust store that contains either the CA certificate or all public certificates. Create a keystore for Data Grid Server and configure an SSL/TLS identity. Note PEM files can be used as trust stores provided they contain one or more certificates. These trust stores should be configured with an empty password: password="" . Procedure Open your Data Grid Server configuration for editing. Add the require-ssl-client-auth="true" parameter to your endpoints configuration. Add the client trust store to the USDRHDG_HOME/server/conf directory. Specify the path and password attributes for the truststore element in the Data Grid Server security realm configuration. Add the <truststore-realm/> element to the security realm if you want Data Grid Server to authenticate each client certificate. Save the changes to your configuration. steps Set up authorization with client certificates in the Data Grid Server configuration if you control access with security roles and permissions. Configure clients to negotiate SSL/TLS connections with Data Grid Server. Client certificate authentication configuration XML <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="trust-store-realm"> <server-identities> <ssl> <!-- Provides an SSL/TLS identity with a keystore that contains server certificates. --> <keystore path="server.p12" relative-to="infinispan.server.config.path" keystore-password="secret" alias="server"/> <!-- Configures a trust store that contains client certificates or part of a certificate chain. --> <truststore path="trust.p12" relative-to="infinispan.server.config.path" password="secret"/> </ssl> </server-identities> <!-- Authenticates client certificates against the trust store. If you configure this, the trust store must contain the public certificates for all clients. --> <truststore-realm/> </security-realm> </security-realms> </security> <endpoints> <endpoint socket-binding="default" security-realm="trust-store-realm" require-ssl-client-auth="true"> <hotrod-connector> <authentication> <sasl mechanisms="EXTERNAL" server-name="infinispan" qop="auth"/> </authentication> </hotrod-connector> <rest-connector> <authentication mechanisms="CLIENT_CERT"/> </rest-connector> </endpoint> </endpoints> </server> JSON { "server": { "security": { "security-realms": [{ "name": "trust-store-realm", "server-identities": { "ssl": { "keystore": { "path": "server.p12", "relative-to": "infinispan.server.config.path", "keystore-password": "secret", "alias": "server" }, "truststore": { "path": "trust.p12", "relative-to": "infinispan.server.config.path", "password": "secret" } } }, "truststore-realm": {} }] }, "endpoints": [{ "socket-binding": "default", "security-realm": "trust-store-realm", "require-ssl-client-auth": "true", "connectors": { "hotrod": { "hotrod-connector": { "authentication": { "sasl": { "mechanisms": "EXTERNAL", "server-name": "infinispan", "qop": "auth" } } }, "rest": { "rest-connector": { "authentication": { "mechanisms": "CLIENT_CERT" } } } } } }] } } YAML server: security: securityRealms: - name: "trust-store-realm" serverIdentities: ssl: keystore: path: "server.p12" relative-to: "infinispan.server.config.path" keystore-password: "secret" alias: "server" truststore: path: "trust.p12" relative-to: "infinispan.server.config.path" password: "secret" truststoreRealm: ~ endpoints: socketBinding: "default" securityRealm: "trust-store-realm" requireSslClientAuth: "true" connectors: - hotrod: hotrodConnector: authentication: sasl: mechanisms: "EXTERNAL" serverName: "infinispan" qop: "auth" - rest: restConnector: authentication: mechanisms: "CLIENT_CERT" Additional resources Configuring Hot Rod client encryption Using Shared System Certificates (Red Hat Enterprise Linux 7 Security Guide) 4.4. Configuring authorization with client certificates Enabling client certificate authentication means you do not need to specify Data Grid user credentials in client configuration, which means you must associate roles with the Common Name (CN) field in the client certificate(s). Prerequisites Provide clients with a Java keystore that contains either their public certificates or part of the certificate chain, typically a public CA certificate. Configure Data Grid Server to perform client certificate authentication. Procedure Open your Data Grid Server configuration for editing. Enable the common-name-role-mapper in the security authorization configuration. Assign the Common Name ( CN ) from the client certificate a role with the appropriate permissions. Save the changes to your configuration. Note Data Grid creates the identity of the client by extracting the certificate principal. Any other Subject Alternative Names (SANs) which may be present in the certificate are currently ignored. For this reason, the authorization.group-only-mapping attribute below must be set to false . Client certificate authorization configuration XML <infinispan> <cache-container name="certificate-authentication" statistics="true"> <security> <authorization group-only-mapping="false"> <!-- Declare a role mapper that associates the common name (CN) field in client certificate trust stores with authorization roles. --> <common-name-role-mapper/> <!-- In this example, if a client certificate contains `CN=Client1` then clients with matching certificates get ALL permissions. --> <role name="Client1" permissions="ALL"/> </authorization> </security> </cache-container> </infinispan> JSON { "infinispan": { "cache-container": { "name": "certificate-authentication", "security": { "authorization": { "group-only-mapping": false, "common-name-role-mapper": null, "roles": { "Client1": { "role": { "permissions": "ALL" } } } } } } } } YAML infinispan: cacheContainer: name: "certificate-authentication" security: authorization: groupOnlyMapping: false commonNameRoleMapper: ~ roles: Client1: role: permissions: - "ALL"
<server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <!-- Adds a keystore that contains server certificates that provide SSL/TLS identities to clients. --> <keystore path="server.p12" relative-to="infinispan.server.config.path" password="secret" alias="my-server"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "alias": "my-server", "path": "server.p12", "password": "secret" } } } }] } } } server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: alias: "my-server" path: "server.p12" password: "secret" <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="generated-keystore"> <server-identities> <ssl> <!-- Generates a keystore that includes a self-signed certificate with the specified hostname. --> <keystore path="server.p12" relative-to="infinispan.server.config.path" password="secret" alias="server" generate-self-signed-certificate-host="localhost"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> { "server": { "security": { "security-realms": [{ "name": "generated-keystore", "server-identities": { "ssl": { "keystore": { "alias": "server", "generate-self-signed-certificate-host": "localhost", "path": "server.p12", "password": "secret" } } } }] } } } server: security: securityRealms: - name: "generated-keystore" serverIdentities: ssl: keystore: alias: "server" generateSelfSignedCertificateHost: "localhost" path: "server.p12" password: "secret" <engine enabled-protocols="TLSv1.3 TLSv1.2" /> <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <keystore path="server.p12" relative-to="infinispan.server.config.path" password="secret" alias="server"/> <!-- Configures Data Grid Server to use specific TLS versions and cipher suites. --> <engine enabled-protocols="TLSv1.3 TLSv1.2" enabled-ciphersuites="TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256" enabled-ciphersuites-tls13="TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "alias": "server", "path": "server.p12", "password": "secret" }, "engine": { "enabled-protocols": ["TLSv1.3"], "enabled-ciphersuites": "TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256", "enabled-ciphersuites-tls13": "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" } } } }] } } } server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: alias: "server" path: "server.p12" password: "secret" engine: enabledProtocols: - "TLSv1.3" enabledCiphersuites: "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256" enabledCiphersuitesTls13: "TLS_AES_256_GCM_SHA384" <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <!-- Adds a keystore that reads certificates from the NSS database. --> <keystore provider="SunPKCS11-NSS-FIPS" type="PKCS11"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "provider": "SunPKCS11-NSS-FIPS", "type": "PKCS11" } } } }] } } } server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: provider: "SunPKCS11-NSS-FIPS" type: "PKCS11" [disconnected]> install org.bouncycastle:bc-fips:1.0.2.3 <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="default"> <server-identities> <ssl> <!-- Adds a keystore that reads certificates from the BCFKS keystore. --> <keystore path="server.bcfks" password="secret" alias="server" provider="BCFIPS" type="BCFKS"/> </ssl> </server-identities> </security-realm> </security-realms> </security> </server> { "server": { "security": { "security-realms": [{ "name": "default", "server-identities": { "ssl": { "keystore": { "path": "server.bcfks", "password": "secret", "alias": "server", "provider": "BCFIPS", "type": "BCFKS" } } } }] } } } server: security: securityRealms: - name: "default" serverIdentities: ssl: keystore: path: "server.bcfks" password: "secret" alias: "server" provider: "BCFIPS" type: "BCFKS" <server xmlns="urn:infinispan:server:15.0"> <security> <security-realms> <security-realm name="trust-store-realm"> <server-identities> <ssl> <!-- Provides an SSL/TLS identity with a keystore that contains server certificates. --> <keystore path="server.p12" relative-to="infinispan.server.config.path" keystore-password="secret" alias="server"/> <!-- Configures a trust store that contains client certificates or part of a certificate chain. --> <truststore path="trust.p12" relative-to="infinispan.server.config.path" password="secret"/> </ssl> </server-identities> <!-- Authenticates client certificates against the trust store. If you configure this, the trust store must contain the public certificates for all clients. --> <truststore-realm/> </security-realm> </security-realms> </security> <endpoints> <endpoint socket-binding="default" security-realm="trust-store-realm" require-ssl-client-auth="true"> <hotrod-connector> <authentication> <sasl mechanisms="EXTERNAL" server-name="infinispan" qop="auth"/> </authentication> </hotrod-connector> <rest-connector> <authentication mechanisms="CLIENT_CERT"/> </rest-connector> </endpoint> </endpoints> </server> { "server": { "security": { "security-realms": [{ "name": "trust-store-realm", "server-identities": { "ssl": { "keystore": { "path": "server.p12", "relative-to": "infinispan.server.config.path", "keystore-password": "secret", "alias": "server" }, "truststore": { "path": "trust.p12", "relative-to": "infinispan.server.config.path", "password": "secret" } } }, "truststore-realm": {} }] }, "endpoints": [{ "socket-binding": "default", "security-realm": "trust-store-realm", "require-ssl-client-auth": "true", "connectors": { "hotrod": { "hotrod-connector": { "authentication": { "sasl": { "mechanisms": "EXTERNAL", "server-name": "infinispan", "qop": "auth" } } }, "rest": { "rest-connector": { "authentication": { "mechanisms": "CLIENT_CERT" } } } } } }] } } server: security: securityRealms: - name: "trust-store-realm" serverIdentities: ssl: keystore: path: "server.p12" relative-to: "infinispan.server.config.path" keystore-password: "secret" alias: "server" truststore: path: "trust.p12" relative-to: "infinispan.server.config.path" password: "secret" truststoreRealm: ~ endpoints: socketBinding: "default" securityRealm: "trust-store-realm" requireSslClientAuth: "true" connectors: - hotrod: hotrodConnector: authentication: sasl: mechanisms: "EXTERNAL" serverName: "infinispan" qop: "auth" - rest: restConnector: authentication: mechanisms: "CLIENT_CERT" <infinispan> <cache-container name="certificate-authentication" statistics="true"> <security> <authorization group-only-mapping="false"> <!-- Declare a role mapper that associates the common name (CN) field in client certificate trust stores with authorization roles. --> <common-name-role-mapper/> <!-- In this example, if a client certificate contains `CN=Client1` then clients with matching certificates get ALL permissions. --> <role name="Client1" permissions="ALL"/> </authorization> </security> </cache-container> </infinispan> { "infinispan": { "cache-container": { "name": "certificate-authentication", "security": { "authorization": { "group-only-mapping": false, "common-name-role-mapper": null, "roles": { "Client1": { "role": { "permissions": "ALL" } } } } } } } } infinispan: cacheContainer: name: "certificate-authentication" security: authorization: groupOnlyMapping: false commonNameRoleMapper: ~ roles: Client1: role: permissions: - "ALL"