diff --git a/libraries/Crypto/AuthenticatedCipher.cpp b/libraries/Crypto/AuthenticatedCipher.cpp new file mode 100644 index 00000000..62566ad3 --- /dev/null +++ b/libraries/Crypto/AuthenticatedCipher.cpp @@ -0,0 +1,129 @@ +/* + * Copyright (C) 2015 Southern Storm Software, Pty Ltd. + * + * Permission is hereby granted, free of charge, to any person obtaining a + * copy of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation + * the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom the + * Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included + * in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + * DEALINGS IN THE SOFTWARE. + */ + +#include "AuthenticatedCipher.h" + +/** + * \class AuthenticatedCipher AuthenticatedCipher.h + * \brief Abstract base class for authenticated ciphers. + * + * This class abstracts the details of algorithms that provide Authenticated + * Encryption with Associated Data (AEAD). Such algorithms combine + * encryption with message authentication to provide a single primitive. + * + * Authenticated ciphers have four parameters: the secret key, an + * initialization vector (called a "nonce" in the literature), the + * plaintext, and some associated data which is to be authenticated + * with the plaintext but not encrypted. Associated data might be + * sequence numbers, IP addresses, protocol versions, or other information + * that is not secret but is important and unique to the session. + * + * Subclasses encrypt the plaintext content and output the ciphertext. + * Once all plaintext has been processed, the caller should invoke + * computeTag() to obtain the authentication tag to transmit with + * the ciphertext. When the ciphertext is later decrypted, the checkTag() + * function can be used to check that the data is authentic. + * + * Reference: RFC 5116 + * + * \sa Cipher + */ + +/** + * \brief Constructs a new authenticated cipher. + */ +AuthenticatedCipher::AuthenticatedCipher() +{ +} + +/** + * \brief Destroys this authenticated cipher. + */ +AuthenticatedCipher::~AuthenticatedCipher() +{ +} + +/** + * \fn size_t AuthenticatedCipher::tagSize() const + * \brief Returns the size of the authentication tag. + * + * \return The size of the authentication tag in bytes. + * + * By default this function should return the largest tag size supported + * by the authenticated cipher. + * + * \sa computeTag() + */ + +/** + * \fn void AuthenticatedCipher::addAuthData(const void *data, size_t len) + * \brief Adds extra data that will be authenticated but not encrypted. + * + * \param data The 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 + * \a 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. + */ + +/** + * \fn void AuthenticatedCipher::AuthenticatedCipher::computeTag(void *tag, size_t len) + * \brief Finalizes the encryption process and computes the authentication tag. + * + * \param tag Points to the buffer to write the tag to. + * \param len The length of the tag, which may be less than tagSize() to + * truncate the tag to the first \a len bytes. + * + * \sa checkTag() + */ + +/** + * \fn bool AuthenticatedCipher::AuthenticatedCipher::checkTag(const void *tag, size_t len) + * \brief Finalizes the decryption process and checks the authentication tag. + * + * \param tag The tag value from the incoming ciphertext to be checked. + * \param len The length of the tag value in bytes, which may be less + * than tagSize(). + * + * \return Returns true if the \a tag is identical to the first \a 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. + * + * \sa computeTag() + */ diff --git a/libraries/Crypto/AuthenticatedCipher.h b/libraries/Crypto/AuthenticatedCipher.h new file mode 100644 index 00000000..de419d09 --- /dev/null +++ b/libraries/Crypto/AuthenticatedCipher.h @@ -0,0 +1,42 @@ +/* + * Copyright (C) 2015 Southern Storm Software, Pty Ltd. + * + * Permission is hereby granted, free of charge, to any person obtaining a + * copy of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation + * the rights to use, copy, modify, merge, publish, distribute, sublicense, + * and/or sell copies of the Software, and to permit persons to whom the + * Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included + * in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + * DEALINGS IN THE SOFTWARE. + */ + +#ifndef CRYPTO_AUTHENTICATEDCIPHER_h +#define CRYPTO_AUTHENTICATEDCIPHER_h + +#include "Cipher.h" + +class AuthenticatedCipher : public Cipher +{ +public: + AuthenticatedCipher(); + virtual ~AuthenticatedCipher(); + + virtual size_t tagSize() const = 0; + + virtual void addAuthData(const void *data, size_t len) = 0; + + virtual void computeTag(void *tag, size_t len) = 0; + virtual bool checkTag(const void *tag, size_t len) = 0; +}; + +#endif