CipherHUB.Cloud Cipherhub API

openapi: 3.2.0
info:
  title: Cryptography Cipherhub API
  version: 1.2.0
  description: 'CipherHUB exposes 31 cryptographic operations covering classical algorithms (AES, RSA, ECC, SM2/3/4, ZUC),

    post-quantum cryptography (ML-KEM FIPS 203, ML-DSA FIPS 204, Hybrid KEX), and utility functions.


    **Recommended integration path for AI Agents**: use the MCP endpoint `POST https://tools.cipherhub.cloud/cipherhub/mcp`.

    MCP clients do not need to implement the CipherHUB application-layer encrypted channel.


    **Encrypted REST API**: `POST https://tools.cipherhub.cloud/cipherhub/api` is not a plaintext business JSON API.

    The REST request body must be wrapped by the CipherHUB SDK channel protocol before transmission.

    The plaintext business object containing `request_id`, `action`, and action-specific parameters is encrypted locally,

    then sent as an `EncryptedApiRequest`.


    **SDK channel protocol summary**:

    1. Call `GET /cipherhub/get_protection_key` to fetch a server protection key.

    2. Generate an ephemeral ECC key pair on the client side.

    3. Run ECDH with the server public key and derive a 32-byte symmetric key with HKDF-SHA512.

    4. Encrypt the plaintext business JSON with ChaCha20-Poly1305 and a fresh 12-byte nonce.

    5. Sign the plaintext business JSON with HMAC-SHA512 using the derived symmetric key.

    6. Submit `key_id`, encrypted data, nonce, ephemeral public key, signature, timestamp, and request_id to `POST /cipherhub/api`.

    7. Decrypt the encrypted response with the same symmetric key and verify its HMAC-SHA512 signature.


    HTTPS protects the transport layer. The CipherHUB SDK channel adds application-layer end-to-end protection.

    Do not send plaintext business requests directly to `/cipherhub/api`. Use `sdk/client_request.py` where possible.


    This document serves as a capability declaration for AI Agents and developers to understand

    available operations, parameter schemas, encrypted-channel wrapping, and response formats.


    **Channel implementation reference**: For a complete Python reference implementation of the encrypted

    channel protocol (ECDH + HKDF-SHA512 + ChaCha20-Poly1305 + HMAC-SHA512), query MCP resource

    `cipherhub://channel-implementation` via `resources/read`, or read `docs/channel-implementation-guide.md`.'
  contact:
    name: Yang X. CHEN
    url: https://cipherhub.cloud
  license:
    name: Proprietary
    url: https://cipherhub.cloud
servers:
- url: https://tools.cipherhub.cloud
  description: Production (MCP + REST)
tags:
- name: Cipherhub
paths:
  /cipherhub/mcp:
    post:
      summary: MCP Streamable HTTP Endpoint
      description: JSON-RPC 2.0 endpoint for Model Context Protocol. Supports tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read. This is the recommended path for AI Agents because it does not require implementing the CipherHUB REST encrypted channel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              - id
              properties:
                jsonrpc:
                  type: string
                  const: '2.0'
                method:
                  type: string
                  enum:
                  - tools/list
                  - tools/call
                  - prompts/list
                  - prompts/get
                  - resources/list
                  - resources/read
                params:
                  type: object
                id:
                  type:
                  - string
                  - integer
      responses:
        '200':
          description: JSON-RPC 2.0 response
      tags:
      - Cipherhub
      operationId: postCipherhubMcp
      x-operation-id-source: derived
  /cipherhub/get_protection_key:
    get:
      summary: Get REST channel protection key
      description: Returns the server ECC ECDH protection public key. Clients need this key before constructing an encrypted REST request for `/cipherhub/api`. Public Nginx route `/cipherhub/get_protection_key` maps to backend route `/get_protection_key`.
      responses:
        '200':
          description: Server protection key for the encrypted REST channel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectionKeyResponse'
      tags:
      - Cipherhub
      operationId: getCipherhubGetProtectionKey
      x-operation-id-source: derived
  /cipherhub/get_api_list:
    get:
      summary: Get supported REST business actions
      description: Returns all supported plaintext business `action` names. These action names are used inside the encrypted business JSON before SDK channel wrapping. Public Nginx route `/cipherhub/get_api_list` maps to backend route `/get_api_list`.
      responses:
        '200':
          description: Supported business action list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiListResponse'
      tags:
      - Cipherhub
      operationId: getCipherhubGetApiList
      x-operation-id-source: derived
  /cipherhub/api:
    post:
      summary: Encrypted REST business API
      description: 'Application-layer encrypted REST endpoint. The request body must be `EncryptedApiRequest`, not plaintext business JSON.


        Plaintext business JSON has the shape `{ "request_id": "...", "action": "HashSum", ... }`, but it must be encrypted with the CipherHUB SDK channel before being sent here.


        Use `sdk/client_request.py` or implement the documented ECDH + HKDF-SHA512 + ChaCha20-Poly1305 + HMAC-SHA512 wrapping protocol.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptedApiRequest'
      responses:
        '200':
          description: Encrypted business response, or a plaintext error response if channel processing failed
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EncryptedApiResponse'
                - $ref: '#/components/schemas/CommonErrorResponse'
      tags:
      - Cipherhub
      operationId: postCipherhubApi
      x-operation-id-source: derived
components:
  schemas:
    EncryptedApiRequest:
      type: object
      required:
      - key_id
      - encrypted_data
      - encrypted_key
      - signature
      - timestamp
      - request_id
      description: 'REST encrypted-channel request body. `encrypted_data` contains the ChaCha20-Poly1305 ciphertext.

        New clients also send `nonce` as a separate 12-byte hex string. For legacy compatibility, `encrypted_data`

        may contain `ciphertext || nonce`; the server accepts both forms.

        '
      properties:
        key_id:
          type: string
          description: Protection key identifier returned by `/cipherhub/get_protection_key`.
        encrypted_data:
          type: string
          pattern: ^[0-9a-fA-F]+$
          description: ChaCha20-Poly1305 ciphertext as hex. Legacy clients append the 12-byte nonce to this field.
        nonce:
          type:
          - string
          - 'null'
          pattern: ^[0-9a-fA-F]{24}$
          description: 12-byte ChaCha20-Poly1305 nonce as hex. If omitted, the server extracts nonce from the last 12 bytes of `encrypted_data`.
        encrypted_key:
          type: string
          pattern: ^[0-9a-fA-F]+$
          description: Client ephemeral ECC public key encoded as hex.
        signature:
          type: string
          pattern: ^[0-9a-fA-F]{128}$
          description: HMAC-SHA512 over the plaintext business JSON, encoded as hex.
        timestamp:
          type: string
          format: date-time
          description: Client send time in ISO 8601 format.
        request_id:
          type: string
          minLength: 8
          maxLength: 64
          description: Client-generated request identifier. It should match the plaintext business request `request_id`.
      examples:
      - key_id: b8b2c6f6c4a64e39a2a2f5e4f1a0c9d0
        encrypted_data: 6f2a...d91c
        nonce: 00112233445566778899aabb
        encrypted_key: 3059...
        signature: 9f1d...
        timestamp: '2026-04-30T10:31:00'
        request_id: demo-request-0001
    EncryptedApiResponse:
      type: object
      required:
      - encrypted_data
      - nonce
      - signature
      description: Encrypted REST response. Decrypt `encrypted_data` with the same derived symmetric key and verify HMAC-SHA512 over the plaintext response JSON.
      properties:
        encrypted_data:
          type: string
          pattern: ^[0-9a-fA-F]+$
          description: ChaCha20-Poly1305 response ciphertext as hex.
        nonce:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
          description: 12-byte response nonce as hex.
        signature:
          type: string
          pattern: ^[0-9a-fA-F]{128}$
          description: HMAC-SHA512 over the plaintext response JSON, encoded as hex.
    ProtectionKeyResponse:
      type: object
      required:
      - key_id
      - public_key
      - algorithm
      properties:
        key_id:
          type: string
          description: Server protection key identifier used in `EncryptedApiRequest.key_id`.
        public_key:
          type: string
          description: Server ECC ECDH public key in PEM format.
        algorithm:
          type: string
          enum:
          - ECC_ECDH
          description: Protection-key algorithm. Current value is `ECC_ECDH`.
      examples:
      - key_id: b8b2c6f6c4a64e39a2a2f5e4f1a0c9d0
        public_key: '-----BEGIN PUBLIC KEY-----

          ...

          -----END PUBLIC KEY-----

          '
        algorithm: ECC_ECDH
    ApiListResponse:
      type: array
      description: List of supported plaintext business action names used before encrypted-channel wrapping.
      items:
        type: string
      examples:
      - - Hello
        - GenerateRandomData
        - HashSum
        - HmacSum
        - BlockCipher
        - StreamCipher
        - MLKEMKeyGen
        - MLDSASign
    CommonErrorResponse:
      type: object
      required:
      - request_id
      - code
      - msg
      description: Plaintext error response returned when encrypted-channel processing fails before a response can be encrypted.
      properties:
        request_id:
          type: string
        code:
          type: string
        msg:
          type: string