Skip to content

Implement safe wrappers for GCM incremental APIs #84

Open
jacsmi-msft wants to merge 6 commits intomicrosoft:mainfrom
jacsmi-msft:user/jacsmi/gcm_incremental_wrappers
Open

Implement safe wrappers for GCM incremental APIs #84
jacsmi-msft wants to merge 6 commits intomicrosoft:mainfrom
jacsmi-msft:user/jacsmi/gcm_incremental_wrappers

Conversation

@jacsmi-msft
Copy link
Copy Markdown
Collaborator

@jacsmi-msft jacsmi-msft commented Feb 11, 2025

Description of Changes:

This PR implements safe wrappers for the GCM incremental APIs:

  • SymCryptGcmAuthPart
  • SymCryptGcmDecryptPart
  • SymCryptGcmDecryptFinal
  • SymCryptGcmEncryptPart
  • SymCryptGcmEncryptFinal

The new public types are:

  • GcmUninitializedKey - Represents storage for an uninitialized SYMCRYPT_GCM_EXPANDED_KEY
  • GcmExpandedKeyHandle - Wraps an &mut GcmExpandedKeyStorage with the guarantee that the SYMCRYPT_GCM_EXPANDED_KEY is initialized and that it is zeroed on drop.
  • GcmExpandedKeyRef - Wraps an &GcmExpandedKeyStorage with the guarantee that the SYMCRYPT_GCM_EXPANDED_KEY is initialized.
  • GcmStream - Represents an uninitialized SYMCRYPT_GCM_STATE
  • GcmAuthStream - Represents an initialized SYMCRYPT_GCM_STATE that can be used for authenticating data
  • GcmAuthStreamRefMut - Roughly equivalent to an &mut GcmAuthStream, but removes a layer of indirection
  • GcmDecryptionStream - Represents an initialized SYMCRYPT_GCM_STATE that can be used to decrypt data
  • GcmDecryptionStreamRefMut - Roughly equivalent to an &mut GcmDecryptionStream, but removes a layer of indirection
  • GcmEncryptionStream - Represents an initialized SYMCRYPT_GCM_STATE that can be used to encrypt data
  • GcmEncryptionStreamRefMut - Roughly equivalent to an &mut GcmEncryptionStream, but removes a layer of indirection

The new internal types are:

  • GcmInitializedStream - Wraps an &mut GcmStream with the additional guarantee that the SYMCRYPT_GCM_STATE is initialized and zeroed on drop.
  • GcmInitializedStreamRefMut - Wraps an &mut GcmStream with the additional guarantee that the SYMCRYPT_GCM_STATE is initialized, but not zeroed on drop.

Next steps are to introduce an std feature so that this crate can be used in a no-std environment. All of the new types should be no-std compatible. This will likely be in a different PR though.

Breaking Changes if any:

This should not contain any breaking changes for users of the existing non-incremental API wrappers.

✅ Admin Checklist

  • Review the PR description and ensure all necessary details are included.
  • Update/add unit tests for changed code.
  • Update/add documentation for new or changed APIs.
  • Run cargo test --all-features on Windows and WSL.

Check the Developer Guidelines in DEVELOPER.md for more info.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant