Files
a9d1d5ab89 Merge the 5.x branch for the Swift Crypto 5.0 release (#470)
## 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>
2026-09-16 14:47:34 +01:00

6.2 KiB

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

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.