Updating SSL documentation for clarity.

This commit is contained in:
WalkerWatch 2017-06-20 09:08:19 -04:00 committed by Joakim Erdfelt
parent 61904052f4
commit b81115dfbc
1 changed files with 23 additions and 35 deletions

View File

@ -363,10 +363,15 @@ An example of this setup:
[source, plain, subs="{sub-order}"] [source, plain, subs="{sub-order}"]
---- ----
$ cd /path/to/mybase $ cd /path/to/mybase
$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
$ java -jar /path/to/jetty-dist/start.jar --add-to-start=ssl $ java -jar /path/to/jetty-dist/start.jar --add-to-start=ssl
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini INFO : ssl initialized in ${jetty.base}/start.d/ssl.ini
INFO : Base directory was modified MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
INFO : Base directory was modified
$ tree $ tree
. .
├── etc ├── etc
@ -394,44 +399,30 @@ jetty.sslContext.keyStorePassword::
[[two-way-authentication]] [[two-way-authentication]]
==== Two Way Authentication ==== Two Way Authentication
To enable two-way authentication, you first need to activate the ssl module as shown in the previous section. To enable two-way authentication both the `ssl` and `https` modules need to be activated.
Once enabled, set the `jetty.sslContext.needClientAuth` property to `true`.
First you need load the `ssl` module and `https` module.
[source%nowrap,ini,linenums] [source%nowrap,ini,linenums]
.$JETTY_BASE/start.d/ssl.ini .$JETTY_BASE/start.d/ssl.ini
---- ----
# Module: ssl # Module: ssl
--module=ssl --module=ssl
...
jetty.ssl.host=0.0.0.0 ## whether client certificate authentication is required
jetty.ssl.port=8583
jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.trustStorePath=etc/keystore
jetty.sslContext.keyStorePassword=OBF:
jetty.sslContext.keyManagerPassword=OBF:
jetty.sslContext.trustStorePassword=OBF:
jetty.sslContext.trustStoreType=JKS
# enable two way authentication
jetty.sslContext.needClientAuth=true jetty.sslContext.needClientAuth=true
---- ...
[source%nowrap,ini,linenums]
.$JETTY_BASE/start.d/https.ini
----
# Module: https
--module=https
---- ----
[[layout-of-keystore-and-truststore]] [[layout-of-keystore-and-truststore]]
===== Layout of `keystore` and `truststore` ==== Layout of keystore and truststore
`keystore` only contains the server's private key and certificate. The server's private key and certificate are contained within the keystore.
[[img-certificate-chain]] [[img-certificate-chain]]
image::images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"] image::images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"]
[literal] [literal]
.The structure of KeyStore file .The structure of a KeyStore file
.... ....
├── PrivateKeyEntry ├── PrivateKeyEntry
│   ├── PrivateKey │   ├── PrivateKey
@ -447,11 +438,7 @@ image::images/certificate-chain.png[title="Certificate chain", alt="Certificate
[TIP] [TIP]
==== ====
└── PrivateKeyEntry + `PrivateKeyEntry`, `Certificate chain`, `Intermediary CA certificate` and `Root CA certificate` are all optional values.
   └── Certificate chain +
      ├── Intermediary CA certificate +
      └── Root CA certificate +
are optional
==== ====
[source%nowrap,plain,linenums] [source%nowrap,plain,linenums]
@ -709,9 +696,10 @@ KeyIdentifier [
******************************************* *******************************************
---- ----
In addition, you can split `$JETTY/etc/keystore` as two files. Additionally, you can split `$JETTY/etc/keystore` into two files.
One is `$JETTY/etc/keystore` which only contains the servers private key and certificate, One being `$JETTY/etc/keystore` which only contains the servers private key and certificate, while the other would be `$JETTY/etc/truststore` which contains intermediary CA and root CA.
the other is `$JETTY/etc/truststore` which contains intermediary CA and root CA.
An example of this would look like the following:
[literal] [literal]
.The structure of `$JETTY/etc/keystore` .The structure of `$JETTY/etc/keystore`
@ -759,7 +747,7 @@ setKeyStorePath::
The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client). The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client).
____ ____
[NOTE] [NOTE]
As a keystore is vital security information, it can be desirable to locate the file in a directory with *very* restricted access. As the keystore is vital security information, it recommended the file is located in a directory with *very* restricted access.
____ ____
setKeyStorePassword:: setKeyStorePassword::
@ -784,7 +772,7 @@ ____
____ ____
[CAUTION] [CAUTION]
The keystore and truststore passwords may also be set using the system properties: `org.eclipse.jetty.ssl.keypassword` `org.eclipse.jetty.ssl.password`. The keystore and truststore passwords may also be set using the system properties: `org.eclipse.jetty.ssl.keypassword` and `org.eclipse.jetty.ssl.password`.
This is _not_ a recommended usage. This is _not_ a recommended usage.
____ ____