Skip to content

Punchplatform TLS certificates

Abtsract

Use this documentation to learn:

  • the specifications to generate your TLS material
  • the deployed components that require TLS material
  • the running components that require TLS material
  • the destination of the deployed TLS material

Glossary:

  • TLS material : term that regroups the private key, the certificate, the keystore and the truststore for TLS usage.

Certificates Specifications

You must provide the TLS material with your own PKI. Here are some recommendations:

  • Key size superior to 4096 bits for RSA keys or superior to 256 bits for elliptic keys rather than small ones
  • TLS_RSA_, TLS_(EC)DHE_RSA__, or TLS_ECDHE_ECDSA_ crypto suites rather than the other ones
  • Choose a CA-oriented chain of certification rather than self-signed certificates
  • Choose to enable the hostname verification rather than disabling it on your deployed services. This checks the Subject Alternative Names (SAN) against the host name and the IP of the server providing the certificate
  • Choose a two-way SSL authentication rather than a one-way SSL authentication on your deployed services (i.e. activating both servers and client certificates checking)

MANDATORY specifications :

  • Private keys MUST be generated in PKCS8 format.
  • Certificates MUST be generated in x509 format.
  • Keystore and Truststore MUST be generated in JKS or P12 format.
  • Each certificate MUST have in its Subject Alternative Names (SAN) the hostname and IP of the server where the certificate will be used.
  • If you deploy the Punch Kibana Plugin :
    1. The kibana server(s) certificate(s) MUST also have in their Subject Alternative Names (SAN) the hostname and IP of the punch gateway that the punch plugin targets.
    2. The gateway server(s) certificate(s) MUST also have in their Subject Alternative Names (SAN) the hostname and IP of the kibana server that targets it.
How can I verify the Subject Alternative Names (SAN) of a certificate ?
# for the kibana server cetificate
openssl x509 -text -noout -in kibana-server.crt | grep "Subject Alternative Name" -A1

X509v3 Subject Alternative Name: 
    DNS:<kibana-host>, IP Address:<kibana-ip>, DNS:<gateway-host>, IP Address:<gateway-ip>

# for the kibana server cetificate
openssl x509 -text -noout -in gateway-server.crt | grep "Subject Alternative Name" -A1

X509v3 Subject Alternative Name: 
    DNS:<kibana-host>, IP Address:<kibana-ip>, DNS:<gateway-host>, IP Address:<gateway-ip>
May I choose a CA-oriented chain of trust ?

Yes but you MUST generate your CA certificate with a basic_constraint configuration set to CA:TRUE.
You MUST generate your intermediate certificate (if present) with a basic_constraint configuration set to [CA:TRUE, pathlen:0].

TLS Material Required for Deployment

Abstract

Use this section to learn what deployed components need TLS material.

Server-side services :

Deployed Service Mandatory TLS material Description
Elasticsearch Node private key
Node certificate
Admin private key
Admin certificate
CA file		 - The CA file may be common for the admin and the node.
- Default client authentication : OPTIONAL (may be configured)
Gateway Truststore
Keystore		 - The client TLS files and those inside the keystores may be the same.
- Default client authentication : need (may be configured)
Kafka Truststore
Keystore		 - The client keystores and the servers keystores may be the same.
- Default client authentication : required (may be configured)
Zookeeper Truststore
Keystore		 - The client keystores and the servers keystores may be the same.
- Default client authentication : required (may be configured)

Client-side services:

Deployed Service Client to server Mandatory TLS material Description
Kibana Elasticsearch
Gateway		 CA file Kibana client to Gateway if the Punch Plugin is installed.
Kibana client to Gateway if the target cluster type is gateway.
Servers authentication : full (may be configured).
kafka Zookeeper Truststore
Keystore		 Server's authentication : required (may be configured)
Zookeeper Kafka Truststore
Keystore		 Server's authentication : required (may be configured)
Shiva Kafka
Elasticsearch		 Truststore
Keystore		 Shiva client to ES if the reporter type is elasticsearch.
Servers authentication : required (can't be configured)
Elastic Beats Elasticsearch
Kafka		 CA file Server's authentication : full (may be configured).
Beat client to Kafka if output type is kafka.
Beat client to ES if output type is elasticsearch.

Learn how to configure these components with TLS and other option TLS configurations in:

TLS Material Usage at Runtime

Abstract

Use this section to learn what running components need TLS material

After the deployment process, components may require additional TLS material to run punch commands or punchlines :

Deployed Services Runtime Usage TLS Material Description
Operator Punch commands TLS configuration in the section platform.punch_commands.security of the punchplatform_deployment.settings file
Gateway
Shiva
Storm
Spark		 Punchlines TLS configuration in the resolver file

Learn how to configure the punch commands with TLS for an operator in:

Learn how to configure the resolver file for tenants, channels and punchlines with TLS in:

Learn what TLS configuration are needed for punchlines in :

TLS material destination on deployed hosts

For each service, the credentials resources have a dedicated storage folder used by the punch deployer on the deployed server :

Deployed Services Destination
Elasticsearch {platform.setups_root}/{elasticsearch.version}/config
Kibana {platform.remote_data_root_directory}/kibana/{kibana.domains.domain}/.secrets
Others /home/{platform.punchplatform_daemons_user}/.secrets

The permissions applied over the TLS material files ensure very restricted access (being readable only by the daemon or operator user linux account thats need them).
This is normally the case for all credential/secrets files deployed through the punch deployer.