Skip to content

Migrating from RSA-2048 to Falcon-1024 (streaming detached-JWS)

This walkthrough shows how to upgrade existing RSA-2048 signatures to Falcon-1024 with zero payload buffering.
All operations use the high-throughput Secure Streaming endpoints, which sign, re-sign and verify data chunk-by-chunk.

1 · Process overview

# Action Endpoint Payload format
1 Generate RSA-2048 key POST /api/key-management/keys JSON
2 Sign file (RSA) POST /api/crypto/stream/sign multipart/form-data → detached-JWS
3 Generate Falcon-1024 key POST /api/key-management/keys JSON
4 Re-sign (RSA → Falcon) POST /api/crypto/stream/resign multipart/form-data
5 Verify (Falcon) POST /api/crypto/stream/verify multipart/form-data
flowchart TD Start(("Start")) --> K1[Generate RSA-2048 key] K1 --> S1["Sign file → detached-JWS (RSA)"] S1 --> K2[Generate Falcon-1024 key] K2 --> RS["Re-sign detached-JWS (RSA → Falcon)"] RS --> V1["Verify detached-JWS (Falcon)"] V1 --> End(("End"))

2 - Detailed steps

2.1 Generate RSA-2048 key

  • Endpoint POST /api/key-management/keys

  • Body application/json

{
  "kid": "rsa_sign_key_001",
  "kty": "RSA",
  "alg": "RSA-2048",
  "keyOps": ["sign", "verify"],
  "exportable": true
}

Response 201 Created

2.2 Sign file (streaming, RSA)

  • Endpoint POST /api/crypto/stream/sign

  • Body multipart/form-data

Part Name Content-Type Notes
1 metadata application/json Schema SignStreamRequest
2 file application/octet-stream Raw payload to be signed

2.2.1 metadata part anatomy (SignStreamRequest)

Field Type Required Description
kid string Yes Private-key identifier used to sign (rsa_sign_key_001).
Example
{ "kid": "rsa_sign_key_001" }

Result

  • JSON body: detached-JWS header + signature field

  • Headers:

X-Key-Requested: rsa_sign_key_001
X-Key-Used: rsa_sign_key_001
X-Algorithm-Used: PS256`

2.3 Generate Falcon-1024 key

  • Endpoint POST /api/key-management/keys

  • Body application/json

{
  "kid": "falcon_key_001",
  "kty": "FALCON",
  "alg": "Falcon-1024",
  "keyOps": ["sign", "verify"],
  "exportable": true
}

Response 201 Created

2.4 Re-sign detached-JWS (RSA → Falcon)

  • Endpoint POST /api/crypto/stream/resign?newKid=falcon_key_001

  • Body multipart/form-data

Part Name Content-Type Notes
1 metadata application/json Schema ResignDetachedJwsStreamRequest
2 file application/octet-stream Original payload (identical to step 2)

2.4.1 metadata part anatomy (ResignDetachedJwsStreamRequest)

Field Type Required Description
oldJws string Yes Detached-JWS header + signature produced by step 2.
newKid string Yes New signing key id (falcon_key_001).
sourceKidOverride string No Fallback key id if oldJws.protected.kid is missing.
Managed flow (kid present)
{
  "oldJws": "{protected:eyJhbGciOiJQUzI1NiIsImtpZCI6InJzYV9zaWduX2tleV8wMDEifQ,signature:...}",
  "newKid": "falcon_key_001"
}
Migration flow (kid absent + override)
{
  "oldJws": "{protected:eyJhbGciOiJQUzI1NiJ9,signature:...}",
  "newKid": "falcon_key_001",
  "sourceKidOverride": "rsa_sign_key_001"
}

Result

  • JSON body: new detached-JWS header + signature (Falcon-1024)

  • Lifecycle headers:

X-OldKey-Requested: rsa_sign_key_001
X-OldKey-Used: rsa_sign_key_001
X-NewKey-Requested: falcon_key_001
X-NewKey-Used: falcon_key_001
X-OldKey-Algorithm-Used: PS256
X-NewKey-Algorithm-Used: Falcon-1024
X-Migration-Mode: true          # only if sourceKidOverride applied

2.5 Verify detached-JWS (Falcon)

  • Endpoint POST /api/crypto/stream/verify

  • Body multipart/form-data

Part Name Content-Type Notes
1 metadata application/json Schema VerifyDetachedJwsStreamRequest
2 file application/octet-stream Same payload used in step 4

2.5.1 metadata part anatomy (VerifyDetachedJwsStreamRequest)

Field Type Required Description
detachedJws string Yes Detached-JWS header + signature from step 4.
Example
{
  "detachedJws": "{protected:eyJhbGciOiJGYWxjb24xMDI0Iiwia2lkIjoiZmFsY29uX2tleV8wMDEifQ,signature:...}"
}

Result

{ "valid": true }

If invalid:

{ "valid": false, "errorMessage": "Invalid signature." }

3 - Key considerations

  1. No plaintext exposure -- payload bytes are streamed once; they are never fully buffered.

  2. Algorithm lineage -- telemetry headers track old vs. new key and algorithm pair (PS256 → Falcon-1024).

  3. Quantum-safe target -- Falcon-1024 offers 233-bit EUF-CMA security against large-scale quantum attacks.

  4. Migration diagnostics -- X-Migration-Mode: true flags legacy signatures lacking a kid.

  5. Automate rotations -- schedule annual re-sign jobs to keep signatures ahead of key expiry and cryptanalytic advances.

Before You Begin

Prerequisites: - Active AnkaSecure tenant with API access - Existing RSA-signed data (or ability to create test data) - API credentials (JWT token or API key)

Estimated Time: 30 minutes (including test data generation)

Complexity: Intermediate (requires understanding of streaming APIs and JWS)

Troubleshooting

Re-signing Fails with 422 Error

Symptom: {"error":"CRYPTO_001","message":"Signature verification failed"}

Causes: - JWS header corrupted during transfer - Original signature invalid - Wrong key ID specified for source key

Solutions: - Verify original JWS signature is valid (verify before re-signing) - Check kid in JWS header matches source key - Ensure complete signature transmitted (Base64url-encoded)

Signature Verification Fails After Re-signing

Symptom: New ML-DSA signature fails verification

Causes: - Payload modified between signing and verification - Wrong public key used for verification

Solutions: - Ensure payload unchanged (hash comparison) - Verify using correct ML-DSA public key (not RSA key) - Check algorithm in JWS header matches key algorithm

Next Steps

Migration Successful? Continue with:

Need Help? - Error Reference - Complete error code catalog - API Documentation - Streaming API details - Support - Contact support team

Documentation Version: 3.0.0 Last Updated: 2025-12-26