Struct KeyStoreContext

pub struct KeyStoreContext<'a, Ids: KeyIds> {
    pub(super) global_keys: GlobalKeys<'a, Ids>,
    pub(super) local_symmetric_keys: Box<dyn StoreBackend<Ids::Symmetric>>,
    pub(super) local_asymmetric_keys: Box<dyn StoreBackend<Ids::Asymmetric>>,
    pub(super) local_signing_keys: Box<dyn StoreBackend<Ids::Signing>>,
    pub(super) security_state_version: u64,
    pub(super) _phantom: PhantomData<(Cell<()>, RwLockReadGuard<'static, ()>)>,
}

The context of a crypto operation using super::KeyStore

This will usually be accessed from an implementation of crate::Decryptable or crate::CompositeEncryptable, crate::PrimitiveEncryptable, but can also be obtained through super::KeyStore::context

This context contains access to the user keys stored in the super::KeyStore (sometimes referred to as global keys) and it also contains it’s own individual secure backend for key storage. Keys stored in this individual backend are usually referred to as local keys, they will be cleared when this context goes out of scope and is dropped and they do not affect either the global super::KeyStore or other instances of contexts.

This context-local storage is recommended for ephemeral and temporary keys that are decrypted during the course of a decrypt/encrypt operation, but won’t be used after the operation itself is complete.

struct Data {
    key: EncString,
    name: String,
}


impl CompositeEncryptable<Ids, SymmKeyId, EncString> for Data {
    fn encrypt_composite(&self, ctx: &mut KeyStoreContext<Ids>, key: SymmKeyId) -> Result<EncString, CryptoError> {
        let local_key_id = ctx.unwrap_symmetric_key(key, &self.key)?;
        self.name.encrypt(ctx, local_key_id)
    }
}

Fields

global_keys: GlobalKeys<'a, Ids>

local_symmetric_keys: Box<dyn StoreBackend<Ids::Symmetric>>

local_asymmetric_keys: Box<dyn StoreBackend<Ids::Asymmetric>>

local_signing_keys: Box<dyn StoreBackend<Ids::Signing>>

security_state_version: u64

_phantom: PhantomData<(Cell<()>, RwLockReadGuard<'static, ()>)>

Implementations

impl<Ids: KeyIds> KeyStoreContext<'_, Ids>

pub fn clear_local(&mut self)

Clears all the local keys stored in this context This will not affect the global keys even if this context has write access. To clear the global keys, you need to use super::KeyStore::clear instead.

pub fn get_security_state_version(&self) -> u64

Returns the version of the security state of the key context. This describes the user’s encryption version and can be used to disable certain old / dangerous format features safely.

pub fn retain_symmetric_keys(&mut self, f: fn(Ids::Symmetric) -> bool)

Remove all symmetric keys from the context for which the predicate returns false This will also remove the keys from the global store if this context has write access

pub fn retain_asymmetric_keys(&mut self, f: fn(Ids::Asymmetric) -> bool)

Remove all asymmetric keys from the context for which the predicate returns false This will also remove the keys from the global store if this context has write access

fn drop_symmetric_key( &mut self, key_id: Ids::Symmetric, ) -> Result<(), CryptoError>

fn drop_asymmetric_key( &mut self, key_id: Ids::Asymmetric, ) -> Result<(), CryptoError>

fn drop_signing_key(&mut self, key_id: Ids::Signing) -> Result<(), CryptoError>

pub fn unwrap_symmetric_key( &mut self, wrapping_key: Ids::Symmetric, wrapped_key: &EncString, ) -> Result<Ids::Symmetric, CryptoError>

Decrypt a symmetric key into the context by using an already existing symmetric key

Arguments

• wrapping_key - The key id used to decrypt the wrapped_key. It must already exist in the context
• new_key_id - The key id where the decrypted key will be stored. If it already exists, it will be overwritten
• wrapped_key - The key to decrypt

pub fn persist_symmetric_key( &mut self, from: Ids::Symmetric, to: Ids::Symmetric, ) -> Result<(), CryptoError>

Move a symmetric key from a local identifier to a global identifier within the context

The key value is copied to to and the original identifier from is removed.

Errors

Returns an error if the source key does not exist or if setting the destination key fails (for example due to read-only global store).

pub fn persist_asymmetric_key( &mut self, from: Ids::Asymmetric, to: Ids::Asymmetric, ) -> Result<(), CryptoError>

Move an asymmetric key from a local identifier to a global identifier within the context

The key value is copied to to and the original identifier from is removed.

Errors

Returns an error if the source key does not exist or if setting the destination key fails (for example due to read-only global store).

pub fn persist_signing_key( &mut self, from: Ids::Signing, to: Ids::Signing, ) -> Result<(), CryptoError>

Move a signing key from a local identifier to a global identifier within the context

The key value at from will be copied to to and the original from will be removed.

Errors

Returns an error if the source key does not exist or updating the destination fails.

pub fn wrap_signing_key( &self, wrapping_key: Ids::Symmetric, key_to_wrap: Ids::Signing, ) -> Result<EncString, CryptoError>

Wrap (encrypt) a signing key with a symmetric key.

The signing key identified by key_to_wrap will be serialized to COSE and encrypted with the symmetric wrapping_key, returning an EncString suitable for storage or transport.

Errors

Returns an error if either key id does not exist or the encryption fails.

pub fn wrap_private_key( &self, wrapping_key: Ids::Symmetric, key_to_wrap: Ids::Asymmetric, ) -> Result<EncString, CryptoError>

Wrap (encrypt) a private/asymmetric key with a symmetric key.

The private key identified by key_to_wrap will be serialized to DER (PKCS#8) and encrypted with wrapping_key, returning an EncString suitable for storage.

Errors

Returns an error if the keys are missing or serialization/encryption fails.

pub fn unwrap_private_key( &mut self, wrapping_key: Ids::Symmetric, wrapped_key: &EncString, ) -> Result<Ids::Asymmetric, CryptoError>

Decrypt and import a previously wrapped asymmetric private key into the context.

The wrapped_key will be decrypted using wrapping_key and parsed as a PKCS#8 private key; the resulting key will be inserted as a local asymmetric key and the new local identifier returned.

Errors

Returns an error if decryption or parsing fails.

pub fn unwrap_signing_key( &mut self, wrapping_key: Ids::Symmetric, wrapped_key: &EncString, ) -> Result<Ids::Signing, CryptoError>

Decrypt and import a previously wrapped signing key into the context.

The wrapped COSE key will be decrypted with wrapping_key and parsed into a SigningKey which is inserted as a local signing key. The new local identifier is returned.

Errors

Returns an error if decryption or parsing fails.

pub fn get_verifying_key( &self, signing_key_id: Ids::Signing, ) -> Result<VerifyingKey, CryptoError>

Return the verifying (public) key corresponding to a signing key identifier.

This converts the stored SigningKey into a VerifyingKey suitable for signature verification operations.

Errors

Returns an error if the signing key id does not exist.

pub fn get_public_key( &self, asymmetric_key_id: Ids::Asymmetric, ) -> Result<AsymmetricPublicCryptoKey, CryptoError>

Return the public key corresponding to an asymmetric (private) key identifier.

This converts the stored private key into its public key representation.

Errors

Returns an error if the asymmetric key id does not exist.

pub fn wrap_symmetric_key( &self, wrapping_key: Ids::Symmetric, key_to_wrap: Ids::Symmetric, ) -> Result<EncString, CryptoError>

Encrypt and return a symmetric key from the context by using an already existing symmetric key

Arguments

• wrapping_key - The key id used to wrap (encrypt) the key_to_wrap. It must already exist in the context
• key_to_wrap - The key id to wrap. It must already exist in the context

pub fn decapsulate_key_unsigned( &mut self, decapsulation_key: Ids::Asymmetric, new_key_id: Ids::Symmetric, encapsulated_shared_key: &UnsignedSharedKey, ) -> Result<Ids::Symmetric, CryptoError>

Decapsulate a symmetric key into the context by using an already existing asymmetric key

Arguments

• decapsulation_key - The key id used to decrypt the encrypted_key. It must already exist in the context
• new_key_id - The key id where the decrypted key will be stored. If it already exists, it will be overwritten
• encapsulated_shared_key - The symmetric key to decrypt

pub fn encapsulate_key_unsigned( &self, encapsulation_key: Ids::Asymmetric, shared_key: Ids::Symmetric, ) -> Result<UnsignedSharedKey, CryptoError>

Encapsulate and return a symmetric key from the context by using an already existing asymmetric key

Arguments

• encapsulation_key - The key id used to encrypt the encapsulated_key. It must already exist in the context
• shared_key - The key id to encrypt. It must already exist in the context

pub fn has_symmetric_key(&self, key_id: Ids::Symmetric) -> bool

Returns true if the context has a symmetric key with the given identifier

pub fn has_asymmetric_key(&self, key_id: Ids::Asymmetric) -> bool

Returns true if the context has an asymmetric key with the given identifier

pub fn has_signing_key(&self, key_id: Ids::Signing) -> bool

Returns true if the context has a signing key with the given identifier

pub fn generate_symmetric_key(&mut self) -> Ids::Symmetric

Generate a new random symmetric key and store it in the context

pub fn make_symmetric_key( &mut self, algorithm: SymmetricKeyAlgorithm, ) -> Ids::Symmetric

Generate a new symmetric encryption key using the specified algorithm and store it in the context as a local key

pub fn make_private_key( &mut self, algorithm: PublicKeyEncryptionAlgorithm, ) -> Result<Ids::Asymmetric, CryptoError>

Makes a new asymmetric encryption key using the current default algorithm, and stores it in the context as a local key

pub fn make_signing_key( &mut self, algorithm: SignatureAlgorithm, ) -> Result<Ids::Signing, CryptoError>

Makes a new signing key using the current default algorithm, and stores it in the context as a local key

pub fn make_asymmetric_key(&mut self) -> Result<Ids::Asymmetric, CryptoError>

Makes a new asymmetric encryption key using the current default algorithm, and stores it in the context

pub fn derive_shareable_key( &mut self, secret: Zeroizing<[u8; 16]>, name: &str, info: Option<&str>, ) -> Result<Ids::Symmetric, CryptoError>

Derive a shareable key using hkdf from secret and name and store it in the context.

A specialized variant of this function was called CryptoService.makeSendKey in the Bitwarden clients repository.

pub fn dangerous_get_symmetric_key( &self, key_id: Ids::Symmetric, ) -> Result<&SymmetricCryptoKey, CryptoError>

👎Deprecated: This function should ideally never be used outside this crate

Return a reference to a symmetric key stored in the context.

Deprecated: intended only for internal use and tests. This exposes the underlying SymmetricCryptoKey reference directly and should not be used by external code. Use the higher-level APIs (for example encryption/decryption helpers) or get_symmetric_key internally when possible.

Errors

Returns CryptoError::MissingKeyId if the key id does not exist in the context.

pub fn dangerous_get_asymmetric_key( &self, key_id: Ids::Asymmetric, ) -> Result<&AsymmetricCryptoKey, CryptoError>

👎Deprecated: This function should ideally never be used outside this crate

Return a reference to an asymmetric (private) key stored in the context.

Deprecated: intended only for internal use and tests. This exposes the underlying AsymmetricCryptoKey reference directly and should not be used by external code. Prefer using the public key via get_public_key or other higher-level APIs instead.

Errors

Returns CryptoError::MissingKeyId if the key id does not exist in the context.

pub fn make_signed_public_key( &self, private_key_id: Ids::Asymmetric, signing_key_id: Ids::Signing, ) -> Result<SignedPublicKey, CryptoError>

Makes a signed public key from an asymmetric private key and signing key stored in context. Signing a public key asserts ownership, and makes the claim to other users that if they want to share with you, they can use this public key.

pub(crate) fn get_symmetric_key( &self, key_id: Ids::Symmetric, ) -> Result<&SymmetricCryptoKey, CryptoError>

pub(super) fn get_asymmetric_key( &self, key_id: Ids::Asymmetric, ) -> Result<&AsymmetricCryptoKey, CryptoError>

pub(super) fn get_signing_key( &self, key_id: Ids::Signing, ) -> Result<&SigningKey, CryptoError>

pub fn set_symmetric_key( &mut self, key_id: Ids::Symmetric, key: SymmetricCryptoKey, ) -> Result<(), CryptoError>

👎Deprecated: This function should ideally never be used outside this crate

Set a symmetric key in the context.

Errors

Returns CryptoError::ReadOnlyKeyStore if the context does not have write access when attempting to modify the global store.

pub(crate) fn set_symmetric_key_internal( &mut self, key_id: Ids::Symmetric, key: SymmetricCryptoKey, ) -> Result<(), CryptoError>

pub fn add_local_symmetric_key( &mut self, key: SymmetricCryptoKey, ) -> Ids::Symmetric

Add a new symmetric key to the local context, returning a new unique identifier for it.

pub fn get_symmetric_key_algorithm( &self, key_id: Ids::Symmetric, ) -> Result<SymmetricKeyAlgorithm, CryptoError>

Get the type of a symmetric key stored in the context.

pub fn set_asymmetric_key( &mut self, key_id: Ids::Asymmetric, key: AsymmetricCryptoKey, ) -> Result<(), CryptoError>

👎Deprecated: This function should ideally never be used outside this crate

Set an asymmetric (private) key in the context.

Errors

Returns CryptoError::ReadOnlyKeyStore if attempting to write to the global store when the context is read-only.

pub fn add_local_asymmetric_key( &mut self, key: AsymmetricCryptoKey, ) -> Result<Ids::Asymmetric, CryptoError>

Add a new asymmetric key to the local context, returning a new unique identifier for it.

pub fn set_signing_key( &mut self, key_id: Ids::Signing, key: SigningKey, ) -> Result<(), CryptoError>

👎Deprecated: This function should ideally never be used outside this crate

Sets a signing key in the context

Errors

Returns CryptoError::ReadOnlyKeyStore if attempting to write to the global store when the context is read-only.

pub fn add_local_signing_key( &mut self, key: SigningKey, ) -> Result<Ids::Signing, CryptoError>

Add a new signing key to the local context, returning a new unique identifier for it.

pub(crate) fn decrypt_data_with_symmetric_key( &self, key: Ids::Symmetric, data: &EncString, ) -> Result<Vec<u8>, CryptoError>

pub(crate) fn encrypt_data_with_symmetric_key( &self, key: Ids::Symmetric, data: &[u8], content_format: ContentFormat, ) -> Result<EncString, CryptoError>

pub fn sign<Message: Serialize>( &self, key: Ids::Signing, message: &Message, namespace: &SigningNamespace, ) -> Result<SignedObject, CryptoError>

Signs the given data using the specified signing key, for the given crate::SigningNamespace and returns the signature and the serialized message. See crate::SigningKey::sign

pub(crate) fn sign_detached<Message: Serialize>( &self, key: Ids::Signing, message: &Message, namespace: &SigningNamespace, ) -> Result<(Signature, SerializedMessage), CryptoError>

Signs the given data using the specified signing key, for the given crate::SigningNamespace and returns the signature and the serialized message. See crate::SigningKey::sign_detached

pub fn dangerous_get_v2_rotated_account_keys( &self, current_user_private_key_id: Ids::Asymmetric, current_user_signing_key_id: Ids::Signing, ) -> Result<RotatedUserKeys, CryptoError>

Re-encrypts the user’s keys with the provided symmetric key for a v2 user.