Bring swift-crypto up to date with CryptoKit 2025 Beta 1

[Lukasa]

This PR sets swift-crypto up for alignment with the WWDC 2025 CryptoKit APIs. This includes the parity APIs for MLKEM and MLDSA, as well as XWing.

At this time the SHA3 APIs are disabled, as they require a novel implementation strategy. This will come later in the summer. All API features that require SHA3 are therefore also disabled at runtime.

[Lukasa]

@fpseverino Thank you for your hard work on the MLKEM/MLDSA implementations! You'll see that they have been brought across as the implementation of the common API layer. In the next week or so we should discuss strategies to allow _CryptoExtras to extend the APIs for the custom mu, as well as potentially to lower the availability guards to match the original implementation.

@0xTim I've also taken this opportunity to have the _CryptoExtras API export Crypto, so only one target is necessary. We should also discuss using the beta period to rename _CryptoExtras, and what that name should be.

[fpseverino]

Is there a planned minor release of swift-crypto before this major one? Because otherwise these "Compatibility" files would not be needed.

In any case, I could update the current implementation of MLKEM and MLDSA to use the future CryptoKit API and simplify everything a bit.

[Lukasa]

I think that would be a reasonable idea. As for a minor release, that's a good question. We could choose to do so, or not. Do you have a preference?

[fpseverino]

as well as potentially to lower the availability guards to match the original implementation.

I'm sorry, I didn't quite understand what you mean here. Could you break that down for me?

For ML-DSA, the minimum version was macOS 10.15 (because of CryptoKitError) and I see that it is still that.
As for ML-KEM, in my implementation the minimum version was macOS 14, because in CryptoKit the KEMPrivateKey and KEMPublicKey protocols require macOS 14 (though their versions in swift-crypto only require 10.15); now I see that the minimum version of ML-KEM has been lowered to 10.15.

[Lukasa]

The actual availability guards will have to be lifted to the 26 release cycle, as that is the availability of the CryptoKit implementations. As you've noted, the BoringSSL-backed implementations have more availability. One of the questions I have will be, can we offer a graceful way to opt in to lowering those guards. Is that even worth doing?

[fpseverino]

I think the answer to both questions will have to be the same.

As for a minor release, that's a good question. We could choose to do so, or not. Do you have a preference?

If the minimum required version of ML-DSA and ML-KEM will be raised in September, I don't know how much sense there is in releasing them now with a lower minimum required version, especially considering that many packages already depend on the "3.0.0"..<"5.0.0" version range. It could be a breaking change.

One of the questions I have will be, can we offer a graceful way to opt in to lowering those guards. Is that even worth doing?

On the other hand, it would be nice if these algorithms worked with pre v26 versions, but that would only be possible in Linux and platforms using BoringSSL, right? On Apple platforms it would still require v26, and that would create a discrepancy.

To conclude, in my opinion the simplest and clearest thing would be to release the new post-quantum algorithms with the API and availability guards they will have in CryptoKit.
I just hope that if this is the case, a beta of swift-crypto v4 will be released soon, so that we can start playing with it.

cc @ptoffy as a potential downstream customer who could use ML-DSA in JWTKit

[Lukasa]

That makes sense @fpseverino, thanks for that proposal. Yes, I'll try to take a beta shortly: I'll clean up the failing CI and then start a side branch for managing the beta releases.

[Lukasa]

I'm merging this into the tracking branch, over the API breakage check (which is expected).