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