Swiftpack.co - Package - apple/swift-crypto

Swift Crypto

Swift Crypto is an open-source implementation of a substantial portion of the API of Apple CryptoKit suitable for use on Linux platforms. It enables cross-platform or server applications with the advantages of CryptoKit.

Functionality

Swift Crypto exposes the portions of the CryptoKit API that do not rely on specialised hardware to any Swift application. It provides safe APIs that abstract over the complexity of many cryptographic primitives that need to be used in modern applications. These APIs encourage safe usages of the underlying primitives, follow cryptographic best practices, and should be the first choice for building applications that need to use cryptography.

The current features of Swift Crypto cover key exchange, key derivation, encryption and decryption, hashing, message authentication, and more.

For specific API documentation, please see our documentation.

Implementation

Swift Crypto compiles in two distinct modes depending on the platform for which it is being built.

When building Swift Crypto for use on an Apple platform where CryptoKit is already available, Swift Crypto compiles its entire API surface down to nothing and simply re-exports the API of CryptoKit. This means that when using Apple platforms Swift Crypto simply delegates all work to the core implementation of CryptoKit, as though Swift Crypto was not even there.

When building Swift Crypto for use on Linux, Swift Crypto builds substantially more code. In particular, we build:

  1. A vendored copy of BoringSSL's libcrypto.
  2. The common API of Swift Crypto and CryptoKit.
  3. The backing implementation of this common API, which calls into BoringSSL.

The API code, and some cryptographic primitives which are directly implemented in Swift, are exactly the same for both Apple CryptoKit and Swift Crypto. The backing BoringSSL-based implementation is unique to Swift Crypto.

Evolution

The vast majority of the Swift Crypto code is intended to remain in lockstep with the current version of Apple CryptoKit. For this reason, patches that extend the API of Swift Crypto will be evaluated cautiously. For any such extension there are two possible outcomes for adding the API.

Firstly, if the API is judged to be generally valuable and suitable for contribution to Apple CryptoKit, the API will be merged into a Staging namespace in Swift Crypto. This Staging namespace is a temporary home for any API that is expected to become available in Apple CryptoKit but that is not available today. This enables users to use the API soon after merging. When the API is generally available in CryptoKit the API will be deprecated in the Staging namespace and made available in the main Swift Crypto namespace.

Secondly, if the API is judged not to meet the criteria for acceptance in general CryptoKit but is sufficiently important to have available for server use-cases, it will be merged into a Server namespace. APIs are not expected to leave this namespace, as it indicates that they are not generally available but can only be accessed when using Swift Crypto.

Note that Swift Crypto does not intend to support all possible cryptographic primitives. Swift Crypto will focus on safe, modern cryptographic primitives that are broadly useful and that do not easily lend themselves to misuse. This means that some cryptographic algorithms may never be supported: for example, 3DES is highly unlikely to ever be supported by Swift Crypto due to the difficulty of safely deploying it and its legacy status. Please be aware when proposing the addition of new primitives to Swift Crypto that the proposal may be refused for this reason.

Code Organisation

Files in this repository are divided into two groups, based on whether they have a name that ends in _boring or are in a BoringSSL directory, or if they are not.

Files that meet the above criteria are specific to the Swift Crypto implementation. Changes to these files can be made fairly easily, so long as they meet the criteria below. If your file needs to import CCryptoBoringSSL or access a BoringSSL API, it needs to be marked this way.

Files that do not have the _boring suffix are part of the public API of CryptoKit. Changing these requires passing a higher bar, as any change in these files must be accompanied by a change in CryptoKit itself.

Contributing

Before contributing please read CONTRIBUTING.md, also make sure to read the two following sections.

Contributing new primitives

To contribute a new cryptographic primitive to Swift Crypto, you should address the following questions:

  1. What is the new primitive for?
  2. How widely is it deployed?
  3. Is it specified in any public specifications or used by any such specification?
  4. How easy is it to misuse?
  5. In what way does Swift Crypto fail to satisfy that use-case today?

In addition, new primitive implementations will only be accepted in cases where the implementation is thoroughly tested, including being tested with all currently available test vectors. If the Wycheproof project provides vectors for the algorithm those should be tested as well. It must be possible to ensure that we can appropriately regression test our implementations.

Contributing bug fixes

If you discover a bug with Swift Crypto, please report it via GitHub.

If you are interested in fixing a bug, feel free to open a pull request. Please also submit regression tests with bug fixes to ensure that they are not regressed in future.

If you have issues with CryptoKit, instead of Swift Crypto, please use Feedback Assistant to file those issues as you normally would.

Get started contributing

gyb

Some of the files in this project are autogenerated (metaprogramming) using the Swift Utils tools called gyb ("generate your boilerplate"). gyb is included in ./scripts/gyb.

gyb will generate some Foobar.swift Swift file from some Foobar.swift.gyb template file. You should not edit Foobar.swift directly, since all manual edits in that generated file will be overwritten the next time gyb is run.

You run gyb for a single file like so:

./scripts/gyb --line-directive "" Sources/Foobar.swift.gyb -o Sources/Foobar.swift

More conveniently you can run the bash script ./scripts/generate_boilerplate_files_with_gyb.sh to generate all Swift files from their corresponding gyb template.

If you add a new .gyb file, you should append a // MARK: - Generated file, do NOT edit warning inside it, e.g.

// MARK: - Generated file, do NOT edit
// any edits of this file WILL be overwritten and thus discarded
// see section `gyb` in `README` for details.

Security

If you believe you have identified a vulnerability in Swift Crypto, please report that vulnerability to Apple through the usual channel.

Swift versions

Swift Crypto supports Swift 5.1 and later.

Compatibility

Swift Crypto follows SemVer 2.0.0. Our public API is the same as that of CryptoKit (except where we lack an implementation entirely), as well as everything in the Server and Staging namespaces. We do not maintain a stable ABI, as Swift Crypto is a source-only distribution.

What this means for you is that you should depend on Swift Crypto with a version range that covers everything from the minimum Swift Crypto version you require up to the next major version. In SwiftPM that can be easily done specifying for example from: "1.0.0" meaning that you support Swift Crypto in every version starting from 1.0.0 up to (excluding) 2.0.0. SemVer and Swift Crypto's Public API guarantees should result in a working program without having to worry about testing every single version for compatibility.

Developing Swift Crypto on macOS

Swift Crypto normally defers to the OS implementation of CryptoKit on macOS. Naturally, this makes developing Swift Crypto on macOS tricky. To get Swift Crypto to build the open source implementation on macOS, in Package.swift, uncomment the line that reads: //.define("CRYPTO_IN_SWIFTPM_FORCE_BUILD_API"), as this will force Swift Crypto to build its public API.

Github

link
Stars: 941

Dependencies

Used By

Total: 0

Releases

Swift Crypto 1.1.2 -

Semver Patch

  • Silence a compiler warning on Linux. (#52, patch credit to @YOCKOW)

SwiftCrypto 1.1.1 -

Semver Patch

  • Updated BoringSSL to 67818bea6690a230e2f42e8a588e0f54949bbbf1 (#50)

Other

  • Moved development to the main branch. (#49)

Swift Crypto 1.1.0 -

Semver Minor

  • Support for PEM/DER serialisation for asymmetric key types.
  • Support for HKDF expand/extract.
  • Brings API up to date with iOS 14.

Semver Patch

  • Updated to BoringSSL 54858b63c1d886f6c8d903d4a4f594f1485de189. (#47)
  • Updated ECDSA signature code to use pure-Swift ASN.1 parsing/serialization.
  • Fixed test running on Android. (#41) (patch credit to @buttaface)
  • Documentation improvements. (#42, #44) (patch credit to @0xTim)

Swift Crypto 1.1.0 RC 2 -

Semver Patch

  • Updated ECDSA signature code to use pure-Swift ASN.1 parsing/serialization. (#46)
  • Fixed test running on Android. (#41) (patch credit to @buttaface)
  • Updated to BoringSSL 54858b63c1d886f6c8d903d4a4f594f1485de189. (#47)
  • Documentation improvements. (#42, #44) (patch credit to @0xTim)

Please note that this release is a release-candidate. We will be shipping release candidates all the way until the final release of the Apple platform SDKs this fall. These are deliberately excluded from the regular semantic versioning scheme as these APIs remain subject to change, just as they are on Apple's platform SDKs.

Swift Crypto 1.1.0 RC 1 -

Semver Minor

  • Support for PEM/DER serialisation for asymmetric key types.
  • Support for HKDF expand/extract.
  • Brings API up to date with WWDC seed of Apple platforms.

Please note that this release is a release-candidate. We will be shipping release candidates all the way until the final release of the Apple platform SDKs this fall. These are deliberately excluded from the regular semantic versioning scheme as these APIs remain subject to change, just as they are on Apple's platform SDKs.

Swift Crypto 1.0.2 -

Semver Patch

  • CI improvements. (#32, #35)
  • Updated BoringSSL to 53a17f55247101105ae35767d5c5a6c311843a8e. (#36)

Swift Crypto 1.0.1 -

Semver Patch

  • Fixed compiler issue that could occur when linking with projects that declare jemalloc functions that don't exist, such as Folly. (#28)
  • Updated BoringSSL to 5298ef99bf2b2d77600b3bb74dd572027bf495be. (#31)
  • Improved usage of XCTest. (#15, thanks to @ZevEisenberg)
  • Improved markdown rendering in Xcode. (#11, thanks to @Sajjon)
  • Helped CI validate that the gyb is kept intact. (#17, thanks to @Sajjon)
  • Added marks within gyb generated files. (#19, thanks to @Sajjon)
  • Cleaned up links in readme. (#10, thanks to @AustinConlon)
  • Improved project name rendering in readme. (#12)
  • Readme typo fixes. (#16)
  • More consistent references to contributors in Git history. (#14)
  • Better GitHub issue template. (#7, #21 thanks to @Sajjon)
  • Helped GitHub statistics be aware that BoringSSL is a vendored copy. (#17, thanks to @sindresorhus)
  • Corrected references to contributors file. (#24, thanks to @Sajjon)
  • Better docker setup. (#6, #30)