Poco::Crypto

class CipherKey

Library: Crypto
Package: Cipher
Header: Poco/Crypto/CipherKey.h

Description

CipherKey stores the key information for decryption/encryption of data. To create a random key, using the following code:

CipherKey key("aes-256");

Note that you won't be able to decrypt data encrypted with a random key once the Cipher is destroyed unless you persist the generated key and IV. An example usage for random keys is to encrypt data saved in a temporary file.

To create a key using a human-readable password string, use the following code. We create a AES Cipher and use a salt value to make the key more robust:

std::string password = "secret";
std::string salt("asdff8723lasdf(**923412");
CipherKey key("aes-256", password, salt);

You may also control the digest and the number of iterations used to generate the key by specifying the specific values. Here we create a key with the same data as before, except that we use 100 iterations instead of DEFAULT_ITERATION_COUNT, and sha1 instead of the default md5:

std::string password = "secret";
std::string salt("asdff8723lasdf(**923412");
std::string digest ("sha1");
CipherKey key("aes-256", password, salt, 100, digest);

Member Summary

Member Functions: blockSize, getIV, getKey, impl, ivSize, keySize, mode, name, operator =, setIV, setKey

Types Aliases

ByteVec

using ByteVec = CipherKeyImpl::ByteVec;

Mode

using Mode = CipherKeyImpl::Mode;

Enumerations

Anonymous

DEFAULT_ITERATION_COUNT = 2000

Default iteration count to use with generateKey(). RSA security recommends an iteration count of at least 1000.

Constructors

CipherKey

CipherKey(
    const std::string & name
);

Creates a new CipherKeyImpl object. Autoinitializes key and initialization vector.

CipherKey

CipherKey(
    const CipherKey & other
);

Copy constructor.

CipherKey

CipherKey(
    CipherKey && other
) noexcept;

Copy constructor.

CipherKey

CipherKey(
    const std::string & name,
    const ByteVec & key,
    const ByteVec & iv
);

Creates a new CipherKeyImpl object using the given cipher name, key and initialization vector (IV).

The size of the IV must match the cipher's expected IV size (see ivSize()), except for GCM mode, which allows a custom IV size.

CipherKey

CipherKey(
    const std::string & name,
    const std::string & passphrase,
    const std::string & salt = "",
    int iterationCount = DEFAULT_ITERATION_COUNT,
    const std::string & digest = "md5"
);

Creates a new CipherKeyImpl object using the given cipher name, passphrase, salt value, iteration count and digest.

Destructor

~CipherKey

~CipherKey();

Destroys the CipherKeyImpl.

Member Functions

blockSize inline

int blockSize() const;

Returns the block size of the Cipher.

getIV inline

const ByteVec & getIV() const;

Returns the initialization vector (IV) for the Cipher.

getKey inline

const ByteVec & getKey() const;

Returns the key for the Cipher.

impl inline

CipherKeyImpl::Ptr impl();

Returns the impl object

ivSize inline

int ivSize() const;

Returns the IV size of the Cipher.

keySize inline

int keySize() const;

Returns the key size of the Cipher.

mode inline

Mode mode() const;

Returns the Cipher's mode of operation.

name inline

const std::string & name() const;

Returns the name of the Cipher.

operator =

CipherKey & operator = (
    const CipherKey & other
);

Assignment.

operator =

CipherKey & operator = (
    CipherKey && other
) noexcept;

Move assignment.

setIV inline

void setIV(
    const ByteVec & iv
);

Sets the initialization vector (IV) for the Cipher.

The size of the vector must match the cipher's expected IV size (see ivSize()), except for GCM mode, which allows a custom IV size.

setKey inline

void setKey(
    const ByteVec & key
);

Sets the key for the Cipher.