From 76db9abe49adc075e093532a252914c9c080f987 Mon Sep 17 00:00:00 2001
From: Mark Kirichenko <mkirich@amazon.de>
Date: Mon, 13 Jan 2025 15:22:10 +0000
Subject: [PATCH] Update chagelog and docstrings

This commit updates the changelog and adds docstrings for methods
`new_from_public_key`, `sign`, and `verify` for `KmsKey`s to
specifically highlight the need to call these methods from a Tokio
runtime.

Signed-off-by: Mark Kirichenko <mkirich@amazon.de>
---
 CHANGELOG.md      | 15 +++++++++++++++
 Cargo.toml        |  2 +-
 src/crypto/kms.rs | 29 +++++++++++++++++++++++++++++
 3 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e21613..94d1010 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,21 @@
 
 # Changelog
 
+## 0.5.3
+* Bumped `aws-sdk-kms` to 1.22
+* Bumped MSRV to 1.71
+* Updated docstrings to mention the need in Tokio runtime for non-local key
+use-cases
+
+## 0.5.2
+* Bumped `serde_with` to 3.3
+* Bumped `tss-esapi` to 7.5
+* Bumped `aws-sdk-kms` to 1.20
+* Bumped MSRV to 1.68
+
+## 0.5.1
+* Fixed serde build errors after update
+
 ## 0.5.0
 * Support signing with an AWS KMS private key via the `key_kms` feature. (thank you @puiterwijk)
 * Abstract Openssl operations (thank you @raoulstrackx)
diff --git a/Cargo.toml b/Cargo.toml
index e857add..2982525 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "aws-nitro-enclaves-cose"
-version = "0.5.2"
+version = "0.5.3"
 authors = ["Petre Eftime <epetre@amazon.com>"]
 edition = "2018"
 license = "Apache-2.0"
diff --git a/src/crypto/kms.rs b/src/crypto/kms.rs
index 17f0b1b..a472bf7 100644
--- a/src/crypto/kms.rs
+++ b/src/crypto/kms.rs
@@ -52,6 +52,8 @@ impl KmsKey {
 
     /// Create a new KmsKey, using the specified client and key_id.
     ///
+    /// This method must be called from a Tokio context, otherwise the call panics.
+    ///
     /// The sig_alg needs to be valid for the specified key.
     /// This version will use local signature verification.
     /// If no public key is passed in, the key will be retrieved with GetPublicKey.
@@ -123,6 +125,21 @@ impl SigningPublicKey for KmsKey {
         Ok((self.sig_alg, self.sig_alg.suggested_message_digest()))
     }
 
+    /// Verifies a digital signature.
+    ///
+    /// If KMS is used for verification, this method must be called from a Tokio context,
+    /// otherwise the call panics.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - A byte slice containing the data to verify
+    /// * `signature` - A byte slice containing the signature to verify against the data
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(true)` - If the signature is valid for the given data
+    /// * `Ok(false)` - If the signature is invalid or verification fails gracefully
+    /// * `Err(CoseError)` - If an error occurs during verification
     fn verify(&self, data: &[u8], signature: &[u8]) -> Result<bool, CoseError> {
         if self.public_key.is_some() {
             #[cfg(feature = "key_openssl_pkey")]
@@ -172,6 +189,18 @@ impl SigningPublicKey for KmsKey {
 }
 
 impl SigningPrivateKey for KmsKey {
+    /// Signs data using AWS KMS and formats the signature according to the ECDSA specification.
+    ///
+    /// This method must be called from a Tokio context, otherwise the call panics.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - A byte slice containing the data to be signed
+    ///
+    /// # Returns
+    ///
+    /// * `Ok(Vec<u8>)` - A vector containing the formatted signature bytes
+    /// * `Err(CoseError)` - If signing or signature formatting fails
     fn sign(&self, data: &[u8]) -> Result<Vec<u8>, CoseError> {
         let request = self
             .client