Arduino Cryptography Library
Public Member Functions | Protected Member Functions | List of all members
GCMCommon Class Reference

Concrete base class to assist with implementing GCM for 128-bit block ciphers. More...

#include <GCM.h>

Inheritance diagram for GCMCommon:
AuthenticatedCipher Cipher GCM< T >

Public Member Functions

virtual ~GCMCommon ()
 Destroys this cipher object after clearing sensitive information.
 
size_t keySize () const
 Default size of the key for this cipher, in bytes. More...
 
size_t ivSize () const
 Size of the initialization vector for this cipher, in bytes. More...
 
size_t tagSize () const
 Returns the size of the authentication tag. More...
 
bool setKey (const uint8_t *key, size_t len)
 Sets the key to use for future encryption and decryption operations. More...
 
bool setIV (const uint8_t *iv, size_t len)
 Sets the initialization vector to use for future encryption and decryption operations. More...
 
void encrypt (uint8_t *output, const uint8_t *input, size_t len)
 Encrypts an input buffer and writes the ciphertext to an output buffer. More...
 
void decrypt (uint8_t *output, const uint8_t *input, size_t len)
 Decrypts an input buffer and writes the plaintext to an output buffer. More...
 
void addAuthData (const void *data, size_t len)
 Adds extra data that will be authenticated but not encrypted. More...
 
void computeTag (void *tag, size_t len)
 Finalizes the encryption process and computes the authentication tag. More...
 
bool checkTag (const void *tag, size_t len)
 Finalizes the decryption process and checks the authentication tag. More...
 
void clear ()
 Clears all security-sensitive state from this cipher. More...
 
- Public Member Functions inherited from AuthenticatedCipher
 AuthenticatedCipher ()
 Constructs a new authenticated cipher.
 
virtual ~AuthenticatedCipher ()
 Destroys this authenticated cipher.
 
- Public Member Functions inherited from Cipher
 Cipher ()
 Constructs a new cipher object.
 
virtual ~Cipher ()
 Destroys this cipher object. More...
 

Protected Member Functions

 GCMCommon ()
 Constructs a new cipher in GCM mode. More...
 
void setBlockCipher (BlockCipher *cipher)
 Sets the block cipher to use for this GCM object. More...
 

Detailed Description

Concrete base class to assist with implementing GCM for 128-bit block ciphers.

References: NIST SP 800-38D, http://en.wikipedia.org/wiki/Galois/Counter_Mode

See also
GCM

Definition at line 30 of file GCM.h.

Constructor & Destructor Documentation

◆ GCMCommon()

GCMCommon::GCMCommon ( )
protected

Constructs a new cipher in GCM mode.

This constructor must be followed by a call to setBlockCipher().

Definition at line 44 of file GCM.cpp.

Member Function Documentation

◆ addAuthData()

void GCMCommon::addAuthData ( const void *  data,
size_t  len 
)
virtual

Adds extra data that will be authenticated but not encrypted.

Parameters
dataThe extra data to be authenticated.
lenThe number of bytes of extra data to be authenticated.

This function must be called before the first call to encrypt() or decrypt(). That is, it is assumed that all extra data for authentication is available before the first payload data block and that it will be prepended to the payload for authentication. If the subclass needs to process the extra data after the payload, then it is responsible for saving data away until it is needed during computeTag() or checkTag().

This function can be called multiple times with separate extra data blocks for authentication. All such data will be concatenated into a single block for authentication purposes.

Implements AuthenticatedCipher.

Definition at line 214 of file GCM.cpp.

◆ checkTag()

bool GCMCommon::checkTag ( const void *  tag,
size_t  len 
)
virtual

Finalizes the decryption process and checks the authentication tag.

Parameters
tagThe tag value from the incoming ciphertext to be checked.
lenThe length of the tag value in bytes, which may be less than tagSize().
Returns
Returns true if the tag is identical to the first len bytes of the authentication tag that was calculated during the decryption process. Returns false otherwise.

This function must be called after the final block of ciphertext is passed to decrypt() to determine if the data could be authenticated.

Note
Authenticated cipher modes usually require that if the tag could not be verified, then all of the data that was previously decrypted must be discarded. It is unwise to use the decrypted data for any purpose before it can be verified. Callers are responsible for ensuring that any data returned via previous calls to decrypt() is discarded if checkTag() returns false.
See also
computeTag()

Implements AuthenticatedCipher.

Definition at line 242 of file GCM.cpp.

◆ clear()

void GCMCommon::clear ( )
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.

Implements Cipher.

Definition at line 253 of file GCM.cpp.

◆ computeTag()

void GCMCommon::computeTag ( void *  tag,
size_t  len 
)
virtual

Finalizes the encryption process and computes the authentication tag.

Parameters
tagPoints to the buffer to write the tag to.
lenThe length of the tag, which may be less than tagSize() to truncate the tag to the first len bytes.
See also
checkTag()

Implements AuthenticatedCipher.

Definition at line 222 of file GCM.cpp.

◆ decrypt()

void GCMCommon::decrypt ( uint8_t *  output,
const uint8_t *  input,
size_t  len 
)
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()

Implements Cipher.

Definition at line 179 of file GCM.cpp.

◆ encrypt()

void GCMCommon::encrypt ( uint8_t *  output,
const uint8_t *  input,
size_t  len 
)
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()

Implements Cipher.

Definition at line 142 of file GCM.cpp.

◆ ivSize()

size_t GCMCommon::ivSize ( ) const
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.

Implements Cipher.

Definition at line 66 of file GCM.cpp.

◆ keySize()

size_t GCMCommon::keySize ( ) const
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()

Implements Cipher.

Definition at line 61 of file GCM.cpp.

◆ setBlockCipher()

void GCMCommon::setBlockCipher ( BlockCipher cipher)
inlineprotected

Sets the block cipher to use for this GCM object.

Parameters
cipherThe block cipher to use to implement GCM mode. This object must have a block size of 128 bits (16 bytes).

Definition at line 54 of file GCM.h.

◆ setIV()

bool GCMCommon::setIV ( const uint8_t *  iv,
size_t  len 
)
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()

Implements Cipher.

Definition at line 83 of file GCM.cpp.

◆ setKey()

bool GCMCommon::setKey ( const uint8_t *  key,
size_t  len 
)
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()

Implements Cipher.

Definition at line 77 of file GCM.cpp.

◆ tagSize()

size_t GCMCommon::tagSize ( ) const
virtual

Returns the size of the authentication tag.

Returns
The size of the authentication tag in bytes.

By default this function should return the largest tag size supported by the authenticated cipher.

See also
computeTag()

Implements AuthenticatedCipher.

Definition at line 72 of file GCM.cpp.


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