Skip to main content

KeychainFile

Struct KeychainFile 

Source
pub struct KeychainFile { /* private fields */ }
Expand description

A keychain database, optionally unlocked.

Implementations§

Source§

impl KeychainFile

Source

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Source

pub fn from_bytes(bytes: &[u8]) -> Result<Self>

Source

pub fn path(&self) -> Option<&Path>

Source

pub fn keychain(&self) -> &Keychain

Source

pub fn schema(&self) -> &Schema

Source

pub fn is_unlocked(&self) -> bool

Source

pub fn db_blob(&self) -> Result<DbBlob>

The database blob, which holds the salt and the encrypted database keys.

Source

pub fn unlock(&mut self, password: &[u8]) -> Result<()>

Derive the database keys from a password and unwrap every item key.

Source

pub fn item_key_count(&self) -> usize

Number of item keys recovered by Self::unlock.

Source

pub fn items(&self) -> Vec<Item<'_>>

Every password item in the keychain, in table order.

Source

pub fn items_of_type(&self, record_type: RecordType) -> Vec<Item<'_>>

Source

pub fn queryable_items(&self) -> Vec<Item<'_>>

Every user-facing or cryptographic record that kc get can query.

Source

pub fn select(&self, expression: &Expression) -> Result<Vec<Item<'_>>>

Query every supported record class with one shared typed expression.

Source

pub fn item_ref(&self, item: &Item<'_>) -> Result<ItemRef>

Create a mutation-safe reference to an item in this exact database revision.

Source

pub fn resolve_ref(&self, reference: &ItemRef) -> Result<Item<'_>>

Validate that a reference names this database revision and still points at a record.

Source

pub fn records_of_type(&self, record_type: RecordType) -> Vec<&Record>

Records of any relation, for callers that need schema-level inspection.

Source

pub fn secret(&self, item: &Item<'_>) -> Result<SecretBytes>

Decrypt an item’s secret. Requires an unlocked keychain.

Source

pub fn find(&self, query: &Query) -> Vec<Item<'_>>

Items matching every supplied criterion.

Source

pub fn find_one(&self, query: &Query) -> Result<Item<'_>>

Exactly one match, or an error naming the ambiguity.

Source

pub fn save(&self, path: impl AsRef<Path>) -> Result<()>

Write the database back out.

Source

pub fn save_in_place(&self) -> Result<()>

Write back to the path this was opened from.

Source§

impl KeychainFile

Source

pub fn info(&self) -> Result<Info>

Source§

impl KeychainFile

Source

pub fn update_item( &mut self, record_type: RecordType, record_number: u32, changes: &ItemChanges, secret: Option<&[u8]>, timestamp: &str, ) -> Result<()>

Update an item in place: its secret, its attributes, or both.

The item keeps its record number, its slot, and its item key; only the encrypted payload is re-sealed, under a fresh IV. mdat is stamped with timestamp and cdat is left as it was.

Requires an unlocked keychain when secret is given.

Source

pub fn delete_item( &mut self, record_type: RecordType, record_number: u32, ) -> Result<usize>

Delete an item and the key record that protects it.

The slot keeps its place in the array — macOS never renumbers records — and both tables’ indexes are rebuilt so nothing points at the hole.

Returns the number of records removed: the item, plus its key when one was found.

Source

pub fn delete_certificate(&mut self, public_key_hash: &[u8]) -> Result<usize>

Delete a certificate, leaving any private key that goes with it.

This is what security delete-certificate does: the key is left behind, orphaned, and security find-identity stops reporting the identity. Use KeychainFile::delete_identity to remove both halves.

Source

pub fn delete_identity(&mut self, public_key_hash: &[u8]) -> Result<usize>

Delete an identity: the certificate and the private key that matches it.

Returns the number of records removed.

Source

pub fn set_item_trust( &mut self, record_type: RecordType, record_number: u32, trusted: &[TrustedApplication], ) -> Result<()>

Rewrite the access control of an item’s key.

An empty list means any application, which is what security add-generic-password -A stores. The key itself is untouched: only the ACL region of its blob is replaced, and the blob re-signed.

Source

pub fn set_item_access( &mut self, record_type: RecordType, record_number: u32, access: &ApplicationAccess, ) -> Result<()>

Rewrite an item’s native application access.

Source

pub fn set_private_key_trust( &mut self, record_number: u32, trusted: &[TrustedApplication], ) -> Result<()>

Rewrite the access control of a stored private key.

This is the identity equivalent of KeychainFile::set_item_trust.

Source

pub fn set_private_key_access( &mut self, record_number: u32, access: &ApplicationAccess, ) -> Result<()>

Rewrite a stored private key’s native application access.

Source

pub fn item_application_access( &self, record_type: RecordType, record_number: u32, ) -> Result<Option<ApplicationAccess>>

Native application access for a password item.

Source

pub fn private_key_application_access( &self, record_number: u32, ) -> Result<Option<ApplicationAccess>>

Native application access for a stored private key.

Source

pub fn item_trusted_applications( &self, record_type: RecordType, record_number: u32, ) -> Result<Option<Vec<TrustedApplication>>>

Native ACL applications for a password item.

None means the ACL was not in the canonical form this library models; an empty vector may mean allow-any or prompt-all. Use KeychainFile::item_application_access to distinguish them.

Source

pub fn private_key_trusted_applications( &self, record_number: u32, ) -> Result<Option<Vec<TrustedApplication>>>

Native ACL applications for a stored private key.

Source

pub fn change_password(&mut self, old: &[u8], new: &[u8]) -> Result<()>

Change the password that protects the keychain.

The database’s own keys are preserved — every item key in the file is wrapped under them — so only the blob is re-sealed: a fresh salt and IV, the keys re-encrypted under the new password, and a new signature. Nothing outside the metadata record changes.

Source

pub fn settings(&self) -> Result<Settings>

The keychain’s settings, as stored in the database blob.

Source

pub fn set_settings(&mut self, settings: &Settings) -> Result<()>

Change the keychain’s settings.

The settings live in the signed part of the database blob, so this needs the signing key: an unlocked keychain, or the password.

Source§

impl KeychainFile

Source

pub fn identities(&self) -> Vec<StoredIdentity>

Certificates in the keychain, paired with their private keys.

Source

pub fn private_key_pkcs8(&self, record_number: u32) -> Result<SecretBytes>

A stored private key, unwrapped, as a PKCS#8 PrivateKeyInfo.

Requires an unlocked keychain. The bytes are the ones that went in: this is the reverse of KeychainFile::add_identity.

Source§

impl KeychainFile

Source

pub fn add_password( &mut self, record_type: RecordType, item: &NewItem, secret: &[u8], timestamp: &str, ) -> Result<()>

Store a password item, creating the item key that protects it.

Requires an unlocked keychain: the item key is wrapped with the database’s encryption key and both blobs are signed with its signing key.

Source

pub fn add_password_with_access( &mut self, record_type: RecordType, item: &NewItem, secret: &[u8], timestamp: &str, access: &ApplicationAccess, ) -> Result<()>

Store a password item with an explicit native application-access policy.

Unlike KeychainFile::add_password, this distinguishes an allow-any ACL from an empty trusted-application list that prompts every caller.

Source

pub fn add_identity(&mut self, identity: &NewIdentity) -> Result<[u8; 20]>

Store an identity: the certificate in the clear, the private key wrapped.

The two records are linked by the certificate’s public key hash, which the key record carries as its Label — that is how SecIdentity pairs them, and how crate::db::KeychainFile and security both find them.

Requires an unlocked keychain: the private key is wrapped with the database’s encryption key, and both blobs are signed with its signing key.

Source

pub fn add_identity_with_access( &mut self, identity: &NewIdentity, access: &ApplicationAccess, ) -> Result<[u8; 20]>

Store an identity with an explicit native application-access policy.

This preserves the distinction between allow-any and prompt-every-caller ACLs while keeping KeychainFile::add_identity backward compatible.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

Source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

Source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

Source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V