10Duke Enterprise C++ SDK
Loading...
Searching...
No Matches
tenduke::crypto::Ciphers Class Referenceabstract

#include <Ciphers.h>

Detailed Description

A "service locator" for cipher-related operations.

This class consolidates cipher-related operations into a single interface. It provides methods for encrypting and decrypting data using the system default cipher (AES256 GCM).

Encryption key of the methods taking encryptionKey (blob version 1): The AES key is derived from encryptionKey with PBKDF2-HMAC-SHA256, 100,000 iterations, using the random IV as the salt. Use a high-entropy key, e.g. 32 random bytes stored in the operating system's credential store. Do not use a password chosen by a person: the iteration count is below current recommendations for passwords.

The blob header (magic and version) is not authenticated, only the content after it is. Changing the header can only make decryption fail, it cannot make it succeed with different content.

Plaintext returned as BinaryData is wiped from memory when it is destroyed. Plaintext returned as std::string (decryptString()) is not, so prefer decrypt() for secrets.

Inheritance diagram for tenduke::crypto::Ciphers:
tenduke::crypto::AbstractCiphers tenduke::crypto::libcrypto::LibcryptoCiphers tenduke::crypto::win::cng::WinCNGCiphers

Public Member Functions

virtual std::unique_ptr<::tenduke::utl::BinaryData > decrypt (const ::tenduke::utl::DataSpan &ciphertext, const ::tenduke::utl::DataSpan &encryptionKey) const =0
 Decrypts given data using the system default cipher (AES256 GCM).
virtual std::string decryptString (const ::tenduke::utl::DataSpan &ciphertext, const ::tenduke::utl::DataSpan &encryptionKey) const =0
 Decrypts given data using the system default cipher (AES256 GCM) to a string.
virtual std::string decryptString (const ::tenduke::crypto::Cipher &cipher, const ::tenduke::utl::DataSpan &ciphertext) const =0
 Decrypts given data using the given cipher to a string.
virtual void encrypt (const ::tenduke::crypto::Cipher &cipher, const ::tenduke::utl::DataSpan &plaintext, ::tenduke::utl::DataSink &ciphertext) const =0
 Encrypts data with the given cipher.
virtual std::unique_ptr<::tenduke::utl::BinaryData > encrypt (const ::tenduke::utl::DataSpan &plaintext, const ::tenduke::utl::DataSpan &encryptionKey) const =0
 Encrypts given data using the system default cipher (AES256 GCM).
virtual std::unique_ptr<::tenduke::utl::BinaryData > encrypt (const std::string &plaintext, const ::tenduke::utl::DataSpan &encryptionKey) const =0
 Encrypts given data using the system default cipher (AES256 GCM).

Member Function Documentation

◆ decrypt()

virtual std::unique_ptr<::tenduke::utl::BinaryData > tenduke::crypto::Ciphers::decrypt ( const ::tenduke::utl::DataSpan & ciphertext,
const ::tenduke::utl::DataSpan & encryptionKey ) const
pure virtual

Decrypts given data using the system default cipher (AES256 GCM).

This method expects the input to consist of magic (4 bytes) + version (2 bytes) + IV (12 bytes) + ciphertext + tag (16 bytes), i.e., the output produced by calling ::encrypt(key, plaintext).

This is "syntactic sugar": The method also performs key-derivation for the provided key to simplify the use.

Parameters
ciphertextthe cipher text (the data to decrypt), the maximum supported length is INT_MAX.
encryptionKeyencryption key
Returns
plain text (decrypted data)

Implemented in tenduke::crypto::AbstractCiphers.

◆ decryptString() [1/2]

virtual std::string tenduke::crypto::Ciphers::decryptString ( const ::tenduke::crypto::Cipher & cipher,
const ::tenduke::utl::DataSpan & ciphertext ) const
pure virtual

Decrypts given data using the given cipher to a string.

This method expects the input to consist of magic (4 bytes) + version (2 bytes) + encrypted content (which is specific to the cipher), i.e., the output produced by calling ::encrypt(cipher, plaintext, ciphertext).

Parameters
cipherThe initialized cipher used to decrypt the data. Must match with the cipher used to encrypt
ciphertextthe cipher text (the data to decrypt), the maximum supported length is INT_MAX.
Returns
plain text (decrypted data) as std::string. Good for decrypting a string but also works for binary data

Implemented in tenduke::crypto::AbstractCiphers.

◆ decryptString() [2/2]

virtual std::string tenduke::crypto::Ciphers::decryptString ( const ::tenduke::utl::DataSpan & ciphertext,
const ::tenduke::utl::DataSpan & encryptionKey ) const
pure virtual

Decrypts given data using the system default cipher (AES256 GCM) to a string.

This method expects the input to consist of magic (4 bytes) + version (2 bytes) + IV (12 bytes) + ciphertext + tag (16 bytes), i.e., the output produced by calling ::encrypt(key, plaintext).

This is "syntactic sugar": The method also performs key-derivation for the provided key to simplify the use.

Parameters
ciphertextthe cipher text (the data to decrypt), the maximum supported length is INT_MAX.
encryptionKeyencryption key
Returns
plain text (decrypted data) as std::string. Good for decrypting a string but also works for binary data

Implemented in tenduke::crypto::AbstractCiphers.

◆ encrypt() [1/3]

virtual void tenduke::crypto::Ciphers::encrypt ( const ::tenduke::crypto::Cipher & cipher,
const ::tenduke::utl::DataSpan & plaintext,
::tenduke::utl::DataSink & ciphertext ) const
pure virtual

Encrypts data with the given cipher.

The output consists of:

  • magic (4 bytes)
  • version (2 bytes)
  • then encrypted content, which depends on the cipher. Typically, it would be nonce (IV) + ciphertext + message authentication code (tag).

Implemented in tenduke::crypto::AbstractCiphers.

◆ encrypt() [2/3]

virtual std::unique_ptr<::tenduke::utl::BinaryData > tenduke::crypto::Ciphers::encrypt ( const ::tenduke::utl::DataSpan & plaintext,
const ::tenduke::utl::DataSpan & encryptionKey ) const
pure virtual

Encrypts given data using the system default cipher (AES256 GCM).

The output consists of magic (4 bytes) + version (2 bytes) + IV (12 bytes) + ciphertext + tag (16 bytes).

This is "syntactic sugar": The method also performs key-derivation for the provided key to simplify the use. The method also generates a random IV.

Parameters
plaintextthe plain text (the data to encrypt), the maximum supported length is INT_MAX.
encryptionKeyencryption key
Returns
cipher text (encrypted data)

Implemented in tenduke::crypto::AbstractCiphers.

◆ encrypt() [3/3]

virtual std::unique_ptr<::tenduke::utl::BinaryData > tenduke::crypto::Ciphers::encrypt ( const std::string & plaintext,
const ::tenduke::utl::DataSpan & encryptionKey ) const
pure virtual

Encrypts given data using the system default cipher (AES256 GCM).

The output consists of magic (4 bytes) + version (2 bytes) + IV (12 bytes) + ciphertext + tag (16 bytes).

This is "syntactic sugar": The method also performs key-derivation for the provided key to simplify the use. The method also generates a random IV.

Parameters
plaintextthe plain text, the maximum supported length is INT_MAX.
encryptionKeyencryption key
Returns
cipher text (encrypted data)

Implemented in tenduke::crypto::AbstractCiphers.


The documentation for this class was generated from the following file: