diff --git a/apple/swift_homomorphic_encryption/api/v1/api.proto b/apple/swift_homomorphic_encryption/api/v1/api.proto index 201a4b5..3f4d1ea 100644 --- a/apple/swift_homomorphic_encryption/api/v1/api.proto +++ b/apple/swift_homomorphic_encryption/api/v1/api.proto @@ -15,40 +15,8 @@ syntax = "proto3"; package apple.swift_homomorphic_encryption.api.v1; -import "apple/swift_homomorphic_encryption/pir/v1/pir.proto"; -import "apple/swift_homomorphic_encryption/pir/v1/pir_algorithm.proto"; -import "apple/swift_homomorphic_encryption/v1/he.proto"; - -// Evaluation key metadata. -message EvaluationKeyMetadata { - // Timestamp of the (secret) key generation, seconds from Unix epoch. - uint64 timestamp = 1; - // Key identifier (SHA256 of `EvaluationKeyConfig`). - bytes identifier = 2; -} - -// Status of the evaluation key. -message KeyStatus { - // When was this key last updated (seconds from Unix epoch), 0 when key is missing. - uint64 timestamp = 1; - // Configuration for the key. - apple.swift_homomorphic_encryption.v1.EvaluationKeyConfig key_config = 2; - reserved 3; -} - -// Container for multiple evaluation keys. -message EvaluationKeys { - // Evaluation keys. - repeated EvaluationKey keys = 1; -} - -// Evaluation key upload. -message EvaluationKey { - // Metadata for the key. - EvaluationKeyMetadata metadata = 1; - // Evaluation key. - apple.swift_homomorphic_encryption.v1.SerializedEvaluationKey evaluation_key = 2; -} +import "apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto"; +import "apple/swift_homomorphic_encryption/api/v1/api_pir.proto"; // Request for server side configurations. message ConfigRequest { @@ -110,58 +78,3 @@ message Response { } reserved 2; } - -// Configuration for one shard of the PIR database. -message PIRShardConfig { - // Number of entries in the shard. - uint64 num_entries = 1; - // Size in bytes of entries in the shard. - uint64 entry_size = 2; - // Dimensions that make up the hypercube. - repeated uint64 dimensions = 3; - // Unique identifier for the shard. - optional string shard_id = 4; - // Whether to compress vectorized PIR response. - optional bool compress_vectorized_pir_response = 5; - // The additional "batching" introduced in vectorized pir to accommodate large entry size. - optional uint64 vectorized_pir_internal_batching_size = 6; -} - -// Configuration for one PIR usecase. -message PIRConfig { - // Encryption parameters. - apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1; - // Configuration for each shard. - repeated PIRShardConfig shard_configs = 2; - // Parameters specific to KeywordPIR. - apple.swift_homomorphic_encryption.pir.v1.KeywordPirParameters keyword_pir_params = 3; - // Server-side PIR algorithm. - apple.swift_homomorphic_encryption.pir.v1.PirAlgorithm algorithm = 4; - // Maximum number of queries allowed in a single request. - uint64 batch_size = 5; - // Hash of EvaluationKeyConfig. - bytes evaluation_key_config_hash = 6; - reserved 7, 8; -} - -// PIR Request. -message PIRRequest { - // Shard index where this request should be routed. Can be overridden by shard_id. - uint32 shard_index = 1; - // Encrypted query. - apple.swift_homomorphic_encryption.pir.v1.EncryptedIndices query = 2; - // Evaluation key metadata. - EvaluationKeyMetadata evaluation_key_metadata = 3; - // Hash of the `PIRConfig` used to construct the query. - bytes configuration_hash = 4; - // If set, route request to a shard with this `shard_id` instead of `shard_index`. - optional string shard_id = 5; - // If set, evaluation key to query with. Will override evaluation key stored server-side. - optional EvaluationKey evaluation_key = 6; -} - -// PIR Response. -message PIRResponse { - // Encrypted replies, each of which is a ciphertext vector. - repeated apple.swift_homomorphic_encryption.v1.SerializedCiphertextVec replies = 1; -} diff --git a/apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto b/apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto new file mode 100644 index 0000000..bdebfc3 --- /dev/null +++ b/apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto @@ -0,0 +1,49 @@ +// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project 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. + +syntax = "proto3"; +package apple.swift_homomorphic_encryption.api.v1; + +import "apple/swift_homomorphic_encryption/v1/he.proto"; + +// Evaluation key metadata. +message EvaluationKeyMetadata { + // Timestamp of the (secret) key generation, seconds from Unix epoch. + uint64 timestamp = 1; + // Key identifier (SHA256 of `EvaluationKeyConfig`). + bytes identifier = 2; +} + +// Status of the evaluation key. +message KeyStatus { + // When was this key last updated (seconds from Unix epoch), 0 when key is missing. + uint64 timestamp = 1; + // Configuration for the key. + apple.swift_homomorphic_encryption.v1.EvaluationKeyConfig key_config = 2; + reserved 3; +} + +// Container for multiple evaluation keys. +message EvaluationKeys { + // Evaluation keys. + repeated EvaluationKey keys = 1; +} + +// Evaluation key upload. +message EvaluationKey { + // Metadata for the key. + EvaluationKeyMetadata metadata = 1; + // Evaluation key. + apple.swift_homomorphic_encryption.v1.SerializedEvaluationKey evaluation_key = 2; +} diff --git a/apple/swift_homomorphic_encryption/api/v1/api_pir.proto b/apple/swift_homomorphic_encryption/api/v1/api_pir.proto new file mode 100644 index 0000000..c398e70 --- /dev/null +++ b/apple/swift_homomorphic_encryption/api/v1/api_pir.proto @@ -0,0 +1,76 @@ +// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project 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. + +syntax = "proto3"; +package apple.swift_homomorphic_encryption.api.v1; + +import "apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto"; +import "apple/swift_homomorphic_encryption/pir/v1/pir.proto"; +import "apple/swift_homomorphic_encryption/pir/v1/pir_algorithm.proto"; +import "apple/swift_homomorphic_encryption/v1/he.proto"; + +// Configuration for one shard of the PIR database. +message PIRShardConfig { + // Number of entries in the shard. + uint64 num_entries = 1; + // Size in bytes of entries in the shard. + uint64 entry_size = 2; + // Dimensions that make up the hypercube. + repeated uint64 dimensions = 3; + // Unique identifier for the shard. + optional string shard_id = 4; + // Whether to compress vectorized PIR response. + optional bool compress_vectorized_pir_response = 5; + // The additional "batching" introduced in vectorized pir to accommodate large entry size. + optional uint64 vectorized_pir_internal_batching_size = 6; +} + +// Configuration for one PIR usecase. +message PIRConfig { + // Encryption parameters. + apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1; + // Configuration for each shard. + repeated PIRShardConfig shard_configs = 2; + // Parameters specific to KeywordPIR. + apple.swift_homomorphic_encryption.pir.v1.KeywordPirParameters keyword_pir_params = 3; + // Server-side PIR algorithm. + apple.swift_homomorphic_encryption.pir.v1.PirAlgorithm algorithm = 4; + // Maximum number of queries allowed in a single request. + uint64 batch_size = 5; + // Hash of EvaluationKeyConfig. + bytes evaluation_key_config_hash = 6; + reserved 7, 8; +} + +// PIR Request. +message PIRRequest { + // Shard index where this request should be routed. Can be overridden by shard_id. + uint32 shard_index = 1; + // Encrypted query. + apple.swift_homomorphic_encryption.pir.v1.EncryptedIndices query = 2; + // Evaluation key metadata. + EvaluationKeyMetadata evaluation_key_metadata = 3; + // Hash of the `PIRConfig` used to construct the query. + bytes configuration_hash = 4; + // If set, route request to a shard with this `shard_id` instead of `shard_index`. + optional string shard_id = 5; + // If set, evaluation key to query with. Will override evaluation key stored server-side. + optional EvaluationKey evaluation_key = 6; +} + +// PIR Response. +message PIRResponse { + // Encrypted replies, each of which is a ciphertext vector. + repeated apple.swift_homomorphic_encryption.v1.SerializedCiphertextVec replies = 1; +} diff --git a/apple/swift_homomorphic_encryption/api/v1/api_pnns.proto b/apple/swift_homomorphic_encryption/api/v1/api_pnns.proto new file mode 100644 index 0000000..9493894 --- /dev/null +++ b/apple/swift_homomorphic_encryption/api/v1/api_pnns.proto @@ -0,0 +1,71 @@ +// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project 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. + +syntax = "proto3"; +package apple.swift_homomorphic_encryption.api.v1; + +import "apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto"; +import "apple/swift_homomorphic_encryption/pnns/v1/pnns.proto"; +import "apple/swift_homomorphic_encryption/pnns/v1/pnns_distance_metric.proto"; +import "apple/swift_homomorphic_encryption/pnns/v1/pnns_matrix_packing.proto"; +import "apple/swift_homomorphic_encryption/v1/he.proto"; + +// Configuration for one PNNS usecase. +message PNNSConfig { + // Encryption parameters. + apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1; + // Factor by which to scale floating-point entries to integers. + uint64 scaling_factor = 2; + // Plaintext packing for the query. + apple.swift_homomorphic_encryption.pnns.v1.MatrixPacking plaintext_packing = 3; + // Number of entries in each vector. + uint32 vector_dimension = 4; + // Metric for similarity computation. + apple.swift_homomorphic_encryption.pnns.v1.DistanceMetric distance_metric = 5; + // hash of EvaluationKeyConfig. + bytes evaluation_key_config_hash = 6; + // For plaintext CRT, the list of extra plaintext moduli. + // The first plaintext modulus will be the one in `encryption_parameters`. + repeated uint64 extra_plaintext_moduli = 7; +} + +// PNNS Request +message PNNSRequest { + // optionally, the shard indices where this request should be routed + repeated uint32 shard_indices = 1; + // Encrypted query, one per plaintext CRT component + repeated apple.swift_homomorphic_encryption.pnns.v1.SerializedCiphertextMatrix query = 2; + // Key metadata + EvaluationKeyMetadata evaluation_key_metadata = 3; + // Identifier for the PNNSConfig used to construct the query + bytes config_id = 4; + // If set, evaluation key to query with. Will override evaluation key stored server-side + optional EvaluationKey evaluation_key = 5; +} + +// PNNS Shard Response +message PNNSShardResponse { + // Encrypted reply, one per plaintext CRT component + repeated apple.swift_homomorphic_encryption.pnns.v1.SerializedCiphertextMatrix reply = 1; + // A list of entry identifiers the server computed similarities for + repeated uint64 entry_ids = 2; + // Metadata for each entry in the database + repeated bytes entry_metadatas = 3; +} + +// PNNS Response +message PNNSResponse { + // PNNS responses from shards + repeated PNNSShardResponse shard_responses = 1; +}