pub struct HostExpectation { /* private fields */ }Expand description
Which program the client is willing to talk to, passed to
Client::connect_expecting.
The host must run as the client’s own user (always) and its executable, read from the kernel
for the connected socket’s process, must be one of the paths named here. Both sides of the
comparison are canonicalised when the check runs, so a symlink, a .. or a case difference on
a case-insensitive volume does not matter; the same file reached by another name (a hard link)
is the same executable.
An expectation with no path matches nothing: it fails closed.
The install-relative constructors (sibling_executable,
bundle_executable,
relative_to_current_exe) derive the host’s path from where
THIS process’s executable lives, so an engine shipped inside an app can name its app without a
hard-coded path. They inherit the trust of that location: see the README, “What this does not
do”.
Implementations§
Source§impl HostExpectation
impl HostExpectation
Sourcepub fn executable(path: impl Into<PathBuf>) -> Self
pub fn executable(path: impl Into<PathBuf>) -> Self
The host is the program at path.
Sourcepub fn any_of<I, P>(paths: I) -> Self
pub fn any_of<I, P>(paths: I) -> Self
The host is any one of paths (a release path and a QA path, say). Empty matches nothing.
Sourcepub fn or_executable(self, path: impl Into<PathBuf>) -> Self
pub fn or_executable(self, path: impl Into<PathBuf>) -> Self
Also accept the program at path.
Sourcepub fn sibling_executable(file_name: impl AsRef<OsStr>) -> Result<Self>
pub fn sibling_executable(file_name: impl AsRef<OsStr>) -> Result<Self>
The host is the executable file_name in the same directory as THIS process’s executable
(symlinks resolved first). Fails when the running executable cannot be located or
file_name is not a bare file name.
Sourcepub fn bundle_executable(file_name: impl AsRef<OsStr>) -> Result<Self>
pub fn bundle_executable(file_name: impl AsRef<OsStr>) -> Result<Self>
The host is the main executable file_name of the macOS app bundle that contains THIS
process’s executable: <App>.app/Contents/MacOS/<file_name>. For an engine or command
line tool shipped inside the app, whether it sits in Contents/Resources/bin or in
Contents/MacOS itself. Fails when the running executable is not inside an .app
directory or file_name is not a bare file name.
Sourcepub fn relative_to_current_exe(
levels_up: usize,
relative: impl AsRef<Path>,
) -> Result<Self>
pub fn relative_to_current_exe( levels_up: usize, relative: impl AsRef<Path>, ) -> Result<Self>
The host is relative under the directory levels_up levels above THIS process’s
executable (symlinks resolved first; 1 is the directory that holds it). For install
layouts that are neither a sibling nor a macOS bundle, for example
relative_to_current_exe(2, "bin/app") for <root>/libexec/engine and <root>/bin/app.
Sourcepub fn with_verifier(
self,
check: impl Fn(&HostProcess) -> Result<(), String> + Send + Sync + 'static,
) -> Self
pub fn with_verifier( self, check: impl Fn(&HostProcess) -> Result<(), String> + Send + Sync + 'static, ) -> Self
Add a check that runs AFTER the executable matched, with the host the OS identified. A
returned Err(reason) refuses the host as HostIdentityReason::Refused. The check runs
before the first application byte is written.
This is the hook for a stronger identity than a path. This crate links no code-signing API,
so the macOS team-identifier check is the caller’s: link Security.framework in the app,
build a SecCode for the host from HostProcess::audit_token with
SecCodeCopyGuestWithAttributes and kSecGuestAttributeAudit (never from the pid alone,
which can be reused), read kSecCodeInfoTeamIdentifier with SecCodeCopySigningInformation
and compare it with your own (SecCodeCopySelf). On Windows the same hook carries an
Authenticode (WinVerifyTrust) check of HostProcess::executable.
Sourcepub fn executables(&self) -> &[PathBuf]
pub fn executables(&self) -> &[PathBuf]
The executables this expectation names, as supplied.