openapi: 3.0.3
info:
  title: kms
  version: 1.0.1782121238300
  description: Сервис kms
  license:
    name: CC BY-NC-ND 4.0
    url: https://gitlab.infra.rtkit.dev/openapi/key/raw/main/LICENCE.md
tags:
  - name: system(public)
    description: Методы system. Не требуют авторизацию. Доступны из интернета
  - name: kms(internal auth)
    description: Внутренние методы. Требуют авторизацию. Доступны только во внутренней сети
paths:
  /kms/api/v1/system/status:
    get:
      summary: |-
        Метод получения статуса сервиса.
        Не требует авторизации
      operationId: SystemService_GetSystemStatus
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetSystemStatusResponse"
        "400":
          description: Ошибка
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - system(public)
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /kms/internal/api/v1/kms/jwt/create/jwe:
    post:
      summary: >-
        Метод создание nested JWT токена.

        Создаёт JWT токен с клеймами переданными в PayloadData, подписывает последним выпущенным приватным ключом платформы Ключ.

        Токен шифруетется (JWE) публичным ключом, переданным в параметре public_key (обычно это публичный ключ партнёра).

        Логика работы метода: https://confluence.rt.ru/pages/viewpage.action?pageId=664695865.

        Метод доступен для: service
      operationId: JwtService_PostKmsJwtCreateJwe
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKmsJwtCreateJweResponse"
        "400":
          description: Ошибка
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKmsJwtCreateJweResponse"
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKmsJwtCreateJweResponse"
        default:
          description: Ошибки транспортного слоя
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/v1PostKmsJwtCreateJweRequest"
        required: true
      tags:
        - kms(internal auth)
      security:
        - oauth2:
            - kms:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /kms/internal/api/v1/kms/key/generate:
    post:
      summary: >-
        Метод генерации пары ключей.

        Генерирует публичный и приватный ключи.

        Приватный ключ шифруется алгоритмом AES-GCM и сохранятеся в колонке kms.key_infos.encrypted_private_key.

        Формат хранения приватного ключа - строковое представление JSON: состоит из переменных:

        - Nonce: Number used once - представляет собой уникальный набор битов, используется один раз при шифровании блока данных в режиме GCM.

        - EncryptedString: зашифрованный приватный ключ в формате DER.

        - Tag: Message Authentication Code, используется для проверки целостности и подлинности данных после их расшифровки.

        Публичный ключ сохранятеся в колонке kms.key_infos.public_key в формате DER и передаётся в сервис JWKS методом PostKey.

        Логика работы метода: https://confluence.rt.ru/pages/viewpage.action?pageId=664695357.

        Метод доступен для: admin, manager, service
      operationId: KmsService_PostKmsKeyGenerate
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKmsKeyGenerateResponse"
        "400":
          description: Ошибка
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKmsKeyGenerateResponse"
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKmsKeyGenerateResponse"
        default:
          description: Ошибки транспортного слоя
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - kms(internal auth)
      security:
        - oauth2:
            - kms:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /kms/internal/api/v1/kms/key/list:
    get:
      summary: >-
        Метод получения ключей.

        Возвращает три последних ключа отсортированных по created_at DESC.

        Используется в административном интерфейсе, для отображения даты выпуска последней пары ключей.

        Сценарий использвания: https://confluence.rt.ru/pages/viewpage.action?pageId=682907591.

        Метод доступен для: admin, manager, service
      operationId: KmsService_GetKmsKeyList
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    $ref: "#/components/schemas/v1GetKmsKeyListResponse"
                  error:
                    $ref: "#/components/schemas/rpcStatus"
                title: Поток объектов v1GetKmsKeyListResponse
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - kms(internal auth)
      security:
        - oauth2:
            - kms:read
            - kms:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
components:
  schemas:
    ErrorPrivateKeyNotFound:
      type: object
      title: Отсутствует ключ для подписания
    GeneratingErrorPublishingKeyError:
      type: object
      title: |-
        Ошибка сохранения публичного ключа в сервисе JWKS.
        Причины:
        - Отсутсвует связанность с сервисом JWKS
    GeneratingErrorTransactionError:
      type: object
      title: |-
        Ошибка генерации ключа в сервисе KMS.
        Причины:
        - Отсутсвует связанность с базой данных
    KeyInfoGeneratingError:
      type: object
      properties:
        transaction:
          title: Ошибка генерации ключа в сервисе KMS
          allOf:
            - $ref: "#/components/schemas/GeneratingErrorTransactionError"
        publishing:
          title: Ошибка сохранения публичного ключа в сервисе JWKS
          allOf:
            - $ref: "#/components/schemas/GeneratingErrorPublishingKeyError"
      title: Ошибка генерации
    PostKmsJwtCreateJweRequestPayloadData:
      type: object
      properties:
        values:
          type: object
          additionalProperties:
            type: string
          title: |-
            Словарь значений.
            Ключи и значения являются строками.
            # Диапазон: 1..128
      title: Claims (данные включаемые в тело токена)
    protobufAny:
      type: object
      properties:
        "@type":
          type: string
      additionalProperties: {}
      title: Произвольный JSON
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/protobufAny"
      title: Ошибка транспортного слоя
    v1GetKmsKeyListResponse:
      type: object
      properties:
        data:
          title: |-
            Ключ.
            В ключе должен отсутсвовать encrypted_private_key
          allOf:
            - $ref: "#/components/schemas/v1KeyInfo"
      title: Ответ на запрос на получение ключей
    v1GetSystemStatusResponse:
      type: object
      title: Ответ на запрос проверки доступности сервиса
    v1KeyInfo:
      type: object
      properties:
        id:
          type: string
          title: |-
            Идентификатор.
            # Тип: Guid
        publicKey:
          type: string
          title: |-
            Публичный ключ.
            # Диапазон: 0..800
          readOnly: true
        encryptedPrivateKey:
          type: string
          title: |-
            Приватный ключ в зашифрованном виде.
            # Диапазон: 0..4000
          readOnly: true
        createdAt:
          type: string
          format: date-time
          title: Дата и время создания ключа
          readOnly: true
        expiredAt:
          type: string
          format: date-time
          title: Дата и время истечения жизни ключа
          readOnly: true
      title: |-
        Пара ключей.
        # Описание модели
      required:
        - id
    v1PostKmsJwtCreateJweRequest:
      type: object
      properties:
        data:
          title: Claims (данные включаемые в тело токена)
          allOf:
            - $ref: "#/components/schemas/PostKmsJwtCreateJweRequestPayloadData"
        publicKey:
          type: string
          title: Публичный ключ для шифрования
      title: Запрос на создание nested JWT токена
      required:
        - data
        - publicKey
    v1PostKmsJwtCreateJweResponse:
      type: object
      properties:
        data:
          type: string
          title: Nested JWT токен
        error:
          title: Ошибка
          allOf:
            - $ref: "#/components/schemas/v1PostKmsJwtCreateJweResponseError"
      title: Ответ на запрос на формирование токена
    v1PostKmsJwtCreateJweResponseError:
      type: object
      properties:
        validation:
          title: Ошибка валидации
          allOf:
            - $ref: "#/components/schemas/v1ValidationError"
        privateKeyNotFound:
          title: Отсутствует ключ для подписания
          allOf:
            - $ref: "#/components/schemas/ErrorPrivateKeyNotFound"
      title: Ошибка
    v1PostKmsKeyGenerateResponse:
      type: object
      properties:
        data:
          type: string
          title: |-
            Идентификатор.
            # Тип: Guid
        error:
          title: Ошибка
          allOf:
            - $ref: "#/components/schemas/v1PostKmsKeyGenerateResponseError"
      title: Ответ на запрос на генерацию пары ключей
    v1PostKmsKeyGenerateResponseError:
      type: object
      properties:
        generating:
          title: Ошибка генерации ключей в сервисе KMS
          allOf:
            - $ref: "#/components/schemas/KeyInfoGeneratingError"
      title: Ошибка
    v1ValidationError:
      type: object
      properties:
        path:
          type: string
          title: Путь к полю в формате наименования прото
        message:
          type: string
          title: Валидационное сообщение
      title: |-
        Ошибки валидации.
        Эти проверки выполняются до обращения в базу данных
      required:
        - path
        - message
  securitySchemes:
    bearerHttp:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth2-staging.k8s.key.rt.ru/oauth2/token
          scopes:
            kms:edit: Предоставляет полный доступ в сервис kms
            kms:read: Предоставляет доступ на чтение данных из сервиса kms
servers:
  - url: https://keyapis-staging.k8s.key.rt.ru
    description: staging
  - url: https://{feature}.k8s.key.rt.ru/
    description: https feature
    variables:
      feature:
        default: ""
        description: Feature name
  - url: http://{feature}.k8s.key.rt.ru/
    description: http feature
    variables:
      feature:
        default: ""
        description: Feature name
  - url: https://localhost:3001
    description: localhost
  - url: https://keyapis.key.rt.ru
    description: production
