API for authenticated ciphers

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 <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: <a href="http://tools.ietf.org/html/rfc5116">RFC 5116</a>
+ *
+ * \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
+ * <i>must</i> 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()
+ */

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