CryptoSwift

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

Note: The main 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

It takes some time to keep it all for your convenience, so maybe spare $1, so I can keep working on that. There are more than 8000 clones daily. If I'd get $1/month from each company that uses my work here, I'd say we're even. Hurry up, find the Sponsorship button, and fulfill your duty.

CryptoSwift isn't backed by any big company and is developed 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 | SHA2-224 | SHA2-256 | SHA2-384 | SHA2-512 | SHA3

Cyclic Redundancy Check (CRC)

CRC32 | CRC32C | CRC16

Cipher

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

RSA (public-key encryption algorithm)

Encryption, Signature

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)
• OCB Authenticated-Encryption Algorithm (OCB)

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
• EMSA-PKCS1-v1_5 (Encoding Method for Signature)
• EME-PCKS1-v1_5 (Encoding Method for Encryption)
• PKCS#7
• Zero padding
• ISO78164
• ISO10126
• No padding

Authenticated Encryption with Associated Data (AEAD)

• AEAD_CHACHA20_POLY1305

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.

• If you found a bug, open a discussion.
• If you have a feature request, open a discussion.

Installation

Hardened Runtime (macOS) and Xcode

Binary CryptoSwift.xcframework (Used by Swift Package Manager package integration) won't load properly in your app if the app uses Sign to Run Locally Signing Certificate with Hardened Runtime enabled. It is possible to setup Xcode like this. To solve the problem you have two options:

• Use proper Signing Certificate, eg. Development <- this is the proper action
• Use Disable Library Validation aka com.apple.security.cs.disable-library-validation entitlement

Xcode Project

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.

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",.upToNextMajor(from:"1.7.1"))

See: Package.swift - manual

Notice: Swift Package Manager uses debug configuration for debug Xcode build, that may result in significant (up to x10000) worse performance. Performance characteristic is different in Release build. To overcome this problem, consider embed CryptoSwift.xcframework described below.

CocoaPods

You can use CocoaPods.

pod'CryptoSwift','~> 1.7.1'

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.

XCFramework

XCFrameworks require Xcode 11 or later and they can be integrated similarly to how we’re used to integrating the .framework format. Please use script scripts/build-framework.sh to generate binary CryptoSwift.xcframework archive that you can use as a dependency in Xcode.

CryptoSwift.xcframework is a Release (Optimized) binary that offer best available Swift code performance.

Embedded Framework

Embedded frameworks require a minimum deployment target of iOS 11.0 or macOS Sierra (10.13). 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, macOS, 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, branch swift5 version <= 1.3.3
• Swift 5.3 and newer, branch main

How-to

• Basics (data types, conversion, ...)
• Digest (MD5, SHA...)
• Message authenticators (HMAC, CMAC...)
• Password-Based Key Derivation Function (PBKDF2, ...)
• HMAC-based Key Derivation Function (HKDF)
• Data Padding
• ChaCha20
• Rabbit
• Blowfish
• AES - Advanced Encryption Standard
• AES-GCM
• Authenticated Encryption with Associated Data (AEAD)

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:

letdata=Data([0x01,0x02,0x03])

Data to Array<UInt8>

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

Hexadecimal encoding:

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

Build bytes out of String

letbytes: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 */
letbytes:Array<UInt8>=[0x01,0x02,0x03]letdigest= input.md5()letdigest=Digest.md5(bytes)

letdata=Data([0x01,0x02,0x03])lethash= data.md5()lethash= data.sha1()lethash= data.sha224()lethash= data.sha256()lethash= data.sha384()lethash= data.sha512()

do{vardigest=MD5()letpartial1=try digest.update(withBytes:[0x31,0x32])letpartial2=try digest.update(withBytes:[0x33])letresult=try digest.finish()}catch{}

Hashing a String and printing result

lethash="123".md5() // "123".bytes.md5()

Calculate CRC

bytes.crc16()
data.crc16()
bytes.crc32()
data.crc32()

Message authenticators

// Calculate Message Authentication Code (MAC) for message
letkey:Array<UInt8>=[1,2,3,4,5,6,7,8,9,10,...]tryPoly1305(key: key).authenticate(bytes)tryHMAC(key: key, variant:.sha256).authenticate(bytes)tryCMAC(key: key).authenticate(bytes)

Password-Based Key Derivation Functions

letpassword:Array<UInt8>=Array("s33krit".utf8)letsalt:Array<UInt8>=Array("nacllcan".utf8)letkey=tryPKCS5.PBKDF2(password: password, salt: salt, iterations:4096, keyLength:32, variant:.sha256).calculate()

letpassword:Array<UInt8>=Array("s33krit".utf8)letsalt:Array<UInt8>=Array("nacllcan".utf8)
// Scrypt implementation does not implement work parallelization, so `p` parameter will
// increase the work time even in multicore systems
letkey=tryScrypt(password: password, salt: salt, dkLen:64, N:16384, r:8, p:1).calculate()

HMAC-based Key Derivation Function

letpassword:Array<UInt8>=Array("s33krit".utf8)letsalt:Array<UInt8>=Array("nacllcan".utf8)letkey=tryHKDF(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

letencrypted=tryChaCha20(key: key, iv: iv).encrypt(message)letdecrypted=tryChaCha20(key: key, iv: iv).decrypt(encrypted)

Rabbit

letencrypted=tryRabbit(key: key, iv: iv).encrypt(message)letdecrypted=tryRabbit(key: key, iv: iv).decrypt(encrypted)

Blowfish

letencrypted=tryBlowfish(key: key, blockMode:CBC(iv: iv), padding:.pkcs7).encrypt(message)letdecrypted=tryBlowfish(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

letencryptedBytes=tryAES(key:[1,2,3,...,32], blockMode:CBC(iv:[1,2,3,...,16]), padding:.pkcs7)

Full example:

letpassword:[UInt8]=Array("s33krit".utf8)letsalt:[UInt8]=Array("nacllcan".utf8)
/* Generate a key from a `password`. Optional if you already have a key */
letkey=tryPKCS5.PBKDF2(
password: password,
salt: salt,
iterations:4096,
keyLength:32, /* AES-256 */
variant:.sha256
).calculate()
/* Generate random IV value. IV is public value. Either need to generate, or get it from elsewhere */
letiv=AES.randomIV(AES.blockSize)
/* AES cryptor instance */
letaes=tryAES(key: key, blockMode:CBC(iv: iv), padding:.pkcs7)
/* Encrypt Data */
letinputData=Data()letencryptedBytes=try aes.encrypt(inputData.bytes)letencryptedData=Data(encryptedBytes)
/* Decrypt Data */
letdecryptedBytes=try aes.decrypt(encryptedData.bytes)letdecryptedData=Data(decryptedBytes)

All at once

do{letaes=tryAES(key:"keykeykeykeykeyk", iv:"drowssapdrowssap") // aes128
letciphertext=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{varencryptor=tryAES(key:"keykeykeykeykeyk", iv:"drowssapdrowssap").makeEncryptor()varciphertext=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)}

AES Advanced usage

letinput:Array<UInt8>=[0,1,2,3,4,5,6,7,8,9]letkey:Array<UInt8>=[0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00]letiv:Array<UInt8>= // Random bytes of `AES.blockSize` length
do{letencrypted=tryAES(key: key, blockMode:CBC(iv: iv), padding:.pkcs7).encrypt(input)letdecrypted=tryAES(key: key, blockMode:CBC(iv: iv), padding:.pkcs7).decrypt(encrypted)} catch {print(error)}

AES without data padding

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

Using convenience extensions

letplain=Data([0x01,0x02,0x03])letencrypted=try! plain.encrypt(ChaCha20(key: key, iv: iv))letdecrypted=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.
letgcm=GCM(iv: iv, mode:.combined)letaes=tryAES(key: key, blockMode: gcm, padding:.noPadding)letencrypted=try aes.encrypt(plaintext)lettag= gcm.authenticationTag
}catch{
// failed
}

decryption

do{
// In combined mode, the authentication tag is appended to the encrypted message. This is usually what you want.
letgcm=GCM(iv: iv, mode:.combined)letaes=tryAES(key: key, blockMode: gcm, padding:.noPadding)returntry 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.
lettagLength=8letccm=CCM(iv: iv, tagLength: tagLength, messageLength: ciphertext.count - tagLength, additionalAuthenticatedData: data)letaes=tryAES(key: key, blockMode: ccm, padding:.noPadding)returntry aes.decrypt(encrypted)}catch{
// failed
}

Check documentation or CCM specification for valid parameters for CCM.

AEAD

letencrypt=tryAEADChaCha20Poly1305.encrypt(plaintext, key: key, iv: nonce, authenticationHeader: header)letdecrypt=tryAEADChaCha20Poly1305.decrypt(ciphertext, key: key, iv: nonce, authenticationHeader: header, authenticationTag: tagArr: tag)

RSA

RSA initialization from parameters

letinput:Array<UInt8>=[0,1,2,3,4,5,6,7,8,9]letn:Array<UInt8>= // RSA modulus
let e: Array<UInt8>= // RSA public exponent
letd:Array<UInt8>= // RSA private exponent
let rsa =RSA(n: n, e: e, d: d)do{letencrypted=try rsa.encrypt(input)letdecrypted=try rsa.decrypt(encrypted)}catch{print(error)}

RSA key generation

letrsa=tryRSA(keySize:2048) // This generates a modulus, public exponent and private exponent with the given size

RSA Encryption & Decryption Example

// Alice Generates a Private Key
letalicesPrivateKey=tryRSA(keySize:1024)
// Alice shares her **public** key with Bob
letalicesPublicKeyData=try alicesPrivateKey.publicKeyExternalRepresentation()
// Bob receives the raw external representation of Alices public key and imports it
letbobsImportOfAlicesPublicKey=tryRSA(rawRepresentation: alicesPublicKeyData)
// Bob can now encrypt a message for Alice using her public key
letmessage="Hi Alice! This is Bob!"letprivateMessage=try bobsImportOfAlicesPublicKey.encrypt(message.bytes)
// This results in some encrypted output like this
// URcRwG6LfH63zOQf2w+HIllPri9Rb6hFlXbi/bh03zPl2MIIiSTjbAPqbVFmoF3RmDzFjIarIS7ZpT57a1F+OFOJjx50WYlng7dioKFS/rsuGHYnMn4csjCRF6TAqvRQcRnBueeINRRA8SLaLHX6sZuQkjIE5AoHJwgavmiv8PY=
// Bob can now send this encrypted message to Alice without worrying about people being able to read the original contents
// Alice receives the encrypted message and uses her private key to decrypt the data and recover the original message
letoriginalDecryptedMessage=try alicesPrivateKey.decrypt(privateMessage)print(String(data:Data(originalDecryptedMessage), encoding:.utf8))
// "Hi Alice! This is Bob!"

RSA Signature & Verification Example

// Alice Generates a Private Key
letalicesPrivateKey=tryRSA(keySize:1024)
// Alice wants to sign a message that she agrees with
letmessageAliceSupports="Hi my name is Alice!"letalicesSignature=try alicesPrivateKey.sign(messageAliceSupports.bytes)
// Alice shares her Public key and the signature with Bob
letalicesPublicKeyData=try alicesPrivateKey.publicKeyExternalRepresentation()
// Bob receives the raw external representation of Alices Public key and imports it!
letbobsImportOfAlicesPublicKey=tryRSA(rawRepresentation: alicesPublicKeyData)
// Bob can now verify that Alice signed the message using the Private key associated with her shared Public key.
letverifiedSignature=try bobsImportOfAlicesPublicKey.verify(signature: alicesSignature, for:"Hi my name is Alice!".bytes)if verifiedSignature ==true{
// Bob knows that the signature Alice provided is valid for the message and was signed using the Private key associated with Alices shared Public key.
}else{
// The signature was invalid, so either
// - the message Alice signed was different then what we expected.
// - or Alice used a Private key that isn't associated with the shared Public key that Bob has.
}

CryptoSwift RSA Key -> Apple's Security Framework SecKey Example

/// Starting with a CryptoSwift RSA Key
letrsaKey=tryRSA(keySize:1024)
/// Define your Keys attributes
letattributes:[String:Any]=[
kSecAttrKeyType asString: kSecAttrKeyTypeRSA,
kSecAttrKeyClass asString: kSecAttrKeyClassPrivate, // or kSecAttrKeyClassPublic
kSecAttrKeySizeInBits asString:1024, // The appropriate bits
kSecAttrIsPermanent asString:false]varerror:Unmanaged<CFError>?=nilguardlet rsaSecKey =trySecKeyCreateWithData(rsaKey.externalRepresentation()asCFData, attributes asCFDictionary,&error)else{
/// Error constructing SecKey from raw key data
return}
/// You now have an RSA SecKey for use with Apple's Security framework

Apple's Security Framework SecKey -> CryptoSwift RSA Key Example

/// Starting with a SecKey RSA Key
letrsaSecKey:SecKey
/// Copy External Representation
varexternalRepError:Unmanaged<CFError>?guardlet cfdata =SecKeyCopyExternalRepresentation(rsaSecKey,&externalRepError)else{
/// Failed to copy external representation for RSA SecKey
return}
/// Instantiate the RSA Key from the raw external representation
letrsaKey=tryRSA(rawRepresentation: cfdata asData)
/// You now have a CryptoSwift RSA Key

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-2022 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.