This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch camel-3.20.x
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/camel-3.20.x by this push:
new 2621b58d1d0 camel-crypto: Updated docs with examples and gpg usage
(#10156)
2621b58d1d0 is described below
commit 2621b58d1d05eaba5aa9d07c14e742ce71045b4e
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 9e85d7e84c9..1ef70141aad 100644
--- a/components/camel-crypto/src/main/docs/crypto-component.adoc
+++ b/components/camel-crypto/src/main/docs/crypto-component.adoc
@@ -112,6 +112,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
@@ -123,15 +137,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.
@@ -141,22 +182,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
@@ -167,19 +210,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]
-------------------------------------------------------------------------------------------------
@@ -189,8 +228,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 0c4b9db4301..120866ffcba 100644
--- a/components/camel-crypto/src/main/docs/crypto-dataformat.adoc
+++ b/components/camel-crypto/src/main/docs/crypto-dataformat.adoc
@@ -85,7 +85,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
@@ -116,9 +116,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]
@@ -153,14 +151,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]
----------------------------------------------------------
@@ -183,8 +178,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]
----------------------------------------------------------
@@ -214,7 +208,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"
@@ -237,12 +231,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 854058f2fcf..30411a489a9 100644
--- a/components/camel-crypto/src/main/docs/pgp-dataformat.adoc
+++ b/components/camel-crypto/src/main/docs/pgp-dataformat.adoc
@@ -26,8 +26,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",]
|=======================================================================
@@ -89,8 +89,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
@@ -125,19 +140,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.