You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by sk...@apache.org on 2023/03/08 13:14:07 UTC
[ignite-3] branch main updated: IGNITE-18933 Added SSL/TLS config docs. Fixes #1761
This is an automated email from the ASF dual-hosted git repository.
sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new 86f25783cb IGNITE-18933 Added SSL/TLS config docs. Fixes #1761
86f25783cb is described below
commit 86f25783cbd018cf0c02615de577388cf752364f
Author: IgGusev <de...@mail.ru>
AuthorDate: Wed Mar 8 15:13:53 2023 +0200
IGNITE-18933 Added SSL/TLS config docs. Fixes #1761
Signed-off-by: Slava Koptilin <sl...@gmail.com>
---
docs/_data/toc.yaml | 3 +-
docs/_docs/ssl-tls.adoc | 191 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 193 insertions(+), 1 deletion(-)
diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml
index 2f2dec7c92..b1ae999f46 100644
--- a/docs/_data/toc.yaml
+++ b/docs/_data/toc.yaml
@@ -72,7 +72,8 @@
url: storage/volatile
- title: Binary Client Protocol
url: binary-protocol
-
+- title: SSL/TLS
+ url: ssl-tls
- title: Data Rebalancing
url: rebalance
- title: Performing Transactions
diff --git a/docs/_docs/ssl-tls.adoc b/docs/_docs/ssl-tls.adoc
new file mode 100644
index 0000000000..2cbf1aae14
--- /dev/null
+++ b/docs/_docs/ssl-tls.adoc
@@ -0,0 +1,191 @@
+= SSL/TLS
+
+This page explains how to configure SSL/TLS encryption between the cluster nodes (server and client) and the clients that connect to your cluster.
+
+== Considerations
+
+All internal connections in the cluster context, as well as cluster's user interaction interfaces, are SSL-enabled. The communication categories are as follows:
+
+* Between the user and the cluster (node): REST
+* Between the user and the platform clients
+* Between nodes: Network (Messaging, Scalecube)
+
+All SSL configurations activities are performed at the node level.
+
+Apache Ignite does not support direct paths to SSL certificates. Instead, it utilizes PKCS12 and JKS keystore.
+
+== REST
+
+The standard implementation of SSL for REST involves configuring a secure connection on a separate port. Apache Ignite supports HTTP and HTTPS, arch on its own port.
+
+The Apache Ignite 3.x REST security configuration is as follows:
+
+[source,json]
+----
+"rest": {
+ "dualProtocol": false,
+ "httpToHttpsRedirection": false,
+ "ssl": {
+ "enabled": true,
+ "port": 10400,
+ "portRange": 100,
+ "keyStore": {
+ "type": "PKCS12",
+ "path": "must not be empty",
+ "password": "may be empty"
+ }
+ }
+}
+----
+
+== Clients and JDBC
+
+Apache Ignite 3.x Client implementation is based on the Netty framework, which supports configuration for security connections via `SSLContextBuilder`.
+
+=== Server-side Configuration
+
+The default way to configure SSL on the server side is to update the configuration with SSL properties:
+
+[source,json]
+----
+"clientConnector": {
+ "ssl": {
+ "enabled": true,
+ "clientAuth": "require",
+ "keyStore": {
+ "type": "PKCS12",
+ "path": "must not be empty",
+ "password": "may be empty"
+ },
+ "trustStore": {
+ "type": "PKCS12",
+ "path": "must not be empty",
+ "password": "may be empty"
+ }
+ }
+}
+----
+
+If you have enabled SSL for `clientConnector`, and want to use JDBC, set the corresponding properties in your code:
+
+[source,java]
+----
+var url =
+ "jdbc:ignite:thin://{address}:{port}"
+ + "?sslEnabled=true"
+ + "&trustStorePath=" + trustStorePath
+ + "&trustStoreType=JKS"
+ + "&trustStorePassword=" + password
+ + "&clientAuth=require"
+ + "&keyStorePath=" + keyStorePath
+ + "&keyStoreType=PKCS12"
+ + "&keyStorePassword=" + password;
+ try (Connection conn = DriverManager.getConnection(url)) {
+ // Other actions.
+ }
+----
+
+
+== Client Configuration
+
+== Java
+
+To enable SSL in your Java clients, use the `IgniteClient` class and pass the ssl configuration to it:
+
+[source,Java]
+----
+var sslConfiguration = SslConfiguration.builder()
+ .enabled(true)
+ .trustStoreType("JKS")
+ .trustStorePath(trustStorePath)
+ .trustStorePassword(password)
+ .clientAuth(REQUIRE)
+ .keyStorePath(keyStorePath)
+ .keyStorePassword(password)
+ .build();
+
+try (IgniteClient client = IgniteClient.builder()
+ .addresses("localhost:10800")
+ .ssl(sslConfiguration)
+ .build()
+)
+----
+
+
+=== .NET
+
+Add the `IgniteClientConfiguration.SslStreamFactory` property of type `ISslStreamFactory`.
+
+Provide a link:https://github.com/apache/ignite/blob/66f43a4bee163aadb3ad731f6eb9a6dfde9faa73/modules/platforms/dotnet/Apache.Ignite.Core/Client/SslStreamFactory.cs[predefined implementation].
+
+Use the base class library `SslStream`.
+
+Basic usage without client authorization:
+
+[source,csharp]
+----
+var cfg = new IgniteClientConfiguration { SslStreamFactory = new() }
+----
+
+== CLI
+
+To SSL on the CLI side, use the `cli config set` command:
+
+[source,shell]
+----
+cli config set cli.trust-store.type=<type>
+cli config set cli.trust-store.path=<path>
+cli config set cli.trust-store.password=<password>
+----
+
+Store the CLI security configuration in a separate file with permission settings that protect it from unauthorized read/write operations. This configuration file must match profiles from the common configuration file.
+
+
+== Network Configuration
+
+The node network is based on the Netty framework. The configuration is the same as described for the Apache Ignite Client part except for the part that addresses the Apache Ignite 3.x configuration:
+
+[source,json]
+----
+"network": {
+ "ssl": {
+ "enabled": true,
+ "clientAuth": "none",
+ "keyStore": {
+ "type": "PKCS12",
+ "path": "must not be empty",
+ "password": "may be empty"
+ },
+ "trustStore": {
+ "type": "PKCS12",
+ "path": "must not be empty",
+ "password": "may be empty"
+ }
+ }
+}
+----
+
+== SSL Client Authentication (mTLS Support)
+
+Optionally, the connections you utilize can support the client authentication feature. Configure it separately for each connection on the server side.
+
+Two-way authentication requires that both server and client have certificates they reciprocally trust. The client generates a private key, stores it in its keystore, and gets it signed by an entity the server's truststore trusts.
+
+To support client authentication, a connection must include the `clientAuth`, `trustStore` and `keyStore` properties. Here is an example of a possible client configuration:
+
+[source,json]
+----
+clientConnector.ssl: {
+ enabled: true,
+ clientAuth: "require",
+ keyStore: {
+ path: "must not be empty",
+ password: "may be empty"
+ },
+ trustStore: {
+ type: "JKS",
+ path: "must not be empty",
+ password: "may be empty"
+ }
+}
+----
\ No newline at end of file