[pulsar] branch master updated: [docs] Fix encryption examples (#6763)

[si...@apache.org]

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 65ff6ac  [docs] Fix encryption examples (#6763)
65ff6ac is described below

commit 65ff6ac2ab11416840ad55349934278935cecc20
Author: Alex Yaroslavsky <tr...@gmail.com>
AuthorDate: Mon Apr 27 10:52:05 2020 +0300

    [docs] Fix encryption examples (#6763)
    
    * Fix encryption examples
    
    * Minor grammar fix
    
    Co-Authored-By: Yu Liu <50...@users.noreply.github.com>
    
    Co-authored-by: Yu Liu <50...@users.noreply.github.com>
---
 site2/docs/security-encryption.md | 42 +++++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/site2/docs/security-encryption.md b/site2/docs/security-encryption.md
index 388b1d0..0ce319c 100644
--- a/site2/docs/security-encryption.md
+++ b/site2/docs/security-encryption.md
@@ -30,16 +30,16 @@ Pulsar does not store the encryption key anywhere in the Pulsar service. If you
 
 ```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
+openssl ec -in test_ecdsa_privkey.pem -pubout -outform pem -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 Pulsar client invokes to load the key.
+3. Implement the CryptoKeyReader interface, specifically CryptoKeyReader.getPublicKey() for producer and CryptoKeyReader.getPrivateKey() for consumer, which Pulsar client invokes to load the key.
 
-4. Add encryption key to producer configuration: conf.addEncryptionKey("myapp.key").
+4. Add encryption key name to producer builder: PulsarClient.newProducer().addEncryptionKey("myapp.key").
 
-5. Add CryptoKeyReader implementation to producer or consumer config: conf.setCryptoKeyReader(keyReader).
+5. Add CryptoKeyReader implementation to producer or consumer builder: PulsarClient.newProducer().cryptoKeyReader(keyReader) / PulsarClient.newConsumer().cryptoKeyReader(keyReader).
 
 6. Sample producer application:
 
@@ -78,18 +78,20 @@ class RawFileKeyReader implements CryptoKeyReader {
         return keyInfo;
     }
 }
-PulsarClient pulsarClient = PulsarClient.create("http://localhost:8080");
 
-ProducerConfiguration prodConf = new ProducerConfiguration();
-prodConf.setCryptoKeyReader(new RawFileKeyReader("test_ecdsa_pubkey.pem", "test_ecdsa_privkey.pem"));
-prodConf.addEncryptionKey("myappkey");
+PulsarClient pulsarClient = PulsarClient.builder().serviceUrl("pulsar://localhost:6650").build();
 
-Producer producer = pulsarClient.createProducer("persistent://my-tenant/my-ns/my-topic", prodConf);
+Producer producer = pulsarClient.newProducer()
+                .topic("persistent://my-tenant/my-ns/my-topic")
+                .addEncryptionKey("myappkey")
+                .cryptoKeyReader(new RawFileKeyReader("test_ecdsa_pubkey.pem", "test_ecdsa_privkey.pem"))
+                .create();
 
 for (int i = 0; i < 10; i++) {
     producer.send("my-message".getBytes());
 }
 
+producer.close();
 pulsarClient.close();
 ```
 7. Sample Consumer Application:
@@ -130,10 +132,12 @@ class RawFileKeyReader implements CryptoKeyReader {
     }
 }
 
-ConsumerConfiguration consConf = new ConsumerConfiguration();
-consConf.setCryptoKeyReader(new RawFileKeyReader("test_ecdsa_pubkey.pem", "test_ecdsa_privkey.pem"));
-PulsarClient pulsarClient = PulsarClient.create("http://localhost:8080");
-Consumer consumer = pulsarClient.subscribe("persistent://my-tenant/my-ns/my-topic", "my-subscriber-name", consConf);
+PulsarClient pulsarClient = PulsarClient.builder().serviceUrl("pulsar://localhost:6650").build();
+Consumer consumer = pulsarClient.newConsumer()
+                .topic("persistent://my-tenant/my-ns/my-topic")
+                .subscriptionName("my-subscriber-name")
+                .cryptoKeyReader(new RawFileKeyReader("test_ecdsa_pubkey.pem", "test_ecdsa_privkey.pem"))
+                .subscribe();
 Message msg = null;
 
 for (int i = 0; i < 10; i++) {
@@ -144,11 +148,12 @@ for (int i = 0; i < 10; i++) {
 
 // Acknowledge the consumption of all messages at once
 consumer.acknowledgeCumulative(msg);
+consumer.close();
 pulsarClient.close();
 ```
 
 ## Key rotation
-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.
+Pulsar generates a 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.
 
 ## 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:
@@ -160,16 +165,15 @@ When producers want to encrypt the messages with multiple keys, producers add al
 If you need to encrypt the messages using 2 keys (myapp.messagekey1 and myapp.messagekey2), refer to the following example.
 
 ```java
-conf.addEncryptionKey("myapp.messagekey1");
-conf.addEncryptionKey("myapp.messagekey2");
+PulsarClient.newProducer().addEncryptionKey("myapp.messagekey1").addEncryptionKey("myapp.messagekey2");
 ```
 ## 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.
 
 ## Handle failures
 * Producer/ Consumer loses access to the key
-  * 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.
+  * Producer action fails indicating the cause of the failure. Application has the option to proceed with sending unencrypted message in such cases. Call PulsarClient.newProducer().cryptoFailureAction(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 PulsarClient.newConsumer().cryptoFailureAction(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 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 and the message contains batch messages, client is not able to retrieve individual messages in the batch, hence message consumption fails even if cryptoFailureAction() is set to ConsumerCryptoFailureAction.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.