Arduino Cryptography Library
Public Member Functions | List of all members
Cipher Class Referenceabstract

Abstract base class for stream ciphers. More...

#include <Cipher.h>

Inheritance diagram for Cipher:
AuthenticatedCipher CBCCommon CFBCommon CTRCommon ChaCha OFBCommon Acorn128 Ascon128 ChaChaPoly EAXCommon GCMCommon CBC< T > CFB< T > CTR< T > OFB< T >

Public Member Functions

 Cipher ()
 Constructs a new cipher object.
 
virtual ~Cipher ()
 Destroys this cipher object. More...
 
virtual size_t keySize () const =0
 Default size of the key for this cipher, in bytes. More...
 
virtual size_t ivSize () const =0
 Size of the initialization vector for this cipher, in bytes. More...
 
virtual bool setKey (const uint8_t *key, size_t len)=0
 Sets the key to use for future encryption and decryption operations. More...
 
virtual bool setIV (const uint8_t *iv, size_t len)=0
 Sets the initialization vector to use for future encryption and decryption operations. More...
 
virtual void encrypt (uint8_t *output, const uint8_t *input, size_t len)=0
 Encrypts an input buffer and writes the ciphertext to an output buffer. More...
 
virtual void decrypt (uint8_t *output, const uint8_t *input, size_t len)=0
 Decrypts an input buffer and writes the plaintext to an output buffer. More...
 
virtual void clear ()=0
 Clears all security-sensitive state from this cipher. More...
 

Detailed Description

Abstract base class for stream ciphers.

This class is intended for implementing ciphers that operate on arbitrary amounts of data. In particular, stream ciphers where the number of bytes that are input to encrypt() or decrypt() is exactly the same as the number of bytes that are output.

All of the stream ciphers such as ChaCha inherit directly from this class, together with block cipher modes such as CTR and CFB.

Definition at line 29 of file Cipher.h.

Constructor & Destructor Documentation

◆ ~Cipher()

Cipher::~Cipher ( )
virtual

Destroys this cipher object.

Subclasses are responsible for clearing temporary key schedules and other buffers so as to avoid leaking sensitive information.

See also
clear()

Definition at line 53 of file Cipher.cpp.

Member Function Documentation

◆ clear()

void Cipher::clear ( )
pure virtual

Clears all security-sensitive state from this cipher.

Security-sensitive information includes key schedules, initialization vectors, and any temporary state that is used by encrypt() or decrypt() which is stored in the cipher itself.

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.

◆ decrypt()

void Cipher::decrypt ( uint8_t *  output,
const uint8_t *  input,
size_t  len 
)
pure virtual

Decrypts an input buffer and writes the plaintext to an output buffer.

Parameters
outputThe output buffer to write to, which may be the same buffer as input. The output buffer must have at least as many bytes as the input buffer.
inputThe input buffer to read from.
lenThe number of bytes to decrypt.

The decrypt() function can be called multiple times with different regions of the ciphertext data.

See also
encrypt()

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.

◆ encrypt()

void Cipher::encrypt ( uint8_t *  output,
const uint8_t *  input,
size_t  len 
)
pure virtual

Encrypts an input buffer and writes the ciphertext to an output buffer.

Parameters
outputThe output buffer to write to, which may be the same buffer as input. The output buffer must have at least as many bytes as the input buffer.
inputThe input buffer to read from.
lenThe number of bytes to encrypt.

The encrypt() function can be called multiple times with different regions of the plaintext data.

See also
decrypt()

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.

◆ ivSize()

size_t Cipher::ivSize ( ) const
pure virtual

Size of the initialization vector for this cipher, in bytes.

If the cipher does not need an initialization vector, this function will return zero.

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.

◆ keySize()

size_t Cipher::keySize ( ) const
pure virtual

Default size of the key for this cipher, in bytes.

If the cipher supports variable-sized keys, keySize() indicates the default or recommended key size. The cipher may support other key sizes.

See also
setKey(), ivSize()

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.

◆ setIV()

bool Cipher::setIV ( const uint8_t *  iv,
size_t  len 
)
pure virtual

Sets the initialization vector to use for future encryption and decryption operations.

Parameters
ivThe initialization vector to use.
lenThe length of the initialization vector in bytes.
Returns
Returns false if the length is not supported.

Initialization vectors should be set before the first call to encrypt() or decrypt() after a setKey() call. If the initialization vector is changed after encryption or decryption begins, then the behaviour is undefined.

Note
The IV is not encoded into the output stream by encrypt(). The caller is responsible for communicating the IV to the other party.
See also
ivSize()

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.

◆ setKey()

bool Cipher::setKey ( const uint8_t *  key,
size_t  len 
)
pure virtual

Sets the key to use for future encryption and decryption operations.

Parameters
keyThe key to use.
lenThe length of the key in bytes.
Returns
Returns false if the key length is not supported, or the key is somehow "weak" and unusable by this cipher.

Use clear() or the destructor to remove the key and any other sensitive data from the object once encryption or decryption is complete.

Calling setKey() resets the cipher. Any temporary data that was being retained for encrypting partial blocks will be abandoned.

See also
keySize(), clear()

Implemented in Ascon128, Acorn128, OFBCommon, CFBCommon, CBCCommon, GCMCommon, EAXCommon, CTRCommon, ChaChaPoly, and ChaCha.


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