You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ma...@apache.org on 2023/10/15 23:28:36 UTC
[pulsar-site] branch main updated: Refine SSL/TLS related documents (#709)
This is an automated email from the ASF dual-hosted git repository.
mattisonchao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 513c83cd3e2c Refine SSL/TLS related documents (#709)
513c83cd3e2c is described below
commit 513c83cd3e2cda0ae15bb22dc009f5a4c2105871
Author: Qiang Zhao <ma...@apache.org>
AuthorDate: Mon Oct 16 07:28:29 2023 +0800
Refine SSL/TLS related documents (#709)
---
docs/security-authorization.md | 7 +-
docs/security-tls-authentication.md | 32 +++++-----
docs/security-tls-transport.md | 123 ++++++++++++++++++++++++++++++------
3 files changed, 123 insertions(+), 39 deletions(-)
diff --git a/docs/security-authorization.md b/docs/security-authorization.md
index 1b3e27c82b99..a2108225981b 100644
--- a/docs/security-authorization.md
+++ b/docs/security-authorization.md
@@ -19,7 +19,7 @@ You can enable the authorization and assign the superusers in the broker ([`conf
```conf
authorizationEnabled=true
-superUserRoles=my-super-user-1,my-super-user-2
+superUserRoles=broker_client,admin,proxy,<custom-super-user-1>,<custom-super-user-2>
```
> A full list of parameters is available in the `conf/broker.conf` or `conf/standalone.conf` file.
@@ -47,10 +47,7 @@ Another approach is to make the proxy role a superuser. This allows the proxy to
You can specify the roles as proxy roles in [`conf/broker.conf`](reference-configuration.md#broker).
```properties
-proxyRoles=my-proxy-role
-
-# if you want to allow superusers to use the proxy (see above)
-superUserRoles=my-super-user-1,my-super-user-2,my-proxy-role
+proxyRoles=proxy,<my-proxy-role>
```
## Administer tenants
diff --git a/docs/security-tls-authentication.md b/docs/security-tls-authentication.md
index 707570d979a3..b8616664619f 100644
--- a/docs/security-tls-authentication.md
+++ b/docs/security-tls-authentication.md
@@ -32,7 +32,7 @@ authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationPr
brokerClientTlsEnabled=true
brokerClientTrustCertsFilePath=/path/to/ca.cert.pem
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
-brokerClientAuthenticationParameters={"tlsCertFile":"/path/to/admin.cert.pem","tlsKeyFile":"/path/to/admin.key-pk8.pem"}
+brokerClientAuthenticationParameters={"tlsCertFile":"/path/to/broker_client.cert.pem","tlsKeyFile":"/path/to/broker_client.key-pk8.pem"}
# configure TLS ports
brokerServicePortTls=6651
@@ -41,9 +41,9 @@ webServicePortTls=8081
# configure CA certificate
tlsTrustCertsFilePath=/path/to/ca.cert.pem
# configure server certificate
-tlsCertificateFilePath=/path/to/broker.cert.pem
+tlsCertificateFilePath=/path/to/server.cert.pem
# configure server's private key
-tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsKeyFilePath=/path/to/server.key-pk8.pem
# enable mTLS
tlsRequireTrustedClientCertOnConnect=true
@@ -67,7 +67,7 @@ authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationPr
tlsEnabledWithBroker=true
brokerClientTrustCertsFilePath=/path/to/ca.cert.pem
brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
-brokerClientAuthenticationParameters={"tlsCertFile":"/path/to/admin.cert.pem","tlsKeyFile":"/path/to/admin.key-pk8.pem"}
+brokerClientAuthenticationParameters={"tlsCertFile":"/path/to/proxy.cert.pem","tlsKeyFile":"/path/to/proxy.key-pk8.pem"}
# configure TLS ports
brokerServicePortTls=6651
@@ -76,9 +76,9 @@ webServicePortTls=8081
# configure CA certificate
tlsTrustCertsFilePath=/path/to/ca.cert.pem
# configure server certificate
-tlsCertificateFilePath=/path/to/proxy.cert.pem
+tlsCertificateFilePath=/path/to/server.cert.pem
# configure server's private key
-tlsKeyFilePath=/path/to/proxy.key-pk8.pem
+tlsKeyFilePath=/path/to/server.key-pk8.pem
# enable mTLS
tlsRequireTrustedClientCertOnConnect=true
@@ -102,7 +102,7 @@ PulsarClient client = PulsarClient.builder()
.serviceUrl("pulsar+ssl://broker.example.com:6651/")
.tlsTrustCertsFilePath("/path/to/ca.cert.pem")
.authentication("org.apache.pulsar.client.impl.auth.AuthenticationTls",
- "tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem")
+ "tlsCertFile:/path/to/client.cert.pem,tlsKeyFile:/path/to/client.key-pk8.pem")
.build();
```
@@ -112,7 +112,7 @@ PulsarClient client = PulsarClient.builder()
```python
from pulsar import Client, AuthenticationTLS
-auth = AuthenticationTLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem")
+auth = AuthenticationTLS("/path/to/client.cert.pem", "/path/to/client.key-pk8.pem")
client = Client("pulsar+ssl://broker.example.com:6651/",
tls_trust_certs_file_path="/path/to/ca.cert.pem",
tls_allow_insecure_connection=False,
@@ -130,8 +130,8 @@ config.setUseTls(true);
config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
config.setTlsAllowInsecureConnection(false);
-pulsar::AuthenticationPtr auth = pulsar::AuthTls::create("/path/to/my-role.cert.pem",
- "/path/to/my-role.key-pk8.pem")
+pulsar::AuthenticationPtr auth = pulsar::AuthTls::create("/path/to/client.cert.pem",
+ "/path/to/client.key-pk8.pem")
config.setAuth(auth);
pulsar::Client client("pulsar+ssl://broker.example.com:6651/", config);
@@ -145,8 +145,8 @@ const Pulsar = require('pulsar-client');
(async () => {
const auth = new Pulsar.AuthenticationTls({
- certificatePath: '/path/to/my-role.cert.pem',
- privateKeyPath: '/path/to/my-role.key-pk8.pem',
+ certificatePath: '/path/to/client.cert.pem',
+ privateKeyPath: '/path/to/client.key-pk8.pem',
});
const client = new Pulsar.Client({
@@ -164,7 +164,7 @@ const Pulsar = require('pulsar-client');
client, err := pulsar.NewClient(ClientOptions{
URL: "pulsar+ssl://broker.example.com:6651/",
TLSTrustCertsFilePath: "/path/to/ca.cert.pem",
- Authentication: pulsar.NewAuthenticationTLS("/path/to/my-role.cert.pem", "/path/to/my-role.key-pk8.pem"),
+ Authentication: pulsar.NewAuthenticationTLS("/path/to/client.cert.pem", "/path/to/client.key-pk8.pem"),
})
```
@@ -189,13 +189,15 @@ var client = PulsarClient.Builder()
To use mTLS authentication with the CLI tools of Pulsar, you need to add the following parameters to the `conf/client.conf` file, alongside [the configurations to enable mTLS encryption](security-tls-transport.md#configure-mtls-encryption-in-cli-tools):
```properties
+webServiceUrl=https://localhost:8081/
+brokerServiceUrl=pulsar+ssl://localhost:6651/
authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
-authParams=tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem
+authParams=tlsCertFile:/path/to/admin.cert.pem,tlsKeyFile:/path/to/admin.key-pk8.pem
```
## Configure mTLS authentication with KeyStore
-Apache Pulsar supports [TLS encryption](security-tls-transport.md) and [mTLS authentication](security-tls-authentication.md) between clients and Apache Pulsar service. By default, it uses PEM format file configuration.
+Apache Pulsar supports [TLS encryption](security-tls-transport.md) and [mTLS authentication](security-tls-authentication.md) between clients and Apache Pulsar service. By default, it uses PEM format file configuration.
To configure mTLS authentication with [KeyStore](https://en.wikipedia.org/wiki/Java_KeyStore), complete the following steps.
diff --git a/docs/security-tls-transport.md b/docs/security-tls-transport.md
index a7bc580f17cb..9bba523d70bc 100644
--- a/docs/security-tls-transport.md
+++ b/docs/security-tls-transport.md
@@ -101,16 +101,16 @@ Once you have created a CA, you can create certificate requests and sign them wi
1. Generate the server's private key.
```bash
- openssl genrsa -out broker.key.pem 2048
+ openssl genrsa -out server.key.pem 2048
```
- The broker expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format. Enter the following command to convert it.
+ The server expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format. Enter the following command to convert it.
```bash
- openssl pkcs8 -topk8 -inform PEM -outform PEM -in broker.key.pem -out broker.key-pk8.pem -nocrypt
+ openssl pkcs8 -topk8 -inform PEM -outform PEM -in server.key.pem -out server.key-pk8.pem -nocrypt
```
-2. Create a `broker.conf` file with the following content:
+2. Create a `server.conf` file with the following content:
```properties
[ req ]
@@ -127,7 +127,7 @@ Once you have created a CA, you can create certificate requests and sign them wi
subjectAltName=@alt_names
[ dn ]
- CN = broker
+ CN = server
[ alt_names ]
DNS.1 = pulsar
@@ -138,23 +138,79 @@ Once you have created a CA, you can create certificate requests and sign them wi
:::tip
- To configure [hostname verification](#hostname-verification), you need to enter the hostname of the broker in `alt_names` as the Subject Alternative Name (SAN). To ensure that multiple machines can reuse the same certificate, you can also use a wildcard to match a group of broker hostnames, for example, `*.broker.usw.example.com`.
+ To configure [hostname verification](#hostname-verification), you need to enter the hostname of the server in `alt_names` as the Subject Alternative Name (SAN). To ensure that multiple machines can reuse the same certificate, you can also use a wildcard to match a group of server hostnames, for example, `*.server.usw.example.com`.
:::
3. Generate the certificate request.
```bash
- openssl req -new -config broker.conf -key broker.key.pem -out broker.csr.pem -sha256
+ openssl req -new -config server.conf -key server.key.pem -out server.csr.pem -sha256
```
4. Sign the certificate with the CA.
```bash
- openssl x509 -req -in broker.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out broker.cert.pem -days 365 -extensions v3_ext -extfile broker.conf -sha256
+ openssl x509 -req -in server.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out server.cert.pem -days 365 -extensions v3_ext -extfile server.conf -sha256
```
-At this point, you have a cert, `broker.cert.pem`, and a key, `broker.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your brokers and proxies.
+At this point, you have a cert, `server.cert.pem`, and a key, `server.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your brokers and proxies.
+
+#### Create a broker client certificate
+
+1. Generate the broker_client's private key.
+
+ ```bash
+ openssl genrsa -out broker_client.key.pem 2048
+ ```
+
+ The broker_client expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format. Enter the following command to convert it.
+
+ ```bash
+ openssl pkcs8 -topk8 -inform PEM -outform PEM -in broker_client.key.pem -out broker_client.key-pk8.pem -nocrypt
+ ```
+
+2. Generate the certificate request. Note that the value of `CN` is used as the broker client's role token.
+
+ ```bash
+ openssl req -new -subj "/CN=broker_client" -key broker_client.key.pem -out broker_client.csr.pem -sha256
+ ```
+
+3. Sign the certificate with the CA.
+
+ ```bash
+ openssl x509 -req -in broker_client.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out broker_client.cert.pem -days 365 -sha256
+ ```
+
+At this point, you have a cert `broker_client.cert.pem` and a key `broker_client.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your broker client.
+
+#### Create a admin certificate
+
+1. Generate the admin's private key.
+
+ ```bash
+ openssl genrsa -out admin.key.pem 2048
+ ```
+
+ The admin expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format. Enter the following command to convert it.
+
+ ```bash
+ openssl pkcs8 -topk8 -inform PEM -outform PEM -in admin.key.pem -out admin.key-pk8.pem -nocrypt
+ ```
+
+2. Generate the certificate request. Note that the value of `CN` is used as the admin's role token.
+
+ ```bash
+ openssl req -new -subj "/CN=admin" -key admin.key.pem -out admin.csr.pem -sha256
+ ```
+
+3. Sign the certificate with the CA.
+
+ ```bash
+ openssl x509 -req -in admin.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out admin.cert.pem -days 365 -sha256
+ ```
+
+At this point, you have a cert `admin.cert.pem` and a key `admin.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your pulsar admin.
#### Create a client certificate
@@ -182,7 +238,36 @@ At this point, you have a cert, `broker.cert.pem`, and a key, `broker.key-pk8.pe
openssl x509 -req -in client.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out client.cert.pem -days 365 -sha256
```
-At this point, you have a cert `client.cert.pem` and a key `client.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your clients.
+At this point, you have a cert `client.cert.pem` and a key `client.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your client.
+
+#### Create a proxy certificate (Optional)
+
+1. Generate the proxy's private key.
+
+ ```bash
+ openssl genrsa -out proxy.key.pem 2048
+ ```
+
+ The proxy expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format. Enter the following command to convert it.
+
+ ```bash
+ openssl pkcs8 -topk8 -inform PEM -outform PEM -in proxy.key.pem -out proxy.key-pk8.pem -nocrypt
+ ```
+
+2. Generate the certificate request. Note that the value of `CN` is used as the proxy's role token.
+
+ ```bash
+ openssl req -new -subj "/CN=proxy" -key proxy.key.pem -out proxy.csr.pem -sha256
+ ```
+
+3. Sign the certificate with the CA.
+
+ ```bash
+ openssl x509 -req -in proxy.csr.pem -CA ca.cert.pem -CAkey ca.key.pem -CAcreateserial -out proxy.cert.pem -days 365 -sha256
+ ```
+
+At this point, you have a cert `proxy.cert.pem` and a key `proxy.key-pk8.pem`, which you can use along with `ca.cert.pem` to configure TLS encryption for your proxy.
+
### Step 2: Configure brokers
@@ -196,9 +281,9 @@ webServicePortTls=8081
# configure CA certificate
tlsTrustCertsFilePath=/path/to/ca.cert.pem
# configure server certificate
-tlsCertificateFilePath=/path/to/broker.cert.pem
+tlsCertificateFilePath=/path/to/server.cert.pem
# configure server's priviate key
-tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsKeyFilePath=/path/to/server.key-pk8.pem
# enable mTLS
tlsRequireTrustedClientCertOnConnect=true
@@ -206,8 +291,8 @@ tlsRequireTrustedClientCertOnConnect=true
# configure mTLS for the internal client
brokerClientTlsEnabled=true
brokerClientTrustCertsFilePath=/path/to/ca.cert.pem
-brokerClientCertificateFilePath=/path/to/client.cert.pem
-brokerClientKeyFilePath=/path/to/client.key-pk8.pem
+brokerClientCertificateFilePath=/path/to/broker_client.cert.pem
+brokerClientKeyFilePath=/path/to/broker_client.key-pk8.pem
```
#### Configure TLS Protocol Version and Cipher
@@ -240,8 +325,8 @@ servicePortTls=6651
webServicePortTls=8081
# configure certificates for clients to connect proxy
-tlsCertificateFilePath=/path/to/broker.cert.pem
-tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsCertificateFilePath=/path/to/server.cert.pem
+tlsKeyFilePath=/path/to/server.key-pk8.pem
tlsTrustCertsFilePath=/path/to/ca.cert.pem
# enable mTLS
@@ -250,8 +335,8 @@ tlsRequireTrustedClientCertOnConnect=true
# configure TLS for proxy to connect brokers
tlsEnabledWithBroker=true
brokerClientTrustCertsFilePath=/path/to/ca.cert.pem
-brokerClientCertificateFilePath=/path/to/client.cert.pem
-brokerClientKeyFilePath=/path/to/client.key-pk8.pem
+brokerClientCertificateFilePath=/path/to/proxy.cert.pem
+brokerClientKeyFilePath=/path/to/proxy.key-pk8.pem
```
### Step 4: Configure clients
@@ -407,7 +492,7 @@ To use mTLS encryption with Pulsar CLI tools, you need to add the following para
webServiceUrl=https://localhost:8081/
brokerServiceUrl=pulsar+ssl://localhost:6651/
authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
-authParams=tlsCertFile:/path/to/client.cert.pem,tlsKeyFile:/path/to/client.key-pk8.pem
+authParams=tlsCertFile:/path/to/admin.cert.pem,tlsKeyFile:/path/to/admin.key-pk8.pem
```
## Configure mTLS encryption with KeyStore