Comments, bump version

Author: Bennett Hardwick

Cargo.lock

@@ -5,7 +5,7 @@ homepage = "https://cipherstash.com"
 repository = "https://github.com/cipherstash/cipherstash-dynamodb"
 readme = "README.md"
 description = "CipherStash client for storing and querying encrypted data in DynamoDB"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2021"
 
 [package.metadata.docs.rs]
@@ -25,7 +25,7 @@ repository = "https://github.com/cipherstash/cipherstash-dynamodb"
 
 [dependencies]
 cipherstash-client = { version = "0.10", registry = "cipherstash" }
-cipherstash-dynamodb-derive = { version = "0.6", path = "cipherstash-dynamodb-derive", registry = "cipherstash" }
+cipherstash-dynamodb-derive = { version = "0.7", path = "cipherstash-dynamodb-derive", registry = "cipherstash" }
 
 aws-sdk-dynamodb = "1.3.0"
 async-trait = "0.1.73"

Cargo.toml

@@ -4,7 +4,7 @@ license-file = "../LICENSE.md"
 homepage = "https://cipherstash.com"
 readme = "../README.md"
 description = "Derive macros for the CipherStash client for DynamoDB"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2021"
 
 [lib]

cipherstash-dynamodb-derive/Cargo.lock

@@ -23,6 +23,9 @@ pub use sealed::{SealedTableEntry, UnsealSpec};
 pub use sealer::Sealer;
 pub use unsealed::Unsealed;
 
+/// In order to stop indexes from exploding with indexes on large strings, cap the number of terms
+/// generated per index. Since there is a fixed number of terms per index it is also possible to
+/// delete all index terms for a particular record.
 const MAX_TERMS_PER_INDEX: usize = 25;
 
 #[derive(Debug, Error)]
@@ -65,6 +68,9 @@ pub fn format_term_key(
     format!("{sort_key}#{index_name}#{index_type}#{counter}")
 }
 
+/// Get all the term index keys for a particular sort key and index definitions
+///
+/// This is used to delete any index items that shouldn't exist during either an update or
 pub(crate) fn all_index_keys<'a>(
     sort_key: &str,
     protected_indexes: impl AsRef<[(Cow<'a, str>, IndexType)]>,
@@ -81,14 +87,14 @@ pub(crate) fn all_index_keys<'a>(
         .collect()
 }
 
-pub fn hmac<C>(
+/// Use a CipherStash [`ExactIndex`] to take the HMAC of a string with a provided salt
+///
+/// This value is used for term index keys and "encrypted" partition / sort keys
+pub fn hmac(
     value: &str,
     salt: Option<&str>,
-    cipher: &Encryption<C>,
-) -> Result<Vec<u8>, EncryptionError>
-where
-    C: Credentials<Token = ServiceToken>,
-{
+    cipher: &Encryption<impl Credentials<Token = ServiceToken>>,
+) -> Result<Vec<u8>, EncryptionError> {
     let plaintext = Plaintext::Utf8Str(Some(value.to_string()));
     let index = CompoundIndex::new(ExactIndex::new(vec![]));
 

cipherstash-dynamodb-derive/Cargo.toml

@@ -366,6 +366,9 @@ impl<D> EncryptedTable<D> {
         let sealed = sealer.seal(protected_attributes, &self.cipher, 12).await?;
 
         let mut put_records = Vec::with_capacity(sealed.len());
+
+        // When doing an upsert you need to delete any index keys that are not used for the current
+        // record but may have been used for previous records.
         let mut delete_records = vec![];
 
         let PrimaryKeyParts { pk, sk } = sealed.primary_key();
@@ -383,6 +386,7 @@ impl<D> EncryptedTable<D> {
         for index_sk in all_index_keys(&sk, protected_indexes) {
             let index_sk = b64_encode(hmac(&index_sk, Some(pk.as_str()), &self.cipher)?);
 
+            // If the current put has an index with the specified key then don't delete it.
             if seen_sk.contains(&index_sk) {
                 continue;
             }
@@ -399,6 +403,8 @@ impl<D> EncryptedTable<D> {
         })
     }
 
+    /// Take a prepared primary key and encrypt it to get the [`PrimaryKeyParts`] which can be used
+    /// for retrieval.
     pub fn encrypt_primary_key_parts(
         &self,
         prepared_primary_key: PreparedPrimaryKey,