This is an automated email from the ASF dual-hosted git repository.
jojochuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/master by this push:
new 16e1045c0 HDDS-15189. [Docs] mTLS usage in Ozone. (#418)
16e1045c0 is described below
commit 16e1045c01773c784efd48cb883d6e224a125e51
Author: Wei-Chiu Chuang <[email protected]>
AuthorDate: Thu May 7 11:58:55 2026 -0700
HDDS-15189. [Docs] mTLS usage in Ozone. (#418)
Generated-by: Cursor composer-2-fast
---
cspell.yaml | 1 +
.../01-basic/02-network/07-default-ports.md | 2 +-
.../05-encryption/01-network-encryption/02-grpc.md | 13 +++++++++++++
.../01-basic/02-network/07-default-ports.md | 2 +-
.../05-encryption/01-network-encryption/02-grpc.md | 13 +++++++++++++
5 files changed, 29 insertions(+), 2 deletions(-)
diff --git a/cspell.yaml b/cspell.yaml
index a458fb471..c58420f6d 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -90,6 +90,7 @@ words:
- mis-replication
- mis-replicated
- unreplicated
+- untampered
- BCSID
- EC
- reconfig
diff --git
a/docs/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
index 05d8534d4..7f7dbc74a 100644
---
a/docs/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
+++
b/docs/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
@@ -82,7 +82,7 @@ For example: `ozone.scm.client.port.scmservice.scm1`.
- Hadoop RPC, a binary protocol operating over TCP, may be authenticated and
encrypted using the Java SASL mechanism.
- Authentication of the Web UI and HttpFS is achievable through
Kerberos/SPNEGO, with encryption facilitated by HTTPS.
- S3 client connections to the S3 Gateway undergo authentication utilizing S3
secrets and encryption via TLS.
-- A series of Ozone service ports are established by gRPC and Ratis, the
latter employing gRPC. gRPC, a protocol based on HTTP/2, is capable of being
encrypted with TLS.
+- A series of Ozone service ports are established by gRPC and Ratis, the
latter employing gRPC. gRPC, a protocol based on HTTP/2, is capable of being
encrypted with TLS. For how TLS and mTLS apply across gRPC/Ratis and HTTPS
ports, see [Configuring gRPC With
TLS](../../security/encryption/network-encryption/grpc).
- Ratis streaming ports, initiated by Netty, can be secured through TLS
encryption.
:::
diff --git
a/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
index e11074f92..00c05c6ec 100644
---
a/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
+++
b/docs/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
@@ -6,6 +6,19 @@ sidebar_label: gRPC TLS
Ozone traffic may be transferred via gRPC (e.g., Ratis write pipeline or
client reading blocks from Datanode). To enable TLS for gRPC traffic, set
`hdds.grpc.tls.enabled` to **true**. This encrypts communication between Ozone
services that use gRPC.
+## mTLS in Apache Ozone
+
+In Apache Ozone, mTLS requirements are split across two distinct communication
layers:
+
+| Communication Layer | Protocol | mTLS Requirement | Configuration Key(s) |
+| --- | --- | --- | --- |
+| Peer-to-Peer (Core) | gRPC / Ratis | Required (Hardcoded) |
`ozone.security.enabled` & `hdds.grpc.tls.enabled` |
+| Management / Web | HTTPS | Optional | `ozone.https.client.need-auth`
(default: **false**) |
+
+For the primary peer-to-peer communication (consensus, replication,
heartbeats), Ozone effectively mandates mTLS by default whenever TLS is enabled
in a secure cluster, using the SCM's internal Certificate Authority to issue
and verify peer identities. For the HTTPS layer, mTLS is an optional extra
security measure.
+
+Clients (including the S3 Gateway) are often treated as "external" entities.
While the S3 Gateway is part of the Ozone distribution, it utilizes the
standard client libraries which are designed to work from machines that do not
have SCM-issued certificates, relying instead on Kerberos for identity and
tokens for data access.
+
## Configuration
Add the following property to your `ozone-site.xml` configuration file:
diff --git
a/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
b/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
index 05d8534d4..7f7dbc74a 100644
---
a/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
+++
b/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
@@ -82,7 +82,7 @@ For example: `ozone.scm.client.port.scmservice.scm1`.
- Hadoop RPC, a binary protocol operating over TCP, may be authenticated and
encrypted using the Java SASL mechanism.
- Authentication of the Web UI and HttpFS is achievable through
Kerberos/SPNEGO, with encryption facilitated by HTTPS.
- S3 client connections to the S3 Gateway undergo authentication utilizing S3
secrets and encryption via TLS.
-- A series of Ozone service ports are established by gRPC and Ratis, the
latter employing gRPC. gRPC, a protocol based on HTTP/2, is capable of being
encrypted with TLS.
+- A series of Ozone service ports are established by gRPC and Ratis, the
latter employing gRPC. gRPC, a protocol based on HTTP/2, is capable of being
encrypted with TLS. For how TLS and mTLS apply across gRPC/Ratis and HTTPS
ports, see [Configuring gRPC With
TLS](../../security/encryption/network-encryption/grpc).
- Ratis streaming ports, initiated by Netty, can be secured through TLS
encryption.
:::
diff --git
a/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
b/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
index e11074f92..00c05c6ec 100644
---
a/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
+++
b/versioned_docs/version-2.1.0/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
@@ -6,6 +6,19 @@ sidebar_label: gRPC TLS
Ozone traffic may be transferred via gRPC (e.g., Ratis write pipeline or
client reading blocks from Datanode). To enable TLS for gRPC traffic, set
`hdds.grpc.tls.enabled` to **true**. This encrypts communication between Ozone
services that use gRPC.
+## mTLS in Apache Ozone
+
+In Apache Ozone, mTLS requirements are split across two distinct communication
layers:
+
+| Communication Layer | Protocol | mTLS Requirement | Configuration Key(s) |
+| --- | --- | --- | --- |
+| Peer-to-Peer (Core) | gRPC / Ratis | Required (Hardcoded) |
`ozone.security.enabled` & `hdds.grpc.tls.enabled` |
+| Management / Web | HTTPS | Optional | `ozone.https.client.need-auth`
(default: **false**) |
+
+For the primary peer-to-peer communication (consensus, replication,
heartbeats), Ozone effectively mandates mTLS by default whenever TLS is enabled
in a secure cluster, using the SCM's internal Certificate Authority to issue
and verify peer identities. For the HTTPS layer, mTLS is an optional extra
security measure.
+
+Clients (including the S3 Gateway) are often treated as "external" entities.
While the S3 Gateway is part of the Ozone distribution, it utilizes the
standard client libraries which are designed to work from machines that do not
have SCM-issued certificates, relying instead on Kerberos for identity and
tokens for data access.
+
## Configuration
Add the following property to your `ozone-site.xml` configuration file:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
