openapi-spec.yml

# Copyright SecureKey Technologies Inc.
#
# SPDX-License-Identifier: Apache-2.0

swagger: "2.0"
info:
  title: Vault Server
  description: |
    The Vault Server is a multi-tenant facade over remote Confidential Storage vaults and WebKMS keystores. Each Vault
    Server vault corresponds to a unique Confidential Storage vault and a WebKMS keystore.
    Each Vault Server vault is identified by a DID.

    Confidential Storage vaults are permissioned "buckets" where users can securely store arbitrary documents.
    WebKMS keystores manage signing and encryption keys. Control of both a vault's Confidential Storage vault and
    WebKMS keystore are cryptographically bound to the key material in the vault's DID.
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
paths:
  /vaults:
    post:
      tags:
        - required
      produces:
        - application/json
      description: |
        Creates a new vault. A new DID is minted and used as the vault's identifier.

        All documents stored in this vault are deposited in a new Confidential Storage vault backend unique to this vault.
        The documents are encrypted with encryption keys managed remotely in a new WebKMS keystore unique to this vault.

        Control of the Confidential Storage vault and the WebKMS keystore is bound to the vault's DID and codified
        in opaque 'authTokens'. These tokens are part of the Vault's properties and are required only when accessing
        the backing Confidential Storage vault and WebKMS keystore directly.
      responses:
        201:
          description: Vault created successfully.
          headers:
            Location:
              description: Location of the vault.
              type: string
          schema:
            $ref: "#/definitions/Vault"
          examples: {
            "application/json": {
              "id": "did:example:123",
              "edv": {
                "uri": "https://edv.example.com/encrypted-data-vaults/123",
                "authToken": "123456789abcdefghi"
              },
              "kms": {
                "uri": "https://kms.example.com/keystores/xyz",
                "authToken": "v6gmMNam3uVAjZpfkcJCwD"
              }
            }
          }
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
    delete:
      description: |
        Deletes an existing vault.

        The vault's unique Confidential Storage vault and WebKMS keystore are deleted, and its DID is deactivated.
      responses:
        200:
          description: Vault deleted, with all contents purged and its DID deactivated.
        404:
          description: Vault does not exist.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
  /vaults/{vaultID}/docs:
    parameters:
      - in: path
        name: vaultID
        required: true
        type: string
        description: The Vault's ID (DID).
    post:
      tags:
        - required
      consumes:
        - application/json
      produces:
        - application/json
      description: |
        Create a document by encrypting it and storing it in the vault.

        Users can store any JSON document and specify a unique identifier of their choosing. The identifier will
        be mapped to a random value to use as identifier in the backing Confidential Storage vault.

        The response does not replay the document back. Instead, it contains metadata about the document,
        including its unique Confidential Storage document URI and unique WebKMS encryption key.
      parameters:
        - name: document
          in: body
          required: true
          schema:
            $ref: "#/definitions/Document"
      responses:
        201:
          description: Document encrypted and stored successfully.
          headers:
            Location:
              description: Location of the document's metadata.
              type: string
          schema:
            $ref: "#/definitions/DocumentMetadata"
        400:
          description: Bad request.
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Vault not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
  /vaults/{vaultID}/docs/{docID}/metadata:
    parameters:
      - name: vaultID
        in: path
        type: string
        required: true
        description: The vault's ID (DID).
      - name: docID
        in: path
        type: string
        required: true
        description: The document's ID.
    get:
      description: Metadata about a stored document.
      produces:
        - application/json
      responses:
        200:
          description: The document's metadata.
          schema:
            $ref: "#/definitions/DocumentMetadata"
        404:
          description: Vault or document not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
  /vaults/{vaultID}/authorizations:
    parameters:
      - in: path
        name: vaultID
        type: string
        required: true
        description: The vault's ID (DID).
    post:
      tags:
        - required
      description: |
        Authorize a third party (`requestingParty`) to gain access to a document in the backing Confidential Storage vault.
        Authorization is also granted for the third party to use the remote WebKMS encryption key to decrypt the contents
        of the document.

        Only `scope` and `requestingParty` need to be provided to create an authorization:

        - The `requestingParty` is identified by a keyID in the format of a DID URL. This url MUST be resolvable
        by the Vault Server.
        - The authorization's scope indicates the actions allowed, the object on which to perform them (eg. a document),
        as well as any optional caveats (eg. expiration).

        The response contains opaque authorization tokens for use at the vault's remote Confidential Storage vault and
        WebKMS keystore.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: authorization
          in: body
          required: true
          schema:
            $ref: "#/definitions/Authorization"
      responses:
        201:
          description: Authorization created.
          headers:
            Location:
              description: Location of the authorization
              type: string
          schema:
            $ref: "#/definitions/Authorization"
          examples: {
            "application/json": {
              "id": "123",
              "scope": {
                "target": "batphone",
                "actions": [ "read" ],
                "caveats": [
                  {
                    "type": "expiry",
                    "duration": 600
                  }
                ]
              },
              "requestingParty": "did:example:phone_dialer_47583#key1",
              "authTokens": {
                "edv": "21tDAKCERh95uGgKbJNHYp",
                "kms": "bcehfew7h32f32h7af3"
              }
            }
          }
        400:
          description: Bad request.
          schema:
            $ref: "#/definitions/Error"
        404:
          description: Vault not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
  /vaults/{vaultID}/authorizations/{authorizationID}:
    parameters:
      - in: path
        name: vaultID
        type: string
        required: true
        description: The vault's ID (DID).
      - in: path
        name: authorizationID
        type: string
        required: true
        description: The authorization's ID.
    get:
      description: Fetch an existing authorization.
      produces:
        - application/json
      responses:
        200:
          description: An authorization object.
          schema:
            $ref: "#/definitions/Authorization"
        404:
          description: Vault or authorization not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
    delete:
      description: Delete an existing authorization. This revokes the tokens issued by the authorization.
      responses:
        200:
          description: Authorization deleted.
        404:
          description: Vault or authorization not found.
          schema:
            $ref: "#/definitions/Error"
        500:
          description: An error occurred.
          schema:
            $ref: "#/definitions/Error"
definitions:
  Vault:
    description: |
      A user-friendly abstraction over a Confidential Storage vault with an accompanying WebKMS keystore
      to encrypt documents.
    type: object
    required:
      - id
      - edv
      - kms
    properties:
      id:
        type: string
        description: A DID that uniquely identifies this vault.
      edv:
        type: object
        description: Properties of the backing Confidential Storage vault.
        properties:
          uri:
            type: string
            description: The backing Confidential Storage vault's unique URI.
          authToken:
            type: string
            description: Opaque authorization token assigned to the vault's DID.
      kms:
        type: object
        description: Properties of the backing WebKMS keystore.
        properties:
          uri:
            type: string
            description: The backing WebKMS keystore's unique URI.
          authToken:
            type: string
            description: Opaque authorization token assigned to the vault's DID.
  Document:
    description: A JSON document in plaintext (not encrypted).
    type: object
    example: {
      "id": "batphone",
      "content": {
        "phone_number": "+12125557972"
      }
    }
    required:
      - id
      - content
    properties:
      id:
        description: |
          The user-chosen identifier to associate with the document.

          This identifier is mapped to the randomized value used to identify the encrypted document at the backing
          Confidential Storage vault.
        type: string
      content:
        description: The JSON document to be encrypted and stored in the vault.
        type: object
  DocumentMetadata:
    description: Metadata about a document.
    type: object
    example: {
      "docID": "batphone",
      "edvDocURI": "https://edv.example.com/encrypted-data-vaults/abc/documents/123",
      "encKeyURI": "https://kms.example.com/kms/keystores/mop/keys/xyz"
    }
    required:
      - docID
      - edvDocURI
    properties:
      docID:
        type: string
        description: The document's identifier provided by the user.
      edvDocURI:
        type: string
        description: The document's unique Confidential Storage URI.
      encKeyURI:
        type: string
        description: The URI of the document's unique encryption key.
  Authorization:
    description: |
      An authorization object encodes the permissions granted to a third party. Its `scope` details the allowed
      action and the object on which the action will be performed. The `requestingParty` is the third party
      allowed to perform those actions.

      `authTokens` contains opaque tokens granting the `requestingParty` access to the document in the
      backing Confidential Storage vault as well as the encryption keys in the remote WebKMS keystore.
    type: object
    example: {
      "scope": {
        "target": "batphone",
        "actions": [ "read" ],
        "caveats": [
          {
            "type": "expiry",
            "duration": 600
          }
        ]
      },
      "requestingParty": "did:example:phone_dialer_47583#key1"
    }
    required:
      - scope
      - requestingParty
    properties:
      id:
        description: The authorization's unique ID.
        type: string
      scope:
        $ref: "#/definitions/Scope"
      requestingParty:
        description: KeyID in the format of a DID URL that identifies the party granted authorization.
        type: string
      authTokens:
        description: |
          Opaque authorization tokens granting access to the document in the Confidential Storage vault as well
          as the document's unique encryption key in the remote WebKMS keystore.
        type: object
        properties:
          edv:
            type: string
          kms:
            type: string
  Scope:
    type: object
    required:
      - target
      - actions
    properties:
      target:
        type: string
      actions:
        description: The allowed actions on the target.
        type: array
        items:
          type: string
          enum:
            - read
            - write
      caveats:
        description: |
          A set of orthogonal constraints placed on the authorization.
          For example, an authorization may allow to read a document but only for a certain length of time (caveat).
        type: array
        items:
          $ref: "#/definitions/Caveat"
  Caveat:
    type: object
    required:
      - type
    properties:
      type:
        type: string
    discriminator: type
  ExpiryCaveat:
    allOf:
      - $ref: "#/definitions/Caveat"
      - type: object
        properties:
          duration:
            type: integer
            description: Duration (in seconds) for which this authorization will remain valid.
  Error:
    type: object
    properties:
      errMessage:
        type: string