Prepping Cargo.toml and updating docs for version bump to 0.6.0

.github/workflows/clippy.yml

@@ -22,6 +22,8 @@ jobs:
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Install Rust toolchain 
         uses: dtolnay/rust-toolchain@stable

rust-symcrypt/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "symcrypt"
-authors = ["nnmkhang"]
-version = "0.5.1"
+authors = ["Microsoft"]
+version = "0.6.0"
 license = "MIT OR Apache-2.0"
 description = "Friendly and Idiomatic Wrappers for SymCrypt"
 edition.workspace = true
@@ -15,7 +15,7 @@ readme = "README.md"
 [dependencies]
 # uses '../symcrypt-sys' when compiled locally, and uses
 # crates.io versioning when published
-symcrypt-sys = {path = "../symcrypt-sys", version = "0.4.0"}
+symcrypt-sys = {path = "../symcrypt-sys", version = "0.5.0"}
 libc = "0.2.0"
 lazy_static = "1.4.0"
 

rust-symcrypt/INSTALL.md

@@ -1,48 +1,42 @@
-# Detailed Build and Install
+# Detailed Build and Install for Dynamic Linking
 
-This page provides more detailed installation instructions
+This page provides more detailed installation instructions for dynamic linking on Windows and Linux.
 
-## Installation
-For ease of use, the recommended usage is to obtain these binaries from the official SymCrypt [Repo](https://github.com/microsoft/SymCrypt/releases/tag/v103.4.2).
+The `symcrypt` crate is a wrapper on top of the `SymCrypt` library, and requires access to the `SymCrypt` library during the build and execution stage for dynamic linking. For ease of use, the recommended way to configure your `SymCrypt` library dependancy is to obtain the required binaries from the official [SymCrypt Repo](https://github.com/microsoft/SymCrypt/releases/tag/v103.8.0).
 
-**Note:** If you wish to build your own version please follow the [Build Instructions](https://github.com/microsoft/SymCrypt/blob/main/BUILD.md) that are provided by SymCrypt to install SymCrypt for your target architecture.
-
-Once SymCrypt is installed on your machine, we must configure your machine so that the SymCrypt crate's build script can easily find `symcrypt.dll` and `symcrypt.lib` which are needed on Windows, or the `libsymcrypt.so*` files which are needed for Linux. 
+However, If you wish to build your own version of the underlying `SymCrypt` library please follow the [Build Instructions](https://github.com/microsoft/SymCrypt/blob/main/BUILD.md) that are provided by SymCrypt to install SymCrypt for your target architecture.
 
 ### Windows Install 
 
-The `symcrypt.lib` can be found in the the following path after SymCrypt has been downloaded and unzipped.
+The `symcrypt.lib` can be found in the the following path after `SymCrypt` has been downloaded and unzipped.
 
 `C:\Your-Path-To-SymCrypt-Release-Download\dll\`
 
-The SymCrypt crate needs to link against the SymCrypt import library during build.
+The SymCrypt crate needs to link against the `SymCrypt` import library during build.
 
 To do so you must set the `SYMCRYPT_LIB_PATH` environment variable. You can do this by using the following command:
 
 `setx SYMCRYPT_LIB_PATH "<your-path-to-symcrypt-lib-folder>"`
-
 The `symcrypt.dll` can be found in the the following path after SymCrypt has been downloaded and unzipped.
-
 `C:\Your-Path-To-SymCrypt-Release-Download\dll\`
-
 During runtime, Windows will handle finding all needed `dll`'s in order to run the intended program, this includes our `symcrypt.dll` file. The places Windows will look are:
-
 1. The folder from which the application loaded.
 2. The system folder. Use the `GetSystemDirectory` function to retrieve the path of this folder.
 3. The Windows folder. Use the `GetWindowsDirectory` function to get the path of this folder.
 4. The current folder.
 5. The directories listed in the PATH environment variable.
-
 For more info please see: [Dynamic-link library search order](https://learn.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order)
-
 Here are 2 recommended options to ensure your `symcrypt.dll` is found by Windows during runtime.
-
 1. Put the `symcrypt.dll` in the same folder as your output `.exe` file. If you are doing development (not release), the common path will be: `C:\your-project\target\debug\`.
 2. Permanently add the `symcrypt.dll` path into your System PATH environment variable. Doing this will ensure that any project that uses the SymCrypt crate will be able to access `symcrypt.lib`
 
+**NOTE:** By setting the `SYMCRYPT_LIB_PATH` via `setx SYMCRYPT_LIB_PATH "<your-path-to-symcrypt-lib-folder>"`; `symcrypt.dll` will already be on the `PATH` and you will not have to do any additional configuration for your program.
+
 ### Linux Install
 
+Though the artifacts on the [SymCrypt Repo](https://github.com/microsoft/SymCrypt/releases/tag/v103.8.0). Have been built with `Ubuntu` in mind, the `SymCrypt` library has been built with very few standard library dependencies and should work on most Linux distributions. 
+
 After installing and unzipping SymCrypt on a Linux distro, the required `libsymcrypt.so*` files can be found in the following path:
 `~/Your-Path-To-SymCrypt-Release-Download/lib/`
 
-The symcrypt crate needs to be able to link with these libs during build/run time. In order to mimic the installation path for other libraries, you must place the `libsymcrypt.so*` files into linker load path. The way that this is set will vary between distros. On most distros it set via the environment variable `$LD_LIBRARY_PATH`.
+The `symcrypt` crate needs to be able to link with these libs during build/run time. In order to mimic the installation path for other libraries, you must place the `libsymcrypt.so*` files into linker load path. The way that this is set will vary between distros. On most distros it set via the environment variable `$LD_LIBRARY_PATH`.

rust-symcrypt/README.md

@@ -1,21 +1,23 @@
 # SymCrypt Rust Wrapper
-
 This crate provides friendly and idiomatic Rust wrappers over [SymCrypt](https://github.com/microsoft/SymCrypt), an open-source cryptographic library.
 
 This crate has a dependency on `symcrypt-sys`, which utilizes `bindgen` to create Rust/C FFI bindings.
 
-**`symcrypt` version `0.5.1` is based off of `SymCrypt v103.4.2`.**. You must use a version that is greater than or equal to `SymCrypt v103.4.2`. 
+**`symcrypt` version `0.6.0` is based off of `SymCrypt v103.8.0`.** You must use a version that is greater than or equal to `SymCrypt v103.8.0`. 
 
 To view a detailed list of changes please see the [releases page](https://github.com/microsoft/rust-symcrypt/releases/).
 
 
 ### Supported Configurations
+| Operating Environment | Architecture      | Dynamic Linking | Static Linking |
+| --------------------- | ----------------- | --------------- | -------------- |
+| Windows user mode     | AMD64, ARM64      | ✅              | ✅  ⚠️       |
+| Ubuntu                | AMD64, ARM64      | ✅              | ✅  ⚠️       |
+| Azure Linux 3         | AMD64, ARM64      | ✅              | ✅  ⚠️       |
+
+**Note:** ⚠️ Static linking is meant to be used for rapid development and testing. Static linking does not offer FIPS and is **not to be used in Microsoft production or release builds.** For more information please see the `Quick Start Guide` below. 
 
-| Operating Environment | Architecture      | Dynamic Linking |
-| --------------------- | ----------------- | ----------- |
-| Windows user mode     | AMD64, ARM64      | ✅          | 
-| Ubuntu       | AMD64, ARM64      | ✅          | 
-| Azure Linux 3         | AMD64, ARM64      | ✅          |
+---
 
 ## Supported APIs
 
@@ -62,69 +64,88 @@ To enable either `Md5` or `Sha1`, or `Pkcs1 Encrypt/Decrypt` pass the `md5` or `
 
 ---
 
-
 ## Quick Start Guide
 
-`symcrypt` requires the `SymCrypt` library to be present at both build time and run time.
+As of version `0.6.0`,  the `symcrypt` crate can take advantage of both static and dynamic linking. Static linking is enabled by default.
+
+---
+## Static Linking:
+
+**NOTE: Static linking should not be used in production and or release builds for Microsoft 1st Party. If you are Microsoft employee please contact the SymCrypt team for more info.**
+
+Static linking works by building the `SymCrypt` library from source and static linking to lib that is produced, this will result in longer build times and larger binaries but gives the added benefit of not worrying about the distribution of a dynamic library. Static linking is enabled by default.
+---
+
+## Dynamic Linking:
+
+Dynamic linking assumes is required for FIPS. If the `dynamic` flag is set, the `symcrypt` crate will operate under the assumption that you have followed following instructions for configuring your system to do a dynamic link of the `SymCrypt` library. 
+
+```cargo
+[dependencies]
+symcrypt = {vesrion = "0.6.0", features = ["dynamic"]}
+hex = "0.4.3"
+``` 
 
 ### Windows:
 Download the latest `symcrypt.dll` and `symcrypt.lib` for your corresponding CPU architecture from the [SymCrypt Releases Page](https://github.com/microsoft/SymCrypt/releases) and place them somewhere accessible on your machine.
 
 Set the required `SYMCRYPT_LIB_PATH` environment variable. You can do this by using the following command:
-
 `setx SYMCRYPT_LIB_PATH "<your-path-to-symcrypt-lib-folder>"`
 
 You will need to restart `terminal` / `cmd` after setting the environment variable.
 
-For more information please see the `INSTALL.md` file on the [`rust-symcrypt`](https://github.com/microsoft/rust-symcrypt/tree/main/rust-symcrypt) page.
+For more information please see `INSTALL.md`.
 
 ### Linux:
 
 #### Azure Linux 3:
 SymCrypt is pre-installed on Azure Linux 3 machines. Please ensure that you have the most up to date version of SymCrypt by updating via `tdnf`.
 
-
 #### Other distros:
 
-For Ubuntu, you can install SymCrypt via package manager by connecting to PMC. 
-
-1. [Connect to PMC](https://learn.microsoft.com/en-us/linux/packages)
-2. `sudo apt-get install symcrypt`
+For Ubuntu, you can install SymCrypt via package manager by connecting to PMC ( Example shown for Ubuntu `24.04` ):
 
-Alternatively, you can manually install the lib files: 
+1. `curl -sSL -O https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb` 
+2. `sudo dpkg -i packages-microsoft-prod.deb`
+3. `sudo apt-get update`
+4. `sudo apt-get install symcrypt`
 
-Download the latest `libsymcrypt.so*` files for your corresponding CPU architecture from the [SymCrypt Releases Page](https://github.com/microsoft/SymCrypt/releases) and place them in your machines `$LD_LIBRARY_PATH`.
+For more info on connecting to PMC please see: [Connecting to PMC](https://learn.microsoft.com/en-us/linux/packages) 
 
-For more information please see the `INSTALL.md` file on the [`rust-symcrypt`](https://github.com/microsoft/rust-symcrypt/tree/main/rust-symcrypt) page
-
-**Note:** This path may be different depending on your flavour of Linux, and architecture. The goal is to place the `libsymcrypt.so*` files in a location where the your Linux distro can find the required libs at build/run time.
+If you want to try connecting with another flavour of Linux, or for more info please see `INSTALL.md`
 
 ---
 
 ## Usage
 There are unit tests attached to each file that show how to use each function. Included is some sample code to do a stateless Sha256 hash. 
-
 **Note:** This code snippet also uses the [hex](https://crates.io/crates/hex) crate.
 
 ### Instructions:  
 
-add symcrypt to your `Cargo.toml` file.
+Add symcrypt to your `Cargo.toml` file.
+
+If static linking:
+```cargo
+[dependencies]
+symcrypt = {vesrion = "0.6.0"}
+hex = "0.4.3"
+```
 
+
+If dynamic linking:
 ```cargo
 [dependencies]
-symcrypt = "0.5.1"
+symcrypt = {vesrion = "0.6.0", features = ["dynamic"]}
 hex = "0.4.3"
 ```
 
-include symcrypt in your code  
+Include symcrypt in your code  
 
 ```rust
 use symcrypt::hash::sha256; 
 use hex;
-
 let data = hex::decode("641ec2cf711e").unwrap();
 let expected: &str = "cfdbd6c9acf9842ce04e8e6a0421838f858559cf22d2ea8a38bd07d5e4692233";
-
 let result = sha256(&data);
 assert_eq!(hex::encode(result), expected);
 ```

symcrypt-sys/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "symcrypt-sys"
 authors = ["Microsoft"]
-version = "0.4.0"
+version = "0.5.0"
 license = "MIT OR Apache-2.0"
 description = "Rust/C Bindings for SymCrypt"
 edition.workspace = true

symcrypt-sys/README.md

@@ -20,7 +20,7 @@ You must also configure your system to pick up the SymCrypt lib on your machine,
 
 In your `Cargo.toml`
 ```Rust
-symcrypt-sys = "0.4.0"
+symcrypt-sys = "0.5.0"
 ```
 Then you can call the underlying SymCrypt code directly via the FFIs.
 ```Rust

symcrypt-sys/build/static_link.rs

@@ -15,12 +15,17 @@ pub fn compile_and_link_symcrypt() -> std::io::Result<()> {
     let options = SymCryptOptions::new();
     println!("Build config: {:?}", options);
 
+    // Rebuild if any of these files change
+    println!("cargo:rerun-if-changed=../symcrypt/lib/");
+    println!("cargo:rerun-if-changed=../symcrypt/inc/");
+    println!("cargo:rerun-if-changed=../inc/");
+
     // Required Windows bcrypt dependency for BCryptGenRandom
     const ADDITIONAL_DEPENDENCIES: &[&str] = &[
         #[cfg(windows)]
         "bcrypt",
     ];
-    println!("cargo:rerun-if-changed=upstream");
+
     println!("Compiling SymCrypt...");
 
     // Compile and Build SymCrypt with provided SymCryptOptions