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 <[email protected]>
AuthorDate: Wed Mar 8 15:13:53 2023 +0200
IGNITE-18933 Added SSL/TLS config docs. Fixes #1761
Signed-off-by: Slava Koptilin <[email protected]>
---
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
