pulsar-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] sijie closed pull request #2220: Rework TLS docs to separate concerns
Date Wed, 01 Aug 2018 23:11:02 GMT
sijie closed pull request #2220: Rework TLS docs to separate concerns
URL: https://github.com/apache/incubator-pulsar/pull/2220
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index bcd58c4676..c38afc524d 100644
--- a/site/_data/sidebar.yaml
+++ b/site/_data/sidebar.yaml
@@ -99,7 +99,9 @@ groups:
   docs:
   - title: Overview
     endpoint: overview
-  - title: Encryption and Authentication using TLS
+  - title: Transport Encryption with TLS
+    endpoint: tls-transport
+  - title: Authentication using TLS
     endpoint: tls
   - title: Authentication using Athenz
     endpoint: athenz
diff --git a/site/docs/latest/security/authorization.md b/site/docs/latest/security/authorization.md
index c0c58eeb62..393284e8ab 100644
--- a/site/docs/latest/security/authorization.md
+++ b/site/docs/latest/security/authorization.md
@@ -25,15 +25,51 @@ tags: [admin, authentication, authorization, athenz, tls, java, cpp]
 -->
 
 In Pulsar, the [authentication provider](../overview#authentication-providers) is charged
with properly identifying clients and
-associating them with [role tokens](../overview#role-tokens). *Authorization* is the process
that determines *what* clients are able to do.
+associating them with [role tokens](../overview#role-tokens). If only authentication is enabled,
an authenticated role token will have the ability to access all resources in the cluster.
*Authorization* is the process that determines *what* clients are able to do.
 
-Authorization in Pulsar is managed at the {% popover tenant %} level, which means that you
can have multiple authorization schemes active
-in a single Pulsar instance. You could, for example, create a `shopping` tenant that has
one set of [roles](../overview#role-tokens)
-and applies to a shopping application used by your company, while an `inventory` tenant would
be used only by an inventory application.
+The role tokens with the most privileges are the *superusers*. The *superusers* can create
and destroy tenants, along with having full access to all tenant resources.
 
-{% include message.html id="properties_multiple_clusters" %}
+When a {% popover tenant %} is created by a superuser, that tenant is assigned an admin role.
A client with the admin role token can then create, modify and destroy namespaces, and grant
and revoke permissions to *other role tokens* on those namespaces.
 
-## Creating a new tenant
+## Broker and Proxy Setup
+
+### Enabling Authorization and Assigning Superusers
+
+Authorization is enabled and superusers are assigned in the broker ([`conf/broker.conf`](../../reference/Configuration#broker))
and proxy ([`conf/proxy.conf`](../../reference/Configuration#proxy)) configuration files.
+
+```properties
+authorizationEnabled=true
+superUserRoles=my-super-user-1,my-super-user-2
+```
+
+{% include message.html id="broker_conf_doc" %}
+
+Typically, superuser roles are used for administrators and clients but also for broker-to-broker
authorization. When using [geo-replication](../GeoReplication), every broker needs to be able
to publish to all the other clusters' topics.
+
+### Proxy Roles
+
+By default, the broker treats the connection between a proxy and the broker as a normal user
connection. The user is authenticated as the role configured in ```proxy.conf``` (see ["Enabling
TLS Authentication on Proxies"](../tls#-on-proxies)). However, this is rarely the behaviour
that the user desires when connecting to the cluster through a proxy. The user expects to
be able to interact with the cluster as the role for which they have authenticated with the
proxy.
+
+Pulsar uses *Proxy roles* to enable this. Proxy roles are specified in the broker configuration
file, [`conf/broker.conf`](../../reference/Configuration#broker). If a client that is authenticated
with a broker is one of its ```proxyRoles```, all requests from that client must also carry
information about the role of the client that is authenticated with the proxy. If this information,
which we call the *original principal*, is missing, the client will not be able to access
anything.
+
+Both the *proxy role* and the *original principle* must be authorized to access a resource
for that resource to be accessible via the proxy. Administrators can take two approaches to
this.
+
+The more secure approach is to grant access to the proxy roles each time you grant access
to a resource. For example, if you have a proxy role ```proxy1```, when a tenant is created
by the superuser, ```proxy1``` should be specified as one of the admin roles. When a role
is granted permissions to produce or consume from a namespace, if that client wants to produce
or consume through a proxy, ```proxy1``` should also be granted the same permissions.
+
+Another approach is to make the proxy role a superuser. This will allow the proxy to access
all resources. The client will still need to authenticate with the proxy, and all requests
made through the proxy will have their role downgraded to the *original principal* of the
authenticated client. However, if the proxy is compromised, a bad actor could get full access
to your cluster.
+
+Roles can be specified as proxy roles in [`conf/broker.conf`](../../reference/Configuration#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
+```
+
+## Administering Tenants
+
+### Creating a new tenant
 
 A Pulsar {% popover tenant %} is typically provisioned by Pulsar {% popover instance %} administrators
or by some kind of self-service portal.
 
@@ -53,26 +89,11 @@ The structure of topic names in Pulsar reflects the hierarchy between
tenants, c
 
 {% include topic.html ten="tenant" n="namespace" t="topic" %}
 
-## Managing permissions
+### Managing permissions
 
 {% include explanations/permissions.md %}
 
-## Superusers
-
-In Pulsar you can assign certain roles to be *superusers* of the system. A superuser is allowed
to perform all administrative tasks on all tenants and namespaces, as well as to publish and
subscribe to all topics.
-
-Superusers are configured in the broker configuration file in [`conf/broker.conf`](../../reference/Configuration#broker)
configuration file, using the [`superUserRoles`](../../reference/Configuration#broker-superUserRoles)
parameter:
-
-```tenants
-superUserRoles=my-super-user-1,my-super-user-2
-```
-
-{% include message.html id="broker_conf_doc" %}
-
-Typically, superuser roles are used for administrators and clients but also for broker-to-broker
authorization. When using [geo-replication](../GeoReplication), every broker
-needs to be able to publish to other clusters' topics.
-
-## Pulsar admin authentication
+### Pulsar admin authentication
 
 ```java
 String authPluginClassName = "com.org.MyAuthPluginClass";
diff --git a/site/docs/latest/security/openssl.cnf b/site/docs/latest/security/openssl.cnf
new file mode 100644
index 0000000000..eee8a47298
--- /dev/null
+++ b/site/docs/latest/security/openssl.cnf
@@ -0,0 +1,152 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# 
+# Configuration file for testing certificate authority.
+# The environment variable, CA_HOME, must be set to point to the directory
+# containing this file before running any openssl commands.
+#
+[ ca ]
+# `man ca`
+default_ca = CA_default
+
+[ CA_default ]
+# Directory and file locations.
+dir               = $ENV::CA_HOME
+certs             = $dir/certs
+crl_dir           = $dir/crl
+new_certs_dir     = $dir/newcerts
+database          = $dir/index.txt
+serial            = $dir/serial
+RANDFILE          = $dir/private/.rand
+
+# The root key and root certificate.
+private_key       = $dir/private/ca.key.pem
+certificate       = $dir/certs/ca.cert.pem
+
+# For certificate revocation lists.
+crlnumber         = $dir/crlnumber
+crl               = $dir/crl/ca.crl.pem
+crl_extensions    = crl_ext
+default_crl_days  = 30
+
+# SHA-1 is deprecated, so use SHA-2 instead.
+default_md        = sha256
+
+name_opt          = ca_default
+cert_opt          = ca_default
+default_days      = 375
+preserve          = no
+policy            = policy_strict
+
+[ policy_strict ]
+# The root CA should only sign intermediate certificates that match.
+# See the POLICY FORMAT section of `man ca`.
+countryName             = match
+stateOrProvinceName     = match
+organizationName        = match
+organizationalUnitName  = optional
+commonName              = supplied
+emailAddress            = optional
+
+[ policy_loose ]
+# Allow the intermediate CA to sign a more diverse range of certificates.
+# See the POLICY FORMAT section of the `ca` man page.
+countryName             = optional
+stateOrProvinceName     = optional
+localityName            = optional
+organizationName        = optional
+organizationalUnitName  = optional
+commonName              = supplied
+emailAddress            = optional
+
+[ req ]
+# Options for the `req` tool (`man req`).
+default_bits        = 2048
+distinguished_name  = req_distinguished_name
+string_mask         = utf8only
+
+# SHA-1 is deprecated, so use SHA-2 instead.
+default_md          = sha256
+
+# Extension to add when the -x509 option is used.
+x509_extensions     = v3_ca
+
+[ req_distinguished_name ]
+# See <https://en.wikipedia.org/wiki/Certificate_signing_request>.
+countryName                     = Country Name (2 letter code)
+stateOrProvinceName             = State or Province Name
+localityName                    = Locality Name
+0.organizationName              = Organization Name
+organizationalUnitName          = Organizational Unit Name
+commonName                      = Common Name
+emailAddress                    = Email Address
+
+# Optionally, specify some defaults.
+countryName_default             = US
+stateOrProvinceName_default     = California
+localityName_default            = Palo Alto
+0.organizationName_default      = My company
+organizationalUnitName_default  = IT
+emailAddress_default            =
+
+[ v3_ca ]
+# Extensions for a typical CA (`man x509v3_config`).
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer
+basicConstraints = critical, CA:true
+keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+[ v3_intermediate_ca ]
+# Extensions for a typical intermediate CA (`man x509v3_config`).
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid:always,issuer
+basicConstraints = critical, CA:true, pathlen:0
+keyUsage = critical, digitalSignature, cRLSign, keyCertSign
+
+[ usr_cert ]
+# Extensions for client certificates (`man x509v3_config`).
+basicConstraints = CA:FALSE
+nsCertType = client, email
+nsComment = "OpenSSL Generated Client Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer
+keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
+extendedKeyUsage = clientAuth, emailProtection
+
+[ server_cert ]
+# Extensions for server certificates (`man x509v3_config`).
+basicConstraints = CA:FALSE
+nsCertType = server
+nsComment = "OpenSSL Generated Server Certificate"
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer:always
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+
+[ crl_ext ]
+# Extension for CRLs (`man x509v3_config`).
+authorityKeyIdentifier=keyid:always
+
+[ ocsp ]
+# Extension for OCSP signing certificates (`man ocsp`).
+basicConstraints = CA:FALSE
+subjectKeyIdentifier = hash
+authorityKeyIdentifier = keyid,issuer
+keyUsage = critical, digitalSignature
+extendedKeyUsage = critical, OCSPSigning
\ No newline at end of file
diff --git a/site/docs/latest/security/tls-transport.md b/site/docs/latest/security/tls-transport.md
new file mode 100644
index 0000000000..1aeff3f66f
--- /dev/null
+++ b/site/docs/latest/security/tls-transport.md
@@ -0,0 +1,209 @@
+---
+title: Transport Encryption using TLS
+---
+
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+
+## TLS Overview
+
+By default, Apache Pulsar clients communicate with the Apache Pulsar service in plain text,
which means that all data is sent in the clear. TLS can be used to encrypt this traffic so
that it cannot be snooped by a man-in-the-middle attacker.
+
+TLS can be configured for both encryption and authentication. You may configure just TLS
transport encryption, which is covered in this guide. TLS authentication is covered [elsewhere](../tls).
Alternatively, you can use [another authentication mechanism](../athenz) on top of TLS transport
encryption.
+
+> Note that enabling TLS may have a performance impact due to encryption overhead.
+
+## TLS concepts
+
+TLS is a form of [public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography).
Encryption is performed using key pairs consisting of a public key and a private key. Messages
are encrypted with the public key and can be decrypted with the private key.
+
+To use TLS transport encryption, you need two kinds of key pairs, **server key pairs** and
a **certificate authority**.
+
+A third kind of key pair, **client key pairs**, are used for [client authentication]("../tls").
+
+The **certificate authority** private key should be stored in a very secure location (a fully
encrypted, disconnected, air gapped computer). The certificate authority public key, the **trust
cert**, can be freely shared.
+
+For both client and server key pairs, the administrator first generates a private key and
a certificate request. Then the certificate authority private key is used to sign the certificate
request, generating a certificate. This certificate is the public key for the server/client
key pair.
+
+For TLS transport encryption, the clients can use the **trust cert** to verify that the server
they are talking to has a key pair that was signed by the certificate authority. A man-in-the-middle
attacker would not have access to the certificate authority, so they couldn't create a server
with such a key pair.
+
+For TLS authentication, the server uses the **trust cert** to verify that the client has
a key pair that was signed by the certificate authority. The Common Name of the **client cert**
is then used as the client's role token (see [Overview](../overview)).
+
+## Creating TLS Certificates
+
+Creating TLS certificates for Pulsar involves creating a [certificate authority](#certificate-authority)
(CA), [server certificate](#server-certificate), and [client certificate](#client-certificate).
+
+The following guide is an abridged guide to setting up a certificate authority. For a more
detailed guide, there are plenty of resource on the internet. We recommend the [this guide](https://jamielinux.com/docs/openssl-certificate-authority/index.html).
+
+### Certificate authority
+
+The first step is to create the certificate for the CA. The CA will be used to sign both
the broker and client certificates, in order to ensure that each party will trust the others.
The CA should be stored in a very secure location (ideally completely disconnected from networks,
air gapped, and fully encrypted).
+
+Create a directory for your CA, and place [this openssl configuration file](../openssl.cnf)
in the directory. You may want to modify the default answers for company name and department
in the configuration file. Export the location of the CA directory to the environment variable,
CA_HOME. The configuration file uses this environment variable to find the rest of the files
and directories needed for the CA.
+
+```bash
+$ mkdir my-ca
+$ cd my-ca
+$ wget {{ "/docs/latest/security/openssl.cnf" | absolute_url }}
+$ export CA_HOME=$(pwd)
+```
+
+Create the necessary directories, keys and certs.
+
+```bash
+$ mkdir certs crl newcerts private
+$ chmod 700 private/
+$ touch index.txt
+$ echo 1000 > serial
+$ openssl genrsa -aes256 -out private/ca.key.pem 4096
+$ chmod 400 private/ca.key.pem
+$ openssl req -config openssl.cnf -key private/ca.key.pem \
+      -new -x509 -days 7300 -sha256 -extensions v3_ca \
+      -out certs/ca.cert.pem
+$ chmod 444 certs/ca.cert.pem
+```
+
+After answering the question prompts, this will store CA-related files in the `./my-ca` directory.
Within that directory:
+
+* `certs/ca.cert.pem` is the public certificate. It is meant to be distributed to all parties
involved.
+* `private/ca.key.pem` is the private key. This is only needed when signing a new certificate
for either broker or clients and it must be safely guarded.
+
+### Server certificate
+
+Once a CA certificate has been created, you can create certificate requests and sign them
with the CA.
+
+The following commands will ask you a few questions and then create the certificates. When
asked for the common name, you should match the hostname of the broker. You could also use
a wildcard to match a group of broker hostnames, for example `*.broker.usw.example.com`. This
ensures that the same certificate can be reused on multiple machines.
+
+{% include admonition.html type="info" content="Sometimes it is not possible or makes no
sense to match the hostname, such as when the brokers are created with random hostnames, or
you plan to connect to the hosts via their IP. In this case, the client should be configured
to disable TLS hostname verification." %}
+
+First generate the key.
+```bash
+$ openssl genrsa -out broker.key.pem 2048
+```
+
+The broker expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format,
so convert it.
+
+```bash
+$ openssl pkcs8 -topk8 -inform PEM -outform PEM \
+      -in broker.key.pem -out broker.key-pk8.pem -nocrypt
+```
+
+Generate the certificate request...
+
+```bash
+$ openssl req -config openssl.cnf \
+      -key broker.key.pem -new -sha256 -out broker.cert.pem
+```
+
+... and sign it with the certificate authority.
+```bash
+$ openssl ca -config openssl.cnf -extensions server_cert \
+      -days 1000 -notext -md sha256 \
+      -in broker.csr.pem -out broker.cert.pem
+```
+
+At this point, you have a cert, `broker.cert.pem`, and a key, `broker.key-pk8.pem`, which
can be used along with `ca.cert.pem` to configure TLS transport encryption for your broker
and proxy nodes.
+
+## Broker Configuration
+
+To configure a Pulsar {% popover broker %} to use TLS transport encryption, you'll need to
make some changes to `broker.conf`, which is located in the `conf` directory of your [Pulsar
installation](../../getting-started/LocalCluster).
+
+Add these values to the configuration file (substituting the appropriate certificate paths
where necessary):
+
+```properties
+tlsEnabled=true
+tlsCertificateFilePath=/path/to/broker.cert.pem
+tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+```
+
+{% include message.html id="broker_conf_doc" %}
+
+# Proxy Configuration
+
+Proxies need to configure TLS in two directions, for clients connecting to the proxy, and
for the proxy to be able to connect to brokers.
+
+```properties
+# For clients connecting to the proxy
+tlsEnabledInProxy=true
+tlsCertificateFilePath=/path/to/broker.cert.pem
+tlsKeyFilePath=/path/to/broker.key-pk8.pem
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+
+# For the proxy to connect to brokers
+tlsEnabledWithBroker=true
+brokerClientTrustCertsFilePath=/path/to/ca.cert.pem
+```
+
+## Client configuration
+
+When TLS transport encryption is enabled, you need to configure the client to use ```https://```
and port 8443 for the web service URL, and ```pulsar+ssl://``` and port 6651 for the broker
service URL.
+
+As the server certificate you generated above doesn't belong to any of the default trust
chains, you also need to either specify the path the **trust cert** (recommended), or tell
the client to allow untrusted server certs.
+
+### CLI tools
+
+[Command-line tools](../../reference/CliTools) like [`pulsar-admin`](../../reference/CliTools#pulsar-admin),
[`pulsar-perf`](../../reference/CliTools#pulsar-perf), and [`pulsar-client`](../../reference/CliTools#pulsar-client)
use the `conf/client.conf` config file in a Pulsar installation.
+
+You'll need to add the following parameters to that file to use TLS transport with Pulsar's
CLI tools:
+
+```properties
+webServiceUrl=https://broker.example.com:8443/
+brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+```
+
+### Java client
+
+```java
+import org.apache.pulsar.client.api.PulsarClient;
+
+PulsarClient client = PulsarClient.builder()
+    .serviceUrl("pulsar+ssl://broker.example.com:6651/")
+    .enableTls(true)
+    .tlsTrustCertsFilePath("/path/to/ca.cert.pem")
+    .build();
+```
+
+### Python client
+
+```python
+from pulsar import Client
+
+client = Client("pulsar+ssl://broker.example.com:6651/",
+                tls_trust_certs_file_path="/path/to/ca.cert.pem",
+                tls_allow_insecure_connection=False)
+```
+
+### C++ client
+
+```c++
+#include <pulsar/Client.h>
+
+pulsar::ClientConfiguration config;
+config.setUseTls(true);
+config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
+config.setTlsAllowInsecureConnection(false);
+
+pulsar::Client client("pulsar+ssl://broker.example.com:6651/", config);
+```
diff --git a/site/docs/latest/security/tls.md b/site/docs/latest/security/tls.md
index f343eeeb9c..acacab2740 100644
--- a/site/docs/latest/security/tls.md
+++ b/site/docs/latest/security/tls.md
@@ -1,5 +1,5 @@
 ---
-title: Encryption and Authentication using TLS
+title: Authentication using TLS
 ---
 
 <!--
@@ -23,139 +23,133 @@ title: Encryption and Authentication using TLS
 
 -->
 
-## TLS Overview
+## TLS Authentication Overview
 
-With [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) authentication, the server
authenticates the client (also called “2-way authentication”).
-Since TLS authentication requires TLS encryption, this page shows you how to configure both
at the same time.
+TLS authentication is an extension of [TLS transport encryption](../tls-transport), but instead
of only servers having keys and certs which the client uses the verify the server's identity,
clients also have keys and certs which the server uses to verify the client's identity. You
must have TLS transport encryption configured on your cluster before you can use TLS authentication.
This guide assumes you already have TLS transport encryption configured.
 
-By default, Apache Pulsar communicates in plain text service url, which means that all data
is sent in the clear.
-To encrypt communication, it is recommended to configure all the Apache Pulsar components
in your deployment to use TLS encryption.
+### Creating client certificates
 
-TLS can be configured for encryption or authentication. You may configure just TLS encryption
-(by default TLS encryption includes certificate authentication of the server) and independently
choose a separate mechanism
-for client authentication, e.g. TLS, [Athenz](../athenz), etc. Note that TLS encryption,
technically speaking, already enables
-1-way authentication in which the client authenticates the server certificate. So when referring
to TLS authentication, it is really
-referring to 2-way authentication in which the broker also authenticates the client certificate.
+Client certificates are generated using the same certificate authority as was used to generate
the server certificates.
 
-> Note that enabling TLS may have a performance impact due to encryption overhead.
+The biggest difference between client certs and server certs is that the **common name**
for the client certificate is the **role token** which that client will be authenticated as.
 
-## Creating TLS Certificates
-
-Creating TLS certificates for Pulsar involves creating a [certificate authority](#certificate-authority)
(CA), [broker certificate](#broker-certificate), and [client certificate](#client-certificate).
+First generate the key.
+```bash
+$ openssl genrsa -out admin.key.pem 2048
+```
 
-### Certificate authority
+Similar to the broker, the client expects the key to be in [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8)
format, so convert it.
 
-The first step is to create the certificate for the CA. The CA will be used to sign both
the broker and client certificates, in order to ensure that each party will trust the others.
+```bash
+$ openssl pkcs8 -topk8 -inform PEM -outform PEM \
+      -in admin.key.pem -out admin.key-pk8.pem -nocrypt
+```
 
-#### Linux
+Generate the certificate request. When asked for a **common name**, enter the **role token**
which you want this key pair to authenticate a client as.
 
 ```bash
-$ CA.pl -newca
+$ openssl req -config openssl.cnf \
+      -key admin.key.pem -new -sha256 -out admin.cert.pem
 ```
 
-#### macOS
+Sign with request with the certificate authority. Note that that client certs uses the **usr_cert**
extension, which allows the cert to be used for client authentication.
 
 ```bash
-$ /System/Library/OpenSSL/misc/CA.pl -newca
+$ openssl ca -config openssl.cnf -extensions usr_cert \
+      -days 1000 -notext -md sha256 \
+      -in admin.csr.pem -out admin.cert.pem
 ```
 
-After answering the question prompts, this will store CA-related files in the `./demoCA`
directory. Within that directory:
+This will give you a cert, `admin.cert.pem`, and a key, `admin.key-pk8.pem`, which, with
`ca.cert.pem`, can be used by clients to authenticate themselves to brokers and proxies as
the role token ``admin``.
 
-* `demoCA/cacert.pem` is the public certificate. It is meant to be distributed to all parties
involved.
-* `demoCA/private/cakey.pem` is the private key. This is only needed when signing a new certificate
for either broker or clients and it must be safely guarded.
+## Enabling TLS Authentication ...
 
-### Broker certificate
+### ... on Brokers
 
-Once a CA certificate has been created, you can create certificate requests and sign them
with the CA.
+To configure brokers to authenticate clients, put the following in `broker.conf`, alongside
[the configuration to enable tls transport](../tls-transport#broker-configuration):
 
-The following commands will ask you a few questions and then create the certificates. When
asked for the common name, you need to match the hostname of the broker. You could also use
a wildcard to match a group of broker hostnames, for example `*.broker.usw.example.com`. This
ensures that the same certificate can be reused on multiple machines.
-
-```shell
-$ openssl req \
-  -newkey rsa:2048 \
-  -sha256 \
-  -nodes \
-  -out broker-cert.csr \
-  -outform PEM
+```properties
+# Configuration to enable authentication
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
 ```
 
-Convert the key to [PKCS 8](https://en.wikipedia.org/wiki/PKCS_8) format:
+### ... on Proxies
 
-```shell
-$ openssl pkcs8 \
-  -topk8 \
-  -inform PEM \
-  -outform PEM \
-  -in privkey.pem \
-  -out broker-key.pem \
-  -nocrypt
-```
-
-This will create two broker certificate files named `broker-cert.csr` and `broker-key.pem`.
Now you can create the signed certificate:
+To configure proxies to authenticate clients, put the folling in `proxy.conf`, alongside
[the configuration to enable tls transport](../tls-transport#proxy-configuration):
 
-```shell
-$ openssl ca \
-  -out broker-cert.pem \
-  -infiles broker-cert.csr
-```
+The proxy should have its own client key pair for connecting to brokers. The role token for
this key pair should be configured in the ``proxyRoles`` of the brokers. See the [authorization
guide](../authorization) for more details.
 
-At this point, you should have a `broker-cert.pem` and `broker-key.pem` file. These will
be needed for the broker.
+```properties
+# For clients connecting to the proxy
+authenticationEnabled=true
+authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
 
-### Client certificate
+# For the proxy to connect to brokers
+brokerClientAuthenticationPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
+brokerClientAuthenticationParameters=tlsCertFile:/path/to/proxy.cert.pem,tlsKeyFile:/path/to/proxy.key-pk8.pem
+```
 
-To create a client certificate, repeat the steps in the previous section, but did create
`client-cert.pem` and `client-key.pem` files instead.
+## Client configuration
 
-For the client common name, you need to use a string that you intend to use as the [role
token](../overview#role-tokens) for this client, though it doesn't need to match the client
hostname.
+When TLS authentication, the client needs to connect via TLS transport, so you need to configure
the client to use ```https://``` and port 8443 for the web service URL, and ```pulsar+ssl://```
and port 6651 for the broker service URL.
 
-## Configure the broker for TLS
+### CLI tools
 
-To configure a Pulsar {% popover broker %} to use TLS authentication, you'll need to make
some changes to the `broker.conf` configuration file, which is located in the `conf` directory
of your [Pulsar installation](../../getting-started/LocalCluster).
+[Command-line tools](../../reference/CliTools) like [`pulsar-admin`](../../reference/CliTools#pulsar-admin),
[`pulsar-perf`](../../reference/CliTools#pulsar-perf), and [`pulsar-client`](../../reference/CliTools#pulsar-client)
use the `conf/client.conf` config file in a Pulsar installation.
 
-Add these values to the configuration file (substituting the appropriate certificate paths
where necessary):
+You'll need to add the following parameters to that file to use TLS authentication with Pulsar's
CLI tools:
 
 ```properties
-# Enable TLS and point the broker to the right certs
-tlsEnabled=true
-tlsCertificateFilePath=/path/to/broker-cert.pem
-tlsKeyFilePath=/path/to/broker-key.pem
-tlsTrustCertsFilePath=/path/to/cacert.pem
-
-# Enable the TLS auth provider
-authenticationEnabled=true
-authorizationEnabled=true
-authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderTls
+webServiceUrl=https://broker.example.com:8443/
+brokerServiceUrl=pulsar+ssl://broker.example.com:6651/
+useTls=true
+tlsAllowInsecureConnection=false
+tlsTrustCertsFilePath=/path/to/ca.cert.pem
+authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
+authParams=tlsCertFile:/path/to/my-role.cert.pem,tlsKeyFile:/path/to/my-role.key-pk8.pem
 ```
 
-{% include message.html id="broker_conf_doc" %}
+### Java client
 
-## Configure the discovery service
+```java
+import org.apache.pulsar.client.api.PulsarClient;
 
-The {% popover discovery %} service used by Pulsar brokers needs to redirect all HTTPS requests,
which means that it needs to be trusted by the client as well. Add this configuration in `conf/discovery.conf`
in your Pulsar installation:
-
-```properties
-tlsEnabled=true
-tlsCertificateFilePath=/path/to/broker-cert.pem
-tlsKeyFilePath=/path/to/broker-key.pem
+PulsarClient client = PulsarClient.builder()
+    .serviceUrl("pulsar+ssl://broker.example.com:6651/")
+    .enableTls(true)
+    .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")
+    .build();
 ```
 
-## Configure clients
+### Python client
 
-For more information on Pulsar client authentication using TLS, see the following language-specific
docs:
+```python
+from pulsar import Client, AuthenticationTLS
 
-* [Java client](../../clients/Java)
-* [C++ client](../../clients/Cpp)
+auth = AuthenticationTLS("/path/to/my-role.cert.pem", "/path/to/my-role.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,
+				authentication=auth)
+```
 
-## Configure CLI tools
+### C++ client
 
-[Command-line tools](../../reference/CliTools) like [`pulsar-admin`](../../reference/CliTools#pulsar-admin),
[`pulsar-perf`](../../reference/CliTools#pulsar-perf), and [`pulsar-client`](../../reference/CliTools#pulsar-client)
use the `conf/client.conf` config file in a Pulsar installation.
+```c++
+#include <pulsar/Client.h>
 
-You'll need to add the following authentication parameters to that file to use TLS with Pulsar's
CLI tools:
+pulsar::ClientConfiguration config;
+config.setUseTls(true);
+config.setTlsTrustCertsFilePath("/path/to/ca.cert.pem");
+config.setTlsAllowInsecureConnection(false);
 
-```properties
-serviceUrl=https://broker.example.com:8443/
-authPlugin=org.apache.pulsar.client.impl.auth.AuthenticationTls
-authParams=tlsCertFile:/path/to/client-cert.pem,tlsKeyFile:/path/to/client-key.pem
-useTls=true
-tlsAllowInsecureConnection=false
-tlsTrustCertsFilePath=/path/to/cacert.pem
+pulsar::AuthenticationPtr auth = pulsar::AuthTls::create("/path/to/my-role.cert.pem",
+                                                         "/path/to/my-role.key-pk8.pem")
+config.setAuth(auth);
+
+pulsar::Client client("pulsar+ssl://broker.example.com:6651/", config);
 ```
+


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

Mime
View raw message