## Motivation Xcode 27 is now available[^1] so it's time to merge in our 5.x branch to main and release 5.0. ## Modifications See "Release Notes" section below for overview of changes and links to the PRs that landed on the 5.x branch during the beta period. ## Result The main branch will be ready to tag a 5.0 release. [^1]: https://developer.apple.com/download/all/?q=Xcode%2027 --- ## Release Notes Swift Crypto 5.0 aligns the cross-platform API surface with CryptoKit as shipped in Xcode 27 (CryptoKit-383.2.1), and takes the opportunity to streamline the package for both adopters and maintainers. Most users will be able to depend on the 1.0.0, 2.0.0, 3.0.0, 4.0.0, or 5.0.0 series of releases. To do so, please use the following dependency in your `Package.swift`: ```swift .package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "6.0.0"), ``` ### Requires Swift 6.2 The package now declares 6.2 as the minimum Swift version in its package manifest. ### New span-based API CryptoKit's new non-allocating, span-based entry points are now available cross-platform: - `SymmetricKey` gains `bytes: RawSpan`, `init(copying: RawSpan)`, `init(copyingWithZeroing: inout MutableRawSpan)`, and `init(size:initializingWith:)` which initializes the key through an `inout OutputRawSpan`. - `HashFunction` gains `update(bytes: RawSpan)` and `hash(bytes: RawSpan)`, and `Digest` gains `init?(copying: RawSpan)`. - `HMAC` gains `authenticationCode(for: RawSpan, using:)`. - `HKDF` gains `deriveKey(inputKeyMaterial:salt:info:output:)` writing into an `inout OutputRawSpan`, along with span-based `extract` and `expand`. The existing `DataProtocol` overload now has a fast path for contiguous salt and info. - `AES.GCM` and `ChaChaPoly` gain in-place `seal(inPlace:using:nonce:authenticating:tag:)` and `open(inPlace:using:nonce:authenticating:tag:)` over `MutableRawSpan`, and their `Nonce` types gain `bytes: RawSpan` and `init(copying: RawSpan)`. ### Single-use KEM keys A new `KEMOneTimePrivateKey` protocol, refining `~Copyable` and `Sendable`, provides a `consuming func decapsulate(_:)` so a decapsulation key cannot be reused. Conforming types are `MLKEM768.OneTimePrivateKey`, `MLKEM1024.OneTimePrivateKey`, and `XWingMLKEM768X25519.OneTimePrivateKey`. ### Extensible enums Historically Swift Crypto needed a new major version each time CryptoKit added a case to a non-frozen enum, because Swift Crypto is not built with library evolution. All public non-frozen enums are now marked `@nonexhaustive` (SE-0487), which should remove that reason for future major bumps. Adopters who do not switch over these enums should not need to widen their version constraints again. ### Other changes - Symbols that were previously marked `@_spi(...) public` have been made internal; they were never intended to be available. - `@available` annotations have been removed from `Crypto`; they are unused in all supported compilation modes. - Some internal reference types are now marked `final` - Some unused code, e.g. `ECDSASignature.derBytes`, is removed. ### Build and packaging - The `CCryptoBoringSSLShims` target is removed, along with all `bindMemory(to:)` calls. - The `.gyb` templates for nonces, digests, ECDH, ECDSA, MLDSA, and MLKEM are removed and the generated Swift is checked in. The BoringSSL backend templates for MLDSA and MLKEM remain. - Conditional compilation is simplified to `#if canImport(CryptoKit)`; branches that could never be taken are gone. - Developing the BoringSSL backend on macOS is no longer supported. Use the Dev Container configuration now shipped in the repository, or build on the target platform. - Warnings are silenced for vendored C sources: `-Wshorten-64-to-32` for BoringSSL and `macro-redefined` for XKCP. CI builds with `-warnings-as-errors`. ### Commits The changes in this release were reviewed and merged to the 5.x branch during the beta period: -0a26a9e3[5.x] Align with CryptoKit APIs from Xcode 27 beta 1 (#442) -8ee9962f[5.x] Align with CryptoKit APIs from Xcode 27 beta 2 (#444) -ce8db476[5.x] Align with CryptoKit APIs from Xcode 27 beta 4 (#453) -15b0fb5b[5.x] Adopt CheckImplementationOnly and CI with -warnings-as-errors (#454) -b3746b14[5.x] Remove bindMemory(to:) calls and the CCryptoBoringSSLShims target (#455) -57782dc6[5.x] Remove duplicate imports from gyb-generated MLDSA backend code (#458) -2c45ca2f[5.x] Remove unused internal code path: ECDSASignature.derBytes (#457) -33785f67[5.x] Mark some class types as final (#456) -2e074efb[5.x] Remove native SwiftPM build-system workaround in CI (#461) -20f90497[5.x] Align with CryptoKit from Xcode 27 beta 6 (#462) --------- Co-authored-by: Dmitry <45711841+darkdi@users.noreply.github.com> Co-authored-by: Cory Benfield <lukasa@apple.com>
6.2 KiB
Legal
By submitting a pull request, you represent that you have the right to license
your contribution to Apple and the community, and agree by submitting the patch
that your contributions are licensed under the Apache 2.0 license (see
LICENSE.txt).
AI tools
Human discourse is an essential part of open source development. To encourage productive collaboration between contributors and maintainers, please refrain from using AI tools for the following:
- Issues: titles, bodies, and comments.
- Pull requests: titles, descriptions, and comments.
Contributors who feel more comfortable writing in another language may use automated translation tools, but must include their original content in their preferred language.
How to submit a bug report
Please ensure to specify the following:
- swift-crypto commit hash
- Contextual information (e.g. what you were trying to achieve with swift-crypto)
- Simplest possible steps to reproduce
- More complex the steps are, lower the priority will be.
- A pull request with failing test case is preferred, but it's just fine to paste the test case into the issue description.
- Anything that might be relevant in your opinion, such as:
- Swift version or the output of
swift --version - OS version and the output of
uname -a
- Swift version or the output of
Example
swift-crypto commit hash: 22ec043dc9d24bb011b47ece4f9ee97ee5be2757
Context:
While using HMAC<SHA256> to verify received data I noticed that we leaked 1kB of memory per invocation.
Steps to reproduce:
1. ...
2. ...
3. ...
4. ...
$ swift --version
Swift version 5.1.2 (swift-5.1.2-RELEASE)
Target: x86_64-unknown-linux-gnu
Operating system: Ubuntu Linux 16.04 64-bit
$ uname -a
Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux
Contributing a pull request
Important
To ensure productive use of contributor and maintainer time and resources, contributors must first agree their proposed change with a maintainer in an issue. Pull requests opened without prior discussion may be closed without review.
If there is no issue already tracking the problem or feature request, please file a new one using your own voice (see "AI tools" usage above).
Once an issue is assigned to you, follow these steps:
- Prepare your change, keeping in mind that a good patch is:
- Concise, and contains as few changes as needed to achieve the end result.
- Tested, ensuring that any tests provided failed before the patch and pass after it.
- Documented, adding API documentation as needed to cover new functions and properties.
- Accompanied by a great commit message.
- Open a pull request and wait for code review by the maintainers.
How to update CMakeLists files
If you wish to update the CMakeLists files you can either do this by using act or calling the remotely hosted CI script.
Issuing a command such as the following to act causes it to run the cmake-lists job locally which updates the CMakeLists files and if it finds no changes performs a build. The --bind flag means that the VM be acts on your local filesystem so be aware that this could delete/change files (including your git setup/branches).
act --container-architecture linux/amd64 pull_request -j cmake-lists -W ./.github/workflows/pull_request.yml --bind
You can find the underlying script at https://github.com/apple/swift-nio/blob/main/scripts/update-cmake-lists.sh . Using the script directly is less straightforwards because it requires you to pass the JSON config from the pull_request.yml file into the script, such as:
curl -s https://raw.githubusercontent.com/apple/swift-nio/main/scripts/update-cmake-lists.sh | CONFIG_JSON='{"targets":[{"name":"CCryptoBoringSSL","type":"source","exceptions":[]},{"name":"CryptoBoringWrapper","type":"source","exceptions":[]},{"name":"Crypto","type":"source","exceptions":[]},{"name":"CryptoExtras","type":"source","exceptions":[]},{"name":"CCryptoBoringSSL","type":"assembly","exceptions":["*/AES/*.swift"]}]}' bash
API Evolution
swift-crypto is a unique project in that it is an open-source reimplementation of APIs provided by an Apple system library. For this reason, it is intended to remain compatible with those APIs.
As a result, while we will discuss and in many cases accept additive changes to the API, these changes will potentially get handled in multiple different ways.
If an API is considered worth adding to the system CryptoKit library, we will initially merge it but not ship it in a tagged release. If it's important to use this API early, we will use a transitional namespace that is only present in the swift-crypto library to make the feature available until it can make its way into the OS proper.
Some use-cases will not meet the requirements of CryptoKit itself, but will still be useful for server use-cases. Where the swift-crypto team believe it is possible to craft good, misuse-resistant APIs for the functionality, we will consider adding these APIs under a Server namespace. This will make it clear that CryptoKit is not intending to support these use-cases, and so they will never graduate to the mainstream namespace.
Please do consider proposing new API: we'll take these on a case-by-case basis. Where we elect not to support a given primitive, we will provide a detailed rationale for why we believe it is out of scope.
Proposing New API
When you propose new API, it would help to fill out the following template. This will allow us to get a better understanding of the scope of the proposal and the utility it provides.
New API Template
### New API Proposal: <Feature Name>
Motivation:
<What use-case is this API proposal trying to serve? Are there any protocols in existence that require this API? If so, which? Please provide links to specifications where applicable, or peer implementations when attempting to perform interop work.>
Importance:
<Does this API unlock entirely new use-cases, or is it possible to achieve the same functionality with existing API, but in easier ways?>
BoringSSL Restrictions
New APIs must be able to be implemented on top of BoringSSL: that is, BoringSSL must have an implementation that we can use.