Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Adds common definitions for security settings #51017

Merged
merged 10 commits into from
Mar 6, 2020
Merged

[DOCS] Adds common definitions for security settings #51017

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
188f54f
[DOCS] Adds common definitions for security settings
lcawl Jan 15, 2020
5371cfa
[DOCS] More SSL setting edits
lcawl Jan 15, 2020
dfe1e57
[DOCS] More edits
lcawl Jan 15, 2020
0313977
Update docs/reference/settings/common-defs.asciidoc
lcawl Feb 21, 2020
b78d1bd
[DOCS] Removes shared ssl-truststore-path-jks definition
lcawl Feb 21, 2020
6cee48c
[DOCS] Removes extra definitions for ssl-supported-protocols
lcawl Feb 21, 2020
e9fb6b2
[DOCS] Removes ssl-keystore-type-pkcs11 shared definition
lcawl Feb 21, 2020
9f16dc2
[DOCS] Adds Java12 cipher suites values
lcawl Mar 4, 2020
a910984
[DOCS] Removes Java8 cipher suites
lcawl Mar 4, 2020
f1587aa
Update docs/reference/settings/common-defs.asciidoc
lcawl Mar 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 150 additions & 0 deletions docs/reference/settings/common-defs.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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).

end::ssl-certificate[]

tag::ssl-certificate-authorities[]
List of paths to PEM encoded certificate files that should be trusted.
//TBD: You cannot use this setting and `ssl.truststore.path` at the same time.
end::ssl-certificate-authorities[]

tag::ssl-cipher-suites-values[]
Supported cipher suites vary depending on which version of Java you use. For
example, for version 12 the default value is `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_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`,
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`,
`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`,
`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`,
`TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`,
`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`.
For more information, see Oracle's
https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2[Java Cryptography Architecture documentation].
end::ssl-cipher-suites-values[]

tag::ssl-cipher-suites-values-java11[]
Supported cipher suites vary depending on which version of Java you use. For
example, for version 11 the default value is `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_ECDSA_WITH_AES_256_CBC_SHA384`,
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`,
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`,
`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`,
`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`,
`TLS_RSA_WITH_AES_128_GCM_SHA256`, `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`. For more information, see Oracle's
https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2[Java Cryptography Architecture documentation].
end::ssl-cipher-suites-values-java11[]

tag::ssl-key-pem[]
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[]

tag::ssl-key-passphrase[]
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
//TBD: You cannot use this setting and `ssl.secure_key_passphrase` at the same time.
end::ssl-key-passphrase[]

tag::ssl-keystore-key-password[]
The password for the key in the keystore. The default is the keystore password.
//TBD: You cannot use this setting and `ssl.keystore.secure_key_password` at the same time.
end::ssl-keystore-key-password[]

tag::ssl-keystore-password[]
The password for the keystore.
//TBD: You cannot use this setting and `ssl.keystore.secure_password` at the same time.
end::ssl-keystore-password[]

tag::ssl-keystore-path[]
The path for the keystore file that contains a private key and certificate.
//TBD: It must be either a Java keystore (jks) or a PKCS#12 file.
//TBD: You cannot use this setting and `ssl.key` at the same time.
end::ssl-keystore-path[]

tag::ssl-keystore-secure-key-password[]
The password for the key in the keystore. The default is the keystore password.
//TBD: You cannot use this setting and `ssl.keystore.key_password` at the same time.
end::ssl-keystore-secure-key-password[]

tag::ssl-keystore-secure-password[]
The password for the keystore.
//TBD: You cannot use this setting and `ssl.keystore.password` at the same time.
end::ssl-keystore-secure-password[]

tag::ssl-keystore-type-pkcs12[]
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[]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

Copy link
Contributor

@tvernum tvernum Mar 4, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


tag::ssl-secure-key-passphrase[]
The passphrase that is used to decrypt the private key. Since the key might not
be encrypted, this value is optional.
//TBD: You cannot use this setting and `ssl.key_passphrase` at the same time.
end::ssl-secure-key-passphrase[]

tag::ssl-supported-protocols[]
Supported protocols with versions. Valid protocols: `SSLv2Hello`,
`SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM's SSL provider supports TLSv1.3,
the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is
`TLSv1.2,TLSv1.1`.
+
--
NOTE: If `xpack.security.fips_mode.enabled` is `true`, you cannot use `SSLv2Hello`
or `SSLv3`. See <<fips-140-compliance>>.

--
end::ssl-supported-protocols[]

tag::ssl-truststore-password[]
The password for the truststore.
//TBD: You cannot use this setting and `ssl.truststore.secure_password` at the same time.
end::ssl-truststore-password[]

tag::ssl-truststore-path[]
The path for the keystore that contains the certificates to trust. It must be
either a Java keystore (jks) or a PKCS#12 file.
//TBD: You cannot use this setting and `ssl.certificate_authorities` at the same time.
end::ssl-truststore-path[]

tag::ssl-truststore-secure-password[]
Password for the truststore.
//TBD: You cannot use this setting and `ssl.truststore.password` at the same time.
end::ssl-truststore-secure-password[]

tag::ssl-truststore-type[]
The format of the truststore file. It must be either `jks` or `PKCS12`. If the
file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`.
Otherwise, it defaults to `jks`.
end::ssl-truststore-type[]

tag::ssl-truststore-type-pkcs11[]
The format of the truststore file. For the Java keystore format, use `jks`. For
PKCS#12 files, use `PKCS12`. For a PKCS#11 token, use `PKCS11`. The default is
`jks`.
end::ssl-truststore-type-pkcs11[]

tag::ssl-verification-mode-values[]
Valid values are:
- `full`, which verifies that the provided certificate is signed by a trusted
authority (CA) and also verifies that the server's hostname (or IP address)
matches the names identified within the certificate.
- `certificate`, which verifies that the provided certificate is signed by a
trusted authority (CA), but does not perform any hostname verification.
- `none`, which performs _no verification_ of the server's certificate. This
mode disables many of the security benefits of SSL/TLS and should only be used
after very careful consideration. It is primarily intended as a temporary
diagnostic mechanism when attempting to resolve TLS errors; its use on
production clusters is strongly discouraged.
+
The default value is `full`.
end::ssl-verification-mode-values[]
Loading