Sailfish Crypto

API Documentation

GenerateKeyRequest Class

(Sailfish::Crypto::GenerateKeyRequest)

Allows a client request that the system crypto service generate and secure store a key based on a template. More...

Header:	#include <Crypto/generatekeyrequest.h> #include <Crypto/generatestoredkeyrequest.h>
Instantiated By:	GenerateKeyRequest
Inherits:	Sailfish::Crypto::Request

List of all members, including inherited members

Properties

cryptoPluginName : QString
generatedKey : const Sailfish::Crypto::Key
keyDerivationParameters : Sailfish::Crypto::KeyDerivationParameters

keyPairGenerationParameters : Sailfish::Crypto::KeyPairGenerationParameters
keyTemplate : Sailfish::Crypto::Key

4 properties inherited from Sailfish::Crypto::Request

Public Functions

	GenerateKeyRequest(QObject *parent = Q_NULLPTR)
	~GenerateKeyRequest()
QString	cryptoPluginName() const
Sailfish::Crypto::Key	generatedKey() const
Sailfish::Crypto::KeyDerivationParameters	keyDerivationParameters() const
Sailfish::Crypto::KeyPairGenerationParameters	keyPairGenerationParameters() const
Sailfish::Crypto::Key	keyTemplate() const
void	setCryptoPluginName(const QString &pluginName)
void	setKeyDerivationParameters(const Sailfish::Crypto::KeyDerivationParameters &params)
void	setKeyPairGenerationParameters(const Sailfish::Crypto::KeyPairGenerationParameters &params)
void	setKeyTemplate(const Sailfish::Crypto::Key &key)

Reimplemented Public Functions

virtual QVariantMap	customParameters() const
virtual Sailfish::Crypto::CryptoManager *	manager() const
virtual Sailfish::Crypto::Result	result() const
virtual void	setCustomParameters(const QVariantMap &params)
virtual void	setManager(Sailfish::Crypto::CryptoManager *manager)
virtual void	startRequest()
virtual Sailfish::Crypto::Request::Status	status() const
virtual void	waitForFinished()

8 public functions inherited from Sailfish::Crypto::Request

Signals

void	cryptoPluginNameChanged()
void	generatedKeyChanged()
void	keyDerivationParametersChanged()
void	keyPairGenerationParametersChanged()
void	keyTemplateChanged()

4 signals inherited from Sailfish::Crypto::Request

Detailed Description

Allows a client request that the system crypto service generate and secure store a key based on a template.

The generated key will be stored securely by the crypto daemon via the storage plugin identified by the storage plugin specified in the key template's identifier, and the returned key reference will not contain any private or secret key data.

Available storage providers can be enumerated from the Sailfish Secrets API.

If the cryptoPluginName() is the same as the Key::Identifier::storagePluginName(), then the key will be stored in storage managed by the crypto provider plugin, if that plugin supports storing keys. In that case, the crypto plugin must also be a Sailfish::Secrets::EncryptedStoragePlugin. Such crypto storage plugins can enforce key component readability constraints, and allow cryptographic operations to occur in the most secure manner possible.

When generating a key for a symmetric cipher algorithm, the client application can request that a specific key derivation function be used to derive the secret key data, via the KeyDerivationParameters option. The input data to the key derivation function may either be specified within those parameters, or alternatively can be requested (by the secrets service) directly from the user if valid InteractionParameters are specified. In that case, the user will be prompted to enter a passphrase, PIN, or other data which will then be used as the input key data by the key derivation function.

See the following for an example of how to generate (via PBKDF2 derivation with HMAC-SHA512, from a user-supplied input passphrase) a 256-bit key intended for use with AES encryption and decryption operations, and store it in secure storage (assuming the prior existence of the collection named "ExampleCollection" stored by a specific crypto storage plugin):

 // Define the key metadata via a template.
 Sailfish::Crypto::Key keyTemplate;
 keyTemplate.setAlgorithm(Sailfish::Crypto::CryptoManager::AlgorithmAes);
 keyTemplate.setOrigin(Sailfish::Crypto::Key::OriginDevice);
 keyTemplate.setOperations(Sailfish::Crypto::CryptoManager::OperationEncrypt | Sailfish::Crypto::CryptoManager::OperationDecrypt);
 keyTemplate.setComponentConstraints(Sailfish::Crypto::Key::MetaData | Sailfish::Crypto::Key::PublicKeyData);

 // The key will be stored by the default crypto storage plugin
 // in the specified collection, with the given name.
 // NOTE: the collection must already exist, or this request will fail.
 // You can create new collections using the Sailfish OS Secrets API.
 keyTemplate.setIdentifier(
         Sailfish::Crypto::Key::Identifier(
             QLatin1String("ExampleKey"),
             QLatin1String("ExampleCollection"),
             Sailfish::Crypto::CryptoManager::DefaultCryptoStoragePluginName));

 // Specify the key derivation parameters which define how the key data
 // should be generated by the crypto plugin from the input data.
 Sailfish::Crypto::KeyDerivationParameters skdf;
 skdf.setKeyDerivationFunction(Sailfish::Crypto::CryptoManager::KdfPkcs5Pbkdf2);
 skdf.setKeyDerivationMac(Sailfish::Crypto::CryptoManager::MacHmac);
 skdf.setKeyDerivationDigestFunction(Sailfish::Crypto::CryptoManager::DigestSha512);
 skdf.setIterations(16384);
 skdf.setSalt(saltData); // 16 bytes, randomly generated, can be stored in plaintext in app data.
 skdf.setOutputKeySize(256);

 // Specify the interaction parameters which define how the the prompt
 // for the user to enter the input data should look and feel.
 Sailfish::Crypto::InteractionParameters uiParams;
 uiParams.setInputType(Sailfish::Crypto::InteractionParameters::AlphaNumericInput);
 uiParams.setEchoMode(Sailfish::Crypto::InteractionParameters::NormalEcho);

 // Ask the crypto service to perform the required operations.
 Sailfish::Crypto::GenerateStoredKeyRequest gskr;
 gskr.setManager(cryptoManager);
 gskr.setCryptoPluginName(Sailfish::Crypto::CryptoManager::DefaultCryptoStoragePluginName);
 gskr.setKeyTemplate(keyTemplate);
 gskr.setKeyDerivationParameters(skdf);
 gskr.setInteractionParameters(uiParams);
 gskr.startRequest();

You can also generate an asymmetric cipher key; however, these are not derived from input key data, but instead generated randomly given certain starting parameters. An example of generating an asymmetric RSA key pair follows:

 // Define the key metadata via a template.
 Sailfish::Crypto::Key keyTemplate;
 keyTemplate.setAlgorithm(Sailfish::Crypto::CryptoManager::AlgorithmRsa);
 keyTemplate.setOrigin(Sailfish::Crypto::Key::OriginDevice);
 keyTemplate.setOperations(Sailfish::Crypto::CryptoManager::OperationEncrypt
                          |Sailfish::Crypto::CryptoManager::OperationDecrypt
                          |Sailfish::Crypto::CryptoManager::OperationSign
                          |Sailfish::Crypto::CryptoManager::OperationVerify);
 keyTemplate.setComponentConstraints(Sailfish::Crypto::Key::MetaData | Sailfish::Crypto::Key::PublicKeyData);
 keyTemplate.setIdentifier(
         Sailfish::Crypto::Key::Identifier(
             QLatin1String("ExampleRsaKey"),
             QLatin1String("ExampleCollection"),
             Sailfish::Crypto::CryptoManager::DefaultCryptoStoragePluginName)));

 // Define some parameters for key-pair generation
 Sailfish::Crypto::RsaKeyPairGenerationParameters kpg;
 kpg.setModulusLength(4096);
 kpg.setPublicExponent(65537);
 kpg.setNumberPrimes(2);

 // Ask the crypto service to perform the required operations.
 Sailfish::Crypto::GenerateStoredKeyRequest gskr;
 gskr.setManager(cryptoManager);
 gskr.setCryptoPluginName(Sailfish::Crypto::CryptoManager::DefaultCryptoStoragePluginName);
 gskr.setKeyTemplate(keyTemplate);
 gskr.setKeyPairGenerationParameters(kpg);
 gskr.startRequest();

Property Documentation

cryptoPluginName : QString

Access functions:

QString	cryptoPluginName() const
void	setCryptoPluginName(const QString &pluginName)

Notifier signal:

void	cryptoPluginNameChanged()

generatedKey : const Sailfish::Crypto::Key

Access functions:

Sailfish::Crypto::Key generatedKey() const

Notifier signal:

void	generatedKeyChanged()

keyDerivationParameters : Sailfish::Crypto::KeyDerivationParameters

Access functions:

Sailfish::Crypto::KeyDerivationParameters	keyDerivationParameters() const
void	setKeyDerivationParameters(const Sailfish::Crypto::KeyDerivationParameters &params)

Notifier signal:

void	keyDerivationParametersChanged()

keyPairGenerationParameters : Sailfish::Crypto::KeyPairGenerationParameters

Access functions:

Sailfish::Crypto::KeyPairGenerationParameters	keyPairGenerationParameters() const
void	setKeyPairGenerationParameters(const Sailfish::Crypto::KeyPairGenerationParameters &params)

Notifier signal:

void	keyPairGenerationParametersChanged()

keyTemplate : Sailfish::Crypto::Key

Access functions:

Sailfish::Crypto::Key	keyTemplate() const
void	setKeyTemplate(const Sailfish::Crypto::Key &key)

Notifier signal:

void	keyTemplateChanged()

Member Function Documentation

GenerateKeyRequest::GenerateKeyRequest(QObject **parent* = Q_NULLPTR)

Constructs a new GenerateKeyRequest object with the given parent.

GenerateKeyRequest::~GenerateKeyRequest()

Destroys the GenerateKeyRequest

QString GenerateKeyRequest::cryptoPluginName() const

Returns the name of the crypto plugin which the client wishes to perform the key generation operation

Note: Getter function for property cryptoPluginName.

See also setCryptoPluginName().

`[virtual]` QVariantMap GenerateKeyRequest::customParameters() const

See also setCustomParameters().

Sailfish::Crypto::Key GenerateKeyRequest::generatedKey() const

Returns the generated key

Note: this value is only valid if the status of the request is Request::Finished.

Note: Getter function for property generatedKey.

Sailfish::Crypto::KeyDerivationParameters GenerateKeyRequest::keyDerivationParameters() const

Returns the symmetric key derivation parameters which should be used to generate the secret key data

These parameters are only meaningful if the template key algorithm is a symmetric cipher algorithm.

Note: Getter function for property keyDerivationParameters.

See also setKeyDerivationParameters().

Sailfish::Crypto::KeyPairGenerationParameters GenerateKeyRequest::keyPairGenerationParameters() const

Returns the asymmetric key pair generation parameters which should be used to generate the public and private key data

These parameters are only meaningful if the template key algorithm is an asymmetric cipher algorithm.

Note: Getter function for property keyPairGenerationParameters.

See also setKeyPairGenerationParameters().

Sailfish::Crypto::Key GenerateKeyRequest::keyTemplate() const

Returns the key which should be used as a template when generating the full key

Note: Getter function for property keyTemplate.

See also setKeyTemplate().

`[virtual]` Sailfish::Crypto::CryptoManager *GenerateKeyRequest::manager() const

See also setManager().

`[virtual]` Sailfish::Crypto::Result GenerateKeyRequest::result() const

void GenerateKeyRequest::setCryptoPluginName(const QString &pluginName)

Sets the name of the crypto plugin which the client wishes to perform the key generation operation to pluginName

Note: Setter function for property cryptoPluginName.

See also cryptoPluginName().

`[virtual]` void GenerateKeyRequest::setCustomParameters(const QVariantMap &params)

See also customParameters().

`[virtual]` void GenerateKeyRequest::setManager(Sailfish::Crypto::CryptoManager **manager*)

See also manager().

Contents

GenerateKeyRequest Class

Properties

Public Functions

Reimplemented Public Functions

Signals

Detailed Description

Property Documentation

cryptoPluginName : QString

generatedKey : const Sailfish::Crypto::Key

keyDerivationParameters : Sailfish::Crypto::KeyDerivationParameters

keyPairGenerationParameters : Sailfish::Crypto::KeyPairGenerationParameters

keyTemplate : Sailfish::Crypto::Key

Member Function Documentation

GenerateKeyRequest::GenerateKeyRequest(QObject **parent* = Q_NULLPTR)

GenerateKeyRequest::~GenerateKeyRequest()

QString GenerateKeyRequest::cryptoPluginName() const

`[virtual]` QVariantMap GenerateKeyRequest::customParameters() const

Sailfish::Crypto::Key GenerateKeyRequest::generatedKey() const

Sailfish::Crypto::KeyDerivationParameters GenerateKeyRequest::keyDerivationParameters() const

Sailfish::Crypto::KeyPairGenerationParameters GenerateKeyRequest::keyPairGenerationParameters() const

Sailfish::Crypto::Key GenerateKeyRequest::keyTemplate() const

`[virtual]` Sailfish::Crypto::CryptoManager *GenerateKeyRequest::manager() const

`[virtual]` Sailfish::Crypto::Result GenerateKeyRequest::result() const

void GenerateKeyRequest::setCryptoPluginName(const QString &pluginName)

`[virtual]` void GenerateKeyRequest::setCustomParameters(const QVariantMap &params)

`[virtual]` void GenerateKeyRequest::setManager(Sailfish::Crypto::CryptoManager **manager*)

`[virtual]` void GenerateKeyRequest::startRequest()

`[virtual]` Sailfish::Crypto::Request::Status GenerateKeyRequest::status() const

`[virtual]` void GenerateKeyRequest::waitForFinished()

Sailfish Crypto

Contents

GenerateKeyRequest Class

Properties

Public Functions

Reimplemented Public Functions

Signals

Detailed Description

Property Documentation

cryptoPluginName : QString

generatedKey : const Sailfish::Crypto::Key

keyDerivationParameters : Sailfish::Crypto::KeyDerivationParameters

keyPairGenerationParameters : Sailfish::Crypto::KeyPairGenerationParameters

keyTemplate : Sailfish::Crypto::Key

Member Function Documentation

GenerateKeyRequest::GenerateKeyRequest(QObject *parent = Q_NULLPTR)

GenerateKeyRequest::~GenerateKeyRequest()

QString GenerateKeyRequest::cryptoPluginName() const

[virtual] QVariantMap GenerateKeyRequest::customParameters() const

Sailfish::Crypto::Key GenerateKeyRequest::generatedKey() const

Sailfish::Crypto::KeyDerivationParameters GenerateKeyRequest::keyDerivationParameters() const

Sailfish::Crypto::KeyPairGenerationParameters GenerateKeyRequest::keyPairGenerationParameters() const

Sailfish::Crypto::Key GenerateKeyRequest::keyTemplate() const

[virtual] Sailfish::Crypto::CryptoManager *GenerateKeyRequest::manager() const

[virtual] Sailfish::Crypto::Result GenerateKeyRequest::result() const

void GenerateKeyRequest::setCryptoPluginName(const QString &pluginName)

[virtual] void GenerateKeyRequest::setCustomParameters(const QVariantMap &params)

[virtual] void GenerateKeyRequest::setManager(Sailfish::Crypto::CryptoManager *manager)

[virtual] void GenerateKeyRequest::startRequest()

[virtual] Sailfish::Crypto::Request::Status GenerateKeyRequest::status() const

[virtual] void GenerateKeyRequest::waitForFinished()

GenerateKeyRequest::GenerateKeyRequest(QObject **parent* = Q_NULLPTR)

`[virtual]` QVariantMap GenerateKeyRequest::customParameters() const

`[virtual]` Sailfish::Crypto::CryptoManager *GenerateKeyRequest::manager() const

`[virtual]` Sailfish::Crypto::Result GenerateKeyRequest::result() const

`[virtual]` void GenerateKeyRequest::setCustomParameters(const QVariantMap &params)

`[virtual]` void GenerateKeyRequest::setManager(Sailfish::Crypto::CryptoManager **manager*)

`[virtual]` void GenerateKeyRequest::startRequest()

`[virtual]` Sailfish::Crypto::Request::Status GenerateKeyRequest::status() const

`[virtual]` void GenerateKeyRequest::waitForFinished()