Anka Secure API Documentation

This document provides an English-language overview and detailed usage guide for the Anka Secure API, which offers cryptographic operations, key management, and post-quantum-capable functions. You will find OpenAPI-based endpoint descriptions, example requests/responses, security considerations, and Mermaid diagrams illustrating core workflows.

---

Table of Contents

1. Introduction
2. Core Concepts
3. High-Level Architecture
4. Authentication
5. Key Management Endpoints
6. Cryptographic Operations (Standard / Non-Streaming)
7. Streaming Cryptographic Operations
8. License Management
9. Error Handling and Status Codes
10. Usage Examples
    • Generating a Key (Post-Quantum or Classical)
    • Encrypting with an Existing Key (Non-Streaming)
    • Decrypting Data (Non-Streaming)
    • Signing Data (Non-Streaming)
    • Verifying Signatures (Non-Streaming)
    • Re-Encrypting Data (Non-Streaming)
    • Re-Signing Data (Non-Streaming)
11. Security Considerations
12. Appendix: Supported Algorithms

---

Introduction

Anka Secure API is a RESTful service designed for key management and crypto-agile operations, including post-quantum cryptography (PQC) algorithms approved by NIST and traditional cryptography (RSA, ECC, AES, etc.).

Key aspects include:

• Crypto-Agility: Dynamically update or add algorithms (RSA, ECC, ML-KEM, Dilithium, Falcon, etc.).
• Post-Quantum Readiness: Implements algorithms such as ML-KEM, Dilithium, Falcon, and classical algorithms like RSA/ECC.
• Unified Key Management: Create, import, revoke, rotate, or remove keys through a single interface.
• Streaming Endpoints: Support large files and streaming for encryption/decryption, signing/verification, and key re-encryption or re-signing.
• Security: Endpoints typically require Bearer JWT or API Key for authentication.

---

Core Concepts

1. Bearer Authentication: Clients present a JWT token in the Authorization: Bearer <token> header.
2. API Key: An additional header (e.g., x-rapidapi-key) might be required by certain deployments.
3. Key Management:
   • Symmetric (kty = oct, e.g., AES-256)
   • Asymmetric Classical (RSA, EC)
   • Asymmetric Post-Quantum (ML-KEM, DILITHIUM, FALCON)
4. Crypto-Streaming: Endpoints that consume or produce large data via multipart/form-data.

5. Crucial Endpoints:

   • Authentication: Acquire JWT tokens.
   • Key Management: Generate, import, list, export, revoke, and remove keys.
   • Crypto: Encrypt, decrypt, sign, verify, re-encrypt, re-sign (both streaming and non-streaming).
   • License Management: Retrieve license info for the client/application.

---

High-Level Architecture

Below is a Mermaid flowchart illustrating the overall architecture of the Anka Secure API. It shows the main modules (Key Management, Crypto Operations, Authentication, etc.) and how clients interact:

flowchart LR
    A[Client / Application] -->|Bearer Token/API Key| B(API Gateway)
    B --> C[Authentication Service]
    B --> D[Key Management]
    B --> E[Crypto Operations]
    D --> F[Key Store / HSM]
    E --> F
    E --> G[Post-Quantum / Classical Algorithms]
    C --> H[License Management]

    subgraph "Anka Secure API"
        B
        C
        D
        E
        H
    end

1. Client / Application makes requests using secure channels (HTTPS with bearer tokens or API keys).

1. API Gateway dispatches requests to the correct module.

2. Key Management handles generation/import/export/removal of keys via the Key Store.

3. Crypto Operations includes encryption, decryption, signing, verifying, re-encrypting, re-signing, etc.

4. License Management queries/updates usage and plan details.

5. Authentication Service validates credentials and issues tokens.

---

Authentication

1. User Login

• Endpoint: POST /api/authenticate/login
• Description: Authenticates a user with username and password.
• Request Body (JSON):

{
    "username": "string",
    "password": "string"
}

- Response (JSON):

{
    "token": "JWT_ACCESS_TOKEN",
    "refreshToken": "JWT_REFRESH_TOKEN"
}

2. Application Authentication

• Endpoint: POST /api/authenticate/app
• Description: Authenticates an application with clientId and clientSecret.
• Request Body (JSON):

{
    "clientId": "string",
    "clientSecret": "string"
}

• Response (JSON):

{
    "token": "JWT_ACCESS_TOKEN",
    "refreshToken": "JWT_REFRESH_TOKEN"
}

3. Refresh Token

• Endpoint: POST /api/authenticate/refresh
• Description: Exchanges a valid refreshToken for a new access token (and possibly a new refresh token).
• Request Body (JSON):

{
    "refreshToken": "string"
}

• Response (JSON):

{
    "accessToken": "NEW_JWT_ACCESS_TOKEN",
    "refreshToken": "OPTIONAL_NEW_REFRESH_TOKEN"
}

Important: Each of these endpoints typically returns 401 Unauthorized if credentials or tokens are invalid.

---

Key Management Endpoints

1. List All Keys

• Endpoint: GET /api/key-management/keys
• Description: Returns a list of all keys (public metadata only---no secret data).
• Response Example:

{
    "totalCount": 3,
    "keys": [
    {
        "kid": "mySymKey",
        "kty": "oct",
        "alg": "AES-256",
        "exportable": false,
        "status": "ACTIVE",
        "usageCount": 45,
        "maxUsageLimit": 1000,
        "createdAt": "2025-03-02T15:00:00Z",
        "expiresAt": "2030-03-02T15:00:00Z"
    },
    ...
    ]
}

2. Generate a Key

• Endpoint: POST /api/key-management/keys
• Description: Creates a new key (classical, symmetric, or post-quantum) with specified parameters.
• Request Body (JSON):

{
    "kid": "myNewKeyId",
    "kty": "ML-KEM",
    "alg": "ML-KEM-768",
    "keyOps": ["encrypt", "decrypt"],
    "exportable": true,
    "expiresAt": "2030-05-31T23:59:59Z",
    "maxUsageLimit": 50000
}

• Response:
  • 201 Created if a new key is generated.
  • 200 OK if metadata was updated on an existing key with the same kid.

3. Import a Key (JSON-based)

• Endpoint: POST /api/key-management/keys/import
• Description: Imports existing key material in Base64/PEM format. Supports symmetric (oct), classical (RSA, EC), and post-quantum (ML-KEM, etc.).
• Request Body (JSON):

{
    "kid": "myImportedKey",
    "kty": "EC",
    "alg": "ES256",
    "publicKey": "BASE64-ENCODED-PUBLIC-KEY",
    "privateKey": "BASE64-ENCODED-PRIVATE-KEY",
    "keyOps": ["sign","verify"]
}

• Response:
  • 201 Created if a new key was imported.
  • 200 OK if key data was merged or updated.

4. Import a Private Key from PKCS#12

• Endpoint: POST /api/key-management/private-keys
• Description: Imports a .p12 / .pfx file (Base64-encoded) containing private keys + optional certificates.
• Request Body (JSON):

{
    "kid": "myPrivateKeyKid",
    "p12Password": "optionalPassword",
    "p12FileBase64": "MIIKvwIBAzCCChAGCSqGSIb3DQEHAaCCCgE..."
}

• Response: 201 Created on success.

5. Get Key by kid (Export Public Portion)

• Endpoint: GET /api/key-management/keys/{kid}
• Description: Retrieves metadata and public key (if asymmetric).
• Response Example:

{
    "kid": "myRsaKey",
    "kty": "RSA",
    "alg": "RSA-2048",
    "publicKey": "BASE64-ENCODED-PUBLIC-KEY",
    "status": "ACTIVE",
    "usageCount": 15
    ...
}

6. Revoke a Key

• Endpoint: POST /api/key-management/keys/{kid}/revoke
• Description: Marks a key's status as REVOKED to prevent further use.
• Response: 204 No Content on success.

7. Remove (Delete) a Key

• Endpoint: DELETE /api/key-management/keys/{kid}
• Description: Permanently deletes the key from the keystore.
• Response: 204 No Content on success.

8. Retrieve Supported Algorithms

• Endpoint: GET /api/key-management/supported-algorithms
• Description: Lists dynamically supported (kty, alg) pairs for crypto-agility. E.g.:

[
    { "kty": "ML-KEM", "alg": "ML-KEM-768" },
    { "kty": "DILITHIUM", "alg": "Dilithium3" },
    { "kty": "oct", "alg": "AES-256" }
]

---

Cryptographic Operations (Standard / Non-Streaming)

These endpoints handle small to medium-size data via Base64-encoded strings in JSON. For large data, see Streaming Cryptographic Operations.

1. Encrypt

• Endpoint: POST /api/crypto/encrypt
• Description: Encrypt Base64-encoded plaintext using the public key of kid.
• Request Body:

{
    "kid": "myKeyKid",
    "data": "SGVsbG8gQW5rYQ=="
}

• Response:

{
    "encryptedData": "Q3lwaGVyZWRUZXh0"
}

2. Decrypt

• Endpoint: POST /api/crypto/decrypt
• Description: Decrypt Base64-encoded ciphertext using the private key of kid.
• Request Body:

{
    "kid": "myKeyKid",
    "encryptedData": "Q3lwaGVyZWRUZXh0"
}

• Response:

{
    "decryptedData": "SGVsbG8gQW5rYQ=="
}

3. Sign

• Endpoint: POST /api/crypto/sign
• Description: Sign Base64-encoded data using the private key of kid.
• Request Body:

{
    "kid": "mySigningKeyKid",
    "data": "U2lnblRoaXNEYXRh"
}

• Response:

{
    "signature": "c2lnbmVkRGF0YQ=="
}

4. Verify

• Endpoint: POST /api/crypto/verify
• Description: Verify a signature.
• Request Body:

{
    "kid": "myVerifyKeyKid",
    "data": "U2lnblRoaXNEYXRh",
    "signature": "c2lnbmVkRGF0YQ=="
}

• Response:

{
    "valid": true,
    "errorMessage": ""
}

or

{
    "valid": false,
    "errorMessage": "Signature mismatch."
}

5. Re-Encrypt

• Endpoint: POST /api/crypto/reencrypt
• Description: Decrypt data with oldKid (private key), then encrypt with newKid (public key).
• Request Body:

{
    "oldKid": "myOldRsaKid",
    "newKid": "myNewKyberKid",
    "encryptedData": "QmFzZTY0Q29udGVudA=="
}

• Response:

{
    "reencryptedData": "QmFzZTY0TmV3Q2lwaGVydGV4dA=="
}

6. Re-Sign

• Endpoint: POST /api/crypto/resign
• Description: Verify the old signature with oldKid (public key), then sign again with newKid (private key).
• Request Body:

{
    "oldKid": "myOldRsaKey",
    "newKid": "myDilithiumKey",
    "data": "SGVsbG8gUmUtc2lnbiBEYXRh",
    "oldSignature": "QmFzZTY0U2lnbmF0dXJl"
}

• Response:

{
    "newSignature": "QmFzZTY0TmV3U2lnbmF0dXJl"
}

---

Streaming Cryptographic Operations

For large data (e.g., files), the API supports multipart/form-data streaming. Each relevant endpoint usually has:

• metadata (JSON part) describing which kid or key parameters to use.
• file (binary part) containing the actual content (plaintext, ciphertext, or data-to-sign).

1. Encrypt (Stream)

• Endpoint: POST /api/crypto/stream/encrypt
• Description: Encrypts a large file using a key kid.
• Multipart Form Fields:
  • metadata: JSON of type EncryptStreamRequest (contains kid).
  • file: The plaintext in raw binary.
• Response: The encrypted data is streamed back as raw bytes (application/octet-stream).

2. Decrypt (Stream)

• Endpoint: POST /api/crypto/stream/decrypt
• Description: Decrypts a large file using a private key kid.
• Multipart Form Fields:
  • metadata: JSON of type DecryptStreamRequest (contains kid).
  • file: The ciphertext in raw binary.
• Response: The decrypted data is streamed back.

3. Sign (Stream)

• Endpoint: POST /api/crypto/stream/sign
• Description: Signs large data using a private key kid.
• Multipart Form Fields:
  • metadata: SignStreamRequest (contains kid).
  • file: The data to be signed.
• Response: The signature in raw bytes.

4. Verify (Stream)

• Endpoint: POST /api/crypto/stream/verify
• Description: Verifies a signature for large data.
• Multipart Form Fields:
  • metadata: VerifySignatureStreamRequest (contains kid, signatureBase64).
  • file: The data to verify.
• Response (JSON):

{
    "valid": true | false,
    "errorMessage": "Optional error info"
}

5. Re-Encrypt / Re-Sign (Stream)

• Endpoints:
  • POST /api/crypto/stream/reencrypt
  • POST /api/crypto/stream/resign
• Description: Similar approach---metadata + file. The server performs the re-encrypt or re-sign on streamed data.

6. Utility Endpoints (Streaming)

• publickey-encrypt: Encrypt with a provided public key (without storing it).
• publickey-verify: Verify a signature with a provided public key (no key store involvement).

These accept a JSON part with publicKey, alg, kty, etc., plus a file for the raw data.

---

License Management

Get License Info

• Endpoint: GET /api/license-management/license-info/{clientId}
• Description: Retrieves the license details (plan tier, expiry date) and usage stats (operation counts, data usage).
• Response Example:

{
    "details": {
    "clientId": "myClientId",
    "contractType": "enterprise",
    "expiryDate": "2026-12-31T23:59:59Z"
    },
    "status": {
    "clientId": "myClientId",
    "totalOperationsUsed": 1500,
    "totalOperationsLimit": 10000,
    "underTotalOperationsLimit": true,
    "dataSizeUsed": 5000000,
    "dataSizeLimit": 10000000,
    "underDataSizeLimit": true,
    "postQuantumOperationsUsed": 120,
    "postQuantumOperationsLimit": 500,
    "underPostQuantumOperationsLimit": true,
    ...
    }
}

---

Error Handling and Status Codes

Most endpoints return:

• 200 OK for successful reads or updates.
• 201 Created for successful key generation/import.
• 204 No Content for successful deletion, revocation, etc.
• 400 Bad Request for invalid inputs (e.g., malformed JSON, invalid Base64).
• 401 Unauthorized if missing or invalid authentication.
• 403 Forbidden if license constraints are violated (or other policy restrictions).
• 404 Not Found if a specific kid or resource does not exist.
• 409 Conflict if a key with the same kid exists but has incompatible parameters.
• 413 Payload Too Large for oversize Base64 data, file parts, or PKCS#12 files.
• 500 Internal Server Error for unexpected server or cryptographic library issues.

Error Responses typically have a structure like:

{
  "status": 400,
  "error": "Bad Request",
  "message": "Specific details on what went wrong",
  "path": "/api/endpoint",
  "timestamp": "2025-01-01T12:00:00Z"
}

---

Usage Examples

Below are cURL examples illustrating common operations.

Generating a Key (Post-Quantum or Classical)

curl -X POST https://demo.ankatech.co/api/key-management/keys\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "kid": "myKyberKey",
    "kty": "ML-KEM",
    "alg": "ML-KEM-768",
    "exportable": true,
    "keyOps": ["encrypt","decrypt"]
  }'

• 201 Created on success.

Encrypting with an Existing Key (Non-Streaming)

curl -X POST https://demo.ankatech.co/api/crypto/encrypt\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "kid": "myKyberKey",
    "data": "SGVsbG8gQW5rYQ=="
  }'

• 200 OK, response body:

  {
      "encryptedData": "Q3lwaGVyZWRUZXh0"
  }
  

Decrypting Data (Non-Streaming)

curl -X POST https://demo.ankatech.co/api/crypto/decrypt\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "kid": "myKyberKey",
    "encryptedData": "Q3lwaGVyZWRUZXh0"
  }'

• 200 OK, response body:

{
    "decryptedData": "SGVsbG8gQW5rYQ=="
}

Signing Data (Non-Streaming)

curl -X POST https://demo.ankatech.co/api/crypto/sign\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "kid": "mySigningKeyKid",
    "data": "U2lnblRoaXNEYXRh"
  }'

• 200 OK, response body:

{
    "signature": "c2lnbmVkRGF0YQ=="
}

Verifying Signatures (Non-Streaming)

curl -X POST https://demo.ankatech.co/api/crypto/verify\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "kid": "myVerifyKeyKid",
    "data": "U2lnblRoaXNEYXRh",
    "signature": "c2lnbmVkRGF0YQ=="
  }'

• 200 OK, response body (example):

{
    "valid": true,
    "errorMessage": ""
}

Re-Encrypting Data (Non-Streaming)

curl -X POST https://demo.ankatech.co/api/crypto/reencrypt\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "oldKid": "myOldRsaKid",
    "newKid": "myNewKyberKid",
    "encryptedData": "QmFzZTY0Q29udGVudA=="
  }'

• 200 OK, response body:

{
    "reencryptedData": "QmFzZTY0TmV3Q2lwaGVydGV4dA=="
}

Re-Signing Data (Non-Streaming)

curl -X POST https://demo.ankatech.co/api/crypto/resign\
  -H "Authorization: Bearer <token>"\
  -H "Content-Type: application/json"\
  -d '{
    "oldKid": "myOldRsaKey",
    "newKid": "myDilithiumKey",
    "data": "SGVsbG8gUmUtc2lnbiBEYXRh",
    "oldSignature": "QmFzZTY0U2lnbmF0dXJl"
  }'

• 200 OK, response body:

{
    "newSignature": "QmFzZTY0TmV3U2lnbmF0dXJl"
}

---

Security Considerations

1. TLS/HTTPS: Always use TLS 1.2 or higher (preferably 1.3).
2. Authentication:
   • Bearer tokens should be stored securely; never transmit them over unencrypted channels.
   • Support token refresh to avoid long-lived tokens.
3. Key Storage: Private keys ideally remain in an HSM or secure KMS. If software-based, ensure strong encryption-at-rest.
4. Access Control:
   • Protect endpoints with roles/permissions.
   • Example: Not every user should be allowed to import or remove keys.
5. Crypto-Agility:
   • Keep track of new NIST PQC standard updates.
   • Plan for algorithm rotation and key revocation.
6. Limits and Monitoring:
   • Ensure data size or usage limits are enforced (license constraints).
   • Log cryptographic operations for auditing and usage metrics.

---

Appendix: Supported Algorithms

Below is a partial snapshot of what might be returned by GET /api/key-management/supported-algorithms. Use this endpoint dynamically to see the full, current set.

• Symmetric:
  • kty = "oct", alg = "AES-128", AES-192, AES-256
• Classical Asymmetric:
  • kty = "RSA", alg = "RSA-2048", RSA-4096
  • kty = "EC", alg = "ES256", ES384, ES512
• Post-Quantum:
  • kty = "ML-KEM", alg = "ML-KEM-768", ML-KEM-1024
  • kty = "DILITHIUM", alg = "Dilithium2", Dilithium3, Dilithium5
  • kty = "FALCON", alg = "Falcon512", Falcon1024

Note: The naming (ML-KEM, DILITHIUM, FALCON) may evolve as NIST finalizes standards.

---

Conclusion

The Anka Secure API combines post-quantum cryptography support, classical algorithms, and crypto-agility into a unified service. By following the endpoints described above, you can:

• Authenticate using user credentials or client credentials.
• Manage Keys (create, import, revoke, remove) for both classical and PQC.
• Perform Crypto Ops for encryption, decryption, signing, verification (both streaming and standard).
• Migrate existing ciphertext/signatures to new keys (re-encrypt or re-sign).
• Stream Large Data securely through multipart endpoints.

Remember to consult the OpenAPI schema (included above) for complete technical details, including field constraints and status codes. Always ensure your environment enforces TLS, proper JWT handling, and respects license usage constraints.

For further assistance or issues, contact AnkaTech Support via [email protected].