cipher: clarify the EncryptingKey docs

aws / aws-lc-rs

aws-lc-rs is a cryptographic library using AWS-LC for its cryptographic operations. The library strives to be API-compatible with the popular Rust library named ring.

Other

318 stars 49 forks source link

Issues:

N/A

Description of changes:

While working with the aws_lc_rs::cipher module downstream in https://github.com/rustls/rustls/pull/2066 we noticed the documentation here could use a small touch-up.

Previously the aws_lc_rs::cipher::EncryptingKey type's encrypt() and less_safe_encrypt() functions were documented as returning a reference to the encrypted data. However, the implementation uses an in_out: &mut [u8] argument for the encrypted data and returns a DecryptionContext, not a ref. to ciphertext.

Similarly, it feels important to call out that the DecryptionContext when using encrypt() contains a randomly generated IV. This makes usage clearer and also provides good counter-point to the disclaimer on less_safe_encrypt() about the provenance (and safety) of the IV being unknown.

Call-outs:

None that I can think of :-)

Testing:

N/A - docs only update.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 92.69%. Comparing base (c358484) to head (fa3209b). Report is 49 commits behind head on main.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #488 +/- ## ========================================== - Coverage 95.80% 92.69% -3.11% ========================================== Files 61 63 +2 Lines 8143 8456 +313 Branches 0 8456 +8456 ========================================== + Hits 7801 7838 +37 - Misses 342 361 +19 - Partials 0 257 +257 ```

aws / aws-lc-rs