Swiftpack.co -  Package - cryptomator/cloud-access-swift
Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
cryptomator/cloud-access-swift
Swift library for accessing various cloud providers incl. Cryptomator vaults
.package(url: "https://github.com/cryptomator/cloud-access-swift.git", from: "0.11.1")

Swift Compatibility Platform Compatibility Codacy Code Quality Codacy Coverage

Cloud Access Swift

This library defines the cloud access API used by Cryptomator for iOS.

The API is implemented once for each cloud. It also forms the foundation for decoration layers for the various vault formats that can be applied to get a cleartext view for cloud-stored vaults.

Requirements

  • iOS 10.0 or higher
  • Swift 5

Installation

Swift Package Manager

You can use Swift Package Manager.

.package(url: "https://github.com/cryptomator/cloud-access-swift.git", .upToNextMinor(from: "1.0.0"))

Usage

Core

The core package contains several protocols, structs, and enums that build the foundation of this library. Asynchronous calls are implemented using the Promises library. CloudProvider is the main protocol that defines the cloud access:

func fetchItemMetadata(at cloudPath: CloudPath) -> Promise<CloudItemMetadata>
func fetchItemList(forFolderAt cloudPath: CloudPath, withPageToken pageToken: String?) -> Promise<CloudItemList>
func downloadFile(from cloudPath: CloudPath, to localURL: URL) -> Promise<Void>
func uploadFile(from localURL: URL, to cloudPath: CloudPath, replaceExisting: Bool) -> Promise<CloudItemMetadata>
func createFolder(at cloudPath: CloudPath) -> Promise<Void>
func deleteFile(at cloudPath: CloudPath) -> Promise<Void>
func deleteFolder(at cloudPath: CloudPath) -> Promise<Void>
func moveFile(from sourceCloudPath: CloudPath, to targetCloudPath: CloudPath) -> Promise<Void>
func moveFolder(from sourceCloudPath: CloudPath, to targetCloudPath: CloudPath) -> Promise<Void>

Crypto

Crypto and shortening decorators allow transparent access to vaults based on Cryptomator's encryption scheme. It depends on cryptolib-swift for cryptographic functions and GRDB for thread-safe caching. For more information on the Cryptomator encryption scheme, visit the security architecture page on docs.cryptomator.org.

In order to create a crypto decorator provider, you need a Cryptor instance from cryptolib-swift. Check out its documentation on how to create a cryptor. And to be fully compatible, you'd have to put a shortening decorator in-between:

let provider = ... // any other cloud provider
let vaultPath = ...
...
let cryptor = ...
let shorteningDecorator = try VaultFormat7ShorteningProviderDecorator(delegate: provider, vaultPath: vaultPath)
let cryptoDecorator = try VaultFormat7ProviderDecorator(delegate: shorteningDecorator, vaultPath: vaultPath, cryptor: cryptor)

:warning: You have to check the version of your MasterkeyFile instance so that you create the correct decorator. This library supports vault version 6 and higher.

Local File System

Since the local file system is not actually a cloud, the naming might be confusing. Even though this library is dedicated to provide access to many cloud storage services, access to the local file system still might be useful.

Create a local file system provider with a root URL:

let rootURL = ... // rootURL.isFileURL must be `true`
let provider = LocalFileSystemProvider(rootURL: rootURL)

When calling the functions of this provider, the cloud paths should be provided relative to the root URL.

This provider uses NSFileCoordinator for its operations and supports asynchronous access.

WebDAV

Create a WebDAV provider with a WebDAV client:

let baseURL = ...
let username = ...
let password = ...
let allowedCertificate = ... // optional: you might want to allowlist a TLS certificate
let identifier = ... // optional: you might want to give this credential an identifier, defaults to a random UUID
let credential = WebDAVCredential(baseURL: baseURL, username: username, password: password, allowedCertificate: allowedCertificate, identifier: identifier)
let sharedContainerIdentifier = ... // if `useBackgroundSession` is `true`, this will be set internally for the `URLSessionConfiguration`
let useBackgroundSession = ... // if `true`, the internal `URLSessionConfiguration` will be based on a background configuration
let client = WebDAVClient(credential: credential, sharedContainerIdentifier: sharedContainerIdentifier, useBackgroundSession: useBackgroundSession)
let provider = WebDAVProvider(with: client)

In theory, you could use the provider without further checks. However, you should verify the WebDAV client and its credential using the WebDAV authenticator:

let client = ...
WebDAVAuthenticator.verifyClient(client: client).then {
  // client validation successful
}.catch { error in
  // error handling
}

Furthermore, for allowlisting a certificate, you can use the TLS certificate validator:

let baseURL = ...
let validator = TLSCertificateValidator(baseURL: baseURL)
validator.validate().then { certificate in
  // certificate of type `TLSCertificate` contains several properties for further handling
}.catch { error in
  // error handling
}

Integration Testing

If you would like to run integration tests that require authorization, you have to set some secrets for them. Create a .integration-test-secrets.sh file in the root directory. Its contents should look something like this:

#!/bin/sh
export DROPBOX_ACCESS_TOKEN=...
export GOOGLE_DRIVE_CLIENT_ID=...
export GOOGLE_DRIVE_REFRESH_TOKEN=...
export WEBDAV_BASE_URL=...
export WEBDAV_USERNAME=...
export WEBDAV_PASSWORD=...

If you aren't using the Xcode project, you may have to run ./create-integration-test-secrets-file.sh once. If you change the secrets later on, you have to run that script again.

If you are building via a CI system, set these secret environment variables accordingly.

Contributing to Cloud Access Swift

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.

GitHub

link
Stars: 5
Last commit: 2 hours ago

Release Notes

0.11.1
6 weeks ago
  • Clarified usage of sharedContainerIdentifier in WebDAV, removed it from TLSCertificateValidator
  • Updated cryptolib-swift dependency

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco