path: root/src/mongo/crypto/fle_field_schema.idl

# Copyright (C) 2022-present MongoDB, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the Server Side Public License, version 1,
# as published by MongoDB, Inc.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# Server Side Public License for more details.
#
# You should have received a copy of the Server Side Public License
# along with this program. If not, see
# <http://www.mongodb.com/licensing/server-side-public-license>.
#
# As a special exception, the copyright holders give permission to link the
# code of portions of this program with the OpenSSL library under certain
# conditions as described in each individual source file and distribute
# linked combinations including the program with the OpenSSL library. You
# must comply with the Server Side Public License in all respects for
# all of the code used other than as permitted herein. If you modify file(s)
# with this exception, you may extend this exception to your version of the
# file(s), but you are not obligated to do so. If you do not wish to do so,
# delete this exception statement from your version. If you delete this
# exception statement from all source files in the program, then also delete
# it in the license file.

global:
    cpp_namespace: "mongo"
    cpp_includes:
      - "mongo/crypto/fle_fields_util.h"

imports:
    - "mongo/db/basic_types.idl"
    - "mongo/crypto/encryption_fields.idl"

enums:
    EncryptedBinDataType:
        description: "Subtypes with an BinData 6, this is the first byte of the payload"
        type: int
        values:
          # FLE 1 Payloads
          kPlaceholder : 0 # see FLEEncryptionPlaceholder
          kDeterministic : 1
          kRandom : 2
          # FLE 2
          # FLE 2 Client-side
          kFLE2Placeholder : 3            # see FLE2EncryptionPlaceholder
          kFLE2InsertUpdatePayload : 4    # see FLE2InsertUpdatePayload
          kFLE2FindEqualityPayload : 5    # see FLE2FindEqualityPayload

          # FLE 2 Server-side
          kFLE2UnindexedEncryptedValue : 6 # see FLE2IndexedEqualityEncryptedValue
          kFLE2EqualityIndexedValue : 7

          # Transient encrypted data in query rewrites, not persisted
          # same as BinDataGeneral but redacted
          kFLE2TransientRaw : 8

          kFLE2RangeIndexedValue : 9      # see FLE2IndexedRangeEncryptedValue
          kFLE2FindRangePayload : 10      # see FLE2FindRangePayload

    FleVersion:
        description: "The version / type of field-level encryption in use."
        type: int
        values:
            kFle1: 1
            kFle2: 2

    FleAlgorithmInt:
        description: "The algorithm used to encrypt fields for field level encryption represented
            as an unsigned integer."
        type: int
        values:
            kDeterministic: 1
            kRandom: 2

    Fle2AlgorithmInt:
        description: "The algorithm used to encrypt fields for field level encryption represented
            as an unsigned integer."
        type: int
        values:
            kUnindexed: 1
            kEquality: 2
            kRange: 3

    Fle2PlaceholderType:
        description: "The type of payload to generate from a placeholder"
        type: int
        values:
            kInsert: 1
            kFind: 2

types:
  encrypted_numeric_element:
    bson_serialization_type:
    - date
    - decimal
    - double
    - int
    - long
    description: A value with any encrypted range numeric BSON type.
    cpp_type: "mongo::IDLAnyType"
    serializer: mongo::IDLAnyType::serializeToBSON
    deserializer: mongo::IDLAnyType::parseFromBSON

structs:
    EncryptionPlaceholder:
        description: "Implements Encryption BinData (subtype 6) sub-subtype 0, the intent-to-encrypt
            mapping. Contains a value to encrypt and a description of how it should be encrypted."
        strict: true
        fields:
          a:
            description: "The encryption algorithm to be used."
            type: FleAlgorithmInt
            cpp_name: algorithm
          ki:
            description: "Used to query the key vault by _id. If omitted, ka must be specified."
            type: uuid
            cpp_name: keyId
            optional: true
          ka:
            description: "Used to query the key vault by keyAltName. If omitted,
                ki must be specified."
            type: string
            cpp_name: keyAltName
            optional: true
          v:
            description: "value to encrypt"
            type: IDLAnyType
            cpp_name: value

    FLE2EncryptionPlaceholder:
        description: "Implements Encryption BinData (subtype 6) sub-subtype 0, the intent-to-encrypt
            mapping. Contains a value to encrypt and a description of how it should be encrypted."
        strict: true
        cpp_validator_func: "validateIDLFLE2EncryptionPlaceholder"
        fields:
          t:
            description: "The type number, determines what payload to replace the placeholder with"
            type: Fle2PlaceholderType
            cpp_name: type
          a:
            description: "The encryption algorithm to be used."
            type: Fle2AlgorithmInt
            cpp_name: algorithm
          ki:
            description: "IndexKeyId, Used to query the key vault by _id."
            type: uuid
            cpp_name: indexKeyId
          ku:
            description: "UserKeyId, Used to query the key vault by _id.,
              Typically same as IndexKeyId unless explicit encryption is used."
            type: uuid
            cpp_name: userKeyId
          v:
            description: "value to encrypt"
            type: IDLAnyType
            cpp_name: value
          cm:
            description: "Queryable Encryption max contention counter"
            type: long
            cpp_name: maxContentionCounter
          s:
            description: "Queryable Encryption range hypergraph sparsity factor"
            type: int
            cpp_name: sparsity
            optional: true
            validator: { gte: 0, lte: 3 }

    EdgeTokenSet:
        description: "Payload of an indexed field to insert or update"
        strict: true
        fields:
          d:
            description: "EDCDerivedFromDataTokenAndCounter"
            type: bindata_generic
            cpp_name: edcDerivedToken
          s:
            description: "ESCDerivedFromDataTokenAndCounter"
            type: bindata_generic
            cpp_name: escDerivedToken
          c:
            description: "ECCDerivedFromDataTokenAndCounter"
            type: bindata_generic
            cpp_name: eccDerivedToken
          p:
            description: "Encrypted tokens"
            type: bindata_generic
            cpp_name: encryptedTokens

    FLE2InsertUpdatePayload:
        description: "Payload of an indexed field to insert or update"
        strict: true
        fields:
          d:
            description: "EDCDerivedFromDataTokenAndCounter"
            type: bindata_generic
            cpp_name: edcDerivedToken
          s:
            description: "ESCDerivedFromDataTokenAndCounter"
            type: bindata_generic
            cpp_name: escDerivedToken
          c:
            description: "ECCDerivedFromDataTokenAndCounter"
            type: bindata_generic
            cpp_name: eccDerivedToken
          p:
            description: "Encrypted tokens"
            type: bindata_generic
            cpp_name: encryptedTokens
          u:
            description: "Index KeyId"
            type: uuid
            cpp_name: indexKeyId
          t:
            description: "Encrypted type"
            type: safeInt
            cpp_name: type
          v:
            description: "Encrypted value"
            type: bindata_generic
            cpp_name: value
          e:
            description: "ServerDataEncryptionLevel1Token"
            type: bindata_generic
            cpp_name: serverEncryptionToken
          g:
            description: "Array of Edges"
            type: array<EdgeTokenSet>
            cpp_name: edgeTokenSet
            optional: true

    FLE2DeletePayload:
        description: "Payload of an indexed field to delete"
        strict: true
        fields:
          o:
            description: "ECOCToken"
            type: bindata_generic
            cpp_name: ecocToken
          e:
            description: "ServerDataEncryptionLevel1Token"
            type: bindata_generic
            cpp_name: serverEncryptionToken

    FLE2FindEqualityPayload:
        description: "Payload for an equality find"
        strict: true
        fields:
          d:
            description: "EDCDerivedFromDataToken"
            type: bindata_generic
            cpp_name: edcDerivedToken
          s:
            description: "ESCDerivedFromDataToken"
            type: bindata_generic
            cpp_name: escDerivedToken
          c:
            description: "ECCDerivedFromDataToken"
            type: bindata_generic
            cpp_name: eccDerivedToken
          e:
            description: "ServerDataEncryptionLevel1Token"
            type: bindata_generic
            cpp_name: serverEncryptionToken
            optional: true # For backwards compat, make this optional
          cm:
            description: "Queryable Encryption max counter"
            type: long
            cpp_name: maxCounter
            optional: true

    EdgeFindTokenSet:
        description: "Payload of an edge to query for"
        strict: true
        fields:
          d:
            description: "EDCDerivedFromDataToken"
            type: bindata_generic
            cpp_name: edcDerivedToken
          s:
            description: "ESCDerivedFromDataToken"
            type: bindata_generic
            cpp_name: escDerivedToken
          c:
            description: "ECCDerivedFromDataToken"
            type: bindata_generic
            cpp_name: eccDerivedToken

    FLE2FindRangePayload:
        description: "Payload for a range find"
        strict: true
        fields:
          g:
            description: "Array of Edges"
            type: array<EdgeFindTokenSet>
            cpp_name: edges
          e:
            description: "ServerDataEncryptionLevel1Token"
            type: bindata_generic
            cpp_name: serverEncryptionToken
          cm:
            description: "Queryable Encryption max counter"
            type: long
            cpp_name: maxCounter

    EncryptionInformation:
        description: "Implements Encryption Information which includes the schema for Queryable Encryption that is consumed by query_analysis, queries and write_ops"
        strict: true
        fields:
          type:
            description: "The version number"
            type: safeInt
            default: 1
            stability: unstable
          deleteTokens:
            description: "A map of field paths to FLEDeletePayload"
            type: object_owned
            optional: true
            stability: unstable
          schema:
            description: "A map of NamespaceString to EncryptedFieldConfig"
            type: object_owned
            stability: unstable
          crudProcessed:
            description: "A boolean to indicate whether the CRUD layer has already processed this Queryable Encryption request. Used to prevent infinite recursion."
            type: bool
            optional: true
            stability: unstable

    ecocDocument:
        description: "foo"
        strict: true
        fields:
          _id:
            description: "Random id"
            type: objectid
          fieldName:
            description: "Name of field"
            type: string
          value:
            description: "Encrypted value"
            type: bindata_generic

    FLE2RangeSpec:
        description: "Range find specification that is encoded inside of a FLE2EncryptionPlaceholder."
        strict: true
        cpp_validator_func: "validateIDLFLE2RangeSpec"
        fields:
          min:
            description: "The minimum value for an encrypted range query."
            type: IDLAnyType
          minIncluded:
            description: "Indicates if the lower bound should be included in the range."
            type: bool
          max:
            description: "The maximum value for an encrypted range query."
            type: IDLAnyType
          maxIncluded:
            description: "Indicates if the upper bound should be included in the range."
            type: bool

    FLE2RangeInsertSpec:
        description: "Range insert specification that is encoded inside of a FLE2EncryptionPlaceholder."
        strict: true
        fields:
          v:
            description: "Value to encrypt"
            type: encrypted_numeric_element
            cpp_name: value
          lb:
            description: "Queryable Encryption lower bound for range"
            type: encrypted_numeric_element
            cpp_name: lowerBound
          ub:
            description: "Queryable Encryption upper bound for range"
            type: encrypted_numeric_element
            cpp_name: upperBound