rust-security-framework

The security-framework crate provides high-level Rust wrappers around the macOS/iOS Security Framework. The API is organized into several functional modules. Note that some modules are platform-specific and only available on macOS.

Core Modules

• base: Error handling and core types.
• certificate: Handling of X.509 certificates.
• cipher_suite: Access to supported cipher suites.
• identity: Managing identities (certificate + private key pairs).
• import_export: Importing and exporting security items.
• item: General security item management.
• key: Cryptographic key management.
• os: Operating system integration.
• passwords: Password management.
• policy: Security policies.
• random: Secure random number generation.
• secure_transport: TLS/SSL secure transport services.
• trust: Certificate trust evaluation.

macOS-Specific Modules

• authorization: Authorization services.
• cms: Cryptographic Message Syntax (CMS).
• trust_settings: Managing system-wide trust settings.

The TrustSettings struct allows you to access and modify certificate trust settings within specific domains on macOS/iOS. You can iterate over certificates that have explicit trust settings in a domain and query their aggregate TLS trust status.

Domains

When creating a TrustSettings instance, specify one of the following domains:

• Domain::User: Per-user trust settings.
• Domain::Admin: Locally administered, system-wide trust settings.
• Domain::System: System trust settings.

Workflow

1. Create a TrustSettings instance for a specific Domain.
2. Use .iter() to discover certificates that have explicit settings in that domain.
3. Use .tls_trust_settings_for_certificate(&cert) to check the aggregate trust status of a specific certificate for TLS usage.

use security_framework::trust_settings::{TrustSettings, Domain};
use security_framework::certificate::SecCertificate;

let settings = TrustSettings::new(Domain::System);

// Iterate over certificates with explicit settings in the System domain
if let Ok(iter) = settings.iter() {
    for cert in iter {
        match settings.tls_trust_settings_for_certificate(&cert) {
            Ok(Some(status)) => println!("Cert status: {:?}", status),
            Ok(None) => println!("Cert is trusted by default (e.g., in system store)"),
            Err(e) => eprintln!("Error querying cert: {}", e),
        }
    }
}

Use set_access_synchronized to determine if a password should be stored in the cloud-synchronized keychain or the local-only keychain.

Important Behavior: Cloud-synchronized and non-synchronized passwords are kept in different stores and are uniquely identified by their synchronization status.

• Some(true): Affects only the cloud-synchronized store.
• Some(false): Affects only the local (not cloud-synchronized) store.
• None:
  • Delete: Deletes from both stores.
  • Get: Returns values from both stores (but only returns one value).
  • Set: Attempts to create a value in the local store first. If successful, it does not update the cloud store. It only updates the cloud store if an existing value in the local store is found.

// Only affect the cloud-synchronized store
options.set_access_synchronized(Some(true));

// Affect only the local store
options.set_access_synchronized(Some(false));

// Affect both (delete) or attempt both (set)
options.set_access_synchronized(None);

You can manage generic passwords (service/account pairs) using the SecKeychain methods or the standalone find_generic_password function.

• SecKeychain::set_generic_password: Updates an existing password if it exists, or adds a new one if it doesn't.
• SecKeychain::add_generic_password: Adds a new password without checking for duplicates.
• find_generic_password: Searches for a password. If keychains is None, it searches the default keychain. If Some(&[SecKeychain]) is provided, it searches only those specific keychains.

Passwords are returned as SecKeychainItemPassword, which can be accessed as a byte slice &[u8] via .as_ref() or converted to a Vec<u8> via .to_owned().

// Using the SecKeychain instance method to set/update a password
keychain.set_generic_password("my-service", "my-account", b"my-password")?;

// Finding a generic password
let (password, item) = find_generic_password(None, "my-service", "my-account")?;
let bytes = password.as_ref();