Skip to content

Streaming Endpoints in ANKA Secure

ANKA Secure provides streaming-based cryptographic endpoints via the CryptoStreamingApiController. Unlike classic JSON endpoints that accept Base64-encoded data, these endpoints allow raw data to flow in and out without being fully loaded into memory or stored in temporary files. This design supports large-scale file encryption/decryption, signing, or re-encryption with minimal overhead.

1. Motivation & Overview

  • Memory Efficiency: Instead of buffering entire files (which can be very large), data is streamed from the request input stream directly into cryptographic operations, then streamed back to the response.
  • Performance: This approach is more network- and memory-efficient—the data is processed as it arrives, and the output is sent as it is produced.
  • Security: Avoiding temporary files lowers security risks (no leftover artifacts on disk).
  • Multipart: By using multipart/form-data, we can pass small JSON “metadata” (e.g., key alias, algorithm) alongside a “file” part containing raw data.

2. Endpoints Overview

All streaming endpoints live under @RequestMapping("/api/crypto/stream"). The major operations include:

  1. Symmetric

    • Encrypt:
      POST /api/crypto/stream/symmetric/encrypt
      (metadata = SymmetricEncryptionMetadata, file = raw plaintext)
    • Decrypt:
      POST /api/crypto/stream/symmetric/decrypt
      (metadata = SymmetricDecryptionMetadata, file = raw ciphertext)

  2. Asymmetric

    • Encrypt:
      POST /api/crypto/stream/asymmetric/encrypt
      (metadata = AsymmetricEncryptionMetadata, file = plaintext)
    • Decrypt:
      POST /api/crypto/stream/asymmetric/decrypt
      (metadata = AsymmetricDecryptionMetadata, file = ciphertext)

  3. Signing/Verification

    • Sign:
      POST /api/crypto/stream/sign
      (metadata = AsymmetricSignMetadata, file = raw data)
      Returns the signature bytes in application/octet-stream.
    • Verify:
      POST /api/crypto/stream/verify
      (metadata = VerifySignatureMetadata, file = raw data)
      Returns a JSON response { "isValid": true/false }.

  4. Re-encrypt

    • Re-encrypt:
      POST /api/crypto/stream/reencrypt
      (metadata = ReencryptDataMetadata with oldAlias + newAlias, file = old ciphertext)
      Decrypt with oldAlias → re-encrypt with newAlias, all streamed, returning new ciphertext.

  5. Re-sign

    • Resign:
      POST /api/crypto/stream/resign
      (metadata = ResignDataMetadata with oldAlias, newAlias, and oldSignatureBase64, file = data)
      1) Verifies old signature with oldAlias (public key).
      2) If valid, signs data with newAlias (private key).
      3) Streams back the new signature in raw bytes.

  6. Utility (No KeyStore usage)

    • Public Key Encryption:
      POST /api/crypto/stream/asymmetric/publickey-encrypt
      (metadata = AsymmetricPublicKeyUtilityEncryptionMetadata, file = plaintext)
      The public key is supplied in Base64, and no alias is used.
    • Public Key Verification:
      POST /api/crypto/stream/asymmetric/publickey-verify
      (metadata = AsymmetricPublicKeyUtilityVerificationMetadata, file = raw data)
      Checks signature with the provided public key (Base64), returns JSON with { "valid": true/false }.

3. Example Flow: Re-Encryption Endpoint

The re-encrypt endpoint (POST /api/crypto/stream/reencrypt) demonstrates how streaming avoids memory overhead:

  1. Client sends multipart/form-data:

    • metadata (JSON) with "oldAlias" (private key) + "newAlias" (public key).
    • file: old ciphertext.

  2. Controller (reencryptDataStream) checks both aliases.

  3. Builds a StreamingResponseBody to handle output streaming.

  4. Inside a try/finally block:

    • Decrypt the data using oldAlias.
    • Immediately encrypt that plaintext using newAlias.
    • Writes the new ciphertext to the response output stream in real-time.

  5. No large buffers in memory or temporary files are used:

    • The input stream is read in chunks.
    • The output stream is also written in chunks.

  6. The response returns HTTP 200 OK with application/octet-stream.

4. Example Flow: Re-Signing Endpoint

Re-sign (POST /api/crypto/stream/resign) flows similarly, but for signatures:

  1. Client sends multipart/form-data:

    • metadata (JSON) with oldAlias, newAlias, and oldSignatureBase64.
    • file: the raw data that was previously signed.

  2. Controller verifies the old signature with oldAlias (public key):

    • If invalid, returns an error (e.g., 400 or 404).
    • If valid, signs the same data with newAlias (private key).
  3. Streams the new signature (raw bytes) to the client in application/octet-stream.
  4. Avoids loading the entire file or signature in memory. Instead, the data is streamed, and verification plus signing are performed in a chunk-wise manner.

5. Threading & Context Management

Because streaming often involves a separate thread or asynchronous I/O, we must ensure:

  1. Geolocation & Usage: executeWithGeolocationAndUsageVoid
  2. Captures IP, location, user info, request method, and response status in a try/finally.

  3. Logs usage after streaming finishes.

  4. Audit Context: executeWithAuditContextVoid

  5. Similarly captures an AuditEvent (start time, end time, success/failure).

  6. Usage Context: executeWithUsageContextVoid

  7. Preserves a thread-local UsageContextHolder (including a transaction ID in MDC).
  8. Each nested call is in a try/finally, guaranteeing we cleanup even if an exception is thrown.

These nested method calls ensure that usage logging, geolocation, and auditing proceed consistently, even if streaming is done on a separate thread from the main request.

6. No Temporary Files, Minimal Memory

A key design choice:

  • Multipart is handled without standard Spring's auto-file upload (or with minimal auto-handling), meaning we do not store entire uploads in memory.
  • We rely on streaming via MultipartFile.getInputStream(), or disabling spring.servlet.multipart.enabled=false if you parse manually.
  • The output is a StreamingResponseBody, which writes directly to the response OutputStream.

Advantages:

  • Large files (e.g., multi-GB) can be encrypted or re-encrypted without spiking memory usage.
  • Minimizes disk usage and security exposure by avoiding temp files.
  • The user experiences a streaming data flow from client → server → server → client.

7. Additional Operations

In CryptoStreamingApiController you also have:

  1. Symmetric Encryption/Decryption

    • Accepts a SymmetricEncryptionMetadata or SymmetricDecryptionMetadata (JSON) + file part.
    • Streams the result back.

  2. Signing

    • Returns raw signature bytes in application/octet-stream.

  3. Signature Verification

    • Returns a short JSON message, e.g., {"isValid": true}, after verifying the streamed data plus a Base64 signature.

  4. Public Key Utility Endpoints (publickey-encrypt, publickey-verify)

    • For ephemeral public keys not in the KeyStore.
    • Decodes them from Base64, then streams encryption or verification.

8. Summary

  • Streaming Endpoints:
    • POST /api/crypto/stream/...
    • All use multipart/form-data with a metadata JSON part and a file binary part.
  • Memory Efficiency:
    • Data is processed in chunks without loading entire files in memory.
    • No temp files are used, avoiding disk I/O overhead.
  • Threading & Context:
    • The code uses nested calls to executeWithGeolocationAndUsageVoid, executeWithAuditContextVoid, and executeWithUsageContextVoid.
    • Each layer ensures logs, usage, and audit data is captured, even in a separate streaming thread.
  • Re-Encryption:
    • Demonstrates reading old ciphertext from oldAlias (private key) → decrypt → newAlias (public key) → encrypt → stream to response.
  • License Usage:
    • Each operation can enqueue usage data to the License Server via usage context, ensuring pay-per-use billing is accurate.

With this design, ANKA Secure handles large-file encryption, signing, verification, and re-encryption in a secure, scalable, and streaming manner.