Skip to main content

crypto_service_sdk/types/
hashing.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//! Hashing, MACs, key derivation and password hashing.
3
4use serde::{Deserialize, Serialize};
5
6use crate::{Hex, SecretBytes, SecretString};
7
8/// Hash algorithms of `POST /v2/hash`.
9#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
10#[non_exhaustive]
11pub enum HashAlgorithm {
12    /// SHA-256.
13    #[default]
14    #[serde(rename = "sha256")]
15    Sha256,
16    /// SHA-384.
17    #[serde(rename = "sha384")]
18    Sha384,
19    /// SHA-512.
20    #[serde(rename = "sha512")]
21    Sha512,
22    /// SHA3-256.
23    #[serde(rename = "sha3-256")]
24    Sha3_256,
25    /// SHA3-512.
26    #[serde(rename = "sha3-512")]
27    Sha3_512,
28    /// BLAKE2b-512.
29    #[serde(rename = "blake2b")]
30    Blake2b,
31    /// BLAKE3.
32    #[serde(rename = "blake3")]
33    Blake3,
34}
35
36/// HMAC hash functions of `POST /v2/hmac` and `POST /v2/hmac/verify`.
37#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
38#[non_exhaustive]
39pub enum MacAlgorithm {
40    /// HMAC-SHA-256.
41    #[default]
42    #[serde(rename = "sha256")]
43    Sha256,
44    /// HMAC-SHA-384.
45    #[serde(rename = "sha384")]
46    Sha384,
47    /// HMAC-SHA-512.
48    #[serde(rename = "sha512")]
49    Sha512,
50    /// HMAC-SHA3-256.
51    #[serde(rename = "sha3-256")]
52    Sha3_256,
53    /// HMAC-SHA3-512.
54    #[serde(rename = "sha3-512")]
55    Sha3_512,
56}
57
58/// `POST /v2/hash`: the digest of the UTF-8 bytes of `data`.
59#[derive(Debug, Clone, Default, Serialize, Deserialize)]
60#[serde(rename_all = "camelCase", deny_unknown_fields)]
61pub struct HashRequest {
62    /// The hash function.
63    pub algorithm: HashAlgorithm,
64    /// The text to hash (1 byte to 10 MiB).
65    pub data: SecretString,
66}
67
68/// The answer of `POST /v2/hash`.
69#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
70#[serde(rename_all = "camelCase")]
71#[non_exhaustive]
72pub struct HashResult {
73    /// The digest.
74    pub digest: Hex,
75    /// The hash function.
76    pub algorithm: String,
77    /// The digest length in bytes.
78    pub length: u64,
79}
80
81/// `POST /v2/hmac`: the HMAC of the UTF-8 bytes of `data`.
82#[derive(Debug, Clone, Default, Serialize, Deserialize)]
83#[serde(rename_all = "camelCase", deny_unknown_fields)]
84pub struct MacRequest {
85    /// The hash function.
86    pub algorithm: MacAlgorithm,
87    /// The text to authenticate.
88    pub data: SecretString,
89    /// The key, at least 16 bytes.
90    pub key: SecretBytes,
91}
92
93/// The answer of `POST /v2/hmac`.
94#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
95#[serde(rename_all = "camelCase")]
96#[non_exhaustive]
97pub struct MacResult {
98    /// The tag.
99    pub mac: Hex,
100    /// The hash function.
101    pub algorithm: String,
102}
103
104/// `POST /v2/hmac/verify`: whether `mac` is the HMAC of `data`.
105#[derive(Debug, Clone, Default, Serialize, Deserialize)]
106#[serde(rename_all = "camelCase", deny_unknown_fields)]
107pub struct MacVerifyRequest {
108    /// The hash function.
109    pub algorithm: MacAlgorithm,
110    /// The text that was authenticated.
111    pub data: SecretString,
112    /// The key.
113    pub key: SecretBytes,
114    /// The tag to check.
115    pub mac: Hex,
116}
117
118/// Key derivation functions of `POST /v2/kdf`.
119#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
120#[serde(rename_all = "kebab-case")]
121#[non_exhaustive]
122pub enum KdfAlgorithm {
123    /// scrypt (N = 2^17, r = 8).
124    Scrypt,
125    /// HKDF-SHA256.
126    #[default]
127    HkdfSha256,
128    /// PBKDF2-SHA256, at least 600,000 iterations.
129    Pbkdf2Sha256,
130}
131
132/// Tuning of `POST /v2/kdf`; each member applies to some algorithms only.
133#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
134#[serde(deny_unknown_fields)]
135pub struct KdfParams {
136    /// scrypt's cost, 131072 (2^17).
137    #[serde(rename = "N", default, skip_serializing_if = "Option::is_none")]
138    pub n: Option<u64>,
139    /// scrypt's block size, 8.
140    #[serde(default, skip_serializing_if = "Option::is_none")]
141    pub r: Option<u32>,
142    /// scrypt's parallelism, 1 to 4.
143    #[serde(default, skip_serializing_if = "Option::is_none")]
144    pub p: Option<u32>,
145    /// PBKDF2's iteration count, 600,000 to 1,000,000.
146    #[serde(default, skip_serializing_if = "Option::is_none")]
147    pub iterations: Option<u32>,
148    /// HKDF's info text, up to 1024 characters.
149    #[serde(default, skip_serializing_if = "Option::is_none")]
150    pub info: Option<String>,
151}
152
153/// `POST /v2/kdf`: derives a key from a password or input key material.
154#[derive(Debug, Clone, Default, Serialize, Deserialize)]
155#[serde(rename_all = "camelCase", deny_unknown_fields)]
156pub struct KdfRequest {
157    /// The derivation function.
158    pub algorithm: KdfAlgorithm,
159    /// The password or input key material, as text.
160    pub password: SecretString,
161    /// The salt; 16 random bytes when absent.
162    #[serde(default, skip_serializing_if = "Option::is_none")]
163    pub salt: Option<Hex>,
164    /// The derived key's length in bytes, 16 to 64.
165    #[serde(default, skip_serializing_if = "Option::is_none")]
166    pub key_length: Option<u32>,
167    /// Algorithm parameters.
168    #[serde(default, skip_serializing_if = "Option::is_none")]
169    pub params: Option<KdfParams>,
170}
171
172/// The answer of `POST /v2/kdf`.
173#[derive(Debug, Clone, Serialize, Deserialize)]
174#[serde(rename_all = "camelCase")]
175#[non_exhaustive]
176pub struct KdfResult {
177    /// The derived key.
178    pub derived_key: SecretBytes,
179    /// The salt used: the request's, or 16 random bytes.
180    pub salt: Hex,
181    /// The derivation function.
182    pub algorithm: String,
183    /// The derived key's length in bytes.
184    pub key_length: u64,
185}
186
187/// Argon2id parameters: memory in KiB, passes and lanes.
188#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
189#[serde(deny_unknown_fields)]
190pub struct Argon2Params {
191    /// Memory cost in KiB.
192    pub m: u32,
193    /// Time cost (passes).
194    pub t: u32,
195    /// Parallelism (lanes).
196    pub p: u32,
197}
198
199/// `POST /v2/password/hash`: an Argon2id hash of a password.
200#[derive(Debug, Clone, Default, Serialize, Deserialize)]
201#[serde(rename_all = "camelCase", deny_unknown_fields)]
202pub struct PasswordHashRequest {
203    /// The password, 1 to 1024 characters.
204    pub password: SecretString,
205    /// Passes, 2 to 10 (default 3).
206    #[serde(default, skip_serializing_if = "Option::is_none")]
207    pub time_cost: Option<u32>,
208    /// Memory in KiB, 19456 to 262144 (default 65536).
209    #[serde(default, skip_serializing_if = "Option::is_none")]
210    pub memory_cost: Option<u32>,
211    /// Lanes, 1 to 8 (default 4).
212    #[serde(default, skip_serializing_if = "Option::is_none")]
213    pub parallelism: Option<u32>,
214}
215
216/// The answer of `POST /v2/password/hash`.
217#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
218#[serde(rename_all = "camelCase")]
219#[non_exhaustive]
220pub struct PasswordHashResult {
221    /// The 32-byte Argon2id hash.
222    pub hash: Hex,
223    /// The random 16-byte salt.
224    pub salt: Hex,
225    /// The parameters used.
226    pub params: Argon2Params,
227    /// `argon2id`.
228    pub algorithm: String,
229    /// The same hash as a PHC string.
230    pub phc: String,
231}
232
233/// `POST /v2/password/verify`: whether `password` matches a stored hash.
234#[derive(Debug, Clone, Default, Serialize, Deserialize)]
235#[serde(rename_all = "camelCase", deny_unknown_fields)]
236pub struct PasswordVerifyRequest {
237    /// The password to check.
238    pub password: SecretString,
239    /// The stored hash.
240    pub hash: Hex,
241    /// The stored salt.
242    pub salt: Hex,
243    /// The stored parameters.
244    pub params: Argon2Params,
245}
246
247/// The answer of `POST /v2/password/verify`.
248#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
249#[non_exhaustive]
250pub struct PasswordVerifyResult {
251    /// Whether the password matches.
252    pub valid: bool,
253}