From d2fbd25a7c614cd11ca89ca2b76506fb547d0f4c Mon Sep 17 00:00:00 2001
From: Hugo Rosenkranz-Costa <hugo.rosenkranz@cosmian.com>
Date: Fri, 12 Jan 2024 16:25:08 +0100
Subject: [PATCH] docs: update CHANGELOG and docstring

---
 CHANGELOG.md    | 10 ++++++++++
 src/core/api.rs | 10 ++++++----
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4bcf8d81..436885b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Features
+
+- Change `Axis` to `Dimension` with a clear distinction between `Ordered` and `Unordered`.
+- Create a `Dictionary` data structure to store and update `Ordered Dimension` efficiently
+- Change the data structure of `MasterSecretKey` and `UserSecretKey` to keep track of subkeys version.
+- Policy does not count the attribute rotations anymore as they are stored in the subkeys.
+- a `UserSecretKey` can now be refreshed without any external `Policy` information.
+
 ## [13.0.0] - 2023-11-06
 
 ### Bug Fixes
diff --git a/src/core/api.rs b/src/core/api.rs
index 09d5f028..6ebb1c3a 100644
--- a/src/core/api.rs
+++ b/src/core/api.rs
@@ -75,8 +75,8 @@ impl Covercrypt {
         )
     }
 
-    /// Renews the keys associated to the given access policy in the master
-    /// keys.
+    /// Generate new keys associated to the given access policy in the master
+    /// keys. User keys will need to be refreshed after this step.
     ///  - `access_policy`  : describe the keys to renew
     ///  - `policy`         : global policy
     ///  - `msk`            : master secret key
@@ -96,7 +96,8 @@ impl Covercrypt {
         )
     }
 
-    /// Removes old keys from the master keys.
+    /// Removes old keys associated to the given master keys from the master
+    /// keys. This will permanently remove access to old ciphers.
     ///  - `access_policy`  : describe the keys to prune
     ///  - `policy`         : global policy
     ///  - `msk`            : master secret key
@@ -114,7 +115,8 @@ impl Covercrypt {
 
     /// Generates a user secret key.
     ///
-    /// A new user secret key does NOT include to old (i.e. rotated) partitions.
+    /// A new user secret key only has the latest keys corresponding to its
+    /// access policy.
     ///
     /// - `msk`           : master secret key
     /// - `access_policy` : user access policy