Flow 31 --- Security Level Matching and Validation

/** **************************************************************************
 * FILE: ExampleScenario31.java
 * SCENARIO: Security Level Matching for Composite Keys
 * TAGS: composite-keys, security-levels, nist, validation
 *************************************************************************** */
package co.ankatech.ankasecure.sdk.examples;

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

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

/**
 * <h1>Scenario 31: Security Level Matching for Composite Keys</h1>
 * <p>
 * Demonstrates the importance of matching NIST security levels between classical
 * and post-quantum components in composite keys. Shows valid matches and invalid
 * mismatches with detailed error handling.
 * </p>
 *
 * <h3>What You'll Learn:</h3>
 * <ul>
 *   <li>Why security level matching is critical</li>
 *   <li>How to create keys at different NIST levels (1, 3, 5)</li>
 *   <li>What happens when security levels mismatch</li>
 *   <li>Client-side validation with {@link CompositeKeyValidator}</li>
 * </ul>
 *
 * <h3>NIST Security Levels:</h3>
 * <table border="1">
 *   <tr>
 *     <th>Level</th>
 *     <th>Bit Strength</th>
 *     <th>Classical Example</th>
 *     <th>PQC Example</th>
 *   </tr>
 *   <tr>
 *     <td>1</td>
 *     <td>128-bit</td>
 *     <td>RSA-2048</td>
 *     <td>ML-KEM-512</td>
 *   </tr>
 *   <tr>
 *     <td>3</td>
 *     <td>192-bit</td>
 *     <td>X25519, RSA-3072</td>
 *     <td>ML-KEM-768</td>
 *   </tr>
 *   <tr>
 *     <td>5</td>
 *     <td>256-bit</td>
 *     <td>RSA-4096</td>
 *     <td>ML-KEM-1024</td>
 *   </tr>
 * </table>
 *
 *
 * @see NistSecurityLevel
 * @see CompositeKeyValidator#validateSecurityLevelMatch(java.util.List, AlgorithmCompatibilityResolver)
 */
public class ExampleScenario31 {

    public static void main(String[] args) {
        try {
            System.out.println("=================================================================");
            System.out.println("  SCENARIO 31: Security Level Matching");
            System.out.println("=================================================================\n");

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

            // Valid matches
            demonstrateLevel3Match(sdk);
            demonstrateLevel5Match(sdk);

            // Invalid mismatches
            demonstrateMismatchDetection(sdk);

            System.out.println("\n=================================================================");
            System.out.println("  SECURITY LEVEL MATCHING DEMONSTRATED SUCCESSFULLY");
            System.out.println("=================================================================");

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

    /**
     * Demonstrates valid Level 3 (192-bit) security level matching.
     */
    private static void demonstrateLevel3Match(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[1/3] VALID: Level 3 Matching (RECOMMENDED)");
        System.out.println("      Use Case: Standard production (95% of deployments)\n");

        // Using builder auto-selection
        GenerateCompositeKeySpec spec = CompositeKeyBuilder
            .forEncryption("level3_auto_" + System.currentTimeMillis())
            .withAlgorithmCatalog(sdk.getSupportedAlgorithms())
            .withSecurityLevel(NistSecurityLevel.LEVEL_3)
            .withKdf(Kdf.HKDF_SHA256)
            .build();

        System.out.println("      Configuration:");
        System.out.println("      - Classical: X25519 (Level 3 - 192-bit)");
        System.out.println("      - PQC: ML-KEM-768 (Level 3 - 192-bit)");
        System.out.println("      - Security Match: ✅ BOTH Level 3");
        System.out.println("      - Performance: ⚡⚡⚡ Excellent");
        System.out.println("      - Compliance: ✅ BSI, ANSSI, ETSI, NIST");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Level 3 key generated: " + result.getKid());
        System.out.println("      Status: " + result.getStatus() + "\n");
    }

    /**
     * Demonstrates valid Level 5 (256-bit) security level matching.
     */
    private static void demonstrateLevel5Match(AnkaSecureSdk sdk) throws Exception {
        System.out.println("[2/3] VALID: Level 5 Matching (HIGH SECURITY)");
        System.out.println("      Use Case: Government, defense, classified data\n");

        GenerateCompositeKeySpec spec = CompositeKeyBuilder
            .forEncryption("level5_classified_" + System.currentTimeMillis())
            .withAlgorithmCatalog(sdk.getSupportedAlgorithms())
            .withSecurityLevel(NistSecurityLevel.LEVEL_5)
            .build(); // Auto-selects algorithms and KDF

        System.out.println("      Configuration:");
        System.out.println("      - Classical: RSA-4096 (Level 5 - 256-bit)");
        System.out.println("      - PQC: ML-KEM-1024 (Level 5 - 256-bit)");
        System.out.println("      - Security Match: ✅ BOTH Level 5");
        System.out.println("      - KDF: HKDF-SHA512 (auto-selected for Level 5)");
        System.out.println("      - Performance: ⚠️ Slower (acceptable for high-security)");
        System.out.println("      - Use Case: Top Secret / TS-SCI data");

        KeyGenerationSummarySpec result = sdk.generateCompositeKey(spec);
        System.out.println("      ✅ Level 5 key generated: " + result.getKid());
        System.out.println("      Status: " + result.getStatus() + "\n");
    }

    /**
     * Demonstrates security level mismatch detection (client-side validation).
     */
    private static void demonstrateMismatchDetection(AnkaSecureSdk sdk) {
        System.out.println("[3/3] INVALID: Security Level Mismatch (DETECTED)");
        System.out.println("      Demonstrating client-side validation error\n");

        try {
            // Intentional mismatch: RSA-2048 (Level 1) + ML-KEM-1024 (Level 5)
            // NIST SP 800-227 allows up to ±2 level difference, so we use Level 1 vs Level 5 (difference = 4)
            GenerateCompositeKeySpec invalidSpec = new GenerateCompositeKeySpec()
                .setKid("invalid_mismatch")
                .setMode(GenerateCompositeKeySpec.Mode.HYBRID_KEM_COMBINE)
                .addComponent(ComponentSpec.classical(ClassicalCompositeAlgorithm.RSA_2048))   // Level 1
                .addComponent(ComponentSpec.pqc(PqcCompositeAlgorithm.ML_KEM_1024))           // Level 5
                .setKdf(Kdf.HKDF_SHA256);

            System.out.println("      Configuration (INVALID):");
            System.out.println("      - Classical: RSA-2048 (Level 1 - 128-bit)");
            System.out.println("      - PQC: ML-KEM-1024 (Level 5 - 256-bit)");
            System.out.println("      - Security Match: ❌ MISMATCH (1 != 5, diff = 4)");
            System.out.println("      - Allowed: ±2 levels difference (per NIST SP 800-227)");

            // This will throw InvalidInputException
            CompositeKeyValidator.validate(invalidSpec, new ServerAlgorithmResolver(sdk.getSupportedAlgorithms()));

            // If we reach here, validation failed to catch the error
            System.err.println("      ❌ ERROR: Validation should have failed!");

        } catch (InvalidInputException e) {
            System.out.println("\n      ✅ Validation correctly detected mismatch:");
            System.out.println("      Error: " + e.getMessage());
            System.out.println("      \n      Reason: NIST SP 800-227 allows up to ±2 security level");
            System.out.println("      difference, but this example has 4 levels difference (1 vs 5),");
            System.out.println("      which would create an unacceptable weak point in the hybrid key.\n");
        }
    }

}