[docs] Add and improve SSL/TLS documentation

docs/configuring.asciidoc

@@ -8,7 +8,7 @@ include::./copied-from-beats/shared-configuring.asciidoc[]
 * <<configuration-process>>
 * <<configuring-output>>
 * <<configuring-ingest-node>>
-* <<configuration-ssl>>
+* <<configuration-ssl-landing>>
 * <<configuration-template>>
 * <<ilm>>
 * <<configuration-logging>>
@@ -25,7 +25,28 @@ include::./copied-from-beats/outputconfig.asciidoc[]
 
 include::./configuring-ingest.asciidoc[]
 
+[[configuration-ssl-landing]]
+== SSL/TLS settings
+
+SSL/TLS is available for:
+
+* <<agent-server-ssl,APM Server **inputs**>> (APM Agents)
+* <<configuration-ssl,APM Server **outputs**>> that support SSL, like {es}, {ls}, or Kafka.
+
+Additional information on getting started with SSL/TLS is available in <<securing-apm-server>>.
+
+// The leveloffset attribute pushes all headings in the included document down by
+// the specified number of levels. It is required here because the shared Beats
+// documentation was created as a level 1 heading. In the APM book, this level
+// would break the DTD. Using leveloffset +1, we can include this file here.
+// It's important too reset the level heading after including the file.
+:leveloffset: +1
 include::./copied-from-beats/shared-ssl-config.asciidoc[]
+:leveloffset: -1
+
+include::ssl-input-settings.asciidoc[]
+
+See <<securing-apm-server,Securing APM Server>> for more information.
 
 include::./template-config.asciidoc[]
 

docs/copied-from-beats/https.asciidoc

@@ -41,7 +41,7 @@ this document.
 By default {beatname_uc} uses the list of trusted certificate authorities from the
 operating system where {beatname_uc} is running. You can configure {beatname_uc} to use a specific list of
 CA certificates instead of the list from the OS. You can also configure it to use client authentication
-by specifying the certificate and key to use when the server requires the Beat to authenticate. Here is an example
+by specifying the certificate and key to use when the server requires the {beatname_uc} to authenticate. Here is an example
 configuration:
 
 ["source","yaml",subs="attributes,callouts"]

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

@@ -8,6 +8,9 @@ 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>>
@@ -21,10 +24,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
 
@@ -34,7 +41,7 @@ include::./https.asciidoc[]
 
 ifndef::only-elasticsearch[]
 [[configuring-ssl-logstash]]
-== Secure communication with Logstash by using SSL
+== Secure communication with Logstash
 
 include::./shared-ssl-logstash-config.asciidoc[]
 endif::only-elasticsearch[]

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

@@ -1,18 +1,25 @@
 [[configuration-ssl]]
+ifndef::apm-server[]
 == Specify SSL settings
+endif::apm-server[]
+ifdef::apm-server[]
+== SSL output settings
 
+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,89 @@
+[[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 in APM Server>>
+. <<https-in-agents,Enable HTTPS in 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,
+and 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**
+
+Each Agent has a configuration for setting the value of the secret token:
+
+* *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 in APM Server
+
+To enable SSL/TLS, you need to enable SSL and provide both a private key and a certificate
+issued by a certificate authority (CA).
+You can then specify the path to those files in your configuration properties.
+This will make APM Server serve HTTPS requests instead of HTTP.
+
+Here's a basic APM Server SSL config with secure communication enabled:
+
+[source,yaml]
+----
+apm-server.ssl.enabled: true
+apm-server.ssl.key: "/etc/pki/key.pem"
+apm-server.ssl.certificate: "/etc/pki/client.pem"
+----
+
+A full list of configuration options is available in <<agent-server-ssl>>.
+
+[[https-in-agents]]
+[float]
+=== HTTPS communication in APM Agents
+
+To enable secure communication in your Agents, you 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.
+
+* *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`]
+
+Most 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,9 @@
-[[security-overview]]
+A reference of all available <<configuration-ssl-landing,SSL configuration settings>> is also available.
+
 [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,75 @@
+[[agent-server-ssl]]
+=== SSL input settings
+
+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`
+
+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]
+==== `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.
+
+[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`.