Update documentation

Update bundled documentation and include macos support

Signed-off-by: William Brown <[email protected]>

Author: uglyoldbob

tss-esapi-sys/Cargo.toml

@@ -22,7 +22,7 @@ cfg-if = "1.0.0"
 semver = "1.0.7"
 
 [target.'cfg(windows)'.build-dependencies]
-msbuild = { git = "https://github.com/uglyoldbob/msbuild.git", optional = true }
+msbuild = { version = "0.1.0", optional = true }
 winreg = {version = "0.52", optional = true }
 
 [features]

tss-esapi-sys/README.md

@@ -13,12 +13,12 @@ interface to Rust to [TSS](https://github.com/tpm2-software/tpm2-tss).
 
 This crate exposes an interface for the TSS Enhanced System API and thus
 links to libraries that expose this interface. In order to allow proper use
-of the ESAPI, this FFI layer includes bindings to TCTI and MU headers, and 
+of the ESAPI, this FFI layer includes bindings to TCTI and MU headers, and
 must therefore link to all of them at build time.
 
 The paths to the libraries are discovered using `pkg-config` - make sure they
-are discoverable in this way on your system. Our build script looks for 
-`tss2-esys`, `tss2-tctildr` and `tss2-mu`. A minimum version of `3.2.2` is 
+are discoverable in this way on your system. Our build script looks for
+`tss2-esys`, `tss2-tctildr` and `tss2-mu`. A minimum version of `3.2.2` is
 required for all of them.
 
 Having installed the open-source implementation libraries at `/usr/local/lib` (by default), it
@@ -41,9 +41,62 @@ available, feel free to raise a Pull Request to add it or to use build-time
 generation of bindings. All the committed bindings **MUST** be generated from
 the library version found under the `vendor` submodule.
 
+## Bundling TPM-TSS
+
+tpm-tss is used by this library to communicate with TPMs. If this library
+is not available on your system you may optionally bundle (vendor) tpm-tss
+during builds. tpm-tss can be provided from a local source path with the
+environment variable `TPM_TSS_SOURCE_PATH` or it will be retrieved from
+github during the build.
+
+To enable this feature:
+
+```bash
+cargo build --features=bundled
+```
+
+```bash
+TPM_TSS_SOURCE_PATH=/path/to/tpm-tss cargo build --features=bundled
+```
+
+If using this feature from an external project
+
+```
+tss-esapi-sys = { version = "...", features = "bundled" }
+```
+
+### Windows
+
+Compiling for windows requires a bit of setup to work with the bundled feature.
+
+* Openssl must be installed to a non-standard location at C:\OpenSSL-v11-Win64
+* Visual studio 2017 must be installed with the Clang/C2 experimental component,
+and windows sdk 10.0.17134.0.
+
+### MacOS
+
+Compiling on MacOS requires the bundling feature. This requires dependencies
+from brew.
+
+```bashbre
+brew install autoconf autoconf-archive automake json-c libtool m4 pkg-config
+```
+
+Optionally you may require these libraries for certain classes of TPM transport
+
+```
+brew install libftdi
+```
+
+### OpenSUSE / SUSE
+
+```
+sudo zypper in autoconf autoconf-archive automake libjson-c-devel libtool libtpms-devel gawk make
+```
+
 ## Cross compiling
 
-Cross-compilation can be done as long as you have on your build system the TSS 
+Cross-compilation can be done as long as you have on your build system the TSS
 libraries compiled for your target system of choice. We rely on `pkg-config` to
 identify the libraries which we link against. Installing `tpm2-tss` does yield
 `.pc` files which can be used for this purpose, but depending on the exact build

tss-esapi-sys/build.rs

@@ -43,6 +43,7 @@ pub mod target {
         match (target.architecture, target.operating_system) {
             (Architecture::Arm(_), OperatingSystem::Linux)
             | (Architecture::Aarch64(_), OperatingSystem::Linux)
+            | (Architecture::Aarch64(_), OperatingSystem::Darwin)
             | (Architecture::X86_64, OperatingSystem::Darwin)
             | (Architecture::X86_64, OperatingSystem::Linux) => {}
             (arch, os) => {
@@ -77,15 +78,20 @@ pub mod tpm2_tss {
     }
 
     impl Installation {
+        /// Return an optional list of clang arguments that are platform specific
+        #[cfg(feature = "bundled")]
         fn platform_args() -> Option<Vec<String>> {
             cfg_if::cfg_if! {
                 if #[cfg(windows)] {
                     let mut clang_args: Vec<String> = Vec::new();
                     let hklm = winreg::RegKey::predef(winreg::enums::HKEY_LOCAL_MACHINE);
+                    // Find the windows sdk path from the windows registry
                     let sdk_entry = hklm.open_subkey("SOFTWARE\\WOW6432Node\\Microsoft\\Microsoft SDKs\\Windows\\v10.0").unwrap();
+                    // add relevant paths to get to the windows 10.0.17134.0 sdk, which tpm2-tss uses on windows.
                     let installation_path: String = sdk_entry.get_value("InstallationFolder").unwrap();
                     let ip_pb = PathBuf::from(installation_path).join("Include");
                     let windows_sdk = ip_pb.join("10.0.17134.0");
+                    // Add paths required for bindgen to find all required headers
                     clang_args.push(format!("-I{}", windows_sdk.join("ucrt").display()));
                     clang_args.push(format!("-I{}", windows_sdk.join("um").display()));
                     clang_args.push(format!("-I{}", windows_sdk.join("shared").display()));
@@ -125,32 +131,63 @@ pub mod tpm2_tss {
             repo_path
         }
 
-        #[cfg(feature = "bundled")]
+        #[cfg(all(feature = "bundled", not(windows)))]
         fn compile_with_autotools(p: PathBuf) -> PathBuf {
             let output1 = std::process::Command::new("./bootstrap")
                 .current_dir(&p)
                 .output()
                 .expect("bootstrap script failed");
             let status = output1.status;
             if !status.success() {
-                panic!("bootstrap script failed with {}:\n{:?}", status, output1);
+                panic!(
+                    "{:?}/bootstrap script failed with {}:\n{:?}",
+                    p, status, output1
+                );
             }
 
             let mut config = autotools::Config::new(p);
-            config.fast_build(true).reconf("-ivf").build()
+            config
+                // Force configuration of the autotools env
+                .reconf("-fiv")
+                // skip ./configure if no parameter changes are made
+                .fast_build(true)
+                .enable("esys", None)
+                // Disable fapi as we only use esys
+                .disable("fapi", None)
+                .disable("fapi-async-tests", None)
+                // Disable integration tests
+                .disable("integration", None)
+                // Don't allow weak crypto
+                .disable("weakcrypto", None)
+                .build()
         }
 
         #[cfg(feature = "bundled")]
         /// Uses a bundled build for an installation
         pub fn bundled() -> Self {
             use std::io::Write;
             let out_path = std::env::var("OUT_DIR").expect("No output directory given");
-            let source_path = Self::fetch_source(
-                out_path,
-                "tpm2-tss",
-                "https://github.com/tpm2-software/tpm2-tss.git",
-                MINIMUM_VERSION,
-            );
+            let source_path = if let Ok(tpm_tss_source) = std::env::var("TPM_TSS_SOURCE_PATH") {
+                eprintln!("using local tpm2-tss from {}", tpm_tss_source);
+                let Ok(source_path) = PathBuf::from(tpm_tss_source).canonicalize() else {
+                    panic!(
+                        "Unable to canonicalize tpm2-tss source path. Does the source path exist?"
+                    );
+                };
+
+                source_path
+            } else {
+                eprintln!(
+                    "using remote tpm2-tss from https://github.com/tpm2-software/tpm2-tss.git"
+                );
+                Self::fetch_source(
+                    out_path,
+                    "tpm2-tss",
+                    "https://github.com/tpm2-software/tpm2-tss.git",
+                    MINIMUM_VERSION,
+                )
+            };
+
             let version_file_name = source_path.join("VERSION");
             let mut version_file = std::fs::File::create(version_file_name)
                 .expect("Unable to create version file for tpm2-tss");
@@ -298,11 +335,14 @@ pub mod tpm2_tss {
                             .clang_arg(tss2_tcti_tbs.include_dir_arg())
                             .header(tss2_tcti_tbs.header_file_arg());
                     }
+
+                    #[cfg(feature = "bundled")]
                     if let Some(clang_args) = Self::platform_args() {
                         for arg in clang_args {
                             builder = builder.clang_arg(arg);
                         }
                     }
+
                     builder
                 }
             }
@@ -332,7 +372,7 @@ pub mod tpm2_tss {
                 let build_string = match profile.as_str() {
                     "debug" => "Debug",
                     "release" => "Release",
-                    _ => panic!("Unknown cargo profile:"),
+                    _ => panic!("Unknown cargo profile: {}", profile),
                 };
                 let mut source_path = self
                     .tss2_esys
@@ -342,7 +382,6 @@ pub mod tpm2_tss {
                 source_path.pop();
                 source_path.pop();
                 source_path.pop();
-                println!("Source path is {}", source_path.display());
                 println!(
                     "cargo:rustc-link-search=dylib={}",
                     source_path.join("x64").join(build_string).display()

tss-esapi/README.md

@@ -17,6 +17,10 @@ time using the headers identified on the system.
 
 Our end-goal is to achieve a fully Rust-native interface that offers strong safety and security guarantees. Check out our [documentation](https://docs.rs/tss-esapi/*/tss_esapi/#notes-on-code-safety) for an overview of our code safety approach.
 
+## Integration Tests
+
+See the [integration tests](https://github.com/parallaxsecond/rust-tss-esapi/tree/main/tss-esapi/tests)
+
 ## Cargo Features
 
 The crate currently offers the following features: