Managers

  • The ZeroDark.cloud framework encrypts node-names before storing them in the cloud. This is to maintain zero-knowledge, and protect the customer in situations where the node-names themselves may reveal sensitive information.

    For more information about how the encryption works, see this article: https://zerodarkcloud.readthedocs.io/en/latest/overview/encryption/

    Here’s the high-level overview:

    1. All files are stored in AWS S3.
      It should be noted that S3 is NOT a filesystem - it’s actually a key/value store. So each treepath needs to get translated to a string that uniquely identifies it. This string is called the key in S3 parlance. And keys in S3 have certain restrictions, such as a max length of 1024.

    2. ZeroDark maps from (cleartext) treepath to (encrypted) S3 key.
      This mapping is done to ensure the server cannot read node names. Here’s an example

      • Treepath: /foo/bar
      • S3 key: com.company.app/F8622C33B26C43C7B7DB3A6B26C60057/58fidhxeyyfzgp73hgefpr956jaxa6xs.rcrd

      The S3 key components are: {treeID}/{dirPrefix}/{hasedNodeName}.ext

    3. The first path component is the app container.
      Your company may create multiple applications. So each application gets its own container.

    4. The second path component is called the dirPrefix.
      A dirPrefix is a UUID - 32 characters of hexadecimal. For example: F8622C33B26C43C7B7DB3A6B26C60057 Every parent node registers a dirPrefix. And every direct child of the parent node will use this dirPrefix within its key.

    5. The last path component is the encrypted name.
      To generate the hashedNodeName, the framework hashes the (cleartext) node name (e.g. Secret coca-cola formula.txt), combined with the parent directory’s salt. Thus 2 nodes with the same name, but different parents, will have a different hashedNodeName.

    See more

    Declaration

    Objective-C

    @interface ZDCCloudPathManager : NSObject

    Swift

    class ZDCCloudPathManager : NSObject
  • ZeroDarkCloud requires a database for atomic operations. YapDatabase is used as it’s the most performant and highly-concurrent.

    If you’re curious about YapDatabase, you can find the project page here. The extensive documentation is on the wiki.

    This class provides access to the YapDatabase instance & various connections/extensions being used by the framework. You’re encouraged (but not required) to store your objects in the same YapDatabase instance, as doing so allows you to participate in the same atomic transactions being used by the framework.

    See more

    Declaration

    Objective-C

    @interface ZDCDatabaseManager : NSObject

    Swift

    class ZDCDatabaseManager : NSObject
  • This class provides optional tools for securely storing & retrieving the key used to encrypt the sqlite database file.

    The local sqlite database (stored on the user’s device) is encrypted using SQLCipher. In order to start using the framework, this database file must first be unlocked.

    Note

    Encryption of the local database is required in order to protect the user’s data. The database stores all the node encryption keys, and other sensitive content. And it’s rather common for this database file to get backed up to various locations, such as iCloud.

    The DatabaseKeyManager provides flexibility for your app. For example, you may want to add password protection or TouchID to your app. This class can help, while maintaining strong security backed by solid crypto.

    Here’s how it works:

    • A random key is generated for encrypting the database file.
    • This key is then wrapped (encrypted) using PBKDF2, and the resulting PBKDF2 file is stored to disk.
    • The key to unlock the PBKDF2 is stored separately, and is configurable to fit the needs of your application.

    By protecting access to this key, you protect access to the database, and thus all user data stored locally. This even includes files stored via the DiskManager (which are also encrypted with keys stored in the database).

    Note

    Use of this class is optional. If your app already has a custom solution for encrypting & storing the database key, then you’re welcome to use it.

    This class gives your app 3 different options for storing the database key:

    1. Keychain The easiest option is simply to store the database key in the OS keychain.

    2. Passphrase You can allow users to protect the data with a passphrase.

    3. Biometric You can allow users to use the biometrics available on their device.

    Long story short: This class provides the security options you’d expect, backed by the crypto you’d hope for.

    Additional documentation can be found in the docs: https://zerodarkcloud.readthedocs.io/en/latest/client/databaseKeyManager/

    See more

    Declaration

    Objective-C

    @interface ZDCDatabaseKeyManager : NSObject

    Swift

    class ZDCDatabaseKeyManager : NSObject
  • Simple utility class to provide standardized URL’s for common local directories & for temp files.

    See more

    Declaration

    Objective-C

    @interface ZDCDirectoryManager : NSObject

    Swift

    class ZDCDirectoryManager : NSObject
  • The DiskManager simplifies the process of persisting & caching files to disk.

    The DiskManager supports two different storage modes:

    • Persistent: Files stored in persistent mode won’t be deleted unless you ask the DiskManager to delete them, or the underlying node/user is deleted from the database.
    • Cache: File stored in cache mode are treated as a temporarily file. They are added to a storage pool managed by the DiskManager. And when the max size of the storage pool is exceeded, the DiskManager automatically starts deleting files. Further, the files are stored in an OS-designated Caches folder, and are available for deletion by the OS due to low-disk-space pressure.
    See more

    Declaration

    Objective-C

    @interface ZDCDiskManager : NSObject

    Swift

    class ZDCDiskManager : NSObject
  • The DownloadManager is your one-stop-shop for downloading data from the cloud.

    Recall that the ZeroDark.cloud framework will automatically fetch the treesystem outline for you. That is, it will tell you about the nodes that exist in the cloud, what their names are, and what the tree/heirarchy looks like. But you’re in complete control when it comes to downloading the actual data (node content). This allows you to optimize for your app. For example:

    • speed up new app logins by not downloading old content
    • save disk space by deleting local copies of node data that are no longer being used
    • optimize per-device by downloading certain content on demand

    When you’re ready to download the node content, the DownloadManager simplifies the process for you. It will automatically coalesce multiple requests to download the same item. And it supports optional background downloads, so that downloads can continue while the app is backgrounded (or even quit).

    For downloads of very large items, the DownloadManager will automatically download the item in parts. If the download is interrupted, it can automatically pick up where it left off.

    It also provides an NSProgress instance for all downloads, allowing you to display progress items in your UI. And it works in concert with the ProgressManager to simplify UI development.

    See more

    Declaration

    Objective-C

    @interface ZDCDownloadManager : NSObject

    Swift

    class ZDCDownloadManager : NSObject
  • The ImageManager simplifies the process of fetching, downloading & resizing images. This includes both node thumbnails & user avatars.

    See more

    Declaration

    Objective-C

    @interface ZDCImageManager : NSObject

    Swift

    class ZDCImageManager : NSObject
  • The LocalUserManager simplifies many aspects of determining sync state.

    See more

    Declaration

    Objective-C

    @interface ZDCLocalUserManager : NSObject

    Swift

    class ZDCLocalUserManager : NSObject
  • Provides various methods for inspecting the node treesystem.

    See more

    Declaration

    Objective-C

    @interface ZDCNodeManager : NSObject

    Swift

    class ZDCNodeManager : NSObject
  • The ProgressManager provides real-time progress information for active operations.

    This includes:

    • downloads : as in the downloads of node data that you request through the DownloadManager
    • uploads : which get queued for the push manager, and then get uploaded when possible

    The ProgressManager automatically monitors its progress items, and provides you with the following useful information:

    • Bandwidth calculations:

      • Estimated bytes-per-second.
      • Available via progress.userInfo[NSProgressThroughputKey]
    • Time remaining calculations:

      • Estimated time remaining based on averaged throughput & remaining bytes.
      • Available via progress.userInfo[NSProgressEstimatedTimeRemainingKey]
    See more

    Declaration

    Objective-C

    @interface ZDCProgressManager : NSObject

    Swift

    class ZDCProgressManager : NSObject
  • The PullManager handles pulling changes down from the cloud.

    The sync process can be broken down into 2 components: Push & Pull. If you’ve used git before, you’re already familiar with the process. You push changes (made locally) to the cloud. And you pull changes (made on remote devices) from the cloud.

    This class handles the PULL side of things.

    In particular, the PullManager will automatically keep the local treesystem information up-to-date with the cloud. This ONLY includes the treesystem metadata information, such as:

    • names of nodes
    • their permissions
    • their location within the tree

    The ZeroDarkCloud framework doesn’t automatically download node data (the content your app generates). You are in complete control of that, which allows you to optimize for your app. For example, you can:

    • download only recent data
    • download data on demand (as the app needs it)
    • download a small part of what’s stored in the cloud (i.e. thumbnails instead of full images)
    See more

    Declaration

    Objective-C

    @interface ZDCPullManager : NSObject

    Swift

    class ZDCPullManager : NSObject
  • The PushManager handles pushing changes up to the cloud.

    The sync process can be broken down into 2 components: Push & Pull. If you’ve used git before, you’re already familiar with the process. You push changes (made locally) to the cloud. And you pull changes (made on remote devices) from the cloud.

    This class handles the PUSH side of things.

    See more

    Declaration

    Objective-C

    @interface ZDCPushManager : NSObject

    Swift

    class ZDCPushManager : NSObject
  • Facilitates access to the REST API of the ZeroDark.cloud servers.

    See more

    Declaration

    Objective-C

    @interface ZDCRestManager : NSObject

    Swift

    class ZDCRestManager : NSObject
  • The SyncManager simplifies many aspects of determining sync state.

    In particular, it can tell you:

    • whether or not the framework is syncing data (pushing or pulling)
    • which nodes are being synced

    The framework can run on autopilot most of the time. But this class gives you fine grained controls. For example, you can pause the push queue for a particular user so changes aren’t uploaded.

    See more

    Declaration

    Objective-C

    @interface ZDCSyncManager : NSObject

    Swift

    class ZDCSyncManager : NSObject
  • The ZDCUITools is a series of functions that simpily the user interface needed for creating, signing-in and managing ZDCLocalUsers

    See more

    Declaration

    Objective-C

    @interface ZDCUITools : NSObject

    Swift

    class ZDCUITools : NSObject
  • The UserManager handles various tasks involving ZDCUser’s.

    Note

    There is also a LocalUserManager, which handles various tasks specific to ZDCLocalUser’s.
    See more

    Declaration

    Objective-C

    @interface ZDCUserManager : NSObject

    Swift

    class ZDCUserManager : NSObject
  • The SearchManager allows you to search for other users within the system.

    Recall that user’s are allows to link multiple identities to their account. For example, a user may choose to link all of the following:

    • Facebook
    • LinkedIn
    • GitHub

    This makes searching much easier for the user. They can search for friends & colleagus using the social connections in which they already interact. And the search API allows them to limit their search to particular networks (e.g. only seach GitHub).

    See more

    Declaration

    Objective-C

    @interface ZDCUserSearchManager : NSObject

    Swift

    class ZDCUserSearchManager : NSObject