progress at applying #to all crates

Author: ounsworth

CONTRIBUTING.md

@@ -2,76 +2,117 @@
 
 Thank you for contributing to Bouncy Castle!
 
-In this guide, you get an overview of the contribution workflow from starting a discussion or opening an issue, to creating, reviewing, and merging a pull request.
+In this guide, you get an overview of the contribution workflow from starting a discussion or opening an issue, to
+creating, reviewing, and merging a pull request.
 
-For an overview of the project, see [README](README.md). 
+For an overview of the project, see [README](README.md).
 
 ## Start a discussion
-If you have a question or problem, you can [search in discussions](https://github.com/bcgit/bc-rust/discussions), if someone has already found a solution to your problem. 
 
-Or you can [start a new discussion](https://github.com/bcgit/bc-rust/discussions/new/choose) and ask your question. 
+If you have a question or problem, you can [search in discussions](https://github.com/bcgit/bc-rust/discussions), if
+someone has already found a solution to your problem.
+
+Or you can [start a new discussion](https://github.com/bcgit/bc-rust/discussions/new/choose) and ask your question.
 
 ## Create an issue
 
 If you find a problem with Bouncy Castle, [search if an issue already exists](https://github.com/bcgit/bc-rust/issues).
 
 > **_NOTE:_**  If the issue is a __potential security problem__, please contact us
-before posting anything public. See [Security Policy](SECURITY.md).
+> before posting anything public. See [Security Policy](SECURITY.md).
 
-If a related discussion or issue doesn't exist, and the issue is not security related, you can [open a new issue](https://github.com/bcgit/bc-java/issues/new). An issue can be converted into a discussion if regarded as one.
+If a related discussion or issue doesn't exist, and the issue is not security related, you
+can [open a new issue](https://github.com/bcgit/bc-java/issues/new). An issue can be converted into a discussion if
+regarded as one.
 
 ## Coding philosophy
 
 > Slow is smooth, smooth is fast.
 
-There is a time and a place for "Move fast and break things", but the source code of a crypto library is not one of them.
+There is a time and a place for "Move fast and break things", but the source code of a crypto library is not one of
+them.
 
-This project takes the philosophy that taking the time to do things right pays off in the long run, both in terms of 
-the runtime and memory footprint of the code, and it terms of the time required for a future maintainer to get up to speed with the code
+This project takes the philosophy that taking the time to do things right pays off in the long run, both in terms of
+the runtime and memory footprint of the code, and it terms of the time required for a future maintainer to get up to
+speed with the code
 and avoid introducing bugs due to the code being hard to understand.
 
 Some specifics:
 
-* Respect that the innovative process sometimes requires exploring several dead-ends before you find the most elegant solution.
-* Public APIs of a library should be both ergonomic and expressive. When defining a new trait or public function, ask yourself whether a programmer who is new to cryptography is likely to use this in a way that will get them into trouble.
-* Variables should be well-named, well-structured, and well-commented (a comment-to-code ration of 1:1 is a goal to be strived for!). Think about memory footprint and, where possible, use unnamed scopes to allow the compiler to pop intermediate value variables off the stack as soon as they are no longer needed.
-* Always run your code through `cargo mutants` and get the issue count as low as your can. As a first pass, this forces you to write thorough unit tests. As a second pass, this draws your attention to bits of your code that cannot be tested from the outside. Often this means that the code can be simplified without affecting functionality (as defined by your set of unit tests) -- "simpler code" usually means faster runtime and easier future maintenance.
+* Respect that the innovative process sometimes requires exploring several dead-ends before you find the most elegant
+  solution.
+* Public APIs of a library should be both ergonomic and expressive. When defining a new trait or public function, ask
+  yourself whether a programmer who is new to cryptography is likely to use this in a way that will get them into
+  trouble.
+* Variables should be well-named, well-structured, and well-commented (a comment-to-code ration of 1:1 is a goal to be
+  strived for!). Think about memory footprint and, where possible, use unnamed scopes to allow the compiler to pop
+  intermediate value variables off the stack as soon as they are no longer needed.
+* Always run your code through `cargo mutants` and get the issue count as low as your can. As a first pass, this forces
+  you to write thorough unit tests. As a second pass, this draws your attention to bits of your code that cannot be
+  tested from the outside. Often this means that the code can be simplified without affecting functionality (as defined
+  by your set of unit tests) -- "simpler code" usually means faster runtime and easier future maintenance.
 
 ## Contribute to the code
 
-For substantial, non-trivial contributions, you may be asked to sign a contributor assignment agreement. Optionally, you can also have your name and contact information listed in [Contributors](https://www.bouncycastle.org/contributors.html). 
+For substantial, non-trivial contributions, you may be asked to sign a contributor assignment agreement. Optionally, you
+can also have your name and contact information listed
+in [Contributors](https://www.bouncycastle.org/contributors.html).
 
-Please note we are unable to accept contributions which cannot be released under the [Bouncy Castle License](https://www.bouncycastle.org/licence.html). Issuing a pull request on our public github mirror is taken as agreement to issuing under the Bouncy Castle License.
+Please note we are unable to accept contributions which cannot be released under
+the [Bouncy Castle License](https://www.bouncycastle.org/licence.html). Issuing a pull request on our public github
+mirror is taken as agreement to issuing under the Bouncy Castle License.
 
 ### Create a pull request
 
 > **_NOTE:_**  If the issue is a __potential security problem__, please contact us. See [Security Policy](SECURITY.md).
 
-You are welcome to send patches, under the Bouncy Castle License, as pull requests. For more information, see [Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). For minor updates, you can instead choose to create an issue with short snippets of code. See above.
+You are welcome to send patches, under the Bouncy Castle License, as pull requests. For more information,
+see [Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+For minor updates, you can instead choose to create an issue with short snippets of code. See above.
 
-* For contributions touching multiple files try and split up the pull request, smaller changes are easier to review and test, as well as being less likely to run into merge issues.
-* Create a test cases for your change, it may be a simple addition to an existing test. If you do not know how to do this, ask us and we will help you. 
-* If you run into any merge issues, check out this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to help you resolve merge conflicts and other issues.
+* For contributions touching multiple files try and split up the pull request, smaller changes are easier to review and
+  test, as well as being less likely to run into merge issues.
+* Create a test cases for your change, it may be a simple addition to an existing test. If you do not know how to do
+  this, ask us and we will help you.
+* If you run into any merge issues, check out this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to
+  help you resolve merge conflicts and other issues.
 
-For more information, refer to the Bouncy Castle documentation on [Getting Started with Bouncy Castle](https://doc.primekey.com/bouncycastle/introduction#Introduction-GettingStartedwithBouncyCastle).
+For more information, refer to the Bouncy Castle documentation
+on [Getting Started with Bouncy Castle](https://doc.primekey.com/bouncycastle/introduction#Introduction-GettingStartedwithBouncyCastle).
 
 ### Quality Standards
+
 Except where otherwise noted, all crates must have:
 
 * benchmarks
 * unit tests that (mostly) satisfy cargo mutants
 * lib.rs needs to compile with: #![forbid(missing_docs)], #![no_std]
-* Fallibility: as much as humanly possible, Result and unwrap() should be used for "Bad input data" type things and not "Programmer didn't read the docs" type things. Things like \[u8]'s of the wrong length, or trying to call an algorithm with a key of the wrong parameter set should be detected at compile time via the typing system and should not require a Result / unwrap() mechanism. Please run `./dev_scripts/quality_stats.sh` before and after your change to see if you have increased the fallibility of the code you changed.
+* Fallibility: as much as humanly possible, Result and unwrap() should be used for "Bad input data" type things and
+  not "Programmer didn't read the docs" type things. Things like \[u8]'s of the wrong length, or trying to call an
+  algorithm with a key of the wrong parameter set should be detected at compile time via the typing system and should
+  not require a Result / unwrap() mechanism. Please run `./dev_scripts/quality_stats.sh` before and after your change to
+  see if you have increased the fallibility of the code you changed.
 
-Code submissions that do not meet these standards, or that require significant effort from the maintainers in order to meet these standards, will not be accepted.
+Code submissions that do not meet these standards, or that require significant effort from the maintainers in order to
+meet these standards, will not be accepted.
 
 ### Self-review
 
 Don't forget to self-review. Please follow these simple guidelines:
-* Keep the patch limited, only change the parts related to your patch. 
-* Do not change other lines, such as whitespace, adding line breaks to Java doc, etc. It will make it very hard for us to review the patch.
+
+* Keep the patch limited, only change the parts related to your patch.
+* Do not change other lines, such as whitespace, adding line breaks to Java doc, etc. It will make it very hard for us
+  to review the patch.
 
 #### Your pull request is merged
 
-Someone on the Bouncy Castle core team will review the pull request when there is time, and let you know if something is missing or suggest improvements. If it is a useful and generic feature it will be integrated in Bouncy Castle to be available in a later release.
+Someone on the Bouncy Castle core team will review the pull request when there is time, and let you know if something is
+missing or suggest improvements. If it is a useful and generic feature it will be integrated in Bouncy Castle to be
+available in a later release.
+
+## AI Policy
 
+LLM-based coding assistants are a great tool, but, especially for a cryptography library, they must be used under the
+strict supervision of a human who takes responsibility for the submitted code, code review process, and for asserting
+that the submission does not include copyrighted material and is assignable to the Legion of the Bouncy Castle.
+Contributions not clearly from a human will be rejected.

alpha_0.1.2_release_notes.md

@@ -22,17 +22,14 @@
   appropriate.
 * Probably it makes sense to leave Hex and Base64 as requiring std; ... or maybe add a no_std version that uses
   fixed-sized blocks?
-* Make this build on the stable compiler. IE Remove the rust-toolchain.toml file that builds with nightly. Will require
-  some refactoring.
 * Create a cargo feature #[cfg(feature='rng')] and put it around things like keygen that takes an rng so that the build
   dependency on bouncycastle_rng is optional.
 * Factories ... Are they worth it? Michael Richardson says Very Yes. If we are keeping them, then we need a serious
   re-engineering of them because I really dislike that currently they make it hard for the underlying primitive to have
   static one-shot APIs.
 * Deal with as many of the inline TODOs as possible
 * Close all open github issues and document them in this file.
-* After everything is merged, circle back to crucible, and make sure that the harness still works (and maybe remove the
-  nightly build toolchain)
+* After everything is merged, circle back to crucible, and make sure that the harness still works
 * Search for all the uses of .unwrap() in non-test code and replace each with either a comment or an expect with a
   meaningful error string.
 
@@ -59,6 +56,7 @@
   .drop_hazardous_operations(), it now uses a closure-based do_hazardous_operations(). Github issue #39.
 * Renamed KeyMaterial::KeyType's and deleted KeyMaterial::concatenate in order to give a better intuition and
   FIPS-alignment.
+* Removed the dependence on nightly / experimental compiler features; the library now buildds on stable.
 * Github issues resolved:
     * #6: https://github.com/bcgit/bc-rust/issues/6, thanks to Q. T. Felix (github: @Quant-TheodoreFelix)
     * #10: https://github.com/bcgit/bc-rust/issues/10, thanks to Nicola Tuveri (github: @romen)

crypto/base64/src/lib.rs

@@ -81,6 +81,9 @@
 //     /// "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_="
 //     URLSafe,
 
+#![forbid(unsafe_code)]
+#![forbid(missing_docs)]
+
 use bouncycastle_utils::ct::Condition;
 
 /// One-shot encode from bytes to a base64-encoded string using a constant-time implementation.
@@ -93,6 +96,7 @@ pub fn decode<T: AsRef<[u8]>>(input: T) -> Result<Vec<u8>, Base64Error> {
     Base64Decoder::new(true).do_final(input)
 }
 
+/// Return type for errors relating to Base64 encoding and decoding.
 #[derive(Debug)]
 pub enum Base64Error {
     /// the do_update() method must not be called on a block that contains padding.
@@ -141,6 +145,8 @@ impl Base64Encoder {
         ret as u8
     }
 
+    /// Streaming API that performs Base64 encoding of the provided input, but does not apply
+    /// the final padding and will hold an incomplete block while waiting for more input.
     pub fn do_update<T: AsRef<[u8]>>(&mut self, input: T) -> String {
         let inref = input.as_ref();
         let mut out: Vec<u8> = Vec::with_capacity(inref.len() * 4 / 3 + 4);
@@ -245,6 +251,8 @@ impl Base64Decoder {
         ret as u8
     }
 
+    /// Streaming API that performs Base64 encoding of the provided input, but does not apply
+    /// the final padding and will hold an incomplete block while waiting for more input.
     pub fn do_update<T: AsRef<[u8]>>(&mut self, input: T) -> Result<Vec<u8>, Base64Error> {
         self.decode_internal(input, true)
     }

crypto/core/src/errors.rs

@@ -1,56 +1,99 @@
+//! Core error types to be used in Result return types.
+//! Errors defined in this module are typically one-to-one with traits defined in [crate::traits].
+//!
+//! Most errors are self-explanatory, but additional description is available on some.
+
+///
 #[derive(Debug)]
 pub enum HashError {
+    ///
     GenericError(&'static str),
+    ///
     InvalidLength(&'static str),
+    ///
     InvalidState(&'static str),
+    ///
     InvalidInput(&'static str),
+    ///
     KeyMaterialError(KeyMaterialError),
 }
 
+///
 #[derive(Debug)]
 pub enum KeyMaterialError {
+    ///
     ActingOnZeroizedKey,
+    ///
     GenericError(&'static str),
+    ///
     HazardousOperationNotPermitted,
+    ///
     InputDataLongerThanKeyCapacity,
+    ///
     InvalidKeyType(&'static str),
+    ///
     InvalidLength,
+    ///
     SecurityStrength(&'static str),
 }
 
+///
 #[derive(Debug)]
 pub enum KDFError {
+    ///
     GenericError(&'static str),
+    ///
     HashError(HashError),
+    ///
     InvalidLength(&'static str),
+    ///
     KeyMaterialError(KeyMaterialError),
+    ///
     MACError(MACError),
 }
 
+///
 #[derive(Debug)]
 pub enum KEMError {
+    ///
     GenericError(&'static str),
+    ///
     ConsistencyCheckFailed(&'static str),
+    ///
     EncodingError(&'static str),
+    ///
     DecapsulationFailed,
+    ///
     DecodingError(&'static str),
+    ///
     KeyGenError(&'static str),
+    ///
     KeyMaterialError(KeyMaterialError),
+    ///
     LengthError(&'static str),
+    ///
     RNGError(RNGError),
 }
 
+///
 #[derive(Debug)]
 pub enum MACError {
+    ///
     GenericError(&'static str),
+    ///
     HashError(HashError),
+    ///
     InvalidLength(&'static str),
+    ///
     InvalidState(&'static str),
+    ///
     KeyMaterialError(KeyMaterialError),
 }
 
+///
 #[derive(Debug)]
 pub enum RNGError {
+    ///
     GenericError(&'static str),
 
     /// Attempting to extract output before the RNG has been seeded.
@@ -69,9 +112,11 @@ pub enum RNGError {
     /// than the algorithm requires.
     SecurityStrengthInsufficientForAlgorithm,
 
+    ///
     KeyMaterialError(KeyMaterialError),
 }
 
+///
 #[derive(Debug)]
 pub enum SuspendableError {
     /// The serialized state was produced by a library version incompatible with this one.
@@ -80,16 +125,26 @@ pub enum SuspendableError {
     InvalidData,
 }
 
+///
 #[derive(Debug)]
 pub enum SignatureError {
+    ///
     GenericError(&'static str),
+    ///
     ConsistencyCheckFailed(),
+    ///
     EncodingError(&'static str),
+    ///
     DecodingError(&'static str),
+    ///
     KeyGenError(&'static str),
+    ///
     KeyMaterialError(KeyMaterialError),
+    ///
     LengthError(&'static str),
+    ///
     SignatureVerificationFailed,
+    ///
     RNGError(RNGError),
 }
 

crypto/core/src/key_material.rs

@@ -59,9 +59,11 @@ use core::fmt;
 
 /// Sometimes you just need a zero-length dummy key.
 pub type KeyMaterial0 = KeyMaterial<0>;
-
+/// Named type for a 128-bit (16-byte) key, for convenience.
 pub type KeyMaterial128 = KeyMaterial<16>;
+/// Named type for a 256-bit (32-byte) key, for convenience.
 pub type KeyMaterial256 = KeyMaterial<32>;
+/// Named type for a 512-bit (64-byte) key, for convenience.
 pub type KeyMaterial512 = KeyMaterial<64>;
 
 /// A helper class used across the bc-rust.test library to hold bytes-like key material.
@@ -153,6 +155,7 @@ pub trait KeyMaterialTrait: KeyMaterialInternalTrait {
     /// [do_hazardous_operations] closure.
     fn set_key_len(&mut self, key_len: usize) -> Result<(), KeyMaterialError>;
 
+    /// Returns the [KeyType] of this KeyMaterial object.
     fn key_type(&self) -> KeyType;
 
     /// Sets (or safely converts) the [KeyType] of this KeyMaterial object.
@@ -225,6 +228,7 @@ impl<const KEY_LEN: usize> Secret for KeyMaterial<KEY_LEN> {}
 // `SerializableState` implementations (see the `TryFrom<u8>` impl below). Pin each value to its
 // variant name: reordering variants is fine, but never reuse or renumber an existing discriminant,
 // or previously-serialized states will be misread.
+///
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[repr(u8)]
 pub enum KeyType {
@@ -279,6 +283,8 @@ impl<const KEY_LEN: usize> Default for KeyMaterial<KEY_LEN> {
 }
 
 impl<const KEY_LEN: usize> KeyMaterial<KEY_LEN> {
+    /// Creates a new empty instance (key_len = 0, key_type = Zeroized).
+    /// If you want a properly populated instance, use [KeyMaterial::from_rng].
     pub fn new() -> Self {
         Self {
             buf: [0u8; KEY_LEN],
@@ -289,7 +295,7 @@ impl<const KEY_LEN: usize> KeyMaterial<KEY_LEN> {
         }
     }
 
-    /// Create a new instance of KeyMaterial containing random bytes from the provided random number generator.
+    /// Creates a new instance of KeyMaterial containing random bytes from the provided random number generator.
     pub fn from_rng(rng: &mut impl RNG) -> Result<Self, KeyMaterialError> {
         let mut key = Self::new();