Deprecate methods that are easy to misuse (#115)

Various helper methods have documented requirements on their inputs, but
for some of them it's too easy for library users to miss the requirement
and include code that panics on invalid input.

For example, the obvious code to parse and validate a `CoseMac0`:

```
let mac = CoseMac0::from_slice(data);
mac.verify_tag(&aad, |t, d| verify(t, d, k))?;
```

misses the required check that `mac.payload.is_some()`, and so can
panic on invalid input.

So deprecate the helpers that are susceptible to this, in favour of
equivalent methods that explicitly check the prerequisites.

Author: daviddrysdale

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - Breaking change:  alter type of `crit` field in `Header` to support private-use labels (in accordance with
   [9052 §3.1](https://datatracker.ietf.org/doc/html/rfc9052#name-common-cose-header-paramete)).
+- Deprecate `CoseMac[0]::verify_tag` in favour of `verify_payload_tag`.
+- Deprecate `CoseEncrypt[0]::decrypt`, `CoseRecipient::decrypt` in favour of `decrypt_ciphertext`.
 
 ## 0.3.8 - 2024-07-24
 

src/encrypt/mod.rs

@@ -102,6 +102,7 @@ impl CoseRecipient {
     ///
     /// This function will panic if no `ciphertext` is available. It will also panic
     /// if the `context` parameter does not refer to a recipient context.
+    #[deprecated = "Use decrypt_ciphertext() to ensure ciphertext is present"]
     pub fn decrypt<F, E>(
         &self,
         context: EncryptionContext,
@@ -121,6 +122,38 @@ impl CoseRecipient {
         let aad = enc_structure_data(context, self.protected.clone(), external_aad);
         cipher(ct, &aad)
     }
+
+    /// Decrypt the `ciphertext` value with an AEAD, using `cipher` to decrypt the cipher text and
+    /// combined AAD as per RFC 8152 section 5.3.  Returns `missing_ciphertext_error()` if the
+    /// `ciphertext` is not set.
+    ///
+    /// # Panics
+    ///
+    /// This function will panic if the `context` parameter does not refer to a recipient context.
+    pub fn decrypt_ciphertext<F, E, G>(
+        &self,
+        context: EncryptionContext,
+        external_aad: &[u8],
+        missing_ciphertext_error: G,
+        cipher: F,
+    ) -> Result<Vec<u8>, E>
+    where
+        F: FnOnce(&[u8], &[u8]) -> Result<Vec<u8>, E>,
+        G: FnOnce() -> E,
+    {
+        let ct = self
+            .ciphertext
+            .as_ref()
+            .ok_or_else(missing_ciphertext_error)?;
+        match context {
+            EncryptionContext::EncRecipient
+            | EncryptionContext::MacRecipient
+            | EncryptionContext::RecRecipient => {}
+            _ => panic!("unsupported encryption context {:?}", context), // safe: documented
+        }
+        let aad = enc_structure_data(context, self.protected.clone(), external_aad);
+        cipher(ct, &aad)
+    }
 }
 
 /// Builder for [`CoseRecipient`] objects.
@@ -267,6 +300,7 @@ impl CoseEncrypt {
     /// # Panics
     ///
     /// This function will panic if no `ciphertext` is available.
+    #[deprecated = "Use decrypt_ciphertext() to ensure ciphertext is present"]
     pub fn decrypt<F, E>(&self, external_aad: &[u8], cipher: F) -> Result<Vec<u8>, E>
     where
         F: FnOnce(&[u8], &[u8]) -> Result<Vec<u8>, E>,
@@ -279,6 +313,30 @@ impl CoseEncrypt {
         );
         cipher(ct, &aad)
     }
+
+    /// Decrypt the `ciphertext` value with an AEAD, using `cipher` to decrypt the cipher text and
+    /// combined AAD.  Returns `missing_ciphertext_error()` if the `ciphertext` is not set.
+    pub fn decrypt_ciphertext<F, E, G>(
+        &self,
+        external_aad: &[u8],
+        missing_ciphertext_error: G,
+        cipher: F,
+    ) -> Result<Vec<u8>, E>
+    where
+        F: FnOnce(&[u8], &[u8]) -> Result<Vec<u8>, E>,
+        G: FnOnce() -> E,
+    {
+        let ct = self
+            .ciphertext
+            .as_ref()
+            .ok_or_else(missing_ciphertext_error)?;
+        let aad = enc_structure_data(
+            EncryptionContext::CoseEncrypt,
+            self.protected.clone(),
+            external_aad,
+        );
+        cipher(ct, &aad)
+    }
 }
 
 /// Builder for [`CoseEncrypt`] objects.
@@ -395,6 +453,7 @@ impl CoseEncrypt0 {
     /// # Panics
     ///
     /// This function will panic if no `ciphertext` is available.
+    #[deprecated = "Use decrypt_ciphertext() to ensure ciphertext is present"]
     pub fn decrypt<F, E>(&self, external_aad: &[u8], cipher: F) -> Result<Vec<u8>, E>
     where
         F: FnOnce(&[u8], &[u8]) -> Result<Vec<u8>, E>,
@@ -407,6 +466,30 @@ impl CoseEncrypt0 {
         );
         cipher(ct, &aad)
     }
+
+    /// Decrypt the `ciphertext` value with an AEAD, using `cipher` to decrypt the cipher text and
+    /// combined AAD.  Returns `missing_ciphertext_error()` if the `ciphertext` is not set.
+    pub fn decrypt_ciphertext<F, E, G>(
+        &self,
+        external_aad: &[u8],
+        missing_ciphertext_error: G,
+        cipher: F,
+    ) -> Result<Vec<u8>, E>
+    where
+        F: FnOnce(&[u8], &[u8]) -> Result<Vec<u8>, E>,
+        G: FnOnce() -> E,
+    {
+        let ct = self
+            .ciphertext
+            .as_ref()
+            .ok_or_else(missing_ciphertext_error)?;
+        let aad = enc_structure_data(
+            EncryptionContext::CoseEncrypt0,
+            self.protected.clone(),
+            external_aad,
+        );
+        cipher(ct, &aad)
+    }
 }
 
 /// Builder for [`CoseEncrypt0`] objects.