Flow 19 – PKCS#7/CMS Structural Analysis

/*
 * Copyright 2025 ANKATech Solutions Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package co.ankatech.ankasecure.sdk.examples;

import co.ankatech.ankasecure.sdk.AuthenticatedSdk;
import co.ankatech.secure.client.model.Pkcs7AnalysisRequest;
import co.ankatech.secure.client.model.Pkcs7AnalysisResponse;
import co.ankatech.secure.client.model.RecipientMetadata;
import co.ankatech.secure.client.model.SignerMetadata;

import java.io.File;
import java.util.List;
import java.util.Properties;

import static co.ankatech.ankasecure.sdk.examples.ExampleUtil.authenticate;
import static co.ankatech.ankasecure.sdk.examples.ExampleUtil.fatal;
import static co.ankatech.ankasecure.sdk.examples.ExampleUtil.loadProperties;

/**
 * Scenario 19 — PKCS#7/CMS Structural Analysis (data-plane).
 *
 * <p>Demonstrates the keyless inspection side of the PKCS#7 migration surface: the SDK
 * reports the structure of a legacy PKCS#7/CMS artifact (format, recipients, signers,
 * encryption parameters, support status and the recommended JOSE migration path) WITHOUT
 * any decryption key. Structural analysis never touches key material, so it is the safe
 * first step when assessing a body of legacy CMS files for migration.</p>
 *
 * <h3>Why analysis needs no key</h3>
 * <ul>
 *   <li><strong>Envelope metadata only:</strong> the CMS header exposes content type,
 *       recipient and signer descriptors, and the content-encryption algorithm in the clear.</li>
 *   <li><strong>The recipient-key id is optional:</strong> supplying one would let the platform
 *       additionally validate decryptability, but the structure report stands on its own.</li>
 *   <li><strong>Data-plane only:</strong> no keystore import, no key provisioning &mdash; those
 *       are control-plane concerns handled outside the SDK (see {@link ExampleScenario20}).</li>
 * </ul>
 *
 * <h3>Steps:</h3>
 * <ol>
 *   <li>Load the packaged, non-sensitive EnvelopedData fixture (single recipient, zero signers)</li>
 *   <li>Compact analysis: {@code analyzePkcs7} over the Base64 of the fixture (no key)</li>
 *   <li>Streaming analysis: {@code analyzePkcs7Stream} over the same fixture materialized to a file</li>
 *   <li>Print the structured report and confirm the two modes agree on the detected structure</li>
 * </ol>
 *
 * <h3>API Endpoints:</h3>
 * <ul>
 *   <li>POST /api/v3/migration/analyze-pkcs7 (compact analysis)</li>
 *   <li>POST /api/v3/migration/stream/analyze-pkcs7 (streaming analysis)</li>
 * </ul>
 *
 * <p><strong>Prerequisite:</strong> a {@code cli.properties} for a data-plane actor of the
 * provisioned playground. No pre-provisioned key and no recipient-key id are required for
 * analysis &mdash; the conversion counterpart that needs a recipient key is
 * {@link ExampleScenario20}.</p>
 *
 * @see ExampleUtil
 * @see Pkcs7ExampleFixture
 * @see ExampleScenario20
 * @see AuthenticatedSdk
 */
public final class ExampleScenario19 {

    /** No instantiation &mdash; this class only exposes {@link #main(String[])}. */
    private ExampleScenario19() { }

    /**
     * Runs the PKCS#7/CMS structural-analysis scenario.
     *
     * @param args command-line arguments (ignored)
     */
    public static void main(String[] args) {
        System.out.println("===== SCENARIO 19: PKCS#7/CMS STRUCTURAL ANALYSIS =====");
        System.out.println("Purpose: Inspect a legacy PKCS#7/CMS artifact WITHOUT any decryption key");
        System.out.println("Modes  : compact (analyzePkcs7) + streaming (analyzePkcs7Stream)");
        System.out.println("Key    : none — analysis is key-independent (data-plane)");
        System.out.println();

        try {
            Properties props = loadProperties();
            AuthenticatedSdk sdk = authenticate(props);
            runScenario(sdk);

            System.out.println("===== SCENARIO 19 END =====");

        } catch (Exception ex) {
            fatal("Scenario 19 failed", ex);
        }
    }

    private static void runScenario(AuthenticatedSdk sdk) throws Exception {

        // ============================================================
        // PHASE 1: Compact analysis — Base64 payload, no key
        // ============================================================

        System.out.println("[Step 1/3] Compact analysis (analyzePkcs7), no decryption key...");
        Pkcs7AnalysisRequest compactRequest = new Pkcs7AnalysisRequest()
                .pkcs7Data(Pkcs7ExampleFixture.envelopedDataBase64());
        // Intentionally NO recipient-key id: structural analysis is key-independent.
        Pkcs7AnalysisResponse compact = sdk.analyzePkcs7(compactRequest);
        printAnalysis("compact", compact);
        System.out.println();

        // ============================================================
        // PHASE 2: Streaming analysis — same fixture as a file
        // ============================================================

        System.out.println("[Step 2/3] Streaming analysis (analyzePkcs7Stream) over a file...");
        File pkcs7File = Pkcs7ExampleFixture.materializeToTempFile();
        // The streaming call takes no options either: analysis needs no key.
        Pkcs7AnalysisResponse stream = sdk.analyzePkcs7Stream(pkcs7File);
        printAnalysis("stream", stream);
        System.out.println();

        // ============================================================
        // PHASE 3: Parity check between the two modes
        // ============================================================

        System.out.println("[Step 3/3] Confirming compact and streaming agree on the structure...");
        String compactStructure = structureOf(compact);
        String streamStructure = structureOf(stream);
        if (compactStructure.equals(streamStructure)) {
            System.out.println("           ✅ Both modes detected: " + compactStructure);
        } else {
            System.out.println("           ❌ Mode mismatch — compact=" + compactStructure
                    + " stream=" + streamStructure);
        }
    }

    /** Prints the structured analysis report using the real {@link Pkcs7AnalysisResponse} accessors. */
    private static void printAnalysis(final String mode, final Pkcs7AnalysisResponse resp) {
        System.out.println("           [" + mode + "] PKCS#7 analysis:");

        if (resp.getDetectedFormat() != null) {
            System.out.println("             Standard      : " + resp.getDetectedFormat().getStandard());
            System.out.println("             Structure     : " + resp.getDetectedFormat().getStructure());
            System.out.println("             Content-Type  : " + resp.getDetectedFormat().getContentTypeOID());
            System.out.println("             Encoding      : " + resp.getDetectedFormat().getEncoding());
        }

        // Zero signers is the EXPECTED shape for EnvelopedData — not a fault.
        List<SignerMetadata> signers = resp.getSigners();
        List<RecipientMetadata> recipients = resp.getRecipients();
        System.out.println("             Signers       : " + (signers == null ? 0 : signers.size()));
        System.out.println("             Recipients    : " + (recipients == null ? 0 : recipients.size()));
        if (recipients != null) {
            for (RecipientMetadata r : recipients) {
                System.out.println("               - recipient[" + r.getIndex() + "] "
                        + r.getKeyEncryptionAlgorithm() + " / issuer=" + r.getIssuerDN()
                        + " / serial=" + r.getSerialNumber());
            }
        }

        if (resp.getEncryption() != null) {
            System.out.println("             Content-Enc   : " + resp.getEncryption().getContentEncryptionAlgorithm()
                    + " (iv " + resp.getEncryption().getIvLength() + " bytes)");
        }

        if (resp.getSupportStatus() != null) {
            System.out.println("             Supported     : " + resp.getSupportStatus().getSupported());
            // When NOT supported, print the reasons instead of crashing (graceful degradation).
            if (Boolean.FALSE.equals(resp.getSupportStatus().getSupported())) {
                System.out.println("             Reasons       : " + resp.getSupportStatus().getReasons());
            }
        }

        if (resp.getRecommendations() != null) {
            System.out.println("             Migration     : " + resp.getRecommendations().getMigrationPath()
                    + " (complexity " + resp.getRecommendations().getEstimatedComplexity() + ")");
            if (resp.getRecommendations().getRequiredKeys() != null) {
                System.out.println("             Required keys : "
                        + resp.getRecommendations().getRequiredKeys().size());
            }
        }
    }

    /** Null-safe detected-structure string for the parity check. */
    private static String structureOf(final Pkcs7AnalysisResponse resp) {
        if (resp.getDetectedFormat() == null || resp.getDetectedFormat().getStructure() == null) {
            return "UNKNOWN";
        }
        return resp.getDetectedFormat().getStructure().toString();
    }
}

/*
 * Copyright 2026 ANKATech Solutions Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package co.ankatech.ankasecure.sdk.examples;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

/**
 * Classpath loader for the PKCS#7/CMS example fixture used by the data-plane
 * migration scenarios ({@link ExampleScenario19}, {@link ExampleScenario20}).
 *
 * <p>The fixture {@code /pkcs7/enveloped-data-sample.p7m} is a small, non-sensitive
 * BER/DER-encoded CMS <em>EnvelopedData</em> structure (single recipient, zero signers)
 * produced by a test signer. It carries no private key material and no secret;
 * its encrypted payload is a throwaway test value. It lives under
 * {@code src/main/resources} so the examples are self-contained
 * (the reader does not need to supply a PKCS#7 file to follow the walkthrough).</p>
 *
 * <p>Loading the recipient's private key — required to actually <em>decrypt</em> and
 * convert the EnvelopedData to JWE — is a control-plane concern handled outside the
 * data-plane SDK (see {@link ExampleScenario20}); this helper only supplies the
 * ciphertext to analyze/convert.</p>
 *
 * @see ExampleScenario19
 * @see ExampleScenario20
 */
public final class Pkcs7ExampleFixture {

    /** Classpath location of the packaged EnvelopedData sample. */
    private static final String RESOURCE = "/pkcs7/enveloped-data-sample.p7m";

    /** Temp-file name used by {@link #materializeToTempFile()} for the streaming APIs. */
    private static final String TEMP_FILE_NAME = "enveloped-data-sample.p7m";

    /** No instantiation &mdash; static helper only. */
    private Pkcs7ExampleFixture() { }

    /**
     * Loads the raw DER bytes of the packaged EnvelopedData fixture from the classpath.
     *
     * @return the fixture bytes (never {@code null} or empty)
     * @throws IllegalStateException if the resource is missing from the classpath
     * @throws UncheckedIOException  if the resource cannot be read
     */
    public static byte[] envelopedDataBytes() {
        try (InputStream in = Pkcs7ExampleFixture.class.getResourceAsStream(RESOURCE)) {
            if (in == null) {
                throw new IllegalStateException(
                        "PKCS#7 example fixture not found on the classpath: " + RESOURCE
                        + " — ensure src/main/resources/pkcs7/enveloped-data-sample.p7m is packaged.");
            }
            return in.readAllBytes();
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to read PKCS#7 example fixture " + RESOURCE, e);
        }
    }

    /**
     * Returns the fixture as a Base64 string, suitable for the compact-mode request
     * fields {@code Pkcs7AnalysisRequest.pkcs7Data} / {@code Pkcs7ConversionRequest.pkcs7Data}.
     *
     * @return Base64-encoded fixture bytes
     */
    public static String envelopedDataBase64() {
        return Base64.getEncoder().encodeToString(envelopedDataBytes());
    }

    /**
     * Materializes the fixture to a temporary {@link File} under
     * {@link ExampleUtil#TEMP_DIR}, for the streaming APIs that take a {@code java.io.File}.
     *
     * @return a readable temp {@code File} containing the fixture bytes
     * @throws UncheckedIOException if the temp file cannot be written
     */
    public static File materializeToTempFile() {
        try {
            ExampleUtil.ensureTempDir();
            Path target = ExampleUtil.TEMP_DIR.resolve(TEMP_FILE_NAME);
            Files.write(target, envelopedDataBytes());
            return target.toFile();
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to materialize PKCS#7 example fixture to a temp file", e);
        }
    }
}