[PM-5693] CryptoService using memfd_secret on Linux

[dani-garcia]

🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-5693

📔 Objective

Migrated from bitwarden/sdk-sm#979

I've been looking into using memfd_secret to protect keys in memory on Linux.

The memfd_secret API is similar to malloc in that we get some memory range allocated for us, but this memory is only visible to the process that has access to the file descriptor, which should protect us from any memory dumping from anything other than a kernel driver.

https://man.archlinux.org/man/memfd_secret.2.en

Using this requires changing how we store keys, so this is the perfect moment to go through removing the raw keys from the API surface.

Changes

• Added a KeyRef trait and SymmetricKeyRef/AsymmetricKeyRef subtraits to represent the key types. Also a small macro to quickly implement them. KeyRef implementations are user defined types that implements Eq+Hash+Copy, and don't contain any key material
• KeyEncryptable/KeyDecryptable are now Decryptable/Encryptable, and instead of taking the key as parameter, they take a CryptoServiceContext and a KeyRef. This way keys are never exposed to the clients.
• KeyLocator trait is replaced by UsesKey. This trait only returns the KeyRef of the key required to decrypt it, instead of fetching the key itself.
• Created a KeyStore trait, with some simple CRUD methods. We have two implementations, one based on memfd_secret for Linux, and another one based on a Rust boxed slice, that also applies mlock if possible.
• Because both mlock and memfd_secret apply their protection over a specified memory area, we need a Rust data structure that is laid out linearly and also doesn't reallocate by itself. Also because memfd_secret allocates the memory for us, we can't use a std type like Vec (reason is the Vec must be allocated by the Rust allocator [ref]). This basically only leaves us with a Rust slice, on top of which we'd need to implement insert/get/delete. To allow for reuse and easier testing I've created SliceKeyStore, which implements the CRUD methods from the KeyStore trait on top of a plain slice. Then the actual mlock and memfd_secret implementations just need to implement a trait casting their data to a slice. The data is stored as a slice of Option<(KeyRef, KeyMaterial)>, and the keys are unique and sorted in the slice for easier lookups.
• Created CryptoService, which contains the KeyStores and some encrypt/decrypt utility functions. From a CryptoService you can also initialize a CryptoServiceContext
• A CryptoServiceContext contains a read only view of the keys inside the CryptoService, plus a read-write ephemeral key store, for use by Decryptable/Encryptable implementations when they need to temporarily store some keys (Cipher keys, attachment keys, send keys...).

Migrated the codebase to use these changes in a separate PR: bitwarden/sdk-sm#1117

📸 Screenshots

⏰ Reminders before review

• Contributor guidelines followed
• All formatters and local linters executed and passed
• Written new unit and / or integration tests where applicable
• Protected functional changes with optionality (feature flags)
• Used internationalization (i18n) for all UI strings
• CI builds passed
• Communicated to DevOps any deployment requirements
• Updated any necessary documentation (Confluence, contributing docs) or informed the documentation
  team

🦮 Reviewer guidelines

• 👍 (:+1:) or similar for great changes
• 📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
• ❓ (:question:) for questions
• 🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed
  issue and could potentially benefit from discussion
• 🎨 (:art:) for suggestions / improvements
• ❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
• 🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
• ⛏ (:pick:) for minor or nitpick changes

[github-actions]

Checkmarx One – Scan Summary & Details – c50a09d3-37c7-4d91-9a9c-1923beada9ae

No New Or Fixed Issues Found

[codecov]

Codecov Report

Attention: Patch coverage is 78.51662% with 252 lines in your changes missing coverage. Please review.

Project coverage is 65.55%. Comparing base (a89b588) to head (275574f).

Files with missing lines	Patch %	Lines
crates/bitwarden-crypto/src/store/context.rs	48.43%	148 Missing ⚠️
crates/bitwarden-crypto/src/keys/encryptable.rs	27.88%	75 Missing ⚠️
crates/bitwarden-crypto/src/store/mod.rs	85.23%	22 Missing ⚠️
...itwarden-crypto/src/store/backend/slice_backend.rs	98.67%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #7      +/-   ##
==========================================
+ Coverage   64.43%   65.55%   +1.12%     
==========================================
  Files         188      195       +7     
  Lines       13832    15005    +1173     
==========================================
+ Hits         8912     9836     +924     
- Misses       4920     5169     +249     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Hinton]

I've taken an initial look at this. I think the general concept is solid, there are some potential areas for improvements.

However the biggest pieces would be:

1. Documentation, we need to ensure we write solid documentation on the difference areas and ensure we are clear about how it's intended to be used.
2. Improve test coverage, since we're dealing with cryptography we want to be really sure nothing breaks in the future.

[Hinton]

MissingKey2 😭 Will this be removed once we remove all usages of the old interfaces?

[dani-garcia]

Yeah, that's removed in the other PR that starts using this code in the rest of the SDK:
https://github.com/bitwarden/sdk-internal/pull/8/files#diff-3a39fb8ed55a85cd232b4ac7681c85bb81462727f6d311b1a4c33be7c5b7f4ed

I didn't want to update it here to avoid needing to touch up code which was going to need to be updated in the other PR anyway

[Hinton]

Do we have any documentation for why we need to implement our own slice vs using built in?

[dani-garcia]

Added some doc comments here:

sdk-internal/crates/bitwarden-crypto/src/store/backend/slice_backend.rs

Lines 40 to 44 in e7bfdc3

	/// The reason why we're not using a Rust collection like `Vec` or `HashMap` is that those types
	/// expect their memory to be allocated by Rust, and they will deallocate/reallocate it as needed.
	/// That will not work for our usecases where we want to have control over allocations/deallocations
	/// and where some of our strategies rely on using system-allocated secure memory for the storage,
	/// like the Linux-only `memfd_secret` API.

[Hinton]

Should these be doc comments?

[dani-garcia]

I've mostly added these to split up and organize all the Encryptable/Decryptable implementations.

They all look very similar and when I didn't have these comments is was quite annoying to find one in particular. Maybe what that is telling us is that we should move those impls into separate modules or separate files.

[Hinton]

question: We define a Keys struct which essentially acts as the KeyStore. Would it be a cleaner interface to define a KeyStore trait which both CryptoService and Keys implements, and CryptoService simply forwards calls to the inner store.

[dani-garcia]

Initially I think I've tried to do something like that, but it was hard to get a good API when using a trait here and then also trying to be generic over key type / Encryptable implementation.

[dani-garcia]

I've made a few changes while documenting this a bit, plus some of the review suggestions are included here as well:

• memsec is disabled on windows for now, and we're not using my fork
• There's been a few renames:
  • CryptoService -> KeyStore. to move away from the service name
  • Keys -> KeyStoreInner. This only exists to be wrapped with the RwLock, and everything in KeyStore is pretty much delegated to it, so it seems like a better name.
  • CryptoServiceContext -> KeyStoreContext. To match the service rename
  • KeyStore -> StoreBackend. To signify there are different backends per platform
  • LinuxMemfdSecretKeyStore -> LinuxMemfdSecretBackend and RustStore -> RustBackend, to match the trait above.
• Changed the generic params of the KeyStore to be a single KeyRefs, which makes the generic types everywhere much less verbose (Instead of having to do <SymmetricKeyRef, AsymmetricKeyRef> everywhere you can do <KeyRefs>.
• Removed the generic type over KeyStoreContext global keys, and moved it to an enum.

---

The next steps for the crypto refactor after this are:

• Move all the Encryptable implementations to the new trait: [PM-5693] Migrate SDK to CryptoService #8
• Migrate existing APIs that deal with SymmetricCryptoKey/AsymmetricCryptoKey directly to deal with references instead (init_crypto functions, MasterKey, UserKey, PinKey, Key fingerprint etc).
• Remove uses of KeyStoreContext::get_key|set_key from the non crypto crates, which shouldn't have any uses left after the previous step (maybe?).
• Once no other uses of SymmetricCryptoKey/AsymmetricCryptoKey are left, make them private to bitwarden-crypto
• Remove the now unnecessary boxing around SymmetricCryptoKey/AsymmetricCryptoKey

---

Some future API improvements:

• Improve the design around local keys, instead of accepting any user type, create an opaque token and return it in the functions, so the only way for a user to get a valid local key ref is to obtain it from a function.
• Currently the context implementation can be read-only or read-write over the global keys, depending on how it's initialized, and it's behavior changes slightly in both cases. I think it might be a better design to instead do something like SQL transactions. Contexts are always read-only, but they have a commit function that consumes them and applies the changes to the global KeyStore