Member Function Documentation

CipherRequest::CipherRequest(QObject *parent = Q_NULLPTR)

Constructs a new CipherRequest object with the given parent.

CipherRequest::~CipherRequest()

Destroys the CipherRequest

Sailfish::Crypto::CryptoManager::BlockMode CipherRequest::blockMode() const

Returns the block mode which should be used when encrypting the data

Note: Getter function for property blockMode.

See also setBlockMode().

CipherMode CipherRequest::cipherMode() const

Returns the mode which the client wishes to apply to the cipher session

Note: Getter function for property cipherMode.

See also setCipherMode().

QString CipherRequest::cryptoPluginName() const

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

Note: Getter function for property cryptoPluginName.

See also setCryptoPluginName().

[virtual] QVariantMap CipherRequest::customParameters() const

See also setCustomParameters().

QByteArray CipherRequest::data() const

Returns the data which the client wishes the system service to operate on

Note: Getter function for property data.

See also setData().

Sailfish::Crypto::CryptoManager::DigestFunction CipherRequest::digestFunction() const

Returns the digest which should be used when signing or verifying the data

Note: Getter function for property digestFunction.

See also setDigestFunction().

Sailfish::Crypto::CryptoManager::EncryptionPadding CipherRequest::encryptionPadding() const

Returns the encryption padding mode which should be used when encrypting or decrypting the data

Note: Getter function for property encryptionPadding.

See also setEncryptionPadding().

QByteArray CipherRequest::generatedData() const

Returns the generated data result of the cipher operation.

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

Note: Getter function for property generatedData.

QByteArray CipherRequest::initializationVector() const

Returns the initialization vector which the client wishes to use when encrypting or decrypting the data

Note: Getter function for property initializationVector.

See also setInitializationVector().

Sailfish::Crypto::Key CipherRequest::key() const

Returns the key which the client wishes the system service to use to encrypt the data

Note: Getter function for property key.

See also setKey().

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

See also setManager().

Sailfish::Crypto::CryptoManager::Operation CipherRequest::operation() const

Returns the operation which the client wishes to perform with the cipher session

Note: Getter function for property operation.

See also setOperation().

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

void CipherRequest::setBlockMode(Sailfish::Crypto::CryptoManager::BlockMode mode)

Sets the block mode which should be used when encrypting the data to mode

Note: Setter function for property blockMode.

See also blockMode().

void CipherRequest::setCipherMode(CipherMode mode)

Sets the mode which the client wishes to apply to the cipher session to mode

The mode will be applied by the system crypto service to the cipher session. In general, the client will want to initialize the cipher session, and then repeatedly update the cipher session with data to be operated upon, and then when finished with all data should finalize the cipher session.

The following example shows how to use a CipherRequest to encrypt a stream of data using AES 256 encryption in CBC mode. Note that it forces the request to finish synchronously, however this is purely to keep the example concise; real code should not use the waitForFinished() method, but instead should react to the statusChanged() signal to determine when each step of the request has finished. Also, error checking has been omitted for brevity.

 QByteArray ciphertext;
 CipherRequest cr;
 cr.setManager(cryptoManager);

 // Initialize the cipher.
 cr.setCipherMode(CipherRequest::InitializeCipher);
 cr.setKey(key); // a valid AES 256 key or key reference
 cr.setBlockMode(Sailfish::Crypto::CryptoManager::BlockModeCbc);
 cr.setOperation(Sailfish::Crypto::CryptoManager::OperationEncrypt);
 cr.setInitializationVector(initializationVector);    // See GenerateInitializationVectorRequest
 cr.startRequest();
 cr.waitForFinished();

 // Update the cipher session with data to encrypt.
 while (morePlaintextBlocks()) {
     cr.setCipherMode(CipherRequest::UpdateCipher);
     cr.setData(getPlaintextBlock()); // e.g. read from file
     cr.startRequest();
     cr.waitForFinished();
     ciphertext.append(cr.generatedData());
 }

 // Finalize the cipher session.
 cr.setCipherMode(CipherRequest::FinalizeCipher);
 cr.startRequest();
 cr.waitForFinished();
 ciphertext.append(cr.generatedData());

To decrypt some ciphertext, the same initialization vector must be specified as was used to encrypt the plaintext data originally. An example of decrypting data follows:

 QByteArray plaintext;
 CipherRequest cr;
 cr.setManager(cryptoManager);

 // Initialize the cipher.
 cr.setCipherMode(CipherRequest::InitializeCipher);
 cr.setKey(key); // a valid AES 256 key or key reference
 cr.setBlockMode(Sailfish::Crypto::CryptoManager::BlockModeCbc);
 cr.setOperation(Sailfish::Crypto::CryptoManager::OperationDecrypt);
 cr.setInitializationVector(initializationVector); // IV used during encryption.
 cr.startRequest();
 cr.waitForFinished();

 // Update the cipher session with data to decrypt.
 while (moreCiphertextBlocks()) {
     cr.setCipherMode(CipherRequest::UpdateCipher);
     cr.setData(getCiphertextBlock()); // e.g. read from file
     cr.startRequest();
     cr.waitForFinished();
     // Note: in CBC mode the first generatedData() will be smaller
     // than the input data by one complete block (16 bytes for AES 256).
     plaintext.append(cr.generatedData());
 }

 // Finalize the cipher session.
 cr.setCipherMode(CipherRequest::FinalizeCipher);
 cr.startRequest();
 cr.waitForFinished();
 plaintext.append(cr.generatedData());

Note that authenticated encryption and decryption is slightly different, as encryption finalization produces an authentication tag, which must be provided during decryption finalization for verification. For example, after encrypting data using BlockModeGcm:

 // Finalize the GCM encryption cipher session.
 cr.setCipherMode(CipherRequest::FinalizeCipher);
 cr.startRequest();
 cr.waitForFinished();
 QByteArray gcmTag = cr.generatedData();

and when decrypting, the authentication tag should be provided for finalization and the verificationStatus flag should be checked carefully:

 // Finalize the GCM decryption cipher session.
 cr.setCipherMode(CipherRequest::FinalizeCipher);
 cr.setData(gcmTag);
 cr.startRequest();
 cr.waitForFinished();
 Sailfish::Crypto::CryptoManager::VerificationStatus status = cr.verificationStatus();

If mode is either CipherRequest::UpdateCipher or CipherRequest::FinalizeCipher then when the request is finished the generatedData() should contain the block of data which was generated based upon the input data (that is, it will be encrypted, decrypted, or signature data) or alternatively verificationStatus() should contain whether the signature data was verificationStatus or if authenticated decryption succeeded, if the operation() was CryptoManager::OperationEncrypt, CryptoManager::OperationDecrypt, CryptoManager::Sign, or CryptoManager::Verify or CryptoManager::OperationDecrypt with BlockModeGcm respectively.

Note: Setter function for property cipherMode.

See also cipherMode().

void CipherRequest::setCryptoPluginName(const QString &pluginName)

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

Note: Setter function for property cryptoPluginName.

See also cryptoPluginName().

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

See also customParameters().

void CipherRequest::setData(const QByteArray &data)

Sets the data which the client wishes the system service to operate on to data

Note: Setter function for property data.

See also data().

void CipherRequest::setDigestFunction(Sailfish::Crypto::CryptoManager::DigestFunction digestFn)

Sets tthe digest which should be used when signing or verifying the data to digestFn

Note: Setter function for property digestFunction.

See also digestFunction().

void CipherRequest::setEncryptionPadding(Sailfish::Crypto::CryptoManager::EncryptionPadding padding)

Sets the encryption padding mode which should be used when encrypting or decrypting the data to padding

Note: Setter function for property encryptionPadding.

See also encryptionPadding().

void CipherRequest::setInitializationVector(const QByteArray &iv)

Sets the initialization vector which the client wishes to use when encrypting or decrypting the data to iv

This initialization vector data will only be used for encrypt or decrypt operations, and is only passed to the system service when the cipher mode is CipherRequest::InitializeCipher.

Note that this is only applicable for certain key types using certain modes of encryption or decryption (e.g. CBC mode with AES symmetric keys).

The client must specify the same initialization vector when decrypting the cipher text as they used when encrypting it. The initialization vector is not secret, and can be stored along with the ciphertext, however it should be generated using a cryptographically secure random number generator (see GenerateRandomDataRequest) and must be the appropriate size according to the cipher.

Note: Setter function for property initializationVector.

See also initializationVector().

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

See also manager().

void CipherRequest::setSignaturePadding(Sailfish::Crypto::CryptoManager::SignaturePadding padding)

Sets the signature padding mode which should be used when signing or verifying the data to padding

Note: Setter function for property signaturePadding.

See also signaturePadding().

Sailfish::Crypto::CryptoManager::SignaturePadding CipherRequest::signaturePadding() const

Returns the signature padding mode which should be used when signing or verifying the data

Note: Getter function for property signaturePadding.

See also setSignaturePadding().

[virtual] void CipherRequest::startRequest()

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

Sailfish::Crypto::CryptoManager::VerificationStatus CipherRequest::verificationStatus() const

Returns the result of the verify operation.

Note: this value is only valid if the status of the request is Request::Finished and the cipher session has been finalized and the operation() was CryptoManager::OperationVerify.

Note: Getter function for property verificationStatus.

[virtual] void CipherRequest::waitForFinished()