Add readmes to all crates (#200)

In an effort to improve documentation for our public crates this PR adds
relevant boilerplate readmes to every crate and moves the disclaimer to
the workspace.

Uses `readme = "DISCLAIMER.md"` to configure which readme is shown on
crates.io. This allows us to use `README.md` for internal documentation.
The READMEs are also included in rustdoc in an effort to avoid
duplicating documentation.

Author: Hinton

Cargo.toml

@@ -13,6 +13,7 @@ rust-version = "1.75"
 homepage = "https://bitwarden.com"
 repository = "https://github.com/bitwarden/sdk-internal"
 license-file = "LICENSE"
+readme = "DISCLAIMER.md"
 keywords = ["bitwarden"]
 
 # Define dependencies that are expected to be consistent across all crates

DISCLAIMER.md

@@ -0,0 +1,4 @@
+This is an internal crate for the Bitwarden SDK. Do not depend on this directly and use the
+[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
+
+This crate does not follow semantic versioning and the public interface may change at any time.

crates/bitwarden-cli/Cargo.toml

@@ -8,6 +8,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+readme.workspace = true
 homepage.workspace = true
 repository.workspace = true
 license-file.workspace = true

crates/bitwarden-cli/README.md

@@ -1,6 +1,3 @@
 # Bitwarden Cli
 
-This is an internal crate for the Bitwarden SDK do not depend on this directly and use the
-[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
-
-This crate does not follow semantic versioning and the public interface may change at any time.
+Common utilities for the Bitwarden Password Manager CLI and Secrets Manager CLI.

crates/bitwarden-cli/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod color;
 
 pub use color::{install_color_eyre, Color};

crates/bitwarden-core/Cargo.toml

@@ -3,15 +3,16 @@ name = "bitwarden-core"
 description = """
 Internal crate for the bitwarden crate. Do not use.
 """
-keywords = ["bitwarden"]
 
 version.workspace = true
 authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+readme.workspace = true
 homepage.workspace = true
 repository.workspace = true
 license-file.workspace = true
+keywords.workspace = true
 
 [features]
 internal = ["dep:zxcvbn"]

crates/bitwarden-core/README.md

@@ -1,6 +1,7 @@
 # Bitwarden Core
 
-This is an internal crate for the Bitwarden SDK do not depend on this directly and use the
-[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
+Contains core functionality used by the feature crates.
 
-This crate does not follow semantic versioning and the public interface may change at any time.
+<div class="warning">
+Generally you should <b>not</b> find yourself needing to edit this crate! When possible, please use the feature crates instead.
+</div>

crates/bitwarden-core/src/lib.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 #[cfg(feature = "uniffi")]
 uniffi::setup_scaffolding!();
 #[cfg(feature = "uniffi")]

crates/bitwarden-crypto/Cargo.toml

@@ -8,6 +8,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+readme.workspace = true
 homepage.workspace = true
 repository.workspace = true
 license-file.workspace = true

crates/bitwarden-crypto/README.md

@@ -1,6 +1,60 @@
-# Bitwarden Crypto
+# Bitwarden Cryptographic primitives
 
-This is an internal crate for the Bitwarden SDK do not depend on this directly and use the
-[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
+This crate contains the cryptographic primitives used throughout the SDK. The general aspiration is
+for this crate to handle all the difficult cryptographic operations and expose higher level concepts
+to the rest of the SDK.
 
-This crate does not follow semantic versioning and the public interface may change at any time.
+<div class="warning">
+Generally you should <b>not</b> find yourself needing to edit this crate! Everything written
+here requires additional care and attention to ensure that the cryptographic primitives are
+secure.
+</div>
+
+## Example:
+
+```rust
+use bitwarden_crypto::{SymmetricCryptoKey, KeyEncryptable, KeyDecryptable, CryptoError};
+
+async fn example() -> Result<(), CryptoError> {
+  let key = SymmetricCryptoKey::generate(rand::thread_rng());
+
+  let data = "Hello, World!".to_owned();
+  let encrypted = data.clone().encrypt_with_key(&key)?;
+  let decrypted: String = encrypted.decrypt_with_key(&key)?;
+
+  assert_eq!(data, decrypted);
+  Ok(())
+}
+```
+
+## Development considerations
+
+This crate is expected to provide long term support for cryptographic operations. To that end, the
+following considerations should be taken into account when making changes to this crate:
+
+- Limit public interfaces to the bare minimum.
+- Breaking changes should be rare and well communicated.
+- Serializable representation of keys and encrypted data must be supported indefinitely as we have
+  no way to update all data.
+
+### Conventions:
+
+- Pure Functions that deterministically "derive" keys from input are prefixed with `derive_`.
+- Functions that generate non deterministically keys are prefixed with `make_`.
+
+### Differences from `clients`
+
+There are some noteworthy differences compared to the other Bitwarden
+[clients](https://github.com/bitwarden/clients). These changes are made in an effort to introduce
+conventions in how we name things, improve best practices and abstracting away internal complexity.
+
+- `CryptoService.makeSendKey` & `AccessService.createAccessToken` are replaced by the generic
+  `derive_shareable_key`
+- MasterKey operations such as `makeMasterKey` and `hashMasterKey` are moved to the MasterKey
+  struct.
+
+## Crate features
+
+- `no-memory-hardening` - Disables memory hardening which ensures that allocated memory is zeroed on
+  drop. This feature primarily exists in case you do not want to use the standard allocator, and we
+  advise to still define a `global_allocator` using the [`ZeroizingAllocator`].