Swiftpack.co - Package - krzyzanowskim/CryptoSwift

Platform

Swift support CocoaPods Compatible Carthage compatible Accio supported Swift Package Manager compatible

Twitter

CryptoSwift

Crypto related functions and helpers for Swift implemented in Swift. (#PureSwift)

Note: The master branch follows the latest currently released version of Swift. If you need an earlier version for an older version of Swift, you can specify its version in your Podfile or use the code on the branch for that version. Older branches are unsupported. Check versions for details.


Requirements | Features | Contribution | Installation | Swift versions | How-to | Author | License | Changelog

Sponsorship

If you (or your Company) use this work, please consider Sponsorship. This is the only option to keep the project alive, that is in your own best interrest.

CryptoSwift isn't backed by a big company and is developer in my spare time that I also use to as a freelancer.

Requirements

Good mood

Features

  • Easy to use
  • Convenient extensions for String and Data
  • Support for incremental updates (stream, ...)
  • iOS, Android, macOS, AppleTV, watchOS, Linux support

Hash (Digest)

MD5 | SHA1 | SHA224 | SHA256 | SHA384 | SHA512 | SHA3

Cyclic Redundancy Check (CRC)

CRC32 | CRC32C | CRC16

Cipher

AES-128, AES-192, AES-256 | ChaCha20 | Rabbit | Blowfish

Message authenticators

Poly1305 | HMAC (MD5, SHA1, SHA256) | CMAC | CBC-MAC

Cipher mode of operation

  • Electronic codebook (ECB)
  • Cipher-block chaining (CBC)
  • Propagating Cipher Block Chaining (PCBC)
  • Cipher feedback (CFB)
  • Output Feedback (OFB)
  • Counter Mode (CTR)
  • Galois/Counter Mode (GCM)
  • Counter with Cipher Block Chaining-Message Authentication Code (CCM)

Password-Based Key Derivation Function

  • PBKDF1 (Password-Based Key Derivation Function 1)
  • PBKDF2 (Password-Based Key Derivation Function 2)
  • HKDF (HMAC-based Extract-and-Expand Key Derivation Function)
  • Scrypt (The scrypt Password-Based Key Derivation Function)

Data padding

PKCS#5 | PKCS#7 | Zero padding | ISO78164 | No padding

Authenticated Encryption with Associated Data (AEAD)

Why

Why? Because I can.

How do I get involved?

You want to help, great! Go ahead and fork our repo, make your changes and send us a pull request.

Contribution

Check out CONTRIBUTING.md for more information on how to help with CryptoSwift.

Installation

To install CryptoSwift, add it as a submodule to your project (on the top level project directory):

git submodule add https://github.com/krzyzanowskim/CryptoSwift.git

It is recommended to enable Whole-Module Optimization to gain better performance. Non-optimized build results in significantly worse performance.

Embedded Framework

Embedded frameworks require a minimum deployment target of iOS 8 or OS X Mavericks (10.9). Drag the CryptoSwift.xcodeproj file into your Xcode project, and add appropriate framework as a dependency to your target. Now select your App and choose the General tab for the app target. Find Embedded Binaries and press "+", then select CryptoSwift.framework (iOS, OS X, watchOS or tvOS)

Sometimes "embedded framework" option is not available. In that case, you have to add new build phase for the target

iOS, macOS, watchOS, tvOS

In the project, you'll find single scheme for all platforms:

  • CryptoSwift

Swift versions support

  • Swift 1.2: branch swift12 version <= 0.0.13
  • Swift 2.1: branch swift21 version <= 0.2.3
  • Swift 2.2, 2.3: branch swift2 version <= 0.5.2
  • Swift 3.1, branch swift3 version <= 0.6.9
  • Swift 3.2, branch swift32 version = 0.7.0
  • Swift 4.0, branch swift4 version <= 0.12.0
  • Swift 4.2, branch swift42 version <= 0.15.0
  • Swift 5.0, branch swift5 version <= 1.2.0
  • Swift 5.1 and newer, branch master

CocoaPods

You can use CocoaPods.

pod 'CryptoSwift', '~> 1.0'

Bear in mind that CocoaPods will build CryptoSwift without Whole-Module Optimization that may impact performance. You can change it manually after installation, or use cocoapods-wholemodule plugin.

Carthage

You can use Carthage. Specify in Cartfile:

github "krzyzanowskim/CryptoSwift"

Run carthage to build the framework and drag the built CryptoSwift.framework into your Xcode project. Follow build instructions. Common issues.

Swift Package Manager

You can use Swift Package Manager and specify dependency in Package.swift by adding this:

.package(url: "https://github.com/krzyzanowskim/CryptoSwift.git", .upToNextMinor(from: "1.0"))

See: Package.swift - manual

Accio

You can use Accio. Specify in Package.swift:

.package(url: "https://github.com/krzyzanowskim/CryptoSwift.git", .upToNextMajor(from: "1.0")),

Then run accio update.


How-to

also check Playground

Basics
import CryptoSwift

CryptoSwift uses array of bytes aka Array<UInt8> as a base type for all operations. Every data may be converted to a stream of bytes. You will find convenience functions that accept String or Data, and it will be internally converted to the array of bytes.

Data types conversion

For your convenience, CryptoSwift provides two functions to easily convert an array of bytes to Data or Data to an array of bytes:

Data from bytes:

let data = Data( [0x01, 0x02, 0x03])

Data to Array<UInt8>

let bytes = data.bytes                     // [1,2,3]

Hexadecimal encoding:

let bytes = Array<UInt8>(hex: "0x010203")  // [1,2,3]
let hex   = bytes.toHexString()            // "010203"

Build bytes out of String

let bytes: Array<UInt8> = "cipherkey".bytes  // Array("cipherkey".utf8)

Also... check out helpers that work with Base64 encoded data:

"aPf/i9th9iX+vf49eR7PYk2q7S5xmm3jkRLejgzHNJs=".decryptBase64ToString(cipher)
"aPf/i9th9iX+vf49eR7PYk2q7S5xmm3jkRLejgzHNJs=".decryptBase64(cipher)
bytes.toBase64()
Calculate Digest

Hashing a data or array of bytes (aka Array<UInt8>)

/* Hash struct usage */
let bytes:Array<UInt8> = [0x01, 0x02, 0x03]
let digest = input.md5()
let digest = Digest.md5(bytes)
let data = Data( [0x01, 0x02, 0x03])

let hash = data.md5()
let hash = data.sha1()
let hash = data.sha224()
let hash = data.sha256()
let hash = data.sha384()
let hash = data.sha512()
do {
    var digest = MD5()
    let partial1 = try digest.update(withBytes: [0x31, 0x32])
    let partial2 = try digest.update(withBytes: [0x33])
    let result = try digest.finish()
} catch { }

Hashing a String and printing result

let hash = "123".md5() // "123".bytes.md5()
Calculate CRC
bytes.crc16()
data.crc16()

bytes.crc32()
data.crc32()
Message authenticators
// Calculate Message Authentication Code (MAC) for message
let key:Array<UInt8> = [1,2,3,4,5,6,7,8,9,10,...]

try Poly1305(key: key).authenticate(bytes)
try HMAC(key: key, variant: .sha256).authenticate(bytes)
try CMAC(key: key).authenticate(bytes)
Password-Based Key Derivation Functions
let password: Array<UInt8> = Array("s33krit".utf8)
let salt: Array<UInt8> = Array("nacllcan".utf8)

let key = try PKCS5.PBKDF2(password: password, salt: salt, iterations: 4096, keyLength: 32, variant: .sha256).calculate()
let password: Array<UInt8> = Array("s33krit".utf8)
let salt: Array<UInt8> = Array("nacllcan".utf8)
// Scrypt implementation does not implement work parallelization, so `p` parameter will
// increase the work time even in multicore systems
let key = try Scrypt(password: password, salt: salt, dkLen: 64, N: 16384, r: 8, p: 1).calculate()
HMAC-based Key Derivation Function
let password: Array<UInt8> = Array("s33krit".utf8)
let salt: Array<UInt8> = Array("nacllcan".utf8)

let key = try HKDF(password: password, salt: salt, variant: .sha256).calculate()
Data Padding

Some content-encryption algorithms assume the input length is a multiple of k octets, where k is greater than one. For such algorithms, the input shall be padded.

Padding.pkcs7.add(to: bytes, blockSize: AES.blockSize)

Working with Ciphers

ChaCha20
let encrypted = try ChaCha20(key: key, iv: iv).encrypt(message)
let decrypted = try ChaCha20(key: key, iv: iv).decrypt(encrypted)
Rabbit
let encrypted = try Rabbit(key: key, iv: iv).encrypt(message)
let decrypted = try Rabbit(key: key, iv: iv).decrypt(encrypted)
Blowfish
let encrypted = try Blowfish(key: key, blockMode: CBC(iv: iv), padding: .pkcs7).encrypt(message)
let decrypted = try Blowfish(key: key, blockMode: CBC(iv: iv), padding: .pkcs7).decrypt(encrypted)
AES

Notice regarding padding: Manual padding of data is optional, and CryptoSwift is using PKCS7 padding by default. If you need to manually disable/enable padding, you can do this by setting parameter for AES class

Variant of AES encryption (AES-128, AES-192, AES-256) depends on given key length:

  • AES-128 = 16 bytes
  • AES-192 = 24 bytes
  • AES-256 = 32 bytes

AES-256 example

try AES(key: [1,2,3,...,32], blockMode: CBC(iv: [1,2,3,...,16]), padding: .pkcs7)
All at once
do {
    let aes = try AES(key: "keykeykeykeykeyk", iv: "drowssapdrowssap") // aes128
    let ciphertext = try aes.encrypt(Array("Nullam quis risus eget urna mollis ornare vel eu leo.".utf8))
} catch { }
Incremental updates

Incremental operations use instance of Cryptor and encrypt/decrypt one part at a time, this way you can save on memory for large files.

do {
    var encryptor = try AES(key: "keykeykeykeykeyk", iv: "drowssapdrowssap").makeEncryptor()

    var ciphertext = Array<UInt8>()
    // aggregate partial results
    ciphertext += try encryptor.update(withBytes: Array("Nullam quis risus ".utf8))
    ciphertext += try encryptor.update(withBytes: Array("eget urna mollis ".utf8))
    ciphertext += try encryptor.update(withBytes: Array("ornare vel eu leo.".utf8))
    // finish at the end
    ciphertext += try encryptor.finish()

    print(ciphertext.toHexString())
} catch {
    print(error)
}

See Playground for sample code that work with stream.

AES Advanced usage
let input: Array<UInt8> = [0,1,2,3,4,5,6,7,8,9]

let key: Array<UInt8> = [0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00]
let iv: Array<UInt8> = // Random bytes of `AES.blockSize` length

do {
    let encrypted = try AES(key: key, blockMode: CBC(iv: iv), padding: .pkcs7).encrypt(input)
    let decrypted = try AES(key: key, blockMode: CBC(iv: iv), padding: .pkcs7).decrypt(encrypted)
} catch {
    print(error)
}

AES without data padding

let input: Array<UInt8> = [0,1,2,3,4,5,6,7,8,9]
let encrypted: Array<UInt8> = try! AES(key: Array("secret0key000000".utf8), blockMode: CBC(iv: Array("0123456789012345".utf8)), padding: .noPadding).encrypt(input)

Using convenience extensions

let plain = Data( [0x01, 0x02, 0x03])
let encrypted = try! plain.encrypt(ChaCha20(key: key, iv: iv))
let decrypted = try! encrypted.decrypt(ChaCha20(key: key, iv: iv))
AES-GCM

The result of Galois/Counter Mode (GCM) encryption is ciphertext and authentication tag, that is later used to decryption.

encryption

do {
    // In combined mode, the authentication tag is directly appended to the encrypted message. This is usually what you want.
    let gcm = GCM(iv: iv, mode: .combined)
    let aes = try AES(key: key, blockMode: gcm, padding: .noPadding)
    let encrypted = try aes.encrypt(plaintext)
    let tag = gcm.authenticationTag
catch {
    // failed
}

decryption

do {
    // In combined mode, the authentication tag is appended to the encrypted message. This is usually what you want.
    let gcm = GCM(iv: iv, mode: .combined)
    let aes = try AES(key: key, blockMode: gcm, padding: .noPadding)
    return try aes.decrypt(encrypted)
} catch {
    // failed
}

Note: GCM instance is not intended to be reused. So you can't use the same GCM instance from encoding to also perform decoding.

AES-CCM

The result of Counter with Cipher Block Chaining-Message Authentication Code encryption is ciphertext and authentication tag, that is later used to decryption.

do {
    // The authentication tag is appended to the encrypted message.
	let tagLength = 8
	let ccm = CCM(iv: iv, tagLength: tagLength, messageLength: ciphertext.count - tagLength, additionalAuthenticatedData: data)
    let aes = try AES(key: key, blockMode: ccm, padding: .noPadding)
    return try aes.decrypt(encrypted)
} catch {
    // failed
}

Check documentation or CCM specification for valid parameters for CCM.

AEAD
let encrypt = try AEADChaCha20Poly1305.encrypt(plaintext, key: key, iv: nonce, authenticationHeader: header)
let decrypt = try AEADChaCha20Poly1305.decrypt(ciphertext, key: key, iv: nonce, authenticationHeader: header, authenticationTag: tagArr: tag)

Author

CryptoSwift is owned and maintained by Marcin Krzyżanowski

You can follow me on Twitter at @krzyzanowskim for project updates and releases.

Cryptography Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

License

Copyright (C) 2014-2017 Marcin Krzyżanowski marcin@krzyzanowskim.com This software is provided 'as-is', without any express or implied warranty.

In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  • The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation is required.
  • Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  • This notice may not be removed or altered from any source or binary distribution.
  • Redistributions of any form whatsoever must retain the following acknowledgment: 'This product includes software developed by the "Marcin Krzyzanowski" (http://krzyzanowskim.com/).'

Changelog

See CHANGELOG file.

Github

link
Stars: 7539

Dependencies

Used By

Total: 0

Releases

- 2019-12-16 10:38:49

  • Adds ISO-78164 padding
  • Performance improvements
  • Swift 5.1 update

- 2019-11-18 13:24:02

1.2.0

  • Performance improvements
  • Workaround Xcode test builds with Xcode 11

- 2019-10-22 08:48:10

  • Fix build crash: https://bugs.swift.org/browse/SR-11630
  • Fixes Xcode project tests build
  • SwiftFormat all the things
  • Increase/fix SHA2 data length for big input by use Int64 for calculation

- 2019-10-15 16:47:06

  • Fix Swift 5.0 build (for real this time)

- 2019-10-14 09:15:54

  • Fix Swift 5.0 build

- 2019-10-13 17:42:19

  • Replace RandomBytesSequence with Swift.RandomNumberGenerator
  • Fix CBC-MAC
  • Update SPM support
  • Update for Xcode 11 and Swift 5.1
  • Xcode: BUILD_LIBRARY_FOR_DISTRIBUTION = YES

- 2019-03-28 20:16:46

1.0.0

  • Swift 5
  • Let's
  • Celebrate
  • This
  • Event
  • With
  • 1.0.0 release
  • After
  • 4 years
  • Thank you

- 2019-03-23 11:01:54

  • Adds The scrypt Password-Based Key Derivation Function (https://tools.ietf.org/html/rfc7914)
  • Minor improvements

- 2019-02-07 10:31:05

  • Fixed decryption of AES-GCM ciphertexts with custom tag length

- 2018-12-02 11:36:12

  • Adds AES-GCM tag length configuration.
  • Fixes count check for initializing UInt64 from Data.

- 2018-10-23 13:02:08

  • Adds CBC-MAC authenticator
  • Adds AES-CCM operation mode.

- 2018-09-15 10:09:11

Swift 4.2 maintenance release

- 2018-07-31 23:29:16

  • API: Cryptor.seek() is throwable
  • Adds proper stream support for CTR encryption with Updaptable interface.
  • Refactor internals for the stream cipher modes.
  • Set minimum deployment target to 8.0 (again).

- 2018-05-29 20:30:58

  • API: BlockMode is no longer an enum. Please migrate to eg. CBC() etc...
  • Adds AES-GCM support. #97 - Feature sponsored by GesundheitsCloud
  • Adds CRC32c support.
  • Improves AES variant validation.
  • Fixes empty password in PBKDF2.

CMAC, AEAD and Swift 4.1 - 2018-03-30 19:23:23

  • Added CMAC message authenticator https://tools.ietf.org/html/rfc4493
  • Added AEADChaCha20Poly1305 (AEAD_CHACHA20_POLY1305) https://tools.ietf.org/html/rfc7539#section-2.8.1
  • Swift 4.1 Update

- 2018-02-22 18:31:23

  • Fix SHA3 partial updates calculations.
  • Make ChaCha20 processing faster again.

- 2018-02-22 18:31:10

  • Fix SHA3 padding.
  • Fix Carthage builds.

- 2018-01-11 10:40:58

  • Adds Data(hex:) helper.
  • Adds HKDF (HMAC-based Extract-and-Expand Key Derivation Function)
  • Prevent ChaCha overflow error

- 2017-10-15 23:06:18

  • Adds SHA3 Keccak variants
  • Adds String.bytes helper to convert String to array of bytes
  • Improves AES performance
  • Speeds up compilation times with Swift 4
  • Fixes: Blowfish minimum key size is 5
  • Removes Ciphers "iv" parameter (value moved to BlockMode)
  • BlockMode uses associated value for IV value where apply e.g. .CBC(iv: ivbytes)
  • Refactors internal hacks no longer needed with Swift 4

Swift 4.0 - 2017-09-21 07:42:33

0.7.1

  • Swift 4.0 compatibility release

- 2017-09-21 23:31:34

  • Adds Padding enum (.pkcs5, .pkcs7, .noPadding, .zeroPadding)
  • Removes Generics from the public API.
  • Slightly improves SHA1, SHA2, SHA3 performance.
  • Update SPM configuration for Swift 4

Swift 3.2 - 2017-09-12 22:36:27

Compatibility release for Xcode 9 and Swift 3.2 release

- 2017-04-30 18:16:47

  • Fixed padding issue where padding was not properly added in CTR mode.
  • Fixed thrown error on decrypting empty string,
  • Fixed CI build script.
  • Added String.encryptToBase64()

Faster & better - 2017-03-20 21:48:27

  • Speed up MD5()
  • Faster Array(hex:)
  • Improve AES performance
  • Fix tvOS bitcode
  • Fix Blowfish CFB, OFB, CTR block modes.
  • Fix Blowfish for 32-bit arch.
  • Fix ChaCha20 preconditions

Xcode 8.2 - 2016-12-15 23:07:22

A minor release for Xcode 8.2 compatibility. SWIFT_VERSION value update. Playground has been updated and fixed too.

Faster - 2016-10-29 12:06:10

Processing 1MB of data on iPhone6, times: MD5: 0.027s SHA1: 0.037s SHA512: 0.024s AES: 0.42s

Blowfish - 2016-10-27 00:29:59

  • More performance improvements
  • Add convenient Digest.sha2(bytes:variant)
  • New: Blowfish cipher

Hotfix - 2016-10-24 14:37:47

Hotfix of broken Digests

Digests 🚀 - 2016-10-24 10:08:33

More improvements to the performance. This time focus on Digests. Everything is X times faster now.

Sample digest performance test times for 10_000 iterations improved from 0.8s -> 0.03s for SHA-1

improvement! profit!

Swift Three - 2016-09-13 09:08:40

0.6.0

  • Remove bridge() workaround for Linux (not needed)
  • make MD5() public
  • Update README
  • Convenience HMAC initializer for String input
  • SHA-2 fix #319
  • HashProtocol -> Digest and refactor
  • MD5 conforms to Updatable protocol and may be calculated incrementally
  • Cipher protocol accepts Collection input now
  • Swift 3 compatibility
  • Multiplatform, Single-scheme Xcode Project
  • Swift Package Manager fully supported (build and tests)
  • Improved Linux support
  • Travis configuration added
  • Public interface tests added
  • enum Authenticator -> protocol Authenticator
  • CRC -> Checksum
  • String.encrypt() returns hex string instead of Array
  • removed String.decrypt()
  • enum Hash -> struct Hash
  • Convenience initializer of Array of bytes with Hex string. Array(hex: "0xb1b1b2b2")
  • Fix reusability of ChaCha20 instance
  • Replace optional initializers with throwable initializers
  • Allow to set initial counter explicitly (AES block modes). RandomAccessCryptor.seek()