Flow 1 – ML-KEM-512 Stream Encrypt / Decrypt (Detached JWET)
This scenario shows a complete post-quantum encryption round-trip with the streaming endpoints:
- Generate a PQC key-pair (
ML-KEM-512). - Export its public metadata.
- Stream-encrypt a plaintext file → detached JWET (General-JSON header + binary part).
- Stream-decrypt the ciphertext.
- Validate that the decrypted data matches the original.
Key points
- Leverages the streaming helpers encryptFileStream / decryptFileStream, letting you encrypt or decrypt multi-gigabyte files while holding only a few kB in memory.\
- Emits a detached JWET (General JSON): header + tag stay in a tiny JSON structure, the raw ciphertext streams as-is — zero Base64 expansion, ideal for direct‐to-disk or direct-to-object-store writes.\
- Illustrates a full post-quantum ML-KEM-512 life-cycle (generate key ➜ export metadata ➜ encrypt ➜ decrypt) and surfaces rich key-usage telemetry in HTTP headers so you can monitor rotations, expiry or soft-limit warnings in real time.
When to use it
- Massive datasets that must stay encrypted at rest — think nightly database dumps, genomic archives, video libraries or research data running into tens or hundreds of GB. Streaming keeps RAM flat while detached JWET avoids Base64 bloat.
- Write-once / read-seldom storage tiers — because the ciphertext is pure binary, you can pipe it straight to S3, GCS, Azure Blob or tape without post-processing; the slim JSON header is all you need to catalogue or audit the object later.
- Long-term confidentiality with quantum resilience — ML-KEM-512 protects backups and legal holds that must remain secret beyond the expected RSA/ECC break horizon, giving confidence for 10- to 20-year data-retention mandates.
Dependency — this example imports
co.ankatech.ankasecure.sdk.examples.ExampleUtil.
If you have not copied that class yet, see example_util.md.
Complete Java implementation
src/main/java/co/ankatech/ankasecure/sdk/examples/ExampleScenario1.java
/* *****************************************************************************
* FILE: ExampleScenario1.java
* ****************************************************************************/
package co.ankatech.ankasecure.sdk.examples;
import co.ankatech.ankasecure.sdk.AnkaSecureSdk;
import co.ankatech.ankasecure.sdk.model.DecryptResultMetadata;
import co.ankatech.ankasecure.sdk.model.EncryptResult;
import co.ankatech.ankasecure.sdk.model.ExportedKeySpec;
import co.ankatech.ankasecure.sdk.model.GenerateKeySpec;
import co.ankatech.ankasecure.sdk.util.FileIO;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.attribute.FileAttribute;
import java.text.MessageFormat;
import java.util.Properties;
import static co.ankatech.ankasecure.sdk.examples.ExampleUtil.*;
/**
* <h2>Scenario 1 – End-to-end ML-KEM-512 Life-cycle (Streaming)</h2>
*
* <p>This scenario demonstrates an <em>end-to-end</em> post-quantum key
* life-cycle using the <strong>streaming</strong> encryption / decryption
* endpoints of <span style="font-variant: small-caps;">ANKASecure</span>.
* In <em>streaming</em> mode the platform produces a <strong>detached
* JWE (General JSON / “JWET”)</strong> where the {@code ciphertext} and
* {@code tag} fields are {@code null} and are instead delivered in the second
* multipart section. The non-streaming API would return a single compact JWE
* string.</p>
*
* <ol>
* <li>Generate a post-quantum ML-KEM-512 key-pair.</li>
* <li>Export its public metadata to JSON.</li>
* <li>Stream-encrypt a local file (detached JWE).</li>
* <li>Stream-decrypt the ciphertext.</li>
* <li>Validate round-trip integrity.</li>
* </ol>
*
* <p><strong>Prerequisite:</strong> the CLI configuration must contain a valid
* access token.</p>
*
* <p><b>Implementation notes (Java 21+):</b></p>
* <ul>
* <li>All file handling relies on the {@link java.nio.file.Path} API.</li>
* <li>Encoding is explicitly set to {@link StandardCharsets#UTF_8} to avoid
* platform-dependent defaults.</li>
* <li>Directory creation leverages {@link Files#createDirectories(Path, FileAttribute[])}.</li>
* </ul>
*
* <p><strong>Thread-safety:</strong> the class is stateless and immutable –
* a new instance of {@link AnkaSecureSdk} is created inside {@code main} and
* locally confined to that thread.</p>
*
* @author ANKATech – Security Engineering
* @since 2.1.0
*/
public final class ExampleScenario1 {
/* ====================================================================== */
/**
* Entry-point.
*
* @param args ignored
*/
public static void main(String[] args) {
System.out.println("===== SCENARIO 1 START =====");
System.out.println("""
Purpose :
* Generate ML-KEM-512
* Export metadata
* Stream-encrypt (detached JWE) / stream-decrypt
* Validate integrity
--------------------------------------------------------------""");
try {
ensureTempDir();
Properties props = loadProperties();
AnkaSecureSdk sdk = authenticate(props);
runScenario(sdk);
} catch (Exception ex) {
fatal("Scenario 1 failed", ex);
}
System.out.println("===== SCENARIO 1 END =====");
}
/* ====================================================================== */
/**
* Executes the individual steps of Scenario 1.
*
* @param sdk a fully authenticated {@link AnkaSecureSdk} instance
*
* @throws Exception if any step fails
*/
private static void runScenario(final AnkaSecureSdk sdk) throws Exception {
final String kid = "sc1_kem_" + System.currentTimeMillis();
// File system artefacts ------------------------------------------------
Path plainFile = TEMP_DIR.resolve("scenario1_plain.txt");
Path encFile = TEMP_DIR.resolve("scenario1.enc");
Path decFile = TEMP_DIR.resolve("scenario1.dec");
Path exportJson = TEMP_DIR.resolve("scenario1_keydata.json");
/* 1 ── plaintext ----------------------------------------------------- */
FileIO.writeUtf8(
plainFile,
"Hello Scenario-1 – streaming encryption demo!");
System.out.println("[1] Plaintext ready -> " + plainFile.toAbsolutePath());
/* 2 ── key generation ------------------------------------------------ */
GenerateKeySpec spec = new GenerateKeySpec()
.setKid(kid)
.setKty("ML-KEM")
.setAlg("ML-KEM-512");
sdk.generateKey(spec);
System.out.println("[2] Key generated -> kid = " + kid);
/* 3 ── export metadata ---------------------------------------------- */
ExportedKeySpec exported = sdk.exportKey(kid);
FileIO.writeUtf8(
exportJson,
toJson(exported));
System.out.println("[3] Metadata exported -> " + exportJson.toAbsolutePath());
/* 4 ── streaming encrypt (detached JWE) ----------------------------- */
EncryptResult encMeta = sdk.encryptFileStream(kid, plainFile, encFile);
System.out.println(MessageFormat.format(
"[4] Ciphertext written -> {0}", encFile.toAbsolutePath()));
printEncryptionMeta(encMeta);
/* 5 ── streaming decrypt -------------------------------------------- */
DecryptResultMetadata decMeta = sdk.decryptFileStream(encFile, decFile);
System.out.println(MessageFormat.format(
"[5] Decrypted file -> {0}", decFile.toAbsolutePath()));
printDecryptionMeta(decMeta);
/* 6 ── validation ---------------------------------------------------- */
String original = FileIO.readUtf8(plainFile);
String recovered = FileIO.readUtf8(decFile);
System.out.println(original.equals(recovered)
? "[6] Validation OK – plaintext matches."
: "[6] WARNING – plaintext mismatch!");
}
/**
* Private constructor prevents instantiation.
*/
private ExampleScenario1() {
/* no-instantiation */
}
}
How to run
Console milestones:
-
ML-KEM-512 key creation
-
Metadata export →
scenario1_keydata.json -
Detached-JWET stream-encryption →
scenario1.enc -
Stream-decryption →
scenario1.dec -
Validation OK -- byte-perfect round-trip