Migration & Interoperability

Bulk onboarding and one-off utilities for external keys

1 · Why this section exists

A core promise of AnkaSecure is friction-free migration from any existing PKI, HSM or ad-hoc keystore.
Typical scenarios:

Import existing keys that already protect production data.
Perform one-shot operations with a public key you will never store (audit, partner exchange).
Export the public part of a key so external systems can consume it.
Prepare legacy artefacts for post-quantum protection without exposing plaintext.

These endpoints let you achieve all of the above, keeping everyday Key Management and Secure workflows clean and deterministic.

2 · Endpoints (tag `Migration & Interoperability`)

Verb	Path	Summary	Typical use-case
POST	`/api/migration/utility/publickey-verify`	Verify a signature with a supplied public key (stream).	One-off audit of a partner’s signed file.
POST	`/api/migration/utility/publickey-encrypt`	Encrypt plaintext with a supplied public key (stream).	Send a file securely to a partner without storing their key.
POST	`/api/migration/private-keys`	Import a PKCS#12 bundle (private key + cert chain).	Bring an RSA / EC key-pair from an external CA/HSM.
POST	`/api/migration/keys/import`	Import an existing key (symmetric, classical, post-quantum).	Register production keys by kid so apps can switch to AnkaSecure immediately.
GET	`/api/migration/keys/{kid}`	Export a key’s public portion + metadata.	Provide the public key to external systems.

Once a key is imported it behaves exactly like a natively generated key: rotate, revoke, patch, monitor — all via Key Management.

3 · Core Schemas (OpenAPI `#/components/schemas/`)*

Schema	Used by	Purpose
SignatureUtilityApi	`/utility/publickey-verify`	Metadata for ad-hoc signature checks.
CryptoUtilityApi	`/utility/publickey-encrypt`	Metadata for ad-hoc public-key encryption.
ImportPkcs12Metadata	`/private-keys`	Parameters (kid, Base64 `.p12`, optional password).
KeyImportRequest	`/keys/import`	Generic key import (`oct` / RSA / EC / PQC).
KeyExportResponse	`/keys/{kid}`	Public key + lifecycle info.

4 · Import a PKCS#12 bundle

POST /api/migration/private-keys
Content-Type: application/json
Authorization: Bearer <JWT>

{
  "kid"           : "legacyRsaKey",
  "p12Password"   : "changeit",
  "p12FileBase64" : "MIIKvwIBAzCCChAG..."
}

201 Created --- private key stored under legacyRsaKey.
400 Bad Request --- wrong password or invalid PKCS#12 structure.

You can now call /api/crypto/decrypt or /api/crypto/sign with kid = legacyRsaKey.

5 - Generic key import

POST /api/migration/keys/import

{
  "kid"       : "myRsaPubKey",
  "kty"       : "RSA",
  "alg"       : "RSA-2048",
  "keyOps"    : ["encrypt","verify"],
  "publicKey" : "<Base64-public-key>"
}

Code	Meaning
201 Created	New key registered.
200 OK	Existing key updated (idempotent).
409 Conflict	Same kid exists with incompatible algorithm.

🔐 Symmetric keys --- set kty = "oct" and place the secret in privateKey.

6 - Ad-hoc public-key utilities (stream)

6.1 Verify a partner's signature

POST /api/migration/utility/publickey-verify
Content-Type: multipart/form-data; boundary=...

Part 1 --- metadata (SignatureUtilityApi)

{ "kty":"ML-DSA", "alg":"ML-DSA-87",
  "publicKey":"...", "signatureBase64":"..." }

Part 2 --- file → the binary payload that was signed.

200 OK → { "valid": true, "algorithmUsed": "ML-DSA-87" }

6.2 Encrypt data for a partner

Same structure but with CryptoUtilityApi and the plaintext file.

7 - Export a key's public portion

GET /api/migration/keys/{kid}

Returns a KeyExportResponse. If the key is symmetric the secret is never returned --- only metadata.

8 - Where to find the zero-friction migration workflow

The complete step-by-step guide for re-encrypting RSA-protected data into ML-KEM (and similar flows) is documented in the Use-Case section:

Zero-Friction RSA → ML-KEM Migration

9 - Error codes (RFC 7807)

Code	`type` URI	Typical cause
400	`/errors/invalid-input`	Missing field, malformed Base64, wrong p12 password.
401	`/errors/unauthorized`	No or invalid JWT.
404	`/errors/not-found`	Unknown `kid`.
409	`/errors/conflict`	Algorithm mismatch on import.
413	`/errors/payload-too-large`	File or JSON > 5 MB.
500	`/errors/internal`	Keystore or crypto engine failure.

10 - Good practices

Hash public keys before import to detect duplicates.
Label legacy keys with soft sunset dates and usage limits; legacy algorithms rarely need unlimited life.
Delete the PKCS#12 password immediately after receiving 201 Created.
Use utility endpoints only for transient cases; for anything repetitive, store the key and use the regular Secure endpoints.