aucpace_conflux/database.rs
1#[cfg(feature = "partial_augmentation")]
2use crate::Result;
3use password_hash::{ParamsString, SaltString};
4
5/// trait for `AuCPace` to use to abstract over the storage and retrieval of verifiers
6pub trait Database {
7 /// The type of password verifier stored in the database
8 type PasswordVerifier;
9
10 /// perform `LookupW`, returning the password verifier `W`, if it exists.
11 ///
12 /// # Arguments:
13 /// `username`: the user the lookup the verifier for
14 ///
15 /// # Return:
16 /// `(password verifier, salt, sigma)`
17 /// where `password verifier` is the verifier stored for the given user
18 /// `salt` is the salt used when hashing the password
19 /// `sigma` is the parameters used by the the PBKDF when hashing the user's password
20 fn lookup_verifier(
21 &self,
22 username: &[u8],
23 ) -> Option<(Self::PasswordVerifier, SaltString, ParamsString)>;
24
25 /// store a username, salt, verifier and hash parameters to the database.
26 /// This function should allow for overwriting users credentials if they exist.
27 /// This is required for password changes and should only be performed once the user has
28 /// negotiated a full session key.
29 ///
30 /// # Arguments:
31 /// - `username`: The name of the user who is storing a verifier
32 /// - `salt`: The salt used when creating the verifier
33 /// - `uad`: Optional - User Attached Data - "represents application data associated with
34 /// this specific user account, e.g. specifying the granted authorization level
35 /// on the server."
36 /// - `verifier`: The password verifier for the given user
37 /// - `params`: The parameters used when hashing the password into the verifier -
38 /// It is called sigma in the protocol defionition
39 fn store_verifier(
40 &mut self,
41 username: &[u8],
42 salt: SaltString,
43 uad: Option<&[u8]>,
44 verifier: Self::PasswordVerifier,
45 params: ParamsString,
46 );
47}
48
49/// trait for `AuCPace` to use to abstract over the storage and retrieval of long-term keypairs
50#[cfg(feature = "partial_augmentation")]
51pub trait PartialAugDatabase {
52 /// The private key type
53 type PrivateKey;
54
55 /// The public key type
56 type PublicKey;
57
58 /// retrieve a long-term key pair from the database
59 ///
60 /// # Arguments:
61 /// `username`: the user the lookup the keypair for
62 ///
63 /// # Return:
64 /// - Some((`public_key`, `private_key`)): if the user has a long term keypair associated with them
65 /// - `private_key`: corresponds to `x` from the protocol definition
66 /// - `public_key`: corresponds to `x_pub` from the protocol definition
67 /// - None: if the user has no associated keypair
68 ///
69 fn lookup_long_term_keypair(
70 &self,
71 username: &[u8],
72 ) -> Option<(Self::PrivateKey, Self::PublicKey)>;
73
74 /// store a long-term key pair for `username`
75 ///
76 /// This can be generated with [`AuCPaceServer::generate_long_term_keypair`](crate::AuCPaceServer::generate_long_term_keypair)
77 ///
78 /// # Arguments:
79 /// - `username`: the user the store the keypair for
80 /// - `priv_key`: the private key to store
81 /// - `pub_key`: the public key to store
82 ///
83 /// # Return:
84 /// - Ok(()): success - the keypair was stored correctly
85 /// - Err([`Error::UserNotRegistered`](crate::Error::UserNotRegistered)): failure -
86 /// `username` is not registered and thus we cannot store a keypair for them
87 ///
88 fn store_long_term_keypair(
89 &mut self,
90 username: &[u8],
91 priv_key: Self::PrivateKey,
92 pub_key: Self::PublicKey,
93 ) -> Result<()>;
94}
95
96/// trait for `AuCPace` to use to abstract over the storage and retrieval of verifiers and secret exponents
97#[cfg(feature = "strong_aucpace")]
98pub trait StrongDatabase {
99 /// The type of password verifier stored in the database
100 type PasswordVerifier;
101
102 /// The type of the secret exponent `q` stored in the database
103 type Exponent;
104
105 /// perform `LookupW`, returning the password verifier `W`, and secret exponent `q` if they exist
106 ///
107 /// # Arguments:
108 /// `username`: the user to lookup the verifier for
109 ///
110 /// # Return:
111 /// `(password verifier, secret exponent, params)`:
112 /// - `password verifier`: the verifier stored for the given user
113 /// - `secret exponent`: the value of `q` stored for the given user
114 /// - `params`: the parameters used by the the PBKDF when hashing the user's password
115 fn lookup_verifier_strong(
116 &self,
117 username: &[u8],
118 ) -> Option<(Self::PasswordVerifier, Self::Exponent, ParamsString)>;
119
120 /// store a username, secret exponent, verifier and hash parameters to the database.
121 /// This function should allow for overwriting users credentials if they exist.
122 /// This is required for password changes and should only be done once the user has negotiated
123 /// a full session key.
124 ///
125 /// # Arguments:
126 /// - `username`: The name of the user who is storing a verifier
127 /// - `uad`: Optional - User Attached Data - "represents application data associated with
128 /// this specific user account, e.g. specifying the granted authorization level
129 /// on the server."
130 /// - `verifier`: The password verifier for the given user
131 /// - `secret exponent`: the value of `q` stored for the given user
132 /// - `params`: The parameters used when hashing the password into the verifier -
133 /// It is called sigma in the protocol definition
134 fn store_verifier_strong(
135 &mut self,
136 username: &[u8],
137 uad: Option<&[u8]>,
138 verifier: Self::PasswordVerifier,
139 secret_exponent: Self::Exponent,
140 params: ParamsString,
141 );
142}