Skip to main content

crypto_service_sdk/types/
symmetric.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//! AEAD, secretbox, password encryption and AES key wrap.
3
4use serde::{Deserialize, Serialize};
5
6use crate::{Base64, SecretBytes, SecretString};
7
8/// `POST /v2/encrypt`: XChaCha20-Poly1305 under a caller-held key.
9#[derive(Debug, Clone, Default, Serialize, Deserialize)]
10#[serde(rename_all = "camelCase", deny_unknown_fields)]
11pub struct EncryptRequest {
12    /// The 32-byte key.
13    pub key: SecretBytes,
14    /// The text to encrypt (1 byte to 10 MiB).
15    pub plaintext: SecretString,
16}
17
18/// `POST /v2/decrypt`: opens what [`EncryptRequest`] produced.
19#[derive(Debug, Clone, Default, Serialize, Deserialize)]
20#[serde(rename_all = "camelCase", deny_unknown_fields)]
21pub struct DecryptRequest {
22    /// The 32-byte key.
23    pub key: SecretBytes,
24    /// `nonce || ciphertext || tag`, as the encrypt call returned it.
25    pub ciphertext: Base64,
26}
27
28/// `POST /v2/secretbox/seal`: XChaCha20-Poly1305 with optional associated
29/// data.
30#[derive(Debug, Clone, Default, Serialize, Deserialize)]
31#[serde(rename_all = "camelCase", deny_unknown_fields)]
32pub struct SecretboxSealRequest {
33    /// The 32-byte key.
34    pub key: SecretBytes,
35    /// The text to seal.
36    pub plaintext: SecretString,
37    /// Associated data, as UTF-8 text.
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub aad: Option<String>,
40}
41
42/// `POST /v2/secretbox/open`: opens a secretbox. The answer is the
43/// plaintext itself.
44#[derive(Debug, Clone, Default, Serialize, Deserialize)]
45#[serde(rename_all = "camelCase", deny_unknown_fields)]
46pub struct SecretboxOpenRequest {
47    /// The 32-byte key.
48    pub key: SecretBytes,
49    /// The sealed box.
50    pub ciphertext: Base64,
51    /// The associated data it was sealed with.
52    #[serde(default, skip_serializing_if = "Option::is_none")]
53    pub aad: Option<String>,
54}
55
56/// `POST /v2/password/encrypt`: Argon2id key derivation and
57/// XChaCha20-Poly1305.
58#[derive(Debug, Clone, Default, Serialize, Deserialize)]
59#[serde(rename_all = "camelCase", deny_unknown_fields)]
60pub struct PasswordEncryptRequest {
61    /// The password.
62    pub password: SecretString,
63    /// The text to encrypt.
64    pub plaintext: SecretString,
65}
66
67/// The answer of `POST /v2/password/encrypt`.
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69#[serde(rename_all = "camelCase")]
70#[non_exhaustive]
71pub struct PasswordEncryptResult {
72    /// The envelope: version, Argon2id parameters, salt, nonce and
73    /// ciphertext.
74    pub encrypted: Base64,
75    /// `argon2id-xchacha20-poly1305`.
76    pub algorithm: String,
77}
78
79/// `POST /v2/password/decrypt`: opens a password envelope. The answer is
80/// the plaintext itself.
81#[derive(Debug, Clone, Default, Serialize, Deserialize)]
82#[serde(rename_all = "camelCase", deny_unknown_fields)]
83pub struct PasswordDecryptRequest {
84    /// The password.
85    pub password: SecretString,
86    /// The envelope.
87    pub ciphertext: Base64,
88}
89
90/// AES key wrap modes.
91#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
92#[serde(rename_all = "kebab-case")]
93#[non_exhaustive]
94pub enum KeyWrapAlgorithm {
95    /// AES-KW, RFC 3394 (keys of a multiple of 8 bytes).
96    #[default]
97    AesKw,
98    /// AES-KWP, RFC 5649 (keys of any length).
99    AesKwp,
100}
101
102/// `POST /v2/keys/wrap`: wraps a key under a key-encryption key.
103#[derive(Debug, Clone, Default, Serialize, Deserialize)]
104#[serde(rename_all = "camelCase", deny_unknown_fields)]
105pub struct KeyWrapRequest {
106    /// The key-encryption key (16, 24 or 32 bytes).
107    pub kek: SecretBytes,
108    /// The key to wrap.
109    pub key_to_wrap: SecretBytes,
110    /// The mode; AES-KW when absent.
111    #[serde(default, skip_serializing_if = "Option::is_none")]
112    pub algorithm: Option<KeyWrapAlgorithm>,
113}
114
115/// The answer of `POST /v2/keys/wrap`.
116#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
117#[serde(rename_all = "camelCase")]
118#[non_exhaustive]
119pub struct KeyWrapResult {
120    /// The wrapped key.
121    pub wrapped: Base64,
122    /// The mode used.
123    pub algorithm: String,
124}
125
126/// `POST /v2/keys/unwrap`: unwraps a key. The answer is the key itself.
127#[derive(Debug, Clone, Default, Serialize, Deserialize)]
128#[serde(rename_all = "camelCase", deny_unknown_fields)]
129pub struct KeyUnwrapRequest {
130    /// The key-encryption key.
131    pub kek: SecretBytes,
132    /// The wrapped key.
133    pub wrapped_key: Base64,
134    /// The mode it was wrapped with; AES-KW when absent.
135    #[serde(default, skip_serializing_if = "Option::is_none")]
136    pub algorithm: Option<KeyWrapAlgorithm>,
137}