CryptoLib Swift
This library contains all cryptographic functions that are used by Cryptomator for iOS. The purpose of this project is to provide a separate light-weight library with its own release cycle that can be used in other projects, too.
For more information on the Cryptomator encryption scheme, visit the security architecture page on docs.cryptomator.org.
Requirements
- iOS 9.0 or higher
- macOS 10.12 or higher
Installation
Swift Package Manager
You can use Swift Package Manager.
.package(url: "https://github.com/cryptomator/cryptolib-swift.git", .upToNextMinor(from: "1.0.0"))
CocoaPods
You can use CocoaPods.
pod 'CryptomatorCryptoLib', '~> 1.0.0'
Usage
Masterkey
Masterkey
is a class that only contains the key material for AES encryption/decryption and MAC authentication.
Factory
This will create a new masterkey with secure random bytes.
let masterkey = try Masterkey.createNew()
Another way is to create a masterkey from raw bytes.
let aesMasterKey = ...
let macMasterKey = ...
let masterkey = Masterkey.createFromRaw(aesMasterKey: aesMasterKey, macMasterKey: macMasterKey)
MasterkeyFile
MasterkeyFile
is a representation of the masterkey file. With that, you can unlock a masterkey file (and get a Masterkey
), lock a masterkey file (and serialize it as JSON), or change the passphrase.
Factory
Create a masterkey file with content provided either from URL:
let url = ...
let masterkeyFile = try MasterkeyFile.withContentFromURL(url: url)
Or from JSON data:
let data = ...
let masterkeyFile = try MasterkeyFile.withContentFromData(data: data)
Unlock
When you have a masterkey file, you can attempt an unlock. When successful, it unwraps the stored encryption and MAC keys into the masterkey, which can be used for the cryptor.
let masterkeyFile = ...
let passphrase = ...
let pepper = ... // optional
let masterkey = try masterkeyFile.unlock(passphrase: passphrase, pepper: pepper)
Lock
For persisting the masterkey, use this method to export its encrypted/wrapped masterkey and other metadata as JSON data.
let masterkey = ...
let vaultVersion = ...
let passphrase = ...
let pepper = ... // optional
let scryptCostParam = ... // optional
let data = try MasterkeyFile.lock(masterkey: masterkey, vaultVersion: vaultVersion, passphrase: passphrase, pepper: pepper, scryptCostParam: scryptCostParam)
Change Passphrase
The masterkey can be re-encrypted with a new passphrase.
let masterkeyFileData = ...
let oldPassphrase = ...
let newPassphrase = ...
let pepper = ... // optional
let scryptCostParam = ... // optional
try MasterkeyFile.changePassphrase(masterkeyFileData: masterkeyFileData, oldPassphrase: oldPassphrase, newPassphrase: newPassphrase, pepper: pepper, scryptCostParam: scryptCostParam)
Cryptor
Cryptor
is the core class for cryptographic operations on Cryptomator vaults.
Constructor
Create a cryptor by providing a masterkey.
let masterkey = ...
let cryptor = Cryptor(masterkey: masterkey)
Path Encryption and Decryption
Encrypt the directory ID in order to determine the encrypted directory URL.
let cryptor = ...
let dirId = ...
let encryptedDirId = try cryptor.encryptDirId(dirId)
Encrypt and decrypt filenames by providing a directory ID.
let cryptor = ...
let filename = ...
let dirId = ...
let ciphertextName = try cryptor.encryptFileName(filename, dirId: dirId)
let cleartextName = try cryptor.decryptFileName(ciphertextName, dirId: dirId)
File Content Encryption and Decryption
Encrypt and decrypt file content via URLs. These methods support implicit progress composition.
let cryptor = ...
let fileURL = ...
let ciphertextURL = ...
let cleartextURL = ...
try cryptor.encryptContent(from: fileURL, to: ciphertextURL)
try cryptor.decryptContent(from: ciphertextURL, to: cleartextURL)
File Size Calculation
Determine the cleartext and ciphertext sizes in O(1).
let cryptor = ...
let size = ...
let ciphertextSize = cryptor.calculateCiphertextSize(size)
let cleartextSize = try cryptor.calculateCleartextSize(ciphertextSize)
Contributing to CryptoLib Swift
Please read our contribution guide, if you would like to report a bug, ask a question or help us with coding.
In general, the following preference is used to choose the implementation of cryptographic primitives:
- Apple Swift Crypto (HMAC)
- Apple CommonCrypto (AES-CTR, RFC 3394 Key Derivation)
Code of Conduct
Help us keep Cryptomator open and inclusive. Please read and follow our Code of Conduct.
License
Distributed under the AGPLv3. See the LICENSE file for more info.