This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new c377865 [doc] Improve Pulsar Security Encryption (#5091)
c377865 is described below
commit c377865cd5698b89c0870fcc30d30a4bc7191470
Author: Monica-zy <44013755+monica...@users.noreply.github.com>
AuthorDate: Fri Sep 13 23:56:22 2019 +0800
[doc] Improve Pulsar Security Encryption (#5091)
### Motivation
Improve the language and the overall descriptive style of the Pulsar
Security document (security-encryption section):
http://pulsar.apache.org/docs/en/next/security-encryption/
### Modifications
Adjust the tone, personal pronouns, voice also some typo errors of some
sentences in the document.
---
site2/docs/security-encryption.md | 60 +++++++++++++++++++++------------------
1 file changed, 33 insertions(+), 27 deletions(-)
diff --git a/site2/docs/security-encryption.md
b/site2/docs/security-encryption.md
index 12c2c00..388b1d0 100644
--- a/site2/docs/security-encryption.md
+++ b/site2/docs/security-encryption.md
@@ -4,19 +4,19 @@ title: Pulsar Encryption
sidebar_label: End-to-End Encryption
---
-Pulsar encryption allows applications to encrypt messages at the producer and
decrypt at the consumer. Encryption is performed using the public/private key
pair configured by the application. Encrypted messages can only be decrypted by
consumers with a valid key.
+Applications can use Pulsar encryption to encrypt messages at the producer
side and decrypt messages at the consumer side. You can use the public and
private key pair that the application configures to perform encryption. Only
the consumers with a valid key can decrypt the encrypted messages.
## Asymmetric and symmetric encryption
-Pulsar uses dynamically generated symmetric AES key to encrypt messages(data).
The AES key(data key) is encrypted using application provided ECDSA/RSA key
pair, as a result there is no need to share the secret with everyone.
+Pulsar uses dynamically generated symmetric AES key to encrypt messages(data).
You can use the application provided ECDSA/RSA key pair to encrypt the AES
key(data key), so you do not have to share the secret with everyone.
-Key is a public/private key pair used for encryption/decryption. The producer
key is the public key, and the consumer key is the private key of the key pair.
+Key is a public and private key pair used for encryption or decryption. The
producer key is the public key of the key pair, and the consumer key is the
private key of the key pair.
-The application configures the producer with the public key. This key is used
to encrypt the AES data key. The encrypted data key is sent as part of message
header. Only entities with the private key(in this case the consumer) will be
able to decrypt the data key which is used to decrypt the message.
+The application configures the producer with the public key. You can use this
key to encrypt the AES data key. The encrypted data key is sent as part of
message header. Only entities with the private key (in this case the consumer)
are able to decrypt the data key which is used to decrypt the message.
-A message can be encrypted with more than one key. Any one of the keys used
for encrypting the message is sufficient to decrypt the message
+You can encrypt a message with more than one key. Any one of the keys used for
encrypting the message is sufficient to decrypt the message.
-Pulsar does not store the encryption key anywhere in the pulsar service. If
you lose/delete the private key, your message is irretrievably lost, and is
unrecoverable
+Pulsar does not store the encryption key anywhere in the Pulsar service. If
you lose or delete the private key, your message is irretrievably lost, and is
unrecoverable.
## Producer
@@ -24,19 +24,25 @@ Pulsar does not store the encryption key anywhere in the
pulsar service. If you
## Consumer
-## Here are the steps to get started:
+## Get started
-1. Create your ECDSA or RSA public/private key pair.
+1. Enter the commands below to create your ECDSA or RSA public and private key
pair.
```shell
openssl ecparam -name secp521r1 -genkey -param_enc explicit -out
test_ecdsa_privkey.pem
openssl ec -in test_ecdsa_privkey.pem -pubout -outform pkcs8 -out
test_ecdsa_pubkey.pem
```
+
2. Add the public and private key to the key management and configure your
producers to retrieve public keys and consumers clients to retrieve private
keys.
-3. Implement CryptoKeyReader::getPublicKey() interface from producer and
CryptoKeyReader::getPrivateKey() interface from consumer, which will be invoked
by Pulsar client to load the key.
-4. Add encryption key to producer configuration:
conf.addEncryptionKey("myapp.key")
-5. Add CryptoKeyReader implementation to producer/consumer config:
conf.setCryptoKeyReader(keyReader)
+
+3. Implement CryptoKeyReader::getPublicKey() interface from producer and
CryptoKeyReader::getPrivateKey() interface from consumer, which Pulsar client
invokes to load the key.
+
+4. Add encryption key to producer configuration:
conf.addEncryptionKey("myapp.key").
+
+5. Add CryptoKeyReader implementation to producer or consumer config:
conf.setCryptoKeyReader(keyReader).
+
6. Sample producer application:
+
```java
class RawFileKeyReader implements CryptoKeyReader {
@@ -87,6 +93,7 @@ for (int i = 0; i < 10; i++) {
pulsarClient.close();
```
7. Sample Consumer Application:
+
```java
class RawFileKeyReader implements CryptoKeyReader {
@@ -141,29 +148,28 @@ pulsarClient.close();
```
## Key rotation
-Pulsar generates new AES data key every 4 hours or after a certain number of
messages are published. The asymmetric public key is automatically fetched by
producer every 4 hours by calling CryptoKeyReader::getPublicKey() to retrieve
the latest version.
+Pulsar generates new AES data key every 4 hours or after publishing a certain
number of messages. A producer fetches the asymmetric public key every 4 hours
by calling CryptoKeyReader::getPublicKey() to retrieve the latest version.
-## Enabling encryption at the producer application:
-If you produce messages that are consumed across application boundaries, you
need to ensure that consumers in other applications have access to one of the
private keys that can decrypt the messages. This can be done in two ways:
-1. The consumer application provides you access to their public key, which you
add to your producer keys
-1. You grant access to one of the private keys from the pairs used by producer
+## Enable encryption at the producer application
+If you produce messages that are consumed across application boundaries, you
need to ensure that consumers in other applications have access to one of the
private keys that can decrypt the messages. You can do this in two ways:
+1. The consumer application provides you access to their public key, which you
add to your producer keys.
+2. You grant access to one of the private keys from the pairs that producer
uses.
-In some cases, the producer may want to encrypt the messages with multiple
keys. For this, add all such keys to the config. Consumer will be able to
decrypt the message, as long as it has access to at least one of the keys.
+When producers want to encrypt the messages with multiple keys, producers add
all such keys to the config. Consumer can decrypt the message as long as the
consumer has access to at least one of the keys.
+
+If you need to encrypt the messages using 2 keys (myapp.messagekey1 and
myapp.messagekey2), refer to the following example.
-E.g: If messages needs to be encrypted using 2 keys myapp.messagekey1 and
myapp.messagekey2,
```java
conf.addEncryptionKey("myapp.messagekey1");
conf.addEncryptionKey("myapp.messagekey2");
```
-## Decrypting encrypted messages at the consumer application:
-Consumers require access one of the private keys to decrypt messages produced
by the producer. If you would like to receive encrypted messages, create a
public/private key and give your public key to the producer application to
encrypt messages using your public key.
+## Decrypt encrypted messages at the consumer application
+Consumers require access one of the private keys to decrypt messages that the
producer produces. If you want to receive encrypted messages, create a public
or private key and give your public key to the producer application to encrypt
messages using your public key.
-## Handling Failures:
+## Handle failures
* Producer/ Consumer loses access to the key
- * Producer action will fail indicating the cause of the failure. Application
has the option to proceed with sending unencrypted message in such cases. Call
conf.setCryptoFailureAction(ProducerCryptoFailureAction) to control the
producer behavior. The default behavior is to fail the request.
- * If consumption failed due to decryption failure or missing keys in
consumer, application has the option to consume the encrypted message or
discard it. Call conf.setCryptoFailureAction(ConsumerCryptoFailureAction) to
control the consumer behavior. The default behavior is to fail the request.
-Application will never be able to decrypt the messages if the private key is
permanently lost.
+ * Producer action fails indicating the cause of the failure. Application has
the option to proceed with sending unencrypted message in such cases. Call
conf.setCryptoFailureAction(ProducerCryptoFailureAction) to control the
producer behavior. The default behavior is to fail the request.
+ * If consumption fails due to decryption failure or missing keys in
consumer, application has the option to consume the encrypted message or
discard it. Call conf.setCryptoFailureAction(ConsumerCryptoFailureAction) to
control the consumer behavior. The default behavior is to fail the request.
Application is never able to decrypt the messages if the private key is
permanently lost.
* Batch messaging
- * If decryption fails and the message contain batch messages, client will
not be able to retrieve individual messages in the batch, hence message
consumption fails even if conf.setCryptoFailureAction() is set to CONSUME.
-* If decryption fails, the message consumption stops and application will
notice backlog growth in addition to decryption failure messages in the client
log. If application does not have access to the private key to decrypt the
message, the only option is to skip/discard backlogged messages.
-
+ * If decryption fails and the message contains batch messages, client is not
able to retrieve individual messages in the batch, hence message consumption
fails even if conf.setCryptoFailureAction() is set to CONSUME.
+* If decryption fails, the message consumption stops and application notices
backlog growth in addition to decryption failure messages in the client log. If
application does not have access to the private key to decrypt the message, the
only option is to skip or discard backlogged messages.
