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.
- iOS 9.0 or higher
- macOS 10.12 or higher
Swift Package Manager
You can use Swift Package Manager.
.package(url: "https://github.com/cryptomator/cryptolib-swift.git", .upToNextMinor(from: "1.0.0"))
You can use CocoaPods.
pod 'CryptomatorCryptoLib', '~> 1.0.0'
Masterkey is a factory for masterkey objects that contain the masterkey bytes for AES encryption/decryption and MAC authentication. The version states the vault format version.
This will create a new masterkey with secure random bytes. Version will be set to the latest version (currently 7).
let masterkey = try Masterkey.createNew()
Another way is to create a masterkey from an existing masterkey file. This is equivalent to an unlock attempt.
Either by URL:
let fileURL = ... let password = ... let pepper = ... // optional let masterkey = try Masterkey.createFromMasterkeyFile(fileURL: fileURL, password: password, pepper: pepper)
Or by JSON data:
let jsonData = ... let password = ... let pepper = ... // optional let masterkey = try Masterkey.createFromMasterkeyFile(jsonData: jsonData, password: password, pepper: pepper)
For persisting the masterkey, use this method to export its encrypted/wrapped masterkey and other metadata as JSON data.
let masterkey = ... let password = ... let pepper = ... // optional let jsonData = try masterkey.exportEncrypted(password: password, pepper: pepper)
Cryptor is the core class for cryptographic operations on Cryptomator vaults.
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)
- CryptoSwift (scrypt)
Code of Conduct
Help us keep Cryptomator open and inclusive. Please read and follow our Code of Conduct.
Distributed under the AGPLv3. See the LICENSE file for more info.
You may find interesting
- 2020-09-26 12:45:13
- Decreased deployment target to macOS 10.12
- 2020-09-26 11:46:29
- Added support for macOS 10.13 or higher
- Restructured project so that it conforms to naming conventions of Swift Package Manager
- Removed Pods integration and added Swift Package Manager as dependency management (this library is still available via CocoaPods, this just affects the development of this library)
- 2020-09-24 13:01:09
Package.swiftmanifest, supporting Swift Package Manager
- 2020-09-18 15:33:30
- Increased deployment target to iOS 9.0
- 2020-07-20 16:19:06
MasterkeyErroris now public
- Updated docs on
- 2020-06-27 19:21:09
- Fixed progress reporting during file content decryption
- 2020-06-26 12:22:15
- Added progress reporting to file content encryption/decryption (methods support implicit progress composition)
- Added docs on public methods
- Adjusted access control on some methods
- 2020-06-24 14:39:56
- Added public init to
createNew()factory method to
- 2020-06-22 12:38:58
- Added file size calculation
- 2020-06-15 16:56:47
- Added file content encryption/decryption
- Added SwiftFormat rules
- 2020-06-15 15:27:39
- Added "public" version field to
Cryptoroperations throw errors instead of returning optionals
- Added GitHub Actions workflow
- 2020-05-04 14:31:49
This release should contain everything necessary to browse directories inside a vault:
- Correctly handles masterkey decryption error cases
- Added support for base32-encoded filename encryption
- Added directory ID encryption
- 2020-05-04 11:04:36
First pre-release version capable of:
- masterkey decryption
- filename encryption/decryption (atm only base64-url-encoded, i.e. vault format 7)