Flow 32 --- Key Derivation Functions (KDFs) Comparison

/** **************************************************************************
 * FILE: ExampleScenario32.java
 * SCENARIO: Key Derivation Functions (KDFs) Comparison for Composite Keys
 * TAGS: composite-keys, kdf, hkdf, catkdf, caskdf, etsi
 *************************************************************************** */
package co.ankatech.ankasecure.sdk.examples;

import co.ankatech.ankasecure.sdk.AnkaSecureSdk;
import co.ankatech.ankasecure.sdk.model.*;

import static co.ankatech.ankasecure.sdk.examples.ExampleUtil.*;

/**
 * <h1>Scenario 32: Key Derivation Functions (KDFs) Comparison</h1>
 * <p>
 * Demonstrates all 5 supported KDFs for composite hybrid keys, explaining their
 * differences, use cases, and regulatory compliance requirements.
 * </p>
 *
 * <h3>What You'll Learn:</h3>
 * <ul>
 *   <li>How KDFs combine classical and PQC secrets in HYBRID_KEM_COMBINE mode</li>
 *   <li>Differences between HKDF-SHA256, HKDF-SHA512, KMAC256, CatKDF, and CasKDF</li>
 *   <li>Which KDFs are required/allowed by regulatory frameworks</li>
 *   <li>Performance and security trade-offs</li>
 * </ul>
 *
 * <h3>KDF Selection Matrix:</h3>
 * <table border="1">
 *   <tr>
 *     <th>KDF</th>
 *     <th>Standard</th>
 *     <th>Use Case</th>
 *     <th>Regulatory</th>
 *   </tr>
 *   <tr>
 *     <td>HKDF-SHA256</td>
 *     <td>NIST SP 800-56C</td>
 *     <td>Universal (default)</td>
 *     <td>✅ ALL</td>
 *   </tr>
 *   <tr>
 *     <td>HKDF-SHA512</td>
 *     <td>NIST SP 800-56C</td>
 *     <td>High security (Level 5)</td>
 *     <td>✅ ALL</td>
 *   </tr>
 *   <tr>
 *     <td>KMAC256</td>
 *     <td>NIST SP 800-185</td>
 *     <td>Post-quantum margin</td>
 *     <td>✅ NIST only</td>
 *   </tr>
 *   <tr>
 *     <td>CatKDF</td>
 *     <td>ETSI TS 103 744</td>
 *     <td>EU 5G/6G telecom</td>
 *     <td>✅ ETSI required</td>
 *   </tr>
 *   <tr>
 *     <td>CasKDF</td>
 *     <td>ETSI TS 103 744</td>
 *     <td>EU telecom (alt)</td>
 *     <td>✅ ETSI allowed</td>
 *   </tr>
 * </table>
 *
 *
 * @see Kdf
 * @see RegulatoryTemplate
 */
public class ExampleScenario32 {

    public static void main(String[] args) {
        try {
            System.out.println("=================================================================");
            System.out.println("  SCENARIO 32: KDF Comparison for Composite Keys");
            System.out.println("=================================================================\n");

            // Initialize SDK
            java.util.Properties props = loadProperties();
            AnkaSecureSdk sdk = authenticate(props);

            // Universal KDFs
            demonstrateHkdfSha256(sdk);
            demonstrateHkdfSha512(sdk);

            // Post-quantum margin
            demonstrateKmac256(sdk);

            // EU Telecom specific
            demonstrateCatKdf(sdk);
            demonstrateCasKdf(sdk);

            System.out.println("\n=================================================================");
            System.out.println("  ALL 5 KDFs DEMONSTRATED SUCCESSFULLY");
            System.out.println("=================================================================");

        } catch (Exception e) {
            fatal("Scenario 32 failed", e);
        }
    }

    /**
     * Demonstrates HKDF-SHA256 (universal, recommended).
     */
    private static void demonstrateHkdfSha256(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[1/5] HKDF-SHA256 - Universal (DEFAULT)");
        System.out.println("      Standard: NIST SP 800-56C Rev. 2");
        System.out.println("      Compliance: ✅ NIST, BSI, ANSSI, ETSI\n");

        GenerateCompositeKeySpec spec = CompositeKeyBuilder
            .forEncryption("kdf_hkdf_sha256_" + System.currentTimeMillis())
            .withAlgorithmCatalog(sdk.getSupportedAlgorithms())
            .withSecurityLevel(NistSecurityLevel.LEVEL_3)
            .withKdf(Kdf.HKDF_SHA256)
            .build();

        System.out.println("      Properties:");
        System.out.println("      - Output: 256 bits");
        System.out.println("      - Security: 128-bit strength");
        System.out.println("      - Performance: ⚡⚡⚡ Excellent (hardware-accelerated)");
        System.out.println("      - Use Case: General-purpose production");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Key generated with HKDF-SHA256: " + result.getKid() + "\n");
    }

    /**
     * Demonstrates HKDF-SHA512 (high security).
     */
    private static void demonstrateHkdfSha512(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[2/5] HKDF-SHA512 - High Security");
        System.out.println("      Standard: NIST SP 800-56C Rev. 2");
        System.out.println("      Compliance: ✅ NIST, BSI, ANSSI, ETSI\n");

        GenerateCompositeKeySpec spec = CompositeKeyBuilder
            .forEncryption("kdf_hkdf_sha512_" + System.currentTimeMillis())
            .withAlgorithmCatalog(sdk.getSupportedAlgorithms())
            .withSecurityLevel(NistSecurityLevel.LEVEL_5)
            .build(); // Auto-selects HKDF-SHA512 for Level 5

        System.out.println("      Properties:");
        System.out.println("      - Output: 512 bits");
        System.out.println("      - Security: 256-bit strength");
        System.out.println("      - Performance: ⚡⚡ Good (~30% slower than SHA-256)");
        System.out.println("      - Use Case: Government, defense, Level 5 requirements");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Key generated with HKDF-SHA512: " + result.getKid() + "\n");
    }

    /**
     * Demonstrates KMAC256 (post-quantum security margin).
     */
    private static void demonstrateKmac256(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[3/5] KMAC256 - Post-Quantum Margin");
        System.out.println("      Standard: NIST SP 800-185 (SHA-3 family)");
        System.out.println("      Compliance: ✅ NIST, ⚠️ Under review by BSI/ANSSI\n");

        GenerateCompositeKeySpec spec = CompositeKeyBuilder
            .forEncryption("kdf_kmac256_" + System.currentTimeMillis())
            .withAlgorithmCatalog(sdk.getSupportedAlgorithms())
            .withSecurityLevel(NistSecurityLevel.LEVEL_3)
            .withKdf(Kdf.KMAC256)
            .build();

        System.out.println("      Properties:");
        System.out.println("      - Output: 256 bits");
        System.out.println("      - Security: Post-quantum margin (SHA-3 sponge construction)");
        System.out.println("      - Performance: ⚡⚡ Moderate (limited hardware support)");
        System.out.println("      - Use Case: Hedging against SHA-2 cryptanalysis");
        System.out.println("      - Note: Diversification from SHA-2 family");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Key generated with KMAC256: " + result.getKid() + "\n");
    }

    /**
     * Demonstrates CatKDF (EU Telecom - ETSI TS 103 744).
     */
    private static void demonstrateCatKdf(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[4/5] CatKDF - EU Telecommunications (ETSI PRIMARY)");
        System.out.println("      Standard: ETSI TS 103 744 v1.1.1 Section 5.2.1");
        System.out.println("      Compliance: ✅ ETSI (REQUIRED), BSI\n");

        // Using factory method (simplest)
        GenerateCompositeKeySpec spec = RegulatoryTemplateFactory.etsiHybrid(
            "kdf_catkdf_" + System.currentTimeMillis(),
            GenerateCompositeKeySpec.Mode.HYBRID_KEM_COMBINE
        );

        System.out.println("      Properties:");
        System.out.println("      - Algorithm: Concatenation-based KDF");
        System.out.println("      - Output: 256 bits");
        System.out.println("      - Performance: ⚡⚡⚡ Excellent (simple concatenation + hash)");
        System.out.println("      - Use Case: EU 5G/6G networks, telecom infrastructure");
        System.out.println("      - Regulatory: REQUIRED for ETSI TS 103 744 compliance");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Key generated with CatKDF: " + result.getKid());
        System.out.println("      Template: ETSI_HYBRID_ENFORCED\n");
    }

    /**
     * Demonstrates CasKDF (EU Telecom - ETSI TS 103 744 alternative).
     */
    private static void demonstrateCasKdf(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[5/5] CasKDF - EU Telecommunications (ETSI ALTERNATIVE)");
        System.out.println("      Standard: ETSI TS 103 744 v1.1.1 Section 5.2.2");
        System.out.println("      Compliance: ✅ ETSI (allowed), BSI\n");

        GenerateCompositeKeySpec spec = CompositeKeyBuilder
            .forEncryption("kdf_caskdf_" + System.currentTimeMillis())
            .withAlgorithmCatalog(sdk.getSupportedAlgorithms())
            .withSecurityLevel(NistSecurityLevel.LEVEL_3)
            .withKdf(Kdf.CAS_KDF)
            .build();

        System.out.println("      Properties:");
        System.out.println("      - Algorithm: Cascade-based KDF (iterative)");
        System.out.println("      - Output: 256 bits");
        System.out.println("      - Performance: ⚡⚡⚡ Excellent (sequential hash construction)");
        System.out.println("      - Use Case: EU telecom (when CatKDF not applicable)");
        System.out.println("      - Difference: Sequential processing vs simple concatenation");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Key generated with CasKDF: " + result.getKid() + "\n");
    }

}