openapi.yaml

swagger: "2.0"
info:
  title: Rekor
  description: Rekor is a cryptographically secure, immutable transparency log for signed software releases.
  version: 0.0.1

host: api.rekor.dev
schemes:
  - http

consumes:
  - application/json
  - application/yaml
produces:
  - application/json;q=1
  - application/yaml

paths:
  /api/v1/index/retrieve:
    post:
      summary: Searches index by entry metadata
      operationId: searchIndex
      tags:
        - index
      parameters:
        - in: body
          name: query
          required: true
          schema:
            $ref: '#/definitions/SearchIndex'
      responses:
        200:
          description: Returns zero or more entry UUIDs from the transparency log based on search query
          schema:
            type: array
            items:
              type: string
              description: Entry UUID in transparency log
              pattern: '^[0-9a-fA-F]{64}$'
        400:
          $ref: '#/responses/BadContent'
        default:
          $ref: '#/responses/InternalServerError'
  /api/v1/log:
    get:
      summary: Get information about the current state of the transparency log
      description: Returns the current root hash and size of the merkle tree used to store the log entries.
      operationId: getLogInfo
      tags:
        - tlog
      responses:
        200:
          description: A JSON object with the root hash and tree size as properties
          schema:
            $ref: '#/definitions/LogInfo'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/publicKey:
    get:
      summary: Retrieve the public key that can be used to validate the signed tree head
      description: Returns the public key that can be used to validate the signed tree head
      operationId: getPublicKey
      tags:
        - tlog
      produces:
        - application/x-pem-file
      responses:
        200:
          description: The public key
          schema:
            type: string
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/proof:
    get:
      summary: Get information required to generate a consistency proof for the transparency log
      description: Returns a list of hashes for specified tree sizes that can be used to confirm the consistency of the transparency log
      operationId: getLogProof
      tags:
        - tlog
      parameters:
        - in: query
          name: firstSize
          type: integer
          default: 1
          minimum: 1
          description: >
            The size of the tree that you wish to prove consistency from (1 means the beginning of the log)
            Defaults to 1 if not specified
        - in: query
          name: lastSize
          type: integer
          required: true
          minimum: 1
          description: The size of the tree that you wish to prove consistency to
      responses:
        200:
          description: All hashes required to compute the consistency proof
          schema:
            $ref: '#/definitions/ConsistencyProof'
        400:
          $ref: '#/responses/BadContent'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/entries:
    post:
      summary: Creates an entry in the transparency log
      description: >
        Creates an entry in the transparency log for a detached signature, public key, and content.
        Items can be included in the request or fetched by the server when URLs are specified.
      operationId: createLogEntry
      tags:
        - entries
      parameters:
        - in: body
          name: proposedEntry
          schema:
            $ref: '#/definitions/ProposedEntry'
          required: true
      responses:
        201:
          description: Returns the entry created in the transparency log
          headers:
            ETag:
              type: string
              description: UUID of log entry
            Location:
              type: string
              description: URI location of log entry
              format: uri
          schema:
            $ref: '#/definitions/LogEntry'
        400:
          $ref: '#/responses/BadContent'
        409:
          $ref: '#/responses/Conflict'
        default:
          $ref: '#/responses/InternalServerError'
    get:
      summary: Retrieves an entry from the transparency log (if it exists) by index
      operationId: getLogEntryByIndex
      tags:
        - entries
      parameters:
        - in: query
          name: logIndex
          type: integer
          required: true
          minimum: 0
          description: specifies the index of the entry in the transparency log to be retrieved
      responses:
        200:
          description: the entry in the transparency log requested
          schema:
            $ref: '#/definitions/LogEntry'
        404:
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/entries/{entryUUID}:
    get:
      summary: Retrieves an entry from the transparency log (if it exists) by UUID
      operationId: getLogEntryByUUID
      tags:
        - entries
      parameters:
        - in: path
          name: entryUUID
          type: string
          required: true
          pattern: '^[0-9a-fA-F]{64}$'
          description: the UUID of the entry to be retrieved from the log. The UUID is also the merkle tree hash of the entry.
      responses:
        200:
          description: the entry in the transparency log requested
          schema:
            $ref: '#/definitions/LogEntry'
        404:
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/entries/{entryUUID}/proof:
    get:
      summary: Get information required to generate an inclusion proof for a specified entry in the transparency log
      description: Returns root hash, tree size, and a list of hashes that can be used to calculate proof of an entry being included in the transparency log
      operationId: getLogEntryProof
      tags:
        - entries
      parameters:
        - in: path
          name: entryUUID
          type: string
          required: true
          pattern: '^[0-9a-fA-F]{64}$'
          description: the UUID of the entry for which the inclusion proof information should be returned
      responses:
        200:
          description: Information needed for a client to compute the inclusion proof
          schema:
            $ref: '#/definitions/InclusionProof'
        404:
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/entries/retrieve:
    post:
      summary: Searches transparency log for one or more log entries
      operationId: searchLogQuery
      tags:
        - entries
      parameters:
        - in: body
          name: entry
          required: true
          schema:
            $ref: '#/definitions/SearchLogQuery'
      responses:
        200:
          description: Returns zero or more entries from the transparency log, according to how many were included in request query
          schema:
            type: array
            items:
              $ref: '#/definitions/LogEntry'
        400:
          $ref: '#/responses/BadContent'
        default:
          $ref: '#/responses/InternalServerError'

definitions:
  ProposedEntry:
    type: object
    discriminator: kind
    properties:
      kind:
        type: string
    required:
      - kind

  rekord:
    type: object
    description: Rekord object
    allOf:
    - $ref: '#/definitions/ProposedEntry'
    - properties:
        apiVersion:
          type: string
          pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
        spec:
          type: object
          $ref: 'pkg/types/rekord/rekord_schema.json'
      required:
        - apiVersion
        - spec
      additionalProperties: false

  rpm:
    type: object
    description: RPM object
    allOf:
    - $ref: '#/definitions/ProposedEntry'
    - properties:
        apiVersion:
          type: string
          pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
        spec:
          type: object
          $ref: 'pkg/types/rpm/rpm_schema.json'
      required:
        - apiVersion
        - spec
      additionalProperties: false

  LogEntry:
    type: object
    additionalProperties:
      type: object
      properties:
        logIndex:
          type: integer
          minimum: 0
        body:
          type: object
          additionalProperties: true
        integratedTime:
          type: integer
      required:
        - "body"

  SearchIndex:
    type: object
    properties:
      publicKey:
        type: object
        properties:
          format:
            type: string
            enum: ['pgp','x509','minisign', 'ssh']
          content:
            type: string
            format: byte
          url:
            type: string
            format: uri
        required:
          - "format"
      hash:
        type: string
        pattern: '^[0-9a-fA-F]{64}$'

  SearchLogQuery:
    type: object
    properties:
      entryUUIDs:
        type: array
        items:
          type: string
          minItems: 1
          pattern: '^[0-9a-fA-F]{64}$'
      logIndexes:
        type: array
        minItems: 1
        items:
          type: integer
          minimum: 0
      entries:
        type: array
        items:
          $ref: '#/definitions/ProposedEntry'
          minItems: 1

  LogInfo:
    type: object
    properties:
      rootHash:
        type: string
        description: The current hash value stored at the root of the merkle tree
        pattern: '^[0-9a-fA-F]{64}$'
      treeSize:
        type: integer
        description: The current number of nodes in the merkle tree
        minimum: 1
      signedTreeHead:
        type: object
        description: The current signed tree head
        properties: 
          keyHint:
            type: string
            description: Key hint
            format: byte
          logRoot:
            type: string
            description: Log root
            format: byte
          signature:
            type: string
            description: Signature for log root
            format: byte
        required:
          - keyHint
          - logRoot
          - signature
    required:
      - rootHash
      - treeSize
      - signedTreeHead

  ConsistencyProof:
    type: object
    properties:
      rootHash:
        type: string
        description: The hash value stored at the root of the merkle tree at the time the proof was generated
        pattern: '^[0-9a-fA-F]{64}$'
      hashes:
        type: array
        items:
          type: string
          description: SHA256 hash value expressed in hexadecimal format
          pattern: '^[0-9a-fA-F]{64}$'
    required:
      - rootHash
      - hashes

  InclusionProof:
    type: object
    properties:
      logIndex:
        type: integer
        description: The index of the entry in the transparency log
        minimum: 0
      rootHash:
        description: The hash value stored at the root of the merkle tree at the time the proof was generated
        type: string
        pattern: '^[0-9a-fA-F]{64}$'
      treeSize:
        type: integer
        description: The size of the merkle tree at the time the inclusion proof was generated
        minimum: 1
      hashes:
        description: A list of hashes required to compute the inclusion proof, sorted in order from leaf to root
        type: array
        items:
          type: string
          description: SHA256 hash value expressed in hexadecimal format
          pattern: '^[0-9a-fA-F]{64}$'
    required:
      - logIndex
      - rootHash
      - treeSize
      - hashes

  Error:
    type: object
    properties:
      code:
        type: integer
      message:
        type: string

responses:
  BadContent:
    description: The content supplied to the server was invalid
    schema:
      $ref: "#/definitions/Error"
  Conflict:
    description: The request conflicts with the current state of the transparency log
    schema:
      $ref: "#/definitions/Error"
    headers:
      Location:
        type: string
        format: uri
  NotFound:
    description: The content requested could not be found
  InternalServerError:
    description: There was an internal error in the server while processing the request
    schema:
      $ref: "#/definitions/Error"