This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/main by this push:
     new 8d2b84392b7 camel-crypto: Updated docs with examples and gpg usage 
(#10156)
8d2b84392b7 is described below

commit 8d2b84392b7a2ad69c7326272733b63499587985
Author: Darren Coleman <[email protected]>
AuthorDate: Fri May 19 11:35:21 2023 +0100

    camel-crypto: Updated docs with examples and gpg usage (#10156)
---
 .../src/main/docs/crypto-component.adoc            | 83 ++++++++++++++++------
 .../src/main/docs/crypto-dataformat.adoc           | 22 +++---
 .../camel-crypto/src/main/docs/pgp-dataformat.adoc | 37 ++++++++--
 3 files changed, 101 insertions(+), 41 deletions(-)

diff --git a/components/camel-crypto/src/main/docs/crypto-component.adoc 
b/components/camel-crypto/src/main/docs/crypto-component.adoc
index d86d4673fa7..f963d836b35 100644
--- a/components/camel-crypto/src/main/docs/crypto-component.adoc
+++ b/components/camel-crypto/src/main/docs/crypto-component.adoc
@@ -113,6 +113,20 @@ include::partial$component-endpoint-headers.adoc[]
 The most basic way to sign and verify an exchange is with a
 KeyPair as follows.
 
+[source,java]
+----
+KeyPair keyPair = KeyGenerator.getInstance("RSA").generateKeyPair();
+
+from("direct:sign")
+    .setHeader(DigitalSignatureConstants.SIGNATURE_PRIVATE_KEY, 
constant(keys.getPrivate()))
+    .to("crypto:sign:message")
+    .to("direct:verify");
+
+from("direct:verify")
+    .setHeader(DigitalSignatureConstants.SIGNATURE_PUBLIC_KEY_OR_CERT, 
constant(keys.getPublic()))
+    .to("crypto:verify:check");
+----
+
 The same can be achieved with the 
xref:manual::spring-xml-extensions.adoc[Spring
 XML Extensions] using references to keys
 
@@ -124,15 +138,42 @@ protected. They can be retrieved by applying an alias to 
the retrieval
 APIs. There are a number of ways to get keys and Certificates into a
 keystore, most often this is done with the external 'keytool'
 application.
-http://www.exampledepot.com/egs/java.security.cert/CreateCert.html[This]
-is a good example of using keytool to create a KeyStore with a self
-signed Cert and Private key.
 
-The examples use a Keystore with a key and cert aliased by 'bob'. The
-password for the keystore and the key is 'letmein'
+The following command will create a keystore containing a key and certificate 
aliased by `bob`, which can be used in the following examples. The password for 
the keystore and the key is `letmein`.
+
+[source,sh]
+----
+keytool -genkey -keyalg RSA -keysize 2048 -keystore keystore.jks -storepass 
letmein -alias bob -dname "CN=Bob,OU=IT,O=Camel" -noprompt
+----
+
+The following route first signs an exchange using Bob's alias from the 
KeyStore bound into the Camel Registry, and then verifies it using the same 
alias.
+
+[source,java]
+----
+from("direct:sign")
+    
.to("crypto:sign:keystoreSign?alias=bob&keystoreName=myKeystore&password=letmein")
+    .log("Signature: ${header.CamelDigitalSignature}")
+    
.to("crypto:verify:keystoreVerify?alias=bob&keystoreName=myKeystore&password=letmein")
+    .log("Verified: ${body}");
+----
 
-The following shows how to use a Keystore via the Fluent builders, it
-also shows how to load and initialize the keystore.
+The following code shows how to load the keystore created using the above 
`keytool` command and bind it into the registry with the name `myKeystore` for 
use in the above route. The example makes use of the `@Configuration` and 
`@BindToRegistry` annotations introduced in Camel 3 to instantiate the KeyStore 
and register it with the name `myKeyStore`.
+
+[source,java]
+----
+@Configuration
+public class KeystoreConfig {
+    
+    @BindToRegistry
+    public KeyStore myKeystore() throws Exception {
+        KeyStore store = KeyStore.getInstance("JKS");
+        try (FileInputStream fis = new FileInputStream("keystore.jks")) {
+            store.load(fis, "letmein".toCharArray());
+        }
+        return store;
+    }
+}
+----
 
 Again in Spring a ref is used to lookup an actual keystore instance.
 
@@ -142,22 +183,24 @@ Changing the Signature algorithm or the Security provider 
is a simple
 matter of specifying their names. You will need to also use Keys that
 are compatible with the algorithm you choose.
 
-or
-
 === Changing the Signature Message Header
 
 It may be desirable to change the message header used to store the
 signature. A different header name can be specified in the route
 definition as follows
 
-or
+[source,java]
+----
+from("direct:sign")
+    
.to("crypto:sign:keystoreSign?alias=bob&keystoreName=myKeystore&password=letmein&signatureHeaderName=mySignature")
+    .log("Signature: ${header.mySignature}")
+    
.to("crypto:verify:keystoreVerify?alias=bob&keystoreName=myKeystore&password=letmein&signatureHeaderName=mySignature");
+----
 
 === Changing the bufferSize
 
 In case you need to update the size of the buffer...
 
-or
-
 === Supplying Keys dynamically.
 
 When using a Recipient list or similar EIP the recipient of an exchange
@@ -168,19 +211,15 @@ then be dynamically enriched with the key of its target 
recipient prior
 to signing. To facilitate this the signature mechanisms allow for keys
 to be supplied dynamically via the message headers below
 
-* `Exchange.SIGNATURE_PRIVATE_KEY`, `"CamelSignaturePrivateKey"`
-* `Exchange.SIGNATURE_PUBLIC_KEY_OR_CERT`, `"CamelSignaturePublicKeyOrCert"`
-
-or
+* `DigitalSignatureConstants.SIGNATURE_PRIVATE_KEY`, 
`"CamelSignaturePrivateKey"`
+* `DigitalSignatureConstants.SIGNATURE_PUBLIC_KEY_OR_CERT`, 
`"CamelSignaturePublicKeyOrCert"`
 
 Even better would be to dynamically supply a keystore alias. Again the
 alias can be supplied in a message header
 
-* `Exchange.KEYSTORE_ALIAS`, `"CamelSignatureKeyStoreAlias"`
-
-or
+* `DigitalSignatureConstants.KEYSTORE_ALIAS`, `"CamelSignatureKeyStoreAlias"`
 
-The header would be set as follows
+The header would be set as follows:
 
 [source,java]
 
-------------------------------------------------------------------------------------------------
@@ -190,8 +229,8 @@ 
unsigned.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_ALIAS, "bob");
 unsigned.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_PASSWORD, 
"letmein".toCharArray());
 template.send("direct:alias-sign", unsigned);
 Exchange signed = getMandatoryEndpoint("direct:alias-sign").createExchange();
-signed.getIn().copyFrom(unsigned.getOut());
-signed.getIn().setHeader(KEYSTORE_ALIAS, "bob");
+signed.getIn().copyFrom(unsigned.getMessage());
+signed.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_ALIAS, "bob");
 template.send("direct:alias-verify", signed);
 
-------------------------------------------------------------------------------------------------
 
diff --git a/components/camel-crypto/src/main/docs/crypto-dataformat.adoc 
b/components/camel-crypto/src/main/docs/crypto-dataformat.adoc
index d8e6cfbbae0..a48018094a8 100644
--- a/components/camel-crypto/src/main/docs/crypto-dataformat.adoc
+++ b/components/camel-crypto/src/main/docs/crypto-dataformat.adoc
@@ -86,7 +86,7 @@ from("direct:hmac-algorithm")
     .to("mock:unencrypted");
 ----------------------------------------------------------
 
-A list of the available algorithms in Java 7 is available via the Java 
Cryptography Architecture Standard Algorithm Name Documentation.
+A list of the available algorithms in Java 17 is available via the 
https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html[Java
 Security Standard Algorithm Names] documentation.
 
 
 == Specifying an Initialization Vector
@@ -117,9 +117,7 @@ or with spring, suppling a reference to a byte[]
 <crypto id="initvector" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" 
initVectorRef="initializationVector" />
 ----------------------------------------------------------
 
-The same vector is required in both the encryption and decryption phases. As 
it is not necessary to keep the IV a secret,
-the DataFormat allows for it to be inlined into the encrypted data and 
subsequently read out in the decryption
-phase to initialize the Cipher. To inline the IV set the /oinline flag.
+The same vector is required in both the encryption and decryption phases. As 
it is not necessary to keep the IV a secret, the DataFormat allows for it to be 
inlined into the encrypted data and subsequently read out in the decryption 
phase to initialize the Cipher. To inline the IV set the `Inline` flag.
 
 
 [source,java]
@@ -154,14 +152,11 @@ For more information of the use of Initialization 
Vectors, consult
 
 * http://en.wikipedia.org/wiki/Initialization_vector
 * http://www.herongyang.com/Cryptography/
-* http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation
+* http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
 
 
 == Hashed Message Authentication Codes (HMAC)
-To avoid attacks against the encrypted data while it is in transit the 
CryptoDataFormat can also calculate a Message Authentication
-Code for the encrypted exchange contents based on a configurable MAC 
algorithm. The calculated HMAC is appended to the stream after encryption.
-It is separated from the stream in the decryption phase. The MAC is 
recalculated and verified against the transmitted version to insure nothing
-was tampered with in transit.For more information on Message Authentication 
Codes see http://en.wikipedia.org/wiki/HMAC
+To avoid attacks against the encrypted data while it is in transit the 
CryptoDataFormat can also calculate a Message Authentication Code for the 
encrypted exchange contents based on a configurable MAC algorithm. The 
calculated HMAC is appended to the stream after encryption. It is separated 
from the stream in the decryption phase. The MAC is recalculated and verified 
against the transmitted version to ensure nothing was tampered with in transit. 
For more information on Message Authentica [...]
 
 [source,java]
 ----------------------------------------------------------
@@ -184,8 +179,7 @@ or with spring.
 <crypto id="hmac" algorithm="DES" keyRef="desKey" shouldAppendHMAC="true" />
 ----------------------------------------------------------
 
-By default the HMAC is calculated using the HmacSHA1 mac algorithm though this 
can be easily changed by supplying a different algorithm name.
-See here for how to check what algorithms are available through the configured 
security providers
+By default the HMAC is calculated using the HmacSHA1 mac algorithm though this 
can be easily changed by supplying a different algorithm name. See here for how 
to check what algorithms are available through the configured security providers
 
 [source,java]
 ----------------------------------------------------------
@@ -215,7 +209,7 @@ or with spring.
 When using a Recipient list or similar EIP the recipient of an exchange can 
vary dynamically.
 Using the same key across all recipients may neither be feasible or desirable. 
It would be useful to be able to specify
 keys dynamically on a per exchange basis. The exchange could then be 
dynamically enriched with the key of its target
-recipient before being processed by the data format. To facilitate this the 
DataFormat allow for keys to be supplied
+recipient before being processed by the data format. To facilitate this the 
DataFormat allows for keys to be supplied
 dynamically via the message headers below
 
 * CryptoDataFormat.KEY "CamelCryptoKey"
@@ -238,12 +232,12 @@ from("direct:key-in-header-encrypt")
 from("direct:key-in-header-decrypt").unmarshal(cryptoFormat).process(new 
Processor() {
     public void process(Exchange exchange) throws Exception {
         exchange.getIn().getHeaders().remove(CryptoDataFormat.KEY);
-        exchange.getOut().copyFrom(exchange.getIn());
+        exchange.getMessage().copyFrom(exchange.getIn());
     }
 }).to("mock:unencrypted");
 ----------------------------------------------------------
 
-or with spring.
+or with spring:
 
 [source,xml]
 ----------------------------------------------------------
diff --git a/components/camel-crypto/src/main/docs/pgp-dataformat.adoc 
b/components/camel-crypto/src/main/docs/pgp-dataformat.adoc
index 6991c58ccbc..723a2833ff6 100644
--- a/components/camel-crypto/src/main/docs/pgp-dataformat.adoc
+++ b/components/camel-crypto/src/main/docs/pgp-dataformat.adoc
@@ -27,8 +27,8 @@ include::partial$dataformat-options.adoc[]
 
 == PGPDataFormat Message Headers
 
-You can override the PGPDataFormat options by applying below headers
-into message dynamically.
+You can override the PGPDataFormat options by applying the below headers
+into messages dynamically.
 
 [width="70%",cols="10%,10%,80%",options="header",]
 |=======================================================================
@@ -90,8 +90,23 @@ The following sample performs signing + encryption, and then 
signature
 verification + decryption. It uses the same keyring for both signing and
 encryption, but you can obviously use different keys:
 
+[source,java]
+----
+from("direct:pgp-encrypt")
+    .marshal().pgp("file:pubring.gpg", "[email protected]")
+    .unmarshal().pgp("file:secring.gpg", "[email protected]", "letmein");
+----
 Or using Spring:
 
+[source,xml]
+----
+<route>
+  <from uri="direct:encrypt"/>
+  <marshal><pgp keyFileName="file:pubring.gpg" 
keyUserid="[email protected]"/></marshal>
+  <unmarshal><pgp keyFileName="file:secring.gpg" keyUserid="[email protected]" 
password="letmein"/></unmarshal>
+</route>
+----
+
 === To work with the previous example you need the following
 
 * A public keyring file which contains the public keys used to encrypt
@@ -126,19 +141,31 @@ If you need to import someone elses public key so that 
you can encrypt a file fo
 --------------------------
 gpg --import <filename.key
 --------------------------
-The following files should now exist and can be used to run the example
+If you are using GnuPG versions prior to 2.1, the key formats are stored in 
different files that can be used for the example. You can check if the required 
files exist by running the following command:
 
 [source,bash]
 -----------------------------------------------
 ls -l ~/.gnupg/pubring.gpg ~/.gnupg/secring.gpg
 -----------------------------------------------
 
+However, starting from GnuPG 2.1, the key formats were changed to improve 
efficiency and flexibility. Unfortunately, these new formats cannot be directly 
used with the Bouncy Castle libraries, which are used to implement the PGP data 
format. For more details about the changes to the key formats, you can refer to 
the https://gnupg.org/faq/whats-new-in-2.1.html[GnuPG FAQ].
+
+In the newer GnuPG versions, the `pubring.gpg` file is replaced with a keybox 
file named `pubring.kbx`. Additionally, the `secring.gpg` file is replaced with 
several files with a `.key` extension located in the 
`~/.gnupg/private-keys-v1.d` directory.
+
+To export the keys to the older format that can be used with PGP data format, 
you can execute the following commands:
+
+[source,bash]
+----
+gpg --export > pubring.gpg
+gpg --export-secret-keys > secring.gpg
+----
+
 
[[Crypto-PGPDecryptingVerifyingofMessagesEncryptedSignedbyDifferentPrivatePublicKeys]]
 == PGP Decrypting/Verifying of Messages Encrypted/Signed by Different 
Private/Public Keys
 
-A PGP Data Formater can decrypt/verify messages which have been
+A PGP Data Formatter can decrypt/verify messages which have been
 encrypted by different public keys or signed by different private keys.
-Just, provide the corresponding private keys in the secret keyring, the
+Just provide the corresponding private keys in the secret keyring, the
 corresponding public keys in the public keyring, and the passphrases in
 the passphrase accessor.
 

Reply via email to