Skip to content

Commit 99f5353

Browse files
fboemerfboemer
authored
Add PNNS API protos (#10)
1 parent 9961dae commit 99f5353

File tree

4 files changed

+198
-89
lines changed

4 files changed

+198
-89
lines changed

‎apple/swift_homomorphic_encryption/api/v1/api.proto

+2-89
Original file line numberDiff line numberDiff line change
@@ -15,40 +15,8 @@
1515
syntax = "proto3";
1616
package apple.swift_homomorphic_encryption.api.v1;
1717

18-
import "apple/swift_homomorphic_encryption/pir/v1/pir.proto";
19-
import "apple/swift_homomorphic_encryption/pir/v1/pir_algorithm.proto";
20-
import "apple/swift_homomorphic_encryption/v1/he.proto";
21-
22-
// Evaluation key metadata.
23-
message EvaluationKeyMetadata {
24-
// Timestamp of the (secret) key generation, seconds from Unix epoch.
25-
uint64 timestamp = 1;
26-
// Key identifier (SHA256 of `EvaluationKeyConfig`).
27-
bytes identifier = 2;
28-
}
29-
30-
// Status of the evaluation key.
31-
message KeyStatus {
32-
// When was this key last updated (seconds from Unix epoch), 0 when key is missing.
33-
uint64 timestamp = 1;
34-
// Configuration for the key.
35-
apple.swift_homomorphic_encryption.v1.EvaluationKeyConfig key_config = 2;
36-
reserved 3;
37-
}
38-
39-
// Container for multiple evaluation keys.
40-
message EvaluationKeys {
41-
// Evaluation keys.
42-
repeated EvaluationKey keys = 1;
43-
}
44-
45-
// Evaluation key upload.
46-
message EvaluationKey {
47-
// Metadata for the key.
48-
EvaluationKeyMetadata metadata = 1;
49-
// Evaluation key.
50-
apple.swift_homomorphic_encryption.v1.SerializedEvaluationKey evaluation_key = 2;
51-
}
18+
import "apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto";
19+
import "apple/swift_homomorphic_encryption/api/v1/api_pir.proto";
5220

5321
// Request for server side configurations.
5422
message ConfigRequest {
@@ -110,58 +78,3 @@ message Response {
11078
}
11179
reserved 2;
11280
}
113-
114-
// Configuration for one shard of the PIR database.
115-
message PIRShardConfig {
116-
// Number of entries in the shard.
117-
uint64 num_entries = 1;
118-
// Size in bytes of entries in the shard.
119-
uint64 entry_size = 2;
120-
// Dimensions that make up the hypercube.
121-
repeated uint64 dimensions = 3;
122-
// Unique identifier for the shard.
123-
optional string shard_id = 4;
124-
// Whether to compress vectorized PIR response.
125-
optional bool compress_vectorized_pir_response = 5;
126-
// The additional "batching" introduced in vectorized pir to accommodate large entry size.
127-
optional uint64 vectorized_pir_internal_batching_size = 6;
128-
}
129-
130-
// Configuration for one PIR usecase.
131-
message PIRConfig {
132-
// Encryption parameters.
133-
apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1;
134-
// Configuration for each shard.
135-
repeated PIRShardConfig shard_configs = 2;
136-
// Parameters specific to KeywordPIR.
137-
apple.swift_homomorphic_encryption.pir.v1.KeywordPirParameters keyword_pir_params = 3;
138-
// Server-side PIR algorithm.
139-
apple.swift_homomorphic_encryption.pir.v1.PirAlgorithm algorithm = 4;
140-
// Maximum number of queries allowed in a single request.
141-
uint64 batch_size = 5;
142-
// Hash of EvaluationKeyConfig.
143-
bytes evaluation_key_config_hash = 6;
144-
reserved 7, 8;
145-
}
146-
147-
// PIR Request.
148-
message PIRRequest {
149-
// Shard index where this request should be routed. Can be overridden by shard_id.
150-
uint32 shard_index = 1;
151-
// Encrypted query.
152-
apple.swift_homomorphic_encryption.pir.v1.EncryptedIndices query = 2;
153-
// Evaluation key metadata.
154-
EvaluationKeyMetadata evaluation_key_metadata = 3;
155-
// Hash of the `PIRConfig` used to construct the query.
156-
bytes configuration_hash = 4;
157-
// If set, route request to a shard with this `shard_id` instead of `shard_index`.
158-
optional string shard_id = 5;
159-
// If set, evaluation key to query with. Will override evaluation key stored server-side.
160-
optional EvaluationKey evaluation_key = 6;
161-
}
162-
163-
// PIR Response.
164-
message PIRResponse {
165-
// Encrypted replies, each of which is a ciphertext vector.
166-
repeated apple.swift_homomorphic_encryption.v1.SerializedCiphertextVec replies = 1;
167-
}

‎apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
package apple.swift_homomorphic_encryption.api.v1;
17+
18+
import "apple/swift_homomorphic_encryption/v1/he.proto";
19+
20+
// Evaluation key metadata.
21+
message EvaluationKeyMetadata {
22+
// Timestamp of the (secret) key generation, seconds from Unix epoch.
23+
uint64 timestamp = 1;
24+
// Key identifier (SHA256 of `EvaluationKeyConfig`).
25+
bytes identifier = 2;
26+
}
27+
28+
// Status of the evaluation key.
29+
message KeyStatus {
30+
// When was this key last updated (seconds from Unix epoch), 0 when key is missing.
31+
uint64 timestamp = 1;
32+
// Configuration for the key.
33+
apple.swift_homomorphic_encryption.v1.EvaluationKeyConfig key_config = 2;
34+
reserved 3;
35+
}
36+
37+
// Container for multiple evaluation keys.
38+
message EvaluationKeys {
39+
// Evaluation keys.
40+
repeated EvaluationKey keys = 1;
41+
}
42+
43+
// Evaluation key upload.
44+
message EvaluationKey {
45+
// Metadata for the key.
46+
EvaluationKeyMetadata metadata = 1;
47+
// Evaluation key.
48+
apple.swift_homomorphic_encryption.v1.SerializedEvaluationKey evaluation_key = 2;
49+
}

‎apple/swift_homomorphic_encryption/api/v1/api_pir.proto

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
package apple.swift_homomorphic_encryption.api.v1;
17+
18+
import "apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto";
19+
import "apple/swift_homomorphic_encryption/pir/v1/pir.proto";
20+
import "apple/swift_homomorphic_encryption/pir/v1/pir_algorithm.proto";
21+
import "apple/swift_homomorphic_encryption/v1/he.proto";
22+
23+
// Configuration for one shard of the PIR database.
24+
message PIRShardConfig {
25+
// Number of entries in the shard.
26+
uint64 num_entries = 1;
27+
// Size in bytes of entries in the shard.
28+
uint64 entry_size = 2;
29+
// Dimensions that make up the hypercube.
30+
repeated uint64 dimensions = 3;
31+
// Unique identifier for the shard.
32+
optional string shard_id = 4;
33+
// Whether to compress vectorized PIR response.
34+
optional bool compress_vectorized_pir_response = 5;
35+
// The additional "batching" introduced in vectorized pir to accommodate large entry size.
36+
optional uint64 vectorized_pir_internal_batching_size = 6;
37+
}
38+
39+
// Configuration for one PIR usecase.
40+
message PIRConfig {
41+
// Encryption parameters.
42+
apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1;
43+
// Configuration for each shard.
44+
repeated PIRShardConfig shard_configs = 2;
45+
// Parameters specific to KeywordPIR.
46+
apple.swift_homomorphic_encryption.pir.v1.KeywordPirParameters keyword_pir_params = 3;
47+
// Server-side PIR algorithm.
48+
apple.swift_homomorphic_encryption.pir.v1.PirAlgorithm algorithm = 4;
49+
// Maximum number of queries allowed in a single request.
50+
uint64 batch_size = 5;
51+
// Hash of EvaluationKeyConfig.
52+
bytes evaluation_key_config_hash = 6;
53+
reserved 7, 8;
54+
}
55+
56+
// PIR Request.
57+
message PIRRequest {
58+
// Shard index where this request should be routed. Can be overridden by shard_id.
59+
uint32 shard_index = 1;
60+
// Encrypted query.
61+
apple.swift_homomorphic_encryption.pir.v1.EncryptedIndices query = 2;
62+
// Evaluation key metadata.
63+
EvaluationKeyMetadata evaluation_key_metadata = 3;
64+
// Hash of the `PIRConfig` used to construct the query.
65+
bytes configuration_hash = 4;
66+
// If set, route request to a shard with this `shard_id` instead of `shard_index`.
67+
optional string shard_id = 5;
68+
// If set, evaluation key to query with. Will override evaluation key stored server-side.
69+
optional EvaluationKey evaluation_key = 6;
70+
}
71+
72+
// PIR Response.
73+
message PIRResponse {
74+
// Encrypted replies, each of which is a ciphertext vector.
75+
repeated apple.swift_homomorphic_encryption.v1.SerializedCiphertextVec replies = 1;
76+
}

‎apple/swift_homomorphic_encryption/api/v1/api_pnns.proto

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project authors
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
package apple.swift_homomorphic_encryption.api.v1;
17+
18+
import "apple/swift_homomorphic_encryption/api/v1/api_evaluation_key.proto";
19+
import "apple/swift_homomorphic_encryption/pnns/v1/pnns.proto";
20+
import "apple/swift_homomorphic_encryption/pnns/v1/pnns_distance_metric.proto";
21+
import "apple/swift_homomorphic_encryption/pnns/v1/pnns_matrix_packing.proto";
22+
import "apple/swift_homomorphic_encryption/v1/he.proto";
23+
24+
// Configuration for one PNNS usecase.
25+
message PNNSConfig {
26+
// Encryption parameters.
27+
apple.swift_homomorphic_encryption.v1.EncryptionParameters encryption_parameters = 1;
28+
// Factor by which to scale floating-point entries to integers.
29+
uint64 scaling_factor = 2;
30+
// Plaintext packing for the query.
31+
apple.swift_homomorphic_encryption.pnns.v1.MatrixPacking plaintext_packing = 3;
32+
// Number of entries in each vector.
33+
uint32 vector_dimension = 4;
34+
// Metric for similarity computation.
35+
apple.swift_homomorphic_encryption.pnns.v1.DistanceMetric distance_metric = 5;
36+
// hash of EvaluationKeyConfig.
37+
bytes evaluation_key_config_hash = 6;
38+
// For plaintext CRT, the list of extra plaintext moduli.
39+
// The first plaintext modulus will be the one in `encryption_parameters`.
40+
repeated uint64 extra_plaintext_moduli = 7;
41+
}
42+
43+
// PNNS Request
44+
message PNNSRequest {
45+
// optionally, the shard indices where this request should be routed
46+
repeated uint32 shard_indices = 1;
47+
// Encrypted query, one per plaintext CRT component
48+
repeated apple.swift_homomorphic_encryption.pnns.v1.SerializedCiphertextMatrix query = 2;
49+
// Key metadata
50+
EvaluationKeyMetadata evaluation_key_metadata = 3;
51+
// Identifier for the PNNSConfig used to construct the query
52+
bytes config_id = 4;
53+
// If set, evaluation key to query with. Will override evaluation key stored server-side
54+
optional EvaluationKey evaluation_key = 5;
55+
}
56+
57+
// PNNS Shard Response
58+
message PNNSShardResponse {
59+
// Encrypted reply, one per plaintext CRT component
60+
repeated apple.swift_homomorphic_encryption.pnns.v1.SerializedCiphertextMatrix reply = 1;
61+
// A list of entry identifiers the server computed similarities for
62+
repeated uint64 entry_ids = 2;
63+
// Metadata for each entry in the database
64+
repeated bytes entry_metadatas = 3;
65+
}
66+
67+
// PNNS Response
68+
message PNNSResponse {
69+
// PNNS responses from shards
70+
repeated PNNSShardResponse shard_responses = 1;
71+
}

0 commit comments

Comments
 (0)