Sailfish Secrets
API DocumentationPluginBase Class
(Sailfish::Secrets::PluginBase)Provides the base interface for extension plugins for the Sailfish OS Secrets and Crypto Framework. More...
| Header: | #include <Secrets/Plugins/extensionplugins.h> |
| Inherited By: | Sailfish::Secrets::AuthenticationPlugin, Sailfish::Secrets::EncryptedStoragePlugin, Sailfish::Secrets::EncryptionPlugin, and Sailfish::Secrets::StoragePlugin |
Public Functions
| PluginBase() | |
| virtual | ~PluginBase() |
| virtual QString | displayName() const = 0 |
| virtual void | initialize() |
| virtual bool | isAvailable() const |
| virtual bool | isLocked() const |
| virtual bool | lock() |
| virtual QString | name() const = 0 |
| virtual bool | setLockCode(const QByteArray &oldLockCode, const QByteArray &newLockCode) |
| virtual bool | supportsLocking() const |
| virtual bool | supportsSetLockCode() const |
| virtual bool | unlock(const QByteArray &code) |
| virtual int | version() const = 0 |
Detailed Description
Provides the base interface for extension plugins for the Sailfish OS Secrets and Crypto Framework.
PluginBase is an abstract base class which provides an interface which all extension plugins must implement. This interface includes some information about the plugin (including its name and version, and whether or not it supports locking), as well as locking operation methods.
Extension plugins are loaded by the Sailfish OS Secrets and Crypto Framework daemon, and the functionality of those plugins is exposed to clients via the Secrets and Crypto API.
There are a variety of extension plugin types which each extend PluginBase, which define specific interfaces which concrete derived types must implement. A list of the available Secrets extension plugin types follows:
- Sailfish::Secrets::AuthenticationPlugin perform suser authentication and verification
- Sailfish::Secrets::EncryptionPlugin encrypts secret data for secrets stored in a Sailfish::Secrets::StoragePlugin
- Sailfish::Secrets::StoragePlugin provides unencrypted storage for secrets
- Sailfish::Secrets::EncryptedStoragePlugin provides encrypted storage for secrets
In addition, there also exists the Sailfish::Crypto::CryptoPlugin extension plugin type, which provides cryptographic functionality to clients (See the Sailfish OS Crypto library documentation for more details). If a particular plugin implements both the Sailfish::Crypto::CryptoPlugin and Sailfish::Secrets::EncryptedStoragePlugin interfaces then it is able to secure store cryptographic keys as well as perform cryptographic operations using those keys, and is referred to as a Crypto-Storage Plugin.
Plugin implementers should not extend PluginBase directly, but should instead derive from one of the above-listed plugin types (or both CryptoPlugin and EncryptedStoragePlugin if they are implementing a Crypto-Storage plugin).
Plugin implementers must be aware that the information reporting methods (name(), version(), supportsLocking(), and supportsSetLockCode()) will be invoked from the main thread of the secrets daemon, while the various locking operation methods (isLocked(), lock(), unlock(), and setLockCode()) and availability reporting method (isAvailable()) will be invoked from a separate thread. Plugins are loaded and plugin instances are constructed in the main thread.
In order to implement a Secrets extension plugin, plugin implementers should specify the following in their .pro file:
CONFIG += link_pkgconfig PKGCONFIG += sailfishsecretspluginapi
An example (skeleton) Encrypted Storage plugin (which also implements the CryptoPlugin interface) may be found at: https://github.com/sailfishos/sailfish-secrets/tree/master/examples/plugins/examplecryptostorageplugin/
Member Function Documentation
PluginBase::PluginBase()
Constructs a new PluginBase instance
[virtual] PluginBase::~PluginBase()
Cleans up the memory associated with the PluginBase instance
[pure virtual] QString PluginBase::displayName() const
Return the translated display name of the plugin
This name will be shown to the user of the device in system prompts when an attempt is made to access a secret or key stored within the plugin. It should be a human-readable string, which is informative for the user, and may need to be translated into different languages if the display name is not a proper noun.
For example, the example encrypted storage plugin based on SQLCipher has the display name "SQLCipher".
[virtual] void PluginBase::initialize()
Initialize the plugin
Derived types should override this method in order to perform initialization rather than doing so in the constructor, as this method will be called once the loaded plugin is accepted for use by the daemon.
This allows the creation of e.g. socket files or other such system side effects to be meaningful and non-interfering.
[virtual] bool PluginBase::isAvailable() const
Returns true if the plugin is available for use.
The default implementation returns true, as by default it is assumed that the plugin does not require any external hardware to be connected to the device in order to offer functionality to clients. This method should be overridden by a specific plugin implementation if it requires physical hardware (e.g. a USB token) or network connectivity (e.g. to talk to remote web service) and thus may situationally be either available or unavailable.
[virtual] bool PluginBase::isLocked() const
Returns true if the plugin is currently locked.
The default implementation returns false, as by default it is assumed that the plugin does not support locking. This method should be overridden by a specific plugin implementation if it requires an unlock code to be provided by the user prior to use, to ensure that this method reports the lock state of the plugin.
[virtual] bool PluginBase::lock()
Returns true if the plugin was able to be locked.
The default implementation does nothing and returns false, as by default it is assumed that the plugin does not support locking. This method should be overridden in order to perform the locking operation as required, if the plugin requires an unlock code to be provided by the user prior to use.
[pure virtual] QString PluginBase::name() const
Return the name of the plugin
This name must be globally unique, so a fully-qualified-domain-name prefix is recommended.
For example, the example encrypted storage plugin based on SQLCipher has the name: "org.sailfishos.secrets.encryptedstorage.sqlcipher".
[virtual] bool PluginBase::setLockCode(const QByteArray &oldLockCode, const QByteArray &newLockCode)
Returns true if the lock code for the plugin was able to be set.
The default implementation does nothing and returns false, as by default it is assumed that the plugin does not support locking. If the plugin implementation supports locking, and allows the lock code for the plugin to be changed, then this method should be overridden in order to perform the operation to set the lock code to the given newLockCode if the given oldLockCode was correct.
[virtual] bool PluginBase::supportsLocking() const
Returns true if the plugin supports locking semantics.
The default implementation returns false. This method should be overridden by a specific plugin implementation if it requires an unlock code to be provided by the user prior to use.
[virtual] bool PluginBase::supportsSetLockCode() const
Returns true if the plugin supports allowing clients to set the lock code.
The default implementation returns the same value as supportsLocking(), as most plugins which support locking should allow clients to change the lock code, however this may be overridden by the plugin implementation if the lock code is pre-set and cannot be changed, or if the lock code may only be set initially but thereafter cannot be changed.
[virtual] bool PluginBase::unlock(const QByteArray &code)
Returns true if the plugin was able to be unlocked with the provided code.
The default implementation does nothing and returns false, as by default it is assumed that the plugin does not support locking. This method should be overridden in order to perform the unlocking operation as required, if the plugin requires an unlock code to be provided by the user prior to use.
[pure virtual] int PluginBase::version() const
Return the version of the plugin
Plugin implementers must document to clients the semantics of every operation they offer through the Sailfish::Secrets or Sailfish::Crypto APIs. Given that the semantics of the implementation may change from version to version, the version of the plugin must be reported programmatically.