Skip to main content

crypto_service_sdk/types/
kms.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//! KMS routes: keys held by a provider (`local`, AWS, GCP, Vault).
3//!
4//! KMS ciphertexts and wrapped keys are opaque provider strings, kept as
5//! `String` and passed back unchanged.
6
7use serde::{Deserialize, Serialize};
8use serde_json::{Map, Value};
9
10use crate::encoding::encode_hex;
11use crate::{SecretBytes, SecretString};
12
13/// What a KMS key is for.
14#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
15#[serde(rename_all = "lowercase")]
16#[non_exhaustive]
17pub enum KmsKeyUsage {
18    /// Encryption.
19    Encrypt,
20    /// Signing.
21    Sign,
22    /// Key wrapping.
23    Wrap,
24}
25
26/// `POST /v2/kms/create-key`.
27#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
28#[serde(rename_all = "camelCase", deny_unknown_fields)]
29pub struct KmsCreateKeyRequest {
30    /// The provider; the server's default when absent.
31    #[serde(default, skip_serializing_if = "Option::is_none")]
32    pub provider: Option<String>,
33    /// The provider's algorithm name.
34    #[serde(default, skip_serializing_if = "Option::is_none")]
35    pub algorithm: Option<String>,
36    /// What the key is for.
37    #[serde(default, skip_serializing_if = "Option::is_none")]
38    pub usage: Option<KmsKeyUsage>,
39    /// Provider metadata.
40    #[serde(default, skip_serializing_if = "Option::is_none")]
41    pub metadata: Option<Map<String, Value>>,
42}
43
44/// The answer of `POST /v2/kms/create-key`.
45#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
46#[serde(rename_all = "camelCase")]
47#[non_exhaustive]
48pub struct KmsKey {
49    /// The provider's key identifier.
50    pub key_id: String,
51    /// The provider.
52    pub provider: String,
53    /// The algorithm.
54    pub algorithm: String,
55    /// What the key is for.
56    pub usage: String,
57    /// When it was created (RFC 3339).
58    pub created_at: String,
59    /// Whether it is enabled.
60    pub enabled: bool,
61    /// The current key version, for providers that version keys.
62    #[serde(default, skip_serializing_if = "Option::is_none")]
63    pub current_version: Option<u64>,
64}
65
66/// How `POST /v2/kms/encrypt` reads `plaintext`. Never guessed.
67#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
68#[serde(rename_all = "lowercase")]
69#[non_exhaustive]
70pub enum KmsEncoding {
71    /// UTF-8 text (the server's default).
72    Utf8,
73    /// Hex.
74    Hex,
75}
76
77/// `POST /v2/kms/encrypt`. Build it with [`KmsEncryptRequest::text`] or
78/// [`KmsEncryptRequest::bytes`], which set `encoding` to match.
79#[derive(Debug, Clone, Default, Serialize, Deserialize)]
80#[serde(rename_all = "camelCase", deny_unknown_fields)]
81pub struct KmsEncryptRequest {
82    /// The provider's key identifier.
83    pub key_id: String,
84    /// The plaintext, encoded as `encoding` says.
85    pub plaintext: SecretString,
86    /// How `plaintext` is encoded; UTF-8 when absent.
87    #[serde(default, skip_serializing_if = "Option::is_none")]
88    pub encoding: Option<KmsEncoding>,
89    /// The provider.
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub provider: Option<String>,
92    /// Encryption context, bound to the ciphertext.
93    #[serde(default, skip_serializing_if = "Option::is_none")]
94    pub context: Option<Map<String, Value>>,
95}
96
97impl KmsEncryptRequest {
98    /// Encrypts the UTF-8 bytes of `text` under `key_id`.
99    pub fn text(key_id: impl Into<String>, text: impl Into<SecretString>) -> Self {
100        KmsEncryptRequest {
101            key_id: key_id.into(),
102            plaintext: text.into(),
103            ..Self::default()
104        }
105    }
106
107    /// Encrypts `bytes` under `key_id`, sent as hex with `encoding: hex`.
108    pub fn bytes(key_id: impl Into<String>, bytes: &[u8]) -> Self {
109        KmsEncryptRequest {
110            key_id: key_id.into(),
111            plaintext: SecretString::new(encode_hex(bytes)),
112            encoding: Some(KmsEncoding::Hex),
113            ..Self::default()
114        }
115    }
116}
117
118/// The answer of `POST /v2/kms/encrypt`.
119#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
120#[serde(rename_all = "camelCase")]
121#[non_exhaustive]
122pub struct KmsCiphertext {
123    /// The provider's ciphertext, opaque.
124    pub ciphertext: String,
125    /// The key used.
126    pub key_id: String,
127    /// The provider.
128    pub provider: String,
129    /// The key version used, for providers that version keys.
130    #[serde(default, skip_serializing_if = "Option::is_none")]
131    pub key_version: Option<u64>,
132    /// The encryption context.
133    #[serde(default, skip_serializing_if = "Option::is_none")]
134    pub context: Option<Map<String, Value>>,
135}
136
137/// `POST /v2/kms/decrypt`.
138#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
139#[serde(rename_all = "camelCase", deny_unknown_fields)]
140pub struct KmsDecryptRequest {
141    /// The provider's key identifier.
142    pub key_id: String,
143    /// The ciphertext, as the encrypt call returned it.
144    pub ciphertext: String,
145    /// The provider.
146    #[serde(default, skip_serializing_if = "Option::is_none")]
147    pub provider: Option<String>,
148    /// The encryption context it was encrypted with.
149    #[serde(default, skip_serializing_if = "Option::is_none")]
150    pub context: Option<Map<String, Value>>,
151}
152
153/// The answer of `POST /v2/kms/decrypt`: the plaintext as UTF-8 text and
154/// as bytes.
155#[derive(Debug, Clone, Serialize, Deserialize)]
156#[serde(rename_all = "camelCase")]
157#[non_exhaustive]
158pub struct KmsPlaintext {
159    /// The plaintext as UTF-8 text (invalid sequences become U+FFFD).
160    pub plaintext: SecretString,
161    /// The plaintext bytes.
162    pub hex: SecretBytes,
163    /// The key used.
164    pub key_id: String,
165    /// The provider.
166    pub provider: String,
167}
168
169/// `POST /v2/kms/generate-data-key`.
170#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
171#[serde(rename_all = "camelCase", deny_unknown_fields)]
172pub struct KmsGenerateDataKeyRequest {
173    /// The provider's key identifier.
174    pub key_id: String,
175    /// The data key's specification, as the provider names it.
176    #[serde(default, skip_serializing_if = "Option::is_none")]
177    pub key_spec: Option<String>,
178    /// The provider.
179    #[serde(default, skip_serializing_if = "Option::is_none")]
180    pub provider: Option<String>,
181}
182
183/// The answer of `POST /v2/kms/generate-data-key`.
184#[derive(Debug, Clone, Serialize, Deserialize)]
185#[serde(rename_all = "camelCase")]
186#[non_exhaustive]
187pub struct KmsDataKey {
188    /// The data key bytes; use, then drop.
189    pub plaintext: SecretBytes,
190    /// The data key, encrypted under the KMS key: keep this one.
191    pub ciphertext: String,
192    /// The key used.
193    pub key_id: String,
194    /// The provider.
195    pub provider: String,
196}
197
198/// `POST /v2/kms/wrap`.
199#[derive(Debug, Clone, Default, Serialize, Deserialize)]
200#[serde(rename_all = "camelCase", deny_unknown_fields)]
201pub struct KmsWrapRequest {
202    /// The provider's key identifier.
203    pub key_id: String,
204    /// The key bytes to wrap.
205    pub unwrapped_key: SecretBytes,
206    /// The provider.
207    #[serde(default, skip_serializing_if = "Option::is_none")]
208    pub provider: Option<String>,
209    /// The encryption context.
210    #[serde(default, skip_serializing_if = "Option::is_none")]
211    pub context: Option<Map<String, Value>>,
212}
213
214/// The answer of `POST /v2/kms/wrap`.
215#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
216#[serde(rename_all = "camelCase")]
217#[non_exhaustive]
218pub struct KmsWrapped {
219    /// The wrapped key, opaque.
220    pub wrapped_key: String,
221    /// The key used.
222    pub key_id: String,
223    /// The provider.
224    pub provider: String,
225}
226
227/// `POST /v2/kms/unwrap`.
228#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
229#[serde(rename_all = "camelCase", deny_unknown_fields)]
230pub struct KmsUnwrapRequest {
231    /// The provider's key identifier.
232    pub key_id: String,
233    /// The wrapped key, as the wrap call returned it.
234    pub wrapped_key: String,
235    /// The provider.
236    #[serde(default, skip_serializing_if = "Option::is_none")]
237    pub provider: Option<String>,
238    /// The encryption context it was wrapped with.
239    #[serde(default, skip_serializing_if = "Option::is_none")]
240    pub context: Option<Map<String, Value>>,
241}
242
243/// The answer of `POST /v2/kms/unwrap`.
244#[derive(Debug, Clone, Serialize, Deserialize)]
245#[serde(rename_all = "camelCase")]
246#[non_exhaustive]
247pub struct KmsUnwrapped {
248    /// The key bytes.
249    pub unwrapped_key: SecretBytes,
250    /// The key used.
251    pub key_id: String,
252    /// The provider.
253    pub provider: String,
254}