Skip to main content

crypto_service_sdk/types/
signing.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//! Server-held keys, Ed25519 signing and batch signing.
3
4use serde::{Deserialize, Serialize};
5
6use crate::{Hex, SecretBytes, SecretString};
7
8/// Key pair algorithms of `POST /v2/keys/generate`.
9#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
10#[serde(rename_all = "kebab-case")]
11#[non_exhaustive]
12pub enum KeyAlgorithm {
13    /// Ed25519 signing.
14    #[default]
15    Ed25519,
16    /// X25519 key agreement.
17    X25519,
18    /// Ed448 signing.
19    Ed448,
20    /// X448 key agreement.
21    X448,
22    /// NIST P-256.
23    P256,
24    /// NIST P-384.
25    P384,
26    /// ML-KEM-512.
27    #[serde(rename = "ml-kem-512")]
28    MlKem512,
29    /// ML-KEM-768.
30    #[serde(rename = "ml-kem-768")]
31    MlKem768,
32    /// ML-KEM-1024.
33    #[serde(rename = "ml-kem-1024")]
34    MlKem1024,
35    /// ML-DSA-44.
36    #[serde(rename = "ml-dsa-44")]
37    MlDsa44,
38    /// ML-DSA-65.
39    #[serde(rename = "ml-dsa-65")]
40    MlDsa65,
41    /// ML-DSA-87.
42    #[serde(rename = "ml-dsa-87")]
43    MlDsa87,
44}
45
46/// What a key is for (JWK `use`).
47#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
48#[serde(rename_all = "lowercase")]
49#[non_exhaustive]
50pub enum KeyUse {
51    /// Signing.
52    Sig,
53    /// Encryption.
54    Enc,
55}
56
57/// Metadata recorded with a generated key.
58#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
59#[serde(deny_unknown_fields)]
60pub struct KeyMetadata {
61    /// A key identifier of the caller's choosing.
62    #[serde(default, skip_serializing_if = "Option::is_none")]
63    pub kid: Option<String>,
64    /// What the key is for.
65    #[serde(rename = "use", default, skip_serializing_if = "Option::is_none")]
66    pub key_use: Option<KeyUse>,
67    /// An expiry, as the caller writes it.
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub exp: Option<String>,
70}
71
72/// `POST /v2/keys/generate`: a key pair whose private key stays on the
73/// server.
74#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
75#[serde(deny_unknown_fields)]
76pub struct GenerateKeyPairRequest {
77    /// The algorithm; Ed25519 when absent.
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub algorithm: Option<KeyAlgorithm>,
80    /// Metadata to record with the key.
81    #[serde(default, skip_serializing_if = "Option::is_none")]
82    pub metadata: Option<KeyMetadata>,
83}
84
85/// The metadata the server recorded with a key; `kid` is always set.
86#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
87#[non_exhaustive]
88pub struct RecordedKeyMetadata {
89    /// The key identifier: the caller's, or one the server chose.
90    pub kid: String,
91    /// What the key is for.
92    #[serde(rename = "use", default, skip_serializing_if = "Option::is_none")]
93    pub key_use: Option<String>,
94    /// The expiry the caller gave.
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub exp: Option<String>,
97}
98
99/// The answer of `POST /v2/keys/generate`.
100#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
101#[serde(rename_all = "camelCase")]
102#[non_exhaustive]
103pub struct GeneratedKeyPair {
104    /// The key's identifier, for the signing and decryption calls.
105    pub key_id: String,
106    /// The algorithm.
107    pub algorithm: String,
108    /// The public key.
109    pub public_key: Hex,
110    /// The key identifier recorded in the metadata.
111    pub kid: String,
112    /// The recorded metadata.
113    pub metadata: RecordedKeyMetadata,
114}
115
116/// The answer of `POST /v2/keys/export`: the key pair's private parts.
117/// Which members are present depends on the algorithm. A member this
118/// version does not name is dropped rather than kept, since it could hold
119/// key material that `Debug` would then print.
120#[derive(Debug, Clone, Serialize, Deserialize)]
121#[serde(rename_all = "camelCase")]
122#[non_exhaustive]
123pub struct ExportedKey {
124    /// The key's identifier.
125    pub key_id: String,
126    /// The algorithm.
127    pub algorithm: String,
128    /// The public key.
129    #[serde(default, skip_serializing_if = "Option::is_none")]
130    pub public_key: Option<Hex>,
131    /// The private key.
132    #[serde(default, skip_serializing_if = "Option::is_none")]
133    pub private_key: Option<SecretBytes>,
134    /// The secret key (ML-KEM, ML-DSA, SLH-DSA).
135    #[serde(default, skip_serializing_if = "Option::is_none")]
136    pub secret_key: Option<SecretBytes>,
137    /// The X25519 public key of a hybrid key.
138    #[serde(default, skip_serializing_if = "Option::is_none")]
139    pub x25519_public_key: Option<Hex>,
140    /// The X25519 private key of a hybrid key.
141    #[serde(default, skip_serializing_if = "Option::is_none")]
142    pub x25519_private_key: Option<SecretBytes>,
143    /// The ML-KEM public key of a hybrid key.
144    #[serde(default, skip_serializing_if = "Option::is_none")]
145    pub ml_kem_public_key: Option<Hex>,
146    /// The ML-KEM secret key of a hybrid key.
147    #[serde(default, skip_serializing_if = "Option::is_none")]
148    pub ml_kem_secret_key: Option<SecretBytes>,
149}
150
151/// The answer of `POST /v2/keys/delete`.
152#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
153#[serde(rename_all = "camelCase")]
154#[non_exhaustive]
155pub struct DeletedKey {
156    /// `true`.
157    pub deleted: bool,
158    /// The deleted key's identifier.
159    pub key_id: String,
160}
161
162/// `POST /v2/sign` (Ed25519) and the ML-DSA and SLH-DSA sign calls: signs
163/// the UTF-8 bytes of `message` with a server-held key.
164#[derive(Debug, Clone, Default, Serialize, Deserialize)]
165#[serde(rename_all = "camelCase", deny_unknown_fields)]
166pub struct SignRequest {
167    /// The key's identifier.
168    pub key_id: String,
169    /// The text to sign.
170    pub message: SecretString,
171}
172
173/// `POST /v2/verify`: an Ed25519 signature against a public key.
174#[derive(Debug, Clone, Default, Serialize, Deserialize)]
175#[serde(rename_all = "camelCase", deny_unknown_fields)]
176pub struct VerifyRequest {
177    /// The signed text.
178    pub message: SecretString,
179    /// The 32-byte public key.
180    pub public_key: Hex,
181    /// The 64-byte signature.
182    pub signature: Hex,
183}
184
185/// One message of a batch sign.
186#[derive(Debug, Clone, Default, Serialize, Deserialize)]
187#[serde(rename_all = "camelCase", deny_unknown_fields)]
188pub struct StreamSignItem {
189    /// The caller's identifier for this item.
190    pub id: String,
191    /// The server-held Ed25519 key.
192    pub key_id: String,
193    /// The text to sign.
194    pub message: SecretString,
195}
196
197/// `POST /v2/stream/sign`: Ed25519 signatures over many messages.
198#[derive(Debug, Clone, Default, Serialize, Deserialize)]
199#[serde(deny_unknown_fields)]
200pub struct StreamSignRequest {
201    /// The messages.
202    pub items: Vec<StreamSignItem>,
203}
204
205/// One signature of a batch.
206#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
207#[non_exhaustive]
208pub struct StreamSignature {
209    /// The item's identifier.
210    pub id: String,
211    /// The signature.
212    pub signature: Hex,
213    /// `ed25519`.
214    pub algorithm: String,
215}
216
217/// The answer of `POST /v2/stream/sign`.
218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
219#[non_exhaustive]
220pub struct StreamSignResult {
221    /// One signature per item, in order.
222    pub signatures: Vec<StreamSignature>,
223    /// The number of signatures.
224    pub count: u64,
225}
226
227/// One signature to check in a batch.
228#[derive(Debug, Clone, Default, Serialize, Deserialize)]
229#[serde(rename_all = "camelCase", deny_unknown_fields)]
230pub struct StreamVerifyItem {
231    /// The caller's identifier for this item.
232    pub id: String,
233    /// The signed text.
234    pub message: SecretString,
235    /// The 64-byte signature.
236    pub signature: Hex,
237    /// The 32-byte Ed25519 public key.
238    pub public_key: Hex,
239}
240
241/// `POST /v2/stream/verify`: checks many Ed25519 signatures.
242#[derive(Debug, Clone, Default, Serialize, Deserialize)]
243#[serde(deny_unknown_fields)]
244pub struct StreamVerifyRequest {
245    /// The signatures.
246    pub items: Vec<StreamVerifyItem>,
247}
248
249/// One outcome of a batch verification.
250#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
251#[non_exhaustive]
252pub struct StreamVerification {
253    /// The item's identifier.
254    pub id: String,
255    /// Whether it verified.
256    pub valid: bool,
257}
258
259/// The answer of `POST /v2/stream/verify`.
260#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
261#[serde(rename_all = "camelCase")]
262#[non_exhaustive]
263pub struct StreamVerifyResult {
264    /// One outcome per item, in order.
265    pub results: Vec<StreamVerification>,
266    /// The number of items.
267    pub count: u64,
268    /// The number that verified.
269    pub valid_count: u64,
270    /// Whether every item verified.
271    pub all_valid: bool,
272}