Skip to main content

crypto_service_sdk/types/
asymmetric.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//! Sealed boxes, multi-recipient encryption and post-quantum streams.
3
4use serde::{Deserialize, Serialize};
5
6use crate::{Base64, Hex, SecretString};
7
8/// `POST /v2/sealedbox/seal`: an anonymous X25519 sealed box.
9#[derive(Debug, Clone, Default, Serialize, Deserialize)]
10#[serde(rename_all = "camelCase", deny_unknown_fields)]
11pub struct SealedboxSealRequest {
12    /// The recipient's 32-byte X25519 public key.
13    pub recipient_public_key: Hex,
14    /// The text to seal.
15    pub plaintext: SecretString,
16}
17
18/// `POST /v2/sealedbox/seal-pq`: a hybrid X25519 and ML-KEM-768 sealed
19/// box.
20#[derive(Debug, Clone, Default, Serialize, Deserialize)]
21#[serde(rename_all = "camelCase", deny_unknown_fields)]
22pub struct SealedboxSealPqRequest {
23    /// The recipient's X25519 public key.
24    pub x25519_public_key: Hex,
25    /// The recipient's ML-KEM-768 public key.
26    pub ml_kem_public_key: Hex,
27    /// The text to seal.
28    pub plaintext: SecretString,
29}
30
31/// `POST /v2/sealedbox/open` and `open-pq`: opens a sealed box with a
32/// server-held key. The answer is the plaintext itself.
33#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(rename_all = "camelCase", deny_unknown_fields)]
35pub struct SealedboxOpenRequest {
36    /// The server-held key.
37    pub key_id: String,
38    /// The sealed box.
39    pub sealed: Base64,
40}
41
42/// What kind of key a multi-recipient recipient has.
43#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
44#[serde(rename_all = "lowercase")]
45#[non_exhaustive]
46pub enum RecipientType {
47    /// An X25519 key.
48    #[default]
49    Classical,
50    /// An X25519 and ML-KEM-768 hybrid key.
51    Pq,
52}
53
54/// One recipient of `POST /v2/multi-recipient/encrypt`.
55#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "camelCase", deny_unknown_fields)]
57pub struct Recipient {
58    /// The kind of key.
59    #[serde(rename = "type")]
60    pub kind: RecipientType,
61    /// The X25519 public key.
62    pub public_key: Hex,
63    /// The ML-KEM-768 public key, for a `Pq` recipient.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub ml_kem_public_key: Option<Hex>,
66}
67
68/// `POST /v2/multi-recipient/encrypt`: one ciphertext, a wrapped key per
69/// recipient.
70#[derive(Debug, Clone, Default, Serialize, Deserialize)]
71#[serde(rename_all = "camelCase", deny_unknown_fields)]
72pub struct MultiRecipientEncryptRequest {
73    /// The text to encrypt.
74    pub plaintext: SecretString,
75    /// The recipients.
76    pub recipients: Vec<Recipient>,
77}
78
79/// One recipient's share of a multi-recipient ciphertext.
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(rename_all = "camelCase")]
82#[non_exhaustive]
83pub struct RecipientShare {
84    /// `x25519` or `x25519-ml-kem-768`.
85    #[serde(rename = "type")]
86    pub kind: String,
87    /// The sender's ephemeral X25519 public key.
88    pub ephemeral_public_key: Hex,
89    /// The content key, wrapped for this recipient.
90    pub wrapped_key: Base64,
91    /// The ML-KEM-768 ciphertext (hybrid recipients only).
92    #[serde(default, skip_serializing_if = "Option::is_none")]
93    pub ml_kem_ciphertext: Option<Hex>,
94}
95
96/// The answer of `POST /v2/multi-recipient/encrypt`.
97#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
98#[non_exhaustive]
99pub struct MultiRecipientCiphertext {
100    /// The ciphertext.
101    pub ciphertext: Base64,
102    /// One share per recipient, in order.
103    pub recipients: Vec<RecipientShare>,
104    /// `multi-recipient-secretbox`.
105    pub algorithm: String,
106}
107
108/// `POST /v2/stream/pq-encrypt`: chunked hybrid post-quantum encryption.
109#[derive(Debug, Clone, Default, Serialize, Deserialize)]
110#[serde(rename_all = "camelCase", deny_unknown_fields)]
111pub struct StreamPqEncryptRequest {
112    /// The recipient's 32-byte X25519 public key.
113    pub x25519_public_key: Hex,
114    /// The recipient's ML-KEM-768 public key.
115    pub ml_kem_public_key: Hex,
116    /// The text to encrypt.
117    pub plaintext: SecretString,
118    /// Chunk size in bytes, 64 to 1,048,576.
119    #[serde(default, skip_serializing_if = "Option::is_none")]
120    pub chunk_size: Option<u32>,
121}
122
123/// `POST /v2/stream/pq-decrypt`: opens a stream with a server-held hybrid
124/// key.
125#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
126#[serde(rename_all = "camelCase", deny_unknown_fields)]
127pub struct StreamPqDecryptRequest {
128    /// The server-held key.
129    pub key_id: String,
130    /// The stream.
131    pub ciphertext: Base64,
132    /// The chunk size it was written with.
133    #[serde(default, skip_serializing_if = "Option::is_none")]
134    pub chunk_size: Option<u32>,
135}
136
137/// One recipient of a multi-recipient stream.
138#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "camelCase", deny_unknown_fields)]
140pub struct StreamRecipient {
141    /// The caller's identifier, 1 to 255 characters.
142    pub recipient_id: String,
143    /// The 32-byte X25519 public key.
144    pub x25519_public_key: Hex,
145    /// The ML-KEM-768 public key.
146    pub ml_kem_public_key: Hex,
147}
148
149/// `POST /v2/stream/multi-pq-encrypt`: a hybrid post-quantum stream for
150/// several recipients.
151#[derive(Debug, Clone, Default, Serialize, Deserialize)]
152#[serde(rename_all = "camelCase", deny_unknown_fields)]
153pub struct StreamMultiPqEncryptRequest {
154    /// The recipients.
155    pub recipients: Vec<StreamRecipient>,
156    /// The text to encrypt.
157    pub plaintext: SecretString,
158    /// Chunk size in bytes, 1024 to 16,777,216.
159    #[serde(default, skip_serializing_if = "Option::is_none")]
160    pub chunk_size: Option<u32>,
161}
162
163/// The answer of `POST /v2/stream/multi-pq-encrypt`.
164#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
165#[serde(rename_all = "camelCase")]
166#[non_exhaustive]
167pub struct MultiPqCiphertext {
168    /// The stream with its header.
169    pub ciphertext: Base64,
170    /// The number of recipients.
171    pub recipient_count: u64,
172    /// The algorithm.
173    pub algorithm: String,
174}
175
176/// `POST /v2/stream/multi-pq-decrypt`: opens a multi-recipient stream with
177/// a server-held hybrid key.
178#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
179#[serde(rename_all = "camelCase", deny_unknown_fields)]
180pub struct StreamMultiPqDecryptRequest {
181    /// The server-held key.
182    pub key_id: String,
183    /// The stream.
184    pub ciphertext: Base64,
185    /// Which recipient the key belongs to; found by trial when absent.
186    #[serde(default, skip_serializing_if = "Option::is_none")]
187    pub recipient_id: Option<String>,
188    /// The chunk size it was written with.
189    #[serde(default, skip_serializing_if = "Option::is_none")]
190    pub chunk_size: Option<u32>,
191}
192
193/// The answer of `POST /v2/stream/multi-pq-decrypt`.
194#[derive(Debug, Clone, Serialize, Deserialize)]
195#[serde(rename_all = "camelCase")]
196#[non_exhaustive]
197pub struct MultiPqPlaintext {
198    /// The plaintext, as UTF-8 text.
199    pub plaintext: SecretString,
200    /// The recipient the key matched.
201    pub recipient_id: String,
202}