openapi.yaml

#
# Copyright 2021 The Sigstore Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

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

host: rekor.sigstore.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:
        - pubkey
      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 and inclusion proof 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 along with an inclusion proof
          schema:
            $ref: '#/definitions/LogEntry'
        404:
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/log/entries/{entryUUID}:
    get:
      summary: Get log entry and information required to generate an inclusion proof for the entry in the transparency log
      description: Returns the entry, 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: getLogEntryByUUID
      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/LogEntry'
        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'
  
  /api/v1/timestamp:
    post:
      summary: Generates a new timestamp response and creates a new log entry for the timestamp in the transparency log
      operationId: getTimestampResponse
      tags:
        - timestamp
      consumes:
        - application/timestamp-query
      produces:
        - application/timestamp-reply
      parameters:
        - in: body
          name: request
          required: true
          schema:
            type: string
            format: binary
      responses:
        201:
          description: Returns a timestamp response and the location of the log entry in the transprency log
          schema:
            type: string
            format: binary
          headers:
            ETag:
              type: string
              description: UUID of the log entry made for the timestamp response
            Location:
              type: string
              description: URI location of the log entry made for the timestamp response
              format: uri
            Index:
              type: integer
              description: Log index of the log entry made for the timestamp response
        400:
          $ref: '#/responses/BadContent'
        501:
          $ref: '#/responses/NotImplemented'
        default:
          $ref: '#/responses/InternalServerError'

  /api/v1/timestamp/certchain:
    get:
      summary: Retrieve the certfiicate chain for timestamping that can be used to validate trusted timestamps
      description: Returns the certfiicate chain for timestamping that can be used to validate trusted timestamps
      operationId: getTimestampCertChain
      tags:
        - timestamp
      produces:
        - application/pem-certificate-chain
      responses:
        200:
          description: The PEM encoded cert chain
          schema:
            type: string
        404:
          $ref: '#/responses/NotFound'
        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 package
    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

  alpine:
    type: object
    description: Alpine package
    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/alpine/alpine_schema.json'
      required:
        - apiVersion
        - spec
      additionalProperties: false

  intoto:
    type: object
    description: Intoto 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/intoto/intoto_schema.json'
      required:
        - apiVersion
        - spec
      additionalProperties: false

  jar:
    type: object
    description: Java Archive (JAR)
    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/jar/jar_schema.json'
      required:
        - apiVersion
        - spec
      additionalProperties: false

  rfc3161:
    type: object
    description: RFC3161 Timestamp
    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/rfc3161/rfc3161_schema.json'
      required:
        - apiVersion
        - spec
      additionalProperties: false

  LogEntry:
    type: object
    additionalProperties:
      type: object
      properties:
        logID:
          type: string
          pattern: '^[0-9a-fA-F]{64}$'
          description: This is the SHA256 hash of the DER-encoded public key for the log at the time the entry was included in the log
        logIndex:
          type: integer
          minimum: 0
        body:
          type: object
          additionalProperties: true
        integratedTime:
          type: integer
        verification:
          type: object
          properties:
            inclusionProof:
              $ref: '#/definitions/InclusionProof'
            signedEntryTimestamp:
              type: string
              format: byte
              # To verify the signedEntryTimestamp:
                # 1. Remove the Verification object from the JSON Document
                # 2. Canonicalize the remaining JSON document by following RFC 8785 rules
                # 3. Verify the canonicalized payload and signedEntryTimestamp against rekor's public key
              description: Signature over the logID, logIndex, body and integratedTime.
      required:
        - "logID"
        - "logIndex"
        - "body"
        - "integratedTime"

  SearchIndex:
    type: object
    properties:
      email:
        type: string
        format: email
      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: '^(sha256:)?[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: string
        format: signedCheckpoint
        description: The current signed tree head
    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
  NotImplemented:
    description: The content requested is not implemented
  InternalServerError:
    description: There was an internal error in the server while processing the request
    schema:
      $ref: "#/definitions/Error"