pub struct KeychainFile { /* private fields */ }Expand description
A keychain database, optionally unlocked.
Implementations§
Source§impl KeychainFile
impl KeychainFile
pub fn open(path: impl AsRef<Path>) -> Result<Self>
pub fn from_bytes(bytes: &[u8]) -> Result<Self>
pub fn path(&self) -> Option<&Path>
pub fn keychain(&self) -> &Keychain
pub fn schema(&self) -> &Schema
pub fn is_unlocked(&self) -> bool
Sourcepub fn db_blob(&self) -> Result<DbBlob>
pub fn db_blob(&self) -> Result<DbBlob>
The database blob, which holds the salt and the encrypted database keys.
Sourcepub fn unlock(&mut self, password: &[u8]) -> Result<()>
pub fn unlock(&mut self, password: &[u8]) -> Result<()>
Derive the database keys from a password and unwrap every item key.
Sourcepub fn item_key_count(&self) -> usize
pub fn item_key_count(&self) -> usize
Number of item keys recovered by Self::unlock.
pub fn items_of_type(&self, record_type: RecordType) -> Vec<Item<'_>>
Sourcepub fn queryable_items(&self) -> Vec<Item<'_>>
pub fn queryable_items(&self) -> Vec<Item<'_>>
Every user-facing or cryptographic record that kc get can query.
Sourcepub fn select(&self, expression: &Expression) -> Result<Vec<Item<'_>>>
pub fn select(&self, expression: &Expression) -> Result<Vec<Item<'_>>>
Query every supported record class with one shared typed expression.
Sourcepub fn item_ref(&self, item: &Item<'_>) -> Result<ItemRef>
pub fn item_ref(&self, item: &Item<'_>) -> Result<ItemRef>
Create a mutation-safe reference to an item in this exact database revision.
Sourcepub fn resolve_ref(&self, reference: &ItemRef) -> Result<Item<'_>>
pub fn resolve_ref(&self, reference: &ItemRef) -> Result<Item<'_>>
Validate that a reference names this database revision and still points at a record.
Sourcepub fn records_of_type(&self, record_type: RecordType) -> Vec<&Record>
pub fn records_of_type(&self, record_type: RecordType) -> Vec<&Record>
Records of any relation, for callers that need schema-level inspection.
Sourcepub fn secret(&self, item: &Item<'_>) -> Result<SecretBytes>
pub fn secret(&self, item: &Item<'_>) -> Result<SecretBytes>
Decrypt an item’s secret. Requires an unlocked keychain.
Sourcepub fn find_one(&self, query: &Query) -> Result<Item<'_>>
pub fn find_one(&self, query: &Query) -> Result<Item<'_>>
Exactly one match, or an error naming the ambiguity.
Sourcepub fn save_in_place(&self) -> Result<()>
pub fn save_in_place(&self) -> Result<()>
Write back to the path this was opened from.
Source§impl KeychainFile
impl KeychainFile
Sourcepub fn update_item(
&mut self,
record_type: RecordType,
record_number: u32,
changes: &ItemChanges,
secret: Option<&[u8]>,
timestamp: &str,
) -> Result<()>
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.
Sourcepub fn delete_item(
&mut self,
record_type: RecordType,
record_number: u32,
) -> Result<usize>
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.
Sourcepub fn delete_certificate(&mut self, public_key_hash: &[u8]) -> Result<usize>
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.
Sourcepub fn delete_identity(&mut self, public_key_hash: &[u8]) -> Result<usize>
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.
Sourcepub fn set_item_trust(
&mut self,
record_type: RecordType,
record_number: u32,
trusted: &[TrustedApplication],
) -> Result<()>
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.
Sourcepub fn set_item_access(
&mut self,
record_type: RecordType,
record_number: u32,
access: &ApplicationAccess,
) -> Result<()>
pub fn set_item_access( &mut self, record_type: RecordType, record_number: u32, access: &ApplicationAccess, ) -> Result<()>
Rewrite an item’s native application access.
Sourcepub fn set_private_key_trust(
&mut self,
record_number: u32,
trusted: &[TrustedApplication],
) -> Result<()>
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.
Sourcepub fn set_private_key_access(
&mut self,
record_number: u32,
access: &ApplicationAccess,
) -> Result<()>
pub fn set_private_key_access( &mut self, record_number: u32, access: &ApplicationAccess, ) -> Result<()>
Rewrite a stored private key’s native application access.
Sourcepub fn item_application_access(
&self,
record_type: RecordType,
record_number: u32,
) -> Result<Option<ApplicationAccess>>
pub fn item_application_access( &self, record_type: RecordType, record_number: u32, ) -> Result<Option<ApplicationAccess>>
Native application access for a password item.
Sourcepub fn private_key_application_access(
&self,
record_number: u32,
) -> Result<Option<ApplicationAccess>>
pub fn private_key_application_access( &self, record_number: u32, ) -> Result<Option<ApplicationAccess>>
Native application access for a stored private key.
Sourcepub fn item_trusted_applications(
&self,
record_type: RecordType,
record_number: u32,
) -> Result<Option<Vec<TrustedApplication>>>
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.
Sourcepub fn private_key_trusted_applications(
&self,
record_number: u32,
) -> Result<Option<Vec<TrustedApplication>>>
pub fn private_key_trusted_applications( &self, record_number: u32, ) -> Result<Option<Vec<TrustedApplication>>>
Native ACL applications for a stored private key.
Sourcepub fn change_password(&mut self, old: &[u8], new: &[u8]) -> Result<()>
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.
Sourcepub fn settings(&self) -> Result<Settings>
pub fn settings(&self) -> Result<Settings>
The keychain’s settings, as stored in the database blob.
Sourcepub fn set_settings(&mut self, settings: &Settings) -> Result<()>
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
impl KeychainFile
Sourcepub fn identities(&self) -> Vec<StoredIdentity>
pub fn identities(&self) -> Vec<StoredIdentity>
Certificates in the keychain, paired with their private keys.
Sourcepub fn private_key_pkcs8(&self, record_number: u32) -> Result<SecretBytes>
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
impl KeychainFile
Sourcepub fn add_password(
&mut self,
record_type: RecordType,
item: &NewItem,
secret: &[u8],
timestamp: &str,
) -> Result<()>
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.
Sourcepub fn add_password_with_access(
&mut self,
record_type: RecordType,
item: &NewItem,
secret: &[u8],
timestamp: &str,
access: &ApplicationAccess,
) -> Result<()>
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.
Sourcepub fn add_identity(&mut self, identity: &NewIdentity) -> Result<[u8; 20]>
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.
Sourcepub fn add_identity_with_access(
&mut self,
identity: &NewIdentity,
access: &ApplicationAccess,
) -> Result<[u8; 20]>
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.