SETOCryptomatorCryptor is an iOS crypto library to access Cryptomator vaults. For more information on the security details visit cryptomator.org.
Requirements
- iOS 8.0 or higher
- ARC enabled
Installation
The easiest way to use SETOCryptomatorCryptor in your app is via CocoaPods.
- Add the following line in the project's Podfile file:
pod 'SETOCryptomatorCryptor', '~> 1.4.0' - Run the command
pod installfrom the Podfile folder directory.
Audits
| Finding | Comment |
|---|---|
| 1u1-22-001 | This issue is related to cryptolib, cryptofs, and siv-mode. |
| 1u1-22-002 | This issue is related to siv-mode. |
Usage
SETOCryptorProvider
SETOCryptorProvider is a factory for SETOCryptor objects. Always use the factory for creating SETOCryptor instances.
Create New Cryptor & Master Key
NSString *password = ...;
SETOCryptor *cryptor = [SETOCryptorProvider newCryptor];
SETOMasterKey *masterKey = [cryptor masterKeyWithPassword:password];Actually, you should call these methods from a background thread, as random number generation will benefit from UI interaction.
NSString *password = ...;
dispatch_async(dispatch_get_global_queue(QOS_CLASS_UTILITY, 0), ^{
SETOCryptor *cryptor = [SETOCryptorProvider newCryptor];
SETOMasterKey *masterKey = [cryptor masterKeyWithPassword:password];
dispatch_async(dispatch_get_main_queue(), ^{
// do the rest here
});
});Create Cryptor From Existing Master Key
This is equivalent to an unlock attempt.
SETOMasterKey *masterKey = ...;
NSError *error;
SETOCryptor *cryptor = [SETOCryptorProvider cryptorFromMasterKey:masterKey withPassword:password error:&error];
if (error) {
NSLog(@"Unlock Error: %@", error);
} else {
NSLog(@"Unlock Success");
}Determine File Sizes
Beginning with vault version 5, you can determine the cleartext and ciphertext sizes in O(1). Reading out the file sizes before vault version 5 is theoretically possible, but not supported by this library.
SETOCryptor *cryptor = ...;
NSUInteger ciphertextSize = ...;
NSUInteger cleartextSize = [SETOCryptorProvider cleartextSizeFromCiphertextSize:ciphertextSize withCryptor:cryptor];
// and the other way round with +[SETOCryptorProvider ciphertextSizeFromCleartextSize:withCryptor:]SETOCryptor
SETOCryptor is the core class for cryptographic operations on Cryptomator vaults. This is an abstract class, so you should use SETOCryptorProvider to create a SETOCryptor instance.
Directory ID Encryption
SETOCryptor *cryptor = ...;
NSString *directoryId = ...;
NSString *encryptedDirectoryId = [cryptor encryptDirectoryId:directoryId];Filename Encryption and Decryption
SETOCryptor *cryptor = ...;
NSString *filename = ...;
NSString *directoryId = ...;
NSString *encryptedFilename = [cryptor encryptFilename:filename insideDirectoryWithId:directoryId];
NSString *decryptedFilename = [cryptor decryptFilename:encryptedFilename insideDirectoryWithId:directoryId];File Content Authentication
SETOCryptor *cryptor = ...;
NSString *ciphertextFilePath = ...;
[cryptor authenticateFileAtPath:ciphertextFilePath callback:^(NSError *error) {
if (error) {
NSLog(@"Authentication Error: %@", error);
} else {
NSLog(@"Authentication Success");
}
} progress:^(CGFloat progress) {
NSLog(@"Authentication Progress: %.2f", progress);
}];File Content Encryption
SETOCryptor *cryptor = ...;
NSString *cleartextFilePath = ...;
NSString *ciphertextFilePath = ...;
[cryptor encryptFileAtPath:cleartextFilePath toPath:ciphertextFilePath callback:^(NSError *error) {
if (error) {
NSLog(@"Encryption Error: %@", error);
} else {
NSLog(@"Encryption Success");
}
} progress:^(CGFloat progress) {
NSLog(@"Encryption Progress: %.2f", progress);
}];File Content Decryption
SETOCryptor *cryptor = ...;
NSString *ciphertextFilePath = ...;
NSString *cleartextFilePath = ...;
[cryptor decryptFileAtPath:ciphertextFilePath toPath:cleartextFilePath callback:^(NSError *error) {
if (error) {
NSLog(@"Decryption Error: %@", error);
} else {
NSLog(@"Decryption Success");
}
} progress:^(CGFloat progress) {
NSLog(@"Decryption Progress: %.2f", progress);
}];SETOAsyncCryptor
SETOAsyncCryptor is a SETOCryptor decorator for running file content encryption and decryption operations asynchronously. It's useful for cryptographic operations on large files without blocking the main thread.
Create and initialize SETOAsyncCryptor using initWithCryptor:queue: to specify a dispatch queue. If you're initializing with the convenience initializer initWithCryptor:, a serial queue (utility QoS class) will be created and used.
SETOMasterKey
SETOMasterKey holds the information necessary for the master key. All properties are immutable to prevent accidental changes. Use updateFromJsonData: or updateFromDictionary: to modify the properties in bulk. Use the convenience method dictionaryRepresentation, e.g. for persisting the master key.
Contributing to Cryptomator
Please read our contribution guide, if you would like to report a bug, ask a question or help us with coding.
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.
