[DOCS] Adds common definitions for security settings #51017
Conversation
lcawl
added
>docs
|
Pinging @elastic/es-docs (>docs) |
|
Pinging @elastic/es-security (:Security/Network) |
|
@elasticmachine update branch |
|
user doesn't have permission to update head repository |
|
@elasticmachine update branch |
|
user doesn't have permission to update head repository |
| tag::ssl-certificate[] | ||
| Specifies the path for the PEM encoded certificate (or certificate chain) that is | ||
| associated with the key. | ||
| //TBD: This setting can be used only if `ssl.key` is set. |
There was a problem hiding this comment.
What's the situation with these //TBD parts? Are you looking for a review as to whether that content is correct, or trying to decide how to represent them in the docs?
There was a problem hiding this comment.
@tvernum Sorry for the lack of clarity. These "TBD" pieces are bits of information that only existed in a subset of the places where these definitions were used. For now, I've left them as-is and the TBD is to move that info into the shared definition if indeed they're applicable to all contexts (likely in a subsequent PR).
| `TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`, | ||
| `TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`. | ||
| end::ssl-cipher-suites-values[] | ||
| //TBD: Are these two different definitions (with different Oracle URLs) for cipher_suites required? |
There was a problem hiding this comment.
On master, no because we don't support Java 8 any more.
On 7.x, I think so. The set of options (and defaults) are different depend in the Java version.
Although, strictly speaking we have different values between Java11 and Java12 as well (since #42155) so we may need to think this through a bit more.
@jkakavas What do we want to do with FIPS here? BC JSSE doesn't support TLS1.3, so some of these ciphers aren't supported, but I think technically the default is still correct (we don't change the default cipher suite list based on the supported protocols list).
There was a problem hiding this comment.
Yes the default is still that one so I agree we shouldn't add anything here (We could add something in the FIPS docs though, but this is part of the effort to make FIPS docs better ).
The actual list of unusable ones while running with fips mode ( we do print this in the logs on startup too)
JDK11:
TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
JDK13:
TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_CHACHA20_POLY1305_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_GCM_SHA256
There was a problem hiding this comment.
The set of options (and defaults) are different depend in the Java version. Although, strictly speaking we have different values between Java11 and Java12 as well (since #42155) so we may need to think this through a bit more.
@tvernum For now I have (1) deleted the "ssl-cipher-suites-values-java8" definition, (2) moved the Java11 info into a "ssl-cipher-suites-values-java11" definition, (3) put a Java12 URL in the "ssl-cipher-suites-values" definition and added the three ChaCha20 ciphers, (4) updated all occurrences of *-values-java8 and *-values-java11 to use the generic *-values. I'm just keeping the *-java11 for now in case we backport this PR.
There was a problem hiding this comment.
Thanks @lcawl that sounds right to me.
| Path to a PEM encoded file containing the private key. | ||
| //TBD: You cannot use this setting and `ssl.keystore.path` at the same time. | ||
| end::ssl-key-pem[] | ||
| //TBD: Is it correct that this setting only applies to PEM files or can it support other types? |
There was a problem hiding this comment.
It only applies to PEM files, but crypto file formats are a complex topic.
The PEM encoding format supports a variety of different key type and formats, so it's possible to have a EC private key in PKCS8 format inside a PEM file.
We don't want to go into that detail here, but "PEM" is a lot less specific than it sounds.
|
|
||
| -- | ||
| end::ssl-supported-protocols[] | ||
| //TBD: Are these three different definitions for supported protocols valid? |
There was a problem hiding this comment.
No, I don't think there's a reason to have all 3 variants. The main (first) one should be accurate everywhere.
| end::ssl-truststore-path[] | ||
|
|
||
| tag::ssl-truststore-path-jks[] | ||
| The path for the Java keystore file that contains the certificates to trust. |
There was a problem hiding this comment.
I don't think we need this. If it's used somewhere it's probably out of date.
There was a problem hiding this comment.
It's used in the ssl.truststore.path in http://elasticsearch_51017.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-settings.html and the {ssl-prefix-ssl}.truststore.path in http://elasticsearch_51017.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/notification-settings.html and http://elasticsearch_51017.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/monitoring-settings.html
I'll switch those occurrence to using the "ssl-truststore-path" shared definition instead.
| The format of the keystore file. It must be either `jks` or `PKCS12`. If the | ||
| keystore path ends in ".p12", ".pfx", or "pkcs12", this setting defaults | ||
| to `PKCS12`. Otherwise, it defaults to `jks`. | ||
| end::ssl-keystore-type-pkcs12[] |
There was a problem hiding this comment.
I think we probably want to merge the pkcs11 and pkcs12 variants. I don't believe there is any context in which the beahviour of this setting is different.
There was a problem hiding this comment.
@tvernum Does that mean we should get rid of this section altogether?: http://elasticsearch_51017.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-settings.html#security-http-pkcs11-tokens
There was a problem hiding this comment.
I'll admit my PKCS#11 knowledge is pretty thin - maybe @jkakavas can chime in here, but ...
No, we still want that section, I think (but am not 100% sure) that our PKCS#11 support is consistent across all SSL contexts, so anything we say for xpack.security.http.ssl.keystore.type could technically be said about monitoring ssl, etc.
However, there is a limit of having only 1 PKCS#11 provider per JVM, so setting this up & describing it is pretty complex. Maybe we leave this for now so we can merge it, and then come back to it. I think we'd need to setup a PKCS#11 environment for testing, and I don't have cycles for that right now.
There was a problem hiding this comment.
Tim's comment is right. PKCS#11 support is consistent across all SSL contexts, but there can only be 1 PKCS#11 provider/keystore and we don't offer a way to configure which alias in a keystore will be used. So that means that of PKCS#11 is used, then there is a single key/certificate pair that needs to be shared across all SSL contexts ( more details are shared in #33459 ) . I agree we can handle adding a few more details in PKCS11 in another PR
Co-Authored-By: Tim Vernum <[email protected]>
Co-Authored-By: Tim Vernum <[email protected]>
Co-Authored-By: Tim Vernum <[email protected]>
Co-Authored-By: Tim Vernum <[email protected]>
…53242) Co-Authored-By: Tim Vernum <[email protected]>
…53245) Co-Authored-By: Tim Vernum <[email protected]>
Related to #50984
There are currently similar SSL/TLS settings for monitoring, alerting, and security features (e.g. listed in https://www.elastic.co/guide/en/elasticsearch/reference/master/security-settings.html#http-tls-ssl-settings, https://www.elastic.co/guide/en/elasticsearch/reference/master/monitoring-settings.html#ssl-monitoring-settings, and https://www.elastic.co/guide/en/elasticsearch/reference/master/notification-settings.html#ssl-notification-settings). Some of them are generated from a shared file https://github.com/elastic/elasticsearch/blob/master/docs/reference/settings/ssl-settings.asciidoc.
There are discrepancies in how some of the settings are defined, however, and whether their default values are listed.
This PR attempts to address those problems as follows:
I have left in some clauses where there are slight variations in the definitions for now (e.g. setting X says it cannot be used at the same time as setting Y). I think for the most part those should ultimately go away (i.e. they're likely applicable to all occurrences of that setting, not just one or two).
Preview: