Feature/officialfrancismendoza/49 no std default

.github/workflows/publish_doc_benches_to_ghpages.yaml

@@ -37,21 +37,22 @@ jobs:
         with:
           name: code_quality_stats
           path: ./code_stats.txt
-  run_benches:
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-      - run: cargo bench --all
-      - name: Save artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: bc-rust-benches
-          path: ./target/criterion
+  # the benches run crazy slow on the github agent. So there's really no point because it's not useful data.
+  # run_benches:
+  #   runs-on: ubuntu-latest
+  #   if: github.ref == 'refs/heads/main'
+  #   steps:
+  #     - name: Checkout code
+  #       uses: actions/checkout@v4
+  #     - run: cargo bench --all
+  #     - name: Save artifacts
+  #       uses: actions/upload-artifact@v4
+  #       with:
+  #         name: bc-rust-benches
+  #         path: ./target/criterion
   collect_ghpages:
     if: github.ref == 'refs/heads/main'
-    needs: [build_docs, code_stats, run_benches]
+    needs: [build_docs, code_stats]
     runs-on: ubuntu-latest
     steps:
       - run: mkdir ./gh-pages
@@ -65,11 +66,11 @@ jobs:
         with:
           name: code_quality_stats
           path: ./gh-pages/
-      - name: Get benches from previous job
-        uses: actions/download-artifact@v4
-        with:
-          name: bc-rust-benches
-          path: ./gh-pages/benches
+      # - name: Get benches from previous job
+      #   uses: actions/download-artifact@v4
+      #   with:
+      #     name: bc-rust-benches
+      #     path: ./gh-pages/benches
       - name: Archive Compatibility Matrix For Download
         uses:  actions/upload-pages-artifact@v3
         with:

.github/workflows/rust-style.yml

@@ -0,0 +1,28 @@
+name: Rust Style
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: rust-style-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rustfmt:
+    if: github.repository == 'bcgit/bc-rust'
+    name: rustfmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install nightly rustfmt
+        run: |
+          rustup toolchain install nightly --profile minimal --component rustfmt
+          rustup override set nightly
+
+      - name: Check formatting
+        run: cargo fmt --all --check

CONTRIBUTING.md

@@ -20,6 +20,23 @@ 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.
 
+## 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.
+
+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.
+
 ## 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). 
@@ -56,5 +73,5 @@ Don't forget to self-review. Please follow these simple guidelines:
 
 #### Your pull request is merged
 
-For acceptance, pull requests need to meet specific quality criteria, including tests for anything substantial. 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.
 

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = [ "cli", "crypto/*", "mem_usage_benches" ]
+members = ["cli", "crypto/*", "mem_usage_benches"]
 
 [workspace.package]
 edition = "2024"
@@ -8,21 +8,24 @@ edition = "2024"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./", version = "0.1.1" }
-bouncycastle-base64 = { path = "./crypto/base64", version = "0.1.1"}
-bouncycastle-core = { path = "crypto/core", version = "0.1.1" }
-bouncycastle-core-test-framework = { path = "./crypto/core-test-framework", version = "0.1.1"}
-bouncycastle-factory = { path = "./crypto/factory", version = "0.1.1"}
+bouncycastle-base64 = { path = "./crypto/base64", version = "0.1.1" }
+# `default-features = false` here (rather than on each member) is required so that individual
+# crates can opt out of the `alloc` feature for `no_std` builds; members re-enable it through
+# their own `alloc` feature. Building the whole workspace keeps `alloc` on via feature unification.
+bouncycastle-core = { path = "crypto/core", version = "0.1.1", default-features = false }
+bouncycastle-core-test-framework = { path = "./crypto/core-test-framework", version = "0.1.1" }
+bouncycastle-factory = { path = "./crypto/factory", version = "0.1.1" }
 bouncycastle-hex = { path = "./crypto/hex", version = "0.1.1" }
-bouncycastle-hkdf = { path = "./crypto/hkdf", version = "0.1.1"}
-bouncycastle-hmac = { path = "./crypto/hmac", version = "0.1.1"}
+bouncycastle-hkdf = { path = "./crypto/hkdf", version = "0.1.1" }
+bouncycastle-hmac = { path = "./crypto/hmac", version = "0.1.1", default-features = false }
 bouncycastle-mlkem = { path = "./crypto/mlkem", version = "0.1.2" }
-bouncycastle-mlkem-lowmemory = { path = "./crypto/mlkem_lowmemory", version = "0.1.2" }
+bouncycastle-mlkem-lowmemory = { path = "./crypto/mlkem-lowmemory", version = "0.1.2" }
 bouncycastle-mldsa = { path = "./crypto/mldsa", version = "0.1.2" }
-bouncycastle-mldsa-lowmemory = { path = "./crypto/mldsa_lowmemory", version = "0.1.2" }
+bouncycastle-mldsa-lowmemory = { path = "./crypto/mldsa-lowmemory", version = "0.1.2" }
 bouncycastle-rng = { path = "./crypto/rng", version = "0.1.1" }
-bouncycastle-sha2 = { path = "./crypto/sha2", version = "0.1.1"}
-bouncycastle-sha3 = { path = "./crypto/sha3", version = "0.1.1"}
-bouncycastle-utils = { path = "./crypto/utils", version = "0.1.1"}
+bouncycastle-sha2 = { path = "./crypto/sha2", version = "0.1.1", default-features = false }
+bouncycastle-sha3 = { path = "./crypto/sha3", version = "0.1.1", default-features = false }
+bouncycastle-utils = { path = "./crypto/utils", version = "0.1.1" }
 
 
 # *** External Dependencies ***
@@ -39,17 +42,20 @@ name = "bouncycastle"
 version = "0.1.2"
 edition.workspace = true
 
+# The umbrella crate re-exports the whole library for downstream users who want everything in one
+# dependency, so it enables `alloc` on the primitive crates whose workspace deps default it off.
+# (base64/hex/hkdf/rng/factory already default `alloc` on.)
 [dependencies]
 bouncycastle-base64.workspace = true
-bouncycastle-core.workspace = true
+bouncycastle-core = { workspace = true, features = ["alloc"] }
 bouncycastle-factory.workspace = true
 bouncycastle-hex.workspace = true
 bouncycastle-hkdf.workspace = true
-bouncycastle-hmac.workspace = true
+bouncycastle-hmac = { workspace = true, features = ["alloc"] }
 bouncycastle-mldsa.workspace = true
 bouncycastle-mldsa-lowmemory.workspace = true
 bouncycastle-mlkem.workspace = true
 bouncycastle-mlkem-lowmemory.workspace = true
 bouncycastle-rng.workspace = true
-bouncycastle-sha2.workspace = true
-bouncycastle-sha3.workspace = true
+bouncycastle-sha2 = { workspace = true, features = ["alloc"] }
+bouncycastle-sha3 = { workspace = true, features = ["alloc"] }

INTRODUCTION.md

@@ -123,7 +123,7 @@ While the `KeyMaterial` is fundamentally just a buffer of bytes, it tracks many
 
 The `KeyMaterial` object is used consistently across the library and any functions that manipulate a key material object will properly update the metadata to track any changes made to the key's entropy or security strength. For example, a `KeyMaterial512{ key_type: MACKey, security_strength: _256bit}` will have its security strength downgraded to 128 bit if you pass it through a SHA256-based KDF, indicating that it is no longer sufficient to generate a full-strength AES256 or ML-DSA-87.  
 
-Of course, there will always be things developers need to do that the library did not provide a utility function for, for example, you may actually need an all-zero MACKey in order to implement certain standardized MAC algorithms. To the end, the library will allow you to, for example, force a key type to any full-entropy key type and security strength, or even get a direct immutable or mutable reference to the underlying buffer via `.ref_to_bytes()` and `mut_ref_to_bytes()`, but only with use of the `allow_hazardous_operations` flag:
+Of course, there will always be things developers need to do that the library did not provide a utility function for, for example, you may actually need an all-zero MACKey in order to implement certain standardized MAC algorithms. To the end, the library will allow you to, for example, force a key type to any full-entropy key type and security strength, or even get a direct immutable or mutable reference to the underlying buffer via `.ref_to_bytes()` and `ref_to_bytes_mut()`, but only with use of the `allow_hazardous_operations` flag:
 
 ```rust
 key.allow_hazardous_operations();
@@ -202,4 +202,4 @@ As this is an alpha release, we're eagerly looking for feedback from the communi
 You can reach us at <some email address>
 
 Sincerely,
-Mike Ounsworth (lead maintainer of BC-Rust), on behalf of the Legion of the Bouncy Castle and the entire Bouncy Castle community
+Mike Ounsworth (lead maintainer of BC-Rust), on behalf of the Legion of the Bouncy Castle and the entire Bouncy Castle community