Struct PolicyBuilder 

pub struct PolicyBuilder { /* private fields */ }

A builder for conveniently defining a policy.

It is highly recommended to use the Self::new() (default) value to create a policy with all options enabled, because each platform acts differently when being requested to enable/disable various authentication methods. Enabling all options is the safest way to ensure that the authentication prompt will be displayed correctly on all platforms.

On Linux, at least one polkit action ID MUST be explicitly provided. If not set (or empty), build() will return None.

Implementations

impl PolicyBuilder

pub const fn new() -> Self

Returns a new policy with sane defaults.

Examples found in repository

examples/simple_authentication.rs (line 54)

fn main() {
    let context = Context::new(());
    let mut policy = PolicyBuilder::new()
        // On Linux You need to set action_ids.
        // See: ./org.robius.authentication.policy file settings and (README: "Usage on Linux").
        .action_ids([
            "org.robius.authentication",
            "org.robius.authentication.settings",
        ])
        .biometrics(Some(BiometricStrength::Strong))
        .password(true)
        .companion(true)
        .build()
        .unwrap();

    if let Err(e) = policy.set_action_id("org.robius.authentication.settings") {
        eprintln!("Invalid action_id: {:?}", e);
        return;
    }

    let (tx, rx) = mpsc::channel();

    // Start authentication. `res` only indicates whether the request was successfully
    // initiated; the final result is delivered via the callback.
    let res = context.authenticate(TEXT, &policy, move |result| {
        let _ = tx.send(result);
    });

    if let Err(e) = res {
        eprintln!("Failed to start authentication: {:?}", e);
        return;
    }

    // Block until the callback produces a result.
    match rx.recv() {
        Ok(Ok(_)) => println!("Authentication successful"),
        Ok(Err(e)) => println!("Authentication failed: {:?}", e),
        Err(e) => eprintln!("Failed to receive auth result: {:?}", e),
    }
}

pub fn action_ids<I, S>(self, ids: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Sets the list of action identifiers that require authorization.

On Linux systems, these map to polkit action_ids, which represent specific privileged operations (such as modifying system settings or powering off the device). The authentication backend uses the current action ID to determine whether the action is permitted and whether user authentication is required.

The first entry is used as the default action ID. To switch between multiple action IDs at runtime on Linux, build a policy once and call Policy::set_action_id before each authentication. The setter validates against this list.

This only has an effect on linux.

Examples found in repository

examples/simple_authentication.rs (lines 57-60)

fn main() {
    let context = Context::new(());
    let mut policy = PolicyBuilder::new()
        // On Linux You need to set action_ids.
        // See: ./org.robius.authentication.policy file settings and (README: "Usage on Linux").
        .action_ids([
            "org.robius.authentication",
            "org.robius.authentication.settings",
        ])
        .biometrics(Some(BiometricStrength::Strong))
        .password(true)
        .companion(true)
        .build()
        .unwrap();

    if let Err(e) = policy.set_action_id("org.robius.authentication.settings") {
        eprintln!("Invalid action_id: {:?}", e);
        return;
    }

    let (tx, rx) = mpsc::channel();

    // Start authentication. `res` only indicates whether the request was successfully
    // initiated; the final result is delivered via the callback.
    let res = context.authenticate(TEXT, &policy, move |result| {
        let _ = tx.send(result);
    });

    if let Err(e) = res {
        eprintln!("Failed to start authentication: {:?}", e);
        return;
    }

    // Block until the callback produces a result.
    match rx.recv() {
        Ok(Ok(_)) => println!("Authentication successful"),
        Ok(Err(e)) => println!("Authentication failed: {:?}", e),
        Err(e) => eprintln!("Failed to receive auth result: {:?}", e),
    }
}

pub fn biometrics(self, strength: Option<BiometricStrength>) -> Self

Configures biometric authentication with the given strength.

The strength only has an effect on Android, see BiometricStrength for more details.

Examples found in repository

examples/simple_authentication.rs (line 61)

fn main() {
    let context = Context::new(());
    let mut policy = PolicyBuilder::new()
        // On Linux You need to set action_ids.
        // See: ./org.robius.authentication.policy file settings and (README: "Usage on Linux").
        .action_ids([
            "org.robius.authentication",
            "org.robius.authentication.settings",
        ])
        .biometrics(Some(BiometricStrength::Strong))
        .password(true)
        .companion(true)
        .build()
        .unwrap();

    if let Err(e) = policy.set_action_id("org.robius.authentication.settings") {
        eprintln!("Invalid action_id: {:?}", e);
        return;
    }

    let (tx, rx) = mpsc::channel();

    // Start authentication. `res` only indicates whether the request was successfully
    // initiated; the final result is delivered via the callback.
    let res = context.authenticate(TEXT, &policy, move |result| {
        let _ = tx.send(result);
    });

    if let Err(e) = res {
        eprintln!("Failed to start authentication: {:?}", e);
        return;
    }

    // Block until the callback produces a result.
    match rx.recv() {
        Ok(Ok(_)) => println!("Authentication successful"),
        Ok(Err(e)) => println!("Authentication failed: {:?}", e),
        Err(e) => eprintln!("Failed to receive auth result: {:?}", e),
    }
}

pub fn password(self, password: bool) -> Self

Sets whether the policy supports passwords.

Examples found in repository

examples/simple_authentication.rs (line 62)

fn main() {
    let context = Context::new(());
    let mut policy = PolicyBuilder::new()
        // On Linux You need to set action_ids.
        // See: ./org.robius.authentication.policy file settings and (README: "Usage on Linux").
        .action_ids([
            "org.robius.authentication",
            "org.robius.authentication.settings",
        ])
        .biometrics(Some(BiometricStrength::Strong))
        .password(true)
        .companion(true)
        .build()
        .unwrap();

    if let Err(e) = policy.set_action_id("org.robius.authentication.settings") {
        eprintln!("Invalid action_id: {:?}", e);
        return;
    }

    let (tx, rx) = mpsc::channel();

    // Start authentication. `res` only indicates whether the request was successfully
    // initiated; the final result is delivered via the callback.
    let res = context.authenticate(TEXT, &policy, move |result| {
        let _ = tx.send(result);
    });

    if let Err(e) = res {
        eprintln!("Failed to start authentication: {:?}", e);
        return;
    }

    // Block until the callback produces a result.
    match rx.recv() {
        Ok(Ok(_)) => println!("Authentication successful"),
        Ok(Err(e)) => println!("Authentication failed: {:?}", e),
        Err(e) => eprintln!("Failed to receive auth result: {:?}", e),
    }
}

pub fn companion(self, companion: bool) -> Self

Sets whether the policy supports authentication via a proximity companion device, e.g., Apple Watch.

This only has an effect on iOS and macOS.

Examples found in repository

examples/simple_authentication.rs (line 63)

fn main() {
    let context = Context::new(());
    let mut policy = PolicyBuilder::new()
        // On Linux You need to set action_ids.
        // See: ./org.robius.authentication.policy file settings and (README: "Usage on Linux").
        .action_ids([
            "org.robius.authentication",
            "org.robius.authentication.settings",
        ])
        .biometrics(Some(BiometricStrength::Strong))
        .password(true)
        .companion(true)
        .build()
        .unwrap();

    if let Err(e) = policy.set_action_id("org.robius.authentication.settings") {
        eprintln!("Invalid action_id: {:?}", e);
        return;
    }

    let (tx, rx) = mpsc::channel();

    // Start authentication. `res` only indicates whether the request was successfully
    // initiated; the final result is delivered via the callback.
    let res = context.authenticate(TEXT, &policy, move |result| {
        let _ = tx.send(result);
    });

    if let Err(e) = res {
        eprintln!("Failed to start authentication: {:?}", e);
        return;
    }

    // Block until the callback produces a result.
    match rx.recv() {
        Ok(Ok(_)) => println!("Authentication successful"),
        Ok(Err(e)) => println!("Authentication failed: {:?}", e),
        Err(e) => eprintln!("Failed to receive auth result: {:?}", e),
    }
}

pub fn wrist_detection(self, wrist_detection: bool) -> Self

Sets whether the policy requires the companion device (Apple Watch) to be on the user’s wrist.

This only has an effect on Apple watchOS.

pub fn build(self) -> Option<Policy>

Constructs the policy.

Returns None if the specified configuration is not valid for the current target.

Examples found in repository

examples/simple_authentication.rs (line 64)

fn main() {
    let context = Context::new(());
    let mut policy = PolicyBuilder::new()
        // On Linux You need to set action_ids.
        // See: ./org.robius.authentication.policy file settings and (README: "Usage on Linux").
        .action_ids([
            "org.robius.authentication",
            "org.robius.authentication.settings",
        ])
        .biometrics(Some(BiometricStrength::Strong))
        .password(true)
        .companion(true)
        .build()
        .unwrap();

    if let Err(e) = policy.set_action_id("org.robius.authentication.settings") {
        eprintln!("Invalid action_id: {:?}", e);
        return;
    }

    let (tx, rx) = mpsc::channel();

    // Start authentication. `res` only indicates whether the request was successfully
    // initiated; the final result is delivered via the callback.
    let res = context.authenticate(TEXT, &policy, move |result| {
        let _ = tx.send(result);
    });

    if let Err(e) = res {
        eprintln!("Failed to start authentication: {:?}", e);
        return;
    }

    // Block until the callback produces a result.
    match rx.recv() {
        Ok(Ok(_)) => println!("Authentication successful"),
        Ok(Err(e)) => println!("Authentication failed: {:?}", e),
        Err(e) => eprintln!("Failed to receive auth result: {:?}", e),
    }
}

Trait Implementations

impl Debug for PolicyBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PolicyBuilder

fn default() -> Self

Returns the “default value” for a type.