Swiftpack.co - Package - cryptomator/cryptolib-swift

Swift Compatibility Platform Compatibility Version Codacy Code Quality Codacy Coverage

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 factory for masterkey objects that contain the masterkey bytes for AES encryption/decryption and MAC authentication. The version states the vault format version.

Factory

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)

Export

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

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:

  1. Apple Swift Crypto (HMAC)
  2. Apple CommonCrypto (AES-CTR, RFC 3394 Key Derivation)
  3. CryptoSwift (scrypt)

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.

Github

link
Stars: 3

Used By

Total: 0

Releases

- 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

  • Added Package.swift manifest, supporting Swift Package Manager

- 2020-09-18 15:33:30

  • Increased deployment target to iOS 9.0

- 2020-07-20 16:19:06

  • MasterkeyError is now public
  • Updated docs on CryptoSupport methods

- 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 Cryptor
  • Added createNew() factory method to Masterkey
  • Added exportEncrypted() method to Masterkey

- 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 Masterkey
  • Cryptor operations 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)