From 04c23b257138ce140fcaf62e06f02825abe99655 Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 23 May 2018 10:47:59 -0700 Subject: [PATCH 1/6] [DOCS] Adds missing TLS settings for auditing --- x-pack/docs/en/settings/audit-settings.asciidoc | 6 +++++- x-pack/docs/en/settings/security-settings.asciidoc | 12 ++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/x-pack/docs/en/settings/audit-settings.asciidoc b/x-pack/docs/en/settings/audit-settings.asciidoc index 6274fae790b8c..2f1d293f008a3 100644 --- a/x-pack/docs/en/settings/audit-settings.asciidoc +++ b/x-pack/docs/en/settings/audit-settings.asciidoc @@ -130,7 +130,11 @@ Specifies the name of the remote cluster. `xpack.security.audit.index.client.xpack.security.user`:: Specifies the `username:password` pair that is used to authenticate with the -remote cluster. +remote cluster. This user must have authority to create the `.security-audit` +index on the remote cluster. + +If the remote {es} cluster has Transport Layer Security (TLS/SSL) enabled, you +must specify extra settings. See <>. You can pass additional settings to the remote client by specifying them in the `xpack.security.audit.index.client` namespace. For example, to allow the remote diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index 4e9d85f1900ae..d606c306b2fd9 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -1257,6 +1257,18 @@ transport profile, use the prefix `transport.profiles.$PROFILE.xpack.security.` append the portion of the setting after `xpack.security.transport.`. For the key setting, this would be `transport.profiles.$PROFILE.xpack.security.ssl.key`. +[[auditing-tls-ssl-settings]] +:ssl-prefix: xpack.security.audit.index.client.xpack +:component: Auditing +:client-auth-default!: +:server!: + +`xpack.security.audit.index.client.xpack.security.transport.ssl.enabled`:: +Used to enable or disable TLS/SSL for the transport client when you are +forwarding audit logs to a remote cluster. The default is `false`. + +include::ssl-settings.asciidoc[] + [float] [[ip-filtering-settings]] ==== IP filtering settings From c6e5b8dd0873f4af9f38fb6e3338acefabcc673f Mon Sep 17 00:00:00 2001 From: lcawl Date: Wed, 23 May 2018 11:59:11 -0700 Subject: [PATCH 2/6] [DOCS] Split off page about forwarding audit logs --- .../auditing/forwarding-logs.asciidoc | 26 ++++++++----------- .../docs/en/settings/audit-settings.asciidoc | 9 ++++++- .../en/settings/security-settings.asciidoc | 6 ++--- 3 files changed, 21 insertions(+), 20 deletions(-) diff --git a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc index 01ed0f72e746d..9d09ea3e65353 100644 --- a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc +++ b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc @@ -1,24 +1,20 @@ [role="xpack"] -[float] [[forwarding-audit-logfiles]] -==== Forwarding audit logs to a remote cluster +=== Forwarding audit logs to a remote cluster -To index audit events to a remote Elasticsearch cluster, you configure -the following `xpack.security.audit.index.client` settings: +When you are <>, you can optionally forward +the audit logs to a remote cluster. + +The logs are sent to the remote cluster by using the +{javaclient}/transport-client.html[transport client]. To establish the +connection from the transport client to the remote cluster, configure the following `xpack.security.audit.index.client` settings: * `xpack.security.audit.index.client.hosts` * `xpack.security.audit.index.client.cluster.name` * `xpack.security.audit.index.client.xpack.security.user` -For more information about these settings, see -{ref}/auditing-settings.html#remote-audit-settings[Remote Audit Log Indexing Configuration Settings]. - -You can pass additional settings to the remote client by specifying them in the -`xpack.security.audit.index.client` namespace. For example, to allow the remote -client to discover all of the nodes in the remote cluster you can specify the -`client.transport.sniff` setting: +NOTE: If the remote {es} cluster has Transport Layer Security (TLS/SSL) enabled, you +must specify extra settings. -[source,yaml] ----------------------------- -xpack.security.audit.index.client.transport.sniff: true ----------------------------- +For more information about these settings, see +{ref}/auditing-settings.html#remote-audit-settings[Remote audit log indexing configuration settings]. diff --git a/x-pack/docs/en/settings/audit-settings.asciidoc b/x-pack/docs/en/settings/audit-settings.asciidoc index 2f1d293f008a3..c1394151654b7 100644 --- a/x-pack/docs/en/settings/audit-settings.asciidoc +++ b/x-pack/docs/en/settings/audit-settings.asciidoc @@ -134,7 +134,14 @@ remote cluster. This user must have authority to create the `.security-audit` index on the remote cluster. If the remote {es} cluster has Transport Layer Security (TLS/SSL) enabled, you -must specify extra settings. See <>. +must set the following setting to `true`: + +`xpack.security.audit.index.client.xpack.security.transport.ssl.enabled`:: +Used to enable or disable TLS/SSL for the transport client that forwards audit +logs to the remote cluster. The default is `false`. + +You must also specify the information necessary to access certificates. See +<>. You can pass additional settings to the remote client by specifying them in the `xpack.security.audit.index.client` namespace. For example, to allow the remote diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index d606c306b2fd9..587cbb7941755 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -1263,12 +1263,10 @@ setting, this would be `transport.profiles.$PROFILE.xpack.security.ssl.key`. :client-auth-default!: :server!: -`xpack.security.audit.index.client.xpack.security.transport.ssl.enabled`:: -Used to enable or disable TLS/SSL for the transport client when you are -forwarding audit logs to a remote cluster. The default is `false`. - include::ssl-settings.asciidoc[] +See also <>. + [float] [[ip-filtering-settings]] ==== IP filtering settings From 1f133283d6eae68ff03ccca1aac8ab2f63e19a87 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 25 May 2018 16:20:55 -0700 Subject: [PATCH 3/6] [DOCS] Expanded instructions for forwarding audit logs --- .../auditing/forwarding-logs.asciidoc | 101 ++++++++++++++++-- .../docs/en/settings/audit-settings.asciidoc | 4 +- 2 files changed, 93 insertions(+), 12 deletions(-) diff --git a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc index 9d09ea3e65353..2c5281c360424 100644 --- a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc +++ b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc @@ -2,19 +2,98 @@ [[forwarding-audit-logfiles]] === Forwarding audit logs to a remote cluster -When you are <>, you can optionally forward -the audit logs to a remote cluster. +When you are auditing security events, you can optionally store the logs in an +{es} index on a remote cluster. The logs are sent to the remote cluster by +using the {javaclient}/transport-client.html[transport client]. -The logs are sent to the remote cluster by using the -{javaclient}/transport-client.html[transport client]. To establish the -connection from the transport client to the remote cluster, configure the following `xpack.security.audit.index.client` settings: +. Configure auditing such that the logs are stored in {es} rolling indices. +See <>. -* `xpack.security.audit.index.client.hosts` -* `xpack.security.audit.index.client.cluster.name` -* `xpack.security.audit.index.client.xpack.security.user` - -NOTE: If the remote {es} cluster has Transport Layer Security (TLS/SSL) enabled, you -must specify extra settings. +. Establish a connection to the remote cluster by configuring the following +`xpack.security.audit.index.client` settings: ++ +-- +[source, yaml] +-------------------------------------------------- +xpack.security.audit.index.client.hosts: 192.168.0.1, 192.168.0.2 <1> +xpack.security.audit.index.client.cluster.name: logging-prod <2> +xpack.security.audit.index.client.xpack.security.user: myuser:mypassword <3> +-------------------------------------------------- +<1> A list of hosts in the remote cluster. If you are not using the default +value for the `transport.tcp.port` setting on the remote cluster, you must +specify the appropriate port number (prefixed by a colon) after each host. +<2> The remote cluster name. +<3> A valid user and password, which must have authority to create the +`.security-audit` index on the remote cluster. +//TBD: Is there a secure version of this setting, so that password is hidden in the keystore? For more information about these settings, see {ref}/auditing-settings.html#remote-audit-settings[Remote audit log indexing configuration settings]. + +-- + +. If the remote cluster has Transport Layer Security (TLS/SSL) enabled, you +must specify extra security settings. + +.. {ref}/configuring-tls.html#node-certificates[Generate a node certificate]. + +.. Enable TLS and specify the information required to access the node certificate. + +*** If the signed certificate is in PKCS#12 format, add the following information +to the `elasticsearch.yml` file: ++ +-- +[source,yaml] +----------------------------------------------------------- +xpack.security.audit.index.client.xpack.security.transport.ssl.enabled: true +xpack.security.audit.index.client.xpack.ssl.keystore.path: certs/elastic-certificates.p12 +xpack.security.audit.index.client.xpack.ssl.truststore.path: certs/elastic-certificates.p12 +----------------------------------------------------------- + +For more information about these settings, see +{ref}/security-settings.html#auditing-tls-ssl-settings[Auditing TLS settings]. +-- + +*** If the certificate is in PEM format, add the following information to the +`elasticsearch.yml` file: ++ +-- +[source, yaml] +-------------------------------------------------- +xpack.security.audit.index.client.xpack.security.transport.ssl.enabled: true +xpack.security.audit.index.client.xpack.ssl.key: /home/es/config/node01.key +xpack.security.audit.index.client.xpack.ssl.certificate: /home/es/config/node01.crt +xpack.security.audit.index.client.xpack.ssl.certificate_authorities: [ "/home/es/config/ca.crt" ] +-------------------------------------------------- + +For more information about these settings, see +{ref}/security-settings.html#auditing-tls-ssl-settings[Auditing TLS settings]. +-- + +.. If you secured the certificate with a password, add the password to +your {es} keystore: + +*** If the signed certificate is in PKCS#12 format, use the following commands: ++ +-- +[source,shell] +----------------------------------------------------------- +bin/elasticsearch-keystore add xpack.security.audit.index.client.xpack.ssl.keystore.secure_password + +bin/elasticsearch-keystore add xpack.security.audit.index.client.xpack.ssl.truststore.secure_password +----------------------------------------------------------- +-- + +*** If the certificate is in PEM format, use the following commands: ++ +-- +[source,shell] +----------------------------------------------------------- +bin/elasticsearch-keystore add xpack.security.audit.index.client.xpack.ssl.secure_key_passphrase +----------------------------------------------------------- +-- + +//TBD: Is this required?: . Restart {es}. + +When these steps are complete, your audit logs are stored in {es} rolling +indices on the remote cluster. \ No newline at end of file diff --git a/x-pack/docs/en/settings/audit-settings.asciidoc b/x-pack/docs/en/settings/audit-settings.asciidoc index c1394151654b7..1e477083c903b 100644 --- a/x-pack/docs/en/settings/audit-settings.asciidoc +++ b/x-pack/docs/en/settings/audit-settings.asciidoc @@ -144,7 +144,9 @@ You must also specify the information necessary to access certificates. See <>. You can pass additional settings to the remote client by specifying them in the -`xpack.security.audit.index.client` namespace. For example, to allow the remote +`xpack.security.audit.index.client` namespace. For example, you can add +<> and +<> in that namespace. To allow the remote client to discover all of the nodes in the remote cluster you can specify the `client.transport.sniff` setting: From 613ba5eee6e5a336b0e1478a44f4181da33b9584 Mon Sep 17 00:00:00 2001 From: lcawl Date: Fri, 25 May 2018 16:52:38 -0700 Subject: [PATCH 4/6] [DOCS] Removed duplicate text from security settings --- x-pack/docs/en/settings/ssl-settings.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/x-pack/docs/en/settings/ssl-settings.asciidoc b/x-pack/docs/en/settings/ssl-settings.asciidoc index 655dfb74a6498..12729abf4abdc 100644 --- a/x-pack/docs/en/settings/ssl-settings.asciidoc +++ b/x-pack/docs/en/settings/ssl-settings.asciidoc @@ -46,7 +46,6 @@ Java Cryptography Architecture documentation]. Defaults to the value of The following settings are used to specify a private key, certificate, and the trusted certificates that should be used when communicating over an SSL/TLS connection. -If none of the settings below are specified, the {ref}/security-settings.html#ssl-tls-settings[Default TLS/SSL Settings] are used. ifdef::server[] A private key and certificate must be configured. endif::server[] From 01d10965755b1667e7db82d870ecd5936a77268f Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 28 May 2018 10:31:04 -0700 Subject: [PATCH 5/6] [DOCS] Addressed feedback --- x-pack/docs/en/security/auditing/forwarding-logs.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc index 2c5281c360424..e33154034af24 100644 --- a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc +++ b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc @@ -25,7 +25,6 @@ specify the appropriate port number (prefixed by a colon) after each host. <2> The remote cluster name. <3> A valid user and password, which must have authority to create the `.security-audit` index on the remote cluster. -//TBD: Is there a secure version of this setting, so that password is hidden in the keystore? For more information about these settings, see {ref}/auditing-settings.html#remote-audit-settings[Remote audit log indexing configuration settings]. @@ -33,9 +32,10 @@ For more information about these settings, see -- . If the remote cluster has Transport Layer Security (TLS/SSL) enabled, you -must specify extra security settings. +must specify extra security settings: -.. {ref}/configuring-tls.html#node-certificates[Generate a node certificate]. +.. {ref}/configuring-tls.html#node-certificates[Generate a node certificate on +the remote cluster], then copy that certificate to the client. .. Enable TLS and specify the information required to access the node certificate. @@ -93,7 +93,7 @@ bin/elasticsearch-keystore add xpack.security.audit.index.client.xpack.ssl.secur ----------------------------------------------------------- -- -//TBD: Is this required?: . Restart {es}. +. Restart {es}. When these steps are complete, your audit logs are stored in {es} rolling indices on the remote cluster. \ No newline at end of file From c2e73224b6fdefb8a5f978698877a58b186a4384 Mon Sep 17 00:00:00 2001 From: lcawl Date: Tue, 29 May 2018 08:14:36 -0700 Subject: [PATCH 6/6] [DOCS] Clarifies certificate names --- .../docs/en/security/auditing/forwarding-logs.asciidoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc index e33154034af24..0b79af593b6ea 100644 --- a/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc +++ b/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc @@ -46,8 +46,8 @@ to the `elasticsearch.yml` file: [source,yaml] ----------------------------------------------------------- xpack.security.audit.index.client.xpack.security.transport.ssl.enabled: true -xpack.security.audit.index.client.xpack.ssl.keystore.path: certs/elastic-certificates.p12 -xpack.security.audit.index.client.xpack.ssl.truststore.path: certs/elastic-certificates.p12 +xpack.security.audit.index.client.xpack.ssl.keystore.path: certs/remote-elastic-certificates.p12 +xpack.security.audit.index.client.xpack.ssl.truststore.path: certs/remote-elastic-certificates.p12 ----------------------------------------------------------- For more information about these settings, see @@ -61,9 +61,9 @@ For more information about these settings, see [source, yaml] -------------------------------------------------- xpack.security.audit.index.client.xpack.security.transport.ssl.enabled: true -xpack.security.audit.index.client.xpack.ssl.key: /home/es/config/node01.key -xpack.security.audit.index.client.xpack.ssl.certificate: /home/es/config/node01.crt -xpack.security.audit.index.client.xpack.ssl.certificate_authorities: [ "/home/es/config/ca.crt" ] +xpack.security.audit.index.client.xpack.ssl.key: /home/es/config/audit-client.key +xpack.security.audit.index.client.xpack.ssl.certificate: /home/es/config/audit-client.crt +xpack.security.audit.index.client.xpack.ssl.certificate_authorities: [ "/home/es/config/remote-ca.crt" ] -------------------------------------------------- For more information about these settings, see