feat: clone from https://github.com/miquels/webdav-server-rs

pam/README.md

@@ -0,0 +1,49 @@
+
+# pam-sandboxed
+
+### PAM authentication with the pam library running in a separate process.
+
+The PAM client in this crate creates a future that resolves with the
+PAM authentication result.
+
+### HOW.
+
+When initialized, the code fork()s and sets up a pipe-based communications
+channel between the parent (pam-client) and the child (pam-server). All
+the Pam work is then done on a threadpool in the child process.
+
+### WHY.
+
+Reasons for doing this instead of just calling libpam directly:
+
+- Debian still comes with pam 1.8, which when calling setuid helpers
+  will first close all filedescriptors up to the rlimit. if
+  If that limit is high (millions) then it takes a looong while.
+  `RLIMIT_NOFILE` is reset to a reasonably low number in the child process.
+- You might want to run the pam modules as a different user than
+  the main process
+- There is code in libpam that might call setreuid(), and that is an
+  absolute non-starter in threaded code.
+- Also, if you're mucking around with per-thread uid credentials on Linux by
+  calling the setresuid syscall directly, the pthread library code that
+  handles setuid() gets confused.
+
+### EXAMPLE.
+```rust
+// call this once.
+let mut pam = PamAuth::new(None).expect("failed to initialized PAM");
+
+// now use `pam` as a handle to authenticate.
+let fut = pam.auth("other", "user", "pass", None)
+    .then(|res| {
+        println!("pam auth result: {:?}", res);
+        res
+    });
+tokio::spawn(fut.map_err(|_| ()));
+```
+
+### Copyright and License.
+
+ * © 2018, 2019 XS4ALL Internet bv
+ * © 2018, 2019 Miquel van Smoorenburg
+ * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)