Add protos for PrivateNearestNeighborsSearch

apple/swift_homomorphic_encryption/pnns/v1/pnns.proto

@@ -0,0 +1,44 @@
+// 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.pnns.v1;
+
+import "apple/swift_homomorphic_encryption/pnns/v1/pnns_matrix_packing.proto";
+import "apple/swift_homomorphic_encryption/v1/he.proto";
+
+// Stores a matrix of encrypted values in a serialized ciphertext for use in linear algebra
+// operations
+message SerializedCiphertextMatrix {
+  // Number of data rows stored in the ciphertext.
+  uint32 num_rows = 1;
+  // Number of data columns stored in the ciphertext.
+  uint32 num_columns = 2;
+  // Stores the encrypted data.
+  repeated apple.swift_homomorphic_encryption.v1.SerializedCiphertext ciphertexts = 3;
+  // Packing algorithm for the plaintext data.
+  MatrixPacking packing = 4;
+}
+
+// Serialized plaintext matrix
+message SerializedPlaintextMatrix {
+  // Number of rows in the data encoded in the plaintext matrix.
+  uint32 num_rows = 1;
+  // Number of columns in the data encoded in the plaintext matrix.
+  uint32 num_columns = 2;
+  // Encoded values.
+  repeated apple.swift_homomorphic_encryption.v1.SerializedPlaintext plaintexts = 3;
+  // Plaintext packing.
+  MatrixPacking packing = 4;
+}

apple/swift_homomorphic_encryption/pnns/v1/pnns_client_config.proto

@@ -0,0 +1,39 @@
+// 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.pnns.v1;
+
+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";
+
+// The client configuration.
+message ClientConfig {
+  // Encryption parameters.
+  apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1;
+  // Factor by which to scale floating-point entries before rounding to integers.
+  uint64 scaling_factor = 2;
+  // Packing for the query.
+  MatrixPacking query_packing = 3;
+  // Number of entries in each vector.
+  uint32 vector_dimension = 4;
+  // Galois elements required for nearest neighbors computation.
+  repeated uint32 galois_elements = 5;
+  // Metric for distances between vectors.
+  DistanceMetric distance_metric = 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;
+}

apple/swift_homomorphic_encryption/pnns/v1/pnns_database.proto

@@ -0,0 +1,32 @@
+// 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.pnns.v1;
+
+// Row in a private nearest neighbors search database.
+message DatabaseRow {
+  // Unique identifier for the database entry.
+  uint64 entry_id = 1;
+  // Metadata associated with the entry.
+  bytes entry_metadata = 2;
+  // Vector for use in nearest neighbors computation.
+  repeated float vector = 3;
+}
+
+// A private nearest neighbors search database.
+message Database {
+  // Rows in the database.
+  repeated DatabaseRow rows = 1;
+}

apple/swift_homomorphic_encryption/pnns/v1/pnns_distance_metric.proto

@@ -0,0 +1,22 @@
+// 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.pnns.v1;
+
+// Metric for distances between vectors.
+enum DistanceMetric {
+  // Cosine similarity.
+  DISTANCE_METRIC_COSINE_SIMILARITY = 0;
+}

apple/swift_homomorphic_encryption/pnns/v1/pnns_matrix_packing.proto

@@ -0,0 +1,69 @@
+// 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.pnns.v1;
+
+// Pre-computed values for matrix-vector multiplication using baby-step, giant-step algorithm.
+// See Section 6.3 of <https://eprint.iacr.org/2018/244.pdf>.
+message BabyStepGiantStep {
+  // Dimension of the vector; "D" in the reference.
+  uint32 vector_dimension = 1;
+  // Baby step; "g" in the reference.
+  uint32 baby_step = 2;
+  // Giant step; "h" in the reference.
+  uint32 giant_step = 3;
+}
+
+// Different algorithms for packing a matrix of scalar values into plaintexts / ciphertexts.
+message MatrixPacking {
+  // Different packing formats.
+  oneof plaintext_packing_type {
+    // Dense row packing.
+    MatrixPackingDenseRow dense_row = 1;
+
+    /// Packs the values using a generalized diagonal packing.
+    ///
+    /// Includes modifications for the baby-step, giant-step algorithm from Section 6.3 of
+    /// <https://eprint.iacr.org/2018/244.pdf>.
+    MatrixPackingDiagonal diagonal = 2;
+
+    /// As many rows of data are packed sequentially into each SIMD plaintext
+    /// row as possible, such that no data row is split across multiple SIMD rows, and
+    /// each data row is zero-padded to the next power of two length.
+    /// The rows in the final plaintext are repeated as many times as possible within the plaintext,
+    /// with the constraint that either all or none of the entries stored within the last plaintext
+    /// row are repeated.
+    MatrixPackingDenseColumn dense_column = 3;
+  }
+}
+
+// As many rows of data are packed sequentially into each SIMD row as possible,
+// such that no data row is split across multiple SIMD rows, and
+// each data row is zero-padded to the next power of two length.
+// The rows in the final plaintext/ciphertext are repeated as many times as possible within the plaintext/ciphertext,
+// with the constraint that either all or none of the entries stored within the last plaintext/ciphertext
+// row are repeated.
+message MatrixPackingDenseRow {}
+
+// Packs the values using a generalized diagonal packing.
+message MatrixPackingDiagonal {
+  reserved 1;
+  // Diagonals are rotated according to the baby-step, giant-step algorithm from Section 6.3 of <https://eprint.iacr.org/2018/244.pdf>.
+  BabyStepGiantStep baby_step_giant_step = 2;
+}
+
+// As many columns of data are packed sequentially into each SIMD row as possible, such that no SIMD row
+// contains data from multiple columns.
+message MatrixPackingDenseColumn {}

apple/swift_homomorphic_encryption/pnns/v1/pnns_server_config.proto

@@ -0,0 +1,28 @@
+// 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.pnns.v1;
+
+import "apple/swift_homomorphic_encryption/pnns/v1/pnns_client_config.proto";
+import "apple/swift_homomorphic_encryption/pnns/v1/pnns_matrix_packing.proto";
+
+// The server configuration.
+message ServerConfig {
+  // Configuration shared with the client.
+  ClientConfig client_config = 1;
+  // Packing for the plaintext database.
+  MatrixPacking database_packing = 2;
+  reserved 3, 4;
+}

buf.yaml

@@ -26,4 +26,5 @@ lint:
   ignore_only:
     ENUM_ZERO_VALUE_SUFFIX:
       - apple/swift_homomorphic_encryption/pir/v1/pir_algorithm.proto
+      - apple/swift_homomorphic_encryption/pnns/v1/pnns_distance_metric.proto
       - apple/swift_homomorphic_encryption/v1/error_stddev.proto