[docs] Add and improve SSL/TLS documentation

docs/configuring.asciidoc

@@ -25,7 +25,13 @@ include::./copied-from-beats/outputconfig.asciidoc[]
 
 include::./configuring-ingest.asciidoc[]
 
-include::./copied-from-beats/shared-ssl-config.asciidoc[]
+[[configuration-ssl-landing]]
+== SSL/TLS settings
+
+SSL/TLS is available for both APM Agent to APM Server communication,
+and APM Server communication with any output that supports SSL, like {es}, {ls}, or Kafka.
+
+See <<securing-apm-server,Securing APM Server>> for more information.
 
 include::./template-config.asciidoc[]
 

docs/copied-from-beats/shared-securing-beat.asciidoc

@@ -8,10 +8,17 @@ The following topics provide information about securing the {beatname_uc}
 process and securing communication between {beatname_uc} and other products in
 the Elastic stack:
 
+ifdef::apm-server[]
+* <<secure-communication-agents>>
+endif::[]
 * <<securing-communication-elasticsearch>>
 ifndef::only-elasticsearch[]
 * <<configuring-ssl-logstash>>
 endif::only-elasticsearch[]
+ifdef::apm-server[]
+* <<configuration-ssl>>
+* <<agent-server-ssl>>
+endif::[]
 * <<securing-beats>>
 ifndef::only-elasticsearch[]
 * <<linux-seccomp>>
@@ -21,10 +28,14 @@ ifdef::beat-specific-security[]
 include::{beat-specific-security}[]
 endif::[]
 
-//sets block macro for https.asciidoc included in next section
-
 --
 
+ifdef::apm-server[]
+include::../secure-communication-agents.asciidoc[]
+endif::[]
+
+//sets block macro for https.asciidoc included in next section
+
 [[securing-communication-elasticsearch]]
 == Secure communication with Elasticsearch
 
@@ -39,6 +50,11 @@ ifndef::only-elasticsearch[]
 include::./shared-ssl-logstash-config.asciidoc[]
 endif::only-elasticsearch[]
 
+ifdef::apm-server[]
+include::shared-ssl-config.asciidoc[]
+include::../ssl-input-settings.asciidoc[]
+endif::[]
+
 include::./security/securing-beats.asciidoc[]
 
 ifndef::only-elasticsearch[]

docs/copied-from-beats/shared-ssl-config.asciidoc

@@ -1,18 +1,28 @@
 [[configuration-ssl]]
+ifndef::apm-server[]
 == Specify SSL settings
+endif::apm-server[]
+ifdef::apm-server[]
+== SSL output settings
 
+NOTE: This page explains SSL settings for {beatname_uc} *outputs*.
+See <<agent-server-ssl>> for information on SSL settings for {beatname_uc} *inputs*.
+
+You can specify SSL options with any output that supports SSL, like {es}, {ls}, or Kafka.
+endif::[]
+
+ifndef::apm-server[]
 You can specify SSL options when you configure:
 
 * <<configuring-output,outputs>> that support SSL
-ifeval::["{beatname_lc}"!="apm-server"]
 * the <<setup-kibana-endpoint,Kibana endpoint>>
-endif::[]
 ifeval::["{beatname_lc}"=="heartbeat"]
 * <<configuration-heartbeat-options,{beatname_uc} monitors>> that support SSL
 endif::[]
 ifeval::["{beatname_lc}"=="metricbeat"]
 * <<metricbeat-modules,modules>> that define the host as an HTTP URL
 endif::[]
+endif::[]
 
 Example output config with SSL enabled:
 

docs/copied-from-beats/shared-ssl-logstash-config.asciidoc

@@ -126,7 +126,7 @@ curl: (51) SSL: certificate verification failed (result: 5)
 See the <<ssl-client-fails,troubleshooting docs>> for info about resolving this issue.
 
 [float]
-=== Test the Beats to Logstash connection
+=== Test the {beatname_uc} to Logstash connection
 
 If you have {beatname_uc} running as a service, first stop the service. Then test your setup by running {beatname_uc} in
 the foreground so you can quickly see any errors that occur:

docs/secure-communication-agents.asciidoc

@@ -0,0 +1,88 @@
+[[secure-communication-agents]]
+== Secure communication with APM Agents
+
+To secure the communication between APM Agents and the APM Server:
+
+. <<secret-token,Set a secret token in your Agents and Server>>
+. <<ssl-setup,Enable SSL/TLS from APM Server>>
+. <<https-in-agents,Enable HTTPS from your APM Agents>>
+
+[[secret-token]]
+[float]
+=== Secret token
+
+You can configure a secret token to authorize requests to the APM Server.
+This ensures that only your agents are able to send data to your APM servers.
+Both the agents and the APM servers have to be configured with the same secret token.
+In addition, secret tokens only provide security when used in combination with SSL/TLS.
+
+**APM Server configuration**
+
+Here's how you set the secret token in APM Server:
+
+[source,yaml]
+----
+apm-server.secret_token: <secret-token>
+----
+
+We recommend saving the token in the APM Server <<keystore>>.
+
+IMPORTANT: Secret tokens are not applicable for the RUM Agent,
+as there is no way to prevent them from being publicly exposed.
+
+**Agent specific configuration**
+
+* *Go Agent*: {apm-go-ref}/configuration.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`]
+* *Java Agent*: {apm-java-ref}/config-reporter.html#config-secret-token[`secret_token`]
+* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-secret-token[`ELASTIC_APM_SECRET_TOKEN`]
+* *Node.js Agent*: {apm-node-ref}/configuration.html#secret-token[`Secret Token`]
+* *Python Agent*: {apm-py-ref}/configuration.html#config-secret-token[`secret_token`]
+* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-secret-token[`secret_token`]
+
+[[ssl-setup]]
+[float]
+=== SSL/TLS communication from APM Server
+
+To enable SSL/TLS, you need both a private key, and a certificate issued by a certification authority (CA).
+You can then specify the path to those files in your configuration properties:
+`apm-server.ssl.key` and `apm-server.ssl.certificate` respectively.
+This will make APM Server serve HTTPS requests instead of HTTP.
+
+Example of a basic output config with secure communication enabled:
+
+[source,yaml]
+----
+apm-server.ssl.key: "/etc/pki/key.pem"
+apm-server.ssl.certificate: "/etc/pki/client.pem"
+output.elasticsearch.ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
+----
+
+A full list of configuration options is available below in <<agent-server-ssl>>.
+
+[[https-in-agents]]
+[float]
+=== HTTPS communication from APM Agents
+
+To enable secure communication in your Agents, you simply need to update the configured server URL to use HTTPS instead of HTTP.
+
+* *Go Agent*: {apm-go-ref}/configuration.html#config-server-url[`ELASTIC_APM_SERVER_URL`]
+* *Java Agent*: {apm-java-ref}/config-reporter.html#config-server-urls[`server_urls`]
+* *.NET Agent*: {apm-dotnet-ref}/config-reporter.html#config-server-urls[`ServerUrls`]
+* *Node.js Agent*: {apm-node-ref}/configuration.html#server-url[`serverUrl`]
+* *Python Agent*: {apm-py-ref}/[`server_url`]
+* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-server-url[`server_url`]
+
+Some Agents also allow you to specify a custom certificate authority for connecting to APM Server.
+This allows you to enable both encryption and verify that you are sending data to the correct APM Server.
+
+* *Go Agent*: {apm-go-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`]
+// * *.NET Agent*: {apm-dotnet-ref}/
+* *Python Agent*: {apm-py-ref}/configuration.html#config-server-cert[`ELASTIC_APM_SERVER_CERT`]
+* *Ruby Agent*: {apm-ruby-ref}/configuration.html#config-ssl-ca-cert[`server_ca_certedit`]
+
+Agents that don't allow you specify a custom certificate will allow you to
+disable verification of the SSL certificate.
+This ensures encryption, but does not verify that you are sending data to the correct APM Server.
+
+* *Java Agent*: {apm-java-ref}/config-reporter.html#config-verify-server-cert[`verify_server_cert`]
+* *Node.js Agent*: {apm-node-ref}/configuration.html#validate-server-cert[`verifyServerCert`]

docs/security.asciidoc

@@ -1,30 +1,7 @@
-[[security-overview]]
 [float]
-=== Security Overview
+[[security-overview]]
+== Security Overview
 
-APM Server exposes an HTTP endpoint and as with anything that opens ports on your servers,
+APM Server exposes an HTTP endpoint, and as with anything that opens ports on your servers,
 you should be careful about who can connect to it.
 Firewall rules are recommended to ensure only authorized systems can connect.
-
-[[secret-token]]
-[float]
-==== Secret token
-
-You can configure a secret token to authorize requests to the APM Server,
-and ensure that only your agents can send data to your APM servers.
-Both the agents and the APM servers have to be configured with the same secret token.
-
-NOTE: Secret tokens provide security only when used in combination with SSL/TLS.
-Secret tokens are not applicable for RUM, as they would be publicly exposed.
-
-[[ssl-setup]]
-[float]
-==== SSL/TLS setup
-
-To enable SSL/TLS you need a private key and a certificate issued by a certification authority (CA).
-You can then specify the path to those files in your configuration properties:
-`apm-server.ssl.key` and `apm-server.ssl.certificate` respectively.
-This will make the APM Server serve HTTPS requests instead of HTTP.
-Don't forget, you also need to enable SSL in the agent.
-For agent specific details on enabling SSL/TLS,
-please see the {apm-agents-ref}/index.html[agent documentation].

docs/ssl-input-settings.asciidoc

@@ -0,0 +1,79 @@
+[[agent-server-ssl]]
+== SSL input settings
+
+NOTE: This page explains SSL settings for {beatname_uc} *inputs*.
+See <<configuration-ssl>> for information on SSL settings for {beatname_uc} *outputs*.
+
+You can specify the following options in the `apm-server.ssl` section of the +{beatname_lc}.yml+ config file.
+They apply to SSL/TLS communication between the APM Server and APM Agents.
+
+[float]
+==== `enabled`
+
+The `enabled` setting can be used to enable the ssl configuration by setting
+it to `true`. The default value is `false`.
+
+[float]
+==== `certificate_authorities`
+
+The list of root certificates for verifying client certificates.
+If `certificate_authorities` is empty or not set, the trusted certificate authorities of the host system are used.
+Required if `apm-server.enabled` is `true`.
+
+[float]
+==== `certificate`
+
+The path to the file containing the certificate for Server authentication.
+Required if `apm-server.enabled` is `true`.
+
+[float]
+==== `key`
+
+The path to the file containing the Server certificate key.
+Required if `apm-server.enabled` is `true`.
+
+[float]
+==== `key_passphrase`
+
+The passphrase used to decrypt an encrypted key stored in the configured `key` file.
+We recommend saving the `key_passphrase` in the APM Server <<keystore>>.
+
+[float]
+==== `supported_protocols`
+
+This setting is a list of allowed protocol versions:
+`SSLv3`, `TLSv1.0`, `TLSv1.1` and `TLSv1.2`. We do not recommend using `SSLv3` or `TLSv1.0`.
+The default value is `[TLSv1.1, TLSv1.2]`.
+
+[float]
+==== `cipher_suites`
+
+The list of cipher suites to use. The first entry has the highest priority.
+If this option is omitted, the Go crypto library's default
+suites are used (recommended).
+
+[float]
+==== `curve_types`
+
+The list of curve types for ECDHE (Elliptic Curve Diffie-Hellman ephemeral key exchange).
+
+[float]
+==== `client_authentication`
+
+This configures what types of client authentication are supported. The valid options
+are `none`, `optional`, and `required`. The default is `optional`.
+If `certificate_authorities` has been specified, this setting will automatically change to `required`.
+
+* `none` - Disables client authentication.
+* `optional` - When a client certificate is given, the server will verify it.
+* `required` - Requires clients to provide a valid certificate.
+
+[float]
+==== `verification_mode`
+
+This option controls whether the client verifies server certificates and host
+names. Valid values are `none` and `full`. If `none` is used,
+SSL-based connections are susceptible to man-in-the-middle attacks. Use this
+option for testing only.
+
+The default is `full`.