Module crypto 

Keychain cryptography: master key derivation, the database blob, wrapped item keys, and item secrets.

The dtformats specification covers the container but not the encryption, so the blob layouts here come from Apple’s own ssblob.h (Security/OSX/libsecurityd/lib/ssblob.h, CommonBlob/DbBlob/KeyBlob) and the key-unwrap sequence from securityd’s BLOBFORMAT notes as implemented by chainbreaker. Every value here is checked against keychains written by macOS in tests/keychain_crypto.rs.

The chain is:

password --PBKDF2-SHA1(salt, 1000, 24)--> master key
master key --3DES-CBC(DbBlob.iv)--> DbBlob crypto blob
                                    -> encryption key (24) + signing key (20)
encryption key --unwrap(KeyBlob)--> item key
item key --3DES-CBC(SSGP.iv)--> item secret

Everything is 3DES (EDE, three-key) in CBC mode. That is what the format specifies; it is not a choice this code makes.

Re-exports

pub use crate::secret::SecretBytes;

Structs

DbBlob

The fixed part of a DbBlob, the record that makes a keychain unlockable.

DbKeys

DbBlob::PrivateBlob: the keys that protect everything in the keychain.

KeyBlob

The fixed part of a KeyBlob: one wrapped key, as stored in a key record.

Ssgp

An item’s encrypted secret, as stored in the record’s key data.

Enums

PublicAcl

A public ACL: understood, or preserved as-is.

Constants

BLOB_MAGIC

CommonBlob::magicNumber.

BLOB_VERSION

The version this code writes for a new keychain, matching what security create-keychain writes outside ~/Library/Keychains.

BLOB_VERSION_MACOS_10_0

CommonBlob::version_MacOS_10_0. Blobs at this version — and only this version — are signed with legacy_hmac_sha1.

BLOB_VERSION_MACOS_10_1

CommonBlob::version_MacOS_10_1.

BLOB_VERSION_PARTITION

CommonBlob::version_partition, written for keychains under ~/Library/Keychains since macOS 10.11.4. Signed with real HMAC-SHA1.

BLOCK_SIZE

3DES block size, and so the IV size for the item and database blobs.

DB_BLOB_LEN

sizeof(DbBlob): the fixed part, before the public ACL.

KEY_BLOB_LEN

sizeof(KeyBlob): the fixed part, before the public ACL.

KEY_LEN

3DES-EDE3 key length.

MAGIC_CMS_IV

The fixed IV Apple’s key wrapping uses for its first pass. From libsecurity_keychain’s KeyItem.cpp; not a nonce, and not secret.

PBKDF2_ITERATIONS

PBKDF2 iteration count. Fixed by the format, and by today’s standards far too low — see the security notes in README.md.

SALT_LEN

PBKDF2 salt length in a DbBlob.

SSGP_HEADER_LEN

Length of the fixed part of an SSGP blob.

SSGP_MAGIC

Bytes that mark an item’s secure-storage group.

Functions

decrypt

3DES-CBC decrypt, then strip and verify the padding.

encrypt

3DES-CBC encrypt with the same padding scheme decrypt expects.

legacy_hmac_sha1

HMAC-SHA1 as Apple’s CSSM_ALGID_SHA1HMAC_LEGACY computes it, over a list of chunks.

master_key

Derive the master key from a keychain password.

sign_blob

Sign a blob the way securityd signs one at version.

unwrap_blob

Unwrap key material of any length: a 24-byte item key, or a private key’s PKCS#8 PrivateKeyInfo, which is what a private-key record holds.

unwrap_key

Apple’s custom key wrapping (CSSM_KEYBLOB_WRAPPED_FORMAT_APPLE_CUSTOM).

wrap_blob

Wrap key material of any length. Inverse of unwrap_blob.

wrap_key

Apple’s custom key wrapping, forwards. Inverse of unwrap_key.