Spezi Storage

The Spezi Storage framework provides two Modules that enable on-disk storage of information. The LocalStorage module can be used to store information that does not need to be encrypted. Credentials, keys, and other sensitive information that needs to be encrypted may be stored by using the SecureStorage module.

Setup

You need to add the Spezi Storage Swift package to your app in Xcode or Swift package.

[!IMPORTANT] If your application is not yet configured to use Spezi, follow the Spezi setup article to set up the core Spezi infrastructure.

[!IMPORTANT] If you use SpeziStorage on the macOS platform, ensure to add the Keychain Access Groups entitlement to the enclosing Xcode project via PROJECT_NAME > Signing&Capabilities > + Capability. The array of keychain groups can be left empty, only the base entitlement is required.

You can configure the LocalStorage or SecureStorage module in the SpeziAppDelegate.

import Spezi
import SpeziLocalStorage
import SpeziSecureStorage


class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            LocalStorage()
            SecureStorage()
            // ...
        }
    }
}

You can then use the LocalStorage or SecureStorage class in any SwiftUI view.

struct ExampleStorageView: View {
    @Environment(LocalStorage.self) var secureStorage
    @Environment(SecureStorage.self) var secureStorage
    
    
    var body: some View {
        // ...
    }
}

Alternatively, it is common to use the LocalStorage or SecureStorage module in other modules as a dependency: Spezi Module dependencies.

Local Storage

The LocalStorage module enables the on-disk storage of data in mobile applications.

The LocalStorage module defaults to storing data encrypted supported by the SecureStorage module. The LocalStorageSetting enables configuring how data in the LocalStorage module can be stored and retrieved.

• Store or update new elements: store(_:storageKey:settings:)
• Retrieve existing elements: read(_:storageKey:settings:)
• Delete existing elements: delete(_:)

Secure Storage

The SecureStorage module allows for the encrypted storage of small chunks of sensitive user data, such as usernames and passwords for internet services, using Apple's Keychain documentation.

Credentials can be stored in the Secure Enclave (if available) or the Keychain. Credentials stored in the Keychain can be made synchronizable between different instances of user devices.

Handling Credentials

Use the SecureStorage module to store a set of Credentials instances in the Keychain associated with a server that is synchronizable between different devices.

• Store new credentials: store(credentials:server:removeDuplicate:storageScope:)
• Retrieve existing credentials: retrieveCredentials(_:server:accessGroup:)
• Retrieve all matching existing credentials: retrieveAllCredentials(forServer:accessGroup:)
• Update existing credentials: updateCredentials(_:server:newCredentials:newServer:removeDuplicate:storageScope:)
• Delete existing credentials: deleteCredentials(_:server:accessGroup:)
• Delete all matching existing credentials: deleteAllCredentials(itemTypes:accessGroup:)

Handling Keys

Similar to Credentials instances, you can also use the SecureStorage module to interact with keys.

• Create new keys: createKey(_:size:storageScope:)
• Retrieve existing public keys: retrievePublicKey(forTag:)
• Retrieve existing private keys: retrievePrivateKey(forTag:)
• Delete existing keys: deleteKeys(forTag:)

For more information, please refer to the API documentation.

The Spezi Template Application

The Spezi Template Application provides a great starting point and example using the Spezi Storage module.

Contributing

Contributions to this project are welcome. Please make sure to read the contribution guidelines and the contributor covenant code of conduct first.

License

This project is licensed under the MIT License. See Licenses for more information.