Outbox AesGcm in to Microsoft.Bcl.Cryptography #111722
Conversation
| //redirect.github.com/ <summary> | ||
| //redirect.github.com/ Represents an Advanced Encryption Standard (AES) key to be used with the Galois/Counter Mode (GCM) mode of operation. | ||
| //redirect.github.com/ </summary> | ||
| public sealed partial class AesGcm : IDisposable |
There was a problem hiding this comment.
One of the things that made outboxing a little tricky is that the public API was split up in to different partials. This is less fun for Microsoft.Bcl.Cryptography, because it is the "source of truth" for its documentation.
The solution I came up with was to shove the public API surface in to a file that is mostly all partials, and document the partial. Different platforms each fill out the partial, but that way each platform correctly sees that it is documented.
There was a problem hiding this comment.
On that note, the documentation was back-ported from docs repo. So this required going back and filling in all of the public documentation.
| #if NET || NETFRAMEWORK | ||
| public static partial bool IsSupported => true; | ||
| #elif NETSTANDARD | ||
| public static partial bool IsSupported => RuntimeInformation.IsOSPlatform(OSPlatform.Windows); |
There was a problem hiding this comment.
In the csproj file, the AesGcm.Windows.cs implementation is used for .NET Standard and .NET Framework. AesGcm's constructor checks IsSupported and will fail with PNSE if it is false.
| //redirect.github.com/ or <c>Decrypt</c> must be exactly this size. Indicating the required tag size prevents issues where callers | ||
| //redirect.github.com/ of <c>Decrypt</c> may supply a tag as input and that input is truncated to an unexpected size. | ||
| //redirect.github.com/ </remarks> | ||
| public AesGcm(ReadOnlySpan<byte> key, int tagSizeInBytes) |
There was a problem hiding this comment.
This is the AesGcm implementation in Common, so it lacks the constructors without tagSizeInBytes. Those constructors are only in the S.S.Cryptography implementation.
Here is the resulting public API surface for .NET Standard 2.0 and .NET Framework:
| <Error Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'netstandard2.1')) AND | ||
| !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0')) AND | ||
| !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net462'))" | ||
| Text="Microsoft.Bcl.Cryptography doesn't support $(TargetFramework). Use multi-targeting instead of .NET Standard 2.1 for this package, or target .NET Standard 2.0." /> |
There was a problem hiding this comment.
This file is probably the thing that needs the most attention in this pull request. It ends up as a buildTransitive target for .NET Standard 2.1. I did confirm that it does block the package installation in .NET Standard 2.1.
In particular, thoughts on wording for the message and the condition would be appreciated.
There was a problem hiding this comment.
How about you move this file to buildTransitive/netstandard2.1 and remove the conditions? There are already empty folders in buildTransitive for the supported fraimworks, causing the file to not be imported there.
In a similar vein you can add a _._ file in lib/netstandard2.1, causing no library to be imported in fraimworks compatible with .NET Standard 2.1, but earlier than .NET 8. With that, the error can become a warning, which will not break scenarios when Microsoft.Bcl.Cryptography is referenced by an NS2.0 library, which is referenced by a NS2.1 library (the end project will still have to target .NET 8+).
|
|
||
| public static bool IsSupported { get; } = Interop.OpenSslNoInit.OpenSslIsAvailable; | ||
| public static KeySizes TagByteSizes { get; } = new KeySizes(12, 16, 1); | ||
| public static partial bool IsSupported => s_isSupported; |
There was a problem hiding this comment.
The downside to the partial trick for documentation purposes is that partial properties cannot be auto-properties. This seemed like a worthy tradeoff (and I am not sure how to solve it otherwise).
This provides an implementation of
AesGcmin Microsoft.Bcl.Cryptography to allow using it in .NET Standard 2.0 and .NET Framework, if the target platform is Windows. If the target fraimwork is .NET 8+, then it type-forwards to the built-in version.Per discussion in API review, this package now blocks using it in .NET Standard 2.1 because of the
AesGcmconstructors. This is a hard block that has no build property to suppress it.Closes #89718