pub struct FfiWrappedMasterKeyStore { /* private fields */ }Expand description
The application’s master key held wrapped by a key-encryption key inside the platform key store.
The store generates the key-encryption key (a non-exportable CNG key on Windows, an
Android Keystore key on Android), keeps it where nothing can read it out, and wraps the
master key with it. FfiWrappedMasterKeyStore::store hands back the wrapped bytes
for the host side to persist, and FfiWrappedMasterKeyStore::load takes them back and
returns the master key.
§Nothing here wraps, unwraps or hands out a key-encryption key
Wrapping is the internal design of this form, and the library keeps it that way: no operation of this object encrypts, decrypts or returns the key-encryption key, and none is added here. The host side stores a master key and receives bytes to keep; what those bytes mean is the platform’s business.
§The bytes belong to one store entry
Bytes produced by another store entry, or damaged in storage, fail rather than unwrap into a key that merely differs. That is what makes them safe to persist next to the vault file they belong to. The wrapped form is not secret the way the master key is: whoever copies the bytes still needs the platform key, which is not in them.
§Current state
Same as FfiDirectMasterKeyStore: Windows and Android have a backend, and every other
platform reports unsupported_platform from every operation.
Implementations§
Source§impl FfiWrappedMasterKeyStore
impl FfiWrappedMasterKeyStore
Sourcepub fn open() -> Result<Arc<Self>, FfiError>
pub fn open() -> Result<Arc<Self>, FfiError>
Opens the wrapped master key store of the current platform.
§Errors
A FfiError::Core error with the kind hardware_unavailable when this machine has
no provider that can create a key-encryption key; see
FfiDirectMasterKeyStore::open for why an unimplemented platform opens anyway.
Sourcepub fn backend(&self) -> String
pub fn backend(&self) -> String
The platform key store that holds the key-encryption key, as a stable short name:
"tpm", "android-keystore", "software", "secure-enclave" or "unavailable".
Reported truthfully, like FfiDirectMasterKeyStore::backend; this is the value the
host side tells the user about before it relies on the wrapped form.
Sourcepub fn is_hardware_backed(&self) -> bool
pub fn is_hardware_backed(&self) -> bool
Whether the key-encryption key cannot leave hardware.
Consistent with FfiWrappedMasterKeyStore::backend by construction: true exactly
when that backend is a hardware one.
Sourcepub fn store(&self, label: String, key: Vec<u8>) -> Result<Vec<u8>, FfiError>
pub fn store(&self, label: String, key: Vec<u8>) -> Result<Vec<u8>, FfiError>
Wraps the 32-byte key under label and returns the bytes the host side has to
persist.
The bytes are opaque: their length and contents belong to the platform, and only the same store entry can turn them back into the master key. Persist them next to the vault file they belong to; losing them means the master key has to be recovered another way, and deleting the label’s entry makes them permanently unusable.
Wrapping under a label that already exists reuses the key-encryption key that is already there, so bytes persisted earlier keep unwrapping.
§Errors
FfiError::InputTooLong for an oversized label; the core’s
master_key_wrong_length when key is not 32 bytes; otherwise a key store failure,
reported as unsupported_platform or device_error — a platform that cannot create
a key-encryption key included.
Sourcepub fn load(&self, label: String, wrapped: Vec<u8>) -> Result<Vec<u8>, FfiError>
pub fn load(&self, label: String, wrapped: Vec<u8>) -> Result<Vec<u8>, FfiError>
Unwraps wrapped — the bytes FfiWrappedMasterKeyStore::store handed back for
label — and returns the master key.
§Errors
invalid_wrapped_key when the bytes do not unwrap: a damaged blob, or one produced
by another store entry or another device. The method never returns bytes it could
not authenticate, so a failure here means “these bytes are unusable”, not “here is
a different key”. A label that holds no key-encryption key at all is device_error
today.
Sourcepub fn delete(&self, label: String) -> Result<(), FfiError>
pub fn delete(&self, label: String) -> Result<(), FfiError>
Deletes the key-encryption key stored under label.
§Warning
Every blob wrapped with that key becomes permanently unusable, which is how a device forgets a master key. The host side has to ask the user first, and it has to be prepared for the persisted bytes to be worthless afterwards.
§Errors
FfiError::InputTooLong for an oversized label, and otherwise the same key store
failures as FfiWrappedMasterKeyStore::load.