PQC Key Encapsulation/Decapsulation Action
Provided by: "Apache Software Foundation"
Support Level for this Kamelet is: "Stable"
Creates a new secret key for a symmetric cipher, such as AES, together with its encapsulation by a post-quantum algorithm such as ML-KEM, or takes the secret key back out of such an encapsulation.
Use it to try out post-quantum key establishment (a KEM, key encapsulation mechanism): one step creates a secret key and its encapsulation, the protected form of the key that may be sent to the holder of the private key, and a later step takes the same secret key out of it. To encrypt the messages themselves with a fixed key, use crypto-encrypt-action.
Input: for generateSecretKeyEncapsulation, any body; it is not used. For extractSecretKeyEncapsulation and extractSecretKeyFromEncapsulation, the body must be the result of generateSecretKeyEncapsulation.
Output: generateSecretKeyEncapsulation and extractSecretKeyEncapsulation give a Java object that holds the secret key and its encapsulation. extractSecretKeyFromEncapsulation gives the secret key, as a Java object. None of them is text or bytes, so the next step must be one that works with Java key objects.
Good to know: unless the key pair of the post-quantum algorithm comes from keyStore or keyPair, it is created when the application starts, so an encapsulation can be opened only by the same running application. Headers that start with CamelPQC are removed from the message first, so they cannot change what the Kamelet does. With a key pair from a key store, it can be opened after a restart, and by any application that has the key store. When the application has exactly one Java KeyStore, or one KeyPair, it is used even when keyStore or keyPair is not set; keyPairAlias and keyStorePassword are then needed for the key store, else the messages fail.
Configuration Options
The following table summarizes the configuration options available for the pqc-kem-action Kamelet:
| Property | Name | Description | Type | Default | Example |
|---|---|---|---|---|---|
PQC Key Encapsulation Algorithm | Required The post-quantum algorithm that encapsulates the secret key. Enum values: * MLKEM * BIKE * HQC * CMCE * SABER * FRODO * NTRU * NTRULPRime | string | |||
PQC KEM Operation | Required What to do with each message. Enum values: * generateSecretKeyEncapsulation * extractSecretKeyEncapsulation * extractSecretKeyFromEncapsulation | string | |||
Symmetric Key Algorithm | Required The symmetric cipher the secret key is for, such as Enum values: * AES * RC2 * RC5 * ARIA * CAMELLIA * CAST5 * CAST6 * CHACHA7539 * DSTU7624 * GOST28147 * GOST3412_2015 * GRAIN128 * HC128 * HC256 * SALSA20 * SEED * SM4 * DESEDE | string | |||
Key Pair | A Java | string | #bean:pqcKeyPair | ||
Key Pair Alias | The alias, the name in | string | kem | ||
Key Store | A Java | string | #bean:pqcKeyStore | ||
Key Store Password | The password of | string | |||
Symmetric Key Length | The length of the secret key, in bits, such as 128 or 256 for | integer | 128 |
Dependencies
At runtime, the pqc-kem-action Kamelet relies upon the presence of the following dependencies:
-
camel:pqc
-
camel:kamelet
Camel JBang usage
Prerequisites
-
You’ve installed JBang.
-
You have executed the following command:
jbang app install camel@apache/camel Supposing you have a file named route.yaml with this content:
- route:
from:
uri: "kamelet:timer-source"
parameters:
period: 10000
message: 'test'
steps:
- to:
uri: "kamelet:pqc-kem-action"
parameters:
.
.
.
- to:
uri: "kamelet:log-sink" You can now run it directly through the following command
camel run route.yaml PQC Key Encapsulation/Decapsulation Action Kamelet Description
Key Pair
Without keyStore or keyPair, the key pair of the post-quantum algorithm is created when the application starts. An encapsulation can then be opened only by the same running application.
To open an encapsulation after a restart, or in another application, keep the key pair in a key store. Java 24 and later can make an ML-KEM key pair with keytool. A key pair of a KEM cannot sign its own certificate, so keytool needs a signing key pair in the same key store, given with -signer, such as an ML-DSA one:
keytool -genkeypair -alias signer -keyalg ML-DSA -dname CN=signer \
-validity 365 -keystore pqc.p12 -storetype PKCS12 -storepass changeit
keytool -genkeypair -alias kem -keyalg ML-KEM -groupname ML-KEM-768 -dname CN=kem -signer signer \
-validity 365 -keystore pqc.p12 -storetype PKCS12 -storepass changeit The key store is a Java KeyStore object, defined in the application, and referred to with #bean: followed by its name. Set keyPairAlias to the alias of the key pair, and keyStorePassword to the password of the key store, which must also be the password of the key pair.
When the application has exactly one Java KeyStore, or one KeyPair, the Camel PQC component uses it even when keyStore or keyPair is not set. With a key store, keyPairAlias and keyStorePassword must then be set too, else the messages fail.
Key Length
symmetricKeyLength is the length of the secret key in bits, 256 when it is not set. Use the same length to create and to open an encapsulation. Set it to 128 for SEED and SM4, which take only 128-bit keys: with 256, the integration fails to start.
Example
The following route creates a 128-bit AES key and its encapsulation with the key pair kem of the key store pqc.p12, and then takes the same key out of the encapsulation again. The key store is loaded by a Groovy script in the beans section, so that no Java class has to be written; Groovy needs the camel-groovy dependency, which Camel JBang adds by itself.
- beans:
- name: pqcKeyStore
type: java.security.KeyStore
scriptLanguage: groovy
script: "java.security.KeyStore.getInstance(new File('pqc.p12'), '{{pqc.keystore.password}}'.toCharArray())"
- route:
from:
uri: "kamelet:timer-source"
parameters:
period: 10000
message: "start"
steps:
- to:
uri: "kamelet:pqc-kem-action"
parameters:
operation: generateSecretKeyEncapsulation
keyEncapsulationAlgorithm: MLKEM
symmetricKeyAlgorithm: AES
symmetricKeyLength: 128
keyStore: "#bean:pqcKeyStore"
keyPairAlias: kem
keyStorePassword: "{{pqc.keystore.password}}"
- to:
uri: "kamelet:pqc-kem-action"
parameters:
operation: extractSecretKeyEncapsulation
keyEncapsulationAlgorithm: MLKEM
symmetricKeyAlgorithm: AES
symmetricKeyLength: 128
keyStore: "#bean:pqcKeyStore"
keyPairAlias: kem
keyStorePassword: "{{pqc.keystore.password}}"
- to:
uri: "kamelet:log-sink"