Update README for 4.0 release (#418)

This commit is contained in:
Cory Benfield authored and GitHub committed 2025-10-06 15:02:13 +01:00
1 parent 431013afaf
commit bcd2b89f2a
9 files changed
+10 -560

No files matched your search

+10 -5
View File
@@ -7,9 +7,9 @@ Swift Crypto is an open-source implementation of a substantial portion of the AP
Swift Crypto is available as a Swift Package Manager package. To use it, add the following dependency in your `Package.swift`:
```swift
// swift-crypto 1.x, 2.x and 3.x are almost API compatible, so most clients
// swift-crypto 1.x, 2.x, 3.x, and 4.x are almost API compatible, so most clients
// should allow any of them
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "4.0.0"),
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "5.0.0"),
```
and to your target, add `Crypto` to your dependencies. You can then `import Crypto` to get access to Swift Crypto's functionality.
@@ -108,7 +108,7 @@ If you believe you have identified a vulnerability in Swift Crypto, please [repo
### Swift versions
The most recent versions of Swift Crypto support Swift 5.7 and newer. The minimum Swift version supported by Swift Crypto releases are detailed below:
The most recent versions of Swift Crypto support Swift 6 and newer. The minimum Swift version supported by Swift Crypto releases are detailed below:
Swift Crypto | Minimum Swift Version
--------------------|----------------------
@@ -119,7 +119,8 @@ Swift Crypto | Minimum Swift Version
`3.1.0 ..< 3.3.0` | 5.7
`3.3.0 ..< 3.8.0` | 5.8
`3.9.0 ..< 3.13.0` | 5.9
`3.13.0 ...` | 5.10
`3.13.0 ..< 4.0.0` | 5.10
`4.0.0 ...` | 6.0
### Compatibility
@@ -131,10 +132,14 @@ SemVer and Swift Crypto's Public API guarantees should result in a working progr
Swift Crypto 2.0.0 was released in September 2021. The only breaking change between Swift Crypto 2.0.0 and 1.0.0 was the addition of new cases in the `CryptoError` enumeration. For most users, then, it's safe to depend on either the 1.0.0 _or_ 2.0.0 series of releases.
Swift Crypto 3.0.0 was released in September 2023. Again the only breaking change was the addition of new cases in the `CryptoError` enumeration, so most users can safely depend on the 1.0.0, 2.0.0, or 3.0.0 series of releases.
Swift Crypto 4.0.0 was released in September 2025. Again the only breaking change was the addition of new cases in the `CryptoError` enumeration, so most users can safely depend on the 1.0.0, 2.0.0, 3.0.0, or 4.0.0 series of releases. Note that in this release `_CryptoExtras` was renamed to `CryptoExtras`. The old products and targets have been kept around for compatibility reasons, but users depending only on new code should use `CryptoExtras` not `_CryptoExtras`.
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" ..< "3.0.0"),
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "5.0.0"),
```
### Developing Swift Crypto on macOS
@@ -1,37 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import SwiftASN1
extension ASN1ObjectIdentifier.AlgorithmIdentifier {
// Identifies the key agreement algorithm X25519.
//
// This identifier is defined in RFC 8410
static let idX25519: ASN1ObjectIdentifier = [1, 3, 101, 110]
// Identifies the key agreement algorithm X448.
//
// This identifier is defined in RFC 8410
static let idX448: ASN1ObjectIdentifier = [1, 3, 101, 111]
// Identifies the signature algorithm Ed25519.
//
// This identifier is defined in RFC 8410
static let idEd25519: ASN1ObjectIdentifier = [1, 3, 101, 112]
// Identifies the signature algorithm Ed448.
//
// This identifier is defined in RFC 8410
static let idEd448: ASN1ObjectIdentifier = [1, 3, 101, 113]
}
@@ -1,76 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Crypto
import Foundation
import SwiftASN1
@available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *)
extension Curve25519.Signing.PrivateKey {
/// A Distinguished Encoding Rules (DER) encoded representation of the private key in PKCS#8 format.
public var pkcs8DERRepresentation: Data {
let pkey = ASN1.PKCS8PrivateKey(algorithm: .ed25519, privateKey: Array(self.rawRepresentation))
var serializer = DER.Serializer()
// Serializing this key can't throw
try! serializer.serialize(pkey)
return Data(serializer.serializedBytes)
}
}
@available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *)
extension Curve25519.KeyAgreement.PrivateKey {
/// A Distinguished Encoding Rules (DER) encoded representation of the private key in PKCS#8 format.
public var pkcs8DERRepresentation: Data {
let pkey = ASN1.PKCS8PrivateKey(algorithm: .x25519, privateKey: Array(self.rawRepresentation))
var serializer = DER.Serializer()
// Serializing this key can't throw
try! serializer.serialize(pkey)
return Data(serializer.serializedBytes)
}
}
@available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *)
extension P256.Signing.PrivateKey {
/// A Distinguished Encoding Rules (DER) encoded representation of the private key in PKCS#8 format.
///
/// This property provides the same output as the existing `derRepresentation` property,
/// which already conforms to the PKCS#8 standard.
public var pkcs8DERRepresentation: Data {
self.derRepresentation
}
}
@available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *)
extension P384.Signing.PrivateKey {
/// A Distinguished Encoding Rules (DER) encoded representation of the private key in PKCS#8 format.
///
/// This property provides the same output as the existing `derRepresentation` property,
/// which already conforms to the PKCS#8 standard.
public var pkcs8DERRepresentation: Data {
self.derRepresentation
}
}
@available(iOS 14.0, macOS 11.0, watchOS 7.0, tvOS 14.0, *)
extension P521.Signing.PrivateKey {
/// A Distinguished Encoding Rules (DER) encoded representation of the private key in PKCS#8 format.
///
/// This property provides the same output as the existing `derRepresentation` property,
/// which already conforms to the PKCS#8 standard.
public var pkcs8DERRepresentation: Data {
self.derRepresentation
}
}
@@ -1,93 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import Crypto
import SwiftASN1
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension ASN1 {
// A PKCS#8 private key is one of two formats, depending on the version:
//
// For PKCS#8 we need the following for the private key:
//
// PrivateKeyInfo ::= SEQUENCE {
// version Version,
// privateKeyAlgorithm PrivateKeyAlgorithmIdentifier,
// privateKey PrivateKey,
// attributes [0] IMPLICIT Attributes OPTIONAL }
//
// Version ::= INTEGER
//
// PrivateKeyAlgorithmIdentifier ::= AlgorithmIdentifier
//
// PrivateKey ::= OCTET STRING
//
// Attributes ::= SET OF Attribute
//
// We disregard the attributes because we don't support them anyway.
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
struct PKCS8PrivateKey: DERImplicitlyTaggable {
static var defaultIdentifier: ASN1Identifier {
.sequence
}
var algorithm: RFC8410AlgorithmIdentifier
var privateKey: ASN1OctetString
init(derEncoded rootNode: ASN1Node, withIdentifier identifier: ASN1Identifier) throws {
self = try DER.sequence(rootNode, identifier: identifier) { nodes in
let version = try Int(derEncoded: &nodes)
guard version == 0 || version == 1 else {
throw ASN1Error.invalidASN1Object(reason: "Version number mismatch")
}
let algorithm = try ASN1.RFC8410AlgorithmIdentifier(derEncoded: &nodes)
let privateKeyBytes = try ASN1OctetString(derEncoded: &nodes)
// We ignore the attributes
_ = try DER.optionalExplicitlyTagged(&nodes, tagNumber: 0, tagClass: .contextSpecific) { _ in }
let privateKeyNode = try DER.parse(privateKeyBytes.bytes)
let privateKey = try ASN1OctetString(derEncoded: privateKeyNode)
return try .init(algorithm: algorithm, privateKey: privateKey)
}
}
private init(algorithm: ASN1.RFC8410AlgorithmIdentifier, privateKey: ASN1OctetString) throws {
self.privateKey = privateKey
self.algorithm = algorithm
}
init(algorithm: ASN1.RFC8410AlgorithmIdentifier, privateKey: [UInt8]) {
self.algorithm = algorithm
self.privateKey = ASN1OctetString(contentBytes: privateKey[...])
}
func serialize(into coder: inout DER.Serializer, withIdentifier identifier: ASN1Identifier) throws {
try coder.appendConstructedNode(identifier: identifier) { coder in
try coder.serialize(0)
try coder.serialize(self.algorithm)
// Here's a weird one: we recursively serialize the private key, and then turn the bytes into an octet string.
var subCoder = DER.Serializer()
try subCoder.serialize(self.privateKey)
let serializedKey = ASN1OctetString(contentBytes: subCoder.serializedBytes[...])
try coder.serialize(serializedKey)
}
}
}
}
@@ -1,74 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import SwiftASN1
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension ASN1 {
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
struct RFC8410AlgorithmIdentifier: DERImplicitlyTaggable, Hashable {
static var defaultIdentifier: ASN1Identifier {
.sequence
}
var algorithm: ASN1ObjectIdentifier
// RFC 8410: For all of these OIDs, the parameters MUST be absent.
// They are still part of the identifer block.
var parameters: ASN1Any?
init(algorithm: ASN1ObjectIdentifier, parameters: ASN1Any?) {
self.algorithm = algorithm
self.parameters = parameters
}
init(derEncoded rootNode: ASN1Node, withIdentifier identifier: ASN1Identifier) throws {
// The AlgorithmIdentifier block looks like this.
//
// AlgorithmIdentifier ::= SEQUENCE {
// algorithm OBJECT IDENTIFIER,
// parameters ANY DEFINED BY algorithm OPTIONAL
// }
//
// We don't bother with helpers: we just try to decode it directly.
self = try DER.sequence(rootNode, identifier: identifier) { nodes in
let algorithmOID = try ASN1ObjectIdentifier(berEncoded: &nodes)
let parameters = nodes.next().map { ASN1Any(berEncoded: $0) }
return .init(algorithm: algorithmOID, parameters: parameters)
}
}
func serialize(into coder: inout DER.Serializer, withIdentifier identifier: ASN1Identifier) throws {
try coder.appendConstructedNode(identifier: identifier) { coder in
try coder.serialize(self.algorithm)
if let parameters = self.parameters {
try coder.serialize(parameters)
}
}
}
}
}
@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
extension ASN1.RFC8410AlgorithmIdentifier {
static let x25519 = ASN1.RFC8410AlgorithmIdentifier(algorithm: .AlgorithmIdentifier.idX25519, parameters: nil)
static let x448 = ASN1.RFC8410AlgorithmIdentifier(algorithm: .AlgorithmIdentifier.idX448, parameters: nil)
static let ed25519 = ASN1.RFC8410AlgorithmIdentifier(algorithm: .AlgorithmIdentifier.idEd25519, parameters: nil)
static let ed448 = ASN1.RFC8410AlgorithmIdentifier(algorithm: .AlgorithmIdentifier.idEd448, parameters: nil)
}
@@ -1,35 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2017-2014 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
protocol ThreadOps {
associatedtype ThreadSpecificKey
associatedtype ThreadSpecificKeyDestructor
static func allocateThreadSpecificValue(destructor: ThreadSpecificKeyDestructor) -> ThreadSpecificKey
static func deallocateThreadSpecificValue(_ key: ThreadSpecificKey)
static func getThreadSpecificValue(_ key: ThreadSpecificKey) -> UnsafeMutableRawPointer?
static func setThreadSpecificValue(key: ThreadSpecificKey, value: UnsafeMutableRawPointer?)
}
@@ -1,73 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2020 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
#if os(Linux) || os(Android) || os(FreeBSD) || os(OpenBSD) || canImport(Darwin)
#if canImport(Glibc)
@preconcurrency import Glibc
#elseif canImport(Bionic)
@preconcurrency import Bionic
#elseif canImport(Musl)
@preconcurrency import Musl
#elseif canImport(Android)
@preconcurrency import Android
#elseif canImport(Darwin)
import Darwin
#endif
typealias ThreadOpsSystem = ThreadOpsPosix
enum ThreadOpsPosix: ThreadOps {
typealias ThreadSpecificKey = pthread_key_t
#if canImport(Darwin)
typealias ThreadSpecificKeyDestructor = @convention(c) (UnsafeMutableRawPointer) -> Void
#else
typealias ThreadSpecificKeyDestructor = @convention(c) (UnsafeMutableRawPointer?) -> Void
#endif
static func allocateThreadSpecificValue(destructor: @escaping ThreadSpecificKeyDestructor) -> ThreadSpecificKey {
var value = pthread_key_t()
let result = pthread_key_create(&value, Optional(destructor))
precondition(result == 0, "pthread_key_create failed: \(result)")
return value
}
static func deallocateThreadSpecificValue(_ key: ThreadSpecificKey) {
let result = pthread_key_delete(key)
precondition(result == 0, "pthread_key_delete failed: \(result)")
}
static func getThreadSpecificValue(_ key: ThreadSpecificKey) -> UnsafeMutableRawPointer? {
pthread_getspecific(key)
}
static func setThreadSpecificValue(key: ThreadSpecificKey, value: UnsafeMutableRawPointer?) {
let result = pthread_setspecific(key, value)
precondition(result == 0, "pthread_setspecific failed: \(result)")
}
}
#endif
@@ -1,111 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2019-2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
// Derived from swift-nio's ThreadSpecificVariable type.
/// A ``ThreadSpecificVariable`` is a variable that can be read and set like a normal variable except that it holds
/// different variables per thread.
///
/// ``ThreadSpecificVariable`` is thread-safe so it can be used with multiple threads at the same time but the value
/// returned by ``currentValue`` is defined per thread.
///
/// - Note: Though ``ThreadSpecificVariable`` is thread-safe, it is not `Sendable` unless `Value` is `Sendable`.
/// If ``ThreadSpecificVariable`` were unconditionally `Sendable`, it could be used to "smuggle"
/// non-`Sendable` state out of an actor or other isolation domain without triggering warnings. If you
/// are attempting to use ``ThreadSpecificVariable`` with non-`Sendable` data, consider using a dynamic
/// enforcement tool like `NIOLoopBoundBox` to police the access.
final class ThreadSpecificVariable<Value: AnyObject> {
// the actual type in there is `Box<(ThreadSpecificVariable<T>, T)>` but we can't use that as C functions can't capture (even types)
private typealias BoxedType = Box<(AnyObject, AnyObject)>
private class Key {
private var underlyingKey: ThreadOpsSystem.ThreadSpecificKey
internal init(destructor: @escaping ThreadOpsSystem.ThreadSpecificKeyDestructor) {
self.underlyingKey = ThreadOpsSystem.allocateThreadSpecificValue(destructor: destructor)
}
deinit {
ThreadOpsSystem.deallocateThreadSpecificValue(self.underlyingKey)
}
func get() -> UnsafeMutableRawPointer? {
ThreadOpsSystem.getThreadSpecificValue(self.underlyingKey)
}
func set(value: UnsafeMutableRawPointer?) {
ThreadOpsSystem.setThreadSpecificValue(key: self.underlyingKey, value: value)
}
}
private let key: Key
/// Initialize a new `ThreadSpecificVariable` without a current value (`currentValue == nil`).
init() {
self.key = Key(destructor: {
Unmanaged<BoxedType>.fromOpaque(($0 as UnsafeMutableRawPointer?)!).release()
})
}
/// Initialize a new `ThreadSpecificVariable` with `value` for the calling thread. After calling this, the calling
/// thread will see `currentValue == value` but on all other threads `currentValue` will be `nil` until changed.
///
/// - Parameters:
/// - value: The value to set for the calling thread.
convenience init(value: Value) {
self.init()
self.currentValue = value
}
/// The value for the current thread.
@available(
*,
noasync,
message: "threads can change between suspension points and therefore the thread specific value too"
)
var currentValue: Value? {
get {
self.get()
}
set {
self.set(newValue)
}
}
/// Get the current value for the calling thread.
private func get() -> Value? {
guard let raw = self.key.get() else { return nil }
// parenthesize the return value to silence the cast warning
return
(Unmanaged<BoxedType>
.fromOpaque(raw)
.takeUnretainedValue()
.value.1 as! Value)
}
/// Set the current value for the calling threads. The `currentValue` for all other threads remains unchanged.
private func set(_ newValue: Value?) {
if let raw = self.key.get() {
Unmanaged<BoxedType>.fromOpaque(raw).release()
}
self.key.set(value: newValue.map { Unmanaged.passRetained(Box((self, $0))).toOpaque() })
}
}
extension ThreadSpecificVariable: @unchecked Sendable where Value: Sendable {}
final class Box<T> {
let value: T
init(_ value: T) { self.value = value }
}
@@ -1,56 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCrypto open source project
//
// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2020 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
#if os(Windows)
import WinSDK
typealias ThreadOpsSystem = ThreadOpsWindows
enum ThreadOpsWindows: ThreadOps {
typealias ThreadSpecificKey = DWORD
typealias ThreadSpecificKeyDestructor = @convention(c) (UnsafeMutableRawPointer?) -> Void
static func allocateThreadSpecificValue(destructor: @escaping ThreadSpecificKeyDestructor) -> ThreadSpecificKey {
FlsAlloc(destructor)
}
static func deallocateThreadSpecificValue(_ key: ThreadSpecificKey) {
let dwResult: Bool = FlsFree(key)
precondition(dwResult, "FlsFree: \(GetLastError())")
}
static func getThreadSpecificValue(_ key: ThreadSpecificKey) -> UnsafeMutableRawPointer? {
FlsGetValue(key)
}
static func setThreadSpecificValue(key: ThreadSpecificKey, value: UnsafeMutableRawPointer?) {
FlsSetValue(key, value)
}
}
#endif