TINKERPOP-2023 updated docs with creating self-signed cert, incorrect ssl configuration will prevent server from starting removed OPTIONAL from needClientAuth
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/b77c0c7b Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/b77c0c7b Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/b77c0c7b Branch: refs/heads/tp33 Commit: b77c0c7b55866bbbddd8d721142118b53fcfe154 Parents: bbc0265 Author: Robert Dale <robd...@gmail.com> Authored: Fri Aug 17 17:35:41 2018 -0400 Committer: Robert Dale <robd...@gmail.com> Committed: Fri Aug 17 17:35:41 2018 -0400 ---------------------------------------------------------------------- .../src/reference/gremlin-applications.asciidoc | 59 ++++++++++++++++---- .../gremlin/server/AbstractChannelizer.java | 16 ++++-- 2 files changed, 60 insertions(+), 15 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/b77c0c7b/docs/src/reference/gremlin-applications.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc index 8372a8a..1cd9964 100644 --- a/docs/src/reference/gremlin-applications.asciidoc +++ b/docs/src/reference/gremlin-applications.asciidoc @@ -1155,10 +1155,10 @@ The following table describes the various configuration options that Gremlin Ser |ssl.keyStore |The private key in JKS or PKCS#12 format. |_none_ |ssl.keyStorePassword |The password of the `keyStore` if it is password-protected. |_none_ |ssl.keyStoreType |`JKS` (Java 8 default) or `PKCS12` (Java 9+ default) |_none_ -|ssl.needClientAuth | Optional. One of NONE, OPTIONAL, REQUIRE. Enables client certificate authentication at the enforcement level specified. Can be used in combination with Authenticator. |_none_ +|ssl.needClientAuth | Optional. One of NONE, REQUIRE. Enables client certificate authentication at the enforcement level specified. Can be used in combination with Authenticator. |_none_ |ssl.sslCipherSuites |The list of JSSE ciphers to support for SSL connections. If specified, only the ciphers that are listed and supported will be enabled. If not specified, the JVM default is used. |_none_ |ssl.sslEnabledProtocols |The list of SSL protocols to support for SSL connections. If specified, only the protocols that are listed and supported will be enabled. If not specified, the JVM default is used. |_none_ -|ssl.trustStore |Required when needClientAuth is OPTIONAL or REQUIRE. Trusted certificates for verifying the remote endpoint's certificate. If this value is not provided and SSL is enabled, the default `TrustManager` will be used. |_none_ +|ssl.trustStore |Required when needClientAuth is REQUIRE. Trusted certificates for verifying the remote endpoint's certificate. If this value is not provided and SSL is enabled, the default `TrustManager` will be used. |_none_ |ssl.trustStorePassword |The password of the `trustStore` if it is password-protected |_none_ |strictTransactionManagement |Set to `true` to require `aliases` to be submitted on every requests, where the `aliases` become the scope of transaction management. |false |threadPoolBoss |The number of threads available to Gremlin Server for accepting connections. Should always be set to `1`. |1 @@ -1249,7 +1249,47 @@ authentication: { ===== Quick Start A quick way to get started with the `SimpleAuthenticator` is to use TinkerGraph for the "credentials graph" and the -"sample" credential graph that is packaged with the server. +"sample" credential graph that is packaged with the server. To secure the transport for the credentials, +SSL should be enabled. For this Quick Start, a self-signed certificate will be created but this should not +be used in a production environment. + +Generate the self-signed SSL certificate: + +[source,text] +---- +$ keytool -genkey -alias localhost -keyalg RSA -keystore server.jks +Enter keystore password: +Re-enter new password: +What is your first and last name? + [Unknown]: localhost +What is the name of your organizational unit? + [Unknown]: +What is the name of your organization? + [Unknown]: +What is the name of your City or Locality? + [Unknown]: +What is the name of your State or Province? + [Unknown]: +What is the two-letter country code for this unit? + [Unknown]: +Is CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? + [no]: yes + +Enter key password for <localhost> + (RETURN if same as keystore password): +---- + +Next, uncomment the `keyStore` and `keyStorePassword` lines in `conf/gremlin-server-secure.yaml`. + +[source,yaml] +---- +ssl: { + enabled: true, + sslEnabledProtocols: [TLSv1.2], + keyStore: server.jks, + keyStorePassword: changeit +} +---- [source,text] ---- @@ -1261,7 +1301,6 @@ $ bin/gremlin-server.sh conf/gremlin-server-secure.yaml [INFO] GremlinServer - Configuring Gremlin Server from conf/gremlin-server-secure.yaml ... -[WARN] AbstractChannelizer - Enabling SSL with self-signed certificate (NOT SUITABLE FOR PRODUCTION) [INFO] AbstractChannelizer - SSL enabled [INFO] SimpleAuthenticator - Initializing authentication with the org.apache.tinkerpop.gremlin.server.auth.SimpleAuthenticator [INFO] SimpleAuthenticator - CredentialGraph initialized at CredentialGraph{graph=tinkergraph[vertices:1 edges:0]} @@ -1269,19 +1308,18 @@ $ bin/gremlin-server.sh conf/gremlin-server-secure.yaml [INFO] GremlinServer$1 - Channel started at port 8182. ---- -In addition to configuring the authenticator, `gremlin-server-secure.yaml` also enables SSL with a self-signed -certificate. As SSL is enabled on the server it must also be enabled on the client when connecting. To connect to -Gremlin Server with `gremlin-driver`, set the `credentials` and `enableSsl` when constructing the `Cluster`. +As SSL is enabled on the server it must also be enabled on the client when connecting. To connect to +Gremlin Server with `gremlin-driver`, set the `credentials`, `enableSsl`, and `trustStore` when constructing the `Cluster`. [source,java] Cluster cluster = Cluster.build().credentials("stephen", "password") - .enableSsl(true).create(); + .enableSsl(true).trustStore("server.jks").create(); If connecting with Gremlin Console, which utilizes `gremlin-driver` for remote script execution, use the provided `conf/remote-secure.yaml` file when defining the remote. That file contains configuration for the username and -password as well as enablement of SSL from the client side. +password as well as enablement of SSL from the client side. Be sure to configure the trustStore if using self-signed certificates. -Similarly, Gremlin Server can be configured for REST and security. +Similarly, Gremlin Server can be configured for REST and security. Follow the steps above for configuring the SSL certificate. [source,text] ---- @@ -1293,7 +1331,6 @@ $ bin/gremlin-server.sh conf/gremlin-server-rest-secure.yaml [INFO] GremlinServer - Configuring Gremlin Server from conf/gremlin-server-secure.yaml ... -[WARN] AbstractChannelizer - Enabling SSL with self-signed certificate (NOT SUITABLE FOR PRODUCTION) [INFO] AbstractChannelizer - SSL enabled [INFO] SimpleAuthenticator - Initializing authentication with the org.apache.tinkerpop.gremlin.server.auth.SimpleAuthenticator [INFO] SimpleAuthenticator - CredentialGraph initialized at CredentialGraph{graph=tinkergraph[vertices:1 edges:0]} http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/b77c0c7b/gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/AbstractChannelizer.java ---------------------------------------------------------------------- diff --git a/gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/AbstractChannelizer.java b/gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/AbstractChannelizer.java index 2a29fec..d7f3ec1 100644 --- a/gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/AbstractChannelizer.java +++ b/gremlin-server/src/main/java/org/apache/tinkerpop/gremlin/server/AbstractChannelizer.java @@ -19,6 +19,7 @@ package org.apache.tinkerpop.gremlin.server; import io.netty.channel.EventLoopGroup; +import io.netty.handler.ssl.ClientAuth; import io.netty.handler.ssl.SslContext; import io.netty.handler.ssl.SslContextBuilder; import io.netty.handler.ssl.SslProvider; @@ -305,6 +306,8 @@ public abstract class AbstractChannelizer extends ChannelInitializer<SocketChann keystore.load(in, password); } kmf.init(keystore, password); + } else { + throw new IllegalStateException("keyStore must be configured when SSL is enabled."); } builder = SslContextBuilder.forServer(kmf); @@ -323,8 +326,8 @@ public abstract class AbstractChannelizer extends ChannelInitializer<SocketChann } } catch (UnrecoverableKeyException | NoSuchAlgorithmException | KeyStoreException | CertificateException | IOException e) { - logger.error("There was an error enabling SSL.", e); - return null; + logger.error(e.getMessage()); + throw new RuntimeException("There was an error enabling SSL.", e); } } @@ -336,14 +339,19 @@ public abstract class AbstractChannelizer extends ChannelInitializer<SocketChann if (null != sslSettings.sslEnabledProtocols && !sslSettings.sslEnabledProtocols.isEmpty()) { builder.protocols(sslSettings.sslEnabledProtocols.toArray(new String[] {})); } + + if (null != sslSettings.needClientAuth && ClientAuth.OPTIONAL == sslSettings.needClientAuth) { + logger.warn("needClientAuth = OPTIONAL is not a secure configuration. Setting to REQUIRE."); + sslSettings.needClientAuth = ClientAuth.REQUIRE; + } builder.clientAuth(sslSettings.needClientAuth).sslProvider(provider); try { return builder.build(); } catch (SSLException ssle) { - logger.error("There was an error enabling SSL", ssle); - return null; + logger.error(ssle.getMessage()); + throw new RuntimeException("There was an error enabling SSL.", ssle); } } }
